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 Quick Start to begin learning how to use and develop with Premake.

Generating the Project Files

If you downloaded one of the official source code release packages, the project files have already been generated for you, and may be found in the build/ directory. Skip ahead to the next section to learn about the important differences between the build configurations.

Premake's Mercurial repository does not contain any project files. Instead, use an existing copy of Premake to generate the files for your particular toolset and environment.

Once you have a working Premake installed, embed the scripts by opening a console or terminal to the source code directory and running the command

premake4 embed

Now generate the project files with a command like:

premake4 gmake    # for GNU makefiles using GCC
premake4 vs2008   # for a Visual Studio 2008 solution

Use the --help option to see all of the available targets. You now have a solution/makefile/workspace that you can load and build.

Note that when working against the Mercurial sources it is a good idea to refresh the embedded scripts after each update.

$ hg pull -u
$ premake4 embed

See Debug vs. Release Modes below for an explanation (and maybe eventually I'll think of a better way to do this).

Building the Source Code

Premake can be built in either "release" (the default) or "debug" modes. If you are using Makefiles (as opposed to an IDE), you can choose which configuration to build with the config argument:

make               # build in release mode, both versions
make config=debug  # build in debug mode, when generated with Premake 4.x
make CONFIG=Debug  # build in debug mode, when generated with Premake 3.x

If you do not supply a config argument, release mode will be used. IDEs like Visual Studio provide their own mechanism for switching build configurations.

Debug vs. Release Modes

A significant portion of Premake is written in Lua. For release builds (the default) this has no impact, just build as normal and go.

When built in Debug mode, Premake will read its Lua scripts from the disk at startup, enabling compile-less code/test iterations, and therefore faster development. But it needs a little help finding the scripts. You can use the /scripts command line argument, like so:

premake4 /scripts=~/Code/premake4/src gmake

Or set a PREMAKE_PATH environment variable:

PREMAKE_PATH=~/Code/premake4/src

You need to specify the location of the Premake src/ directory, the one containing _premake_main.lua.

Embedding the Scripts

In release builds, Premake uses a copy of the scripts embedded into static strings: see src/host/scripts.c. If you modify any of the core Lua scripts (anything ending in .lua), you must also update these embedded strings before your changes will appear in the release mode build.

You can update these strings by using the embed action, which is part of Premake's own build script.

premake4 embed

This command embeds all of the scripts listed in _manifest.lua into src/host/scripts.c. The next release build will include the updated scripts.

CONFUSED?

The inclusion of the Lua scripts throws a wrench in things, and I certainly understand if you have questions. I'll be glad to help you out. Leave a note in the forums (the preferred approach), join the mailing list, or contact me directly. Your questions will help me improve these instructions.

Yes, confused is right.

How do I build the .lua file in the first place if I only have .sln files or .vcproj files?

That's the bit you have to write yourself, the "program" that describes the project. Feel free to ask for help over in the forums.

The README or INSTALL file, and related docs, would really benefit from making explicit how to:
- build the software
- run the regression tests
- install the software

Currently, they just say "build with make config=release", but do not explain what directory you should be in before invoking that. And there isn't a word about test and install.

I too find this page a bit confusing. What I'd like to do is build premake -- I don't have it yet, all I have is some source I downloaded. The relevant text says, "the project files have already been generated for you, and may be found in the build/ directory. Skip ahead to the next section...". I take 'next section' to mean the "Building the source Code" section. Every section after that seems to presume that I already have premake4, which is odd to me.

But brushing that aside, I cd into the build directory, and type 'make'. But no makefile is found. There are a lot of subdirectories such as 'gmake.unix'. They aren't mentioned in the instructions, but I'll cd into that one and give it a shot. I type 'make' there.

It starts building! I think it built. Now what? How do I install? Should I type 'make install'? Nope, 'make install' is not a valid target.

I poke around, but it looks like I didn't generate a binary at all, just a lot of object files into an 'obj' directory. The rest of the instructions above are no help at all. In fact, the "Embedding the Scripts" section is utterly confusing. I came to this page with the goal of building premake, but there's not enough information here to help me achieve that goal.

I tried the BUILD.txt file in the codebase itself, but the content is fairly similar. It's not focused on the goal of helping me build and use this product. (I'm not a developer of premake; I want to use it, and the downloadable binary didn't work for me.)