==============================
Installing Freeciv with Meson:
==============================

This file describes how to compile and install Freeciv with the
Meson build system support. The other supported way to compile and
install Freeciv is using autotools as described in doc/INSTALL.autotools.


Prerequisites:
==============

Freeciv has mostly the same prerequisites no matter if it's built
with autotools or meson and ninja. The only difference is the requirement
of the build system itself. Meson build does not need autotools, nor does
autotools build need meson. See INSTALL.autotools file for the
common prerequisites.

For the meson based build minimum version of meson is 0.63.0.


Meson specific prerequisites for the Qt client:
-----------------------------------------------

 - If the Qt-client is built with svgflags features
   (configured with -Dsvgflags=true), to really enable them
   also at runtime, Qt6Svg libraries and headers are needed.


Prerequisites for the SDL3 client:
----------------------------------

 - The "SDL3" library.

   "Simple DirectMedia Layer is a cross-platform multimedia library designed
    to provide low level access to audio, keyboard, mouse, joystick, 3D hardware
    via OpenGL, and 2D video framebuffer." (https://www.libsdl.org/)

   These features make it a good choice for portable games. You may obtain it
   at:

   https://github.com/libsdl-org/SDL/releases/download/release-3.2.10/SDL3-3.2.10.tar.gz

   To compile the client using the "SDL3" library add "-Dclient=sdl3"
   to the Freeciv meson execution.

 - The "SDL3_image" library.

   This library loads the PNG images (with the help of libpng) and converts
   them to "SDL surfaces" that can be handled by the "SDL" library. You may
   obtain it at:

   https://github.com/libsdl-org/SDL_image/releases/download/release-3.2.4/SDL3_image-3.2.4.tar.gz

 - The "SDL3_ttf" library.

   https://github.com/libsdl-org/SDL_ttf/releases/download/release-3.2.2/SDL3_ttf-3.2.2.tar.gz

 - The "freetype" library.

   This library helps to render text for the SDL3 client, using an externally
   provided TrueType font. You may obtain it at:

   https://download.savannah.gnu.org/releases/freetype/freetype-2.13.3.tar.xz


Overview:
=========

There's two parts in building freeciv. First one needs to configure the
build, and then execute it.

Build directory is configured with the 'meson' command. This is equivalent
of running './configure' in autotools based system. Meson does not allow
configuring the source directory. It always requires separate build directory.
Just create an empty directory, cd in to it, and run meson with path to
source directory as parameter. You can also give configure options in this
phase.

> mkdir build ; cd build
> meson setup ../freeciv-3.1.0

You need to configure the build directory just once. As source files get
updated, you can just execute incremental builds in the build directory.
You can have multiple build directories configured to use the same source
directory, typically set up with different configure options. You can
for example have separate build directories for different kinds of clients.

The build is executed with 'ninja' command. This is equivalent of running
'make' in autotools based system. It's also used to install freeciv

> ninja
> ninja install


Configure options:
==================

Configure options are given as '-D<option>=<value>'.
For example to set freeciv installation prefix as
'/home/cazfi/freeciv-install':

> meson setup ../src -Dprefix=/home/cazfi/freeciv-install

You can give configure options when you first set up the build directory
(like in example above), or you can change configure options for the
build directory later by 'meson configure' subcommand like this:

> meson configure -Dprefix=/home/cazfi/freeciv-install

You get full list of configure options by running 'meson configure'
subcommand without any configure options to set

> meson configure

Some of the configure options are implemented by meson itself for
all meson-based projects. Some options are implemented in freeciv build
system, and they are specific to freeciv.


Notable generic configure options:
----------------------------------

prefix (string):
  The directory where Freeciv will be installed. You can install multiple
  versions of Freeciv in parallel by using different prefix for each.
  It's also a good idea to use prefix to avoid messing your system directories

debug (boolean):
  Whether debug version of Freeciv should be built. While this is generic
  option, some functionality in Freeciv depends on this setting.

werror (boolean):
  Turn compiler warnings to hard errors. This is recommended for
  any development builds of freeciv, to make sure that newly introduced
  warnings get noticed.

default_library ('shared'/'static'/'both')
  In case of freeciv, this affects build of common libfreeciv library.
  The default is to build shared library, and as the binaries then
  need to find the shared library at their run time, setting
  system up for that may require some extra work. If one uses
  this setting to build static library instead, it's going to be
  included in the binaries themselves, so they don't need to find it.


Freeciv specific configure options:
-----------------------------------

clients (array):
  List of clients to build. To disable client build completely, give an
  empty array ('-Dclients=[]'). Currently gtk3.22-, sdl2-, qt-,
  gtk4-, sdl3-, gtk4x-, and stub-client builds are supported.
  By default builds just gtk4-client.

fcmp (array):
  List of freeciv modpack installer UIs to build. To disable their build
  completely, give an empty array ('-Dfcmp=[]'). Currently gtk3, qt, gtk4,
  gtk4x, and cli are supported. By default builds just gtk4 UI.

cacert-path (string):
  Custom path to CA cert bundle. If this is empty, default path will be used.
  This affects mostly downloading custom modpacks with modpack installer from
  an 'https' URL.

followtag (string):
  Custom followtag name. If this is empty, default follow tag is used.
  That's the version tag that the client checks from the metaserver to
  see if there's newer freeciv versions of the kind available.

json-protocol (boolean):
  Build json-protocol support in. Json-protocol is an alternative to the default
  raw-protocol between freeciv server and client.

syslua ('try'/'true'/'false')
  Whether to use lua from the system, or to build lua included in freeciv
  source tree. The default is 'try' to use lua from the system if possible,
  but fallback to using freeciv's included one if not found from system.

sys-tolua-cmd (boolean):
  Whether to use tolua command from the system, or to build one
  included in the freeciv source tree. For native build
  the default is false, i.e., to use freeciv's own tolua.
  When cross-compiling, this setting is ignored, and tolua is
  always used from the build system.

mwand ('try'/'true'/'false')
  Whether to build against MagickWand to have support for additional
  mapimg formats. The default is 'try' to enable the support if possible.

readline ('try'/'true'/'false')
  Whether to enable readline functionality on server.
  The default is 'try' to enable it if suitable readline found.

audio ('none'/'sdl2'/'sdl3'):
  What kind of sound support should be built to the clients. Defaults to sdl2.

tools (array):
  Extra tools to build:
   * ruledit : Ruleset editor
   * manual  : Manual generator
   * ruleup  : Ruleset upgrader
  Default is to build them all.

nls (boolean):
  Build in Native Language Support. Defaults to true.

gitrev (boolean):
  Include git commit id to the version string.

server ('disabled'/'enabled'/'freeciv-web'):
  Whether to build server, or not. Special value 'freeciv-web'
  means that freeciv-web version will be built instead of
  the regular server.

appimage (boolean):
  Make build suitable for AppImage packaging. This affects paths from
  which various resources are looked from, and produces build that
  doesn't work outside AppImage.

gen-packets-args (array):
  Additional packet generator arguments passed to common/generate_packets.py.

qtver ('qt6'/'qt6x'):
  Whether to build Qt6, or experimental Qt6 versions of the binaries.

project-definition (string):
  Filename of the project definition to use. See below for contents of
  such a file

min-win-ver (string):
  Minimum Windows version the build should support. Versions listed on
  https://learn.microsoft.com/en-us/cpp/porting/modifying-winver-and-win32-winnt?view=msvc-170

localeprefix (string):
  If non-empty, will be used instead of default prefix when constructing locale path.
  Default prefix is the regular prefix on most systems,
  but current directory ('.') in Windows.
  Unlike regular prefix, this can also be a relative path.

python (string):
  Python interpreter to use. Defaults to 'python3'

svgflags (boolean)
  Add support for svg flags features on clients where this is supported,
  currently only Qt.

fcdb (array):
  fcdb (player authentication) backends to build.
  Possible backends are sqlite3, mariadb, and odbc.
  The default is sqlite3.


Project definition file
-----------------------
Each line of project definition line must have keyword in the beginning,
separated by a space from the rest of the line containing the value.

There's an example file bootstrap/freeciv.fcproj

Supported keys:
META_URL             - URL of the default metaserver
MODPACK_LIST_URL     - URL of the default modpack list
FREECIV_STORAGE_DIR  - Directory where freeciv stores user files
FREECIV_DEFAULT_PORT - Default port of the server


run.sh
------

One of the build results is script named 'run.sh' in the build directory -
it does not get installed to the installation directory. This script can
be used to run freeciv executables from the build directory.
Give the executable name and parameters as parameters to ./run.sh, e.g.,
./run.sh freeciv-server --help
