Changes between Version 23 and Version 24 of premake


Ignore:
Timestamp:
Nov 1, 2017, 7:36:52 PM (6 years ago)
Author:
Itms
Comment:

Update for premake5 and recent changes

Legend:

Unmodified
Added
Removed
Modified

  • premake

    v23 v24  
    11= Premake =
    22
    3 [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).
     3[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).
    44
    5 '''Note:''' 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. (see #1518)
     5'''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.
    66
    77== Premake in 0 A.D. ==
    88
    990 A.D. uses two custom Lua scripts to generate its workspaces with Premake:
    10  * [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.
    11  * [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.
     10 * [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.
     11 * [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.
    1212These scripts are well commented, describing the reasoning behind most of the logic.
    1313
    … …  
    1515{{{
    1616#!sh
    17 premake4/bin/release/premake4 --file="premake4.lua" --outpath="../workspaces/gcc/" gmake
     17premake5/bin/release/premake5 --file="premake5.lua" --outpath="../workspaces/gcc/" gmake
    1818}}}
    19 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.
     19This 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.
     20
     21'''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.
    2022
    2123See [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.
    … …  
    2628 * `vs2013` - Visual C++ 2013
    2729 * `gmake` - [http://www.gnu.org/software/make/ GNU Make]
    28  * `xcode3` - Apple Xcode 3
    2930 * `xcode4` - [https://developer.apple.com/xcode/ Apple Xcode 4]
    30  * `codeblocks` - [http://www.codeblocks.org/ Code::Blocks]
    31 '''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.
     31'''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.
    3232
    3333=== Premake options ===
    … …  
    3636 * `android` - Use non-working Android cross-compiling mode
    3737 * '''`atlas` - Include Atlas scenario editor projects'''
    38  * '''`collada` - Include COLLADA projects (requires FCollada library)'''
     38 * `collada` is ''deprecated'' and was needed with premake4 to build the COLLADA project that we rely upon.
    3939 * `coverage` - Enable code coverage data collection (GCC only)
    4040 * `gles` - Use non-working OpenGL ES 2.0 mode
    … …  
    5757 * `build-shared-glooxwrapper` - Rebuild glooxwrapper DLL for Windows. Requires the same compiler version that gloox was built with
    5858 * `use-shared-glooxwrapper` - Use prebuilt glooxwrapper DLL for Windows
     59 * `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.
    5960
    6061 * `bindir` - Directory for executables (typically `/usr/games`); default is to be relocatable
    … …  
    6465'''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.
    6566
    66 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.
     67The 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.
    6768
    6869The `update-workspaces` scripts will pass arguments through to Premake:
    … …  
    7475== Building Premake ==
    7576
    76 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.
     77For 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.
    7778
    7879For *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.
    7980
    80 == Modifying Premake ==
     81== Extending Premake ==
    8182
    82 To modify Premake's behavior, you typically modify the Lua scripts within [source:/ps/trunk/build/premake/premake4 build/premake/premake4]. You shouldn't modify its [source:/ps/trunk/build/premake/premake4/build build files] or [source:/ps/trunk/build/premake/premake4/src/host/scripts.c 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.
     83To 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].
    8384
    84 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.
    85 
    86 == Generating Premake's workspaces ==
    87 
    88 Premake's own workspaces and Makefiles are mostly generated using a Premake binary and the contents of [source:/ps/trunk/build/premake/premake4/premake4.lua 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):
    89 {{{
    90 ./bin/release/premake4 --os=linux --to=build/gmake.unix/ gmake
    91 }}}
    92 This will generate a Linux-compatible Makefile in the [source:/ps/trunk/build/premake/premake4/build/gmake.unix 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.'''
     85Refer to [https://github.com/premake/premake-core/wiki/Extending-Premake the official documentation] for more information on the matter.