=====================
Installing Freeciv21:
=====================

A better maintained HTML version of this file is available at https://longturn.readthedocs.io/en/latest/Getting/compile.html.

This document contains sections and subsections as follows:
     0. Prerequisites
     1. Prerequisites for the client and tools
     2. Compiling and Installing Freeciv21
     3. Debian Notes
     4. Windows Notes


0. Prerequisites:
=================

Freeciv21 has a number of prerequisites.  Note, that apart from the first prerequisite, the Freeciv21
configuration process is smart enough to work out whether your system is suitable.  If in doubt, just try it.

 - An operating system that support Qt.

Any modern operating system that support Qt is required. As of this writing this is Linux, Windows and Mac
OS X. On Windows Msys2 is supported.

 - A C and C++ compiler.

Freeciv21 is written in very portable C and C++.  Both 32- and 64-bit machines are supported.  You cannot
use a "K&R C" compiler, or a C++ compiler. The C++ compiler must support C++ 17.

Development of Freeciv21 is primarily done with "gcc", the GNU project's excellent C and C++ compiler.
Microsoft Windows MS Visual C support is under development.

 - A "cmake" program.

   Freeciv21 developers generally use "cmake", the Kitware make program.

   You can check if you have GNU make installed on your system by typing:

       % cmake --version

   The output should include "Kitware cmake" somewhere and the version should be >=3.12.

 - Ninja cmake build program

 - libtool version 2.2 or better

 - libsqlite3

   http://www.sqlite.org/

 - The programs from GNU gettext version 0.15 or better

   Especially the xgettext program is required to create the *.gmo files which aren't included in the git tree.

 - Lua version 5.3 or higher

   Exact 5.3 is preferred.

 - KF 5 Archive Library

   KArchive provides classes for easy reading, creation and manipulation of "archive" formats like ZIP and TAR.

 - SDL2_Mixer

   SDL_mixer is a sample multi-channel audio mixer library.

 - Python 3


1. Prerequisites for the client and tools:
==========================================

The Freeciv21 project maintains a single Qt client.

 - C++ compiler.

Qt-client is written in C++, so you need appropriate compiler. In Freeciv21 development, g++ has been used.

 - Qt5Core, Qt5Gui, QtSvg, and Qt5Widgets libraries and headers. At least version 5.15 is required.


2. Compiling and Installing Freeciv21:
======================================

Compiling Freeciv21 requires the use of the cmake program. To build with defaults enter the following commmand from the freeciv21
directory:

   cmake . -B build -G Ninja

To customize the compile, cmake requires the use of command line parameters.  cmake calls them directives
and they start with -D. The defaults are marked with * (e.g. *ON*).

  -DFREECIV_ENABLE_TOOLS={*ON*/OFF}     -- Enables all the tools with one parameter (Ruledit, FCMP, Ruleup,
                                           and Manual)
  -DFREECIV_ENABLE_SERVER={*ON*/OFF}    -- Enables the server. Should typically set to ON to be able to play
                                           AI games
  -DFREECIV_ENABLE_NLS={*ON*/OFF}       -- Enables Native Language Support
  -DFREECIV_ENABLE_CIVMANUAL={*ON*/OFF} -- Enables the Freeciv Manual application
  -DFREECIV_ENABLE_CLIENT={*ON*/OFF}    -- Enables the Qt client. Should typically set to ON unless you only
                                           want the server
  -DFREECIV_ENABLE_FCMP_CLI={ON/OFF}    -- Enables the command line version of the Freeciv21 Modpack Installer
  -DFREECIV_ENABLE_FCMP_QT={ON/OFF}     -- Enables the Qt version of the Freeciv21 Modpack Installer (recommended)
  -DFREECIV_ENABLE_RULEDIT={ON/OFF}     -- Enables the Ruleset Editor
  -DFREECIV_ENABLE_RULEUP={ON/OFF}      -- Enables the Ruleset upgrade tool
  -DCMAKE_BUILD_TYPE={*Release*/Debug}  -- Changes the Build Type. Most people will pick Release
  -DCMAKE_INSTALL_PREFIX=/some/path     -- Allows an alternative install path. Default is /usr/local/freeciv21

For more information on other cmake directives see https://cmake.org/cmake/help/latest/manual/cmake-variables.7.html.

Once the command line directives are determined, the appropriate command looks like this:

   cmake . -B build -G Ninja \
     -DFREECIV_ENABLE_TOOLS=OFF \
     -DFREECIV_ENABLE_SERVER=ON \
     -DCMAKE_BUILD_TYPE=Release \
     -DFREECIV_ENABLE_NLS=OFF \
     -DCMAKE_INSTALL_PREFIX=$HOME/Install/Freeciv21

Once the build files have been written, then compile with this command:

   cmake --build build

Once the compilation is complete, install the game with this command.

   cmake --build build --target install

   NOTE: If you did not change the default install prefix, you will need to elevate privileges with sudo.

After compilation, the important results are:

  - The build/freeciv21-client client application binary.
  - The build/freeciv21-server game server binary.


3. Debian Linux Notes:
======================

Below are all the command line steps needed to start with a fresh install of Debian or its variants (e.g.
Ubuntu, Linux Mint) to install Freeciv21.

Start with ensuring your have a source repository (deb-src) turned on in apt sources and then run the
following commands.

   sudo apt update

   sudo apt install git \
     cmake \
     ninja-build \
     python3 \
     qtbase5-dev \
     libqt5svg5-dev \
     libkf5archive-dev \
     liblua5.3-dev \
     libsqlite3-dev \
     libsdl2-mixer-dev \
     libunwind-dev \
     libdw-dev

   mkdir -p $HOME/GitHub

   cd $HOME/GitHub

   git clone https://github.com/longturn/freeciv21.git

   cd freeciv21

At this point follow the steps in section 2 above.


4. Windows notes:
=================

Msys2 is an available environment for compiling Freeciv21. Microsoft Windows Visual C is under development.

Freeciv21 currently supports building and installing using the Msys2 environment. Build instructions for
Msys2 versions are documented at https://longturn.readthedocs.io/en/latest/Contributing/msys2.html.
Alternately you can visit https://github.com/jwrober/freeciv-msys2 for ready made scripts.

Follow the steps starting in configuring above.

Instead of installing, use this command to create the Windows Installer package:

  cmake --build build --target package

When the Ninja command is finished running, you will find an installer in build/Windows-${arch}

** END **
