Compiling Freeciv21

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 supports Qt 6.6+ is required. As of this writing this is Linux, Microsoft Windows® and Apple macOS®.

Linux Distributions:

  • Arch

  • Debian 13 “Testing” (Trixie)®

  • Fedora 41+

  • Gentoo

  • KDE Neon

  • Manjaro

  • NixOS

  • openSUSE Tumbleweed (Leap is not supported)

  • Slackware

  • Ubuntu 24.10+

Note

The above list of Linux distributions is, of course, not exhaustive. The Freeciv21 Community has simply listed the mainline, well supported, distributions here. The code repository has Continuous Integration enabled and all code commits pass through Ubuntu, macOS and Windows for testing. It is assumed that the user is keeping his/her computer OS up to date. Support by the community for these distributions will be better than for some of the others out there, so keep that in mind if you are not an experienced Linux user.

Note

The following instructions on this page are for Linux and MSYS2 on Windows. You will need to install MSYS2 first before continuing here if using MSYS2 on Windows. However, you can also compile on Windows with Microsoft Visual Studio. The Visual Studio instructions are self contained. No need to return to this page after following the installation instructions. Follow the steps in macOS to setup macOS as a development environment. As with Visual Studio the macOS instructions are self contained.

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. The C++ compiler must support C++ 17.

Development of Freeciv21 is primarily done with gcc, the GNU project’s excellent C and C++ compiler. For complete cross-platform support the Longturn community uses the LLVM project’s clang-cl compiler, which is supported on Linux, Windows and macOS.

The Cmake program

Freeciv21 developers generally use cmake, the Kitware make program. You can check if you have cmake installed on your system by typing the following command. The output should include “Kitware cmake” somewhere and the version should be >=3.21.

$ cmake --version
The Ninja cmake build program

Freeciv21 uses the ninja build tool. You can check if you have ninja installed on your system by typing the following command. The output should include ninja version >=1.10.

$ ninja --version
GNU Libtool

GNU Libtool is a generic library support script that hides the complexity of using shared libraries behind a consistent, portable interface. Freeciv21 requires version 2.2 or better.

https://www.gnu.org/software/libtool/

SQLite

SQLite is a C-language library that implements a small, fast, self-contained, high-reliability, full-featured, SQL database engine. SQLite is the most used database engine in the world. SQLite is built into all mobile phones and most computers and comes bundled inside countless other applications that people use every day. Freeciv21 requires version 3.

https://www.sqlite.org

GNU Gettext

GNU Gettext is used for Internationalization support. Freeciv21 requires version 0.15 or better. The xgettext program is required to create the *.gmo files which are not included in the git tree.

https://www.gnu.org/software/gettext/

Lua

Lua is a powerful, efficient, lightweight, embeddable scripting language. It supports procedural programming, object-oriented programming, functional programming, data-driven programming, and data description. Exact version 5.3 is preferred.

https://www.lua.org/about.html

KDE Frameworks KArchive Library

KDE frameworks KArchive provides classes for easy reading, creation and manipulation of “archive” formats like ZIP and TAR. Any version that is included in the KDE Frameworks v6+.

https://invent.kde.org/frameworks/karchive

SDL2_Mixer

SDL_mixer is a sample multi-channel audio mixer library.

https://www.libsdl.org

Python

Freeciv21 requires version 3 of Python

https://www.python.org

Prerequisites for the Client and Tools

The Freeciv21 project maintains a single Qt based client.

C++ compiler.

The client is written in C++, so you need an appropriate compiler. In Freeciv21 development, g++ has been used as well as tests against LLVM’s compiler (clang++)

QT Libraries

Freeciv21 uses the Qt libraries, specifically Qt6Core, Qt6Gui, Qt6Network, Qt6Multimedia, Qt6Svg, and Qt6Widgets libraries and headers.

At least version 6.6 is required.

Installing Package Dependencies

See the Debian Linux Packages section below on the steps to install the components for Debian Linux and its variants.

See the Fedora Linux Packages section below on the steps to install the components for Fedora Linux

Debian Linux Packages

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 you 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 \
   g++ \
   python3 \
   qt6-base-dev \
   qt6-multimedia-dev \
   qt6-svg-dev \
   libkf6archive-dev \
   liblua5.3-dev \
   libsqlite3-dev \
   libsdl2-mixer-dev \
   libunwind-dev \
   libdw-dev \
   gettext \
   python3-sphinx \
   clang-format-17

At this point, follow the steps in Obtaining the Source Code section below.

Fedora Linux Packages

Below are all the command line steps needed to start with a fresh install of Fedora or its variants (e.g. RHEL, CentOS Stream) to install Freeciv21.

$ sudo dnf install git \
  cmake \
  ninja-build \
  python \
  gettext \
  qt6-qtbase-devel \
  qt6-qtmultimedia-devel \
  qt6-qtsvg-devel \
  kf6-karchive-devel \
  lua-devel \
  sqlite-devel \
  SDL2_mixer-devel \
  readline-devel \
  zlib-devel \
  libunwind-devel \
  elfutils-libs \
  python3-sphinx \
  clang17-tools-extra

Obtaining the Source Code

In order to compile Freeciv21, you need a local copy of the source code. You can download a saved version in an archive file (.tar.gz or .zip) of the code from the project releases page at https://github.com/longturn/freeciv21/releases. Alternately you can get the latest from the master branch with the git program with this command:

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

Configuring

Configuring Freeciv21 for compilation requires the use of the cmake program.

On Debian Linux, to build with defaults enter the following command from the freeciv21 directory. Continue reading in the Other CMake Notes section below for more notes about other command line options you can give cmake.

$ cmake . -B build -G Ninja

Note

If you are compiling on Windows MSYS2, alter the above command to add

-DCMAKE_INSTALL_PREFIX=$PWD/build/install

at the end.

Compiling/Building

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

$ cmake --build build

Installing

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.

Tip

If you want to enable menu integration for the installed copy of Freeciv21, you will want to copy the .desktop files in $CMAKE_INSTALL_PREFIX/share/applications to $HOME/.local/share/applications.

This is only necessary if you change the installation prefix. If you do not and use elevated privileges, then the files get copied to the system default location.

At this point, the compilation and installation process is complete. The following sections document other aspects of the packaging and documentation generation process.

Debian and Windows Package Notes

Operating System native packages can be generated for Debian and Windows based systems.

Debian

Assuming you have obtained the source code and installed the package dependencies in the sections above, follow these steps to generate the Debian package:

$ cmake --build build --target package

When the last command is finished running, you will find a .deb installer in build/Linux-$arch

Microsoft Windows

There are two platforms available for installing Freeciv21 on Windows: MSYS2 and Visual Studio. The package target is only supported on MSYS2 due to licensing constraints.

Once your MSYS2 environment is ready, start with Obtaining the Source Code above. Instead of installing, use this command to create the Windows Installer package:

$ cmake --build build --target package

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

Building with Nix

The project also contains a flake.nix allowing it to be built in NixOS or using the Nix package manager.

The following command is needed to configure the flake and should be repeated any time the flake is altered:

$ nix flake check

To create a standard release build:

$ nix build .#freeciv21 --out-link ./build-nix

This will create a symlink to the build directory under build-nix in the source directory. The binaries can be found under ./build-nix/bin/freeciv21-server for example.

To create a debug build retaining debug symbols compatible with gdb:

$ nix build .#freeciv21-debug --out-link ./build-nix-debug

Documentation Build Notes

Freeciv21 uses python3-sphynx and https://readthedocs.org/ to generate the well formatted HTML documentation that you are reading right now. To generate a local copy of the documentation from the docs directory you need two dependencies and a special build target.

The Sphinx Build Program

The sphinx-build program is used to generate the documentation from reStructuredText files (*.rst).

https://www.sphinx-doc.org/en/master/index.html

ReadTheDocs Theme

Freeciv21 uses the Read The Docs (RTD) theme for the general look and feel of the documentation.

https://sphinx-rtd-theme.readthedocs.io/en/stable/

If you are running Debian Linux, the base program is installed by the instructions in the Debian Linux Packages section above. The documentation is not built by default from the steps in Compiling/Building above. To generate a local copy of the documentation, issue this command:

$ cmake --build build --target docs

Other CMake Notes

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 bold text.

Table 1 Cmake Parameters

Directive

Description

FREECIV_ENABLE_TOOLS={ON/OFF}

Enables all the tools with one parameter (Ruledit, FCMP, Ruleup, and Manual)

FREECIV_ENABLE_SERVER={ON/OFF}

Enables the server. Should typically set to ON to be able to play AI games

FREECIV_ENABLE_NLS={ON/OFF}

Enables Native Language Support

FREECIV_ENABLE_CIVMANUAL={ON/OFF}

Enables the Freeciv21 Manual application

FREECIV_ENABLE_CLIENT={ON/OFF}

Enables the Qt client. Should typically set to ON unless you only want the server

FREECIV_ENABLE_FCMP_CLI={ON/OFF}

Enables the command line version of the Freeciv21 Modpack Installer

FREECIV_ENABLE_FCMP_QT={ON/OFF}

Enables the Qt version of the Freeciv21 Modpack Installer (recommended)

FREECIV_ENABLE_RULEDIT={ON/OFF}

Enables the Ruleset Editor

FREECIV_ENABLE_RULEUP={ON/OFF}

Enables the Ruleset upgrade tool

FREECIV_ENABLE_MANPAGES={ON/OFF}

Enables the generation of manpages. This is primarily relevant for Unix-like operating systems

FREECIV_USE_VCPKG={ON/OFF}

Enables the use of VCPKG

FREECIV_DOWNLOAD_FONTS{ON/OFF}

Enables the downloading of Libertinus Fonts

CMAKE_BUILD_TYPE={Release/Debug}

Changes the Build Type. Most people will pick Release

CMAKE_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 \
   -DCMAKE_BUILD_TYPE=Release \
   -DCMAKE_INSTALL_PREFIX=$HOME/Install/Freeciv21

A very common Debian Linux configuration command looks like this:

$ cmake . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=$PWD/build/install