This section describes the functions and variables available to Premake scripts.
Premake is built on Lua, so everything in the Lua Reference Manual applies to a Premake script. Premake adds the ability to define solutions, projects, and configurations, as well as functions useful for build configuration tasks.
You may also want to check out LuaForge for a wide assortment of Lua add-on modules.
The _ACTION global variable stores the name of the action to be performed on
this execution run. As an example, if this command line was used to launch
Premake...
$ premake4 vs2005
...then _ACTION will be set to "vs2005". If there is no action (for instance,
if the command was premake4 /help) this variable will be nil.
The _ARGS global variable stores any arguments to the current action. As an
example, if this command line was used to launch Premake...
$ premake4 vs2005 alpha beta
...then _ARGS[1] will be set to "alpha" and _ARGS[2] to "beta". If there
are no arguments this array will be empty.
The _OPTIONS global variable lists the current set of command line options and their values, if any. For more information, see Command Line Arguments.
The _PREMAKE_COMMAND global variable stores the full path to the Premake
executable.
Introduced in Premake 4.4.
The _GENIE_VERSION global variable stores the current GENie version, i.e.
62.
The _GENIE_VERSION_STR global variable stores the current GENie version with
git commit hash.
The _SCRIPT global variable stores the full path of the currently executing
script.
The _WORKING_DIR global variable stores the current working directory at the
time Premake was launched.
Introduced in Premake 4.4.
The buildaction function specifies how a file or set of files should be treated during the compilation process. It is usually paired with a configuration filter to select a file set. If no build action is specified for a file a default action will be used, based on the file's extension.
Build actions are currently only supported for .NET projects, and not for C or C++.
Updated information is available on the new Premake wiki.
Solutions, projects, and configurations.
action is one of:
Compile : Treat the file as source code; compile and link it.
Embed : Embed the file into the target binary as a resource.
Copy : Copy the file to the target directory.
None : Do nothing with this file.
Embed all PNG image files into the target binary.
configuration "**.png" buildaction "Embed"
The buildoptions function passes arguments directly to the compiler command line without translation.
buildoptions { "options" }
If a project includes multiple calls to buildoptions the lists are concatenated, in the order in which they appear in the script.
Solutions, projects, and configurations.
options is a list of compiler flags and options, specific to a particular compiler.
Use pkg-config style configuration when building on Linux with GCC. Build
options are always compiler specific and should be targeted to a particular
toolset.
configuration { "linux", "gmake" } buildoptions { "`wx-config --cxxflags`",
"-ansi", "-pedantic" }
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.
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.
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.
The function returns the current configuration object; see The Configuration Block below for more information on the structure of this object.
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" }
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.
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.
startproject : The default startup project (for VS2005+)
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").
The configurations function specifies the set of build configurations, such as "Debug" and "Release", for a solution.
configurations { "names" }
A configuration encapsulates a collection of build settings, allowing the developer to easily switch between them. "Debug" and "Release" are the most common configurations, the former providing debugging information, and the latter providing optimizations.
The list of configurations must be specified before any projects are defined, and once a project has been defined the configuration list may no longer be changed.
Updated information is available on the new Premake wiki.
Solutions only.
names is a list of configuration names. Spaces are allowed, but may make using certain Premake features, such as a command-line configuration selection, more difficult.
The function returns the current list of configuration names for the active solution.
Specify debug and release configurations for a solution.
solution "MySolution" configurations { "Debug", "Release" }
Add additional configurations for a dynamic link library version.
configurations { "Debug", "Release", "DebugDLL", "ReleaseDLL" }
You can retrieve the current list of configurations by calling the function with no parameters.
local cfgs = configurations()
The debugargs function specifies a list of arguments to pass to the application when run under the debugger.
Note that this settings is not implemented for Xcode 3, which requires a per-user configuration file in order to make it work.
In Visual Studio, this file can be overridden by a per-user configuration file (such as ProjectName.vcproj.MYDOMAIN-MYUSERNAME.user). Removing this file (which is done by Premake's clean action) will restore the default settings.
Added in Premake 4.4.
Solutions, projects, and configurations.
args is a Lua list of arguments to provide to the executable while debugging.
configuration "Debug" debugargs { "--append", "somefile.txt" }
The debugdir function sets the working directory for the integrated debugger.
Note that this settings is not implemented for Xcode 3, which requires a per-user configuration file in order to make it work.
In Visual Studio, this file can be overridden by a per-user configuration file (such as ProjectName.vcproj.MYDOMAIN-MYUSERNAME.user). Removing this file (which is done by Premake's clean action) will restore the default settings.
Added in Premake 4.4.
Solutions, projects, and configurations.
path is the path to the working directory, relative to the currently executing script file.
configuration "Debug" debugdir "bin/debug"
The defines function adds preprocessor or compiler symbols to a project.
If a project includes multiple calls to defines the lists are concatenated, in the order in which they appear in the script.
Solutions, projects, and configurations.
symbols specifies a list of symbols to be defined.
Define two new symbols in the current project.
defines { "DEBUG", "TRACE" }
Symbols may also assign values.
defines { "CALLSPEC=__dllexport" }
The deploymentoptions function passes arguments directly to the deployment tool command line without translation.
deploymentoptions { "options" }
If a project includes multiple calls to deploymentoptions the lists are concatenated, in the order in which they appear in the script.
Deployment options are currently only supported for Xbox 360 targets.
Solutions, projects, and configurations.
options is a list of deployment tools flags and options.
The excludes function removes files, added with the files function, from a project.
If a project includes multiple calls to excludes the lists are concatenated.
Files may be set on the solution, project, and configuration level. However, only project-level file lists are currently supported.
file_list specifies one or more file patterns, separated by commas. File paths should be specified relative to the location of the script file. File patterns may contain the ***** wildcard to match against files in the current directory, or the ****** wildcard to perform a recursive match.
Add all C files in a directory, and then exclude a specific file.
files { "*.c" } excludes { "a_file.c" }
Add an entire directory tree of C files, and then exclude one particular directory.
files { "**.c" } excludes { "tests/*.c" }
The files function adds files to a project.
If a project includes multiple calls to files the lists are concatenated, in the order in which they appear in the script.
Files may be set on the solution, project, and configuration level. However, only project-level file lists are currently supported.
file_list specifies one or more file patterns, separated by commas. File paths should be specified relative to the location of the script file. File patterns may contain the ***** wildcard to match against files in the current directory, or the ****** wildcard to perform a recursive match.
If a wildcard matches more files than you would like, you may filter the list using the excludes function.
Add two files to the current project.
files { "hello.cpp", "goodbye.cpp" }
Add all C++ files from the src/ directory to the project.
Add all C++ files from the src/ directory, and any subdirectories.
The flags function specifies build flags to modify the compiling or linking process.
If a project includes multiple calls to flags the lists are concatenated, in the order in which they appear in the script.
Updated information is available on the new Premake wiki.
Solutions, projects, and configurations.
flags_list is a list of string flag names; see below for a list of valid flags. The flag values are not case-sensitive. Flags that are not supported by a particular platform or toolset are ignored.
EnableSSE, EnableSSE2 : Use the SSE instruction sets for floating point math.
EnableMinimalRebuild : Enable Visual Studio's minimal rebuild feature. This will also disable multiprocessor compilation.
ExtraWarnings : Sets the compiler's maximum warning level.
FatalWarnings : Treat warnings as errors.
FloatFast : Enable floating point optimizations at the expense of accuracy.
FloatStrict : Improve floating point consistency at the expense of performance.
Managed : Enable Managed C++ (.NET).
MFC : Enable support for Microsoft Foundation Classes.
NativeWChar, NoNativeWChar : Enable or disable support for the wchar data type. If no flag is specified, the toolset default will be used.
No64BitChecks : Disable 64-bit portability warnings.
NoEditAndContinue : Disable support for Visual Studio's Edit-and-Continue feature.
NoExceptions : Disable C++ exception support.
NoFramePointer : Disable the generation of stack frame pointers.
NoIncrementalLink : Disable support for Visual Studio's incremental linking feature.
NoImportLib : Prevent the generation of an import library for a Windows DLL.
NoManifest : Prevent the generation of a manifest for Windows executables and shared libraries.
NoMultiProcessorCompilation : Disable multiprocessor compilation in Visual Studio.
NoPCH : Disable precompiled header support. If not specified, the toolset default behavior will be used. Also see pchheader and pchsource.
NoRTTI : Disable C++ runtime type information.
Optimize : Perform a balanced set of optimizations.
OptimizeSize : Optimize for the smallest file size.
OptimizeSpeed : Optimize for the best performance.
SEH : Enable structured exception handling.
StaticRuntime : Perform a static link against the standard runtime libraries.
Symbols : Generate debugging information.
Unicode : Enable Unicode strings. If not specified, the default toolset behavior is used.
Unsafe : Enable the use of unsafe code in .NET applications.
UnsignedChar : Force char type to be unsigned.
WinMain : Use WinMain() as the program entry point for Windows applications, rather than the default main().
If the existing flags are not sufficient, you can also pass tool-specific arguments directly to the compiler or linker using buildoptions and linkoptions.
A common configuration: enable debugging symbols in the Debug configuration, and optimize the Release configuration.
configuration "Debug" flags { "Symbols" } configuration "Release"
flags { "Optimize" }
You can specify multiple flags.
flags { "Symbols", "ExtraWarnings", "FatalWarnings" }
The framework function selects a .NET framework version.
This value currently is only applied to Visual Studio 2005 or later, and GNU makefiles using Mono. If no framework is specified the toolset default is used.
Solutions and projects.
version is one of:
Use the .NET 3.0 Framework.
The iif function implements an immediate "if" clause, returning one of two possible values.
result = iif(condition, trueval, falseval)
condition is the logical condition to test. trueval is the value to return if the condition evaluates to true, falseval if the condition evaluates false.
trueval is the condition evaluates true, falseval otherwise.
result = iif(os.is("windows"), "is windows", "is not windows")
Note that all expressions are evaluated before the condition is checked; the following expression can not be implemented with an immediate if because it may try to concatenate a string value.
result = iif(x ~= nil, "x is " .. x, "x is nil")
The imageoptions function passes arguments directly to the image tool command line without translation.
imageoptions { "options" }
If a project includes multiple calls to imageoptions the lists are concatenated, in the order in which they appear in the script.
Image options are currently only supported for Xbox 360 targets.
Solutions, projects, and configurations.
options is a list of image tools flags and options.
The imagepath function sets the file name of the deployment image produced by the build.
This value is currently only used by the Xbox 360.
Solutions, projects, and configurations.
path is the full path for the image file, relative to the currently executing script file.
The implibdir function specifies the import library output directory. Import libraries are generated for Windows DLL projects.
By default, the generated project files will place the import library in the same directory as the compiled binary. The implibdir function allows you to change this location.
Solutions, projects, and configurations.
path is the output directory for the library, relative to the currently executing script file.
implibname implibextension implibprefix implibsuffix
The implibextension function specifies the import library file extension. Import libraries are generated for Windows DLL projects.
By default, the toolset static library file extension will be used (.lib with Windows tools, .a with GNU tools). The implibextension function allows you to change this default.
Solutions, projects, and configurations.
ext is the new file extension, including the leading dot.
implibname implibdir implibprefix implibsuffix
The implibname function specifies the import library base file name. Import libraries are generated for Windows DLL projects.
By default, the target name will be used as the import library file name. The implibname function allows you to change this default.
Solutions, projects, and configurations.
name is the new base file name.
implibdir implibextension implibprefix implibsuffix
The implibprefix function specifies the import library file name prefix. Import libraries are generated for Windows DLL projects.
By default, the system naming convention will be used: no prefix on Windows, a prefix of "lib" (as in libMyProject.a) on other systems. The implibprefix function allows you to change this default.
Solutions, projects, and configurations.
prefix is the new file name prefix.
implibname implibdir implibextension implibsuffix
The prefix may also be set to an empty string for no prefix.
The implibsuffix function specifies a file name suffix for the import library base file name. Import libraries are generated for Windows DLL projects.
Solutions, projects, and configurations.
suffix is the new filename suffix.
implibname implibdir implibprefix implibextension
-- Add "-d" to debug versions of files configuration "Debug" implibsuffix
"-d"
The include function looks for a file named premake4.lua in a specified directory, and includes it in the current script.
This is equivalent to:
dofile "directory/premake4.lua"
This allows you to specify each project in its own premake4.lua file, and then easily include them into a solution, or multiple solutions.
directory is the path to the included directory, relative to the currently executing script file. The directory must contain a premake4.lua file, or an error will occur. If you wish to call a file other than premake4.lua, use the dofile function instead.
Any values returned by the included script are passed through to the caller.
-- runs "src/MyApplication/premake4.lua" include "src/MyApplication"
-- runs "src/MyLibrary/premake4.lua" include "src/MyLibrary"
The includedirs function specifies the include file search paths.
If a project includes multiple calls to includedirs the lists are concatenated, in the order in which they appear in the script.
Solutions, projects, and configurations.
paths specifies a list of include file search directories. Paths should be specified relative to the currently running script file.
Define two include file search paths.
includedirs { "../lua/include", "../zlib" }
You can also use wildcards to match multiple directories. The ***** will match against a single directory, ****** will recurse into subdirectories as well.
includedirs { "../includes/**" }
The kind function sets the kind of binary object being created by the project, such as a console or windowed application, or a shared or static library.
Updated information is available on the new Premake wiki.
Solutions, projects, and configurations.
kind is the project kind identifier, and must be one of:
ConsoleApp : A console, or command-line, executable.
WindowedApp : An application that runs in a desktop window. This distinction does not apply on Linux, but is important on Windows and Mac OS X.
SharedLib : A shared library, or DLL.
StaticLib : A static library.
Set the project to generate a console executable.
Set the project to generate a shared library (DLL).
You can also set different kinds for each configuration. This is not supported by Xcode.
solution "MySolution" configurations { "DebugLib", "ReleaseLib",
"DebugDLL", "ReleaseDLL" } project "MyProject" configuration "*Lib"
kind "StaticLib" configuration "*DLL" kind "SharedLib"
The language function sets the programming language used by a project.
Premake currently supports C, C++, and C#. Not all languages are supported by all of the generators; for instance, SharpDevelop does not (currently) support C or C++ development, and Code::Blocks does not support the .NET languages (C#, Managed C++).
Solutions and projects.
lang is the language identifier. This is a string value, set to one of C, C++, or C#. The value is not case sensitive.
Set the project language to C++.
Set the project language to C#
The libdirs function specifies the library search paths.
Library search directories are not well supported by the .NET tools. Visual Studio will change relative paths to absolute, making it difficult to share the generated project. MonoDevelop and SharpDevelop do not support search directories at all, using only the GAC. In general, it is better to include the full (relative) path to the assembly in links instead. C/C++ projects do not have this limitation.
If a project includes multiple calls to libdirs the lists are concatenated, in the order in which they appear in the script.
Solutions, projects, and configurations.
paths specifies a list of library search directories. Paths should be specified relative to the currently running script file.
Define two library file search paths.
libdirs { "../lua/libs", "../zlib" }
You can also use wildcards to match multiple directories. The ***** will match against a single directory, ****** will recurse into subdirectories as well.
The linkoptions function passes arguments directly to the linker command line without translation.
linkoptions { "options" }
If a project includes multiple calls to linkoptions the lists are concatenated, in the order in which they appear in the script.
Solutions, projects, and configurations.
options is a list of linker flags and options, specific to a particular linker.
Use pkg-config style configuration when building on Linux with GCC. Build
options are always linker specific and should be targeted to a particular
toolset.
configuration { "linux", "gmake" } linkoptions { "`wx-config --libs`" }
The links function specifies a list of libraries and projects to link against.
If a project includes multiple calls to links the lists are concatenated, in the order in which they appear in the script.
Solutions, projects, and configurations.
references is a list of library and project names.
When linking against another project in the same solution, specify the project name here, rather than the library name. Premake will figure out the correct library to link against for the current configuration, and will also create a dependency between the projects to ensure a proper build order.
When linking against system libraries, do not include any prefix or file extension. Premake will use the appropriate naming conventions for the current platform.
Link against some system libraries.
configuration "windows" links { "user32", "gdi32" } configuration
"linux" links { "m", "png" } configuration "macosx" -- OS X
frameworks need the extension to be handled properly links {
"Cocoa.framework", "png" }
In a solution with two projects, link the library into the executable. Note that the project name is used to specify the link; Premake will automatically figure out the correct library file name and directory and create a project dependency.
solution "MySolution" configurations { "Debug", "Release" } language "C++"
project "MyExecutable" kind "ConsoleApp" files "**.cpp" links {
"MyLibrary" } project "MyLibrary" kind "SharedLib" files "**.cpp"
You may also create links between non-library projects. In this case, Premake will generate a build dependency (the linked project will build first), but not an actual link. In this example, MyProject uses a build dependency to ensure that MyTool gets built first. It then uses MyTool as part of its build process.
solution "MySolution" configurations { "Debug", "Release" } language "C++"
project "MyProject" kind "ConsoleApp" files "**.cpp" links {
"MyTool" } prebuildcommands { "MyTool --dosomething" } project
"MyTool" kind "ConsoleApp" files "**.cpp"
The location function sets the destination directory for a generated solution or project file.
By default, solution and project files are generated into the same directory as the script that defines them. The location function allows you to change this location.
Note that unlike other values, location does not automatically propagate to the contained projects. Projects will use their default location unless explicitly overridden.
Solutions and projects.
path is the directory where the generated files should be stored, specified relative to the currently executing script file.
Set the destination directory for a solution. Setting the location for a project works the same way.
solution "MySolution" location "../build"
If you plan to build with multiple tools from the same source tree you might want to split up the project files by toolset. The _ACTION global variable contains the current toolset identifier, as specified on the command line. Note that Lua syntax requires parenthesis around the function parameters in this case.
location ("../build/" .. _ACTION)
The newaction function registers a new command-line action argument. For more information, see Command Line Arguments.
description is a table describing the new action. It may contain the following fields:
trigger : The string identifier of the action; what the user would type on the command line.
description : A short description of the action, to be displayed in the help text.
execute : A function to be executed when the action is fired.
Register a new action to install the software project.
newaction { trigger = "install", description = "Install the software",
execute = function () os.copyfile("bin/debug/myprogram",
"/usr/local/bin/myprogram") end }
The newoption function registers a new command-line option argument. For more information, see Command Line Arguments.
description is a table describing the new option. It may contain the following fields:
trigger : The string identifier of the option; what the user would type on the command line.
description : A short description of the option, to be displayed in the help text.
value : Optional. If the option needs a value, provides a hint to the user what type of data is expected.
allowed : Optional. A list of key-value pairs listing the allowed values for the option.
Register a new option to select a rendering API for a 3D application.
newoption { trigger = "gfxapi", value = "API", description =
"Choose a particular 3D API for rendering", allowed = { { "opengl",
"OpenGL" }, { "direct3d", "Direct3D (Windows only)" }, { "software",
"Software Renderer" } } }
The objdir function sets object and intermediate file directory for a project.
By default, object and intermediate files are stored in a directory named "obj" in the same directory as the project. The objdir function allows you to change this location.
Updated information is available on the new Premake wiki.
Solutions, projects, and configurations.
path is the directory where the object and intermediate files should be stored, specified relative to the currently executing script file.
Set an object directory for a project.
project "MyProject" objdir "objects"
Set object directories per configuration.
configuration "Debug" objdir "../obj_debug" configuration "Release"
objdir "../obj_release"
The os.chdir function changes the current working directory.
path is the file system path to the new working directory.
True if successful, otherwise nil and an error message.
The os.copyfile function copies a file from one location to another.
os.copyfile("source", "destination")
Source is the file system path to the file to be copied. Destination is the path to the copy location.
True if successful, otherwise nil and an error message.
The os.findlib function scans the well-known system locations looking for a library file.
p = os.findlib("libname")
libname is name of the library to locate. It may be specified with (libX11.so) or without (X11) system-specific decorations.
The path containing the library file, if found. Otherwise, nil.
The os.get function identifies the currently targeted operating system.
None.
An operating system identifier, one of bsd, linux, macosx, solaris, or windows.
Note that this function returns the OS being targeted, which is not necessarily the same as the OS on which Premake is being run. If you are running on Mac OS X and generating Visual Studio project files, the identifier is "Windows", since that is the OS being targeted by the Visual Studio action.
if os.get() == "windows" then -- do something Windows-specific end
The os.getcwd function gets the current working directory.
None.
The current working directory.
Retrieve version information for the host operating system.
Introduced in Premake 4.4, this function has not yet been implemented for all platforms. On platforms where this has not been implemented, it will return zero for all version numbers, and the platform name as the description.
A table, containing the following key-value pairs:
majorversion The major version number
minorversion The minor version number
revision The bug fix release or service pack number
description A human-readable description of the OS version
local ver = os.getversion() print(string.format(" %d.%d.%d (%s)",
ver.majorversion, ver.minorversion, ver.revision, ver.description))
-- On Windows XP: "5.1.3 (Windows XP)" -- On OS X,: "10.6.6 (Mac OS X Snow
Leopard)"
The os.is function checks the current operating system identifier against a particular value.
id is one of the operating system identifiers bsd, linux, macosx, solaris, or windows.
Note that this function tests against the OS being targeted, which is not necessarily the same as the OS on which Premake is being run. If you are running on Mac OS X and generating Visual Studio project files, the identifier is "Windows", since that is the OS being targeted by the Visual Studio action.
True if the supplied ID matches the current operating system identifier, false otherwise.
The os.is64bit function determines if the host is using a 64-bit processor.
Introduced in Premake 4.4.
True if the host system has a 64-bit processor, false otherwise.
if os.is64bit() then print("This is a 64-bit system") else print("This is
NOT a 64-bit system") end
The os.isdir function checks for the existence of directory.
Path is the file system path to check.
True if a matching directory is found; false is there is no such file system path, or if the path points to a file instead of a directory.
The os.isfile function checks for the existence of file.
Path is the file system path to check.
True if a matching file is found; false is there is no such file system path, or if the path points to a directory instead of a file.
The os.matchdirs function performs a wildcard match to locate one or more directories.
matches = os.matchdirs("pattern")
patterm is the file system path to search. It may contain single (non-recursive) or double (recursive) asterisk wildcard patterns.
A list of directories which match the specified pattern. May be empty.
matches = os.matchdirs("src/*") -- non-recursive match matches =
os.matchdirs("src/**") -- recursive match matches =
os.matchdirs("src/test*") -- may also match partial names
The os.matchdirs function performs a wildcard match to locate one or more directories.
matches = os.matchfiles("pattern")
patterm is the file system path to search. It may contain single (non-recursive) or double (recursive) asterisk wildcard patterns.
A list of files which match the specified pattern. May be empty.
matches = os.matchfiles("src/*.c") -- non-recursive match matches =
os.matchfiles("src/**.c") -- recursive match
The os.mkdir function creates a new directory.
Path is the file system path to be created.
True if successful, otherwise nil and an error message.
The os.outputof function runs a shell command and returns the output.
result = os.outputof("command")
command is a shell command to run.
The output of the command.
-- Get the ID for the host processor architecture local proc =
os.outputof("uname -p")
The os.pathsearch function searches a collection of paths for a particular file.
p = os.pathsearch("fname", "path1", ...)
fname is the name of the file being searched. This is followed by one or more path sets to be searched.
Path sets match the format of the PATH environment variable: a colon-delimited list of paths. On Windows, you may use a semicolon-delimited list if drive letters might be included.
The path to the directory which contains the file, if found. Otherwise, nil.
local p = os.pathsearch("mysystem.config", "./config:/usr/local/etc:/etc")
The os.rmdir function removes an existing directory as well as any files or subdirectories it contains.
path is the file system path to be removed.
True if successful, otherwise nil and an error message.
The os.stat function retrieves information about a file.
Added in Premake 4.4.
path is the filesystem path to file for which to retrieve information.
A table of values:
mtime : Last modified timestamp
size : The file size in bytes
The os.uuid function returns a Universally Unique Identifier.
None.
A new UUID, a string value with the format 74CFC033-FA4D-4B1E-A871-7DC48FA36769.
The path.getabsolute function converts a relative path an absolute path.
p = path.getabsolute("path")
path is the relative path to be converted. It does not need to actually exist on the file system.
A new absolute path, calculated from the current working directory.
The path.getbasename function returns the base file portion of a path, with the directory and file extension removed.
p = path.getbasename("path")
path is the file system path to be split.
The base name portion of the supplied path, with any directory and file extension removed.
The path.getdirectory function returns the directory portion of a path, with any file name removed.
p = path.getdirectory("path")
path is the file system path to be split.
The directory portion of the path, with any file name removed. If the path does not include any directory information, the "." (single dot) current directory is returned.
The path.getdrive function returns the drive letter portion of a path, if present.
p = path.getdrive("path")
path is the file system path to be split.
The drive letter portion of the path, if one is specified. Otherwise, nil.
The path.getextension function returns the file extension portion of a path.
p = path.getextension("path")
path is the file system path to be split.
The file extension portion of the path, or an empty string if no extension is present.
The path.getname function returns the file name and extension, with any directory information removed.
path is the file system path to be split.
The file name and extension, with no directory information.
The path.getrelative function computes a relative path from one directory to another.
p = path.getrelative("src", "dest")
src is the originating directory, dest is the target directory. Both may be specified as absolute or relative.
A relative path from src to dest.
The path.isabsolute function returns true if the specified path is an absolute path.
path is the file system path to check.
True if the specified path is absolute, false otherwise.
The path.iscfile function returns true if the specified path represents a C source code file, based on its file extension.
path is the file system path to check.
True if the path matches a well-known C file extension, false otherwise.
The path.iscppfile function returns true if the specified path represents a C++ source code file, based on its file extension.
path is the file system path to check.
True if the path matches a well-known C++ file extension, false otherwise.
The path.isresourcefile function returns true if the specified path represents a Windows resource file, based on its file extension.
path.isresourcefile("path")
path is the file system path to check.
True if the path matches a well-known Windows resource file extension, false otherwise.
The path.join function joins two path portions together into a single path.
path.join("leading", "trailing")
If trailing is an absolute path, then the leading portion is ignored, and the absolute path is returned instead (see below for examples).
leading is the beginning portion of the path; trailing is the ending portion.
A merged path.
-- returns "MySolution/MyProject" p = path.join("MySolution", "MyProject")
-- returns "/usr/bin", because the trailing path is absolute p =
path.join("MySolution", "/usr/bin") -- tokens are assumed to be
absolute; this returns "$(ProjectDir)" p = path.join("MySolution",
"$(ProjectDir)")
The path.rebase function takes a relative path and makes it relative to a different location.
path.rebase("path", "oldbase", "newbase")
path is the relative path to conver. oldbase is the original base directory, from with path is relative. newbase is the new base directory, from where the resulting path should be relative.
The rebased path.
The path.translate function converts the file separators in a path.
path.translate("path", "newsep")
path is the file system path to translate. newsep is the new path separator.
If newsep is nil, the native path separator for the current environment will be used.
The translated path.
The pchheader function sets the main header file for precompiled header support.
If no header file is set, the toolset default settings will be used.
Updated information is available on the new Premake wiki.
Projects only.
file is the name of the header file, as it is specified in your source file #include statements.
pchheader "afxwin.h" pchsource "afxwin.cpp"
The pchsource function sets the main source file for precompiled header support. This is only used by Visual Studio.
If no source file is set, the toolset default settings will be used.
Updated information is available on the new Premake wiki.
Projects only.
file is the name of the source file, specified relative to the currently executing script file.
pchheader "afxwin.h" pchsource "afxwin.cpp"
Platform support is a new, experimental feature which will be introduced in Premake 4.1. The syntax and behavior described here might change as we sort out the details.
The platforms function specifies a set of target hardware platforms for a solution. This is an optional setting; if it is not provided the toolset's default behavior will be used.
platforms { "identifiers" }
Please see the Platforms section of the user guide for a lot more information on platforms and how they are used by Premake.
Updated information is available on the new Premake wiki.
Solutions only.
identifiers is a list of hardware platform identifiers, and may include any of the following.
Native : A general build not targeting any particular platform; uses the default build behavior of the compiler. If your project can be built in a generic fashion, you should include this as the first platform option.
x32 : Target a 32-bit environment.
x64 : Target a 64-bit environment
Universal : Create a Mac OS X universal binary, targeting both 32- and 64-bit versions of x86 and PPC. Note that in order to target multiple architectures, automated dependency generation must be turned off. You should always do a clean build when creating a universal target. Universal builds are not supported by Visual Studio.
Universal32 : Like Universal above, but targeting only 32-bit platforms.
Universal64 : Like Universal above, but targeting only 64-bit platforms.
PS3 : Target the Playstation 3.
Xbox360 : Target the Xbox 360 compiler and linker under Visual Studio; ignored elsewhere.
Not all platforms are supported on all systems, unsupported platforms will be silently ignored. Some targets require extra configuration of the build tools on the client machine in order to support cross-compilation.
The function returns the current list of target platforms for the active solution.
Provide a generic build that will work anywhere, as well as a Mac OS X Universal build.
solution "MySolution" configurations { "Debug", "Release" } platforms {
"native", "universal" }
Provide 32- and 64-bit specific build targets. No generic build is provided, so one of these two platforms must always be used. Do this only if your software requires knowledge of the underlying architecture at build time, otherwise include "native" to provide a generic build.
solution "MySolution" configurations { "Debug", "Release" } platforms {
"x32", "x64" }
You can retrieve the current list of platforms by calling the function with no parameters.
Once you have defined a list of platforms, you may use those identifiers to set up configuration filters and apply platform-specific settings.
configuration "x64" defines "IS_64BIT" -- You can also mix platforms
with other configuration selectors configuration { "Debug", "x64" } defines
"IS_64BIT_DEBUG"
The postbuildcommands function specifies shell commands to run after build is finished.
postbuildcommands { "commands" }
Solutions, projects, and configurations.
commands is one or more shell commands. These commands will be passed to the shell exactly as entered, including path separators and the like.
prebuildcommands prelinkcommands
configuration "windows" postbuildcommands { "copy default.config
bin\project.config" } configuration "not windows" postbuildcommands
{ "cp default.config bin/project.config" }
The prebuildcommands function specifies shell commands to run before each build.
prebuildcommands { "commands" }
Solutions, projects, and configurations.
commands is one or more shell commands. These commands will be passed to the shell exactly as entered, including path separators and the like.
prelinkcommands postbuildcommands
configuration "windows" prebuildcommands { "copy default.config
bin\project.config" } configuration "not windows" prebuildcommands {
"cp default.config bin/project.config" }
The prelinkcommands function specifies shell commands to run after the source files have been compiled, but before the link step.
prelinkcommands { "commands" }
Solutions, projects, and configurations.
commands is one or more shell commands. These commands will be passed to the shell exactly as entered, including path separators and the like.
prebuildcommands postbuildcommands
configuration "windows" prelinkcommands { "copy default.config
bin\project.config" } configuration "not windows" prelinkcommands {
"cp default.config bin/project.config" }
The printf performs like its C counterpart, printing a formatted string.
It is equivalent to this Lua code:
print(string.format(format, unpack(arg))
format is a formatting string containing C printf() style formatting codes. It is followed by a list of arguments to be substituted into the format string.
None.
The project function creates a new project and makes it active.
Projects contain all of the settings necessary to build a single binary target, and are synonymous with a Visual Studio project. These settings include the list of source code files, the programming language used by those files, compiler flags, include directories, and which libraries to link against.
Every project belongs to a solution.
name is a unique name for the project. If a project with the given name already exists, it is made active and returned. The project name will be used as the file name of the generated solution file.
The function returns the active project object; see The Project Object below for more information on the structure of this object.
Create a new project named "MyProject". Note that a solution must exist to contain the project. The indentation is for readability and is optional.
solution "MySolution" configurations { "Debug", "Release" } project
"MyProject"
You can retrieve the currently active project object by calling project with no parameters.
You can retrieve the list of projects associated with a solution using the projects field on the solution object, which may then be iterated over.
local prjs = solution().projects for i, prj in ipairs(prjs) do
print(prj.name) end
Each project is represented in Lua as a table of key-value pairs. 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 project object contains the following values.
basedir : The directory where the project was original defined; acts as a root for relative paths.
blocks : A list of configuration blocks.
language : The project language, if set.
location : The output directory for the generated project file.
name : The name of the project.
solution : The solution which contains the project.
uuid : The project's unique identifier.
The resdefines function specifies preprocessor symbols for the resource compiler.
If a project includes multiple calls to resdefines the lists are concatenated, in the order in which they appear in the script.
Solutions, projects, and configurations.
symbols specifies a list of symbols to be defined.
Define two new symbols in the current project.
resdefines { "DEBUG", "TRACE" }
Symbols may also assign values.
resdefines { "CALLSPEC=__dllexport" }
The resincludedirs function specifies the include file search paths for the resource compiler.
resincludedirs { "paths" }
If a project includes multiple calls to resincludedirs the lists are concatenated, in the order in which they appear in the script.
Solutions, projects, and configurations.
paths specifies a list of include file search directories. Paths should be specified relative to the currently running script file.
Define two include file search paths.
resincludedirs { "../lua/include", "../zlib" }
You can also use wildcards to match multiple directories. The ***** will match against a single directory, ****** will recurse into subdirectories as well.
resincludedirs { "../includes/**" }
The resoptions function passes arguments directly to the resource compiler command line without translation.
If a project includes multiple calls to resoptions the lists are concatenated, in the order in which they appear in the script.
Solutions, projects, configurations
options is a list of resource compiler flags and options, specific to a particular compiler.
Use pkg-config style configuration when building on Linux with GCC. Build
options are always compiler specific and should be targeted to a particular
toolset.
configuration { "linux", "gmake" } resoptions { "`wx-config --cxxflags`",
"-ansi", "-pedantic" }
The solution function creates a new solution and makes it active.
Solutions are the top-level objects in a Premake build script, and are synonymous with a Visual Studio solution. Each solution contains one or more projects, which it turn contain the settings to generate a single binary target.
name is a unique name for the solution. If a solution with the given name already exists, it is made active and returned. The solution name will be used as the file name of the generated solution file.
The function returns the active solution object; see The Solution Object below for more information on the structure of this object.
Create a new solution named "MySolution".
You can retrieve the currently active solution object by calling solution with no parameters.
You can the global variable _SOLUTIONS to list out all of the currently defined solutions.
for i, sln in ipairs(_SOLUTIONS) do print(sln.name) end
Each solution is represented in Lua as a table of key-value pairs. 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 solution object contains the following values.
basedir : The directory where the project was original defined; acts as a root for relative paths.
configurations : The list of valid configuration names.
blocks : A list of configuration blocks.
language : The solution language, if set.
location : The output directory for the generated solution file.
name : The name of the solution.
platforms : A list of target platforms.
projects : A list of projects contained by the solution.
The string.endswith function returns true if the given string ends with the provided sequence.
string.endswith("haystack", "needle")
haystack is the string to check. needle is the ending sequence to check against.
True if haystack ends with needle.
The string.explode function returns an array of strings, each of which is a substring of s formed by splitting on boundaries formed by pattern.
string.explode("str", "pattern")
str is the string to be split. pattern is the separator pattern at which to split; it may use Lua's pattern matching syntax.
A list of substrings.
The string.findlast function finds the last instance of a pattern within a string.
string.endswith("str", "pattern", plain)
str is the string to be searched. pattern is the pattern to search for; it may use Lua's pattern matching syntax. If plain is true, no pattern matching will be performed (faster).
The matching pattern, if found, or nil if there were no matches.
The string.startswith function returns true if the given string starts with the provided sequence.
string.startswith("haystack", "needle")
haystack is the string to check. needle is the starting sequence to check against.
True if haystack starts with needle.
The table.contains function determines if an array contains a particular value.
table.contains(arr, value)
arr is the array to test; value is the value being tested for.
True if the array contains the value, false otherwise.
The table.implode function merges an array of items into a single, formatted string.
table.implode(arr, "before", "after", "between")
arr is the array to be converted into a string. before is a string to be inserted before each item. after is a string to be inserted after each item. between is a string to be inserted between items.
The formatted string.
The targetdir function sets the destination directory for the compiled binary target.
By default, the generated project files will place their compiled output in the same directory as the script. The targetdir function allows you to change this location.
Solutions, projects, and configurations.
path is the file system path to the directory where the compiled target file should be stored. It is specified relative to the currently executing script file.
targetname targetextension targetprefix
This project separates its compiled output by configuration type.
project "MyProject" configuration "Debug" targetdir "bin/debug"
configuration "Release" targetdir "bin/release"
The targetextension function specifies the file extension for the compiled binary target.
By default, the project will use the system's normal naming conventions: .exe for Windows executables, .so for Linux shared libraries, and so on. The targetextension function allows you to change this default.
Solutions, projects, and configurations.
ext is the new file extension, including the leading dot.
targetname targetdir targetprefix targetsuffix
The targetname function specifies the base file name for the compiled binary target.
By default, the project name will be used as the file name of the compiled binary target. A Windows executable project named "MyProject" will produce a binary named MyProject.exe. The targetname function allows you to change this default.
Solutions, projects, and configurations.
name is the new base file name.
targetdir targetextension targetprefix targetsuffix
The targetprefix function specifies the file name prefix for the compiled binary target.
By default, the system naming convention will be used: a "lib" prefix for POSIX libraries (as in libMyProject.so), and no prefix elsewhere. The targetprefix function allows you to change this default.
Solutions, projects, and configurations.
prefix is the new file name prefix.
targetname targetdir targetextension targetsuffix
The prefix may also be set to an empty string for no prefix.
The targetsuffix function specifies a file name suffix for the compiled binary target.
Solutions, projects, and configurations.
suffix is the new filename suffix.
targetname targetdir targetprefix targetextension
-- Add "-d" to debug versions of files configuration "Debug" targetsuffix
"-d"
The uuid function sets the Universally Unique Identifier (UUID) for a project.
UUIDs are synonymous (for Premake's purposes) with Globally Unique Identifiers (GUID).
Premake automatically assigns a UUID to each project, which is used by the Visual Studio generators to identify the project within a solution. This UUID is essentially random and will change each time the project file is generated. If you are storing the generated Visual Studio project files in a version control system, this will create a lot of unnecessary deltas. Using the uuid function, you can assign a fixed UUID to each project which never changes, removing the randomness from the generated projects.
Projects only.
project_uuid is the UUID for the current project. It should take the form "01234567-ABCD-ABCD-ABCD-0123456789AB" (see the examples below for some real UUID values). You can use the Visual Studio guidgen tool to create new UUIDs, or this website, or run Premake once to generate Visual Studio files and copy the assigned UUIDs.
The current project UUID, or nil if no UUID has been set.
Set the UUID for a current project.
uuid "BE2461B7-236F-4278-81D3-F0D476F9A4C0"
The vpaths function places files into groups or "virtual paths", rather than the default behavior of mirroring the filesystem in IDE-based projects. So you could, for instance, put all header files in a group called "Headers", no matter where they appeared in the source tree.
vpaths { ["group"] = "pattern(s)" }
Note that Lua tables do not maintain any ordering between key-value pairs, so there is no precedence between the supplied rules. That is, you can't write a rule that rewrites the results of an earlier rule, since there is no guarantee in which order the rules will run.
Added in Premake 4.4.
Virtual paths, like files, may be set on the solution, project, and configuration level. However, only project-level file lists are currently supported.
A list of key/value pairs, specified with Lua's standard syntax, which map file patterns to the group in which they should appear. See the examples below for a more complete explanation.
Place all header files into a virtual path called "Headers". Any directory information is removed, so a path such as src/lua/lua.h will appear in the IDE as Headers/lua.h.
vpaths { ["Headers"] = "**.h" }
You may also specify multiple file patterns using the table syntax.
vpaths { ["Headers"] = { "**.h", "**.hxx", "**.hpp" } }
It is also possible to include the file's path in the virtual group. Using the same example as above, this rule will appear in the IDE as Headers/src/lua/lua.h.
vpaths { ["Headers/*"] = "**.h" }
Any directory information explicitly provided in the pattern will be removed from the replacement. This rule will appear in the IDE as Headers/lua/lua.h.
vpaths { ["Headers/*"] = "src/**.h" }
You can also use virtual paths to remove extra directories from the IDE. For instance, this rule will cause the previous example to appear as lua/lua.h, removing the src part of the path from all files.
And of course, you can specify more than one rule at a time.
vpaths { ["Headers"] = "**.h", ["Sources/*"] = {"**.c", "**.cpp"}, ["Docs"]
= "**.txt" }