Version 17 (modified by 10 years ago) ( diff ) | ,
---|
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 a modified version of the Premake 4.3 release, located in build/premake/premake4. The modifications fix a number of bugs and missing features in the 4.3 release. (see #1518)
Premake in 0 A.D.
0 A.D. uses two custom Lua scripts to generate its workspaces with Premake:
- build/premake/premake4.lua - this is the main script which controls compiler, linker, and workspace behavior on different platforms.
- build/premake/extern_libs4.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:
premake4/bin/release/premake4 --file="premake4.lua" --outpath="../workspaces/gcc/" gmake
This tells Premake to use our custom premake4.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.
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).
vs2010
- Visual Studio 2010 (or Express)vs2008
- Visual Studio 2008 (or Express)vs2005
- Visual Studio 2005 (or Express)gmake
- GNU Makexcode3
- Apple Xcode 3xcode4
- Apple Xcode 4codeblocks
- Code::Blocks
Note: In most cases we've had to modify the default workspaces for bug fixes, so additional platforms might be supported by Premake in theory but broken in practice. Our main goal is to have an acceptable workspace on each of our main supported platforms: Windows w/ MSVC, Linux w/ make, and OS X w/ Xcode. 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 modeatlas
- Include Atlas scenario editor projectscollada
- Include COLLADA projects (requires FCollada library)coverage
- Enable code coverage data collection (GCC only)gles
- Use non-working OpenGL ES 2.0 modeicc
- Use Intel C++ Compiler (Linux only; should use either--cc icc
or--without-pch
too, and then setCXX=icpc
before calling make)jenkins-tests
- Configure CxxTest to use the XmlPrinter runner which produces Jenkins-compatible outputminimal-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-c++11
- Build using C++11 on GCC.with-system-nvtt
- Search standard paths for nvidia-texture-tools library, instead of using bundled copywith-system-miniupnpc
- Search standard paths for miniupnpc library, instead of using bundled copywith-system-mozjs24
- Search standard paths for libmozjs24 (SpiderMonkey), instead of using bundled copywithout-audio
- Disable use of OpenAL/Ogg/Vorbis APIswithout-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 NVTTwithout-pch
- Disable generation and usage of precompiled headerswithout-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 thesysroot
compiler flag andsyslibroot
linker flag (e.g./usr/lib
becomesSYSROOT/usr/lib
).
build-shared-glooxwrapper
- Rebuild glooxwrapper DLL for Windows. Requires the same compiler version that gloox was built withuse-shared-glooxwrapper
- Use prebuilt glooxwrapper DLL for Windows
bindir
- Directory for executables (typically/usr/games
); default is to be relocatabledatadir
- Directory for data files (typically/usr/share/games/0ad
); default is../data/
relative to executablelibdir
- 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 options are --atlas
and --collada
(you might want to disable them if building the game on an experimental new 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-mozjs24
Building Premake
For Windows developers, we bundle a pre-built, 32-bit premake.exe in SVN. This EXE only needs to be updated when the Premake source code is modified, which happens infrequently.
For *nix and OS X developers, the Premake binary is built by update-workspaces.sh as part of the standard BuildInstructions.
Modifying Premake
To modify Premake's behavior, you typically modify the Lua scripts within build/premake/premake4. You shouldn't modify its build files or scripts.c directly, as these are automatically generated from the scripts. Obviously you need a working, already built Premake binary to do this. This is slightly confusing in that Premake creates the workspace you need to build a new version of Premake.
After you've modified Premake's source scripts, you need to run the old Premake binary with the embed
option to update e.g. src/host/scripts.c
, see Building Premake for more information.
Generating Premake's workspaces
Premake's own workspaces and Makefiles are mostly generated using a Premake binary and the contents of build/premake/premake4/premake4.lua - the Premake4 build configuration script (not to be confused with the game's custom premake4.lua
script, one directory higher). Building Premake and running it with the --help
option will list available options, the basic invocation is as follows (on *nix):
./bin/release/premake4 --os=linux --to=build/gmake.unix/ gmake
This will generate a Linux-compatible Makefile in the build/gmake.unix subdirectory. Using a similar process it should be possible to generate any supported OS- or toolset-specific workspace for Premake. Note: some of the results may need hand-editing to work around Premake bugs, so use with caution. When possible it should be preferred to fix the bugs instead.