Compiling the source

From Unvanquished
Jump to: navigation, search

Dependencies

Information 48x48.png

Note

In case this happens to become outdated, the up-to-date documentation can be found in the README.md file in source repository.

The game requires some dependencies to be built, which are the same on all systems:

  • cmake
  • python3-yaml
  • python3-jinja2
  • A C++11 able compiler (those are known to work: clang (>= 3.5), gcc (>= 4.8), visual studio (>= 2019))
  • zlib1g
  • libgmp
  • nettle
  • libcurl4-gnutls
  • libsdl2
  • libglew
  • libpng
  • libjpeg-turbo8
  • libwebp
  • libfreetype6
  • liblua5.3
  • libopenal
  • libogg
  • libvorbis
  • libopusfile

Those are optional:

  • libncursesw5

macOS

First, you need to acquire the source code.

Regardless of what interface you may use to compile the source, you will need CMake to generate makefiles. You will also need to install Xcode. At a minimum, you must install the "Xcode command-line tools" in order to compile anything. You may also install Xcode proper, if you wish to use that IDE.

Once you have the source code and the tools installed, you may actually proceed to compile the source. You have several options:

  • Compile the source at the command line. This is the easiest if you would just like to compile the game to use yourself and you do not intend to work on the code.
  • Compile the source using an IDE. This is preferred if you intend on developing the source.
    • Xcode is Apple's flagship IDE.
    • QtCreator is cross-platform and provides real-time feedback of syntax errors, a Vim mode, as well as other features.
    • Code::Blocks is also cross-platform but lacks some of the features of Xcode and QtCreator.

Dependencies

Precompiled static libs are provided for all dependencies. CMake downloads them at configure time and extracts to daemon/external_deps/macos-amd64-default_<version>/. These were produced by the external_deps/build.sh script, which you could also use to build them yourself if you want to for some reason.

Configuring with CMake

  1. Run CMake.
  2. Enter the location of the source code.
  3. Enter the location in which you would like to build the source code. This should be a different directory.
  4. Click "Configure". You will be prompted as to which generator you would like to use. If you have Xcode installed, choose that. Wait while the configuration process runs. You may have to set the following:
    1. If you have selected to generate Xcode project files, make the SDLMAIN_LIBRARY field blank. This option is not available if you have the generator set to Unix makefiles.
  5. Click "Generate".
  6. You may now close CMake.

Compiling

With Xcode

  1. Either start Xcode and open the project file (in the build directory you specified) or double-click the project file in Finder.
  2. Open the project file created by CMake, which should be in the build directory you specified.
  3. Change the active target to "ALL_BUILD" and click Product→Build.

With Unix Makefiles

  • Start Terminal (Applications → Utilities → Terminal).
  • Type the following commands: 
    $ cd /path/to/Unvanquished-build
$ make

    If you are on a multi-core or multi-processor machine, you may speed up the process by passing the -j argument followed by the number of available cores to make; e.g., make -j4. Note that doing so makes reading error messages more difficult, as multiple instances of the compiler will print to the screen at once, causing information to appear out of order.

Testing the build

With Xcode 4

To test the game, select the "client" scheme from the combo box on the toolbar, and click the run button or press Command ⌘R.

Building for arm64 (Apple Silicon) architecture

Our CMake scripts default to amd64 architecture, but you can also make a native build for the latest ARM-based Macs. Albeit while still relying on Rosetta to run amd64-based Native Client gamelogic binaries. 

# Install Daemon + Unvanquished dependencies (no pre-built ones for this architecture)
brew install nettle sdl2 libogg libvorbis opus opusfile web freetype glew openal-soft 

cmake path/to/source -DCMAKE_OSX_ARCHITECTURES=arm64 -DOpenAL_ROOT=$(brew --prefix openal-soft)

# If you want to run NaCl (assumes you have built amd64 at least once to download its deps):
cp path/to/daemon/external_deps/macos-amd64-default_10/{nacl_loader,irt_core-amd64.nexe} .

Windows

Visual Studio

CMake can generate Visual Studio projects for Unvanquished.

  1. Add _NO_DEBUG_HEAP=1 to your environment variables otherwise performance under the debugger will be terrible
  2. Run CMake with the source directory as the base directory of your source code (which should contain the directory src), and the build directory as a subdirectory of the source directory named build.
  3. Click the Open Project button. Or if you used CMake from the command line, open build/Unvanquished.sln in Visual Studio.
  4. In Visual Studio, choose your desired build type (default: Debug) from the drop-down menu in the top bar. Debug runs assertions and has complete debug information, but is slower. RelWithDebInfo is fast and still fairly usable with the debugger, but assertions don't run and sometimes you can't see the value of a local variable.
  5. Use Build → Build Solution to compile the code. Or just press F5 to build and run, but beware: this will not automatically build cgame or sgame! Only engine changes are automatically rebuilt when you run something from Visual Studio.

Important Notes

  • Due to limitations with CMake, the startup project cannot be specified. This must be set manually to debug the client with Visual Studio:
    • Right click on client and select "Set as Startup project".

MinGW

It is possible to produce a Windows build of Unvanquished with MinGW, as either a Windows or a Linux user. See MinGW#Distributions for detailed information about the toolchains available for installation.

Instructions for native Windows build with MSYS2

  1. Install MSYS2.
  2. Open the MSYS2 MinGW 32-bit or MSYS2 MinGW 64-bit terminal, depending on which bitness you want to build.
    3. Install toolchain: 
    # For 32-bit replace x86_64 with i686
pacman -Sy && pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake make
  3. Run CMake. If you're building Unvanquished, you may want to use the -DDAEMON_CBSE_PYTHON_PATH=<path> option in case you want to use a different Python rather than the one in MSYS2. 
    mkdir mybuild && cd mybuild
cmake -G "MSYS Makefiles" somepath/Unvanquished
  4. Build: 
     make -j4

    If you would like verbose output (useful to see compiler flags), set the VERBOSE environment variable before running Make. 

    export VERBOSE=1

You may find that the game (or some part of the MSYS2 toolchain!) fails to start due to missing DLL dependencies. Two helpful tools are:

  • The strace command in MSYS2, e.g. strace ./daemon
  • Dependencies (a Windows GUI program)

When distributing MinGW binaries, you need to distribute some additional DLLs besides the ones in the build folder. See MinGW#Built-in_DLL_dependencies.

MSYS2 Clang

In MSYS2, it is possible to build with Clang, rather than GCC as shown as in the above instructions. However, some of our pre-built libraries are incompatible. You need to use the ones from pacman instead.

  1. Create a deps folder with incompatible packages removed. This assumes that the latest version of the prebuilt deps for the mingw package of the appropriate bitness has already been extracted to the windows-${ARCH}-mingw_${VERSION} directory. In this example, we use windows-amd64-mingw_8. 
    cd somepath/daemon/external_deps
mkdir msysclang
cp windows-amd64-mingw_8 -R msysclang
find msysclang -depth -name '*freetype*' -o -name '*png*' -o name '*curl*' -o -name '*lua*' | grep -v pnacl | xargs rm -r
  2. Install those deps from Pacman: 
    # For Daemon
pacman -Sy && pacman -S mingw-w64-clang-x86_64-freetype mingw-w64-clang-x86_64-curl mingw-w64-clang-x86_64-libpng
# For Unvanquished
pacman -Sy && pacman -S mingw-w64-clang-x86_64-freetype mingw-w64-clang-x86_64-lua
  3. Use the deps folder you made when configuring the build: 
    CC=clang CXX=clang++ cmake -G "MSYS Makefiles" -DEXTERNAL_DEPS_DIR=somepath/daemon/external_deps/msysclang /c/path/to/source

    If you see a download progress bar upon invoking CMake, you did the deps stuff wrong.

QtCreator

  1. Install MinGW and follow the above instructions, except select Code::Blocks as the generator.
  2. Start QtCreator, and select "Open File or Project…" from the File menu.
  3. Navigate to your source directory and open CMakeLists.txt.
  4. At the CMake Wizard, select the same build directory you already configured using CMake. (If you did not chose Code::Blocks as the generator, you will have to start over again, as QtCreator requires a Code::Blocks project file in order to compile the source.)
  5. Ensure that a generator is selected in the combo box, and click "Run CMake". If there is no generator listed, see the troubleshooting section below.
  6. Click "Finish" to close the wizard.

You should now be able to compile, run, and debug the code using QtCreator.

Troubleshooting

If at the "Run CMake" prompt of the the CMake Wizard, select "Run CMake" and are warned that no generator was selected, and notice that there are no generators in the combo box, you will likely have to manually configure your toolchain. Select "Options…" from the "Tools" menu, then navigate to "Build & Run".

At the options window,

  • Go to the "Kits" tab, and mouse over the "Desktop (default)" kit under "Manual". If there were any errors in configuring this kit, they will be displayed in the tool tip. If there are problems, select the kit. You may need to manually specify the location of the MinGW debugger, for example, which is typically C:\MinGW\bin\gdb.exe.
  • Go to the "Compilers" tab, and ensure that MinGW is present. If not, you will need to add it manually.

Linux

Dependencies

🚧️ TODO: This may be incomplete.

Debian/Ubuntu

sudo apt-get install build-essential cmake libcurl4-gnutls-dev \
 libglew-dev libgmp-dev nettle-dev zlib1g-dev libncursesw5-dev \
 libsdl2-dev libopenal-dev libjpeg-dev libpng-dev libwebp-dev \
 libogg-dev libvorbis-dev libopusfile-dev \
 libfreetype6-dev \
 liblua5.3-dev \
 python3-yaml python3-jinja2

If the version of WebP supplied by your version of Debian or Ubuntu is older than v0.2.0, you will need to download and compile it from source. After compiling and installing with sudo make install, in CMake, you'll need to set WEBP_INCLUDE_DIR to /usr/local/include/webp and WEBP_LIBRARY to /usr/local/lib/libwebp.so.

Developpment package name may differs, for example libgmp-dev may be named libgmp3-dev and libglew-dev may be named libglew1.7-dev.

We have a debian directory in the source tree, you can check what's missing this way. 

cd path/to/unvanquished
dpkg-checkbuilddeps

Then install the listed packages this way: 

sudo apt-get install package list

The dpkg-checkbuilddeps command produces no output if you already have the required dependencies.

Note that you only need debhelper to build .deb files.

Fedora

Line 1 of the packages is basic dev tools. Lines 2-3 are Daemon dependencies. Line 4 is (additional) Unvanquished dependencies. 

$ sudo dnf install \
  cmake gcc gcc-c++ \
  {freetype,glew,gmp,mesa-libGL,ncurses,nettle,openal-soft,opus,opusfile,SDL2}-devel \
  lib{curl,jpeg-turbo,png12,vorbis,webp}-devel \
  lua-devel python3-pyyaml python3-jinja2

Gentoo

$ emerge curl freetype glew gmp jpeg ncurses media-sound/opus-tools libogg openal libpng libsdl libvorbis sys-libs/zlib

openSUSE

$ sudo install zypper gcc gcc-c++ Mesa-libGL-devel SDL-devel libjpeg8-devel \
  libpng12-devel glew-devel webp-devel ncurses-devel gmp-devel libcurl-devel \
  libnettle-devel openal-soft-devel libvorbis-devel

The latest version of WebP must be installed manually (FIXME: why, if there is webp-devel in the zypper package list?): 

$ cd Unvanquished/daemon/external_deps
$ ./build.sh linux-amd64-default webp naclsdk naclports
$ ./build.sh linux-amd64-default install

You must disable curses (set USE_CURSES appropriately in CMake) as failing to do so will cause Unvanquished to crash on startup.

Configuring the code with CMake

After you have acquired the source code, you can proceed to compile. Unvanquished uses CMake, so you must have that installed.

Using ccmake (curses-based front-end)

On Debian or Ubuntu: 

$ sudo apt-get install cmake-curses-gui

On Gentoo you should set the ncurses USE flag either globally or individually, just for cmake. To add the USE flag globally, edit the USE array in /etc/make.conf for it to include ncurses. To only install cmake with ncurses functionality, you could do the following: 

$ echo 'dev-util/cmake ncurses' >> /etc/portage/package.use && emerge cmake

Note that in Ubuntu, cmake-curses-gui is in Universe, which you may have to enable with software-properties-gtk. Make sure to reload the software sources with sudo apt-get update afterwards.

Optionally: to use clang (rather than the default gcc and g++ compilers) export the CC and CXX variables before running cmake: 

$ export CC="clang"
$ export CXX="clang++ -stdlib=libc++ -lc++abi"

Next, configure the codebase. 

$ cd /path/to/unvanquished
$ mkdir build
$ cd build
$ ccmake ..

In Debian or Ubuntu you can build a package this way (you need devscripts and fakeroot packages): 

$ cd /path/to/unvanquished
$ fakeroot dpkg-buildpackage -b -uc
$ sudo dpkg -i ../unvanquished_*.deb

Once in ccmake, use the following keys:

  • Press c to configure. If an error occurs during this phase, make note of it and press e to dismiss it.
  • Use the up and down arrow keys to navigate the compilation options.
  • Press Enter to enable or disable boolean options (i.e., on/off) or to edit textual options.
    • Press Esc when editing a textual option to cancel the change.

Once you have finished the configuration process, press C again, then G to generate the makefile.

Using cmake-qt-gui (graphical front-end)

This graphical front end for cmake has its own package you must install:

Debian/Ubuntu
$ sudo apt-get install cmake-qt-gui
Gentoo

With the qt4 USE flag enabled: 

$ emerge cmake

Once installed, run with cmake-gui.

Cmake-qt-gui.png
  1. Set the path where you have the source code downloaded.
  2. Set the path where you would like to build the engine. This may be the same directory if you wish.
  3. Click 'Configure'.
  4. Click 'Generate'.

Unnecessary libraries

Regardless of which front-end to cmake you use, you may want to disable some libraries that are not strictly necessary:

  • USE_BREAKPAD — Disabling this will cause the game to not produce crashdumps on failure.
  • USE_CURSES — Disabling this will cause the external (not in-game) console to not use curses; it will not be scrollable and will be similar to the console in the original Tremulous. This does in no way affect gameplay.

Compiling

$ cd path/to/unvanquished/build
$ make -j4

The -j switch to make allows you to speed up the compilation process by running it in multiple threads; set the number following this to the number of cores your processor(s) have.

FreeBSD

While building on FreeBSD is usually very similar to building on Linux, the PNaCl toolchain not being native to FreeBSD means not everything can be built on FreeBSD. See the Systems/FreeBSD page for details and dedicated instructions.

Acquiring the Game Files

Acquiring mandatory game files

The game files are not in the Git repository, and must be downloaded separately. They must be saved to the data location for your system.

Linux users may use the download-paks script that is distributed with the source code, which requires one of curl, wget or aria2 to be installed: 

$ cd path/to/unvanquished/build
$ ../download-paks pkg

Otherwise, the set of necessary packages can be extracted from the latest release, or downloaded a la carte from the package index.

Retrieved from ‘https://wiki.unvanquished.net/index.php?title=Compiling_the_source&oldid=8769’