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 5.15+ is required. As of this writing this is Linux, Microsoft Windows® and Apple macOS®.
Linux Distributions:
Arch
Debian 11+ (Bullseye)®
Fedora 30+
Gentoo
KDE Neon
Manjaro
Mint 20+ or Mint Debian Edition (set to Bullseye)
openSUSE 15.3+
Slackware
Ubuntu 22.04 LTS+
Fedora 37+
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, MSYS2 and macOS environments. 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.
- 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’sclang-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 havecmake
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 haveninja
installed on your system by typing the following command. The output should includeninja
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.
- 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.
- 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.- 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.
- KF 5 Archive Library
KDE frameworks 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
Freeciv21 requires version 3 of Python
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
Qt5Core
,Qt5Gui
,Qt5Network
,Qt5Svg
, andQt5Widgets
libraries and headers.At least version 5.15 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
See the macOS Packages section below on the steps to install the components for Apple macOS.
If you are running Windows and want to use the MSYS2 environment and have not set it up yet, then do so now, before continuing.
Lastly, if you are running Windows and want to use Visual Studio, you can follow the Microsoft Visual Studio instructions. The Visual Studio instructions are self contained. You do not need to return here in that case.
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 \
python3 \
qtbase5-dev \
libqt5svg5-dev \
libkf5archive-dev \
liblua5.3-dev \
libsqlite3-dev \
libsdl2-mixer-dev \
libmagickwand-dev \
libunwind-dev \
libdw-dev \
python3-sphinx \
clang-format-11
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 \
qt5-qtbase-devel \
qt5-qtsvg-devel \
kf5-karchive-devel \
lua-devel \
sqlite-devel \
SDL2_mixer-devel \
readline-devel \
zlib-devel \
libunwind-devel \
elfutils-libs \
python3-sphinx
At this point, follow the steps in Obtaining the Source Code section below.
macOS Packages
Below are all the command line steps needed to start with a fresh install of macOS.
$ brew update
$ brew install \
cmake \
ninja \
python3 \
gettext \
vcpkg
brew link gettext --force
$ export VCPKG_ROOT="$HOME/vcpkg"
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.
On macOS, you need to use a preset that is defined in the CMakePresets.json
file. When complete
you can go to the Compiling/Building section below to continue.
$ cmake --preset fullrelease-macos -S . -B build
Note
The first time you run the this command, cmake
invokes the vcpkg
installation process to
download and compile all of the project dependencies listed in the manifest file: vcpkg.json
.
This will take a very long time. On a fast computer with a good Internet connection it will take
at least 3 hours to complete. Everything will be downloaded and compiled into the $HOME/vcpkg
directory. Binaries for the packages will be copied into the ./build/
directory inside of the main
Freeciv21 directory and reused for subsequent builds.
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
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
).- ReadTheDocs Theme
Freeciv21 uses the Read The Docs (RTD) theme for the general look and feel of the documentation.
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.
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
|
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