Version 234 (modified by 10 years ago) ( diff ) | ,
---|
Table of Contents
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 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 forum.
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 (XP or newer)
- Linux
- OS X (currently 10.6 or newer)
- 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.
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
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 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 TortoiseSVN manual has information on checking out, as well as updating and 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:
- Visual C++ 2010 Express Edition is recommended.
- Or download and install Visual C++ 2008 Express Edition.
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 thevc2008
directory for VC++ 2008; use thevc2012
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 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 Atlas Scenario Editor or Actor Editor tools, you will need to download and build the 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:
- 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:
- Boost
- CMake (only needed if you use bundled NVTT)
- GCC (at least 4.0, preferably 4.3 or later)
- libcurl
- libgloox (needed for the lobby; pass
--without-lobby
toupdate-workspaces.sh
to exclude the lobby) - libicu
- libnspr4
- libogg
- libpng
- libvorbis
- libxcursor
- libxml2
- OpenAL
- OpenGL
- SDL
- 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):
- ENet 1.3 (
--with-system-enet
) - SpiderMonkey 24 (
--with-system-mozjs24
) - NVTT (
--with-system-nvtt
) - MiniUPnP client (
--with-system-miniupnpc
)
For a list of all options to update-workspaces.sh
see premake.
Debian (7 or later) / Ubuntu (12.04 or later)
Install the dependencies with:
sudo apt-get install build-essential libboost-dev libboost-filesystem-dev \ libboost-signals-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-enet --with-system-miniupnpc --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 jessie/8 and Ubuntu trusty/14.04 or later:
- you should replace
libwxgtk3.0-dev
withlibwxgtk2.8-dev
; - you should replace
libmozjs-24-dev
withlibnspr4-dev
and runupdate-workspace.sh
without--with-system-mozjs24
.
- you should replace
- When not using system libraries,
libenet-dev
andlibnvtt-dev
can be omitted, butcmake
is needed to build the bundled NVTT. - You can also use
libcurl4-openssl-dev
instead oflibcurl4-gnutls-dev
(it's not possible to install both at once), but note that openssl is not GPL compatible and the resulting binaries could not be redistributed.
Mandriva
Install the dependencies with:
urpmi gcc-c++ python subversion zip cmake boost-devel libcurl-devel \ libgloox-devel libjpeg-devel libpng-devel libvorbis-devel libxml2-devel \ libwxgtku2.8-devel openal-soft-devel
Fedora
Install the dependencies with:
su -c 'yum -y install gcc-c++ python subversion zip cmake boost-devel \ libcurl-devel libjpeg-devel libpng-devel libvorbis-devel libxml2-devel \ openal-soft-devel pkgconfig SDL-devel wxGTK-devel gloox-devel'
openSUSE
Install the dependencies with:
sudo zypper install gcc-c++ python subversion zip cmake boost-devel \ libcurl-devel libjpeg-devel libpng-devel libvorbis-devel libxml2-devel \ openal-soft-devel pkg-config wxGTK-devel libSDL-devel gloox-devel
Users of openSUSE 11.4 and later should install the wxWidgets-devel package instead of wxGTK-devel.
ArchLinux
pacman -S libgl boost cmake gcc curl gloox libogg libpng libvorbis libxcursor libxml2 patch sdl subversion zip zlib
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
Note: 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:
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 runpyrogenesis_dbg
) if you need better debugging support.
If you encounter any build errors, review the existing bug reports, check the known problems section or please file a 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.
#!/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:
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 0ad and 0ad-data packages on OBS for examples (especially the control
and rules
files).
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 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 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 OSX GCC Installer):
- If available, use your Mac OS X install DVD which saves downloading 1.72+ GB.
- Visit 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 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: CMake is a required dependency. You can download a prebuilt OS X package here. If prompted, install the command line CMake tools to the default location.
- Obtain the game's source code from SVN as described above.
Now you have two options:
1. Build the game as a loose binary
- Run 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).
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 build on the command line with
llvm-gcc
, follow the build instructions for Linux beginning with./update-workspaces.sh
.- Or if you have Xcode 4 installed, you can open
build/workspaces/xcode4/pyrogenesis.xcworkspace
(see discussion on this here). - Or if you're on Snow Leopard and have Xcode 3 installed, you can open
build/workspaces/xcode3/pyrogenesis.xcodeproj
- Or if you have Xcode 4 installed, you can open
- Note: 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 (on these systems,gcc
is a symlink tollvm-gcc
).
2. Build the game as a distributable bundle
- You will need Xcode installed (for its SDKs)
- Open build/workspaces/build-osx-bundle.sh and read the comments. You might need to change a few settings depending on your version of OS X, Xcode, etc.
- Run
build-osx-bundle.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
. Consider packaging the bundle inside a DMG for distribution (see ReleaseProcess).
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):
Install commands for the variants are provided below.- boost-libs
- cmake
- curl
- execinfo
- gmake
- icu
- libGL
- libjpeg
- libogg
- libvorbis
- libxml2
- openal
- png
- sdl
- subversion
- wxWidgets-gtk2 (unicode) - required to build the Atlas editor
- zip
- Note: GCC 4.2.1 and zlib should already be installed by default
- Obtain the game's source code as 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 theMAKE
environment variable to the correct GNU make path. - Follow the build instructions above for Linux.
FreeBSD
- Install the dependencies with:
pkg_add -r boost-libs cmake curl execinfo gmake libGL libjpeg-turbo libogg \ libvorbis libxml2 openal png sdl subversion wxgtk2-unicode zip
- TODO: Fix missing ecvt() (see #1325)
- If building Atlas, you need to set the
WX_CONFIG
variable, becausewx-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: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 theexport WX_CONFIG=wxgtk2u-2.8-config
--disable-atlas
option toupdate-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.
- You'll have to set this variable every time you run
OpenBSD
- Install the dependencies with:
pkg_add -i boost cmake curl gmake jpeg libexecinfo libogg libxml 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).
Known problems and solutions
- If you get linker errors like
cannot find -lboost_signals-mt
(particularly users of Arch Linux or Slackware), edit the file build/premake/extern_libs4.lua and remove the-mt
suffix from the Boostunix_name
definitions, then runupdate-workspaces.sh
again.
- 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 thencd 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 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 here.