----------------------------------------------------------------------
                   Notes for Freeciv packagers
----------------------------------------------------------------------

This file is meant to help those people wanting to package Freeciv
for their distribution, and, to some degree, those people who want to
create Freeciv fork.

----------------------------------------------------------------------
Updating from 2.5 to 2.6
------------------------
* Client uses ~/.freeciv/freeciv-client-rc-2.6 for storing its options.
  Options are always saved to that file.
  Loading of options first tries to get options from
  ~/.freeciv/freeciv-client-rc-2.6. If that file does not exist it tries to
  load options from old client files generated by former version of Freeciv
  (e.g. ~/.freeciv-client-rc-2.5 generated by Freeciv 2.5 or ~/.civclientrc
   generated by Freeciv version <= 2.1).
* gtk3-client is now the default client
* Minimum gtk3 requirement for building gtk3-client is now 3.8.
* Minimum qt requirement for building qt-client and freeciv-ruledit is 5.2.
* There's new gtk3.22-client that has gtk+-3.22 as requirement. It can be
  built with --enable-client=gtk3.22. This client suits better for
  systems with gtk+-3.22 than the gtk3-client compatible with much older
  gtk+ versions.
* There's new experimental sdl2-client. It can be built with
  --enable-client=sdl2
* Development of ruleset editor, freeciv-ruledit, has begun.
  It has same Qt5 dependencies as other Qt programs in Freeciv distribution.
  It is not very usable in 2.6 and should probably not be packaged by
  distributions.
* Lua version to use is 5.3 now.
* System lua library is now used by default. Copy of lua distributed
  with freeciv is used only if system lua is not found, or it's
  explicitly requested with configure option --disable-sys-lua
* There's new configure option --enable-sys-tolua-cmd to use tolua
  command from the build system when generating lua bindings. Plain
  --enable-sys-tolua-cmd searches tolua from the PATH, other values
  are treated as full path to executable. The default is to search
  for tolua from the system. You have to use system tolua when
  cross-compiling.
* Minimum libtool version is now 1.5.2
* Minimum automake version is now 1.10
* For translation support minimum gettext version is now 0.14. It's
  still possible to build completely without translation support
  with configure option --disable-nls
* SDL2-mixer is now the default. To build clients to still use
  SDL1.2-mixer, configure with --enable-sdl-mixer=sdl1.2. sdl-client
  cannot be built with SDL2-mixer, nor can sdl2-client be built with
  SDL1.2-mixer
* Server now saves its readline history to file
  "~/.freeciv/freeciv-server_history" instead of "~/.freeciv-server_history"
* Configure option --with-freeciv-manual / --without-freeciv-manual has
  been replaced with --enable-freeciv-manual / --disable-freeciv-manual
  that can take also value --enable-freeciv-manual=html to make
  freeciv-manual that produces manuals with alternative formatting,
  default still being wiki formatting.
* Added configure options --with[out]-libbz2 and --with[out]-liblzma to
  explicitly enable or disable support for bz2 or xz compressed files.
  The default is still to autodetect if the support can be built in.
  Note that it's usually a bad idea to disable one of these if you
  have had it previously enabled, as then your new version will be
  unable to load old savegames created with that compression type in
  use.
* Ruleset README files have moved from doc/ into data/ directory
  alongside ruleset data, so that they can be displayed inside the
  game. You may want to symlink to these from /usr/share/doc/ or
  equivalent so that users can continue to easily find the
  documentation outside the game.

----------------------------------------------------------------------
Compatibility of modified versions
----------------------------------
If you create patched version of Freeciv, take necessary precautions
to avoid problems when your patched version interacts with unpatched
version, or tries to load or save incompatible data files.

Concept called "capabilities" is widely used in Freeciv. If two things
(server/client, program/datafile...) are incompatible, they have
different capabilities defined. Based on that they can detect
incompatibility and act gracely.
Be sure to update network capability string in fc_version if you break
network compatibility, so your patched server/client does not cause
problems to official Freeciv servers/clients trying to connect it.

If you distribute modified version of freeciv, even (or especially)
one network compatible with upstream, you should change also
FREECIV_DISTRIBUTOR in fc_version to match. This information is sent
by client to (public) server so in case there's any problems with certain
clients, we know a bit more what kind of code they are using.

----------------------------------------------------------------------
Configure time version number adjustment
----------------------------------------

The version label part of the version number can be set via
configure time environment variable FREECIV_LABEL_FORCE.
If the variable contains tag "<base>", that gets replaced with the
label that would be used if FREECIV_LABEL_FORCE was not set at all.

----------------------------------------------------------------------
Announcement of new versions
----------------------------
As of 2.4, the Freeciv client displays the latest available version if
it's newer than the running version. This information comes from the
metaserver.

The metaserver maintains several different versions to report here,
distinguished by "follow tags". The default follow tag is "stable",
updated when a new source release is made, but for instance Windows
builds will follow a different tag such as "win32", which will only be
updated when a new Windows binary is available.

This mechanism is primary intended for the Freeciv maintainers, since
updates to the metaserver need to be made be us. However, if you
maintain a significant version/package of Freeciv, you can contact us
and ask to be allocated a tag to pass to 'configure --with-followtag';
thereafter you'd need to let us know whenever you make a new release
so we can update the metaserver.

(This is unlikely to be of use to Linux distribution packagers, who
have their own means of distributing updates.)

----------------------------------------------------------------------
Optional features
-----------------
Configure enables many optional features by default when their
dependencies are satisfied in the system. Downside of this automation
is that missing dependencies cause no hard error even when you would
want the features. For getting list of features automatically left out
because of missing dependencies you can give option --with-missinglist
to configure, and last thing configure outputs will be that list.

----------------------------------------------------------------------
Shared libfreeciv
-----------------
Libfreeciv contains code common to server and client. By default it's
built as static library, but you can build it as shared library by
giving configure option "--enable-shared" (and possibly "--disable-static")

----------------------------------------------------------------------
Generated files
---------------
This is list of files Freeciv might generate to filesystem when running.
You may want to remove some of these when Freeciv is uninstalled.

* Client saves its options to file "~/.freeciv/freeciv-client-rc-2.6"
* Server saves its readline history to file "~/.freeciv/freeciv-server_history"
* When running local single player games, challenge files with name
  like "~/.freeciv/challenge_*_*" are generated
* When saving game in server launched by client, savegame go to
  "~/.freeciv/saves/"
* When saving game in independently launched server, savegames go
  to directory specified with "-s" command line option, defaulting
  to working directory
* freeciv-modpack saves data under "~/.freeciv/2.6/" and
  "~/.freeciv/scenarios/"
* Server can write log to file specified with "-l" command line option
* When mapimage feature is used, it can save colortest images to
  working directory and actual map images to save directory (same as above)

----------------------------------------------------------------------
Building multiple clients at once
---------------------------------
Starting from 2.2 it has been possible to build multiple clients running
'make' just once. Just give configure option "--enable-client" comma
separated list of clients to compile, e.g. "--enable-client=gtk3,gtk2,sdl,qt"

----------------------------------------------------------------------
Savegame compression support
----------------------------
Freeciv can use several different compression libraries for compressing
its savegames. See server setting "compresstype".
* zlib (gzip compression) is required to compile freeciv so zlib
  compression support is always present
* bzip2 compression is built into Freeciv if bzip2 libraries and
  headers are present at configure time. One can override this automatic
  detection with configure option --with[out]-libbz2.
* xz compression is built into Freeciv if liblzma library and
  headers are present at configure time. One can override this automatic
  detection with configure option --with[out]-liblzma.

While this feature is called "Savegame compression support" it actually
applies to loading of all the section files: savegames, rulesets, tileset
spec files... If compression support is built into Freeciv, you can
compress any of these files and Freeciv can still load them. Freeciv ships
with all the data files uncompressed, except scenarios which are gzipped.

----------------------------------------------------------------------
Loadable AI modules
-------------------
Freeciv can be built with support of loading AI code from custom module.
There can be multiple modules loaded at once, and AI players can use
different module from each other.
This feature is not enabled by default. When it's not enabled, default
AI code is built in to server and always used.
You can enable this feature with '--enable-aimodules'. For this to work
you have to enable also building of shared libraries (and modules) with
'--enable-shared' as discussed in chapter 'Shared libfreeciv'
All modules, both default and custom, must be installed under
${libdir}/fcai (/usr/lib/fcai for example) for their loading to work.

----------------------------------------------------------------------
Public servers
--------------
Sadly we have not resources to keep public servers for many different
Freeciv versions running. To give your users ability to play on public
servers, try to provide them as current Freeciv client version as possible.
To see list of currently running public servers, see
"http://meta.freeciv.org/metaserver.php" Note that from the web you
can see complete list, while list shown by Freeciv client only lists
compatible servers.

Any a.b.c release is network compatible with any a.b.d release. If you
provide 2.6.c client, it can be used to play on 2.6.d server.
