Difference between revisions of "Compiling the source"

From Unvanquished
Jump to: navigation, search
(Configuring with CMake: s/Xcode/CMake)
(Clarify a bit)
Line 116: Line 116:
# Hit "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:
# Hit "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:
## If CMake did not find your jpeg headers for some reason, set <code>JPEG_INCLUDE_DIR</code> to <code>/path/to/Unvanquished/src/libs/jpeg</code>.
## If CMake did not find your jpeg headers for some reason, set <code>JPEG_INCLUDE_DIR</code> to <code>/path/to/Unvanquished/src/libs/jpeg</code>.
## Check <code>USE_INTERNAL_CRYPTO</code> to avoid having to compile nettle and hogweed.
## Check <code>USE_INTERNAL_CRYPTO</code> to avoid having to compile nettle and hogweed yourself.
## Check <code>USE_INTERNAL_SPEEX</code> to avoid having to compile Speex.
## Check <code>USE_INTERNAL_SPEEX</code> to avoid having to compile Speex yourself.
## Uncheck <code>USE_CIN_THEORA</code> and <code>USE_CIN_XVID</code> to avoid having to compile Theora or Xvid. (At present, there are not cutscenes or any such that require it.)
## Uncheck <code>USE_CIN_THEORA</code> and <code>USE_CIN_XVID</code> to avoid having to compile Theora or Xvid. (At present, there are not cutscenes or any such that require it.)
## '''You will probably not be able to compile with the GLSL optimizer enabled; uncheck <code>USE_GLSL_OPTIMIZER</code>'''
## '''You will probably not be able to compile with the GLSL optimizer enabled; uncheck <code>USE_GLSL_OPTIMIZER</code>'''

Revision as of 17:08, 15 April 2013

Mac OS X

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 (making sure to choose to install the command-line utilities when prompted by the installer).

Then, you will need to acquire (and in some cases, manually compile) at a minimum the necessary libraries.

Once you have the source code and the libraries 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 and you should have installed to compile the source regardless of which method you use.
    • QtCreator is cross-platform and provides real-time feedback of syntax errors, a Vim mode, as well as other features.
    • Code::Blcoks is also cross-platform but lacks some of the features of Xcode and QtCreator.


You only need to use one of the following methods (HomeBrew or compiling by hand). Please try and avoid mixing methods as this may produce unexpected results.

Unvanquished requires the following libraries:

The following libraries are optional:


Install HomeBrew and then run the following command

$ brew install nettle libjpeg curl sdl webp xvid gmp glew speex libvorbis theora

All the necessary libraries should now have been installed.

Compiling by hand

The following are shell scripts that download, compile, and install various libraries. This is more time consuming then other methods but might be useful if you need more control over your libraries

$ curl http://www.ijg.org/files/jpegsrc.v8d.tar.gz > jpegsrc.v8d.tar.gz
$ tar xvzf jpegsrc.v8d.tar.gz
$ cd jpeg-8d
$ ./configure
$ make
$ sudo make install
The OpenGL Extension Wrangler Library (GLEW)
$ curl -L https://sourceforge.net/projects/glew/files/glew/1.7.0/glew-1.7.0.tgz/download > glew-1.7.0.tgz
$ tar xvzf glew-1.7.0.tgz
$ cd glew-1.7.0
$ make
$ sudo make install
Simple DirectMedia Layer (SDL)

Do not use the binaries provided by libsdl.org, as these are known to cause issues with gamma and color display. Instead, compile your own:

$ curl http://www.libsdl.org/release/SDL-1.2.15.tar.gz > SDL-1.2.15.tar.gz
$ tar xvzf SDL-1.2.15.tar.gz
$ cd SDL-1.2.15
$ ./configure
$ make
$ sudo make install
The GNU MP Bignum Library (libgmp)
$ curl ftp://ftp.gmplib.org/pub/gmp-5.0.5/gmp-5.0.5.tar.bz2 > gmp-5.0.5.tar.bz2
$ tar xvjf gmp-5.0.5.tar.bz2
$ cd gmp-5.0.5
$ ./configure
$ make
$ sudo make install
$ curl http://downloads.xiph.org/releases/ogg/libogg-1.3.0.tar.gz > libogg-1.3.0.tar.gz
$ tar xvzf libogg-1.3.0.tar.gz
$ cd libogg-1.3.0
$ ./configure
$ make
$ sudo make install
$ curl http://downloads.xiph.org/releases/vorbis/libvorbis-1.3.3.tar.gz > libvorbis-1.3.3.tar.gz
$ tar xvzf libvorbis-1.3.3.tar.gz
$ cd libvorbis-1.3.3
$ ./configure
$ make
$ sudo make install

You do not need to compile WebP by hand; Google provides binaries for Mac OS X available from their project page. You will need version 0.2.0 or newer.

Once downloaded, you must still install the header files and the binary:

$ curl https://webp.googlecode.com/files/libwebp-0.2.0-mac-10.5.tar.gz > libwebp-0.2.0-mac-10.5.tar.gz
$ tar xvzf libwebp-0.2.0-mac-10.5.tar.gz
$ cd libwebp-0.2.0-mac-10.5
$ sudo cp include/webp /usr/local/include
$ sudo cp lib/libwebp.a /usr/local/lib

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. Hit "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 CMake did not find your jpeg headers for some reason, set JPEG_INCLUDE_DIR to /path/to/Unvanquished/src/libs/jpeg.
    2. Check USE_INTERNAL_CRYPTO to avoid having to compile nettle and hogweed yourself.
    3. Check USE_INTERNAL_SPEEX to avoid having to compile Speex yourself.
    4. Uncheck USE_CIN_THEORA and USE_CIN_XVID to avoid having to compile Theora or Xvid. (At present, there are not cutscenes or any such that require it.)
    5. You will probably not be able to compile with the GLSL optimizer enabled; uncheck USE_GLSL_OPTIMIZER
    6. 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. Hit "Generate".
  6. You may now close CMake.


With Xcode

  1. Compilation will fail unless you manually create certain directories needed by the build scripts:
    $ cd /path/to/build/dir/CMakeFiles
    $ mkdir gpp{game,trem,ui}-qvm.dir

    This is a workaround to Issue 101.

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

With Unix Makefiles

  • Start Terminal (Applications → Utilities → Terminal).
  • Input 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.

With Unix Makefiles

After compiling, you'll have to place the data files in the main directory in your build directory. For download instructions, see below.

Your file structure should look as follows:

Build dir Mac OS X.png

You may now start the application as such:

$ ./daemon.i386

Note that older machines will not support the new OpenGL 3 renderer, and must be started specifying the "vanilla" (aka "GL") renderer:

$ ./daemon.i386 +set cl_renderer GL

Bundling the Application

With CPack

CPack is able to create standalone bundles (as well as many other types of installers). However you must generate the files using Unix Makefiles instead of Xcode.

$ cd /path/to/Unvanquished-build
$ cpack -G Bundle

Some warnings will be printed however these can be safely ignored. There should be a file called Unvanquished.dmg in the Unvanquished-build folder.


You'll find the Mac dynamic library bundler to be quite useful (you must generate the files using Unix Makefiles instead of Xcode):

$ curl -L http://sourceforge.net/projects/macdylibbundler/files/macdylibbundler/0.4.1/dylibbundler0.4.1.zip/download > \
$ unzip dylibbundler0.4.1.zip
$ cd dylibbundler
$ make
$ sudo make install

Once you've done that, you can proceed to create the application bundle. Note that these steps assume that you have downloaded the data files to main/ as shown above:

$ git=/path/to/Unvanquished-git-repo
$ build=/path/to/Unvanquished-build-dir
$ mkdir -pv Unvanquished.app/Contents/{libs,MacOS,Resources,Frameworks}
$ cp -r $build/main Unvanquished.app/Contents/MacOS
$ sips -s format tiff $git/debian/unvanquished.png --out temp.tiff
$ tiff2icns temp.tiff Unvanquished.app/Contents/Resources/Unvanquished.icns
$ rm temp.tiff
$ cp $build/daemon{,ded}.i386 $build/*.dylib Unvanquished.app/Contents/MacOS
$ cp -r /Library/Frameworks/SDL.framework Unvanquished.app/Contents/Frameworks
$ install_name_tool -id \
    @executable_path/../Frameworks/SDL.framework/Versions/A/SDL \
$ install_name_tool -change @rpath/SDL.framework/Versions/A/SDL \
    @executable_path/../Frameworks/SDL.framework/Versions/A/SDL \
$ install_name_tool -change @rpath/SDL.framework/Versions/A/SDL \
    @executable_path/../Frameworks/SDL.framework/Versions/A/SDL \
$ install_name_tool -change @rpath/SDL.framework/Versions/A/SDL \
    @executable_path/../Frameworks/SDL.framework/Versions/A/SDL \
$ for binary in Unvanquished.app/Contents/MacOS/*.{i386,dylib}; do
    dylibbundler -b -x $binary -d $dest/Unvanquished.app/Contents/libs/; done
$ cp /usr/lib/libGLEW.1.7.0.dylib ./Unvanquished.app/Contents/libs/libGLEW.1.7.0.dylib
$ chmod +w ./Unvanquished.app/Contents/libs/libGLEW.1.7.0.dylib
$ install_name_tool -id @executable_path/../libs/libGLEW.1.7.0.dylib \
$ install_name_tool -change /usr/lib/libGLEW.1.7.0.dylib \
    @executable_path/../libs/libGLEW.1.7.0.dylib \
$ cat > Unvanquished.app/Contents/Info.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
<plist version="1.0">

Note: ^d indicates pressing CtrlD on the keyboard.

The contents of the completed application bundle should look like this:

Bundle dir Mac OS X.png

Note: If you compiled SDL from source, you will not see a directory titled SDL.framework.


Visual Studio

CMake can generate Visual Studio projects for Unvanquished.

  1. Run the Visual_Studio32.bat batch script in your source directory by double-clicking it. Alternatively, you may use the Visual_Studio64.bat shell script if you have the Windows 7 SDK installed and a 64-bit system.
  2. Open build-32/Daemon.sln in Visual Studio 2010.
  3. In the two text boxes in the toolbar, select "Release" or "Debug" in the first one and Win32 in the second one
  4. Press F5 to build solution and run application, or just use Build → Build Solution to compile the code.

Important Notes

  • LLVM is disabled and does not work correctly with CMake generated Visual Studio projects.
  • ncurses is not supported under Visual Studio.
  • The path to the build folder must not have any spaces otherwise generation of QVMs will fail. See Issue 102.
  • Due to limitations with CMake, neither the startup project nor the working directory can be specified. These must be set manually to debug the client with Visual Studio:
    • Right click on client and select "Set as StartUp project".
    • Right click on client, select properties, select Debugging and set "Working Directory" to $(TargetPath)\...


It is possible to build Unvanquished with MinGW, although the process is rather arduous compared to Visual Studio or compiling for other platforms.


  • The easiest way to acquire and install MinGW is with the graphical mingw-get-inst installer.
  • When configuring the build with CMake, you will find that you will have to set a number of libraries manually. You can find precompiled DLLs for most of the dependencies; those that are not pre-compiled can be built with the corresponding USE_INTERNAL_ setting.
  • On Windows, SDL requires that the Direct X SDK can be installed. You may download the June 2010 release from Microsoft's site.
  • The build will fail during QVM compilation if your source or build directories contain spaces. This is due to a bug with lcc. If your home directory contains a space, you may want to create source and build directories at the root of one of your drives (e.g., C:\Unvanquished\Source and C:\Unvanquished\Build.)


The easiest way to get a build up (at the time of writing) is as follows:

Information 48x48.png


Although there are 64-bit binaries of most of the libraries required to build the game, these do not work with MinGW at present, so the following instructions all use the 32-bit binaries.

  1. Although there are binaries of gmp distributed with the source, they have are dependent on Visual Studio's implementations of _ftol2_sse and _alloca_probe_16. A fix may be found on Stack Exchange, but requires that Visual Studio be installed, which defeats the purpose of attempting to use MinGW to compile the source. You can build gmp yourself:
    1. Download and extract the latest version of the GNU MP Bignum Library (GMP). (You will need either cygwin with tar and bz2 installed or 7-zip to extract the archive.)
    2. Install the following Cygwin packages if you have not already:
      • binutils
      • gcc
      • gcc-g++
      • m4
      • make
    3. As part of the GMP compilation process, a file called gen-fib.c generates a table of numbers in the Fibonacci sequence. The generated file does not play nicely with Cygwin or MinGW, so you must fix it. Edit gen-fib.c, and at around line 100, change these lines
        for (i = 0; i < fnum; i++)
            printf ("  CNST_LIMB (0x");
            mpz_out_str (stdout, 16, f[i]);
            printf ("),  /* %d */\n", i-1);
        printf ("};\n");

      to look like this:

        for (i = 0; i < fnum; i++)
            printf ("  CNST_LIMB (0x");
            mpz_out_str (stdout, 16, f[i]);
            printf (")%c  /* %d */\n", (i == (fnum-1)) ? ' ' : ',', i-1);
        printf ("};\n");

      The patch file looks like this:

      @@ -100,7 +100,7 @@
             printf ("  CNST_LIMB (0x");
             mpz_out_str (stdout, 16, f[i]);
      -      printf ("),  /* %d */\n", i-1);
      +      printf (")%c  /* %d */\n", (i == (fnum-1)) ? ' ' : ',', i-1);
         printf ("};\n");
    4. Compiling with MinGW does not work, so you will need to compile with Cygwin. At the prompt:
      $ ./configure --disable-static --enable-shared
      $ make

      The --disable-static and --enable-shared flags configure GMP to build a DLL instead of a static library. You may optionally perform make install. Additional compilation instructions are available.

      If you experience difficulties with compilation and it appears that MinGW gcc is being detected by configure and not Cygwin gcc, you can try editing your PATH variable:

      $ export PATH=`echo $PATH | sed "s|/cygdrive/c/MinGW/bin:||"`

      Re-run configure and make afterwards.

  2. Download the latest stable version of SDL for Windows. Extract the archive and copy SDL.dll from it to the root of your build directory.
  3. Set the following CMake flags:
    Setting Description Type Value
    USE_INTERNAL_CRYPTO Use the provided copies of crypto libraries. BOOL true
    USE_INTERNAL_GLEW Use the provided copy of GLEW. BOOL true
    USE_INTERNAL_JPEG Use the provided copy of JPEG. BOOL true
    USE_INTERNAL_SDL Use the provided copy of SDL. BOOL true
    USE_INTERNAL_SPEEX Use the provided copy of Speex. BOOL true
    USE_INTERNAL_WEBP Use the provided copy of WebP. BOOL true
    USE_CURSES Enables/disables curses. BOOL false
    PNG_LIBRARY Path to the PNG library DLL. FILEPATH SourcePath/src/libs/libpng/libs/win32/libpng.lib
    PNG_PNG_INCLUDE_DIR Path to the PNG library header files. PATH SourcePath/src/libs/libpng
    FREETYPE_LIBRARY Path to the compiled FreeType library. FILEPATH SourcePath/src/libs/freetype/lib/freetype.lib
    FREETYPE_INCLUDE_DIR_freetype2 Path to the FreeType library header files. PATH SourcePath/src/libs/freetype/include/freetype2
    FREETYPE_INCLUDE_DIR_ft2build Path to the FreeType library file "ftbuild.h". FILEPATH SourcePath/src/libs/freetype/include/
    GMP_INCLUDE_DIR Path to the GMP library header files. PATH SourcePath/src/libs/gmp/include
    GMP_LIBRARY Path to the GMP library. FILEPATH path/to/compiled/gmp/.libs/cyggmp-10.dll
    ZLIB_INCLUDE_DIR Path to the zlib library header files. PATH SourcePath/src/libs/zlibwapi/include
    ZLIB_LIBRARY Path to the zlib library. FILEPATH SourcePath/src/libs/zlibwapi/lib/x32/zlib1.dll
    CURL_LIBRARY Path to the CURL library. FILEPATH SourcePath/src/libs/curl-7.21.6/lib/win32/release/libcurl.dll
    CURL_INCLUDE_DIR Path to the zlib library. PATH SourcePath/src/libs/curl-7.21.6/include/curl
    USE_OPENAL Enables/disables OpenAL support. BOOL false
    USE_CIN_THEORA Enables/disables Theora support. BOOL false
    USE_CIN_XVID Enables/disables Xvid support. BOOL false
    USE_CODEC_THEORA Enables/disables Ogg support. BOOL false
    SDL_LIBRARY The path to the SDL DLL. FILEPATH BuildPath/SDL.dll
    SDLMAIN_LIBRARY Enables/disables Ogg support. FILEPATH SourcePath/src/libs/libsdl/src/main/win32/SDL_win32_main.c

    Do note that CMake is slash-direction–agnostic; it can handle both forward- and backslashes on Windows.

    If you would like to compile a debug build, change CMAKE_RELEASE_TYPE from Release to Debug.

  4. Open SourcePath/CMakeLists.txt and edit the line
        set( OS_LIBRARIES m winmm ws2_32 psapi z )

    (around line 1040) to look like this:

        set( OS_LIBRARIES m winmm ws2_32 psapi )

    Also edit around line 1700:

    #Configure Download Script#
    if( NOT MSVC )

    to look like this:

    #Configure Download Script#
    if( NOT WIN32 )
  5. Open SourcePath/src/libs/libsdl/src/main/win32/SDL_win32_main.c and edit the lines:
    /* Include the SDL main definition header */
    #include "SDL.h"
    #include "SDL_main.h"

    to look like:

    /* Include the SDL main definition header */
    #include "../../../include/SDL.h"
    #include "../../../include/SDL_main.h"
  6. Open a command prompt and cd to your source directory.
  7. Run make:
    > mingw32-make

    If you would like verbose output, set the VERBOSE environment variable before running make.

    > set VERBOSE=1

    To make it easier to build the source, you can create a batch file (call it something like compile.bat) and place it in your build directory:

    @echo off
    set RETURN=compile
    	:: Thank you, Rob van der Woude:
    	:: (http://www.robvanderwoude.com/datetimentparse.php)
    	FOR /F "tokens=1,2,3 delims=:." %%A IN ("%Time%") DO (
    		SET /A HOURS   = 100%%A %% 100
    		SET /A MINUTES = 100%%B %% 100
    		SET /A SECONDS = 100%%C %% 100
    	SET /A TICKS=( %HOURS% * 3600 ) + ( %MINUTES% * 60 ) + %SECONDS%
    	:: mingw32-make clean
    	mingw32-make -j4
    	set RETURN=finish
    	GOTO get_time
    	ECHO Compilation took %MINUTES%m %SECONDS%s.
  8. Once compilation finishes, you will find that the game will fail to run due to DLL dependencies. To resolve these:
    • You will need to move INTERNAL_GLEW from the Release/ folder of the build directory to the root of the build directory.
    • You will need to place the following other DLLs in your build directory:
      • freetype6.dll
      • libbz2.dll
      • libcurl.dll
      • libogg.dll
      • libpng14-14.dll
      • libtheora.dll
      • libvorbis.dll
      • libvorbisfile.dll
      • msvcr100.dll
      • msvcr100d.dll
      • zlib1.dll
      • zlibwapi.dll
      The easiest way to obtain these DLLs is by copying them from the installation directory of an official release of Unvanquished.
    • You will need to copy your compiled DLL of GMP to your build directory. It may be found in path/to/compiled/gmp/.libs/cyggmp-10.dll.
    • As you compiled GMP with Cygwin, it in turn depends on cygwin1.dll, which may typically be found in C:\cygwin\bin\. Copy and paste it into your build directory.

    Once you have completed these steps, you should never have to do them again.


  • If you would like to use curses, try using PDCurses.


  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.


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.




$ sudo apt-get install libcurl4-gnutls-dev libfreetype6-dev libglew1.5-dev \
  libgmp3-dev libjpeg8-dev libncurses5-dev libogg-dev libopenal-dev \
  libpng12-dev libsdl1.2-dev libvorbis-dev zlib1g-dev nettle-dev \
  libwebp-dev libspeexdsp-dev libtheora-dev

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.

We currently provide a ready-to-use libwebp-dev in our Debian and Ubuntu repositories, alongside .debs of the game and server.

Actual dev package names may vary, e.g. libgmp-dev instead of libgmp3-dev and libglew-dev or libglew1.7-dev instead of libglew1.5-dev.

Since we have a debian directory in the source, you can also to check what's needed then install the listed packages (choosing from alternatives as needed):

$ cd /path/to/unvanquished
$ dpkg-checkbuilddeps
$ sudo apt-get install package(s)

If dpkg-checkbuilddeps produces no output, you have all necessary build dependencies. Also, debhelper's only needed if you're building .debs.


$ emerge curl freetype glew gmp jpeg ncurses libogg openal libpng libsdl libvorbis zlib


$ 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 speex-devel libvorbis-devel \

The latest version of WebP must be installed manually:

$ wget https://webp.googlecode.com/files/libwebp-0.2.1.tar.gz
$ tar xvzf libwebp-0.2.1.tar.gz
$ cd libwebp-0.2.1
$ ./configure && make
$ sudo make 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.

Next, configure the codebase.

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

Or, in Debian or Ubuntu, you can build a package (but you'll need to have devscripts and fakeroot installed):

$ 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:

$ sudo apt-get install cmake-qt-gui

With the qt4 USE flag enabled:

$ emerge cmake

Once installed, run with cmake-gui.

  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_OPENAL — If this is disabled, SDL is used instead for sound.
  • USE_CODEC_VORBIS — Disabling this will cause certain sound effects (those using the .ogg format) not to play. At present, this has only a minor impact on gameplay, but more and more sounds will likely use the format in the future.
  • 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.
  • USE_CIN_THEORA — Disabling this prevents videos from being recorded in Theora.
  • USE_CIN_XVID — Disabling this prevents videos from being recorded in Xvid.
  • USE_VOIP — Disabling this removes VOIP support. Alternatively enabling USE_INTERNAL_SPEEX will use the libraries distributed with Unvanquished for VoIP
  • USE_INTERNAL_CRYPTO — Enable this to use the crypto libraries provided by Unvanquished.


$ 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.

Acquiring the Game Files

Acquiring mandatory game files

The game files are not in the Git repository, and must be downloaded separately. This may be done on the command line or from your web browser. The downloads may be found on SourceForge.net. If you download the files from your browser, just download the files named "pak*.pk3", and save them to the data location for your system.

On Linux, this may be done as follows:

$ cd [path to Unvanquished installation or build]/main
$ for file in (PLACEHOLDER: new filesystem); do
if [ ! -e $file ]; then
wget -O $file "http://sourceforge.net/projects/unvanquished/files/Assets/$file/download"

On FreeBSD, using the sh shell:

$ cd [path to Unvanquished installation or build]/main
$ for file in (PLACEHOLDER: new filesystem); do
if [ ! -e $file ]; then
fetch -r -o $file "http://sourceforge.net/projects/unvanquished/files/Assets/$file/download"

On Mac OS X:

$ cd ~/Library/Application\ Support/Unvanquished/main
$ for file in (PLACEHOLDER: new filesystem); do
if [ ! -e $file ]; then
curl -L "http://sourceforge.net/projects/unvanquished/files/Assets/$file/download" > $file

Linux users may also use the download-pk3.sh script that is distributed with the source code, which requires that curl be installed:

$ cd [path to Unvanquished source code]
$ mkdir -p ~/.Unvanquished/main
$ ./download-pk3.sh ~/.Unvanquished/main

Downloading the map pack

The map pack exists only for convenience; if you do not download the map pack, Unvanquished will automatically download maps as needed when you attempt to play online.

To download the map pack on Linux:

$ wget -O maps.7z "http://sourceforge.net/projects/unvanquished/files/Map%20Pack/maps.7z"; done

To download the map pack on Mac OS X:

$ curl -L "http://sourceforge.net/projects/unvanquished/files/Map%20Pack/maps.7z" > maps.7z; done

Note that you will need to unzip the map pack on either system as it is compressed with LZMA. Mac users can use the Unarchiver. Uncompressing the archive on Linux is highly dependent on your distribution.

Verifying the Files

Download the latest MD5 hash file and save it to your system's data location.

On systems with the md5 command (Mac OS X):

$ cd ~/Library/Application\ Support/Unvanquished/main
$ cat md5sums0.37 | while read line; do
file="`echo "$line" | sed -E "s/^[a-fA-F0-9]+ +\*?//"`"
if [ -e "$file" ]; then
if [ `md5 -r "$file" | cut -d\  -f1` = "`echo "$line" | cut -d\  -f1`" ]
then echo "File \"$file\" appears okay."
else echo "File \"$file\" is corrupt"'!' >&2
fi; fi; done

On systems with the md5sum command (most Linux distributions):

$ cd /path/to/data/files
$ md5sum -c md5sums0.37 2>&1 | grep -v "open or read\|file or directory"

The grep invocation is used to strip output complaining about missing files.

Any files that are found to be corrupt should be replaced; just download a new copy of the affected file(s).


CMake cannot locate Newton

If CMake cannot find Newton, you'll need to set it up yourself.

It should be in /path/to/Unvanquished/src/libs/libnewton/libs/your_os/libNewton.so. Be sure to replace your_os with the proper directory name.

Use CMake as before to change the NEWTON_LIBRARY build setting to the said path:

  1. Start the CMake configurator:
    $ ccmake ..
  2. Scroll down and highlight NEWTON_LIBRARY.
  3. Press Enter to begin editing and input in the path.
  4. Press C to configure and G to generate the new makefiles.
  5. Press Q to quit.
  6. Recompile the source:
    $ make

The C Compiler is not able to compile a simple test program

When attempting to generate a solution for Xcode CMake fails with the following error

 -- Check for working C compiler using: Xcode -- broken
 CMake Error at /Applications/CMake 2.8-8.app/Contents/share/cmake-2.8/Modules/CMakeTestCCompiler.cmake:52 (MESSAGE):
  The C compiler "/usr/bin/gcc" is not able to compile a simple test program.
   It fails with the following output:
    Change Dir: /Users/danielmaloney/Documents/Unvanquished/build-xcode/CMakeFiles/CMakeTmp
   Run Build Command:/Applications/CMake\ 2.8-8.app/Contents/bin/cmakexbuild
   -project CMAKE_TRY_COMPILE.xcodeproj build -target
   cmTryCompileExec1400153232 -configuration Debug
   Error: No developer directory found at /Developer.  Run
   /usr/bin/xcode-select to update the developer directory path.


   CMake will not be able to correctly generate this project.
 Call Stack (most recent call first):
   CMakeLists.txt:19 (project)

This is due to Xcode 4.3 having a different directory structure to previous versions. Simply running the following command will correct this error:

sudo /usr/bin/xcode-select -switch /Applications/Xcode.app/Contents/Developer/