doc/README.packaging

   1 ----------------------------------------------------------------------
   2                    Notes for Freeciv packagers
   3 ----------------------------------------------------------------------
   4
   5 This file is meant to help those people wanting to package Freeciv
   6 for their distribution, and, to some degree, those people who want to
   7 create Freeciv fork.
   8
   9 ----------------------------------------------------------------------
  10 Updating from 3.0 to 3.1
  11 ------------------------
  12 * Client uses ~/.freeciv/freeciv-client-rc-3.1 for storing its options.
  13   Options are always saved to that file.
  14   Loading of options first tries to get options from
  15   ~/.freeciv/freeciv-client-rc-3.1. If that file does not exist it tries to
  16   load options from old client files generated by former version of Freeciv
  17   (e.g. ~/.freeciv/freeciv-client-rc-3.0 generated by Freeciv 3.0,
  18    ~/.freeciv-client-rc-2.6 generated by Freeciv 2.6,
  19    or ~/.civclientrc generated by Freeciv version <= 2.1).
  20 * Gtk2-client has been dropped completely
  21 * Sdl1.2 Mixer support has been dropped
  22 * Minimum automake version is now 1.11.3
  23 * Libsqlite3 is now hard requirement
  24 * Sqlite3 based player authentication support is enabled by default
  25
  26 ----------------------------------------------------------------------
  27 Compatibility of modified versions
  28 ----------------------------------
  29 If you create patched version of Freeciv, take necessary precautions
  30 to avoid problems when your patched version interacts with unpatched
  31 version, or tries to load or save incompatible data files.
  32
  33 Concept called "capabilities" is widely used in Freeciv. If two things
  34 (server/client, program/datafile...) are incompatible, they have
  35 different capabilities defined. Based on that they can detect
  36 incompatibility and act gracely.
  37 Be sure to update network capability string in fc_version if you break
  38 network compatibility, so your patched server/client does not cause
  39 problems to official Freeciv servers/clients trying to connect it.
  40
  41 If you distribute modified version of freeciv, even (or especially)
  42 one network compatible with upstream, you should change also
  43 FREECIV_DISTRIBUTOR in fc_version to match. This information is sent
  44 by client to (public) server so in case there's any problems with certain
  45 clients, we know a bit more what kind of code they are using.
  46
  47 ----------------------------------------------------------------------
  48 Project definition file
  49 -----------------------
  50 Project definition file contains information about the project
  51 infrastructure, needed at freeciv build time. The default project
  52 file of the freeciv project itself is bootstrap/freeciv.project.
  53 Comments on that default file document the contents of such a
  54 project definition file. Once you have made definition file for a
  55 freeciv fork project, you can build freeciv using it by giving
  56 configure option --with-project-definition=<file.project>
  57
  58 ----------------------------------------------------------------------
  59 Configure time version number adjustment
  60 ----------------------------------------
  61
  62 The version label part of the version number can be set via
  63 configure time environment variable FREECIV_LABEL_FORCE.
  64 If the variable contains tag "<base>", that gets replaced with the
  65 label that would be used if FREECIV_LABEL_FORCE was not set at all.
  66
  67 ----------------------------------------------------------------------
  68 Announcement of new versions
  69 ----------------------------
  70 As of 2.4, the Freeciv client displays the latest available version if
  71 it's newer than the running version. This information comes from the
  72 metaserver.
  73
  74 The metaserver maintains several different versions to report here,
  75 distinguished by "follow tags". The default follow tag is "stable",
  76 updated when a new source release is made, but for instance Windows
  77 builds will follow a different tag such as "win32", which will only be
  78 updated when a new Windows binary is available.
  79
  80 This mechanism is primary intended for the Freeciv maintainers, since
  81 updates to the metaserver need to be made be us. However, if you
  82 maintain a significant version/package of Freeciv, you can contact us
  83 and ask to be allocated a tag to pass to 'configure --with-followtag';
  84 thereafter you'd need to let us know whenever you make a new release
  85 so we can update the metaserver.
  86
  87 (This is unlikely to be of use to Linux distribution packagers, who
  88 have their own means of distributing updates.)
  89
  90 ----------------------------------------------------------------------
  91 Optional features
  92 -----------------
  93 Configure enables many optional features by default when their
  94 dependencies are satisfied in the system. Downside of this automation
  95 is that missing dependencies cause no hard error even when you would
  96 want the features. For getting list of features automatically left out
  97 because of missing dependencies you can give option --with-missinglist
  98 to configure, and last thing configure outputs will be that list.
  99
 100 ----------------------------------------------------------------------
 101 Shared libfreeciv
 102 -----------------
 103 Libfreeciv contains code common to server and client. By default it's
 104 built as static library, but you can build it as shared library by
 105 giving configure option "--enable-shared" (and possibly "--disable-static")
 106
 107 ----------------------------------------------------------------------
 108 Generated files
 109 ---------------
 110 This is list of files Freeciv might generate to filesystem when running.
 111 You may want to remove some of these when Freeciv is uninstalled.
 112
 113 * Client saves its options to file "~/.freeciv/freeciv-client-rc-3.1"
 114 * Server saves its readline history to file "~/.freeciv/freeciv-server_history"
 115 * When running local single player games, challenge files with name
 116   like "~/.freeciv/challenge_*_*" are generated
 117 * When saving game in server launched by client, savegame go to
 118   "~/.freeciv/saves/"
 119 * When saving game in independently launched server, savegames go
 120   to directory specified with "-s" command line option, defaulting
 121   to working directory
 122 * freeciv-modpack saves data under "~/.freeciv/3.1/" and
 123   "~/.freeciv/scenarios/"
 124 * Server can write log to file specified with "-l" command line option
 125 * When mapimage feature is used, it can save colortest images to
 126   working directory and actual map images to save directory (same as above)
 127
 128 ----------------------------------------------------------------------
 129 Building multiple clients at once
 130 ---------------------------------
 131 Starting from 2.2 it has been possible to build multiple clients running
 132 'make' just once. Just give configure option "--enable-client" comma
 133 separated list of clients to compile, e.g. "--enable-client=gtk3,gtk3x,sdl2,qt"
 134
 135 ----------------------------------------------------------------------
 136 Savegame compression support
 137 ----------------------------
 138 Freeciv can use several different compression libraries for compressing
 139 its savegames. See server setting "compresstype".
 140 * zlib (gzip compression) is required to compile freeciv so zlib
 141   compression support is always present
 142 * bzip2 compression is built into Freeciv if bzip2 libraries and
 143   headers are present at configure time. One can override this automatic
 144   detection with configure option --with[out]-libbz2.
 145 * xz compression is built into Freeciv if liblzma library and
 146   headers are present at configure time. One can override this automatic
 147   detection with configure option --with[out]-liblzma.
 148
 149 While this feature is called "Savegame compression support" it actually
 150 applies to loading of all the section files: savegames, rulesets, tileset
 151 spec files... If compression support is built into Freeciv, you can
 152 compress any of these files and Freeciv can still load them. Freeciv ships
 153 with all the data files uncompressed, except scenarios which are gzipped.
 154
 155 ----------------------------------------------------------------------
 156 Loadable AI modules
 157 -------------------
 158 Freeciv can be built with support of loading AI code from custom module.
 159 There can be multiple modules loaded at once, and AI players can use
 160 different module from each other.
 161 This feature is not enabled by default. When it's not enabled, default
 162 AI code is built in to server and always used.
 163 You can enable this feature with '--enable-aimodules'. For this to work
 164 you have to enable also building of shared libraries (and modules) with
 165 '--enable-shared' as discussed in chapter 'Shared libfreeciv'
 166 All modules, both default and custom, must be installed under
 167 ${libdir}/fcai (/usr/lib/fcai for example) for their loading to work.
 168
 169 ----------------------------------------------------------------------
 170 Public servers
 171 --------------
 172 Sadly we have not resources to keep public servers for many different
 173 Freeciv versions running. To give your users ability to play on public
 174 servers, try to provide them as current Freeciv client version as possible.
 175 To see list of currently running public servers, see
 176 "http://meta.freeciv.org/metaserver.php" Note that from the web you
 177 can see complete list, while list shown by Freeciv client only lists
 178 compatible servers.
 179
 180 Any a.b.c release is network compatible with any a.b.d release. If you
 181 provide 3.1.c client, it can be used to play on 3.1.d server.