[[TOC]] 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 [http://play0ad.com/download 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]. [[br]] == General prerequisites == You'll need: * An adequately high-spec computer: * At least 5GB of free disk space * At least 1GB of RAM for compiling * 32 or 64-bit x86-compatible CPU, or an ARMv5+ processor * 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] (XP or newer) * [#Linux Linux] * [#OSX OS X] (preferably 10.7/Lion or newer) * [#BSD FreeBSD/OpenBSD] (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. [[br]] ---- == Windows == The main supported versions are: * Windows 8 * Windows 7 * Windows Vista * Windows XP Windows 2000 is not currently supported, see #2417. The main supported IDEs are: * Visual C++ 2012 * Visual C++ 2010 * Visual C++ 2008 Visual C++ 2013 is not supported yet, due to missing Boost libs (see #2271). Visual C++ 2005 is also not supported (#1951). '''Important notes:''' * 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; 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 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++ 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]. The Visual Studio project/solution files are automatically generated from the source files: * Run [source:/ps/trunk/build/workspaces/update-workspaces.bat build/workspaces/update-workspaces.bat]. * Open `build/workspaces/vc2010/pyrogenesis.sln`. (Use the `vc2008` directory for VC++ 2008; use the `vc2012` directory for VC++ 2012.) === Build configuration === 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:Debugging] and [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_Manual 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 [source:/ps/trunk/libraries/wxwidgets/README.txt 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. [[br]] ---- == 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: * Boost (at least 1.40 since r15173) * CMake (only needed if you use bundled NVTT) * GCC (at least 4.4, required by SpiderMonkey) * libcurl * libenet (1.3, the older 1.2 is not compatible) * libgloox (needed for the lobby; at least 1.0.9, previous versions are know to have connection problems; pass `--without-lobby` to `update-workspaces.sh` to exclude the lobby) * libicu * libjpeg * libnspr4 * libogg * libpng * libvorbis * libxcursor * libxml2 * miniupnpc (at least 1.6) * OpenAL * OpenGL * SDL (2.0 version is also experimental supported when passing `--with-sdl2` to `update-workspaces.sh`) * Subversion (or git if you want to use the Git mirror; see below) * zlib 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): * [https://developer.mozilla.org/docs/SpiderMonkey/24 SpiderMonkey 24] (`--with-system-mozjs24`) * [http://code.google.com/p/nvidia-texture-tools NVTT] (`--with-system-nvtt`) For a list of all options to `update-workspaces.sh` see [wiki:premake premake]. ==== Debian / Ubuntu ==== * On **Debian 8/jessie or Ubuntu 14.04/trusty or later** install the required dependencies with: {{{ #!sh sudo apt-get install build-essential libboost-dev libboost-filesystem-dev \ libcurl4-gnutls-dev libenet-dev libgloox-dev libicu-dev libjpeg-dev \ libminiupnpc-dev libmozjs-24-dev libnvtt-dev libogg-dev libopenal-dev \ libpng-dev libsdl-dev libvorbis-dev libwxgtk3.0-dev libxcursor-dev \ libxml2-dev subversion zlib1g-dev }}} * With these dependencies you have to run: * `./update-workspaces.sh --with-system-nvtt --with-system-mozjs24` * To avoid useless warnings when using system mozjs24 you could fix mozjs24 headers with: {{{ sudo perl -i -pe 's/(^#elif _MSC_VER >= 1600).*/#elif defined(_MSC_VER) && _MSC_VER >= 1600/' /usr/include/mozjs-24/mozilla/NullPtr.h }}} * On systems **earlier than Debian 8/jessie and Ubuntu 14.04/trusty**: * you should run `update-workspace.sh` with `--without-miniupnpc` if you don't have `libminiupnpc-dev` >= 1.6; * you should replace `libwxgtk3.0-dev` with `libwxgtk2.8-dev`; * you should replace `libmozjs-24-dev` with `libnspr4-dev` and run `update-workspace.sh` without `--with-system-mozjs24`. * When not using system nvidia-texture-tools, `libnvtt-dev` can be omitted, but `cmake` is needed to build the bundled NVTT. * You can also use `libcurl4-openssl-dev` instead of `libcurl4-gnutls-dev` (it's not possible to install both at once), but [http://lintian.debian.org/tags/possible-gpl-code-linked-with-openssl.html note that openssl is not GPL compatible and the resulting binaries could not be redistributed]. ==== Mandriva ==== Install the dependencies with: {{{ #!sh urpmi gcc-c++ python subversion zip cmake boost-devel libcurl-devel \ libenet-devel libgloox-devel libjpeg-devel libpng-devel libvorbis-devel \ libxml2-devel libwxgtku2.8-devel openal-soft-devel libicu-devel }}} ==== Fedora ==== Install the dependencies with: {{{ #!sh su -c 'yum -y install gcc-c++ python subversion zip cmake boost-devel \ libcurl-devel enet-devel libjpeg-devel libpng-devel libvorbis-devel \ libxml2-devel openal-soft-devel pkgconfig SDL-devel wxGTK-devel \ gloox-devel libicu-devel miniupnpc-devel' }}} ==== openSUSE ==== Install the dependencies with: {{{ #!sh sudo zypper install gcc-c++ python subversion zip cmake boost-devel \ libcurl-devel libenet-devel libjpeg-devel libpng-devel libvorbis-devel \ libxml2-devel openal-soft-devel pkg-config wxGTK-devel libSDL-devel \ gloox-devel libicu-devel miniupnpc-devel }}} Users of openSUSE 11.4 and later should install the wxWidgets-devel package instead of wxGTK-devel. ==== !ArchLinux ==== {{{ #!sh pacman -S libgl boost cmake gcc curl enet gloox libogg libpng libvorbis libxcursor libxml2 miniupnpc patch sdl subversion zip zlib icu }}} === Getting the code === 0 A.D. is primarily developed on SVN. To checkout the latest code from SVN, run this command: {{{ #!sh svn co http://svn.wildfiregames.com/public/ps/trunk/ 0ad }}} '''Note:''' Sometimes SVN stops before it has downloaded all files. You should check that it outputs something like `at revision rXXXX`. Otherwise run {{{ #!sh 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: {{{ #!sh 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. See [wiki:Debugging] for more details. 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: {{{ #!sh binaries/system/test }}} === Running === If everything went well, compiling the code worked and all tests passed, it's finally time to run the game: {{{ #!sh binaries/system/pyrogenesis }}} === Keeping up to date === 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. == Creating Linux packages == If you want to create packages for a Linux distribution see the current [http://anonscm.debian.org/viewvc/pkg-games/packages/trunk/0ad/debian/ 0ad] and [http://anonscm.debian.org/viewvc/pkg-games/packages/trunk/0ad-data/debian/ 0ad-data] packages on OBS for examples (especially the `control` and `rules` files). [[BR]] ---- == OS X == The process on OS X is similar to Linux: * Obtain the command line tools: * 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: * 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.'' * If you want to build a distributable app bundle as described below, you will need Xcode. * '''Note:''' As of Mavericks (10.9) and Xcode 5, Apple [https://developer.apple.com/library/mac/releasenotes/DeveloperTools/RN-Xcode/xc5_release_notes/xc5_release_notes.html#//apple_ref/doc/uid/TP40001051-CH2-SW302 no longer supports] llvm-gcc, instead it is required to use clang. Additionally, the default C++ library is now libc++ instead of libstdc++. If you've upgraded and previously built the game, you should pass the `--force-rebuild` flag to `build-osx-libs.sh`. * '''Note:''' As of Alpha 16, the game uses SpiderMonkey 24, which no longer supports gcc 4.2.x including llvm-gcc previously bundled with Xcode. The game can no longer be built on OS X Leopard (10.5), and there is a !SpiderMonkey [https://bugzilla.mozilla.org/show_bug.cgi?id=862657 bug] that breaks the build on Snow Leopard (10.6) with Xcode 3.2.6. * '''Note: CMake is a required dependency.''' You can download a prebuilt OS X package [http://www.cmake.org/cmake/resources/software.html here]. If prompted, install the command line CMake tools to the default location. * Obtain the game's source code: * 0 A.D. is primarily developed on SVN. To checkout the latest code from SVN, run this command: {{{ #!sh svn co http://svn.wildfiregames.com/public/ps/trunk/ 0ad }}} '''Note:''' Sometimes SVN stops before it has downloaded all files. You should check that it outputs something like `at revision rXXXX`. Otherwise run {{{ #!sh 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: {{{ #!sh git clone https://github.com/0ad/0ad.git }}} Now you have two options: === 1. Build the game for your personal use === * Run [source:/ps/trunk/libraries/osx/build-osx-libs.sh libraries/osx/build-osx-libs.sh], the OS X libraries build script, this will download and build the game's dependencies (except CMake, see above). This script will take some time to finish when first run, after that it will reuse the old build. {{{ #!sh cd libraries/osx ./build-osx-libs.sh -j3 }}} * '''-j3''' gives the number of parallel builds to run, and should typically be one plus the number of CPU cores available. * To force a rebuild for some reason, e.g. the SVN folder is moved or Xcode / OS X is upgraded, pass in the `--force-rebuild` flag. * Next, to build the game on the command line, use the following commands: {{{ #!sh cd 0ad/build/workspaces ./update-workspaces.sh -j3 cd gcc make -j3 }}} * 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. See [wiki:Debugging] for more details. * 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]. * Or if you have Xcode 4 installed, you can open `build/workspaces/xcode4/pyrogenesis.xcworkspace` (see discussion on this [http://www.wildfiregames.com/forum/index.php?showtopic=15511&st=160#entry261743 here]). * Or if you're on Snow Leopard and have Xcode 3 installed, you can open `build/workspaces/xcode3/pyrogenesis.xcodeproj` * Run the automated tests to verify that everything works as expected like this: {{{ #!sh binaries/system/test }}} * If everything went well, compiling the code worked and all tests passed, it's finally time to run the game: {{{ #!sh binaries/system/pyrogenesis }}} * '''Note:''' Newer versions of Xcode no longer include the command line tools by default, you need to install them as described above. * '''Note:''' It is recommended to use the command line build, since the Xcode build is not as well-tested, but Xcode's IDE can be very useful for code editing. === 2. Build the game as a distributable app bundle === * You will need Xcode installed (for its SDKs) * Open [source:/ps/trunk/build/workspaces/build-osx-bundle.sh build/workspaces/build-osx-bundle.sh] and read the comments. You will need to change a few settings depending on your version of OS X, Xcode, etc. * Run `build-osx-bundle.sh`, the bundle build script, which will download and build the game's dependencies for the appropriate SDK, build the game's source code, package the mod data, and set up the app bundle info. {{{ #!sh cd build/workspaces ./build-osx-bundle.sh -j3 }}} * '''-j3''' gives the number of parallel builds to run, and should typically be one plus the number of CPU cores available. * When it's finished, there should be a complete '''0ad app''' bundle in `build/workspaces`. You can open it by double-clicking its icon in Finder or with the `open 0ad.app` command in the terminal. * Consider the following to make an official release: * Use `build-osx-bundle.sh --release`, to create a bundle from a clean SVN working copy. * Package the bundle inside a compressed DMG with background image, for easy distribution (see ReleaseProcess). [[BR]] ---- == BSD == '''Note: The *BSD support 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 (names probably differ depending on the BSD variant):[[BR]] Install commands for the variants are provided below. * boost-libs * cmake * curl * enet * execinfo * gloox * gmake * iconv * icu * libGL * libjpeg * libogg * libvorbis * libxml2 * miniupnpc * nspr * openal * png * sdl * subversion * wxWidgets-gtk2 (unicode) - required to build the Atlas editor * zip * '''Note:''' zlib should already be installed by default * GCC 4.4+ or Clang * Obtain the game's source code as [#Gettingthecode described above] for Linux. * Check for any variant specific issues below. * '''Note:''' Our build scripts should detect that you are running *BSD and use `gmake` as the make command. If for some reason this isn't correct, you can set the `MAKE` environment variable to the correct GNU make path. * Follow the [#Building build] instructions above for Linux. === FreeBSD === * Install the dependencies with: {{{ #!sh pkg install boost-libs cmake curl enet gloox gmake iconv libGL libogg \ libvorbis libxml2 miniupnpc nspr openal pkgconf png sdl subversion \ wx30-gtk2 zip }}} * If running FreeBSD 10.0+ you need to set `CC` to `clang` and `CXX` to `clang++`. {{{ export CC=clang CXX=clang++ }}} * TODO: Fix missing ecvt() (see #1325) * 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: {{{ #!sh 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. === OpenBSD === * As we require GCC 4.4+ you need to set `CC` and `CXX` before building {{{ #!sh export CC=egcc CXX=eg++ }}} * Install the dependencies with: {{{ #!sh pkg_add -i boost cmake curl enet g++ gcc gloox gmake icu4c libexecinfo libogg \ libxml miniupnpc nspr openal png sdl subversion zip }}} * As OpenBSD's packaged libxml isn't build with threading support, building Atlas is not possible so you should run `update-workspaces.sh` with the `--disable-atlas` option. * You probably need to run pyrogenesis with `LD_PRELOAD=/usr/local/lib/libogg.so.6.2:/usr/local/lib/libvorbis.so.8.0` (see #1463). [[BR]] ---- == Known problems and solutions == * If in Visual Studio 2010 build of pyrogenesis fails with link error like: {{{ fatal error LNK1123: failure during conversion to COFF: file invalid or corrupt }}} then most common fix is to install Visual Studio 2010 Service Pack 1, which you can get from [http://www.microsoft.com/en-us/download/details.aspx?id=23691 here].