Difference between revisions of "How to build VCMI (Linux)"

From VCMI Project Wiki
Jump to: navigation, search
(Package building)
(Update instructions how to build RPM)
 
(32 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 
= Compiling VCMI =
 
= Compiling VCMI =
Supported C++ compilers for UNIX-like systems: GCC 4.6+, Clang 3.1+
+
* Current baseline requirement for building is Ubuntu 20.04
 +
* Supported C++ compilers for UNIX-like systems are GCC 5.5+ and Clang 13+
  
There is a guide for compiling and running VCMI located in the SVN trunk root directory: [https://vcmi.svn.sourceforge.net/svnroot/vcmi/trunk/README.linux README.linux]
+
Older distributions and compilers might work, but they aren't tested by [https://travis-ci.org/vcmi/vcmi/ Travis CI]
  
'''Set automatically soft-links bash script'''
+
= Installing dependencies =
  
The last step in the above-mentioned compiling guide requires to create soft-links for convenient debugging and development in general. There is a bash script which does this step automatically for you. You have to enter the build path, specify the source path and select the usual library folder of the operating system. Then the script takes the work to create all those symbolic links. This is comfortable if you're working on different source folders(trunk, tag, branch) or build types(debug, release) and you want to switch from one build to the other. The link to the script is here: http://download.vcmi.eu/setBuildLinks
+
== Prerequisites ==
  
= Setting up a development environment using QtCreator =
+
To compile, the following packages (and their development counterparts) are needed to build:
 +
* CMake 3.10 or newer
 +
* SDL2 with devel packages: mixer, image, ttf
 +
* zlib and zlib-devel
 +
* Recommended, if you want to build launcher or map editor: Qt 5, widget and network modules
 +
* Recommended, FFmpeg libraries, if you want to watch in-game videos: libavformat and libswscale. Their name could be libavformat-devel and libswscale-devel, or ffmpeg-libs-devel or similar names.
 +
* Boost C++ libraries v1.48+: program-options, filesystem, system, thread, locale
 +
* Optional, if you want to build scripting modules: LuaJIT
  
QtCreator is the recommended IDE for VCMI development on linux distros. (It may be used on other operating systems as well) It has the following advantages compared to other IDEs:
+
== On Debian-based systems (e.g. Ubuntu) ==
* Almost no manual configuration when used with CMake (Project configuration is read from CMake text files)
 
* Fast parser/indexer, stable
 
* Can use several compiler toolchains: GCC, Visual Studio, Clang
 
* Doesn't pollute SVN with project files
 
  
You can download QtCreator from here: http://qt-project.org/downloads#qt-creator
+
For Ubuntu 22.04 (jammy) or newer you need to install this list of packages, including '''libtbb2-dev''':
 +
<pre>
 +
sudo apt-get install cmake g++ libsdl2-dev libsdl2-image-dev libsdl2-ttf-dev libsdl2-mixer-dev zlib1g-dev libavformat-dev libswscale-dev libboost-dev libboost-filesystem-dev libboost-system-dev libboost-thread-dev libboost-program-options-dev libboost-locale-dev qtbase5-dev libtbb2-dev libluajit-5.1-dev qttools5-dev
 +
</pre>
 +
 
 +
For Ubuntu 21.10 (impish) or older and all versions of Debian (9 stretch - 11 bullseye) you need to install this list of packages, including '''libtbb-dev''':
 +
<pre>
 +
sudo apt-get install cmake g++ libsdl2-dev libsdl2-image-dev libsdl2-ttf-dev libsdl2-mixer-dev zlib1g-dev libavformat-dev libswscale-dev libboost-dev libboost-filesystem-dev libboost-system-dev libboost-thread-dev libboost-program-options-dev libboost-locale-dev qtbase5-dev libtbb-dev libluajit-5.1-dev qttools5-dev
 +
</pre>
 +
 
 +
Alternatively if you have VCMI installed from repository or PPA you can use:
 +
<pre>
 +
sudo apt-get build-dep vcmi
 +
</pre>
 +
 
 +
== On RPM-based distributions (e.g. Fedora) ==
 +
 
 +
<pre>
 +
sudo yum install cmake gcc-c++ SDL2-devel SDL2_image-devel SDL2_ttf-devel SDL2_mixer-devel boost boost-devel boost-filesystem boost-system boost-thread boost-program-options boost-locale zlib-devel ffmpeg-devel ffmpeg-libs qt5-qtbase-devel tbb-devel luajit-devel fuzzylite-devel
 +
</pre>
 +
 
 +
NOTE: `fuzzylite-devel` package is no longer available in recent version of Fedora, for example Fedora 38. It's not a blocker because VCMI bundles fuzzylite lib in its source code.
 +
 
 +
== On Arch-based distributions ==
 +
On Arch-based distributions, there is a development package available for VCMI on the AUR.
 +
 
 +
It can be found at: https://aur.archlinux.org/packages/vcmi-git/
  
== Configuration ==
+
Information about building packages from the Arch User Repository (AUR) can be found at the Arch wiki.
To open the project you have to click File -> Open file or project... -> Select /trunk/src/CMakeLists.txt.
 
  
 +
== Manual Installation ==
  
For the first time and for every CMake project configuration change you have to execute CMake. This step can be done when opening the project for the first time or alternatively via the left bar -> Projects -> Build Settings -> Execute CMake. You have to specify CMake arguments and the build dir. CMake arguments can be the following:
+
For older OS versions the latest prerequisite packages may not be readily available via the system installer. Some brief instructions for manual install are given below (tested on Ubuntu 14.04, update version numbers as desired).
<pre>-DCMAKE_BUILD_TYPE=Debug</pre>
 
The build dir should be set to something like /trunk/build for the debug build and /trunk/buildrel for the release build.
 
For cleaning the build dir a command like "make clean" may be not enough. Better way is to delete the build dir, re-create it and re-execute CMake. Steps for cleaning can be configured in the Projects tab as well.
 
  
== Debugging ==
+
* CMake (see also https://askubuntu.com/questions/355565/how-do-i-install-the-latest-version-of-cmake-from-the-command-line/865294)
There is a problem with QtCreator when debugging both vcmiclient and vcmiserver. If you debug the vcmiclient, start a game, attach the vcmiserver process to the gdb debugger(Debug > Start Debugging > Attach to Running External Application...) then breakpoints which are set for vcmiserver will be ignored. This looks like a bug, in any case it's not intuitively. Two workarounds are available luckily:
+
<pre>
 +
wget https://cmake.org/files/v3.11/cmake-3.11.0.tar.gz
 +
tar xfz cmake-3.11.0.tar.gz
 +
cd cmake-3.11.0
 +
./bootstrap
 +
make -j2
 +
sudo checkinstall --pkgname cmake --pkgversion 3.11.0 -y
 +
</pre>
 +
Note: Will only be visible in new terminals. Test with cmake --version.
  
1) Run vcmiclient (no debug mode), then attach server process to the debugger
+
* Boost (see also https://ubuntuforums.org/showthread.php?t=1180792)
 +
<pre>
 +
wget https://dl.bintray.com/boostorg/release/1.66.0/source/boost_1_66_0.tar.gz
 +
tar xfz boost_1_66_0.tar.gz
 +
cd boost_1_66_0
 +
./bootstrap.sh --with-libraries=program-options,filesystem,system,thread,locale
 +
./b2
 +
sudo ./b2 install
 +
</pre>
 +
Note: Boost 1.66.0 produces a bug in asio.hpp when used with old gcc versions (see https://svn.boost.org/trac10/ticket/13368).
  
2) Open two instances of QtCreator and debug vcmiserver and vcmiclient separately(it works!)
+
* GCC (for Ubuntu - compile from source is lengthy)
 +
<pre>
 +
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
 +
sudo apt-get update
 +
sudo apt-get install gcc-7 g++-7
 +
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-7 70 --slave /usr/bin/g++ g++ /usr/bin/g++-7
 +
</pre>
 +
Note: Test with gcc --version (and g++ --version).
 +
 
 +
* Clang (for Ubuntu 14.04 - for later versions first line is not needed, and 'trusty' should be replaced with version name)
 +
<pre>
 +
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
 +
sudo add-apt-repository "deb http://apt.llvm.org/trusty/ llvm-toolchain-trusty-6.0 main"
 +
sudo apt-get update
 +
sudo apt-get install clang-6.0
 +
sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-6.0 60 --slave /usr/bin/clang++ clang++ /usr/bin/clang++-6.0
 +
</pre>
 +
Note: Test with clang --version (and clang++ --version).
 +
 
 +
= Getting the sources =
 +
 
 +
VCMI is still in development. We recommend the following initial directory structure:
 +
<pre>
 +
.
 +
├── vcmi -> contains sources and is under git control
 +
└── build -> contains build output, makefiles, object files,...
 +
</pre>
 +
 
 +
You can get latest sources with:
 +
<pre>
 +
git clone -b develop --recursive https://github.com/vcmi/vcmi.git
 +
</pre>
 +
 
 +
= Compilation =
 +
 
 +
== Configuring Makefiles ==
 +
<pre>
 +
mkdir build && cd build
 +
cmake ../vcmi
 +
 
 +
# Additional options that you may want to use:
 +
## To enable debugging:
 +
cmake ../vcmi -DCMAKE_BUILD_TYPE=Debug
 +
</pre>
 +
'''Notice''':
 +
The ../vcmi/ is not a typo, it will place makefile scripts into the build dir as the build dir is your working dir when calling CMake.
 +
 
 +
== Trigger build ==
 +
<pre>
 +
cmake --build . -- -j2
 +
# -j2 = compile with 2 threads, you can specify any value
 +
</pre>
 +
That will generate vcmiclient, vcmiserver, vcmilauncher as well as 4 .so libraries in '''build/bin/''' directory.
  
 
= Package building =
 
= Package building =
Line 40: Line 136:
 
The first step is to prepare a RPM build environment. On Fedora systems you can follow this guide: http://fedoraproject.org/wiki/How_to_create_an_RPM_package#SPEC_file_overview
 
The first step is to prepare a RPM build environment. On Fedora systems you can follow this guide: http://fedoraproject.org/wiki/How_to_create_an_RPM_package#SPEC_file_overview
  
1. Download the file rpm/vcmi.spec from any tagged VCMI release for which you wish to build a RPM package via the SVN Browser trac at this URL for example(which is for VCMI 0.9): http://sourceforge.net/apps/trac/vcmi/browser/tags/0.9/rpm/vcmi.spec
 
  
2. Copy the file to ~/rpmbuild/SPECS
+
0. Enable RPMFusion free repo to access to ffmpeg libs:
 +
 
 +
<pre>
 +
sudo dnf install \
 +
  https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
 +
</pre>
  
3. Follow instructions in the vcmi.spec. You have to export the corresponding SVN tag, compress it to a g-zipped archive and copy it to ~/rpmbuild/SOURCES. Instructions are written as comments and you can copy/paste commands into terminal.
+
NOTE: the stock ffmpeg from Fedora repo is no good as it has stripped lots of codecs
  
4. Go to ~/rpmbuild/SPECS and open terminal in this folder and type: <pre>rpmbuild -ba vcmi.spec (this will build rpm and source rpm)</pre>
+
1. Perform a git clone from a tagged branch for the right Fedora version from https://github.com/rpmfusion/vcmi; for example for Fedora 38: <pre>git clone -b f38 --single-branch https://github.com/rpmfusion/vcmi.git</pre>
 +
 
 +
2. Copy all files to ~/rpmbuild/SPECS with command: <pre>cp vcmi/*  ~/rpmbuild/SPECS</pre>
 +
 
 +
3. Fetch all sources by using spectool:
 +
 
 +
<pre>
 +
sudo dnf install rpmdevtools
 +
spectool -g -R ~/rpmbuild/SPECS/vcmi.spec
 +
</pre>
 +
 
 +
4. Fetch all dependencies required to build the RPM:
 +
 
 +
<pre>
 +
sudo dnf install dnf-plugins-core
 +
sudo dnf builddep ~/rpmbuild/SPECS/vcmi.spec
 +
</pre>
 +
 
 +
4. Go to ~/rpmbuild/SPECS and open terminal in this folder and type: `rpmbuild -ba ~/rpmbuild/SPECS/vcmi.spec`
  
 
5. Generated RPM is in folder ~/rpmbuild/RPMS
 
5. Generated RPM is in folder ~/rpmbuild/RPMS
  
If you want to package the generated RPM above for different processor architectures and operating systems you can use the tool mock. Moreover, it is necessary to install mock-rpmfusion_free due to the packages ffmpeg-devel and ffmpeg-libs which aren't available in the standard RPM repositories(at least for Fedora). Go to ~/rpmbuild/SRPMS in terminal and type:
+
If you want to package the generated RPM above for different processor architectures and operating systems you can use the tool mock.
<pre>mock -r fedora-17-i386-rpmfusion_free path_to_source_RPM
+
Moreover, it is necessary to install mock-rpmfusion_free due to the packages ffmpeg-devel and ffmpeg-libs which aren't available in the
mock -r fedora-17-x86_64-rpmfusion_free path_to_source_RPM</pre>
+
standard RPM repositories(at least for Fedora). Go to ~/rpmbuild/SRPMS in terminal and type:
 +
<pre>mock -r fedora-38-aarch64-rpmfusion_free path_to_source_RPM
 +
mock -r fedora-38-x86_64-rpmfusion_free path_to_source_RPM</pre>
 +
 
 +
For other distributions that uses RPM, chances are there might be a spec file for VCMI. If there isn't, you can adapt the RPMFusion's file
  
 
Available root environments and their names are listed in /etc/mock.
 
Available root environments and their names are listed in /etc/mock.
Line 65: Line 187:
 
</pre>
 
</pre>
 
To generate packages for different architectures see "-a" flag of dpkg-buildpackage command
 
To generate packages for different architectures see "-a" flag of dpkg-buildpackage command
 +
 +
== Documentation ==
 +
 +
To compile using Doxygen, the UseDoxygen CMake module must be installed. It can be fetched from: http://tobias.rautenkranz.ch/cmake/doxygen/
 +
 +
Once UseDoxygen is installed, run:
 +
<pre>
 +
cmake .
 +
make doc
 +
</pre>
 +
 +
The built documentation will be available from ./doc

Latest revision as of 06:09, 17 August 2023

Compiling VCMI

  • Current baseline requirement for building is Ubuntu 20.04
  • Supported C++ compilers for UNIX-like systems are GCC 5.5+ and Clang 13+

Older distributions and compilers might work, but they aren't tested by Travis CI

Installing dependencies

Prerequisites

To compile, the following packages (and their development counterparts) are needed to build:

  • CMake 3.10 or newer
  • SDL2 with devel packages: mixer, image, ttf
  • zlib and zlib-devel
  • Recommended, if you want to build launcher or map editor: Qt 5, widget and network modules
  • Recommended, FFmpeg libraries, if you want to watch in-game videos: libavformat and libswscale. Their name could be libavformat-devel and libswscale-devel, or ffmpeg-libs-devel or similar names.
  • Boost C++ libraries v1.48+: program-options, filesystem, system, thread, locale
  • Optional, if you want to build scripting modules: LuaJIT

On Debian-based systems (e.g. Ubuntu)

For Ubuntu 22.04 (jammy) or newer you need to install this list of packages, including libtbb2-dev:

sudo apt-get install cmake g++ libsdl2-dev libsdl2-image-dev libsdl2-ttf-dev libsdl2-mixer-dev zlib1g-dev libavformat-dev libswscale-dev libboost-dev libboost-filesystem-dev libboost-system-dev libboost-thread-dev libboost-program-options-dev libboost-locale-dev qtbase5-dev libtbb2-dev libluajit-5.1-dev qttools5-dev 

For Ubuntu 21.10 (impish) or older and all versions of Debian (9 stretch - 11 bullseye) you need to install this list of packages, including libtbb-dev:

sudo apt-get install cmake g++ libsdl2-dev libsdl2-image-dev libsdl2-ttf-dev libsdl2-mixer-dev zlib1g-dev libavformat-dev libswscale-dev libboost-dev libboost-filesystem-dev libboost-system-dev libboost-thread-dev libboost-program-options-dev libboost-locale-dev qtbase5-dev libtbb-dev libluajit-5.1-dev qttools5-dev 

Alternatively if you have VCMI installed from repository or PPA you can use:

sudo apt-get build-dep vcmi

On RPM-based distributions (e.g. Fedora)

sudo yum install cmake gcc-c++ SDL2-devel SDL2_image-devel SDL2_ttf-devel SDL2_mixer-devel boost boost-devel boost-filesystem boost-system boost-thread boost-program-options boost-locale zlib-devel ffmpeg-devel ffmpeg-libs qt5-qtbase-devel tbb-devel luajit-devel fuzzylite-devel

NOTE: `fuzzylite-devel` package is no longer available in recent version of Fedora, for example Fedora 38. It's not a blocker because VCMI bundles fuzzylite lib in its source code.

On Arch-based distributions

On Arch-based distributions, there is a development package available for VCMI on the AUR.

It can be found at: https://aur.archlinux.org/packages/vcmi-git/

Information about building packages from the Arch User Repository (AUR) can be found at the Arch wiki.

Manual Installation

For older OS versions the latest prerequisite packages may not be readily available via the system installer. Some brief instructions for manual install are given below (tested on Ubuntu 14.04, update version numbers as desired).

wget https://cmake.org/files/v3.11/cmake-3.11.0.tar.gz
tar xfz cmake-3.11.0.tar.gz
cd cmake-3.11.0
./bootstrap
make -j2
sudo checkinstall --pkgname cmake --pkgversion 3.11.0 -y

Note: Will only be visible in new terminals. Test with cmake --version.

wget https://dl.bintray.com/boostorg/release/1.66.0/source/boost_1_66_0.tar.gz
tar xfz boost_1_66_0.tar.gz
cd boost_1_66_0
./bootstrap.sh --with-libraries=program-options,filesystem,system,thread,locale
./b2
sudo ./b2 install

Note: Boost 1.66.0 produces a bug in asio.hpp when used with old gcc versions (see https://svn.boost.org/trac10/ticket/13368).

  • GCC (for Ubuntu - compile from source is lengthy)
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update
sudo apt-get install gcc-7 g++-7
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-7 70 --slave /usr/bin/g++ g++ /usr/bin/g++-7

Note: Test with gcc --version (and g++ --version).

  • Clang (for Ubuntu 14.04 - for later versions first line is not needed, and 'trusty' should be replaced with version name)
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo add-apt-repository "deb http://apt.llvm.org/trusty/ llvm-toolchain-trusty-6.0 main"
sudo apt-get update
sudo apt-get install clang-6.0
sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-6.0 60 --slave /usr/bin/clang++ clang++ /usr/bin/clang++-6.0

Note: Test with clang --version (and clang++ --version).

Getting the sources

VCMI is still in development. We recommend the following initial directory structure:

.
├── vcmi -> contains sources and is under git control
└── build -> contains build output, makefiles, object files,...

You can get latest sources with:

git clone -b develop --recursive https://github.com/vcmi/vcmi.git

Compilation

Configuring Makefiles

mkdir build && cd build
cmake ../vcmi

# Additional options that you may want to use:
## To enable debugging:
cmake ../vcmi -DCMAKE_BUILD_TYPE=Debug

Notice: The ../vcmi/ is not a typo, it will place makefile scripts into the build dir as the build dir is your working dir when calling CMake.

Trigger build

cmake --build . -- -j2
# -j2 = compile with 2 threads, you can specify any value

That will generate vcmiclient, vcmiserver, vcmilauncher as well as 4 .so libraries in build/bin/ directory.

Package building

RPM package

The first step is to prepare a RPM build environment. On Fedora systems you can follow this guide: http://fedoraproject.org/wiki/How_to_create_an_RPM_package#SPEC_file_overview


0. Enable RPMFusion free repo to access to ffmpeg libs:

sudo dnf install \
  https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm

NOTE: the stock ffmpeg from Fedora repo is no good as it has stripped lots of codecs

1. Perform a git clone from a tagged branch for the right Fedora version from https://github.com/rpmfusion/vcmi; for example for Fedora 38:
git clone -b f38 --single-branch https://github.com/rpmfusion/vcmi.git
2. Copy all files to ~/rpmbuild/SPECS with command:
cp vcmi/*  ~/rpmbuild/SPECS

3. Fetch all sources by using spectool:

sudo dnf install rpmdevtools
spectool -g -R ~/rpmbuild/SPECS/vcmi.spec

4. Fetch all dependencies required to build the RPM:

sudo dnf install dnf-plugins-core
sudo dnf builddep ~/rpmbuild/SPECS/vcmi.spec

4. Go to ~/rpmbuild/SPECS and open terminal in this folder and type: `rpmbuild -ba ~/rpmbuild/SPECS/vcmi.spec`

5. Generated RPM is in folder ~/rpmbuild/RPMS

If you want to package the generated RPM above for different processor architectures and operating systems you can use the tool mock. Moreover, it is necessary to install mock-rpmfusion_free due to the packages ffmpeg-devel and ffmpeg-libs which aren't available in the standard RPM repositories(at least for Fedora). Go to ~/rpmbuild/SRPMS in terminal and type:

mock -r fedora-38-aarch64-rpmfusion_free path_to_source_RPM
mock -r fedora-38-x86_64-rpmfusion_free path_to_source_RPM

For other distributions that uses RPM, chances are there might be a spec file for VCMI. If there isn't, you can adapt the RPMFusion's file

Available root environments and their names are listed in /etc/mock.

Debian/Ubuntu

1. Install debhelper and devscripts packages

2. Run dpkg-buildpackage command from vcmi source directory

sudo apt-get install debhelper devscripts
cd /path/to/source
dpkg-buildpackage

To generate packages for different architectures see "-a" flag of dpkg-buildpackage command

Documentation

To compile using Doxygen, the UseDoxygen CMake module must be installed. It can be fetched from: http://tobias.rautenkranz.ch/cmake/doxygen/

Once UseDoxygen is installed, run:

cmake .
make doc

The built documentation will be available from ./doc