[[TOC]]
'''NOTE: The build system has changed since Alpha 7 and the instructions are now subtly different. If you want to build Alpha 7 or previous versions of the game, use the [http://trac.wildfiregames.com/wiki/BuildInstructions?version=140 older version] of this page.'''
This page describes how to get the very latest unstable version of the code. Unless you want to actively follow and contribute to development, you probably want the [LatestRelease latest relatively-stable release] instead.
The current release of the game is aimed at developers and not at 'normal' users. As such, the following instructions assume a reasonable level of technical proficiency. If you encounter difficulties, please post on the [http://www.wildfiregames.com/forum/index.php?showforum=312 forum].
== General prerequisites ==
You'll need:
* An adequately high-spec computer:
* At least 5GB of free disk space
* Preferably at least 1GB of RAM for compiling
* Intel x86-compatible CPU, 32- or 64-bit, multiple cores will help compile faster
* Modern graphics hardware is also recommended, though the game can run (slowly) on fairly old devices (!GeForce 4, Intel 945GM, etc)
* One of the following operating systems:
* [#Windows Windows] (2000 or newer)
* [#Linux Linux]
* [#OSX OS X] (currently 10.6 or newer)
* [#FreeBSD FreeBSD] (only experimental support at this time)
* Up-to-date system software (Windows service packs, graphics driver updates, etc)
* Some technical proficiency. We try to make the build process as smooth and painless as possible, but it's designed to be followed by programmers - if you just want to play the game, wait for a pre-packaged installer instead.
== Windows ==
Windows 7, Vista and XP are the main supported versions; 2000 should work too but is rarely tested. Visual C++ 2010 and 2008 are supported. Visual C++ 2005 may also work given a sufficiently modern Platform SDK. Only 32-bit builds are supported (though they can be compiled and run on 64-bit Windows). We have noticed occasional trouble with the free Express Editions; if possible, please consider acquiring the full version (e.g. via university programs). In particular, failures of the built-in self-test test_wdbg_sym.h seem to occur with VC2008 EE but not VC2008 nor VC2010 (c.f. #884).
=== Acquiring the code ===
The game's code, data and build environment are stored on a Subversion server. The recommended way to get an up-to-date copy is with TortoiseSVN:
* Download and install [http://tortoisesvn.net/ TortoiseSVN]. (Make sure you reboot when it asks you to.)
* Use TortoiseSVN to check out `http://svn.wildfiregames.com/public/ps/trunk/`. This may take a while, and will use around 1.2GB of disk space. If there are errors during the checkout, use TortoiseSVN's "update" to resume downloading.
The [http://tortoisesvn.net/docs/release/TortoiseSVN_en/index.html TortoiseSVN manual] has information on [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-checkout.html checking out], as well as [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-update.html updating] and [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-patch.html creating patches].
(This is the read-only public SVN URL. If you have commit access, you need to use `http://svn.wildfiregames.com/svn/ps/trunk/` instead.)
=== Setting up the build environment ===
The game must be compiled with Microsoft Visual C++. If you already have Visual C++ 2005 or 2008 installed, make sure you have SP1 and then continue. Otherwise, you can get the free Express edition:
* [http://www.microsoft.com/express/Downloads/#2010-Visual-CPP Visual C++ 2010 Express Edition] is recommended.
* Or download and install [http://www.microsoft.com/express/Downloads/#2008-Visual-CPP Visual C++ 2008 Express Edition].
* If you have the old VC++ 2005 Express, you need to install the separate [http://www.microsoft.com/express/2005/platformsdk/default.aspx Platform SDK] (steps 1-3).
The Visual Studio project/solution files are automatically generated from the source files:
* Run `build/workspaces/update-workspaces.bat`.
* Open `build/workspaces/vc2010/pyrogenesis.sln`. (Use the `vc2005` directory for VC++ 2005 or the `vc2008` directory for VC++ 2008.)
=== Optimised builds ===
Make sure to select the "Release" configuration to build an optimised, more playable version of the game (the target will be `pyrogenesis.exe`). The "Debug" configuration can be more useful for debugging but has significantly reduced performance (the target will be `pyrogenesis_dbg.exe`). Both "Release" and "Debug" builds include debug symbols, see [wiki:DebuggingOnWindows Debugging on Windows] for more details on debugging.
Now you should be able to build the code from within Visual Studio, using "Build Solution" (F7).
=== Building Atlas ===
If you also wish to test the [wiki:Atlas_User%27s_Guide Atlas Scenario Editor] or [wiki:Actor_Editor Actor Editor] tools, you will need to download and build the [http://www.wxwidgets.org/ wxWidgets] library separately (see `libraries\wxwidgets\README.txt` for details), then supply the `--atlas` option when running `update-workspaces.bat`. Atlas projects will now be included when you open `pyrogenesis.sln` in Visual C++.
=== Running ===
Run the game with F5 inside Visual Studio (assuming "pyrogenesis" is set as the startup project, which is default). If you want to run it outside the debugger, run `binaries/system/pyrogenesis_dbg.exe`.
To run the automated tests, run the "test" project. (Right click on "test" and "set as !StartUp Project" and F5; or right click, "Debug", "Start new instance"). In VS's debug output window, ignore any "first-chance exception" messages; it should say ".......OK!" if it succeeded.
=== Keeping up to date ===
After you've set everything up, the process for staying up to date is:
* [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-update.html Update] the root directory of the checkout.
* Close the solution in Visual Studio if you've got it open. Run `update-workspaces.bat` again. (This is only needed if any source files have been added or removed. If you forget to run this, you'll probably get build errors about missing symbols.)
* Build again.
== Linux ==
0 A.D. should work on any reasonably modern Linux distro, on x86 and x86_64 (amd64). The details depend on exactly which distro you use.
=== Dependencies ===
First you need to install various standard tools and development libraries:
* GCC (at least 4.0, preferably 4.3 or later)
* Subversion (or git if you want to use the Git mirror; see below)
* SDL
* Boost
* zlib
* libpng
* libxml2
* OpenGL
* OpenAL
* zip (needed by spidermonkey)
* libogg
* libvorbis
* libcurl
* Gamin (FAM should work too, but is considered deprecated)
* CMake
* To compile editing tools (enabled by default; pass the flag `--disable-atlas` to `update-workspaces.sh` to disable):
* wxWidgets (packages are probably called wxgtk)
* To use shared system libraries instead of bundled copies (default) of libraries (pass the flag `--with-system-$COMPONENT` to `update-workspaces.sh` to use the non-bundled copy):
* ENet 1.3 (`--with-system-enet`)
* [http://code.google.com/p/nvidia-texture-tools NVTT] (`--with-system-nvtt`)
* [https://developer.mozilla.org/en/SpiderMonkey/1.8.5 SpiderMonkey 1.8.5] (`--with-system-mozjs185`)
==== Debian/Ubuntu ====
Install the dependencies with:
{{{
#!html
sudo apt-get install subversion build-essential cmake libsdl1.2-dev zlib1g-dev libpng12-dev libjpeg8-dev libgamin-dev libwxgtk2.8-dev libboost-dev libboost-signals-dev libboost-filesystem-dev libopenal-dev libalut-dev libvorbis-dev libogg-dev libxml2-dev libcurl4-gnutls-dev zip libenet-dev libmozjs185-dev
}}}
* You can also use `libcurl4-openssl-dev` instead of `libcurl4-gnutls-dev` (it's not possible to install both at once).
==== Mandriva ====
Install the dependencies with:
{{{
#!html
urpmi gcc-c++ python subversion zip cmake boost-devel fam-devel libcurl-devel libjpeg-devel libpng-devel libvorbis-devel libxml2-devel libwxgtku2.8-devel openal-soft-devel
}}}
==== Fedora ====
Install the dependencies with:
{{{
#!html
su -c 'yum -y install gcc-c++ python subversion zip cmake boost-devel fam-devel libcurl-devel libjpeg-devel libpng-devel libvorbis-devel libxml2-devel openal-soft-devel pkgconfig SDL-devel wxGTK-devel'
}}}
==== OpenSUSE ====
Install the dependencies with:
{{{
#!html
sudo zypper install gcc-c++ python subversion zip cmake boost-devel fam-devel libcurl-devel libjpeg-devel libpng-devel libvorbis-devel libxml2-devel openal-soft-devel pkg-config wxGTK-devel libSDL-devel
}}}
Users of OpenSUSE 11.4 and later should install the wxWidgets-devel package instead of wxGTK-devel.
=== Getting the code ===
0 A.D. is primarily developed on SVN. To checkout the latest code from SVN, run this command:
{{{
svn co http://svn.wildfiregames.com/public/ps/trunk/ 0ad
}}}
Sometimes SVN stops before it has downloaded all files. You should check that it outputs something like `at revision rXXXX`. Otherwise run
{{{
svn up 0ad
}}}
There is also a Git mirror, which may be slightly less up-to-date but usually offers faster downloads. To use the Git mirror, use this command instead:
{{{
git clone https://github.com/0ad/0ad.git
}}}
=== Building ===
Compile the code with:
{{{
#!sh
cd 0ad/build/workspaces
./update-workspaces.sh -j3
cd gcc
make -j3
}}}
* '''-j3''' gives the number of parallel builds to run, and should typically be one plus the number of CPU cores available.
* The '''Release''' mode builds (which are the default) are more optimised, but are harder to debug. Use `make config=debug` (and run `pyrogenesis_dbg`) if you need better debugging support.
If you encounter any build errors, review the [http://trac.wildfiregames.com/report existing bug reports], check the [#Knownproblemsandsolutions known problems section] or please file a [http://trac.wildfiregames.com/newticket new bug in the tracker].
=== Testing ===
Run the automated tests to verify that everything works as expected like this:
{{{
binaries/system/test
}}}
=== Running ===
If everything went well, compiling the code worked and all tests passed, it's finally time to run the game:
{{{
binaries/system/pyrogenesis
}}}
=== Keeping up to date ===
If you already checked out the code and only want to update and rebuild it, you may find it helpful to save the lines below to a script called e.g. `rebuild.sh`, place it in your 0ad directory, make it executable and run it.
{{{
#!sh
#!/bin/sh
set -e
svn up
cd build/workspaces
./clean-workspaces.sh
./update-workspaces.sh
cd gcc
make clean
make -j3
}}}
If you just edited one source code file and want to rebuild, you can usually get away with:
{{{
make -j3
}}}
If you want to rebuild quickly after updating from SVN, you can usually get away with:
{{{
#!sh
svn up
cd build/workspaces
./update-workspaces.sh
cd gcc
make -j3
}}}
If the `make` line gives errors, you may need to run `make clean` before it. If the `update-workspaces.sh` gives errors, you may need to run `clean-workspaces.sh` before it.
== OS X ==
The process on OS X is similar to Linux:
* If you're using Lion 10.7.3 or later, Apple has made their ''Command Line Tools for Xcode'' package freely available, as a separate download. '''It does not include or require Xcode.''' If you don't want the Xcode IDE, it's recommended to install only this package from [https://developer.apple.com/downloads/index.action Apple Developer Downloads]. You need a free Apple ID to access the download. If you already have Xcode 4.3+, you can download the command line tools from the [https://developer.apple.com/library/IOs/#recipes/xcode_help-documentation_preferences/DownloadingandInstallingXcodeComponents/DownloadingandInstallingXcodeComponents.html download preferences].
* If you're using Snow Leopard or Lion 10.7.2 or earlier, you'll probably need to install Xcode to get the command line tools (or you can try [https://github.com/kennethreitz/osx-gcc-installer/ OSX GCC Installer]):
* If available, use your Mac OS X install DVD which saves downloading 1.72+ GB.
* Visit [https://developer.apple.com/downloads/index.action Apple Developer Downloads] (logging in with your free Apple ID) and download the latest Xcode version for your OS. Version 4.x is required for Lion, while version 3.x is required for Snow Leopard. It's very important you install the correct version.
* The latest version of Xcode is also available for free from the [http://www.apple.com/mac/app-store/ Mac App Store], you'll need Snow Leopard 10.6.6 or later to access the App Store. ''Note: if you download the app, it is only the installer for Xcode. You need to open it and run the "Install Xcode" app.''
* Install [http://www.macports.org/install.php MacPorts]. This is the easiest way to install all the dependencies needed by the game.
* `sudo port install` the following packages :
* boost
* cmake
* libenet
* libsdl
* libvorbis
* libxml2
* curl
* wxWidgets-devel (required for building Atlas, only the 2.9.x branch will work on 64-bit Macs)
* subversion (the default version on 10.5 seems to cause checksum mismatch errors)
* Now follow the [#Gettingthecode same instructions] as for Linux above, starting from the `svn co`.
* Newer versions of Xcode no longer include the command line tools by default, you need to install them as described above. Additionally, the command line tools package no longer includes GCC but it does include LLVM-GCC which is compatible. If you get errors during the build like "C compiler cannot create executables" then you probably have the newer command line tools with LLVM. The following command should fix it:
{{{
export CC=gcc CXX=g++
}}}
=== Compiling with GCC 4.2 or 4.3 under OS X ===
If you get errors compiling with OS X's default version of GCC (4.0.1), you can try compiling with GCC 4.2 or 4.3. On Snow Leopard, running
{{{
export CXX=/usr/bin/g++-4.2
}}}
before compiling the game may be sufficient. Leopard does not ship with a recent version of GCC, so you first have to get them from !MacPorts and then patch some system libraries:
* `sudo port install gcc42 gcc43 gcc_select`
* Select GCC 4.2 or 4.3: `sudo gcc_select mp-gcc42` or `sudo gcc_select mp-gcc43`
* You may need to patch Apple's OpenAL (`/System/Library/Frameworks/OpenAL.Framework/Headers/alc.h`: replace all `ALCvoid` by `void`, except the first one which is a `typedef`). (GCC >=4.2 is stricter about parameters invalidly typedefed to void in C++.)
* If you're under Tiger, you'll certainly have to edit `build/premake/premake4.lua` to get rid of the `-fstack-protector-all` line: see the [#Knownproblemsandsolutions known problems section].
* Then, restart the compilation starting from `./update-workspace.sh`
== FreeBSD ==
'''Note: this is a work in progress and should be considered experimental. That means don't try it unless you "know what you're doing" :)'''
* Install the following ports or packages (using `pkg_add -r`):
* sdl
* boost-libs
* png
* execinfo
* libxml2
* libGL
* openal
* zip
* libogg
* libvorbis
* curl
* gamin
* cmake
* wxgtk2-unicode - required to build Atlas tools
* subversion - note the latest version for 8.2 Release is 1.6
* Note: GCC 4.2.1 and zlib should already be installed by default
* Obtain the game's source code as [#Gettingthecode described above] for Linux.
* TODO: Fix missing ecvt() and get premake to generate a proper build/gmake.unix/Makefile, or maybe create a build/gmake.bsd/? (the only difference is it tries to link libdl, which doesn't exist on FreeBSD)
* If building Atlas, you need to set the `WX_CONFIG` variable, because `wx-config` has a different name on FreeBSD. For example, you'd run this command if you built the wxGTK 2.8 package with unicode support:
{{{
export WX_CONFIG=wxgtk2u-2.8-config
}}}
if not correct, you will get errors about missing "wx/*.h" includes. You can skip building Atlas altogether (and the wxWidgets dependency) by later passing the `--disable-atlas` option to `update-workspaces.sh`.
* You'll have to set this variable every time you run `update-workspaces.sh`, so it may be most convenient to put these commands into another shell script.
* Note: FreeBSD's `make` command is actually Berkeley [http://www.freebsd.org/cgi/man.cgi?query=make make], which is similar to but different than GNU make. Our build scripts will detect if you're on FreeBSD and use the `gmake` command instead. If for some reason this isn't correct, you can set the `MAKE` environment variable with the path and name of the correct GNU make.
* Follow the [#Building build] instructions above for Linux.
== Known problems and solutions ==
* If you get linker errors like '''`multiple definition of '(anonymous namespace)::_1'`''', particularly when using GCC 4.1, try running `./update-workspaces.sh --without-pch` and then `cd gcc; make clean` and rebuild.
* If you get linker errors like '''`/usr/bin/ld: Undefined symbols: ___stack_chk_fail, ___stack_chk_guard`''', this comes from using a libc that is not glibc >=2.4. Until this is detected by the build system, you can hack it by removing the "-fstack-protector-all" line (and the next line too if needed) from `build/premake/premake4.lua`
* If you get linker errors like '''`cannot find -lboost_signals-mt`''' (particularly users of Slackware 13.37 and -current), edit the file `build/premake/extern_libs4.lua` and remove the `-mt` suffixes from the boost definitions in line 221 and line 230, and then run `update-workspaces.sh` again. It should look like
{{{
unix_names = { "boost_filesystem", "boost_system" },
}}}
for line 221 and
{{{
unix_names = { "boost_signals" },
}}}
for 230 respectively.
* If !SpiderMonkey has compile errors during `update-workspace.sh`, throwing errors like '''`'r13' is not a member of 'JSC::X86Registers'`''', then you likely have a 32-bit userspace with a 64-bit kernel. Run
{{{
export CHOST=i386-pc-linux-gnu
}}}
before compiling.
* If the !SpiderMonkey build fails with errors like:
{{{
Can't open perl script "../build/autoconf/acoutput-fast.pl": No such file or directory
not updating unwritable cache ./config.cache
creating ./config.status
creating Makefile
sed: can't read ../Makefile.in: No such file or directory
...
}}}
then you are likely using a build directory with spaces in its path. !SpiderMonkeys build system isn't designed to cope with spaces in the source path (see #916). Rename your build directory so that it doesn't contain any spaces.
== Creating Linux packages ==
If you want to create packages for a Linux distribution, see the current [https://build.opensuse.org/package/files?package=0ad&project=games 0ad] and [https://build.opensuse.org/package/files?package=0ad-data&project=games 0ad-data] packages on OBS for examples (especially the `.spec` and `debian.rules` files).