Version 334 (modified by 5 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, more if compiling multiple jobs in parallel (using -j)
- 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 (7 or newer)
- Linux
- OS X (10.7/Lion 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 10
- Windows 8.1
- Windows 8
- Windows 7
If you want to develop, the only supported IDEs are:
- Visual C++ 2013 (default compiler, used in official builds of the game)
- Visual C++ 2015 (recommended for developers as we will soon drop support for VS 2013)
Important notes:
- We have dropped support for older versions of Visual Studio when moving to C++11, see #2669.
- XP and Vista are supported as targets, but not for installing Visual Studio 2013/2015.
- 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 TortoiseSVN. (Make sure you reboot when it asks you to.)
- Use TortoiseSVN to check out
https://svn.wildfiregames.com/public/ps/trunk/
. This may take a while, and will use around 5GB 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 https://svn.wildfiregames.com/svn/ps/trunk/
instead.)
If you only wish to play the most cutting-edge version, this is all you have to do (other than Keeping up to date). The executable will be located at binaries/system/pyrogenesis.exe
.
Setting up the build environment
The game must be compiled with Microsoft Visual C++. You can get the free 2015 Community edition, or 2013 Express edition, here: Visual Studio older downloads. You can also install Visual Studio 2017 and choose to install the 2015 compiler (version 14.0).
The Visual Studio project/solution files are automatically generated from the source files:
- Run
cd build\workspaces
and then update-workspaces.bat. - Open
build\workspaces\vc2015\pyrogenesis.sln
(orvc2013
for the older version).
Build configuration
Make sure to select the "Release" configuration to build an optimized, 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 and 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 (at least 1.57 since r21726)
- CMake (only needed if you use bundled NVTT)
- GCC (at least 4.8.1, required by C++11 features)
- libcurl (at least 7.32)
- libenet (1.3, the older 1.2 is not compatible)
- libgloox (needed for the lobby; at least 1.0.10, previous versions are know to have connection problems; pass
--without-lobby
toupdate-workspaces.sh
to exclude the lobby) - libicu
- libnspr4
- libogg
- libpng
- libsodium (>= 1.0.14, follow the instructions at https://download.libsodium.org/doc/installation/ if your distro is behind)
- libvorbis
- libxcursor
- libxml2
- miniupnpc (at least 1.6)
- OpenAL
- OpenGL
- SDL2 (at least 2.0.2)
- 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):
- SpiderMonkey 38 (
--with-system-mozjs38
) - NVTT (
--with-system-nvtt
)
For a list of all options to update-workspaces.sh
see premake.
Debian / Ubuntu
- On Debian 8/jessie or Ubuntu 14.04/trusty or later install the required dependencies with:
sudo apt-get install build-essential libboost-dev libboost-filesystem-dev \ libcurl4-gnutls-dev libenet-dev libgloox-dev libicu-dev \ libminiupnpc-dev libnspr4-dev libnvtt-dev libogg-dev libopenal-dev \ libpng-dev libsdl2-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 these dependencies you have to run:
- On all versions except Ubuntu 18.04, you will need to install libsodium manually.
- On Ubuntu 18.04,
sudo apt-get install libsodium-dev
.
- On Ubuntu 18.04,
- If you want to use a packaged mozjs38, available for example in 0ad.dev PPA:
- you should replace
libnspr4-dev
withlibmozjs-38-dev
and runupdate-workspace.sh
with--with-system-mozjs38
.
- you should replace
- When not using system nvidia-texture-tools,
libnvtt-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 \ libenet-devel libgloox-devel libpng-devel libsodium-devel libvorbis-devel \ libxml2-devel libwxgtku2.8-devel openal-soft-devel libicu-devel
Fedora
Install the dependencies with:
sudo dnf install gcc-c++ python subversion zip cmake patch \ boost-devel libcurl-devel enet-devel libpng-devel libsodium-devel libvorbis-devel \ libxml2-devel openal-soft-devel pkgconfig SDL2-devel wxGTK-devel \ gloox-devel libicu-devel miniupnpc-devel nspr-devel
- To submit a patch for review via arcanist ([wiki:Phabricator), php is needed:
dnf install php-cli php-xml
.
openSUSE
Install the dependencies with:
sudo zypper install gcc-c++ python subversion zip cmake boost-devel \ libcurl-devel libenet-devel libpng-devel libsodium-devel libvorbis-devel \ libxml2-devel openal-soft-devel pkg-config wxWidgets-devel libSDL2-devel \ gloox-devel libicu-devel miniupnpc-devel
ArchLinux
pacman -S --needed boost cmake curl enet gcc gloox icu libgl libogg libpng libsodium libvorbis libxcursor libxml2 miniupnpc patch sdl2 subversion wxgtk zip zlib make python python2 pkg-config nspr grep awk
Solus
sudo eopkg install libboost-devel libnspr-devel curl-devel enet-devel gloox-devel libicu-devel libnspr-devel libogg-devel libpng-devel libsodium-devel libvorbis-devel libxcursor-devel libxml2-devel miniupnpc-devel openal-soft-devel mesalib-devel sdl2-devel zlib-devel wxwidgets-devel
Slackware
After installing the dependencies for your particular version, you can build 0 A.D. from the svn code using the instructions from the Building section.
Note: These instructions have been tested on the 64-bit version of Slackware.
Slackware 14.2
At this time, 0 A.D. will build successfully, but the resulting binary produces a segmentation fault
immediately after executing. If you would like to help with the ticket please contact us.
If you've done the full install of Slackware, most of the dependencies are already installed. The other required dependencies you can install from the Slackbuilds repo using sbopkg:
- enet
- gloox
- libsodium
- miniupnpc
- OpenAL
- SDL2
note about libnspr4: The nspr library, also a requirement, is in the mozilla-nss
package, which is shipped with Slackware.
Required to build Atlas:
- wxGTK3 (install/build this first, required by wxPython3)
- wxPython3
Slackware-current
Presently, 0 A.D. does not build on Slackware-current. If you'd like to help with the ticket, please contact us.
If you attempt to build on Slackware-current, install the dependencies listed above with sbopkg
, but skip libsodium and sdl2; they are already distributed with Slackware-current.
CentOS
Discussion of installing on CentOS 7 can be found on the forums here.
Note: The advice below is derived from installing in a Virtual Machine with CentOS 7 64-bit minimally installed. If you have CentOS 6 (or earlier), the following steps may not be possible. Installation on a physical machine, a machine with more stuff already installed upon it, or a machine that is 32-bit, may differ slightly.
- Firstly, you will need to enable the "Extra Packages for Enterprise Linux" (or "EPEL") repository (if you haven't already). You can do this by running (as root/via sudo)
yum install epel-release
- Install some auxiliary packages. These are not dependencies of 0AD itself, but are necessary to run update_workspaces.sh successfully. They might already be installed on your system:
yum install bzip2 patch
- Install the 0AD dependencies that are available directly from repos:
yum install cmake gcc-c++ enet-devel libglvnd-devel gloox-devel libicu-devel nspr-devel \ libogg-devel libpng-devel libsodium-devel libvorbis-devel libXcursor-devel libxml2-devel \ miniupnpc-devel openal-soft-devel subversion wxGTK3-devel zlib-devel SDL2-devel
- Acquire a sufficiently recent version of libcurl:
- From this site: https://mirror.city-fan.org/ftp/contrib/libraries/, download the two files that satisfy one of the following patterns:
libssh2-{version}.cf.rhel7.{arch}.rpm
libssh2-devel-{version}.cf.rhel7.{arch}.rpm
- From this site: https://mirror.city-fan.org/ftp/contrib/sysutils/Mirroring/, download the three files that satisfy one of the following patterns:
curl-{version}.cf.rhel7.{arch}.rpm
libcurl-{version}.cf.rhel7.{arch}.rpm
libcurl-devel-{version}.cf.rhel7.{arch}.rpm
- Install some dependencies from repos:
yum install nss-devel libnghttp2 libpsl libmetalink
- Install dependencies from downloaded packages.
Note: This will replace the version of libssh2 that is provided by the CentOS official repos. This is necessary as the version of libcurl we're installing needs a more up-to-date version than what the official repos can provide. As the packages we've acquired are compiled as to be interoperable with CentOS systems, this shouldn't cause any problems with other programs installed on your system.
Install thelibssh2-*
andlibssh2-devel-*
packages usingrpm -Uvh
. For example:rpm -Uvh libssh2-1.8.0-8.0.cf.rhel7.x86_64.rpm libssh2-devel-1.8.0-8.0.cf.rhel7.x86_64.rpm
- Install the updated curl packages (
curl-*
,libcurl-*
andlibcurl-devel-*
) usingrpm -Uvh
. For example:rpm -Uvh curl-7.61.1-3.0.cf.rhel7.x86_64.rpm libcurl-7.61.1-3.0.cf.rhel7.x86_64.rpm libcurl-devel-7.61.1-3.0.cf.rhel7.x86_64.rpm
- From this site: https://mirror.city-fan.org/ftp/contrib/libraries/, download the two files that satisfy one of the following patterns:
- Acquire a sufficiently recent version of boost:
- From https://www.boost.org/users/history/version_1_68_0.html, download
boost_1_68_0.tar.gz
. - Uncompress archive:
- $
tar -xf boost_1_68_0.tar.gz
- $
- Enter folder:
- $
cd ./boost_1_68_0
- $
- Compile the parts that are needed to be compiled, and install the libraries:
- $
./bootstrap.sh --with-libraries=filesystem,system
- #
./b2 install
- (Compiled files end up in
/usr/local/lib/
, header files in/usr/local/include/boost/
)
- $
- From https://www.boost.org/users/history/version_1_68_0.html, download
- You should now have all dependencies for 0AD. Continue by getting the code, as described below.
VoidLinux
sudo xbps-install -Syv base-devel boost-devel cmake curl gcc icu-devel libcurl-devel libenet-devel libogg-devel libopenal-devel libpng-devel libsodium-devel libvorbis-devel libXcursor libxml2 MesaLib-devel miniupnpc-devel nspr-devel patch pkg-config SDL2-devel wxWidgets-devel zip zlib
If there are issues, install more header files depending on the compiler's error message.
nspr-devel
is required for building SpiderMonkey and pyrogenesis requires MesaLib-devel
to provide header files for libGL.
Custom compile gloox
for the Lobby or use xbps source packages or use update-workspaces.sh --without-lobby
or wait until https://github.com/voidlinux/void-packages/pull/5102 is merged.
If there are unresolved shlibs or an update breaks a package, then e.g.
sudo xbps-install -Syv SDL2-devel dbus dbus-x11 # credit Vaelatern sudo xpbs-install -Su # update, add -d for debugging, credit duncaen
Getting the code
0 A.D. is primarily developed on SVN. To checkout the latest code from SVN, run this command:
svn co https://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
Note: Make sure that the checkout directory doesn't contain special characters (spaces or non-ASCII characters)
There are also Git mirrors, which may be slightly less up-to-date but usually offers faster downloads. To use a Git mirror, use one of the following commands instead:
git clone https://github.com/0ad/0ad.git
or
git clone https://gitlab.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. See Debugging for more details.
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:
cd ../../..
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 want to rebuild quickly after updating from SVN, you can usually get away with:
svn up cd build/workspaces ./update-workspaces.sh -j3 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 Salsa 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 5.1+, you can download the command line tools from the download preferences.
- If you're using 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 Apple Developer Downloads (logging in with your free Apple ID) and download the latest Xcode version for your OS.
- The latest version of Xcode is also available for free from the Mac 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 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 tobuild-osx-libs.sh
.
- As of Alpha 21, the game uses SpiderMonkey 38 which requires a Python 2.7 version later than 2.7.3. If you're on Mountain Lion (10.8) or earlier, you will need to first update your Python installation with the latest 2.7.x installer from here.
- Obtain CMake:
- You can download a prebuilt OS X package here.
- If prompted, install the CMake command line tools to the default location.
- Note: Recent versions have no installer, so after copying the app bundle to Applications, you need to run CMake with elevated permissions to install the command line tools. From the terminal:
sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install
- If the install command fails, you can manually add the following line to the end of
/etc/paths
:/Applications/CMake.app/Contents/bin
- Obtain the game's source code:
- 0 A.D. is primarily developed on SVN. To checkout the latest code from SVN, run this command:
Note: Sometimes SVN stops before it has downloaded all files. You should check that it outputs something like
svn co https://svn.wildfiregames.com/public/ps/trunk/ 0ad
at revision rXXXX
. Otherwise runsvn 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
- 0 A.D. is primarily developed on SVN. To checkout the latest code from SVN, run this command:
Now you have two options:
1. Build the game for your personal use
- 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). This script will take some time to finish when first run, after that it will reuse the old build.
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:
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 runpyrogenesis_dbg
) if you need better debugging support. See Debugging for more details. - 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.
- The Release mode builds (which are the default) are more optimised, but are harder to debug. Use
- Or if you have Xcode 4 installed, you can open
build/workspaces/xcode4/pyrogenesis.xcworkspace
(see discussion on this here). - Run the automated tests to verify that everything works as expected like this:
binaries/system/test
- If everything went well, compiling the code worked and all tests passed, it's finally time to run the game:
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 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.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 theopen 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).
- Use
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 (at least 7.32)
- enet
- execinfo
- gloox
- gmake
- iconv
- icu
- libGL
- libogg
- libvorbis
- libxml2
- miniupnpc
- nspr
- openal
- png
- sdl2
- subversion
- wxWidgets-gtk2 (unicode) - required to build the Atlas editor
- zip
- Note: zlib should already be installed by default
- GCC 4.8.1+ or Clang
- 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 install boost-libs cmake curl enet gloox gmake iconv libGL libogg \ libsodium libvorbis libxml2 miniupnpc nspr openal pkgconf png sdl2 subversion \ wx30-gtk2 zip
- If running FreeBSD 10.0+ you need to set
CC
toclang
andCXX
toclang++
.export CC=clang CXX=clang++
- 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
- As we require GCC 4.8.1+ you need to set
CC
andCXX
before buildingexport CC=egcc CXX=eg++
- Install the dependencies with:
pkg_add -i boost cmake curl enet g++ gcc gloox gmake icu4c libexecinfo libogg libsodium \ libxml miniupnpc nspr openal png sdl2 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
- None currently.