[[TOC]] 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 - several gigabytes of free disk space, preferably at least 1GB of RAM for compiling, a fast CPU unless you want to spend ages waiting for the compiler, etc. Modern graphics hardware is also recommended, though the game can run (slowly) on fairly old devices (!GeForce 4, Intel 945GM, etc). * 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 XP, Vista and 7 are the main supported versions; 2000 should work too but is rarely tested. Visual C++ 2005 and 2008 are supported; older versions aren't, newer versions may work but haven't been tested, MinGW certainly won't work. Only 32-bit builds are supported (though they can be compiled and run on 64-bit Windows). === 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 700MB of disk space. Make sure it's in a path that does not contain any space characters (#482). 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: * Download and install [http://www.microsoft.com/express/ Visual C++ 2008 Express Edition]. (You can skip the optional Silverlight and SQL Server components.) (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/vc2008/pyrogenesis.sln`. (If you have VC++ 2005, use the `vc2005` directory instead.) Now you should be able to build the code from within Visual Studio, using "Build Solution" (F7). === 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. == Unix == This is much less streamlined than the process for Windows. But you're cooler than a Windows developer, so you should be able to cope: === Linux === * Install various standard tools and development libraries: * GCC (at least 4.1, preferably 4.3) * Subversion * NASM * There is a [http://sourceforge.net/tracker/?func=detail&aid=2821249&group_id=6208&atid=106208 bug] in NASM 2.06 on x86_64, so you might want to try a different version if you get errors. * SDL * Boost * zlib * libpng * libxml2 * OpenGL * OpenAL * libogg * libvorbis * cryptopp * wxWidgets (probably called wxgtk on Linux) (optional, but required for the editor tools) * Gamin (FAM should work too) (Linux only) * BFD (typically called something like binutils-dev) (Linux only) * ENet * DevIL * For '''Ubuntu''' the following might help: ''sudo apt-get install build-essential libsdl1.2-dev zlib1g-dev libpng12-dev libjpeg62-dev libgamin-dev nasm libwxgtk2.8-dev libboost-dev libboost-signals-dev libboost-filesystem-dev libopenal-dev libalut-dev libvorbis-dev libogg-dev libcrypto++-dev binutils-dev libdevil-dev libenet-dev libxml2-dev'' * For '''Mandriva''' (tested with 2009.1): ''urpmi libboost-devel libcryptopp-devel libwxgtk2.8-devel libwxgtku2.8-devel libbinutils2-devel libopenal-devel zlib1-devel libpng-devel libogg0-devel libvorbis-devel libSDL-devel libdevil-devel libgamin-1_0-devel libjpeg62-devel libfreealut-devel nasm make svn''. No ENet package is available, so [http://enet.bespin.org/Installation.html install it from source]. * For '''Fedora''' (tested with 12): ''yum -y install subversion gcc-c++ nasm SDL-devel boost-devel zlib-devel libpng-devel libjpeg-devel libxml2-devel openal-devel libogg-devel libvorbis-devel cryptopp-devel wxGTK-devel gamin-devel binutils-devel enet-devel DevIL-devel'' * `svn co http://svn.wildfiregames.com/public/ps/trunk/` * `cd trunk/build/workspaces` * `./update-workspaces.sh` (if you update to a later version of the code from SVN, you should run this again each time) * `cd gcc` * `make -j3` (where `3` is the number of parallel builds to run, and could perhaps be one plus the number of CPU cores available) * '''Note''': Parallel building can cause errors due to race conditions. Run a "make clean" and try just "make" if you encounter problems. * If you encounter any build errors, look for an existing bug report or report a new bug. Also check the [#Knownproblemsandsolutions known problems section] below. * `cd ../../../binaries/system` * Optionally, run the automated tests to verify that everything works as expected: `./test_dbg` * Run the game: `./pyrogenesis_dbg` * Optionally, run the map editor: `./pyrogenesis_dbg -editor` By default, the game is compiled in an unoptimised debug configuration, so that errors are easier to detect and understand and fix. To compile an optimised version, build with `CONFIG=Release make` and then run the game as `./pyrogenesis` === 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. * 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 * libsdl * xercesc * wxWidgets * libxml2 * libdevil * libenet * 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` * Take care that libdevil 1.6.8-rc2 (the version in !MacPorts) is not compatible with GCC 4.3, you'll need to install 1.7.8. Get it from http://openil.sourceforge.net/download.php, then extract the archive, and run `./configure --enable-ILU --enable-ILUT` then `make` then `sudo make install` * You may need to patch Apple's OpenAL (`/System/Library/Frameworks/OpenAL.Framework/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/premake.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` === 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 {{{ /opt/local/include/js/jsotypes.h:77: error: conflicting declaration ‘typedef struct JSUint64 uint64’ /System/Library/Frameworks/Security.framework/Headers/cssmconfig.h:48: error: ‘uint64’ has a previous declaration as ‘typedef uint64_t uint64’ }}} Run your favourite text editor as root, and edit line 77 of /opt/local/include/js/jsotypes.h from `typedef JSUint64 uint64;` to {{{ #ifndef _UINT64 typedef JSUint64 uint64; #define _UINT64 #endif }}} == Obtaining the latest release == '''This is a new untested distribution method. It might be best to stick with SVN for now, while we sort this out over the next few days.''' === Linux packages === Unofficial packages may exist or be in development for several distros: * [http://bugs.gentoo.org/show_bug.cgi?id=278541 Gentoo] * [http://aur.archlinux.org/packages.php?ID=28560 Arch] * [https://bugs.launchpad.net/getdeb.net/+bug/543277 Ubuntu] If you use a different distro, or if these packages are outdated, or if you want to edit or debug the code, see the next section. === Compiling on Linux and OS X === You need two files: * [http://releases.wildfiregames.com/0ad-r07405-pre-alpha-unix-build.tar.xz 0ad-unix-build.tar.xz] (6 MB) ''or'' [http://releases.wildfiregames.com/0ad-r07405-pre-alpha-unix-build.tar.bz2 0ad-unix-build.tar.bz2] (8 MB) * [http://releases.wildfiregames.com/0ad-r07405-pre-alpha-unix-data.tar.xz 0ad-unix-data.tar.xz] (92 MB) ''or'' [http://releases.wildfiregames.com/0ad-r07405-pre-alpha-unix-data.tar.bz2 0ad-unix-data.tar.bz2] (106 MB) The `.xz` files are smaller but may require you to install [http://tukaani.org/xz/ XZ Utils]. SHA1 digests: {{{ 57d61f2bee26666d8e89e9952a6c2b532dd6e030 0ad-r07405-pre-alpha-unix-build.tar.xz eaaa0094a8baeaf3d3a11792b7272b397f2ca84c 0ad-r07405-pre-alpha-unix-build.tar.bz2 2a5837141579f77f3b3b5f3d2e83b490dbef9bc5 0ad-r07405-pre-alpha-unix-data.tar.xz a30fc818807a40225bb792892ffd91a1c86fadfe 0ad-r07405-pre-alpha-unix-data.tar.bz2 }}} Extract both files to the same location: {{{ # Extract .xz version into the current directory: tar xvJf 0ad-r07405-pre-alpha-unix-build.tar.xz tar xvJf 0ad-r07405-pre-alpha-unix-data.tar.xz # Or, if your tar is older than 1.22: xz -cd 0ad-r07405-pre-alpha-unix-build.tar.xz | tar xv xz -cd 0ad-r07405-pre-alpha-unix-data.tar.xz | tar xv # Or, if you have the .bz2 version: tar xvjf 0ad-r07405-pre-alpha-unix-build.tar.bz2 tar xvjf 0ad-r07405-pre-alpha-unix-data.tar.bz2 }}} Then follow the SVN build instructions. === Windows === Download and run [http://releases.wildfiregames.com/0ad-r07405-pre-alpha-win32.exe 0ad-win32.exe] (114 MB) (self-extracting [http://www.7-zip.org/ 7-Zip]), then select a location to extract the files. This includes all the source code and data files, and precompiled binaries. SHA1 digest: {{{ 76f4ba98ef0f6e05eac9ff2a1b83ca767b181da3 0ad-r07405-pre-alpha-win32.exe }}} Either follow the SVN build instructions, or run binaries\system\pyrogenesis.exe directly. == Creating Linux packages == This section is for people creating installable packages for Linux distros. Download the `build` tarball listed above. Follow the SVN build instructions. The default is an unoptimised debug-mode build (this is helpful since the game is unstable and buggy); if you want an optimised harder-to-debug build instead, compile with `CONFIG=Release make`. Run the automated tests to make sure nothing is broken: extract the `data` tarball alongside the `build` one, then run `./test_dbg` (or `./test` for Release builds) from `binaries/system/`. There should be no error output. You need to distribute the following files from `binaries/system/`: * `pyrogenesis_dbg` (Debug build) or `pyrogenesis` (Release build) * `libCollada_dbg.so` or `libCollada.so` * `libAtlasUI_dbg.so` or `libAtlasUI.so` * `libmozjs-ps-debug.so` or `libmozjs-ps-release.so` You also need to distribute the contents of the `data` tarball. You don't need to distribute anything from the `build` tarball. The executables should be located somewhere so that they can use `../data/` to access the `data` tarball's `binaries/data/` directory. (They don't need to be in a directory called `system/`, and that directory doesn't need to be in one called `binaries/`, if you prefer different names). The whole thing should probably go somewhere like `/opt/0ad/`, and you might want to set up a script with a nice name like `/usr/bin/0ad` to run it, depending on local conventions. These directories and files should be read-only; all per-user output goes in XDG basedir locations (unless we have bugs).