Changes between Initial Version and Version 1 of premake

Timestamp:

Jul 1, 2012, 5:34:22 AM (12 years ago)

Author:

historic_bruno

Comment:

Initial draft

premake

@@ +1 @@
+= Premake =
+
+[http://industriousone.com/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 [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).
+
+Currently we bundle a modified version of the Premake 4.3 release, located in [source:/ps/trunk/build/premake/premake4 build/premake/premake4]. The modifications fix a number of bugs and missing features in the 4.3 release.
+
+== Premake in 0 A.D. ==
+
+0 A.D. uses two custom Lua scripts to generate its workspaces with Premake:
+ * [source:/ps/trunk/build/premake/premake4.lua build/premake/premake4.lua] - this is the main script which controls compiler, linker, and workspace behavior on different platforms.
+ * [source:/ps/trunk/build/premake/extern_libs4.lua 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:
+{{{
+#!sh
+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 [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).
+ * `vs2010` - [http://www.microsoft.com/visualstudio/en-us/products/2010-editions Visual Studio 2010] (or [http://www.microsoft.com/visualstudio/en-us/products/2010-editions/express Express])
+ * `vs2008` - Visual Studio 2008 (or Express)
+ * `vs2005` - Visual Studio 2005 (or Express)
+ * `gmake` - [http://www.gnu.org/software/make/ GNU Make]
+ * `xcode3` - [https://developer.apple.com/xcode/ Apple Xcode 3]
+ * `codeblocks` - [http://www.codeblocks.org/ 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 mode
+ * '''`atlas` - Include Atlas scenario editor projects'''
+ * '''`collada` - Include COLLADA projects (requires FCollada library)'''
+ * `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)
+ * `without-fam` - Disable use of FAM API on Linux
+ * `without-audio` - Disable use of OpenAL/Ogg/Vorbis APIs
+ * `without-nvtt` - Disable use of NVTT
+ * `without-tests` - Disable generation of test projects
+ * `without-pch` - Disable generation and usage of precompiled headers
+ * `with-system-nvtt` - Search standard paths for nvidia-texture-tools library, instead of using bundled copy
+ * `with-system-enet` - Search standard paths for libenet, instead of using bundled copy
+ * `with-system-mozjs185` - Search standard paths for libmozjs185, instead of using bundled copy
+ * `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 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.
+
+The `update-workspaces` scripts will pass arguments through to Premake:
+{{{
+#!sh
+./update-workspaces.sh --without-tests --with-system-mozjs185
+}}}
+
+== Building Premake ==
+
+For Windows developers, we bundle a pre-built, 32-bit [/ps/trunk/build/premake/premake4/bin/release/premake.exe 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 [source:/ps/trunk/build/workspaces/update-workspaces.sh 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 the Makefile(s) or C source code directly, as these are automatically generated from the scripts by Premake. 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 [http://industriousone.com/building-premake Building Premake] for more information.