Compiling the source

From Unvanquished
Jump to: navigation, search

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

Dependencies

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:

HomeBrew

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

This is more time consuming than other methods but might be useful if you need more control over your libraries.

JPEG
$ 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
Ogg
$ 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
Vorbis
$ 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
WebP

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. 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 CMake did not find your jpeg headers for some reason, set JPEG_INCLUDE_DIR to /path/to/Unvanquished/src/libs/jpeg.
    2. 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.

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

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.

Manually

Information 48x48.png

Important

Please be aware that these instructions are very much out of date, and may not work. Also note that the dynamic library bundler does not work as intended and although you will be able to run your build on your machine, it will most likely not work on other machines. It is strongly suggested that you compile the source using Xcode.

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 > \
   dylibbundler0.4.1.zip
$ 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 \
    Unvanquished.app/Contents/Frameworks/SDL.framework/Versions/A/SDL
$ install_name_tool -change @rpath/SDL.framework/Versions/A/SDL \
    @executable_path/../Frameworks/SDL.framework/Versions/A/SDL \
    Unvanquished.app/Contents/MacOS/daemon.i386
$ install_name_tool -change @rpath/SDL.framework/Versions/A/SDL \
    @executable_path/../Frameworks/SDL.framework/Versions/A/SDL \
    Unvanquished.app/Contents/MacOS/librendererGLi386.dylib
$ install_name_tool -change @rpath/SDL.framework/Versions/A/SDL \
    @executable_path/../Frameworks/SDL.framework/Versions/A/SDL \
    Unvanquished.app/Contents/MacOS/librendererGL3i386.dylib
$ 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 \
    ./Unvanquished.app/Contents/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 \
    ./Unvanquished.app/Contents/MacOS/daemon.i386
$ cat > Unvanquished.app/Contents/Info.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
          "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>CFBundleName</key>
	<string>Unvanquished</string>
	<key>CFBundleDisplayName</key>
	<string>Unvanquished</string>
	<key>CFBundleExecutable</key>
	<string>daemon.i386</string>
	<key>CFBundleIconFile</key>
	<string>Unvanquished.icns</string>
	<key>CFBundleIdentifier</key>
	<string>net.Unvanquished</string>
	<key>CFBundleInfoDictionaryVersion</key>
	<string>6.0</string>
	<key>CFBundlePackageType</key>
	<string>APPL</string>
	<key>CFBundleShortVersionString</key>
	<string>0.4.0</string>
	<key>CFBundleVersion</key>
	<string>0.4.0</string>
</dict>
</plist>
^d

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.

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 directories such as main and src), and the build directory as a subdirectory of the source directory named build.
  3. Open build/Daemon.sln in Visual Studio 2013.
  4. In the two text boxes in the toolbar, select "Release" or "Debug" in the first one and Win32 in the second one
  5. Use Build → Build Solution to compile the code (or just press F5 to build and run).

Important Notes

  • ncurses is not supported under Visual Studio.
  • 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 build Unvanquished with MinGW.

Notes

  • The easiest way to acquire and install MinGW is with the graphical mingw-get-inst installer. At a minimum, you will need to install the C and C++ compilers.
  • 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.

Instructions

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

Information 48x48.png

Note

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. Open a command prompt and cd to your source directory.
  2. 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
    
    :get_time
    	:: 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%
    	GOTO %RETURN%
    
    :compile
    	SET START_TICKS=%TICKS%
    
    	SET VERBOSE=1
    	:: mingw32-make clean
    	mingw32-make -j4
    
    	set RETURN=finish
    	GOTO get_time
    
    :finish
    	SET /A COMPILE_TIME=%TICKS% - %START_TICKS%
    	SET /A MINUTES=%COMPILE_TIME% / 60
    	SET /A SECONDS=%COMPILE_TIME% %% 60
    	ECHO.
    	ECHO Compilation took %MINUTES%m %SECONDS%s.
    	PAUSE
    
  3. Once compilation finishes, you may find that the game will fail to run due to DLL dependencies. To resolve these:
    • The following DLLs need to be in the same directory as the executable. They should be copied into the appropriate build directory automatically.
      • freetype6.dll
      • libcurl.dll
      • libpng14-14.dll
      • zlib1.dll
      If the renderer's DLL dependencies are not met, you will be informed that the game failed to load a renderer. If you receive an error stating that the application failed to start at all, then you are likely missing some version of the Microsoft Visual C runtime redistributable.

      You may find that you also need these DLLs (if you configured your build differently):

      • libbz2.dll
      • libogg.dll
      • libtheora.dll
      • libvorbis.dll
      • libvorbisfile.dll
      • msvcr100.dll
      • msvcr100d.dll
      • zlibwapi.dll

      The easiest way to obtain these DLLs is by copying them from the installation directory of an official release of Unvanquished.

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

Notes

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

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

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-turbo8-dev libpng-dev libwebp-dev \
  libogg-dev libvorbis-dev libtheora-dev libopusfile-dev \
  libgeoip-dev libfreetype6-dev \
  python-yaml python-jinja2


If libsdl2-dev isn't available, you can use libsdl1.2-dev instead.

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.

Actual dev package names may vary, e.g. libgmp3-dev instead of libgmp-dev and libglew1.7-dev instead of libglew-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.

Fedora

(This was tested to work on fedora 22 workstation)

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

Gentoo

$ emerge curl freetype glew gmp jpeg ncurses libogg openal libpng libsdl libvorbis 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 speex-devel libvorbis-devel \
  libtheora-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.

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

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:

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.
  • USE_GEOIP — Disabling this will make the game unable to locate players from their ip address.

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.

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-pk3.sh script that is distributed with the source code, which requires that curl be installed:

$ cd path/to/unvanquished/build
$ mkdir -p pkg
$ ../download-pk3.sh pkg

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

Errors

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/