[[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: * Install Apple's XCode for your system: see your Mac OS X install DVD or go to [http://connect.apple.com Apple's Developer Connection Site]. This provides the necessary tools to compile programs. For Leopard, you must install XCode >= 3.1 from the ADC site else some components will not compile. * You may also need the [http://connect.apple.com/cgi-bin/WebObjects/MemberSite.woa/wa/getSoftware?bundleID=20719 Java Developer Package]. * 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) * xercesc3 (required for building Atlas when running update-workspaces with "--aoe3ed") * subversion (the default version on 10.5 seems to cause checksum mismatch errors) * Now follow the same instructions as for Linux above, starting from the `svn co`. === 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/premake.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).