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. We also bundle a few plugins that extend the features of premake to suit our needs: those are located under 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:

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 and 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).

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
  • 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 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 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 and for using CxxTest.

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

Last modified 8 months ago Last modified on Nov 1, 2017, 7:36:52 PM