configuration

Home > [Scripting Reference](Scripting Reference) > configuration

---

configuration

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

#!lua
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](Premake 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.
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.

#!lua
configuration "Debug"
  defines { "_DEBUG" }

Define a symbol only when targeting Visual Studio 2005.

#!lua
configuration "vs2005"
  defines { "VISUAL_STUDIO_2005" }

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

#!lua
configuration "vs*"
  defines { "VISUAL_STUDIO_2005" }

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.

#!lua
configuration "*.png"
  buildaction "Embed"

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

#!lua
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.

#!lua
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.

#!lua
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.

#!lua
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.

#!lua
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").