diff options
Diffstat (limited to '3rdparty/genie/scripting-reference.md')
-rw-r--r-- | 3rdparty/genie/scripting-reference.md | 2436 |
1 files changed, 0 insertions, 2436 deletions
diff --git a/3rdparty/genie/scripting-reference.md b/3rdparty/genie/scripting-reference.md deleted file mode 100644 index a8bc9433073..00000000000 --- a/3rdparty/genie/scripting-reference.md +++ /dev/null @@ -1,2436 +0,0 @@ -# Scripting Reference - -This section describes the functions and variables available to Premake -scripts. - -Premake is built on Lua, so everything in the [Lua Reference Manual][1] 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][2] 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][3]. - -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][4]**. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_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. - -### Examples - -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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_options_ is a list of compiler flags and options, specific to a particular -compiler. - -### Examples - -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. - -### 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][5] function. - -Action names : Any action name, such as **vs2005** or **gmake**. See the [Quick -Start][6] for a complete list. - -Operating system names : Any of the operating system identifiers, such as -**windows** or **macosx**, as returned by [os.get][7]. - -Platform names : Any of the platform identifiers, such as **ps3** or -**xbox360**. See [platforms][8] 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][9] 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" } - -Although support is currently quite limited (only [buildaction][10] 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. - -### 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. - -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][11].** - -### Applies To - -Solutions only. - -### Parameters - -_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. - -### Return Value - -The function returns the current list of configuration names for the active -solution. - -### Examples - -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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_args_ is a Lua list of arguments to provide to the executable while debugging. - -### Examples - - - 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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_path_ is the path to the working directory, relative to the currently -executing script file. - -### Examples - - - 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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_symbols_ specifies a list of symbols to be defined. - -### Examples - -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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_options_ is a list of deployment tools flags and options. - -The **excludes** function removes files, added with the [files][12] function, -from a project. - -If a project includes multiple calls to **excludes** the lists are -concatenated. - -### Applies To - -Files may be set on the solution, project, and configuration level. However, -only project-level file lists are currently supported. - -### Parameters - -_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. - -### Examples - -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. - -### Applies To - -Files may be set on the solution, project, and configuration level. However, -only project-level file lists are currently supported. - -### Parameters - -_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][13] function. - -### Examples - -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][14]**. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_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][15]. 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][16] and [pchsource][17]. - -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][18]. - -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][19] and -[linkoptions][20]. - -### Examples - -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. - -### Applies To - -Solutions and projects. - -### Parameters - -_version_ is one of: - -### Examples - -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) - -### Parameters - -_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. - -### Return Value - -_trueval_ is the condition evaluates true, _falseval_ otherwise. - -### Examples - - - 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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_path_ is the full path for the image file, relative to the currently executing -script file. - -### See Also - -[imageoptions][21] - -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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_path_ is the output directory for the library, relative to the currently -executing script file. - -### See Also - -[implibname][22] [implibextension][23] [implibprefix][24] [implibsuffix][25] - -### Examples - -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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_ext_ is the new file extension, including the leading dot. - -### See Also - -[implibname][22] [implibdir][26] [implibprefix][24] [implibsuffix][25] - -### Examples - -The **implibname** function specifies the import library base file name. Import -libraries are generated for Windows DLL projects. - -By default, the [target name][27] will be used as the import library file name. -The **implibname** function allows you to change this default. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_name_ is the new base file name. - -### See Also - -[implibdir][26] [implibextension][23] [implibprefix][24] [implibsuffix][25] - -### Examples - -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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_prefix_ is the new file name prefix. - -### See Also - -[implibname][22] [implibdir][26] [implibextension][23] [implibsuffix][25] - -### Examples - -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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_suffix_ is the new filename suffix. - -### See Also - -[implibname][22] [implibdir][26] [implibprefix][24] [implibextension][23] - -### Examples - - - -- 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. - -### Parameters - -_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][28] function instead. - -### Return Value - -Any values returned by the included script are passed through to the caller. - -### Examples - - - -- 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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_paths_ specifies a list of include file search directories. Paths should be -specified relative to the currently running script file. - -### Examples - -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][29]**. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_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. - -### Examples - -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++). - -### Applies To - -Solutions and projects. - -### Parameters - -_lang_ is the language identifier. This is a string value, set to one of **C**, -**C++**, or **C#**. The value is not case sensitive. - -### Examples - -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][30] 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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_paths_ specifies a list of library search directories. Paths should be -specified relative to the currently running script file. - -### Examples - -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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_options_ is a list of linker flags and options, specific to a particular -linker. - -### Examples - -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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_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. - -### Examples - -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. - -### Applies To - -Solutions and projects. - -### Parameters - -_path_ is the directory where the generated files should be stored, specified -relative to the currently executing script file. - -### Examples - -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][31] 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][3]. - -### Parameters - -_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. - -### See Also - -[Command Line Arguments][3] - -### Examples - -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][3]. - -### Parameters - -_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. - -### See Also - -[Command Line Arguments][3] - -### Examples - -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][32]**. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_path_ is the directory where the object and intermediate files should be -stored, specified relative to the currently executing script file. - -### Examples - -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. - -### Parameters - -_path_ is the file system path to the new working directory. - -### Return Value - -**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") - -### Parameters - -_Source_ is the file system path to the file to be copied. _Destination_ is the -path to the copy location. - -### Return Value - -**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") - -### Parameters - -_libname_ is name of the library to locate. It may be specified with -(libX11.so) or without (X11) system-specific decorations. - -### Return Value - -The path containing the library file, if found. Otherwise, nil. - -The **os.get** function identifies the currently targeted operating system. - -### Parameters - -None. - -### Return Value - -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. - -### Example - - - if os.get() == "windows" then -- do something Windows-specific end - -The **os.getcwd** function gets the current working directory. - -### Parameters - -None. - -### Return Value - -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. - -### Return Value - -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 - -### Examples - - - 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. - -### Parameters - -_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. - -### Return Value - -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**. - -### Return Value - -**True** if the host system has a 64-bit processor, **false** otherwise. - -### Examples - - - 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. - -### Parameters - -_Path_ is the file system path to check. - -### Return Value - -**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. - -### Parameters - -_Path_ is the file system path to check. - -### Return Value - -**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") - -### Parameters - -_patterm_ is the file system path to search. It may contain single -(non-recursive) or double (recursive) asterisk wildcard patterns. - -### Return Value - -A list of directories which match the specified pattern. May be empty. - -### Example - - - 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") - -### Parameters - -_patterm_ is the file system path to search. It may contain single -(non-recursive) or double (recursive) asterisk wildcard patterns. - -### Return Value - -A list of files which match the specified pattern. May be empty. - -### Example - - - matches = os.matchfiles("src/*.c") -- non-recursive match matches = - os.matchfiles("src/**.c") -- recursive match - -The **os.mkdir** function creates a new directory. - -### Parameters - -_Path_ is the file system path to be created. - -### Return Value - -**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") - -### Parameters - -_command_ is a shell command to run. - -### Return Value - -The output of the command. - -### Examples - - - -- 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", ...) - -### Parameters - -_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. - -### Return Value - -The path to the directory which contains the file, if found. Otherwise, nil. - -### Examples - - - 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. - -### Parameters - -_path_ is the file system path to be removed. - -### Return Value - -**True** if successful, otherwise **nil** and an error message. - -The **os.stat** function retrieves information about a file. - -Added in Premake 4.4. - -### Parameters - -_path_ is the filesystem path to file for which to retrieve information. - -### Return Value - -A table of values: - -mtime : Last modified timestamp - -size : The file size in bytes - -The **os.uuid** function returns a [Universally Unique Identifier][33]. - -### Parameters - -None. - -### Return Value - -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") - -### Parameters - -_path_ is the relative path to be converted. It does not need to actually exist -on the file system. - -### Return Value - -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") - -### Parameters - -_path_ is the file system path to be split. - -### Return Value - -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") - -### Parameters - -_path_ is the file system path to be split. - -### Return Value - -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") - -### Parameters - -_path_ is the file system path to be split. - -### Return Value - -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") - -### Parameters - -_path_ is the file system path to be split. - -### Return Value - -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. - -### Parameters - -_path_ is the file system path to be split. - -### Return Value - -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") - -### Parameters - -_src_ is the originating directory, _dest_ is the target directory. Both may be -specified as absolute or relative. - -### Return Value - -A relative path from _src_ to _dest_. - -The **path.isabsolute** function returns true if the specified path is an -absolute path. - -### Parameters - -_path_ is the file system path to check. - -### Return Value - -**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. - -### Parameters - -_path_ is the file system path to check. - -### Return Value - -**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. - -### Parameters - -_path_ is the file system path to check. - -### Return Value - -**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") - -### Parameters - -_path_ is the file system path to check. - -### Return Value - -**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). - -### Parameters - -_leading_ is the beginning portion of the path; _trailing_ is the ending -portion. - -### Return Value - -A merged path. - -### Examples - - - -- 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") - -### Parameters - -_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. - -### Return Value - -The rebased path. - -The **path.translate** function converts the file separators in a path. - - - path.translate("path", "newsep") - -### Parameters - -_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. - -### Return Value - -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][34]**. - -### Applies To - -Projects only. - -### Parameters - -_file_ is the name of the header file, as it is specified in your source file -**#include** statements. - -### See Also - -[pchsource][17] - -### Examples - - - 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][35]**. - -### Applies To - -Projects only. - -### Parameters - -_file_ is the name of the source file, specified relative to the currently -executing script file. - -### See Also - -[pchheader][16] - -### Examples - - - 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][36] for a lot more -information on platforms and how they are used by Premake. - -**Updated information is [available on the new Premake wiki][37].** - -### Applies To - -Solutions only. - -### Parameters - -_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. - -### Return Value - -The function returns the current list of target platforms for the active -solution. - -### Examples - -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][38] 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" } - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_commands_ is one or more shell commands. These commands will be passed to the -shell exactly as entered, including path separators and the like. - -### See Also - -[prebuildcommands][39] [prelinkcommands][40] - -### Examples - - - 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" } - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_commands_ is one or more shell commands. These commands will be passed to the -shell exactly as entered, including path separators and the like. - -### See Also - -[prelinkcommands][40] [postbuildcommands][41] - -### Examples - - - 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" } - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_commands_ is one or more shell commands. These commands will be passed to the -shell exactly as entered, including path separators and the like. - -### See Also - -[prebuildcommands][39] [postbuildcommands][41] - -### Examples - - - 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)) - -### Parameters - -_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. - -### Return Value - -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. - -### Parameters - -_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. - -### Return Value - -The function returns the active project object; see [The Project Object][42] -below for more information on the structure of this object. - -### See Also - -[solution][43] - -### Examples - -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 - -### The Project Object - -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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_symbols_ specifies a list of symbols to be defined. - -### Examples - -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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_paths_ specifies a list of include file search directories. Paths should be -specified relative to the currently running script file. - -### Examples - -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. - -### Applies To - -Solutions, projects, configurations - -### Parameters - -_options_ is a list of resource compiler flags and options, specific to a -particular compiler. - -### Examples - -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. - -### Parameters - -_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. - -### Return Value - -The function returns the active solution object; see [The Solution Object][42] -below for more information on the structure of this object. - -### Examples - -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 - -### The Solution Object - -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") - -### Parameters - -_haystack_ is the string to check. _needle_ is the ending sequence to check -against. - -### Return Value - -**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") - -### Parameters - -_str_ is the string to be split. _pattern_ is the separator pattern at which to -split; it may use Lua's pattern matching syntax. - -### Return Value - -A list of substrings. - -The **string.findlast** function finds the last instance of a pattern within a -string. - - - string.endswith("str", "pattern", plain) - -### Parameters - -_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). - -### Return Value - -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") - -### Parameters - -_haystack_ is the string to check. _needle_ is the starting sequence to check -against. - -### Return Value - -**True** if _haystack_ starts with _needle_. - -The **table.contains** function determines if an array contains a particular -value. - - - table.contains(arr, value) - -### Parameters - -_arr_ is the array to test; _value_ is the value being tested for. - -### Return Value - -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") - -### Parameters - -_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. - -### Return Value - -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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_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. - -### See Also - -[targetname][27] [targetextension][44] [targetprefix][45] - -### Examples - -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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_ext_ is the new file extension, including the leading dot. - -### See Also - -[targetname][27] [targetdir][46] [targetprefix][45] [targetsuffix][47] - -### Examples - -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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_name_ is the new base file name. - -### See Also - -[targetdir][46] [targetextension][44] [targetprefix][45] [targetsuffix][47] - -### Examples - -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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_prefix_ is the new file name prefix. - -### See Also - -[targetname][27] [targetdir][46] [targetextension][44] [targetsuffix][47] - -### Examples - -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. - -### Applies To - -Solutions, projects, and configurations. - -### Parameters - -_suffix_ is the new filename suffix. - -### See Also - -[targetname][27] [targetdir][46] [targetprefix][45] [targetextension][44] - -### Examples - - - -- Add "-d" to debug versions of files configuration "Debug" targetsuffix - "-d" - -The **uuid** function sets the [Universally Unique Identifier][33] (UUID) for a -project. - -UUIDs are synonymous (for Premake's purposes) with [Globally Unique -Identifiers][48] (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. - -### Applies To - -Projects only. - -### Parameters - -_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][49] tool to create new -UUIDs, or [this website][50], or run Premake once to generate Visual Studio -files and copy the assigned UUIDs. - -### Returns - -The current project UUID, or **nil** if no UUID has been set. - -### Examples - -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. - -### Applies To - -Virtual paths, like files, may be set on the solution, project, and -configuration level. However, only project-level file lists are currently -supported. - -### Parameters - -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. - -### Examples - -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" } - -[1]: http://www.lua.org/manual/5.1/ -[2]: http://luaforge.net/ -[3]: http://industriousone.com/command-line-arguments -[4]: https://bitbucket.org/premake/premake-stable/wiki/buildaction -[5]: http://industriousone.com/configurations -[6]: http://industriousone.com/premake/quick-start -[7]: http://industriousone.com/osget -[8]: http://industriousone.com/platforms-0 -[9]: http://industriousone.com#block -[10]: http://industriousone.com/buildaction -[11]: https://bitbucket.org/premake/premake-dev/wiki/configurations -[12]: http://industriousone.com/files -[13]: http://industriousone.com/excludes -[14]: https://bitbucket.org/premake/premake-stable/wiki/flags -[15]: http://msdn.microsoft.com/en-us/library/kfz8ad09(VS.80).aspx -[16]: http://industriousone.com/pchheader -[17]: http://industriousone.com/pchsource -[18]: http://www.microsoft.com/msj/0197/exception/exception.aspx -[19]: http://industriousone.com/buildoptions -[20]: http://industriousone.com/linkoptions -[21]: http://industriousone.com/imageoptions -[22]: http://industriousone.com/implibname -[23]: http://industriousone.com/implibextension -[24]: http://industriousone.com/implibprefix -[25]: http://industriousone.com/implibsuffix -[26]: http://industriousone.com/implibdir -[27]: http://industriousone.com/targetname -[28]: http://www.lua.org/manual/5.1/manual.html#pdf-dofile -[29]: https://bitbucket.org/premake/premake-stable/wiki/kind -[30]: http://industriousone.com/links -[31]: http://industriousone.com/action -[32]: https://bitbucket.org/premake/premake-dev/wiki/objdir -[33]: http://en.wikipedia.org/wiki/UUID -[34]: https://bitbucket.org/premake/premake-stable/wiki/pchheader -[35]: https://bitbucket.org/premake/premake-stable/wiki/pchsource -[36]: http://industriousone.com/platforms -[37]: https://bitbucket.org/premake/premake-dev/wiki/platforms -[38]: http://industriousone.com/configuration -[39]: http://industriousone.com/prebuildcommands -[40]: http://industriousone.com/prelinkcommands -[41]: http://industriousone.com/postbuildcommands -[42]: http://industriousone.com#object -[43]: http://industriousone.com/solution -[44]: http://industriousone.com/targetextension -[45]: http://industriousone.com/targetprefix -[46]: http://industriousone.com/targetdir -[47]: http://industriousone.com/targetsuffix -[48]: http://en.wikipedia.org/wiki/Globally_Unique_Identifier -[49]: http://msdn2.microsoft.com/en-us/library/ms241442(VS.80).aspx -[50]: http://www.famkruithof.net/uuid/uuidgen |