= Premake = [https://premake.github.io/ Premake] is the tool used to build 0 A.D. from source code. It is a critical part of the "build system". Premake uses [http://www.lua.org/ 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 [source:/ps/trunk/build/premake/premake5 build/premake/premake5]. We also bundle a few plugins that extend the features of premake to suit our needs: those are located under [source:/ps/trunk/build/premake/ 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: * [source:/ps/trunk/build/premake/premake5.lua build/premake/premake5.lua] - this is the main script which controls compiler, linker, and workspace behavior on different platforms. * [source:/ps/trunk/build/premake/extern_libs5.lua 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: {{{ #!sh 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 [source:/ps/trunk/build/workspaces/update-workspaces.sh update-workspaces.sh] and [source:/ps/trunk/build/workspaces/update-workspaces.bat 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` - [http://www.gnu.org/software/make/ GNU Make] * `xcode4` - [https://developer.apple.com/xcode/ 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: {{{ #!sh ./update-workspaces.sh --without-tests --with-system-mozjs38 }}} == Building Premake == For Windows developers, we distribute the pre-built 32-bit from upstream [source:/ps/trunk/build/premake/premake5/bin/release/premake5.exe 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 [source:/ps/trunk/build/workspaces/update-workspaces.sh 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 [source:/ps/trunk/build/premake/pkgconfig pkg-config] and for using [source:/ps/trunk/build/premake/cxxtest CxxTest]. Refer to [https://github.com/premake/premake-core/wiki/Extending-Premake the official documentation] for more information on the matter.