Configurations

A configuration is a collection of flags and options to apply to a build, including build flags, header file and library search directories, and more. Each solution defines its own list of configurations. The most common configuration set, which is usually provided by default by most IDEs, is "Debug" and "Release". Visual Studio and other IDEs provide facilities to quickly switch between configurations; Premake-generated makefiles allow the configuration to be specified with a command-line parameter.

Updated information is available on the new Premake wiki.

Specifying Configurations

At the solution level, specify your list of possible configurations by calling the configurations function and passing it a list of names.

solution "MySolution"
  configurations { "Debug", "Release" }

You are not limited to these two standard names. For instance, if your project can be built as both as both static or shared libraries, you might use this instead:

  configurations { "DebugLib", "DebugDLL", "ReleaseLib", "ReleaseDLL" }

Some features of Premake, such as selecting a configuration from the command line, are easier if you avoid spaces. However, spaces are allowed in configuration names.

Using Configurations

Premake provides a great deal of flexibility when it comes to configuring your build: you can apply settings across an entire solution, a project, or to a targeted combination of configuration and toolset. The configuration function is used to apply settings to a particular build environment.

For example, you can define a symbol across all configurations of all projects by setting it at the solution level, before any filters are enabled.

solution "MySolution"
  configurations { "Debug", "Release" }
 
  defines { "MY_SYMBOL" }

Or, using the configuration function, you can limit it to a particular configuration.

solution "MySolution"
  configurations { "Debug", "Release" }
 
  configuration "Debug"
    defines { "MY_SYMBOL" }

The same rules hold true at the project level.

project "MyProject"
 
   defines { "TRACE" }         -- this will be applied to every configuration
 
   configuration "Debug"
      defines { "DEBUG" }      -- this will only be applied to Debug builds

When values are supplied at multiple levels, list fields (like defines above) are concatenated while single-value fields (like language) are overridden. Project values take precedence over solution values, and will appear after the solution values in lists. Values at the same level are evaluated in the order in which they are encountered in the script.

This is just an overview of configuration filtering. For more details, including a list of the available filter keywords, see the documentation for the configuration function.

(I can see where this topic might be a bit confusing for newcomers, and I welcome suggestions for improving this text. Feel free to leave your ideas for improvements in the comments; questions should be asked in the forums).