AuroraPipeline/premake
1
0
Fork 0
Code Issues 1 Pull Requests Projects Releases 1 Wiki Activity

Fix broken links in docs

Browse Source
This commit is contained in:
KyrietS 2021-06-01 23:24:42 +02:00
parent ebbbb72ab7
commit 504c764016
37 changed files with 540 additions and 527 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
website/README.md
View File

@ -10,7 +10,21 @@ Editing our documentation website is very simple. You don't have to build a whol
1. Add a new Markdown file into the `docs/` folder. Follow naming conventions there. 1. Add a new Markdown file into the `docs/` folder. Follow naming conventions there.
2. Add your Markdown file's name into the `sidebars.js`. Make sure you've kept alphabetical order among category items. 2. Add your Markdown file's name into the `sidebars.js`. Make sure you've kept alphabetical order among category items.
*Use other files as references.* ### Adding a reference to another documentation page
Always reference another documentation page like this:
```markdown
[some text](Case-Sensitive-Filename.md)
```
and **never** like this:
```markdown
[some text](some-markdown-file)
[some text](/docs/some-markdown-file)
[some text](https://premake.github.io/docs/some-markdown-file)
```
*Use existing files in documentation as examples.*
## Installation ## Installation

4
website/docs/Adding-New-Action.md
View File

@ -8,7 +8,7 @@ Premake provides the ability to create your own actions. These can be simple one
This tutorial walks through the process of creating a new action that outputs solution and project information as Lua tables, which you can then use Premake to read and manipulate if you wish. This tutorial walks through the process of creating a new action that outputs solution and project information as Lua tables, which you can then use Premake to read and manipulate if you wish.
* [Starting Your New Action](starting-your-new-action) * [Starting Your New Action](Starting-Your-New-Action.md)
* [Generating Project Files](generating-project-files) * [Generating Project Files](Generating-Project-Files.md)
* Working with Configurations * Working with Configurations
* (More to come!) * (More to come!)

4
website/docs/Adding-Source-Files.md
View File

@ -2,7 +2,7 @@
title: Adding Source Files title: Adding Source Files
--- ---
You add files—source code, resources, and so on—to your project using the [files](files) function. You add files—source code, resources, and so on—to your project using the [files](files.md) function.
```lua ```lua
files { files {
@ -24,7 +24,7 @@ Paths should always use the forward slash `/` as a separator; Premake will trans
## Excluding Files ## Excluding Files
Sometimes you want most, but not all, of the files in a directory. In that case, use the [removefiles()](removing-values) function to mask out those few exceptions. Sometimes you want most, but not all, of the files in a directory. In that case, use the [removefiles()](Removing-Values.md) function to mask out those few exceptions.
```lua ```lua
files { "*.c" } files { "*.c" }

4
website/docs/Adding-Unit-Tests.md
View File

@ -7,7 +7,7 @@ Premake includes an automated testing system that you can use the verify the beh
## Add your first test ## Add your first test
Within our [Lucky module](introducing-modules) folder, create a new folder named `tests`. Within our [Lucky module](Introducing-Modules.md) folder, create a new folder named `tests`.
Within that folder, create a new file named `tests/test_lucky_numbers.lua` with a simple failing test: Within that folder, create a new file named `tests/test_lucky_numbers.lua` with a simple failing test:
@ -43,7 +43,7 @@ lucky/
Premake's automated testing module is considered an advanced, developer-only feature which is not enabled by default. To enable it, you simply need to add the line `test = require("self-test")` somewhere it will be executed before your tests run. Premake's automated testing module is considered an advanced, developer-only feature which is not enabled by default. To enable it, you simply need to add the line `test = require("self-test")` somewhere it will be executed before your tests run.
The best place to put it is in your [system script](system-scripts), which will make the testing action available to all of your projects. But if that isn't feasible for you or your users, you can also place it in your project or testing script. The best place to put it is in your [system script](System-Scripts.md), which will make the testing action available to all of your projects. But if that isn't feasible for you or your users, you can also place it in your project or testing script.
Premake's own code makes use of the latter approach: its `premake5.lua` script defines a custom action named "test", which in turn enables the built-in testing module: Premake's own code makes use of the latter approach: its `premake5.lua` script defines a custom action named "test", which in turn enables the built-in testing module:

20
website/docs/Build-Settings.md
View File

@ -2,19 +2,19 @@
title: Build Settings title: Build Settings
--- ---
Premake provides an ever-growing list of build settings that you can tweak; the following table lists some of the most common configuration tasks with a link to the corresponding functions. For a comprehensive list of available settings and functions, see the [Project API](project-api) and [Lua Library Additions](lua-library-additions). Premake provides an ever-growing list of build settings that you can tweak; the following table lists some of the most common configuration tasks with a link to the corresponding functions. For a comprehensive list of available settings and functions, see the [Project API](Project-API.md) and [Lua Library Additions](Lua-Library-Additions.md).
If you think something should be possible and you can't figure out how to do it, see [Support](/community/support). If you think something should be possible and you can't figure out how to do it, see [Support](/community/support).
| | | | | |
|-----------------------------------------------|----------------------| |-----------------------------------------------|----------------------|
| Specify the binary type (executable, library) | [kind](kind) | | Specify the binary type (executable, library) | [kind](kind.md) |
| Specify source code files | [files](files), [removefiles](files) | | Specify source code files | [files](files.md), [removefiles](files.md) |
| Define compiler or preprocessor symbols | [defines](defines) | | Define compiler or preprocessor symbols | [defines](defines.md) |
| Locate include files | [includedirs](includedirs) | | Locate include files | [includedirs](includedirs.md) |
| Set up precompiled headers | [pchheader](pchheader), [pchsource](pchsource) | | Set up precompiled headers | [pchheader](pchheader.md), [pchsource](pchsource.md) |
| Link libraries, frameworks, or other projects | [links](links), [libdirs](libdirs) | | Link libraries, frameworks, or other projects | [links](links.md), [libdirs](libdirs.md) |
| Enable debugging information | symbols(symbols) | | Enable debugging information | symbols(symbols) |
| Optimize for size or speed | [optimize](optimize) | | Optimize for size or speed | [optimize](optimize.md) |
| Add arbitrary build flags | [buildoptions](buildoptions), [linkoptions](linkoptions) | | Add arbitrary build flags | [buildoptions](buildoptions.md), [linkoptions](linkoptions.md) |
| Set the name or location of compiled targets | [targetname](targetname), [targetdir](targetdir) | | Set the name or location of compiled targets | [targetname](targetname.md), [targetdir](targetdir.md) |

4
website/docs/Building-Premake.md
View File

@ -7,7 +7,7 @@ If you downloaded a prebuilt binary package you can skip this page, which discus
## Using a Source Code Package ## ## Using a Source Code Package ##
If you have one of the [official source code packages](http://premake.github.io/download.html), you'll find that project files for a variety of toolsets have already been generated for you in the `build/` folder. Find the right set for your platform and toolset and build as you normally would (i.e. run `make`). The resulting binaries will be placed in the top-level `bin/` folder. If you have one of the [official source code packages](/download), you'll find that project files for a variety of toolsets have already been generated for you in the `build/` folder. Find the right set for your platform and toolset and build as you normally would (i.e. run `make`). The resulting binaries will be placed in the top-level `bin/` folder.
Skip ahead to the next section to learn more about using the source version of Premake. Skip ahead to the next section to learn more about using the source version of Premake.
@ -31,7 +31,7 @@ call "%VS140COMNTOOLS%\..\..\VC\vcvarsall.bat" # Sets up the necessary environme
nmake -f Bootstrap.mak MSDEV=vs2015 windows # For Windows with Visual Studio 2015. nmake -f Bootstrap.mak MSDEV=vs2015 windows # For Windows with Visual Studio 2015.
``` ```
On other platforms, if the bootstrap fails to build, you will need to have a working Premake executable on your system. The easiest way to get one is by [downloading prebuilt binary package](http://premake.github.io/download.html). If a binary is not available for your system, or if you would prefer to build one yourself, grab the latest source code package from that same site and follow the steps in **Using a Source Code Package**, above. On other platforms, if the bootstrap fails to build, you will need to have a working Premake executable on your system. The easiest way to get one is by [downloading prebuilt binary package](/download). If a binary is not available for your system, or if you would prefer to build one yourself, grab the latest source code package from that same site and follow the steps in **Using a Source Code Package**, above.
Once you have a working Premake available, you can generate the project files for your toolset by running a command like the following in the top-level Premake directory: Once you have a working Premake available, you can generate the project files for your toolset by running a command like the following in the top-level Premake directory:

12
website/docs/Code-Overview.md
View File

@ -10,7 +10,7 @@ The Premake source code is organized into a few different folders:
* `src/base` contains the core Lua scripts, the code that is used to read and process your project scripts, and supporting logic for the actions and exporters. * `src/base` contains the core Lua scripts, the code that is used to read and process your project scripts, and supporting logic for the actions and exporters.
* `src/host` contains all of the C language code, logic that either can't easily be written in Lua because of the way it needs to interact with the underlying operating system, or because a Lua implementation would be too slow. We try to keep C code to a minimum and use Lua whenever we can, to enable [overrides and call arrays](overrides-and-call-arrays). * `src/host` contains all of the C language code, logic that either can't easily be written in Lua because of the way it needs to interact with the underlying operating system, or because a Lua implementation would be too slow. We try to keep C code to a minimum and use Lua whenever we can, to enable [overrides and call arrays](Overrides-and-Call-Arrays.md).
* `src/tools` contains the adapters for command line toolsets like GCC and Clang. We will probably be migrating these toward modules in the near-ish future as well. * `src/tools` contains the adapters for command line toolsets like GCC and Clang. We will probably be migrating these toward modules in the near-ish future as well.
@ -22,7 +22,7 @@ In addition to those general categories, there are a few special files of note:
* `src/_premake_init.lua` sets up much of the initial configuration, including all of the project scripting functions, the default set of command line arguments, and the default project configurations. * `src/_premake_init.lua` sets up much of the initial configuration, including all of the project scripting functions, the default set of command line arguments, and the default project configurations.
* `src/_modules.lua` contains the list of built-in modules which are automatically loaded in startup. See [Embedding Modules](embedding-modules) for more information. * `src/_modules.lua` contains the list of built-in modules which are automatically loaded in startup. See [Embedding Modules](Embedding-Modules.md) for more information.
* `src/_manifest.lua` lists the Lua scripts that should be embedded into the Premake executable when making the release builds. There are separate manifests for Premake's core scripts and each embedded module. * `src/_manifest.lua` lists the Lua scripts that should be embedded into the Premake executable when making the release builds. There are separate manifests for Premake's core scripts and each embedded module.
@ -39,9 +39,9 @@ Execution starts at `main()` in `src/host/premake_main.c`, which calls into to `
* Once `src/premake_main.lua` has finished, `premake_execute()` calls `_premake_main()`, which located at the end of `src/_premake_main.lua`, and waits for it to return. * Once `src/premake_main.lua` has finished, `premake_execute()` calls `_premake_main()`, which located at the end of `src/_premake_main.lua`, and waits for it to return.
At this point, execution has moved into and remains in Lua; [extending Premake by overriding functions and call arrays](overrides-and-call-arrays) now becomes possible. At this point, execution has moved into and remains in Lua; [extending Premake by overriding functions and call arrays](Overrides-and-Call-Arrays.md) now becomes possible.
`_premake_main()` uses a [call array](overrides-and-call-arrays) to control the high-level process of evaluating the user scripts and acting on the results. Notable functions in this list include: `_premake_main()` uses a [call array](Overrides-and-Call-Arrays.md) to control the high-level process of evaluating the user scripts and acting on the results. Notable functions in this list include:
* `prepareEnvironment()` sets more global variables and otherwise gets the script environment ready to use. * `prepareEnvironment()` sets more global variables and otherwise gets the script environment ready to use.
@ -49,7 +49,7 @@ At this point, execution has moved into and remains in Lua; [extending Premake b
* `checkInteractive()` is responsible for launching the REPL prompt, if requested. * `checkInteractive()` is responsible for launching the REPL prompt, if requested.
* `runSystemScript()` runs [the user's system script](system-scripts), and `runUserScript()` runs the project script found by `locateUserScript()`. * `runSystemScript()` runs [the user's system script](System-Scripts.md), and `runUserScript()` runs the project script found by `locateUserScript()`.
* `processCommandLine()` handles any command line options and sets the target action and arguments. This needs to happen after the project script has run, in case it defines new options or modifies the behavior of existing options—a common point of confusion. * `processCommandLine()` handles any command line options and sets the target action and arguments. This needs to happen after the project script has run, in case it defines new options or modifies the behavior of existing options—a common point of confusion.
@ -59,5 +59,5 @@ At this point, execution has moved into and remains in Lua; [extending Premake b
* `callAction()` passes each workspace, project, rule, and other container to the target action, causing the appropriate result--like generating a Visual Studio project or GNU makefile--to occur. This container iteration is done in `action.call()` in `src/base/action.lua`. * `callAction()` passes each workspace, project, rule, and other container to the target action, causing the appropriate result--like generating a Visual Studio project or GNU makefile--to occur. This container iteration is done in `action.call()` in `src/base/action.lua`.
Calling the action, via `callAction()`, is where the interesting part for most people begins. Control now transfers to one of exporters, causing the project files to be written. For more information on how *that* happens, see [Creating a New Action](adding-new-action). Calling the action, via `callAction()`, is where the interesting part for most people begins. Control now transfers to one of exporters, causing the project files to be written. For more information on how *that* happens, see [Creating a New Action](Adding-New-Action.md).

2
website/docs/Coding-Conventions.md
View File

@ -111,4 +111,4 @@ Similarly, instead of implementing the output of a particular section of the pro
end end
``` ```
For an example of how to implement a new feature using these conventions, see [Overrides and Call Arrays](Overrides-and-Call-Arrays). For an example of how to implement a new feature using these conventions, see [Overrides and Call Arrays](Overrides-and-Call-Arrays.md).

8
website/docs/Command-Line-Arguments.md
View File

@ -2,7 +2,7 @@
title: Command Line Arguments title: Command Line Arguments
--- ---
Premake provides the ability to define and handle new command-line arguments from within your project script using the [newaction](newaction) and [newoption](newoption) functions. Premake provides the ability to define and handle new command-line arguments from within your project script using the [newaction](newaction.md) and [newoption](newoption.md) functions.
## Actions and Options ## Actions and Options
@ -12,7 +12,7 @@ An _action_ indicates what Premake should do on any given run. For instance, the
An _option_ modifies the behavior of the action. For instance, the `dotnet` option is used to change which .NET compiler set is used in the generated files. Options can accept a value, such as `--dotnet=mono` or act as a flag, like `--with-opengl`. An _option_ modifies the behavior of the action. For instance, the `dotnet` option is used to change which .NET compiler set is used in the generated files. Options can accept a value, such as `--dotnet=mono` or act as a flag, like `--with-opengl`.
From within your script, you can identify the current action with the [`_ACTION`](_ACTION) global variable, a string value. You can check for an option using the [`_OPTIONS`](_OPTIONS) table, which contains a list of key-value pairs. The key is the option identifier ("dotnet"), which references the command line value ("mono") or an empty string for valueless options. From within your script, you can identify the current action with the [`_ACTION`](_ACTION.md) global variable, a string value. You can check for an option using the [`_OPTIONS`](_OPTIONS.md) table, which contains a list of key-value pairs. The key is the option identifier ("dotnet"), which references the command line value ("mono") or an empty string for valueless options.
```lua ```lua
-- delete a file if the clean action is running -- delete a file if the clean action is running
@ -26,7 +26,7 @@ targetdir ( _OPTIONS["outdir"] or "out" )
## Creating New Options ## Creating New Options
New command-line options are created using the [`newoption`](newoption) function, passing a table which fully describes the option. This is best illustrated with some examples. New command-line options are created using the [`newoption`](newoption.md) function, passing a table which fully describes the option. This is best illustrated with some examples.
Here is an option intended to force the use of OpenGL in a 3D application. It serves as a simple flag, and does not take any value. Here is an option intended to force the use of OpenGL in a 3D application. It serves as a simple flag, and does not take any value.
@ -125,4 +125,4 @@ newaction {
The actual code to be executed when the action is fired should be placed in the `execute()` function. The actual code to be executed when the action is fired should be placed in the `execute()` function.
That's the simple version, which is great for one-off operations that don't need to access to the specific project information. For a tutorial for writing a more complete action, see [Adding a New Action](adding-new-Action). That's the simple version, which is great for one-off operations that don't need to access to the specific project information. For a tutorial for writing a more complete action, see [Adding a New Action](Adding-New-Action.md).

10
website/docs/Configurations-and-Platforms.md
View File

@ -6,7 +6,7 @@ A *configuration* is a collection of settings to apply to a build, including fla
## Build Configurations ## Build Configurations
The [previous examples](your-first-script) showed how to specify build configurations. The [previous examples](Your-First-Script.md) showed how to specify build configurations.
```lua ```lua
workspace "MyWorkspace" workspace "MyWorkspace"
@ -27,7 +27,7 @@ workspace "MyWorkspace"
configurations { "Froobniz", "Fozbat", "Cthulhu" } configurations { "Froobniz", "Fozbat", "Cthulhu" }
``` ```
The meaning of the build configuration depends on the settings you apply to it, as shown in [the earlier examples](your-first-script). The meaning of the build configuration depends on the settings you apply to it, as shown in [the earlier examples](Your-First-Script.md).
```lua ```lua
workspace "HelloWorld" workspace "HelloWorld"
@ -42,7 +42,7 @@ workspace "HelloWorld"
optimize "On" optimize "On"
``` ```
The [Filters](filters) section will cover this in more detail. The [Filters](Filters.md) section will cover this in more detail.
## Platforms ## Platforms
@ -56,7 +56,7 @@ platforms { "Win32", "Win64", "Xbox360" }
Once set, your listed platforms will appear in the Platforms list of your IDE. So you can choose a "Debug Win32" build, or a "Release Xbox360" build, or any combination of the two lists. Once set, your listed platforms will appear in the Platforms list of your IDE. So you can choose a "Debug Win32" build, or a "Release Xbox360" build, or any combination of the two lists.
Just like the build configurations, the platform names have no meaning on their own. You provide meaning by applying settings using the [`filter`](filter) function. Just like the build configurations, the platform names have no meaning on their own. You provide meaning by applying settings using the [`filter`](filter.md) function.
```lua ```lua
configurations { "Debug", "Release" } configurations { "Debug", "Release" }
@ -76,7 +76,7 @@ filter { "platforms:Xbox360" }
Unlike build configurations, platforms are completely optional. If you don't need them, just don't call the platforms function at all and the toolset's default behavior will be used. Unlike build configurations, platforms are completely optional. If you don't need them, just don't call the platforms function at all and the toolset's default behavior will be used.
Platforms are just another form of build configuration. You can use all of the same settings, and the same scoping rules apply. You can use the [`system`](system) and [`architecture`()`](architecture) settings without platforms, and you can use otherwise non-platform settings in a platform configuration. If you've ever done build configurations like "Debug Static", "Debug DLL", "Release Static", and "Release DLL", platforms can really simplify things. Platforms are just another form of build configuration. You can use all of the same settings, and the same scoping rules apply. You can use the [`system`](system.md) and [`architecture`()`](architecture.md) settings without platforms, and you can use otherwise non-platform settings in a platform configuration. If you've ever done build configurations like "Debug Static", "Debug DLL", "Release Static", and "Release DLL", platforms can really simplify things.
```lua ```lua
configurations { "Debug", "Release" } configurations { "Debug", "Release" }

8
website/docs/Custom-Build-Commands.md
View File

@ -4,11 +4,11 @@ title: Custom Build Commads
There are a few different ways that you can add custom commands to your Premake-generated builds: *pre- and post-build stages*, *custom build commands*, and *custom rules*. There are a few different ways that you can add custom commands to your Premake-generated builds: *pre- and post-build stages*, *custom build commands*, and *custom rules*.
You can also use [Makefile projects](makefile-projects) to execute external shell scripts or makefiles, rather than use the normal build system. You can also use [Makefile projects](Makefile-Projects.md) to execute external shell scripts or makefiles, rather than use the normal build system.
## Pre- and Post-Build Stages ## Pre- and Post-Build Stages
These are the simplest to setup and use: pass one or more command lines to the [`prebuildcommands`](prebuildcommands), [`prelinkcommands`](prelinkcommands), or [`postbuildcommands`](postbuildcommands) functions. You can use [Tokens](tokens) to create generic commands that will work across platforms and configurations. These are the simplest to setup and use: pass one or more command lines to the [`prebuildcommands`](prebuildcommands.md), [`prelinkcommands`](prelinkcommands.md), or [`postbuildcommands`](postbuildcommands.md) functions. You can use [Tokens](Tokens.md) to create generic commands that will work across platforms and configurations.
```lua ```lua
@ -46,7 +46,7 @@ filter 'files:**.lua'
The basic syntax follows Visual Studio's model, but it should be easy to see how it would translate to makefiles. The basic syntax follows Visual Studio's model, but it should be easy to see how it would translate to makefiles.
Build rules follow the same configuration scoping as the rest of the Premake API. You can apply rules to a specific platform or build configuration, to specific files or all files, or to any combination. And you can use [Tokens](tokens) to create generic commands that will work across platforms and configurations. Build rules follow the same configuration scoping as the rest of the Premake API. You can apply rules to a specific platform or build configuration, to specific files or all files, or to any combination. And you can use [Tokens](Tokens.md) to create generic commands that will work across platforms and configurations.
If the outputs include any object files, they will be automatically added to the link step. Ideally, any source code files included in the outputs would be fed back into the build, but that is not the case currently. If the outputs include any object files, they will be automatically added to the link step. Ideally, any source code files included in the outputs would be fed back into the build, but that is not the case currently.
@ -68,4 +68,4 @@ Custom build commands currently have a few shortcomings. Help fixing these issue
## Custom Rules ## ## Custom Rules ##
The [custom rules feature](custom-rules) is similar to custom build commands. It allows you describe how to build a particular kind of file, but in a more generic way, and with variables that can be set in your project script. [Learn more about custom rules here](custom-rules). The [custom rules feature](Custom-Rules.md) is similar to custom build commands. It allows you describe how to build a particular kind of file, but in a more generic way, and with variables that can be set in your project script. [Learn more about custom rules here](Custom-Rules.md).

8
website/docs/Custom-Rules.md
View File

@ -2,7 +2,7 @@
title: Custom Rules title: Custom Rules
--- ---
Rule file generation is a new and experimental feature of Premake 5.0, which currently only supports Visual Studio and the gmake2 action. It allows you describe how to build a particular kind of file, similar to [custom build commands](custom-build-commands), but in a more generic way, and with variables that can be set in your project script. Rule file generation is a new and experimental feature of Premake 5.0, which currently only supports Visual Studio and the gmake2 action. It allows you describe how to build a particular kind of file, similar to [custom build commands](Custom-Build-Commands.md), but in a more generic way, and with variables that can be set in your project script.
At generation time, Premake will output the appropriate rule files for the target action, just as it does for workspaces and projects. For Visual Studio 2010+, Premake will generate `RuleName.props`, `RuleName.targets`, and `RuleName.xml`. Currently, no other actions are supported. At generation time, Premake will output the appropriate rule files for the target action, just as it does for workspaces and projects. For Visual Studio 2010+, Premake will generate `RuleName.props`, `RuleName.targets`, and `RuleName.xml`. Currently, no other actions are supported.
@ -23,11 +23,11 @@ rule "MyCustomRule"
buildoutputs '%(IntDir)/%(Filename).obj"' buildoutputs '%(IntDir)/%(Filename).obj"'
``` ```
This rule will pass all files in project with the ".xyz" file extension through the specified build command. At export time, the files `MyCustomRule.props`, `MyCustomRule.targets`, and `MyCustomRule.xml` will be generated in the sample directory. Like workspaces and projects, this can be changed with [`location`](location) and [`filename`](filename). This rule will pass all files in project with the ".xyz" file extension through the specified build command. At export time, the files `MyCustomRule.props`, `MyCustomRule.targets`, and `MyCustomRule.xml` will be generated in the sample directory. Like workspaces and projects, this can be changed with [`location`](location.md) and [`filename`](filename.md).
There are still some shortcomings with the current implementation, notably that we don't have a generic set of variables to use in the commands. The example above uses Visual Studio's own variables such as `%(FullPath)` and `%(IntDir)`; obviously these won't work if rules are implemented for a different toolset. There are still some shortcomings with the current implementation, notably that we don't have a generic set of variables to use in the commands. The example above uses Visual Studio's own variables such as `%(FullPath)` and `%(IntDir)`; obviously these won't work if rules are implemented for a different toolset.
To use the sample rule from above in a project, list the rule name in a [`rules`](rules) statement: To use the sample rule from above in a project, list the rule name in a [`rules`](rules.md) statement:
```lua ```lua
project "MyProject" project "MyProject"
@ -37,7 +37,7 @@ project "MyProject"
## Rule Properties ## Rule Properties
The benefit of custom rules over [custom build commands](custom-build-commands) is the ability to specify *properties*, which can then be set like any other project or configuration value. Properties are defined with [`propertydefinition`](propertydefinition) functions, including default values which can be overridden by specific project configurations. The benefit of custom rules over [custom build commands](Custom-Build-Commands.md) is the ability to specify *properties*, which can then be set like any other project or configuration value. Properties are defined with [`propertydefinition`](propertydefinition.md) functions, including default values which can be overridden by specific project configurations.
```lua ```lua
rule "MyCustomRule" rule "MyCustomRule"

2
website/docs/Debugging-Scripts.md
View File

@ -7,7 +7,7 @@ title: Debugging Scripts
Since Premake's update to 5.3, the only debugger that seems to be able to debug Premake is the free ZeroBrane Studio IDE. Since Premake's update to 5.3, the only debugger that seems to be able to debug Premake is the free ZeroBrane Studio IDE.
* [Download ZeroBrane Studio](https://studio.zerobrane.com/) and install it * [Download ZeroBrane Studio](https://studio.zerobrane.com/) and install it
* Compile a [debug build of Premake](building-premake). Your premake build should have built luasocket.dll, and there is a mobdebug.lua file in the root. Copy both alongside your premake executable to the location where you intend to run premake. * Compile a [debug build of Premake](Building-Premake.md). Your premake build should have built luasocket.dll, and there is a mobdebug.lua file in the root. Copy both alongside your premake executable to the location where you intend to run premake.
* Run ZeroBrane Studio and in the Project dropdown, select **Start Debugger Server**. * Run ZeroBrane Studio and in the Project dropdown, select **Start Debugger Server**.
* There's also a Project tab. Right-click the root folder and select **Project Directory > Choose...** to select the root of the premake repository. Open the lua file you want to debug (you can start with _premake_init.lua) and set a breakpoint. * There's also a Project tab. Right-click the root folder and select **Project Directory > Choose...** to select the root of the premake repository. Open the lua file you want to debug (you can start with _premake_init.lua) and set a breakpoint.
* Run premake with your desired command line and append `--scripts=path_to_premake --debugger` path_to_premake is the root of the repository where src lives. This isn't necessary if you run premake in the same directory as the src folder. If all goes well premake should think for a moment and the debugger should flash indicating that it has broken execution. * Run premake with your desired command line and append `--scripts=path_to_premake --debugger` path_to_premake is the root of the repository where src lives. This isn't necessary if you run premake in the same directory as the src folder. If all goes well premake should think for a moment and the debugger should flash indicating that it has broken execution.

8
website/docs/Developing-Modules.md
View File

@ -4,7 +4,7 @@ title: Developing Modules
Modules are the preferred way to package your customizations to reuse and share with others. Modules are the preferred way to package your customizations to reuse and share with others.
* [Introduction](introducing-modules) * [Introduction](Introducing-Modules.md)
* [Adding Unit Tests](adding-unit-tests) * [Adding Unit Tests](Adding-Unit-Tests.md)
* [Sharing Your Module](sharing-your-module) * [Sharing Your Module](Sharing-Your-Module.md)
* [Embedding Modules](embedding-modules) * [Embedding Modules](Embedding-Modules.md)

8
website/docs/Extending-Premake.md
View File

@ -2,7 +2,7 @@
title: Extending Premake title: Extending Premake
--- ---
Premake is written almost entirely in [Lua](http://www.lua.org/), the same dynamic language that you use while [writing your project scripts](your-first-script). Because Lua is dynamic, you can easily replace functions, add new values, and generally run amok in the code to make things work the way you like. Premake is written almost entirely in [Lua](http://www.lua.org/), the same dynamic language that you use while [writing your project scripts](Your-First-Script.md). Because Lua is dynamic, you can easily replace functions, add new values, and generally run amok in the code to make things work the way you like.
We've structured (or are in the process of structuring, with the intention of being done before the 5.0 release) the code with this feature in mind, adopting coding conventions that make it easy to hook and override or extend Premake's functionality. We've structured (or are in the process of structuring, with the intention of being done before the 5.0 release) the code with this feature in mind, adopting coding conventions that make it easy to hook and override or extend Premake's functionality.
@ -12,8 +12,8 @@ Before you start hacking away, you should be comfortable browsing through the [s
If you haven't already, you should [grab a source code package, or clone the code repository on GitHub](/download) to use as a reference. If you haven't already, you should [grab a source code package, or clone the code repository on GitHub](/download) to use as a reference.
Then check out the [Code Overview](code-overview) to get a general sense of where things live, and [Coding Conventions](coding-conventions) for an overview on how the code is structured and why we did it that way. Then check out the [Code Overview](Code-Overview.md) to get a general sense of where things live, and [Coding Conventions](Coding-Conventions.md) for an overview on how the code is structured and why we did it that way.
Have a look at [Overrides and Call Arrays](overrides-and-call-arrays) to learn more about Premake's extensible coding conventions, and how you can leverage them to easily change its current behavior. Have a look at [Overrides and Call Arrays](Overrides-and-Call-Arrays.md) to learn more about Premake's extensible coding conventions, and how you can leverage them to easily change its current behavior.
When you're ready, check out the [documentation index](/docs) for more customization topics like adding support for new actions and toolsets, and [how to use modules](introducing-modules) to package your code up to share with others. When you're ready, check out the [documentation index](/docs) for more customization topics like adding support for new actions and toolsets, and [how to use modules](Introducing-Modules.md) to package your code up to share with others.

4
website/docs/Filters.md
View File

@ -2,7 +2,7 @@
title: Filters title: Filters
--- ---
Premake's filter system allows you target build settings to the exact configurations in which you want them to appear. You can filter by specific build configurations or platforms, operating system, target actions, [and more](filter). Premake's filter system allows you target build settings to the exact configurations in which you want them to appear. You can filter by specific build configurations or platforms, operating system, target actions, [and more](filter.md).
Here is an example which sets a preprocessor symbol named "DEBUG" in a workspace's "Debug" build configuration, and "NDEBUG" in the Release configuration. Here is an example which sets a preprocessor symbol named "DEBUG" in a workspace's "Debug" build configuration, and "NDEBUG" in the Release configuration.
@ -51,4 +51,4 @@ The filter "configurations:Release" would be skipped, because the pattern "Relea
The last filter "{}" does not define any filtering criteria, and so does not exclude anything. Any settings applied after this filter will appear in _all_ configurations within the workspace or project. The last filter "{}" does not define any filtering criteria, and so does not exclude anything. Any settings applied after this filter will appear in _all_ configurations within the workspace or project.
Filters may also be combined, modified with "or" or "not", and use pattern matches. For a more complete description and lots of examples, see [`filter`](filter). Filters may also be combined, modified with "or" or "not", and use pattern matches. For a more complete description and lots of examples, see [`filter`](filter.md).

2
website/docs/How-to-Help.md
View File

@ -2,7 +2,7 @@
title: How to Help title: How to Help
--- ---
I've posted a [Development Roadmap](Development-Roadmap) to get us to the Premake 5.0 release. That is where help is most needed right now and there is plenty to do, from moving documentation (easy) to developing new modules (harder). I've posted a [Development Roadmap](Development-Roadmap.md) to get us to the Premake 5.0 release. That is where help is most needed right now and there is plenty to do, from moving documentation (easy) to developing new modules (harder).
Here are some other ways you can help: Here are some other ways you can help:

8
website/docs/Introducing-Modules.md
View File

@ -6,9 +6,9 @@ A Premake module is simply a Lua script that follows a few extra conventions:
* the name of the script file is the name of the module * the name of the script file is the name of the module
* the script should be placed in a folder of the same name * the script should be placed in a folder of the same name
* the folder should be placed [somewhere Premake can find it](locating-scripts) * the folder should be placed [somewhere Premake can find it](Locating-Scripts.md)
Let's start with a simple example. Create a new module by creating a folder named `lucky` and placing it [somewhere where Premake can find it](locating-scripts). Create a new file inside this folder named `lucky.lua`, with this simple starter module: Let's start with a simple example. Create a new module by creating a folder named `lucky` and placing it [somewhere where Premake can find it](Locating-Scripts.md). Create a new file inside this folder named `lucky.lua`, with this simple starter module:
```lua ```lua
-- lucky.lua -- lucky.lua
@ -52,7 +52,7 @@ Generating MyProject.vcxproj...
Done. Done.
``` ```
`require()` is [Lua's standard module loading function](http://www.lua.org/pil/8.1.html) (though the version in Premake has been extended to support [more search locations](locating-scripts)). The first time a module is required, Lua will load it and return the module's interface (the table we assigned to `m` in the example). If the module is later required again, the same table instance will be returned, without reloading the scripts. `require()` is [Lua's standard module loading function](http://www.lua.org/pil/8.1.html) (though the version in Premake has been extended to support [more search locations](Locating-Scripts.md)). The first time a module is required, Lua will load it and return the module's interface (the table we assigned to `m` in the example). If the module is later required again, the same table instance will be returned, without reloading the scripts.
Any local variables or functions you define in your module will be private, and only accessible from your module script. Variables or functions you assign to the module table will public, and accessible through the module interface returned from `require()`. Any local variables or functions you define in your module will be private, and only accessible from your module script. Variables or functions you assign to the module table will public, and accessible through the module interface returned from `require()`.
@ -87,5 +87,5 @@ local luckyEight = lucky.makeNumberLucky(8)
That's all there to it! That's all there to it!
Note that if you decide you want to [share your module](/community/modules) with other people, there are a [few other considerations to make](sharing-your-module). Note that if you decide you want to [share your module](/community/modules) with other people, there are a [few other considerations to make](Sharing-Your-Module.md).

6
website/docs/Linking.md
View File

@ -2,7 +2,7 @@
title: Linking title: Linking
--- ---
Linking to external libraries is done with the [`links`](links) function. Linking to external libraries is done with the [`links`](links.md) function.
```lua ```lua
links { "png", "zlib" } links { "png", "zlib" }
@ -29,13 +29,13 @@ workspace "MyWorkspace"
### Finding Libraries ### ### Finding Libraries ###
You can tell Premake where to search for libraries with the [`libdirs`](libdirs) function. You can tell Premake where to search for libraries with the [`libdirs`](libdirs.md) function.
```lua ```lua
libdirs { "libs", "../mylibs" } libdirs { "libs", "../mylibs" }
``` ```
If you need to discover the location of a library, use the [`os.findlib`](os.findlib) function. If you need to discover the location of a library, use the [`os.findlib`](os.findlib.md) function.
```lua ```lua
libdirs { os.findlib("X11") } libdirs { os.findlib("X11") }

2
website/docs/Locating-Scripts.md
View File

@ -20,6 +20,6 @@ When Premake needs to load a script file, via a call to `dofile()` or `include()
* In the directory containing the currently running Premake executable. * In the directory containing the currently running Premake executable.
Note that these search paths also work for modules (e.g. `~/.premake/monodevelop`) and [system scripts](system-scripts). Note that these search paths also work for modules (e.g. `~/.premake/monodevelop`) and [system scripts](System-Scripts.md).
You are free to add or remove paths from `premake.path`, in either your project or system scripts. Any requests to load scripts after the change will use your modified path. You are free to add or remove paths from `premake.path`, in either your project or system scripts. Any requests to load scripts after the change will use your modified path.

205
website/docs/Lua-Library-Additions.md
View File

@ -1,136 +1,135 @@
### Globals ### Globals
* [dofileopt](dofileopt) * [dofileopt](dofileopt.md)
* [include](include) * [include](include.md)
* [includeexternal](includeexternal) * [includeexternal](includeexternal.md)
* [require](require) * [require](require.md)
### Debugging ### Debugging
* [debug.prompt](debug.prompt) * [debug.prompt](debug.prompt.md)
### HTTP/S ### HTTP/S
* [http.download](http.download) * [http.download](http.download.md)
* [http.get](http.get) * [http.get](http.get.md)
* [http.post](http.post) * [http.post](http.post.md)
### I/O ### I/O
* [io.readfile](io.readfile) * [io.readfile](io.readfile.md)
* [io.writefile](io.writefile) * [io.writefile](io.writefile.md)
### JSON ### JSON
* [json.decode](json.decode) * [json.decode](json.decode.md)
* [json.encode](json.encode) * [json.encode](json.encode.md)
### OS ### OS
* [os.chdir](os.chdir) * [os.chdir](os.chdir.md)
* [os.chmod](os.chmod) * [os.chmod](os.chmod.md)
* [os.comparefiles](os.comparefiles) * [os.comparefiles](os.comparefiles.md)
* [os.copyfile](os.copyfile) * [os.copyfile](os.copyfile.md)
* [os.executef](os.executef) * [os.executef](os.executef.md)
* [os.findheader](os.findheader) * [os.findheader](os.findheader.md)
* [os.findlib](os.findlib) * [os.findlib](os.findlib.md)
* [os.get](os.get) * [os.get](os.get.md)
* [os.getcwd](os.getcwd) * [os.getcwd](os.getcwd.md)
* [os.getpass](os.getpass) * [os.getpass](os.getpass.md)
* [os.getversion](os.getversion) * [os.getversion](os.getversion.md)
* [os.host](os.host) * [os.host](os.host.md)
* [os.is](os.is) * [os.is](os.is.md)
* [os.is64bit](os.is64bit) * [os.is64bit](os.is64bit.md)
* [os.isdir](os.isdir) * [os.isdir](os.isdir.md)
* [os.isfile](os.isfile) * [os.isfile](os.isfile.md)
* [os.islink](os.islink) * [os.islink](os.islink.md)
* [os.locate](os.locate) * [os.locate](os.locate.md)
* [os.matchdirs](os.matchdirs) * [os.matchdirs](os.matchdirs.md)
* [os.matchfiles](os.matchfiles) * [os.matchfiles](os.matchfiles.md)
* [os.mkdir](os.mkdir) * [os.mkdir](os.mkdir.md)
* [os.outputof](os.outputof) * [os.outputof](os.outputof.md)
* [os.pathsearch](os.pathsearch) * [os.pathsearch](os.pathsearch.md)
* [os.realpath](os.realpath) * [os.realpath](os.realpath.md)
* [os.remove](os.remove) * [os.remove](os.remove.md)
* [os.rmdir](os.rmdir) * [os.rmdir](os.rmdir.md)
* [os.stat](os.stat) * [os.stat](os.stat.md)
* [os.target](os.target) * [os.target](os.target.md)
* [os.touchfile](os.touchfile) * [os.touchfile](os.touchfile.md)
* [os.translateCommands](os.translateCommands) * [os.translateCommands](os.translateCommands.md)
* [os.uuid](os.uuid) * [os.uuid](os.uuid.md)
* [os.writefile_ifnotequal](os.writefile_ifnotequal) * [os.writefile_ifnotequal](os.writefile_ifnotequal.md)
### Path ### Path
* [path.appendextension](path.appendextension) * [path.appendExtension](path.appendExtension.md)
* [path.appendExtension](path.appendExtension) * [path.getabsolute](path.getabsolute.md)
* [path.getabsolute](path.getabsolute) * [path.getbasename](path.getbasename.md)
* [path.getbasename](path.getbasename) * [path.getdirectory](path.getdirectory.md)
* [path.getdirectory](path.getdirectory) * [path.getdrive](path.getdrive.md)
* [path.getdrive](path.getdrive) * [path.getextension](path.getextension.md)
* [path.getextension](path.getextension) * [path.getname](path.getname.md)
* [path.getname](path.getname) * [path.getrelative](path.getrelative.md)
* [path.getrelative](path.getrelative) * [path.hasextension](path.hasextension.md)
* [path.hasextension](path.hasextension) * [path.isabsolute](path.isabsolute.md)
* [path.isabsolute](path.isabsolute) * [path.iscfile](path.iscfile.md)
* [path.iscfile](path.iscfile) * [path.iscppfile](path.iscppfile.md)
* [path.iscppfile](path.iscppfile) * [path.iscppheader](path.iscppheader.md)
* [path.iscppheader](path.iscppheader) * [path.isframework](path.isframework.md)
* [path.isframework](path.isframework) * [path.islinkable](path.islinkable.md)
* [path.islinkable](path.islinkable) * [path.isobjectfile](path.isobjectfile.md)
* [path.isobjectfile](path.isobjectfile) * [path.isresourcefile](path.isresourcefile.md)
* [path.isresourcefile](path.isresourcefile) * [path.join](path.join.md)
* [path.join](path.join) * [path.normalize](path.normalize.md)
* [path.normalize](path.normalize) * [path.rebase](path.rebase.md)
* [path.rebase](path.rebase) * [path.replaceextension](path.replaceextension.md)
* [path.replaceextension](path.replaceextension) * [path.translate](path.translate.md)
* [path.translate](path.translate) * [path.wildcards](path.wildcards.md)
* [path.wildcards](path.wildcards)
### String ### String
* [string.capitalized](string.capitalized) * [string.capitalized](string.capitalized.md)
* [string.contains](string.contains) * [string.contains](string.contains.md)
* [string.endswith](string.endswith) * [string.endswith](string.endswith.md)
* [string.escapepattern](string.escapepattern) * [string.escapepattern](string.escapepattern.md)
* [string.explode](string.explode) * [string.explode](string.explode.md)
* [string.findlast](string.findlast) * [string.findlast](string.findlast.md)
* [string.hash](string.hash) * [string.hash](string.hash.md)
* [string.lines](string.lines) * [string.lines](string.lines.md)
* [string.plural](string.plural) * [string.plural](string.plural.md)
* [string.sha1](string.sha1) * [string.sha1](string.sha1.md)
* [string.startswith](string.startswith) * [string.startswith](string.startswith.md)
### Table ### Table
* [table.arraycopy](table.arraycopy) * [table.arraycopy](table.arraycopy.md)
* [table.contains](table.contains) * [table.contains](table.contains.md)
* [table.deepcopy](table.deepcopy) * [table.deepcopy](table.deepcopy.md)
* [table.extract](table.extract) * [table.extract](table.extract.md)
* [table.filterempty](table.filterempty) * [table.filterempty](table.filterempty.md)
* [table.flatten](table.flatten) * [table.flatten](table.flatten.md)
* [table.fold](table.fold) * [table.fold](table.fold.md)
* [table.foreachi](table.foreachi) * [table.foreachi](table.foreachi.md)
* [table.implode](table.implode) * [table.implode](table.implode.md)
* [table.indexof](table.indexof) * [table.indexof](table.indexof.md)
* [table.insertafter](table.insertafter) * [table.insertafter](table.insertafter.md)
* [table.insertflat](table.insertflat) * [table.insertflat](table.insertflat.md)
* [table.isempty](table.isempty) * [table.isempty](table.isempty.md)
* [table.join](table.join) * [table.join](table.join.md)
* [table.keys](table.keys) * [table.keys](table.keys.md)
* [table.merge](table.merge) * [table.merge](table.merge.md)
* [table.replace](table.replace) * [table.replace](table.replace.md)
* [table.tostring](table.tostring) * [table.tostring](table.tostring.md)
* [table.translate](table.translate) * [table.translate](table.translate.md)
### Term ### Term
* [term.getTextColor](term.getTextColor) * [term.getTextColor](term.getTextColor.md)
* [term.setTextColor](term.setTextColor) * [term.setTextColor](term.setTextColor.md)
* [term.pushColor](term.pushColor) * [term.pushColor](term.pushColor.md)
* [term.popColor](term.popColor) * [term.popColor](term.popColor.md)
### Zip ### Zip
* [zip.extract](zip.extract) * [zip.extract](zip.extract.md)

12
website/docs/Makefile-Projects.md
View File

@ -50,9 +50,9 @@ Makefile projects currently have a few shortcomings. Help fixing these issues, o
## See Also ## ## See Also ##
* [Custom Build Commands](custom-build-commands) * [Custom Build Commands](Custom-Build-Commands.md)
* [Custom Rules](custom-rules) * [Custom Rules](Custom-Rules.md)
* [buildcommands](buildcommands) * [buildcommands](buildcommands.md)
* [buildoutputs](buildoutputs) * [buildoutputs](buildoutputs.md)
* [cleancommands](cleancommands) * [cleancommands](cleancommands.md)
* [rebuildcommands](rebuildcommands) * [rebuildcommands](rebuildcommands.md)

22
website/docs/Migrating-From-4.x.md
View File

@ -4,21 +4,21 @@ title: Migrating from Premake 4.x
# Function name changes # Function name changes
The function [`workspace`](workspace) replaces `solution`. The latter still works, but the former is preferred. The function [`workspace`](workspace.md) replaces `solution`. The latter still works, but the former is preferred.
The function [`filter`](filter) replaces the `configuration` function for specifying the current configuration. It provides a more powerful interface for selecting which configuration is current, making it easy to specify flags for different actions, files, etc. The `configurations` setting at the workspace level still sets the available configurations. The function [`filter`](filter.md) replaces the `configuration` function for specifying the current configuration. It provides a more powerful interface for selecting which configuration is current, making it easy to specify flags for different actions, files, etc. The `configurations` setting at the workspace level still sets the available configurations.
# Flag changes # Flag changes
Many of the old [`flags`](flags) have become full-fledged functions. This should be a comprehensive list of such changes. Many of the old [`flags`](flags.md) have become full-fledged functions. This should be a comprehensive list of such changes.
| Old flags | New Function | | Old flags | New Function |
| --------- | ------------ | | --------- | ------------ |
| `EnableSSE`, `EnableSSE2` | [`vectorextensions`](vectorextensions) | | `EnableSSE`, `EnableSSE2` | [`vectorextensions`](vectorextensions.md) |
| `ExtraWarnings`, `NoWarnings` | [`warnings`](warnings) | | `ExtraWarnings`, `NoWarnings` | [`warnings`](warnings.md) |
| `FloatFast`, `FloatStrict` | [`floatingpoint`](floatingpoint) | | `FloatFast`, `FloatStrict` | [`floatingpoint`](floatingpoint.md) |
| `Managed`, `Unsafe` | [`clr`](clr) | | `Managed`, `Unsafe` | [`clr`](clr.md) |
| `NativeWChar` | [`nativewchar`](nativewchar) | | `NativeWChar` | [`nativewchar`](nativewchar.md) |
| `NoEditAndContinue` | [`editandcontinue`](editandcontinue) | | `NoEditAndContinue` | [`editandcontinue`](editAndContinue.md) |
| `NoRTTI` | [`rtti`](rtti) | | `NoRTTI` | [`rtti`](rtti.md) |
| `OptimizeSize`, `OptimizeSpeed` | [`optimize`](optimize) | | `OptimizeSize`, `OptimizeSpeed` | [`optimize`](optimize.md) |

12
website/docs/Overrides-and-Call-Arrays.md
View File

@ -23,7 +23,7 @@ Instead, we'd really like to implement this customization right in our project s
## Use the Source! ## Use the Source!
Before we can make this change, we first need to know what function in the Premake source code is emitting this particular markup. As described in the [Code Overview](code-overview), the Visual Studio exporter is currently located in the `src/actions/vstudio` folder in the Premake source tree (go ahead and find it, we'll wait!). Before we can make this change, we first need to know what function in the Premake source code is emitting this particular markup. As described in the [Code Overview](Code-Overview.md), the Visual Studio exporter is currently located in the `src/actions/vstudio` folder in the Premake source tree (go ahead and find it, we'll wait!).
We're looking for the code which generates the `.vcxproj` files, and browsing the file names brings us to `vs2010_vcxproj.lua`. Opening this file, we can then search for the `"<Project"` string, which we find in the `m.project()` function: We're looking for the code which generates the `.vcxproj` files, and browsing the file names brings us to `vs2010_vcxproj.lua`. Opening this file, we can then search for the `"<Project"` string, which we find in the `m.project()` function:
@ -40,7 +40,7 @@ We're looking for the code which generates the `.vcxproj` files, and browsing th
For the moment we don't really need to worry too much about how this code works because we aren't actually going to change it at all. Instead, we will *override* it with a new function that outputs our version comment, and then calls the original function to output the Project element, unmodified. For the moment we don't really need to worry too much about how this code works because we aren't actually going to change it at all. Instead, we will *override* it with a new function that outputs our version comment, and then calls the original function to output the Project element, unmodified.
Before we can do that, we need one more bit of information: what is `m`? [By convention](coding-conventions), `m` is a shortcut for the module's namespace (really just a Lua table) which we declare at the top of the file. Looking at the top of `vs2010_vcxproj.lua` we find: Before we can do that, we need one more bit of information: what is `m`? [By convention](Coding-Conventions.md), `m` is a shortcut for the module's namespace (really just a Lua table) which we declare at the top of the file. Looking at the top of `vs2010_vcxproj.lua` we find:
```lua ```lua
local p = premake local p = premake
@ -71,7 +71,7 @@ end)
This snippet replaces the original implementation of `m.project()` with my new (anonymous) function. From this point on, when someone calls `m.project()`, Premake will call my new function, passing it the original implementation as the first argument (`base`). If the function requires any other arguments (in this case, it receives the project being exported as `prj`) they appear after. This snippet replaces the original implementation of `m.project()` with my new (anonymous) function. From this point on, when someone calls `m.project()`, Premake will call my new function, passing it the original implementation as the first argument (`base`). If the function requires any other arguments (in this case, it receives the project being exported as `prj`) they appear after.
In our replacement function, we emit our comment header using `premake.w()`, which is short for "premake write", and [_PREMAKE_VERSION](_PREMAKE_VERSION), which is a global variable holding the version of the currently running Premake executable. In our replacement function, we emit our comment header using `premake.w()`, which is short for "premake write", and [_PREMAKE_VERSION](_PREMAKE_VERSION.md), which is a global variable holding the version of the currently running Premake executable.
After emitting the comment we call `base(prj)`, the original implementation of `m.project()`, to do the rest of the work for us. Easy! After emitting the comment we call `base(prj)`, the original implementation of `m.project()`, to do the rest of the work for us. Easy!
@ -96,7 +96,7 @@ The next time you generate a Visual Studio project from your scripts, the commen
## Introducing Call Arrays ## Introducing Call Arrays
Overrides are a great way to intercept an existing call to modify its arguments or return value or even replace it entirely. There is another, more self-contained way that we could have implemented our customization by leveraging [Premake's *call array* convention](coding-conventions). Overrides are a great way to intercept an existing call to modify its arguments or return value or even replace it entirely. There is another, more self-contained way that we could have implemented our customization by leveraging [Premake's *call array* convention](Coding-Conventions.md).
If you look at the top of `vs2010_vcxproj.lua`, you will see that `m.project()` is called via an array of function references: If you look at the top of `vs2010_vcxproj.lua`, you will see that `m.project()` is called via an array of function references:
@ -128,7 +128,7 @@ function m.generate(prj)
end end
``` ```
Premake calls `m.generate()` to export the project—we'll talk about how that happens later. `m.generate()` calls `p.callArray()` (remember [`p` is an alias for `premake`](coding-conventions)), which calls all of the functions in the list returned by `m.elements.project()`, passing the provided arguments (in this case `prj`) to each of them. This indirection allows project script authors like yourself an opportunity to modify that list of calls by adding, removing, or reordering the list. Premake calls `m.generate()` to export the project—we'll talk about how that happens later. `m.generate()` calls `p.callArray()` (remember [`p` is an alias for `premake`](Coding-Conventions.md)), which calls all of the functions in the list returned by `m.elements.project()`, passing the provided arguments (in this case `prj`) to each of them. This indirection allows project script authors like yourself an opportunity to modify that list of calls by adding, removing, or reordering the list.
Let's implement our version comment as an addition to this particular call array. To do so, we will override the `m.elements.project()` function (remember from the earlier example that `m` is short for `premake.vstudio.vc2010`). We'll call the original implementation to get the array of calls, and then add our own before returning it to `m.generate()`. Let's implement our version comment as an addition to this particular call array. To do so, we will override the `m.elements.project()` function (remember from the earlier example that `m` is short for `premake.vstudio.vc2010`). We'll call the original implementation to get the array of calls, and then add our own before returning it to `m.generate()`.
@ -146,4 +146,4 @@ end)
If you add that snippet to your project or system script, your new function will get called between `m.xmlDeclaration()` and `m.project()` and place our comment right where we'd like it. If you add that snippet to your project or system script, your new function will get called between `m.xmlDeclaration()` and `m.project()` and place our comment right where we'd like it.
*(Wondering [why the call array is in a function and not just a global table](why-do-call-arrays-need-functions)? Hint: because otherwise overrides wouldn't work.)* *(Wondering [why the call array is in a function and not just a global table](Why-Do-Call-Arrays-Need-Functions.md)? Hint: because otherwise overrides wouldn't work.)*

344
website/docs/Project-API.md
View File

@ -2,176 +2,176 @@
| API | Brief | | API | Brief |
|-----------------------------------------------------------|--------------------| |-----------------------------------------------------------|--------------------|
| [_ACTION](_ACTION) | The action that will be run | | [_ACTION](_ACTION.md) | The action that will be run |
| [_ARGS](_ARGS) | Array of action args | | [_ARGS](_ARGS.md) | Array of action args |
| [_MAIN_SCRIPT](_MAIN_SCRIPT) | | | [_MAIN_SCRIPT](_MAIN_SCRIPT.md) | |
| [_MAIN_SCRIPT_DIR](_MAIN_SCRIPT_DIR) | | | [_MAIN_SCRIPT_DIR](_MAIN_SCRIPT_DIR.md) | |
| [_OPTIONS](_OPTIONS) | | | [_OPTIONS](_OPTIONS.md) | |
| [_OS](_OS) | The currently targeted operating system | | [_OS](_OS.md) | The currently targeted operating system |
| [_PREMAKE_COMMAND](_PREMAKE_COMMAND) | | | [_PREMAKE_COMMAND](_PREMAKE_COMMAND.md) | |
| [_PREMAKE_DIR](_PREMAKE_DIR) | | | [_PREMAKE_DIR](_PREMAKE_DIR.md) | |
| [_PREMAKE_VERSION](_PREMAKE_VERSION) | The version of the currently executing instance of Premake | | [_PREMAKE_VERSION](_PREMAKE_VERSION.md) | The version of the currently executing instance of Premake |
| [_WORKING_DIR](_WORKING_DIR) | | | [_WORKING_DIR](_WORKING_DIR.md) | |
| [architecture](architecture) | | | [architecture](architecture.md) | |
| [atl](atl) | Use Microsoft's Active Template Library | | [atl](atl.md) | Use Microsoft's Active Template Library |
| [basedir](basedir) | | | [basedir](basedir.md) | |
| [bindirs](bindirs) | | | [bindirs](bindirs.md) | |
| [buildaction](buildaction) | | | [buildaction](buildaction.md) | |
| [buildcommands](buildcommands) | | | [buildcommands](buildcommands.md) | |
| [buildcustomizations](buildcustomizations) | | | [buildcustomizations](buildcustomizations.md) | |
| [builddependencies](builddependencies) | | | [builddependencies](builddependencies.md) | |
| [buildinputs](buildinputs) | | | [buildinputs](buildinputs.md) | |
| [buildlog](buildlog) | | | [buildlog](buildlog.md) | |
| [buildmessage](buildmessage) | | | [buildmessage](buildmessage.md) | |
| [buildoptions](buildoptions) | Additional build options (passed directly to compiler) | | [buildoptions](buildoptions.md) | Additional build options (passed directly to compiler) |
| [buildoutputs](buildoutputs) | | | [buildoutputs](buildoutputs.md) | |
| [buildrule](buildrule) | | | [buildrule](buildrule.md) | |
| [callingconvention](callingconvention) | Sets the function calling convention | | [callingconvention](callingconvention.md) | Sets the function calling convention |
| [cdialect](cdialect) | | | [cdialect](cdialect.md) | |
| [characterset](characterset) | Set the character encoding | | [characterset](characterset.md) | Set the character encoding |
| [cleancommands](cleancommands) | | | [cleancommands](cleancommands.md) | |
| [cleanextensions](cleanextensions) | | | [cleanextensions](cleanextensions.md) | |
| [clr](clr) | Use Microsoft's Common Language Runtime | | [clr](clr.md) | Use Microsoft's Common Language Runtime |
| [compileas](compileas) | | | [compileas](compileas.md) | |
| [compilebuildoutputs](compilebuildoutputs) | | | [compilebuildoutputs](compilebuildoutputs.md) | |
| [configfile](configfile) | | | [configfile](configfile.md) | |
| [configmap](configmap) | | | [configmap](configmap.md) | |
| [configuration](configuration) | | | [configuration](configuration.md) | |
| [configurations](configurations) | | | [configurations](configurations.md) | |
| [copylocal](copylocal) | | | [copylocal](copylocal.md) | |
| [cppdialect](cppdialect) | | | [cppdialect](cppdialect.md) | |
| [customtoolnamespace](customtoolnamespace) | | | [customtoolnamespace](customtoolnamespace.md) | |
| [debugargs](debugargs) | | | [debugargs](debugargs.md) | |
| [debugcommand](debugcommand) | | | [debugcommand](debugcommand.md) | |
| [debugconnectcommands](debugconnectcommands) | Debugger commands to execute on remote target connection | | [debugconnectcommands](debugconnectcommands.md) | Debugger commands to execute on remote target connection |
| [debugconstants](debugconstants) | | | [debugconstants](debugconstants.md) | |
| [debugdir](debugdir) | Working directory for debug session | | [debugdir](debugdir.md) | Working directory for debug session |
| [debugenvs](debugenvs) | Env vars for debug session | | [debugenvs](debugenvs.md) | Env vars for debug session |
| [debugextendedprotocol](debugextendedprotocol) | Use gdb 'extended' protocol; maintain a persistent connection | | [debugextendedprotocol](debugextendedprotocol.md) | Use gdb 'extended' protocol; maintain a persistent connection |
| [debugformat](debugformat) | Format for embedded debug information | | [debugformat](debugformat.md) | Format for embedded debug information |
| [debugger](debugger) | | | [debugger](debugger.md) | |
| [debuggertype](debuggertype) | | | [debuggertype](debuggertype.md) | |
| [debuglevel](debuglevel) | | | [debuglevel](debuglevel.md) | |
| [debugpathmap](debugpathmap) | | | [debugpathmap](debugpathmap.md) | |
| [debugport](debugport) | Port to use for remote debugging | | [debugport](debugport.md) | Port to use for remote debugging |
| [debugremotehost](debugremotehost) | Target for remote debugging | | [debugremotehost](debugremotehost.md) | Target for remote debugging |
| [debugsearchpaths](debugsearchpaths) | Search paths for source code while debugging | | [debugsearchpaths](debugsearchpaths.md) | Search paths for source code while debugging |
| [debugstartupcommands](debugstartupcommands) | Debugger commands to execute on debugger startup | | [debugstartupcommands](debugstartupcommands.md) | Debugger commands to execute on debugger startup |
| [debugtoolargs](debugtoolargs) | | | [debugtoolargs](debugtoolargs.md) | |
| [debugtoolcommand](debugtoolcommand) | | | [debugtoolcommand](debugtoolcommand.md) | |
| [defaultplatform](defaultplatform) | | | [defaultplatform](defaultplatform.md) | |
| [defaultplatform](defaultplatform) | | | [defaultplatform](defaultplatform.md) | |
| [defines](defines) | | | [defines](defines.md) | |
| [dependson](dependson) | | | [dependson](dependson.md) | |
| [deploymentoptions](deploymentoptions) | | | [deploymentoptions](deploymentoptions.md) | |
| [disablewarnings](disablewarnings) | | | [disablewarnings](disablewarnings.md) | |
| [display](display) | | | [display](display.md) | |
| [display](display) | | | [display](display.md) | |
| [docdir](docdir) | | | [docdir](docdir.md) | |
| [docname](docname) | | | [docname](docname.md) | |
| [editandcontinue](editandcontinue) | | | [editandcontinue](editAndContinue.md) | |
| [editorintegration](editorintegration) | Enable or disable IDE integration | | [editorintegration](editorintegration.md) | Enable or disable IDE integration |
| [enablewarnings](enablewarnings) | | | [enablewarnings](enablewarnings.md) | |
| [endian](endian) | | | [endian](endian.md) | |
| [entrypoint](entrypoint) | Specify the program entry point function | | [entrypoint](entrypoint.md) | Specify the program entry point function |
| [exceptionhandling](exceptionhandling) | Enable or disable exception handling | | [exceptionhandling](exceptionhandling.md) | Enable or disable exception handling |
| [external](external) | | | [external](external.md) | |
| [externalRule](externalRule) | | | [externalrule](externalrule.md) | |
| [fatalwarnings](fatalwarnings) | | | [fatalwarnings](fatalwarnings.md) | |
| [fileextension](fileextension) | | | [fileextension](fileextension.md) | |
| [filename](filename) | | | [filename](filename.md) | |
| [files](files) | | | [files](files.md) | |
| [filter](filter) | | | [filter](filter.md) | |
| [flags](flags) | | | [flags](flags.md) | |
| [floatingpoint](floatingpoint) | | | [floatingpoint](floatingpoint.md) | |
| [floatingpointexceptions](floatingpointexceptions) | | | [floatingpointexceptions](floatingpointexceptions.md) | |
| [forceincludes](forceincludes) | | | [forceincludes](forceincludes.md) | |
| [forceusings](forceusings) | | | [forceusings](forceusings.md) | |
| [fpu](fpu) | | | [fpu](fpu.md) | |
| [framework](framework) | | | [framework](framework.md) | |
| [functionlevellinking](functionlevellinking) | | | [functionlevellinking](functionlevellinking.md) | |
| [gccprefix](gccprefix) | | | [gccprefix](gccprefix.md) | |
| [group](group) | | | [group](group.md) | |
| [headerdir](headerdir) | | | [headerdir](headerdir.md) | |
| [headername](headername) | | | [headername](headername.md) | |
| [icon](icon) | | | [icon](icon.md) | |
| [ignoredefaultlibraries](ignoredefaultlibraries) | Specify a list of default libraries to ignore | | [ignoredefaultlibraries](ignoredefaultlibraries.md) | Specify a list of default libraries to ignore |
| [imageoptions](imageoptions) | | | [imageoptions](imageoptions.md) | |
| [imagepath](imagepath) | | | [imagepath](imagepath.md) | |
| [implibdir](implibdir) | | | [implibdir](implibdir.md) | |
| [implibextension](implibextension) | | | [implibextension](implibextension.md) | |
| [implibname](implibname) | | | [implibname](implibname.md) | |
| [implibprefix](implibprefix) | | | [implibprefix](implibprefix.md) | |
| [implibsuffix](implibsuffix) | | | [implibsuffix](implibsuffix.md) | |
| [include](include) | | | [include](include.md) | |
| [includedirs](includedirs) | | | [includedirs](includedirs.md) | |
| [includeexternal](includeexternal) | | | [includeexternal](includeexternal.md) | |
| [inlining](inlining) | Tells the compiler when it should inline functions | | [inlining](inlining.md) | Tells the compiler when it should inline functions |
| [intrinsics](intrinsics) | | | [intrinsics](intrinsics.md) | |
| [kind](kind) | | | [kind](kind.md) | |
| [language](language) | | | [language](language.md) | |
| [largeaddressaware](largeaddressaware) | | | [largeaddressaware](largeaddressaware.md) | |
| [libdirs](libdirs) | | | [libdirs](libdirs.md) | |
| [linkbuildoutputs](linkbuildoutputs) | | | [linkbuildoutputs](linkbuildoutputs.md) | |
| [linkgroups](linkgroups) | Turn on/off linkgroups for gcc/clang | | [linkgroups](linkgroups.md) | Turn on/off linkgroups for gcc/clang |
| [linkoptions](linkoptions) | Additional linker options (passed directly to linker) | | [linkoptions](linkoptions.md) | Additional linker options (passed directly to linker) |
| [links](links) | | | [links](links.md) | |
| [locale](locale) | | | [locale](locale.md) | |
| [location](location) | Specifies the directory for the generated workspace/project file | | [location](location.md) | Specifies the directory for the generated workspace/project file |
| [makesettings](makesettings) | | | [makesettings](makesettings.md) | |
| [namespace](namespace) | | | [namespace](namespace.md) | |
| [nativewchar](nativewchar) | | | [nativewchar](nativewchar.md) | |
| [nuget](nuget) | | | [nuget](nuget.md) | |
| [nugetsource](nugetsource) | | | [nugetsource](nugetsource.md) | |
| [objdir](objdir) | Output dir for object/intermediate files | | [objdir](objdir.md) | Output dir for object/intermediate files |
| [optimize](optimize) | Optimization level | | [optimize](optimize.md) | Optimization level |
| [pchheader](pchheader) | Precompiled header file | | [pchheader](pchheader.md) | Precompiled header file |
| [pchsource](pchsource) | Precompiled header source file (which should build the PCH) | | [pchsource](pchsource.md) | Precompiled header source file (which should build the PCH) |
| [pic](pic) | Position independent code | | [pic](pic.md) | Position independent code |
| [platforms](platforms) | | | [platforms](platforms.md) | |
| [postbuildcommands](postbuildcommands) | | | [postbuildcommands](postbuildcommands.md) | |
| [postbuildmessage](postbuildmessage) | | | [postbuildmessage](postbuildmessage.md) | |
| [prebuildcommands](prebuildcommands) | | | [prebuildcommands](prebuildcommands.md) | |
| [prebuildmessage](prebuildmessage) | | | [prebuildmessage](prebuildmessage.md) | |
| [preferredtoolarchitecture](preferredtoolarchitecture) | | | [preferredtoolarchitecture](preferredtoolarchitecture.md) | |
| [prelinkcommands](prelinkcommands) | | | [prelinkcommands](prelinkcommands.md) | |
| [prelinkmessage](prelinkmessage) | | | [prelinkmessage](prelinkmessage.md) | |
| [project](project) | | | [project](project.md) | |
| [propertydefinition](propertydefinition) | | | [propertydefinition](propertydefinition.md) | |
| [rebuildcommands](rebuildcommands) | | | [rebuildcommands](rebuildcommands.md) | |
| [resdefines](resdefines) | | | [resdefines](resdefines.md) | |
| [resincludedirs](resincludedirs) | | | [resincludedirs](resincludedirs.md) | |
| [resoptions](resoptions) | | | [resoptions](resoptions.md) | |
| [resourcegenerator](resourcegenerator) | | | [resourcegenerator](resourcegenerator.md) | |
| [rtti](rtti) | Enable or disable runtime type information | | [rtti](rtti.md) | Enable or disable runtime type information |
| [rule](rule) | | | [rule](rule.md) | |
| [rules](rules) | | | [rules](rules.md) | |
| [runtime](runtime) | | | [runtime](runtime.md) | |
| [sharedlibtype](sharedlibtype) | | | [sharedlibtype](sharedlibtype.md) | |
| [startproject](startproject) | | | [startproject](startproject.md) | |
| [strictaliasing](strictaliasing) | | | [strictaliasing](strictaliasing.md) | |
| [stringpooling](stringpooling) | | | [stringpooling](stringpooling.md) | |
| [symbols](symbols) | Turn symbol generation on/off | | [symbols](symbols.md) | Turn symbol generation on/off |
| [symbolspath](symbolspath) | Allows you to specify the target location of the symbols | | [symbolspath](symbolspath.md) | Allows you to specify the target location of the symbols |
| [sysincludedirs](sysincludedirs) | | | [sysincludedirs](sysincludedirs.md) | |
| [syslibdirs](syslibdirs) | | | [syslibdirs](syslibdirs.md) | |
| [system](system) | | | [system](system.md) | |
| [tags](tags) | | | [tags](tags.md) | |
| [targetdir](targetdir) | | | [targetdir](targetdir.md) | |
| [targetextension](targetextension) | | | [targetextension](targetextension.md) | |
| [targetname](targetname) | | | [targetname](targetname.md) | |
| [targetprefix](targetprefix) | | | [targetprefix](targetprefix.md) | |
| [targetsuffix](targetsuffix) | | | [targetsuffix](targetsuffix.md) | |
| [toolset](toolset) | | | [toolset](toolset.md) | |
| [undefines](undefines) | | | [undefines](undefines.md) | |
| [usingdirs](usingdirs) | | | [usingdirs](usingdirs.md) | |
| [uuid](uuid) | Set project GUID (for VS projects/workspaces) | | [uuid](uuid.md) | Set project GUID (for VS projects/workspaces) |
| [vectorextensions](vectorextensions) | Enable hardware vector extensions | | [vectorextensions](vectorextensions.md) | Enable hardware vector extensions |
| [versionconstants](versionconstants) | | | [versionconstants](versionconstants.md) | |
| [versionlevel](versionlevel) | | | [versionlevel](versionlevel.md) | |
| [vpaths](vpaths) | | | [vpaths](vpaths.md) | |
| [warnings](warnings) | | | [warnings](warnings.md) | |
| [workspace](workspace) | | | [workspace](workspace.md) | |
### Builtin Extension APIs ### ### Builtin Extension APIs ###
@ -190,5 +190,5 @@ The following API reference is for use with various built-in extensions.
| Xcode APIs | Brief | | Xcode APIs | Brief |
|------------------------------------------------|--------------------| |------------------------------------------------|--------------------|
| [xcodebuildsettings](xcodebuildsettings) | | | [xcodebuildsettings](xcodebuildsettings.md) | |
| [xcodebuildresources](xcodebuildresources) | | | [xcodebuildresources](xcodebuildresources.md) | |

2
website/docs/Removing-Values.md
View File

@ -2,7 +2,7 @@
title: Removing Values title: Removing Values
--- ---
The remove...() set of functions remove one or more values from a list of configuration values. Every configuration list in the Premake API has a corresponding remove function: [flags()](flags) has removeflags(), [defines()](defines) has removedefines(), and so on. The remove...() set of functions remove one or more values from a list of configuration values. Every configuration list in the Premake API has a corresponding remove function: [flags()](flags.md) has removeflags(), [defines()](defines.md) has removedefines(), and so on.
```lua ```lua
remove... { "values_to_remove" } remove... { "values_to_remove" }

2
website/docs/Scopes-and-Inheritance.md
View File

@ -21,7 +21,7 @@ project "MyProject"
defines { "PROJECT" } defines { "PROJECT" }
``` ```
Sometimes it can be helpful to go back and add values to a previously declared scope. You can do this the same way you declared it in the first place: by calling [`workspace`](workspace) or [`project`](project), using the same name. Sometimes it can be helpful to go back and add values to a previously declared scope. You can do this the same way you declared it in the first place: by calling [`workspace`](workspace.md) or [`project`](project.md), using the same name.
```lua ```lua
-- declare my workspace -- declare my workspace

10
website/docs/Starting-Your-New-Action.md
View File

@ -1,6 +1,6 @@
When developing something as complex as a new exporter, it is a good idea to build it as a [module](developing-modules). Doing so helps organize the code, provides [a way to automate testing](adding-unit-tests), and makes it easy to [share your code with others](sharing-your-module). When developing something as complex as a new exporter, it is a good idea to build it as a [module](Developing-Modules.md). Doing so helps organize the code, provides [a way to automate testing](Adding-Unit-Tests.md), and makes it easy to [share your code with others](Sharing-Your-Module.md).
So let's start by setting up a module containing a really simple action. Create a new file named `lua.lua` and place it into a folder named `lua`. Place this `lua` folder [somewhere Premake can find it](locating-scripts). So let's start by setting up a module containing a really simple action. Create a new file named `lua.lua` and place it into a folder named `lua`. Place this `lua` folder [somewhere Premake can find it](Locating-Scripts.md).
Copy this simple skeleton action definition into your `lua.lua`: Copy this simple skeleton action definition into your `lua.lua`:
@ -67,7 +67,7 @@ Lua generation complete
Done. Done.
``` ```
(Quick side note: if you'd like to make this or any third-party module available without having to add a `require()` to every project script, just put that `require("lua")` call in your [system script](system-scripts) instead.) (Quick side note: if you'd like to make this or any third-party module available without having to add a `require()` to every project script, just put that `require("lua")` call in your [system script](System-Scripts.md) instead.)
### Explain. ### ### Explain. ###
@ -125,9 +125,9 @@ All of these callbacks are optional; you only need to include the ones you are a
`onStart` is called first to indicate that processing has begun. `onStart` is called first to indicate that processing has begun.
`onWorkspace` is called once for every workspace that was declared, via the [`workspace`](workspace) function, in the user's project script. `onWorkspace` is called once for every workspace that was declared, via the [`workspace`](workspace.md) function, in the user's project script.
`onProject` is called once for every project that was declared, via the [`project`](project) function, in the user's project script. `onProject` is called once for every project that was declared, via the [`project`](project.md) function, in the user's project script.
`execute` is called after all projects and workspaces have been processed. This is a good place to put more general code that doesn't require a workspace or project as input, and should only run once. `execute` is called after all projects and workspaces have been processed. This is a good place to put more general code that doesn't require a workspace or project as input, and should only run once.

4
website/docs/System-Scripts.md
View File

@ -2,9 +2,9 @@
title: System Scripts title: System Scripts
--- ---
Immediately after startup, Premake will look for and run a *system script*. It does this before handling actions and other arguments, and before loading the project script, if present. The system script is a great place for adding [modules](using-modules) and other support code that you wish to include in all of your Premake-enabled projects. Immediately after startup, Premake will look for and run a *system script*. It does this before handling actions and other arguments, and before loading the project script, if present. The system script is a great place for adding [modules](Using-Modules.md) and other support code that you wish to include in all of your Premake-enabled projects.
By default, this file is named `premake-system.lua` or `premake5-system.lua`, and should be located [somewhere on Premake's search paths](locating-scripts). By default, this file is named `premake-system.lua` or `premake5-system.lua`, and should be located [somewhere on Premake's search paths](Locating-Scripts.md).
You can override the default system script file name and location using the `--systemscript` command line argument. You can override the default system script file name and location using the `--systemscript` command line argument.

16
website/docs/Tokens.md
View File

@ -83,14 +83,14 @@ postbuildcommands {
You can use command tokens anywhere you specify a command line, including: You can use command tokens anywhere you specify a command line, including:
* [buildcommands](buildcommands) * [buildcommands](buildcommands.md)
* [cleancommands](cleancommands) * [cleancommands](cleancommands.md)
* [os.execute](os.execute) * [os.execute](os.execute.md)
* [os.executef](os.executef) * [os.executef](os.executef.md)
* [postbuildcommands](postbuildcommands) * [postbuildcommands](postbuildcommands.md)
* [prebuildcommands](prebuildcommands) * [prebuildcommands](prebuildcommands.md)
* [prelinkcommands](prelinkcommands) * [prelinkcommands](prelinkcommands.md)
* [rebuildcommands](rebuildcommands) * [rebuildcommands](rebuildcommands.md)
Command tokens are replaced with an appropriate command for the target platform. For Windows, path separators in the commmand arguments are converted to backslashes. Command tokens are replaced with an appropriate command for the target platform. For Windows, path separators in the commmand arguments are converted to backslashes.

18
website/docs/Topics.md
View File

@ -2,12 +2,12 @@
title: More Authoring Topics title: More Authoring Topics
--- ---
* [Locating Scripts](locating-scripts) * [Locating Scripts](Locating-Scripts.md)
* [System Scripts](system-scripts) * [System Scripts](System-Scripts.md)
* [Removing Values](removing-values) * [Removing Values](Removing-Values.md)
* [Tokens](tokens) * [Tokens](Tokens.md)
* [Precompiled Headers](precompiled-headers) * [Precompiled Headers](Precompiled-Headers.md)
* [Custom Build Commands](custom-build-commands) * [Custom Build Commands](Custom-Build-Commands.md)
* [Custom Rules](custom-rules) * [Custom Rules](Custom-Rules.md)
* [Makefile Projects](makefile-projects) * [Makefile Projects](Makefile-Projects.md)
* [Debugging Scripts](debugging-scripts) * [Debugging Scripts](Debugging-Scripts.md)

12
website/docs/Using-Modules.md
View File

@ -4,13 +4,13 @@ title: Using Modules
Premake can be extended through the use of third-party modules. Modules can add support for new toolsets, languages, and frameworks as well as entirely new features. See [Modules](/community/modules) for some examples of what the community has already created. Premake can be extended through the use of third-party modules. Modules can add support for new toolsets, languages, and frameworks as well as entirely new features. See [Modules](/community/modules) for some examples of what the community has already created.
To use a module, download or clone the module's repository to [one of Premake's search paths](locating-scripts), making sure that the destination folder has the same name as the module's main script, e.g. **qt/qt.lua**. To use a module, download or clone the module's repository to [one of Premake's search paths](Locating-Scripts.md), making sure that the destination folder has the same name as the module's main script, e.g. **qt/qt.lua**.
```` ````
$ git clone https://github.com/dcourtois/premake-qt qt $ git clone https://github.com/dcourtois/premake-qt qt
```` ````
Then simply call `require()` from your project or [system script](system-scripts) to include it. Then simply call `require()` from your project or [system script](System-Scripts.md) to include it.
```lua ```lua
require "qt" require "qt"
@ -26,21 +26,21 @@ require "build/qt"
### System Modules ### ### System Modules ###
You may also put your modules anywhere on [Premake's search paths](locating-scripts), for example in **~/.premake**. In this case no path information is needed, and you can simply call: You may also put your modules anywhere on [Premake's search paths](Locating-Scripts.md), for example in **~/.premake**. In this case no path information is needed, and you can simply call:
```lua ```lua
require "qt" require "qt"
``` ```
If you wish to make a module always available to *all* of your projects, you may place the call to `require()` in your [system script](system-scripts). In that case, the module will be automatically loaded each time Premake runs, and all of its features will be available. If you wish to make a module always available to *all* of your projects, you may place the call to `require()` in your [system script](System-Scripts.md). In that case, the module will be automatically loaded each time Premake runs, and all of its features will be available.
## Version Requirements ## Version Requirements
To ensure compatibility with your project script, it can sometimes be helpful to require a minimum version or range of versions for your module dependencies. Premake includes [a modified version Lua's `require()` function](require) which accepts a version test as its second argument. To ensure compatibility with your project script, it can sometimes be helpful to require a minimum version or range of versions for your module dependencies. Premake includes [a modified version Lua's `require()` function](require.md) which accepts a version test as its second argument.
```lua ```lua
require("qt", ">=1.1") require("qt", ">=1.1")
``` ```
See [the `require()` documentation](require) for more information and examples. See [the `require()` documentation](require.md) for more information and examples.

8
website/docs/Using-Premake.md
View File

@ -2,9 +2,9 @@
title: Using Premake title: Using Premake
--- ---
*New to Premake? You might want to start with [What is Premake?](what-is-premake)* *New to Premake? You might want to start with [What is Premake?](What-Is-Premake.md)*
If you haven't already, you can [download Premake here](/download), or [build it from source](building-premake). Premake is a small command line executable, delivered as a single file. Just unpack the download and place the executable on your system search path, or anywhere else convenient. If you haven't already, you can [download Premake here](/download), or [build it from source](Building-Premake.md). Premake is a small command line executable, delivered as a single file. Just unpack the download and place the executable on your system search path, or anywhere else convenient.
## Using Premake to Generate Project Files ## Using Premake to Generate Project Files
@ -31,7 +31,7 @@ Premake defines the following list of actions out of the box; projects may also
| xcode4 | XCode projects | | xcode4 | XCode projects |
| codelite | CodeLite projects | | codelite | CodeLite projects |
(Premake4 supported some additional actions that haven't yet been ported to this new version; see the [Available Feature Matrix](feature-matrix) for the whole list.) (Premake4 supported some additional actions that haven't yet been ported to this new version; see the [Available Feature Matrix](Feature-Matrix.md) for the whole list.)
To generate Visual Studio 2013 project files, use the command: To generate Visual Studio 2013 project files, use the command:
@ -68,7 +68,7 @@ make clean # to clean the default target
make config=release clean # to clean a different target make config=release clean # to clean a different target
``` ```
Premake generated makefiles do not (currently) support a `make install` step. Instead, project owners are encouraged to [add an install action](command-line-arguments) to their Premake scripts, which has the advantage of working with any toolset on any platform. You can check for the existence of an install action by viewing the help (run `premake5 --help` in the project directory). Premake generated makefiles do not (currently) support a `make install` step. Instead, project owners are encouraged to [add an install action](Command-Line-Arguments.md) to their Premake scripts, which has the advantage of working with any toolset on any platform. You can check for the existence of an install action by viewing the help (run `premake5 --help` in the project directory).
[1]: http://www.cygwin.com/ [1]: http://www.cygwin.com/
[2]: http://www.mingw.org/ [2]: http://www.mingw.org/

238
website/docs/Whats-New-in-5.0.md
View File

@ -16,140 +16,140 @@ title: What's New in 5.0
## Major Features ## ## Major Features ##
* [Custom Rules](custom-rules) (still experimental) * [Custom Rules](Custom-Rules.md) (still experimental)
* [Makefile Projects](makefile-projects) * [Makefile Projects](Makefile-Projects.md)
* [Modules](developing-modules) * [Modules](Developing-Modules.md)
* [Per-Configuration File Lists](files) * [Per-Configuration File Lists](files.md)
* [Per-File Configurations](configuration) * [Per-File Configurations](configuration.md)
* [Per-Project Configurations](configurations-and-platforms) * [Per-Project Configurations](Configurations-and-Platforms.md)
* [Platforms](configurations-and-platforms) * [Platforms](Configurations-and-Platforms.md)
* [Removes](removing-values) * [Removes](Removing-Values.md)
* [System Scripts](system-scripts) * [System Scripts](System-Scripts.md)
* [Tokens](tokens) * [Tokens](Tokens.md)
* [HTTP support](http.download) * [HTTP support](http.download.md)
## New or Modified Globals ## ## New or Modified Globals ##
* [_MAIN_SCRIPT](_main_script) * [_MAIN_SCRIPT](_MAIN_SCRIPT.md)
* [_MAIN_SCRIPT_DIR](_main_script_dir) * [_MAIN_SCRIPT_DIR](_MAIN_SCRIPT_DIR.md)
* [_PREMAKE_DIR](_premake_dir) * [_PREMAKE_DIR](_PREMAKE_DIR.md)
## New or Modified API calls ## ## New or Modified API calls ##
* [architecture](architecture) (new) * [architecture](architecture.md) (new)
* [buildaction](buildaction) (new values) * [buildaction](buildaction.md) (new values)
* [buildcommands](buildcommands) (new) * [buildcommands](buildcommands.md) (new)
* [builddependencies](builddependencies) (new) * [builddependencies](builddependencies.md) (new)
* [buildlog](buildlog) (new) * [buildlog](buildlog.md) (new)
* [buildmessage](buildmessage) (new) * [buildmessage](buildmessage.md) (new)
* [buildoutputs](buildoutputs) (new) * [buildoutputs](buildoutputs.md) (new)
* [characterset](characterset) (new) * [characterset](characterset.md) (new)
* [callingconvention](callingconvention) (new) * [callingconvention](callingconvention.md) (new)
* [cleancommands](cleancommands) (new) * [cleancommands](cleancommands.md) (new)
* [cleanextensions](cleanextensions) (new) * [cleanextensions](cleanextensions.md) (new)
* [clr](clr) (new, replaces flags `Managed` and `Unsafe`) * [clr](clr.md) (new, replaces flags `Managed` and `Unsafe`)
* [configfile](configfile) (new) * [configfile](configfile.md) (new)
* [configmap](configmap) (new) * [configmap](configmap.md) (new)
* [configuration](configuration) (retired) * [configuration](configuration.md) (retired)
* [configurations](configurations) (modified) * [configurations](configurations.md) (modified)
* [copylocal](copylocal) (new) * [copylocal](copylocal.md) (new)
* [debugcommand](debugcommand) (new) * [debugcommand](debugcommand.md) (new)
* [debugconnectcommands](debugconnectcommands) (new) * [debugconnectcommands](debugconnectcommands.md) (new)
* [debugextendedprotocol](debugextendedprotocol) (new) * [debugextendedprotocol](debugextendedprotocol.md) (new)
* [debugport](debugport) (new) * [debugport](debugport.md) (new)
* [debugremotehost](debugremotehost) (new) * [debugremotehost](debugremotehost.md) (new)
* [debugsearchpaths](debugsearchpaths) (new) * [debugsearchpaths](debugsearchpaths.md) (new)
* [debugstartupcommands](debugstartupcommands) (new) * [debugstartupcommands](debugstartupcommands.md) (new)
* [dependson](dependson) (new) * [dependson](dependson.md) (new)
* [disablewarnings](disablewarnings) (new) * [disablewarnings](disablewarnings.md) (new)
* [dotnetframework](dotnetframework) (new) * [dotnetframework](dotnetframework.md) (new)
* [editandcontinue](editandcontinue) (new, replaces flag `NoEditAndContinue`) * [editandcontinue](editAndContinue.md) (new, replaces flag `NoEditAndContinue`)
* [editorintegration](editorintegration) (new) * [editorintegration](editorintegration.md) (new)
* [enablewarnings](enablewarnings) (new) * [enablewarnings](enablewarnings.md) (new)
* [endian](endian) (new) * [endian](endian.md) (new)
* [entrypoint](entrypoint) (new) * [entrypoint](entrypoint.md) (new)
* [exceptionhandling](exceptionhandling) (new) * [exceptionhandling](exceptionhandling.md) (new)
* [external](external) (new) * [external](external.md) (new)
* [externalproject](externalproject) (new) * [externalproject](externalproject.md) (new)
* [externalrule](externalrule) (new) * [externalrule](externalrule.md) (new)
* [fatalwarnings](fatalwarnings) (new) * [fatalwarnings](fatalwarnings.md) (new)
* [fileextension](fileextension) (new) * [fileextension](fileextension.md) (new)
* [filename](filename) (new) * [filename](filename.md) (new)
* [filter](filter) (new) * [filter](filter.md) (new)
* [flags](flags) (new values) * [flags](flags.md) (new values)
* [floatingpoint](floatingpoint) (new, replaces flags `FloatFast` and `FloatStrict`) * [floatingpoint](floatingpoint.md) (new, replaces flags `FloatFast` and `FloatStrict`)
* [forceincludes](forceincludes) (new) * [forceincludes](forceincludes.md) (new)
* [forceusings](forceusings) (new) * [forceusings](forceusings.md) (new)
* [fpu](fpu) (new) * [fpu](fpu.md) (new)
* [gccprefix](gccprefix) (new) * [gccprefix](gccprefix.md) (new)
* [group](group) (new) * [group](group.md) (new)
* [icon](icon) (new) * [icon](icon.md) (new)
* [inlining](inlining) (new) * [inlining](inlining.md) (new)
* [kind](kind) (Makefile, None) * [kind](kind.md) (Makefile, None)
* [linkbuildoutputs](linkbuildoutputs) (new) * [linkbuildoutputs](linkbuildoutputs.md) (new)
* [links](links) * [links](links.md)
* [language](language) (new values) * [language](language.md) (new values)
* [locale](locale) (new) * [locale](locale.md) (new)
* [makesettings](makesettings) (new) * [makesettings](makesettings.md) (new)
* [namespace](namespace) (new) * [namespace](namespace.md) (new)
* [nativewchar](nativewchar) (new, replaces flag `NativeWChar`) * [nativewchar](nativewchar.md) (new, replaces flag `NativeWChar`)
* [newaction](newaction) (modified) * [newaction](newaction.md) (modified)
* [nuget](nuget) (new) * [nuget](nuget.md) (new)
* [objdir](objdir) (modified) * [objdir](objdir.md) (modified)
* [optimize](optimize) (new, replaces flags `OptimizeSize` and `OptimizeSpeed`) * [optimize](optimize.md) (new, replaces flags `OptimizeSize` and `OptimizeSpeed`)
* [pic](pic) (new) * [pic](pic.md) (new)
* [platforms](platforms) (modified) * [platforms](platforms.md) (modified)
* [postbuildmessage](postbuildmessage) (new) * [postbuildmessage](postbuildmessage.md) (new)
* [prebuildmessage](prebuildmessage) (new) * [prebuildmessage](prebuildmessage.md) (new)
* [prelinkmessage](prelinkmessage) (new) * [prelinkmessage](prelinkmessage.md) (new)
* [project](project) (modified) * [project](project.md) (modified)
* [propertydefinition](propertydefinition) (new) * [propertydefinition](propertydefinition.md) (new)
* [rebuildcommands](rebuildcommands) (new) * [rebuildcommands](rebuildcommands.md) (new)
* [rtti](rtti) (new, replaces flag `NoRTTI`) * [rtti](rtti.md) (new, replaces flag `NoRTTI`)
* [rule](rule) (new) * [rule](rule.md) (new)
* [rules](rules) (new) * [rules](rules.md) (new)
* [runtime](runtime) (new) * [runtime](runtime.md) (new)
* [solution](workspace) (name changed) * [solution](workspace.md) (name changed)
* [startproject](startproject) (new) * [startproject](startproject.md) (new)
* [strictaliasing](strictaliasing) (new) * [strictaliasing](strictaliasing.md) (new)
* [sysincludedirs](sysincludedirs) (new) * [sysincludedirs](sysincludedirs.md) (new)
* [syslibdirs](syslibdirs) (new) * [syslibdirs](syslibdirs.md) (new)
* [system](system) (new) * [system](system.md) (new)
* [toolset](toolset) (new) * [toolset](toolset.md) (new)
* [undefines](undefines) (new) * [undefines](undefines.md) (new)
* [vectorextensions](vectorextensions) (new, replaces flags `EnableSSE` and `EnableSSE2`) * [vectorextensions](vectorextensions.md) (new, replaces flags `EnableSSE` and `EnableSSE2`)
* [warnings](warnings) (new, replaces flags `ExtraWarnings` and `NoWarnings`) * [warnings](warnings.md) (new, replaces flags `ExtraWarnings` and `NoWarnings`)
* [workspace](workspace) (new) * [workspace](workspace.md) (new)
## New or Modified Lua library calls ## ## New or Modified Lua library calls ##
* [includeexternal](includeexternal) (new) * [includeexternal](includeexternal.md) (new)
* [require](require) (modified) * [require](require.md) (modified)
* [debug.prompt](debug.prompt) (new) * [debug.prompt](debug.prompt.md) (new)
* [http.download](http.download) (new) * [http.download](http.download.md) (new)
* [http.get](http.get) (new) * [http.get](http.get.md) (new)
* [os.chmod](os.chmod) (new) * [os.chmod](os.chmod.md) (new)
* [os.islink](os.islink) (new) * [os.islink](os.islink.md) (new)
* [os.realpath](os.realpath) (new) * [os.realpath](os.realpath.md) (new)
* [os.uuid](os.uuid) (can now generated deterministic name-based UUIDs) * [os.uuid](os.uuid.md) (can now generated deterministic name-based UUIDs)
* [path.getabsolute](path.getabsolute) (new "relative to" argument) * [path.getabsolute](path.getabsolute.md) (new "relative to" argument)
* [string.hash](string.hash) (new) * [string.hash](string.hash.md) (new)
## Deprecated Values and Functions ## ## Deprecated Values and Functions ##
* [buildrule](buildrule) * [buildrule](buildrule.md)
* [flags](flags): * [flags](flags.md):
* Component * Component
* EnableSSE, EnableSSE2: use [vectorextensions](vectorextensions) instead * EnableSSE, EnableSSE2: use [vectorextensions](vectorextensions.md) instead
* ExtraWarnings, NoWarnings: use [warnings](warnings) instead * ExtraWarnings, NoWarnings: use [warnings](warnings.md) instead
* FloatFast, FloatStrict: use [floatingpoint](floatingpoint) instead * FloatFast, FloatStrict: use [floatingpoint](floatingpoint.md) instead
* Managed, Unsafe: use [clr](clr) instead * Managed, Unsafe: use [clr](clr.md) instead
* NativeWChar: use [nativewchar](nativewchar) instead * NativeWChar: use [nativewchar](nativewchar.md) instead
* NoEditAndContinue: use [editandcontinue](editandcontinue) instead * NoEditAndContinue: use [editandcontinue](editAndContinue.md) instead
* NoRTTI: use [rtti](rtti) instead. * NoRTTI: use [rtti](rtti.md) instead.
* OptimizeSize, OptimizeSpeed: use [optimize](optimize) instead * OptimizeSize, OptimizeSpeed: use [optimize](optimize.md) instead

18
website/docs/Workspaces-and-Projects.md
View File

@ -9,16 +9,16 @@ For convenience, Premake follows the Visual Studio conventions for structuring a
At the top level of every build is a *workspace*, acting as a container for *projects*. Other tools, notably Visual Studio, may use the term *solution*. At the top level of every build is a *workspace*, acting as a container for *projects*. Other tools, notably Visual Studio, may use the term *solution*.
Workspaces define a common set of [build configurations and platforms](configurations-and-platforms) to be used across all of the contained projects. You may also specify additional build settings (defines, include paths, etc.) at this level which will be similarly inherited by the projects. Workspaces define a common set of [build configurations and platforms](Configurations-and-Platforms.md) to be used across all of the contained projects. You may also specify additional build settings (defines, include paths, etc.) at this level which will be similarly inherited by the projects.
Workspaces are defined using the [`workspace`](workspace) function. Most builds will need only a single workspace, but you are free to create more if needed. Build configurations are specified using the [`configurations`](configurations) function and are required; see [Configurations and Platforms](configurations-and-platforms) for more information. Workspaces are defined using the [`workspace`](workspace.md) function. Most builds will need only a single workspace, but you are free to create more if needed. Build configurations are specified using the [`configurations`](configurations.md) function and are required; see [Configurations and Platforms](Configurations-and-Platforms.md) for more information.
```lua ```lua
workspace "HelloWorld" workspace "HelloWorld"
configurations { "Debug", "Release" } configurations { "Debug", "Release" }
``` ```
The workspace name, provided as a parameter to the function, is used as the default file name of the generated workspace file, so it is best to avoid special characters (spaces are okay). If you wish to use a different name use the [`filename`](filename) function to specify it. The workspace name, provided as a parameter to the function, is used as the default file name of the generated workspace file, so it is best to avoid special characters (spaces are okay). If you wish to use a different name use the [`filename`](filename.md) function to specify it.
```lua ```lua
workspace "Hello World" workspace "Hello World"
@ -33,7 +33,7 @@ workspace "Hello World"
The primary purpose of a workspace is to act as a container for projects. A *project* lists the settings and source files needed to build one binary target. Just about every IDE uses the term "project" for this. In the world of Make, you can think of projects as a makefile for one particular library or executable; the workspace is a meta-makefile that calls each project as needed. The primary purpose of a workspace is to act as a container for projects. A *project* lists the settings and source files needed to build one binary target. Just about every IDE uses the term "project" for this. In the world of Make, you can think of projects as a makefile for one particular library or executable; the workspace is a meta-makefile that calls each project as needed.
Projects are defined using the [`project`](project) function. You must create the containing workspace first. Projects are defined using the [`project`](project.md) function. You must create the containing workspace first.
```lua ```lua
workspace "MyWorkspace" workspace "MyWorkspace"
@ -42,11 +42,11 @@ workspace "MyWorkspace"
project "MyProject" project "MyProject"
``` ```
The project name, like the workspace name, is used as the file name for the generated project file so avoid special characters, or use the [`filename`](filename) function to provide a different value. The project name, like the workspace name, is used as the file name for the generated project file so avoid special characters, or use the [`filename`](filename.md) function to provide a different value.
Each project specifies a *kind* which determines what kind of output is generated, such as a console or windowed executable, or a shared or static library. The [`kind`](kind) function is used to specify this value. Each project specifies a *kind* which determines what kind of output is generated, such as a console or windowed executable, or a shared or static library. The [`kind`](kind.md) function is used to specify this value.
Each project also specifies which programming language it uses, such as C++ or C#. The [`language`](language) function is used to set this value. Each project also specifies which programming language it uses, such as C++ or C#. The [`language`](language.md) function is used to set this value.
```lua ```lua
project "MyProject" project "MyProject"
@ -59,7 +59,7 @@ project "MyProject"
By default, Premake will place generated workspace and project files in the same directory as the script which defined them. If your Premake script is in `C:\Code\MyProject` then the generated files will also be in `C:\Code\MyProject`. By default, Premake will place generated workspace and project files in the same directory as the script which defined them. If your Premake script is in `C:\Code\MyProject` then the generated files will also be in `C:\Code\MyProject`.
You can change the output location using the [location](location) function. You can change the output location using the [location](location.md) function.
```lua ```lua
workspace "MyWorkspace" workspace "MyWorkspace"
@ -70,4 +70,4 @@ project "MyProject"
location "build/MyProject" location "build/MyProject"
``` ```
Like all paths in Premake, the [location](location) should be specified relative to the script file. Using the example and script above, the generated workspace will be placed in `C:\Code\MyProject\build` and the project in `C:\Code\MyProject\build\MyProject`. Like all paths in Premake, the [location](location.md) should be specified relative to the script file. Using the example and script above, the generated workspace will be placed in `C:\Code\MyProject\build` and the project in `C:\Code\MyProject\build\MyProject`.

2
website/docs/Your-First-Script.md
View File

@ -43,7 +43,7 @@ If you save this script as a file named `premake5.lua`, and place it in the same
$ premake5 vs2013 $ premake5 vs2013
``` ```
This particular command will generate `HelloWorld.sln` and `HelloWorld.vcxproj` files for Visual Studio 2013 (see [Using Premake](using-premake) or run `premake --help` for a complete list of exporters). If you build the generated workspace, you will get a command line executable named `HelloWorld.exe` in the `bin/Debug` or `bin/Release` directory, depending on which configuration was selected within Visual Studio. This particular command will generate `HelloWorld.sln` and `HelloWorld.vcxproj` files for Visual Studio 2013 (see [Using Premake](Using-Premake.md) or run `premake --help` for a complete list of exporters). If you build the generated workspace, you will get a command line executable named `HelloWorld.exe` in the `bin/Debug` or `bin/Release` directory, depending on which configuration was selected within Visual Studio.
If you happened to be on Linux, you could generate and build a makefile like so: If you happened to be on Linux, you could generate and build a makefile like so:

2
website/docs/os.translateCommands.md
View File

@ -1,4 +1,4 @@
Translate [command tokens](Tokens#command-tokens) into their OS or action specific equivalents. Translate [command tokens](Tokens.md#command-tokens) into their OS or action specific equivalents.
```lua ```lua
cmd = os.translateCommands("cmd", map) cmd = os.translateCommands("cmd", map)