Premake

Premake is the tool used to build 0 A.D. from source code. It is a critical part of the "build system". Premake uses Lua scripts to create workspaces both for building Premake itself and other projects like 0 A.D. It mostly supports Visual Studio (Windows), Xcode (OS X) and GNU make (*nix and OS X).

Note: Currently we bundle an unmodified version of Premake 5 alpha 12 release, located in [build/premake/premake5]source:/ps/trunk/build/premake/premake5. We also bundle a few plugins that extend the features of premake to suit our needs: those are located under [build/premake/]source:/ps/trunk/build/premake/. We also still distribute our former modified version of Premake 4.3, which is still used by our CI scripts to avoid regressions. We will get rid of it when we drop premake4 for good.

Premake in 0 A.D.

0 A.D. uses two custom Lua scripts to generate its workspaces with Premake:

[build/premake/premake5.lua]source:/ps/trunk/build/premake/premake5.lua - this is the main script which controls compiler, linker, and workspace behavior on different platforms.
[build/premake/extern_libs5.lua]source:/ps/trunk/build/premake/extern_libs5.lua - this is an auxiliary script, which lists external dependencies / libraries used by 0 A.D. and how they differ on various platforms. These scripts are well commented, describing the reasoning behind most of the logic.

Generating the workspaces is quite simple and done automatically by the update-workspaces step(s) of our BuildInstructions. The Premake binary is run as with the following command:

premake5/bin/release/premake5 --file="premake5.lua" --outpath="../workspaces/gcc/" gmake

This tells Premake to use our custom premake5.lua to generate a GNU make workspace located in build/workspaces/gcc/. Those options are self-explanatory, but there are a number of other options supported by Premake and our custom scripts, listed below.

Note: gmake is also used with clang, so ideally the outpath should follow a sensible convention and be called gmake, regardless of the compiler used.

See [update-workspaces.sh]source:/ps/trunk/build/workspaces/update-workspaces.sh and [update-workspaces.bat]source:/ps/trunk/build/workspaces/update-workspaces.bat to see how we use Premake.

Supported workspaces

Our Premake build supports the following workspaces, but not on every platform (e.g. xcode3 probably won't work on Windows or Linux).

vs2013 - Visual C++ 2013
gmake - GNU Make
xcode4 - Apple Xcode 4 Note: Our scripts have not been tested yet on all platforms, so some combinations may cause issues. Our main goal is to have an acceptable workspace on each of our main supported platforms: Windows w/ MSVC, Linux w/ gmake+gcc, and OS X w/ Xcode and gmake+clang. Supporting additional platforms is less of a priority.

Premake options

In addition to --file and --outpath, our scripts support the following options (also prefixed with "--"):

android - Use non-working Android cross-compiling mode
atlas - Include Atlas scenario editor projects
collada is deprecated and was needed with premake4 to build the COLLADA project that we rely upon.
coverage - Enable code coverage data collection (GCC only)
gles - Use non-working OpenGL ES 2.0 mode
icc - Use Intel C++ Compiler (Linux only; should use either --cc icc or --without-pch too, and then set CXX=icpc before calling make)
jenkins-tests - Configure CxxTest to use the XmlPrinter runner which produces Jenkins-compatible output
minimal-flags - Only set compiler/linker flags that are really needed. Has no effect on Windows builds. Use this to set your own compiler/linker flags (CXXFLAGS, LDFLAGS)
with-system-nvtt - Search standard paths for nvidia-texture-tools library, instead of using bundled copy
with-system-mozjs38 - Search standard paths for libmozjs38 (SpiderMonkey), instead of using bundled copy
without-audio - Disable use of OpenAL/Ogg/Vorbis APIs
without-lobby - Disable the game lobby (and thus the use of gloox)
without-miniupnpc - Disable use of miniupnpc (and thus automatic port forwarding)
without-nvtt - Disable use of NVTT
without-pch - Disable generation and usage of precompiled headers
without-tests - Disable generation of test projects
prefer-local-libs - On Linux and BSD systems, use this to prefer libraries installed locally (in /usr/local/lib) instead of those installed from your distribution's package repositories. Note: you might also need to create a suitable file in /etc/ld.so.conf.d, otherwise your system might complain that it cannot find the libraries at run-time.
macosx-bundle - Set the compiled binary as an OS X bundle with the given identifier string, e.g. "com.wildfiregames.0ad".
macosx-version-min - Set minimum required version of the OS X APIs to use, e.g. "10.6".
sysroot - Root directory for SDK builds, sets the sysroot compiler flag and syslibroot linker flag (e.g. /usr/lib becomes SYSROOT/usr/lib).
build-shared-glooxwrapper - Rebuild glooxwrapper DLL for Windows. Requires the same compiler version that gloox was built with
use-shared-glooxwrapper - Use prebuilt glooxwrapper DLL for Windows
large-address-aware - Support for large memory addresses on Windows. The autobuilt version of the game uses it, but this is disabled by default, so that developers experience and fix memory issues.
bindir - Directory for executables (typically /usr/games); default is to be relocatable
datadir - Directory for data files (typically /usr/share/games/0ad); default is ../data/ relative to executable
libdir - Directory for libraries (typically /usr/lib/games/0ad); default is ./ relative to executable

Note: Most of the options are special purpose and not needed for the average build. You shouldn't use an option unless you understand it and have a need for it.

The most commonly used option is --atlas (you might want to disable it if building the game on an experimental platform like Android). --atlas is not used by default in update-workspaces.bat, because we don't bundle the wxWidgets libraries in SVN. If you are using update-workspaces.sh Atlas is built by default. Use --disable-atlas to skip it.

The update-workspaces scripts will pass arguments through to Premake:

./update-workspaces.sh --without-tests --with-system-mozjs38

Building Premake

For Windows developers, we distribute the pre-built 32-bit from upstream [premake5.exe]source:/ps/trunk/build/premake/premake5/bin/release/premake5.exe in SVN. Thus, changes to the premake source code will have no effect. The upstream is quite responsive and will gladly accept pull requests.

For *nix and OS X developers, the Premake binary is built by [update-workspaces.sh]source:/ps/trunk/build/workspaces/update-workspaces.sh as part of the standard BuildInstructions.

Extending Premake

To extend Premake's features (seldom necessary), you can write plugins. We currently distribute plugins for interacting with [pkg-config]source:/ps/trunk/build/premake/pkgconfig and for using [CxxTest]source:/ps/trunk/build/premake/cxxtest.

Refer to the official documentation for more information on the matter.