A Premake configuration is a set of flags and options to apply to the build. Premake defines two configurations by default, named “Debug” and “Release”, but you can override these by defining a new list for your project.

project.configs = { "Debug", "ReleaseWithSymbols", "Release" }

Configuration values may be set on a particular configuration or on all configurations at once. Here is an example of each:

-- This defines the symbol "TRACE" in all configurations
package.defines = { "TRACE" }

-- This defines the symbol "DEBUG" just for the Debug config
package.config["Debug"].defines = { "DEBUG" }

Package Target

The target specifies the base filename for the compiled binary, and by default is the same as the package name. The target filename is decorated depending on the platform and type of file, as shown below:

	Executable	Shared Library	Static Library
Windows	somefile.exe	somefile.dll	somefile.lib
Linux	somefile	libsomfile.so	libsomefile.a

You may also include path information, relative to the appropriate target directory as set in the project file. For instance, this will compile the binary to ./bin/MyPackage/debug/mypackage.exe:

project.bindir = "bin"

package.kind = "exe"
package.config["Debug"].target = "MyPackage/debug/mypackage"

You can override the file extension applied to the target by setting targetextension, or the prefix by settings targetprefix. This example will create the binary file myplugin.zmf on all platforms.

package.name = "MyPlugin"
package.kind = "dll"
package.target = "myplugin"
package.targetprefix = ""
package.targetextension = "zmf"

Build Flags

package.buildflags = { "no-exceptions", "no-rtti" }

The build flags control the options passed to the compiler. They are translated (or ignored) for the target toolset. The build flags are always specified as a list and must be enclosed in curly braces, even for a single value. A complete list of build flags follows:

dylib	on Mac OS X produce a dylib instead of a Posix-style shared library
extra-warnings	sets the maximum warning level for the given compiler
fatal-warnings	treat warnings as errors
managed	enables Managed C++ (.NET only)
native-wchar no-native-wchar	enable or disable native support for the wchar type. If not specified, uses the toolset default.
no-64bit-checks	disables 64-bit portability warnings
no-edit-and-continue	disables support for Edit and Continue
no-exceptions	disables C++ exception support
no-frame-pointer	disables generation of frame pointers. Frame pointers are required for stack traces; removing them will reduce the size of release builds
no-import-lib	prevents the generation of Windows import libraries for DLL targets
no-main	use WinMain() on Windows, otherwise will default to main()
no-pch	disables precompiled headers
no-rtti	disables C++ RTTI support
no-symbols	disables generation of debugging symbols
optimize	performs a balanced set of optimizations
optimize-size	optimizes for the smallest file size
optimize-speed	optimizes for the fastest performance
static-runtime	will perform a static link against the standard runtime libraries
unicode	enables Unicode strings
unsafe	enables unsafe code in .NET applications

If the existing build flags are not sufficient, there is an additional list of build options. These are text values that are passed without translation to the compiler command line. Here’s an example from a wxWidgets application I wrote:

if (linux) then
  package.buildoptions = { "`wx-config --cxxflags` -W -Wall -ansi -pedantic" }
end

There is a similar list to pass options to the linker:

if (linux) then
  package.linkoptions = { "`wx-config --ldflags`" }
end

Defines

package.defines = { "DEBUG", "API=__declspec(dllexport)" }

The defines provide a list of preprocessor symbols to the compiler. You may include simple symbol definitions or, if the language supports it, symbol assignments. Defines are always specified as a list and must be enclosed in curly braces, even for a single value.

Include Paths

package.includepaths = { "../Include", "libs/zlib" }

The include paths adds directories to the compiler’s include file search path.

Links

package.links = { "MyRenderer", "GL" }

The links provide a list of libraries (or assemblies in .NET) to be linked against. Specify the base library filenames without any platform-specific decorations.

If the library is being built as part of the current project (ie. it is a sibling package), you should specify the name of the library package, not the name of the library. Premake will automatically determine the appropriate library path and filename, and will also add a dependency to the project to ensure the packages are built in correct order. As an example, suppose you have two packages in your project, MyExecutable and MyLibrary. The Premake script for your executable should look like this:

package.links = { "MyLibrary" }

Not this; Premake will figure out the names and paths automatically:

package.links = { "../lib/MyLibrary" }

Library Paths

package.libpaths = { "../PackageB/Lib" }

The library paths provide additional search directories to the linker. The paths specified by project.bindir and project.libdir always included by default.

If you know the name of the library but aren’t sure where it will be installed, you can use Premake’s findlib() function:

package.libpaths = { findlib("X11") }

Object Directory

You can control the location of intermediate files with objdir:

-- Set for all configurations
package.objdir = "../obj/MyPackage"

-- Set individually
package.config["Debug"].objdir = "../obj/MyPackage/Debug"
package.config["Release"].objdir = "../obj/MyPackage/Release"

By default Premake will place intermediate files in obj/config_name.

Precompiled Headers

Precompiled headers are supported by the pchheader and pchsource settings, which indicate which files should be precompiled.

package.pchheader = "afxwin.h"
package.pchsource = "afxwin.cpp"

If these values are not set the toolset default settings will be used. These values are currently recognized by the Visual Studio and Code::Blocks generators; they are ignored everywhere else.

The “no-pch” build flag (see Build Flags, above) overrides these values and disables precompiled headers.

Build Actions

Some environments, notably .NET, allow a build action to control how the file is handled by the build process. Premake tries to set intellegent default actions based on the file extension and generally does a good job. When the defaults aren’t sufficient, you can set the build action for a single file, or match a set of files. Here are examples of both:

-- "Content" is copied to the bin directory (C#)
package.config["MySchema.xml"].buildaction = "Content"

-- "EmbeddedResource" is compiled into the binary
package.config[matchfiles("*.png")].buildaction = "EmbeddedResource"

The possible values for buildaction depend on the target language. For .NET languages, the values include “None”, “Compile”, “Content”, and “EmbeddedResource”.