Building Premake

If you downloaded a prebuilt binary package you can skip this page, which discusses how to build the Premake source code. Jump ahead to one of the next sections to learn how to develop with Premake.

Using a Source Code Package

If you have one of the official source code packages, you'll find that project files for a variety of toolsets have already been generated for you in the build/ folder. Find the right set for your platform and toolset and build as you normally would (i.e. run make). The resulting binaries will be placed in the top-level bin/ folder.

Skip ahead to the next section to learn more about using the source version of Premake.

Using the Git Code Repository

If you are planning to make changes or contribute to Premake, working directly against the source code repository is the way to go. Premake 5's source code is housed right here on GitHub. To get the source code, find the "Clone" option in the sidebar to the left and follow the instructions there.

Note that after you do "git clone " for the main repository, you must also bring down submodules -- otherwise many unit tests (when you get to those) will fail because the modules are missing from your repo. To bring down submodules, use the following additional commands (make sure your current working directory is premake-core/modules)

git submodule update --init monodevelop
git submodule update --init d
git submodule update --init codelite
git submodule update --init xcode

We use Premake to help us build Premake, both to generate the project files for our tools of choice, and also to embed the scripts into a C source file that can be built into the final executable. To do either of these things, you will need to have a working Premake executable on your system.

The easiest way to get one is by downloading prebuilt binary package. If that isn't possible, or if not binary is provided for your platform, you can build from a Premake 4.x source package as described above; they include pre-generated project files, allowing you to skip this bootstrapping step.

Once you have a working Premake available, you can generate the project files for your toolset by running a command like the following in the top-level Premake directory:

$ premake5 gmake  # for makefiles
$ premake5 vs2012 # for a Visual Studio 2012 solution
$ premake --help  # to see a list of supported toolsets

If this is the first time you have built Premake, or if you have made changes to the Lua scripts, you should prepare them to be embedded into the Premake executable.

$ premake5 embed

This creates a C file (at src/host/scripts.c) which contains all of the Lua scripts as static string buffers. These then get compiled into the executable, which is how we get away with shipping a single file instead of a whole bunch of scripts.

You should now have a solution/makefile/workspace in the top-level folder, which you can go ahead and build. The resulting binaries will placed into the bin/ folder.

Running the Tests

Once you have built an executable, you can verify it by running Premake's unit test suites. From the top-level Premake folder, run:

$ bin/debug/premake5 test    # or...
$ bin/release/premake5 test

Runtime Script Loading

If you are modifying or extending Premake, you can skip the embedding and compilation steps and run the scripts directly from the disk. This removes the build from the change-build-test cycle and really speeds up development.

If you are running Premake from the top of its own source tree (where its premake5.lua is located) you will get this behavior automatically. If you are running Premake from some other location, use the --scripts option to provide the path to that top-level folder:

$ bin/release/premake5 --scripts=../path/to/premake test

If you find yourself doing this repeatedly, or if you want Premake to be able to find other, custom scripts, you can also set a search path with the PREMAKE_PATH environment variable. Set it just like you would set your system PATH variable.

Once your changes are complete and you are ready to distribute them to others, embed them into the executable and rebuild:

$ bin/release/premake5 embed
$ make config=release   # or via Visual Studio, etc.

Stuck?

Give us a shout over in the Developer Forums and we'll be glad to help you out.