Home » Premake » User Guide » Scripting Reference

configuration

The configuration function limits the subsequent build settings to a particular environment.

configuration { "keywords" }

The configuration functions acts as a filter. Any settings that appear after this function in the script will be applied only in those environments that match all of the listed keywords. See below for some usage examples.

Parameters

keywords is a list of identifiers (see below). If all of these identifiers are present in the current runtime environment, then the settings following the configuration call will be applied. If any of the identifiers is not the current environment the settings will be ignored.

The following table lists the available sources for keywords. Keywords are not case-sensitive.

Configuration names
Any of the configuration names supplied to the configurations function.
Action names
Any action name, such as vs2005 or gmake. See the Quick Start for a complete list.
Operating system names
Any of the operating system identifiers, such as windows or macosx, as returned by os.get.
Platform names
Any of the platform identifiers, such as ps3 or xbox360. See platforms for a complete list.
Target kind
Any of the target kinds, such as ConsoleApp or SharedLib. See kind for a complete list.
Command-line options
Any of the available command-line options or the option values, whether built-in or custom to the project.
File names
Although currently very limited, some settings can be applied to specific files.

In addition to the terms listed above, you may use the * and ** wildcards to match more than one term or file. You may also use the modifiers not and or to build more complex conditions. See the examples below for more information.

Return Value

The function returns the current configuration object; see The Configuration Block below for more information on the structure of this object.

Examples

Define a new symbol which applies only to debug builds; assumes a configuration named "Debug" was defined as part of the solution.

configuration "Debug"
  defines { "_DEBUG" }

Define a symbol only when targeting Visual Studio 2005.

configuration "vs2005"
  defines { "VISUAL_STUDIO_2005" }

Wildcards can be used to match multiple terms. Define a symbol for all versions of Visual Studio.

configuration "vs*"
  defines { "VISUAL_STUDIO_2005" }

Add a suffix to the debug versions of libraries.

configuration { "Debug", "SharedLib or StaticLib" }
  targetsuffix "_d"
 
-- ...or...
configuration { "Debug", "*Lib" }
  targetsuffix "_d"

Although support is currently quite limited (only buildaction works so far), you may also apply settings to a particular file or set of files. This example sets the build action for all PNG image files.

configuration "*.png"
  buildaction "Embed"

In the case of files you may also use the ** wildcard, which will recurse into subdirectories.

configuration "**.png"
  buildaction "Embed"

If multiple keywords are specified, they will be treated as a logical AND. All terms must be present for the block to be applied. This example will apply the symbol only for debug builds on Mac OS X.

configuration { "debug", "macosx" }
  defines { "DEBUG_MACOSX" }

Multiple terms must use Lua's curly bracket list syntax.

You can use the or modifier to match against multiple, specific terms.

configuration "linux or macosx"
  defines { "LINUX_OR_MACOSX" }

You can also use not to apply the settings to all environments where the identifier is not set.

configuration "not windows"
  defines { "NOT_WINDOWS" }

Finally, you can reset the configuration filter and remove all active keywords by passing the function an empty table.

configuration {}

The Configuration Block

Each call to configuration function creates a new configuration block object. Unless you really know what you are doing, you should treat this object as read-only and use the Premake API to make any changes. The configuration block object contains the following values:

buildaction
A build action.
buildoptions
A list of compiler options.
defines
A list of compiler symbols.
excludes
A list of excluded files.
files
A list of files.
flags
A list of build flags.
implibdir
The import library directory.
implibextension
The import library file extension.
implibname
The import library base file name.
implibprefix
The import library file name prefix.
implibsuffix
The import library file name suffix.
includedirs
A list of include file search directories.
keywords
A list of keywords associated with the block.
kind
The target kind.
libdirs
A list of library search directories.
linkoptions
A list of linker options.
links
A list of libraries or assemblies to link against.
objdir
The objects and intermediate files directory.
pchheader
The target file name for precompiled header support.
pchsource
The target source file name for precompiled header support.
prebuildcommands
A list of pre-build commands.
prelinkcommands
A list of pre-link commands.
postbuildcommands
A list of post-build commands.
resdefines
A list of symbols for the resource compiler.
resincludedirs
A list of include file search paths for the resource compiler.
resoptions
A list of resource compiler options.
targetdir
The target output directory.
targetextension
The target file extension.
targetname
The target base file name.
targetprefix
The target file name prefix.
targetsuffix
The target file name suffix.
terms
The filter terms passed to the configuration function to create the block (i.e. "Debug").
Anonymous | 04 Mar 2010 14:57

version 4.2.1 add the value
terms
The terms used to create the configuration block

Useful to save and refine the current configuration

--...
function addDebugDefines()
  cfg = configuration()
  -- restrain to Debug only
  configuration{ cfg.terms, "Debug" }
     --...
     define {"SOME_DEBUG_FLAG"}
  -- restore previous config
  configuration(cfg.terms)
--...
end
Anonymous | 12 Feb 2011 10:47

Is it possible to add a configuration filter based "kind" at the solution level? I've been trying to do something like the following at the solution level:

for _, plat in ipairs(platforms()) do
    configuration { plat, "ConsoleApp" }
        targetdir ("bin/" .. plat)
    configuration { plat, "StaticLib" }
        targetdir ("lib/" .. plat)

which should output all my static libs to "lib/x32", "lib/x64" etc and binaries to "bin/x32", "bin/x64" etc, but the projects end up using the default output directory for everything. If I do this on a per-project basis, it seems to work as expected.

Is this a bug, or am I doing something wrong? Disclaimer: I'm no Lua expert.