mirror of
https://github.com/xenia-project/premake-core.git
synced 2025-02-21 12:32:44 +00:00
Port user guide pages from wiki
This commit is contained in:
starkos
parent
c97edfa2a1
commit
d9cab6a684
@ -1,4 +1,4 @@
|
||||
# Premake website
|
||||
# Premake Website
|
||||
|
||||
Premake website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
|
||||
|
||||
@ -16,6 +16,8 @@ npm start
|
||||
|
||||
This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
|
||||
|
||||
To see a list of broken links (mistakes happen!), be sure to run `npm run build` before submitting updates.
|
||||
|
||||
## Build
|
||||
|
||||
```
|
||||
@ -23,4 +25,3 @@ npm run-script build
|
||||
```
|
||||
|
||||
This command generates static content into the `build` directory and can be served using any static contents hosting service.
|
||||
|
||||
|
||||
14
website/docs/Adding-New-Action.md
Normal file
14
website/docs/Adding-New-Action.md
Normal file
@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Adding a New Action
|
||||
---
|
||||
|
||||
The Visual Studio, Makefile, and other exporters included in Premake are all "actions". They take the information from your project scripts and perform an action: in these examples, they output project files for specific toolsets.
|
||||
|
||||
Premake provides the ability to create your own actions. These can be simple one time operations like preparing a working copy of your source code for first use, or complex support for an entirely new toolset.
|
||||
|
||||
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)
|
||||
* [Generating Project Files](generating-project-files)
|
||||
* Working with Configurations
|
||||
* (More to come!)
|
||||
46
website/docs/Adding-Source-Files.md
Normal file
46
website/docs/Adding-Source-Files.md
Normal file
@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Adding Source Files
|
||||
---
|
||||
|
||||
You add files—source code, resources, and so on—to your project using the [files](files) function.
|
||||
|
||||
```lua
|
||||
files {
|
||||
"hello.h", -- you can specify exact names
|
||||
"*.c", -- or use a wildcard...
|
||||
"**.cpp" -- ...and recurse into subdirectories
|
||||
}
|
||||
```
|
||||
|
||||
You can use wildcards in the file patterns to match a set of files. The wildcard \* will match files in one directory; the wildcard \*\* will match files in one directory and also recurse down into any subdirectories.
|
||||
|
||||
Files located in other directories should be specified relative to the script file. For example, if the script is located at `MyProject/build` and the source files are at `MyProject/src`, the files should be specified as:
|
||||
|
||||
```lua
|
||||
files { "../src/*.cpp" }
|
||||
```
|
||||
|
||||
Paths should always use the forward slash `/` as a separator; Premake will translate to the appropriate platform-specific separator as needed.
|
||||
|
||||
## 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.
|
||||
|
||||
```lua
|
||||
files { "*.c" }
|
||||
removefiles { "a_file.c", "another_file.c" }
|
||||
```
|
||||
|
||||
Excludes may also use wildcards.
|
||||
|
||||
```lua
|
||||
files { "**.c" }
|
||||
removefiles { "tests/*.c" }
|
||||
```
|
||||
|
||||
Sometimes you may want to exclude all the files in a particular directory, but aren't sure where that directory will fall in the source tree.
|
||||
|
||||
```lua
|
||||
files { "**.c" }
|
||||
removefiles { "**/Win32Specific/**" }
|
||||
```
|
||||
103
website/docs/Adding-Unit-Tests.md
Normal file
103
website/docs/Adding-Unit-Tests.md
Normal file
@ -0,0 +1,103 @@
|
||||
---
|
||||
title: Adding Unit Tests
|
||||
---
|
||||
|
||||
Premake includes an automated testing system that you can use the verify the behavior of your new module.
|
||||
|
||||
|
||||
## Add your first test
|
||||
|
||||
Within our [Lucky module](introducing-modules) 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:
|
||||
|
||||
```lua
|
||||
local suite = test.declare("lucky_numbers")
|
||||
|
||||
function suite.aFailingTest()
|
||||
test.isequal(2, 3)
|
||||
end
|
||||
```
|
||||
|
||||
You'll also need a manifest to list all of your test files. Create another file in that same folder named `_tests.lua`:
|
||||
|
||||
```lua
|
||||
lucky = require('lucky') -- replace with name of your module, obviously
|
||||
|
||||
return {
|
||||
"test_lucky_numbers.lua",
|
||||
}
|
||||
```
|
||||
|
||||
When you're all done, your module should now look like:
|
||||
|
||||
```
|
||||
lucky/
|
||||
|- lucky.lua
|
||||
`- tests/
|
||||
|- _tests.lua
|
||||
`- test_lucky_numbers.lua
|
||||
```
|
||||
|
||||
## Enable the testing module
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
```lua
|
||||
newaction {
|
||||
trigger = "test",
|
||||
description = "Run the automated test suite",
|
||||
execute = function ()
|
||||
test = require "self-test"
|
||||
premake.action.call("self-test")
|
||||
end
|
||||
}
|
||||
```
|
||||
|
||||
## Run your test
|
||||
|
||||
Once the testing module is enabled, `cd` to your module folder and run the command `premake5 self-test`. You should see your simple failing test fail.
|
||||
|
||||
```
|
||||
$ premake5 self-test
|
||||
Running action 'self-test'...
|
||||
lucky_numbers.aFailingTest: ...e/Premake/Modules/lucky/tests/test_lucky_numbers.lua:4: expected 2 but was 3
|
||||
0 tests passed, 1 failed in 0.00 seconds
|
||||
```
|
||||
|
||||
If developing new tests for premake itself, it is often beneficial to run smaller subsets of tests with the command-line option --test-only:
|
||||
|
||||
```
|
||||
$ premake5 --test-only=lucky_numbers test
|
||||
```
|
||||
|
||||
## Passing a test
|
||||
|
||||
To complete the example, let's replace our failing test with one which actually calls our module.
|
||||
|
||||
```lua
|
||||
local suite = test.declare("lucky_numbers")
|
||||
|
||||
function suite.makesEightLucky()
|
||||
local x = lucky.makeNumberLucky(8)
|
||||
test.isequal(56, x)
|
||||
end
|
||||
```
|
||||
|
||||
And give it a go:
|
||||
|
||||
```
|
||||
$ premake5 self-test
|
||||
Running action 'self-test'...
|
||||
1 tests passed, 0 failed in 0.00 seconds
|
||||
```
|
||||
|
||||
## Next steps?
|
||||
|
||||
The `tests` folder in the Premake source code contains over 1,000 tests which you can use as examples. The ones in [`tests/actions/vstudio/vc2010`](https://github.com/premake/premake-core/tree/master/tests/actions/vstudio/vc2010) tend to be the most frequently updated and maintained, and generally make the best examples.
|
||||
|
||||
You can see the full set of test assertions (`test.isequal()`, `test.capture()`, etc.) in the Premake source code at [`modules/self-test/test_assertions.lua`](https://github.com/premake/premake-core/blob/master/modules/self-test/test_assertions.lua).
|
||||
20
website/docs/Build-Settings.md
Normal file
20
website/docs/Build-Settings.md
Normal file
@ -0,0 +1,20 @@
|
||||
---
|
||||
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).
|
||||
|
||||
If you think something should be possible and you can't figure out how to do it, see [Getting Help](getting-help).
|
||||
|
||||
| | |
|
||||
|-----------------------------------------------|----------------------|
|
||||
| Specify the binary type (executable, library) | [kind](kind) |
|
||||
| Specify source code files | [files](files), [removefiles](files) |
|
||||
| Define compiler or preprocessor symbols | [defines](defines) |
|
||||
| Locate include files | [includedirs](includedirs) |
|
||||
| Set up precompiled headers | [pchheader](pchheader), [pchsource](pchsource) |
|
||||
| Link libraries, frameworks, or other projects | [links](links), [libdirs](libdirs) |
|
||||
| Enable debugging information | symbols(symbols) |
|
||||
| Optimize for size or speed | [optimize](optimize) |
|
||||
| Add arbitrary build flags | [buildoptions](buildoptions), [linkoptions](linkoptions) |
|
||||
| Set the name or location of compiled targets | [targetname](targetname), [targetdir](targetdir) |
|
||||
63
website/docs/Code-Overview.md
Normal file
63
website/docs/Code-Overview.md
Normal file
@ -0,0 +1,63 @@
|
||||
---
|
||||
title: Code Overview
|
||||
---
|
||||
|
||||
## A Quick Tour of Premake ##
|
||||
|
||||
The Premake source code is organized into a few different folders:
|
||||
|
||||
* `src/actions` contains the code for the built-on actions and exporters, e.g. "vs2012" or "gmake". We are gradually migrating these into independent modules, but for now they live here.
|
||||
|
||||
* `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/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.
|
||||
|
||||
* `modules` contains the official set of modules which are distributed as part of Premake. These modules add support for additional languages and toolsets to the core code in the `src` folder.
|
||||
|
||||
In addition to those general categories, there are a few special files of note:
|
||||
|
||||
* `src/_premake_main.lua` contains the Lua-side program entry point, and is responsible for the main application flow. The C-side program entry point `main()` is located in `src/host/premake_main.c`.
|
||||
|
||||
* `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/_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.
|
||||
|
||||
|
||||
## Code Execution Overview ##
|
||||
|
||||
Execution starts at `main()` in `src/host/premake_main.c`, which calls into to `src/host/premake.c` to do the real bootstrapping work:
|
||||
|
||||
* `premake_init()` installs all of Premake's native C extensions to the Lua scripting environment.
|
||||
|
||||
* `premake_execute()` finds and runs `src/_premake_main.lua`, which may be embedded into the executable for a release build, or located on the filesystem.
|
||||
|
||||
* `src/_premake_main.lua` in turn reads `src/_manifest.lua` and loads all of the scripts listed there. Notably, this includes `src/_premake_init.lua` which does
|
||||
|
||||
* 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.
|
||||
|
||||
`_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:
|
||||
|
||||
* `prepareEnvironment()` sets more global variables and otherwise gets the script environment ready to use.
|
||||
|
||||
* `locateUserScript()` handles finding the user's project script, i.e. `premake5.lua` on the file system.
|
||||
|
||||
* `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()`.
|
||||
|
||||
* `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.
|
||||
|
||||
* `bake()` takes all of the project and configuration information that has been specified in the user's project script and prepares it for use by the target action, a somewhat convoluted process that is implemented in `src/base/oven.lua`.
|
||||
|
||||
* `validate()` examines the processed configuration information and tries to make sure it all makes sense, and that all required data is available. The main validation logic is located in `src/base/validation.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).
|
||||
|
||||
114
website/docs/Coding-Conventions.md
Normal file
114
website/docs/Coding-Conventions.md
Normal file
@ -0,0 +1,114 @@
|
||||
---
|
||||
title: Coding Conventions
|
||||
---
|
||||
|
||||
While not all of Premake's code currently follows these conventions, we are gradually nudging everything in this direction and hope to have it all done before the final 5.0 release. Knowing these conventions will make the code a little easier to read and follow.
|
||||
|
||||
|
||||
### Tables as Namespaces
|
||||
|
||||
Premake tables are used as namespaces, with related functions grouped together into their own namespace table. Most of Premake's own code is placed into a table named `premake`. Code related to the project scripting API is in `premake.api`, code related to command line options in in `premake.options`, and so on.
|
||||
|
||||
Organizing the code in this way helps avoid collisions between similarly named functions, and generally helps to keep things tidy.
|
||||
|
||||
|
||||
### Local Variables as Aliases
|
||||
|
||||
New namespaces are declared at the top of each source code file, followed by aliases for namespaces which are going to be used frequently within the source file. For example:
|
||||
|
||||
```lua
|
||||
-- define a new namespace for the VC 2010 related code
|
||||
premake.vstudio.vc2010 = {}
|
||||
|
||||
-- create aliases for namespaces we'll use often
|
||||
local p = premake
|
||||
local vstudio = p.vstudio
|
||||
local project = p.project
|
||||
|
||||
-- and the "m" alias represents the current module being implemented
|
||||
local m = p.vstudio.vc2010
|
||||
```
|
||||
|
||||
The alias `p` is used conventionally as a shortcut for the `premake` namespace. The alias `m` is conventially used to represent the module being implemented.
|
||||
|
||||
Using aliases saves some keystrokes when coding. And since Premake embeds all of its scripts into the release executables, it saves on the final download size as well.
|
||||
|
||||
|
||||
### Call Arrays
|
||||
|
||||
Premake's project file exporters—which write out the Visual Studio projects, makefiles, and so on—are basically big long lists of "output this, and then this, and then this". This could easily be written (and once was) as one giant function, but then it would be virtually impossible to modify its behavior.
|
||||
|
||||
Instead, we split up the generation of a project into many small functions, often writing out only a single line to the output. Any one of these functions can then be overridden by your own scripts or modules.
|
||||
|
||||
```lua
|
||||
-- instead of this...
|
||||
|
||||
function m.outputConfig(cfg)
|
||||
if #cfg.defines > 0 or vstudio.isMakefile(cfg) then
|
||||
p.x('PreprocessorDefinitions="%s"', table.concat(cfg.defines, ";"))
|
||||
end
|
||||
|
||||
if #cfg.undefines > 0 then
|
||||
p.x('UndefinePreprocessorDefinitions="%s"', table.concat(cfg.undefines, ";"))
|
||||
end
|
||||
|
||||
if cfg.rtti == p.OFF and cfg.clr == p.OFF then
|
||||
p.w('RuntimeTypeInfo="false"')
|
||||
elseif cfg.rtti == p.ON then
|
||||
p.w('RuntimeTypeInfo="true"')
|
||||
end
|
||||
end
|
||||
|
||||
-- we do this...
|
||||
|
||||
function m.preprocessorDefinitions(cfg)
|
||||
if #cfg.defines > 0 or vstudio.isMakefile(cfg) then
|
||||
p.x('PreprocessorDefinitions="%s"', table.concat(cfg.defines, ";"))
|
||||
end
|
||||
end
|
||||
|
||||
function m.undefinePreprocessorDefinitions(cfg)
|
||||
if #cfg.undefines > 0 then
|
||||
p.x('UndefinePreprocessorDefinitions="%s"', table.concat(cfg.undefines, ";"))
|
||||
end
|
||||
end
|
||||
|
||||
function m.runtimeTypeInfo(cfg)
|
||||
if cfg.rtti == p.OFF and cfg.clr == p.OFF then
|
||||
p.w('RuntimeTypeInfo="false"')
|
||||
elseif cfg.rtti == p.ON then
|
||||
p.w('RuntimeTypeInfo="true"')
|
||||
end
|
||||
end
|
||||
|
||||
```
|
||||
|
||||
Similarly, instead of implementing the output of a particular section of the project as a function calling a long list of other functions, we put those functions into an array, and then iterate over the array. We call these "call arrays", and they allow you to inject new functions, or remove existing ones, from the array at runtime.
|
||||
|
||||
```lua
|
||||
-- instead of this...
|
||||
|
||||
function m.outputConfig(cfg)
|
||||
m.preprocessorDefinitions(cfg)
|
||||
m.undefinePreprocessorDefinitions(cfg)
|
||||
m.runtimeTypeInfo(cfg)
|
||||
-- and so on...
|
||||
end
|
||||
|
||||
-- we do this
|
||||
|
||||
m.elements.config = function(cfg)
|
||||
return {
|
||||
m.preprocessorDefinitions,
|
||||
m.undefinePreprocessorDefinitions,
|
||||
m.runtimeTypeInfo,
|
||||
-- and so on...
|
||||
}
|
||||
end
|
||||
|
||||
function m.outputConfig(cfg)
|
||||
p.callArray(m.element.config, cfg)
|
||||
end
|
||||
```
|
||||
|
||||
For an example of how to implement a new feature using these conventions, see [Overrides and Call Arrays](Overrides-and-Call-Arrays).
|
||||
128
website/docs/Command-Line-Arguments.md
Normal file
128
website/docs/Command-Line-Arguments.md
Normal file
@ -0,0 +1,128 @@
|
||||
---
|
||||
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.
|
||||
|
||||
## Actions and Options
|
||||
|
||||
Premake recognizes two types of arguments: _actions_ and _options_.
|
||||
|
||||
An _action_ indicates what Premake should do on any given run. For instance, the `vs2013` action indicates that Visual Studio 2013 project files should be generated. The `clean` action causes all generated files to be deleted. Only one action may be specified at a time.
|
||||
|
||||
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.
|
||||
|
||||
```lua
|
||||
-- delete a file if the clean action is running
|
||||
if _ACTION == "clean" then
|
||||
-- do something
|
||||
end
|
||||
|
||||
-- use an option value in a configuration
|
||||
targetdir ( _OPTIONS["outdir"] or "out" )
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
|
||||
```lua
|
||||
newoption {
|
||||
trigger = "with-opengl",
|
||||
description = "Force the use of OpenGL for rendering, regardless of platform"
|
||||
}
|
||||
```
|
||||
|
||||
Note the commas after each key-value pair; this is required Lua syntax for a table. Once added to your script, the option will appear in the help text, and you may use the trigger as a keyword in your configuration blocks.
|
||||
|
||||
```lua
|
||||
configuration "with-opengl"
|
||||
links { "opengldrv" }
|
||||
|
||||
configuration "not with-opengl"
|
||||
links { "direct3ddrv" }
|
||||
```
|
||||
|
||||
The next example shows an option with a fixed set of allowed values. Like the example above, it is intended to allow the user to specify a 3D API.
|
||||
|
||||
```lua
|
||||
newoption {
|
||||
trigger = "gfxapi",
|
||||
value = "API",
|
||||
description = "Choose a particular 3D API for rendering",
|
||||
allowed = {
|
||||
{ "opengl", "OpenGL" },
|
||||
{ "direct3d", "Direct3D (Windows only)" },
|
||||
{ "software", "Software Renderer" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
As before, this new option will be integrated into the help text, along with a description of each of the allowed values. Premake will check the option value at startup, and raise an error on invalid values. The <b>value</b> field appears in the help text, and is intended to give the user a clue about the type of value that is expected. In this case, the help text will appear like this:
|
||||
|
||||
```
|
||||
--gfxapi=API Choose a particular 3D API for rendering; one of:
|
||||
opengl OpenGL
|
||||
direct3d Direct3D (Windows only)
|
||||
software Software Renderer
|
||||
```
|
||||
|
||||
Unlike the example above, you now use the _value_ as a keyword in your configuration blocks.
|
||||
|
||||
```lua
|
||||
configuration "opengl"
|
||||
links { "opengldrv" }
|
||||
|
||||
configuration "direct3d"
|
||||
links { "direct3ddrv" }
|
||||
|
||||
configuration "software"
|
||||
links { "softwaredrv" }
|
||||
```
|
||||
|
||||
Or you could be more clever.
|
||||
|
||||
```lua
|
||||
links { _OPTIONS["gfxapi"] .. "drv" }
|
||||
```
|
||||
|
||||
In this example, you would also want to provide a default behavior for the case where no option is specified. You could place a bit of code like this anywhere in your script.
|
||||
|
||||
```lua
|
||||
if not _OPTIONS["gfxapi"] then
|
||||
_OPTIONS["gfxapi"] = "opengl"
|
||||
end
|
||||
```
|
||||
|
||||
As a last example of options, you may want to specify an option that accepts an unconstrained value, such as an output path. Just leave off the list of allowed values.
|
||||
|
||||
```lua
|
||||
newoption {
|
||||
trigger = "outdir",
|
||||
value = "path",
|
||||
description = "Output directory for the compiled executable"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Creating New Actions
|
||||
|
||||
Actions are defined in much the same way as options, and can be as simple as this:
|
||||
|
||||
```lua
|
||||
newaction {
|
||||
trigger = "install",
|
||||
description = "Install the software",
|
||||
execute = function ()
|
||||
-- copy files, etc. here
|
||||
end
|
||||
}
|
||||
```
|
||||
|
||||
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).
|
||||
127
website/docs/Configurations-and-Platforms.md
Normal file
127
website/docs/Configurations-and-Platforms.md
Normal file
@ -0,0 +1,127 @@
|
||||
---
|
||||
title: Configurations & Platforms
|
||||
---
|
||||
|
||||
A *configuration* is a collection of settings to apply to a build, including flags and switches, header file and library search directories, and more. Each workspace defines its own list of configuration names; the default provided by most IDEs is "Debug" and "Release".
|
||||
|
||||
## Build Configurations
|
||||
|
||||
The [previous examples](your-first-script) showed how to specify build configurations.
|
||||
|
||||
```lua
|
||||
workspace "MyWorkspace"
|
||||
configurations { "Debug", "Release" }
|
||||
```
|
||||
|
||||
You are not limited to these names, but can use whatever makes sense to your software project and build environment. For instance, if your project can be built as both static or shared libraries, you might use this instead:
|
||||
|
||||
```lua
|
||||
workspace "MyWorkspace"
|
||||
configurations { "Debug", "DebugDLL", "Release", "ReleaseDLL" }
|
||||
```
|
||||
|
||||
It is important to note that these names have no meaning in and of themselves, and that you can use whatever names you like.
|
||||
|
||||
```lua
|
||||
workspace "MyWorkspace"
|
||||
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).
|
||||
|
||||
```lua
|
||||
workspace "HelloWorld"
|
||||
configurations { "Debug", "Release" }
|
||||
|
||||
filter "configurations:Debug"
|
||||
defines { "DEBUG" }
|
||||
flags { "Symbols" }
|
||||
|
||||
filter "configurations:Release"
|
||||
defines { "NDEBUG" }
|
||||
optimize "On"
|
||||
```
|
||||
|
||||
The [Filters](filters) section will cover this in more detail.
|
||||
|
||||
|
||||
## Platforms
|
||||
|
||||
"Platforms" is a bit of a misnomer here; once again I am following the Visual Studio nomenclature. Really, platforms are just another set of build configuration names, providing another axis on which to configure your project.
|
||||
|
||||
```lua
|
||||
configurations { "Debug", "Release" }
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
```lua
|
||||
configurations { "Debug", "Release" }
|
||||
platforms { "Win32", "Win64", "Xbox360" }
|
||||
|
||||
filter { "platforms:Win32" }
|
||||
system "Windows"
|
||||
architecture "x86"
|
||||
|
||||
filter { "platforms:Win64" }
|
||||
system "Windows"
|
||||
architecture "x86_64"
|
||||
|
||||
filter { "platforms:Xbox360" }
|
||||
system "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.
|
||||
|
||||
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.
|
||||
|
||||
```lua
|
||||
configurations { "Debug", "Release" }
|
||||
platforms { "Static", "DLL" }
|
||||
|
||||
filter { "platforms:Static" }
|
||||
kind "StaticLib"
|
||||
|
||||
filter { "platforms:DLL" }
|
||||
kind "SharedLib"
|
||||
defines { "DLL_EXPORTS" }
|
||||
```
|
||||
|
||||
## Per-Project Configurations
|
||||
|
||||
Configurations and platform lists may now be specified per-project. As an example, a project that should build for Windows, but not for a game console, can remove that platform:
|
||||
|
||||
```lua
|
||||
workspace "MyWorkspace"
|
||||
configurations { "Debug", "Release" }
|
||||
platforms { "Windows", "PS3" }
|
||||
|
||||
project "MyProject"
|
||||
removeplatforms { "PS3" }
|
||||
```
|
||||
|
||||
A related feature, configuration maps, translate a workspace-level configuration to project-level values, allowing projects with different configuration and platform lists to be combined in a single workspace. For example, a unit test library might be configured with the generic debug and release configurations.
|
||||
|
||||
```lua
|
||||
project "UnitTest"
|
||||
configurations { "Debug", "Release" }
|
||||
|
||||
```
|
||||
|
||||
To reuse that test project in a workspace which contains a more complex set of configurations, create a mapping from the workspace's configurations to the corresponding project configuration.
|
||||
|
||||
```lua
|
||||
workspace "MyWorkspace"
|
||||
configurations { "Debug", "Development", "Profile", "Release" }
|
||||
|
||||
project "UnitTest"
|
||||
configmap {
|
||||
["Development"] = "Debug",
|
||||
["Profile"] = "Release"
|
||||
}
|
||||
```
|
||||
|
||||
It is important to note that projects can't *add* new configurations to the workspace. They can only remove support for existing workspace configurations, or map them to a different project configuration.
|
||||
71
website/docs/Custom-Build-Commands.md
Normal file
71
website/docs/Custom-Build-Commands.md
Normal file
@ -0,0 +1,71 @@
|
||||
---
|
||||
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*.
|
||||
|
||||
You can also use [Makefile projects](makefile-projects) to execute external shell scripts or makefiles, rather than use the normal build system.
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
```lua
|
||||
-- copy a file from the objects directory to the target directory
|
||||
postbuildcommands {
|
||||
"{COPY} %{cfg.objdir}/output.map %{cfg.targetdir}"
|
||||
}
|
||||
```
|
||||
|
||||
## Custom Build Commands
|
||||
|
||||
*As of this writing, the custom build commands feature is still incomplete; see the list of limitations below.*
|
||||
|
||||
Custom build commands provide the ability to compile or process new types of files, other than the C/C++ or C# files Premake supports out of the box. You can compile a Cg shader program, or process an image.
|
||||
|
||||
Here is an example which compiles all Lua files in a project to C:
|
||||
|
||||
```lua
|
||||
filter 'files:**.lua'
|
||||
-- A message to display while this build step is running (optional)
|
||||
buildmessage 'Compiling %{file.relpath}'
|
||||
|
||||
-- One or more commands to run (required)
|
||||
buildcommands {
|
||||
'luac -o "%{cfg.objdir}/%{file.basename}.out" "%{file.relpath}"'
|
||||
}
|
||||
|
||||
-- One or more outputs resulting from the build (required)
|
||||
buildoutputs { '%{cfg.objdir}/%{file.basename}.c' }
|
||||
|
||||
-- One or more additional dependencies for this build command (optional)
|
||||
buildinputs { 'path/to/file1.ext', 'path/to/file2.ext' }
|
||||
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Custom build commands currently have a few shortcomings. Help fixing these issues, or any other gaps, would be most appreciated!
|
||||
|
||||
* There is limited detection of paths in the build commands. Tokens that
|
||||
expand to absolute paths (most of them do, i.e. %{cfg.objdir}) are properly
|
||||
made project relative. Custom tokens, or paths hardcoded inline with the
|
||||
commands, must be specified relative to the generated project location.
|
||||
|
||||
* Commands that output C/C++ source files are not fed into the build
|
||||
process yet (but commands that output object files are fed to the
|
||||
linker).
|
||||
|
||||
* The generated makefile rule only takes the first output into account
|
||||
for dependency checking.
|
||||
|
||||
|
||||
## 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).
|
||||
74
website/docs/Custom-Rules.md
Normal file
74
website/docs/Custom-Rules.md
Normal file
@ -0,0 +1,74 @@
|
||||
---
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
The documentation for this feature is still very incomplete.
|
||||
|
||||
|
||||
## Your First Rule
|
||||
|
||||
A simple build rule might look like this:
|
||||
|
||||
```lua
|
||||
rule "MyCustomRule"
|
||||
display "My custom compiler"
|
||||
fileextension ".xyz"
|
||||
|
||||
buildmessage 'Compiling %(Filename) with MyCustomCC'
|
||||
buildcommands 'MyCustomCC.exe -c "%(FullPath)" -o "%(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).
|
||||
|
||||
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:
|
||||
|
||||
```lua
|
||||
project "MyProject"
|
||||
rules { "MyCustomRule" }
|
||||
```
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
```lua
|
||||
rule "MyCustomRule"
|
||||
-- ...rule settings...
|
||||
|
||||
propertydefinition {
|
||||
name = "StripDebugInfo",
|
||||
ind = "boole
|
||||
display = "Strip Debug Info",
|
||||
description = "Remove debug information from the generated object files"
|
||||
value = false,
|
||||
switch = "-s"
|
||||
}
|
||||
```
|
||||
|
||||
Properties may then be used in the rule commands by enclosing the name in square brackets. This, again, is a Visual Studio convention; we may switch it up if support for additional exporters becomes available.
|
||||
|
||||
```lua
|
||||
buildcommand 'MyCustomCC.exe -c "%(FullPath)" -o "%(IntDir)/%(Filename).obj" [StripDebugInfo]
|
||||
```
|
||||
|
||||
The string `[StripDebugInfo]` will be set with the switch value `-s` if the value is set to true.
|
||||
|
||||
To set the properties for a rule, Premake will create a setter function of the format *ruleName*Vars(). To set the example property above for a project's release configuration only:
|
||||
|
||||
```lua
|
||||
project "MyProject"
|
||||
rules { "MyCustomRule" }
|
||||
|
||||
filter { "configurations:Release" }
|
||||
myCustomRuleVars {
|
||||
StripDebugInfo = true
|
||||
}
|
||||
```
|
||||
14
website/docs/Debugging-Scripts.md
Normal file
14
website/docs/Debugging-Scripts.md
Normal file
@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Debugging Scripts
|
||||
---
|
||||
|
||||
## ZeroBrane Studio
|
||||
|
||||
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
|
||||
* 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.
|
||||
* 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.
|
||||
* 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.
|
||||
* An example command line would be `C:/my_project_folder/premake5.exe vs2015 --scripts=C:/premake_repo/ --debugger`
|
||||
10
website/docs/Developing-Modules.md
Normal file
10
website/docs/Developing-Modules.md
Normal file
@ -0,0 +1,10 @@
|
||||
---
|
||||
title: Developing Modules
|
||||
---
|
||||
|
||||
Modules are the preferred way to package your customizations to reuse and share with others.
|
||||
|
||||
* [Introduction](introducing-modules)
|
||||
* [Adding Unit Tests](adding-unit-tests)
|
||||
* [Sharing Your Module](sharing-your-module)
|
||||
* [Embedding Modules](embedding-modules)
|
||||
5
website/docs/Development-Roadmap.md
Normal file
5
website/docs/Development-Roadmap.md
Normal file
@ -0,0 +1,5 @@
|
||||
---
|
||||
title: Development Roadmap
|
||||
---
|
||||
|
||||
*(Out of date; removed)*
|
||||
77
website/docs/Embedding-Modules.md
Normal file
77
website/docs/Embedding-Modules.md
Normal file
@ -0,0 +1,77 @@
|
||||
---
|
||||
title: Embedding Modules
|
||||
---
|
||||
|
||||
*This section only applies if you want to embed your module into a custom build of Premake for easier distribution. If you're not doing that, you can skip it.*
|
||||
|
||||
Premake includes [a number of modules](modules) as part of the official builds, with more being added regularly. These modules are embedded directly into Premake along with the core scripts to enable easy distribution of a single, self-contained executable.
|
||||
|
||||
If you are creating a custom build of Premake, you can easily embed your own modules by following the instructions below. Also take a look at Premake's own set of modules in the `modules/` folder for some real working examples.
|
||||
|
||||
#### 1. Put your module where Premake can find it.
|
||||
|
||||
Premake's embedding system only considers scripts which are in Premake source code tree, so the first step is to put your module where it can be found. Premake's own modules are stored in the `modules/` folder.
|
||||
|
||||
#### 2. Add a manifest
|
||||
|
||||
Premake needs to know which scripts it should embed, and which it should ignore (tests, etc.). Create a file named `_manifest.lua` which returns an array file names to be loaded. For example, Premake's Xcode module manifest looks like this:
|
||||
|
||||
```lua
|
||||
return {
|
||||
"_preload.lua",
|
||||
"xcode.lua",
|
||||
"xcode4_workspace.lua",
|
||||
"xcode_common.lua",
|
||||
"xcode_project.lua",
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. Add an (optional) preload script
|
||||
|
||||
As more modules get added, Premake has to do more and more work on startup to evaluate all of those script files. To help minimize that work, modules should try to defer loading until they are actually needed by the project being generated.
|
||||
|
||||
On startup, Premake will check each embedded module for script named `_preload.lua`. If present, Premake will run that script, and defer loading the rest of the module. After the project script has had a chance to run, Premake will then ask the module if it needs to be loaded and, if so, load it before continuing. If no `_preload.lua` script is present, the module will be fully loaded immediately on startup.
|
||||
|
||||
To enable this, create a file named `_preload.lua` (be sure to also add it to your manifest). Move any settings or values that might be required by a project script—new actions, command line options, or project API calls or allowed values—out of your module to this file. At the very end of the script, return a function which determines whether the module can be loaded or not.
|
||||
|
||||
Here is a subset of the `_preload.lua` script from Premake's Xcode module:
|
||||
|
||||
```lua
|
||||
local p = premake
|
||||
|
||||
-- Register the Xcode action.
|
||||
|
||||
newaction {
|
||||
trigger = "xcode4",
|
||||
shortname = "Apple Xcode 4",
|
||||
description = "Generate Apple Xcode 4 project files",
|
||||
|
||||
-- …
|
||||
}
|
||||
|
||||
-- Decide when the full module should be loaded.
|
||||
|
||||
return function(cfg)
|
||||
return (_ACTION == "xcode4")
|
||||
end
|
||||
```
|
||||
|
||||
It starts by registering the Xcode action; this allows the action to be used on the command line and appear in Premake's help text, even though the full module has not yet been loaded. It then returns a test function to decide when the module should be loaded: in this case, when the user requests the "xcode4" action on the command line.
|
||||
|
||||
In the case of a new action, the test function's configuration argument is ignored. In Premake's D language module, it should only load if one of the project's specified in the user scripts wants to use the D language.
|
||||
|
||||
```lua
|
||||
return function(cfg)
|
||||
return (cfg.language == "D")
|
||||
end
|
||||
```
|
||||
|
||||
#### 4. Tell Premake to load your module
|
||||
|
||||
If you would like your module loaded (or pre-loaded) on startup, you must add it to the list in `src/_modules.lua`. Modules in this list can be used by project scripts without having to first `require()` them.
|
||||
|
||||
Modules that are not in this list are still embedded and may still be used by calling `require()`.
|
||||
|
||||
#### 5. Embed and rebuild
|
||||
|
||||
The final step is run Premake's embedding script (`premake5 embed`) and then rebuild the Premake executable.
|
||||
19
website/docs/Extending-Premake.md
Normal file
19
website/docs/Extending-Premake.md
Normal file
@ -0,0 +1,19 @@
|
||||
---
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
### Use the Source! ###
|
||||
|
||||
Before you start hacking away, you should be comfortable browsing through the [source code of Premake](http://github.com/premake/premake-core) or [the third-party module](modules) you wish to modify. You will need to be able to identify the Lua function that emits the markup or otherwise implements the feature you wish to change before you can hook into it.
|
||||
|
||||
If you haven't already, you should [grab a source code package, or clone the code repository on GitHub](getting-premake) 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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
24
website/docs/Feature-Matrix.md
Normal file
24
website/docs/Feature-Matrix.md
Normal file
@ -0,0 +1,24 @@
|
||||
---
|
||||
title: Feature Matrix
|
||||
---
|
||||
|
||||
I am filling this in as I discover missing functionality in the various exporters. So it is not (yet) a comprehensive list. Porting of Xcode and CodeLite have begun and are mostly working. CodeBlocks has not yet begun.
|
||||
|
||||
|
||||
| Feature | vcproj | vcxproj | csproj | make(C) | make(C#) | xcode |
|
||||
|--------------------------------|----------|----------|----------|----------|----------|----------|
|
||||
| buildaction() | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ |
|
||||
| buildlog() | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| cleanextensions() | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| Command tokens | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
|
||||
| Configuration maps | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
|
||||
| copylocal() | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ |
|
||||
| Custom Build Commands | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
|
||||
| Custom Rules | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| Extensible (call arrays) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||
| Makefile projects | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| Per-config file lists | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| Per-file configurations | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| Per-project configurations | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
|
||||
| New platform support | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
|
||||
| Toolset versions | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
54
website/docs/Filters.md
Normal file
54
website/docs/Filters.md
Normal file
@ -0,0 +1,54 @@
|
||||
---
|
||||
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).
|
||||
|
||||
Here is an example which sets a preprocessor symbol named "DEBUG" in a workspace's "Debug" build configuration, and "NDEBUG" in the Release configuration.
|
||||
|
||||
```lua
|
||||
workspace "MyWorkspace"
|
||||
configurations { "Debug", "Release" }
|
||||
|
||||
filter "configurations:Debug"
|
||||
defines { "DEBUG" }
|
||||
|
||||
filter "configurations:Release"
|
||||
defines { "NDEBUG" }
|
||||
```
|
||||
|
||||
Filters are always made up of two parts: a *prefix* that specifies which field is being filtered against, and a *pattern* that specifies which values of that field should be accepted. Here is another example that filters by the target action:
|
||||
|
||||
Filters follow Premake's pseudo-declarative style for its scripts: calling filter() makes that filter condition "active". All settings which subsequently appear in the script will be filtered by this condition until a new filter or container (workspace, project) is activated.
|
||||
|
||||
```lua
|
||||
-- All of these settings will appear in the Debug configuration
|
||||
filter "configurations:Debug"
|
||||
defines { "DEBUG" }
|
||||
flags { "Symbols" }
|
||||
|
||||
-- All of these settings will appear in the Release configuration
|
||||
filter "configurations:Release"
|
||||
defines { "NDEBUG" }
|
||||
optimize "On"
|
||||
|
||||
-- This is a sneaky bug (assuming you always want to link against these lib files).
|
||||
-- Because the last filter set was Release. These libraries will only be linked for release.
|
||||
-- To fix this place this after the "Deactivate" filter call below. Or before any filter calls.
|
||||
links { "png", "zlib" }
|
||||
|
||||
-- "Deactivate" the current filter; these settings will apply
|
||||
-- to the entire workspace or project (whichever is active)
|
||||
filter {}
|
||||
files { "**.cpp" }
|
||||
```
|
||||
|
||||
Filters are evaluated at generation time, when the workspace or project file is being created and written to disk. When it comes time to output the settings for this workspace's "Debug" build configuration, Premake evaluates the list of filters to find those that match the "Debug" criteria.
|
||||
|
||||
Using the above example, Premake would first consider the filter "configurations:Debug". It would check the name of the configuration that was currently being output, see that it matched, and so include any settings up to the next filter call.
|
||||
|
||||
The filter "configurations:Release" would be skipped, because the pattern "Release" would not match the name of the configuration currently being generated ("Debug").
|
||||
|
||||
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).
|
||||
272
website/docs/Generating-Project-Files.md
Normal file
272
website/docs/Generating-Project-Files.md
Normal file
@ -0,0 +1,272 @@
|
||||
---
|
||||
title: Generating Project Files
|
||||
---
|
||||
|
||||
Now let's extend our new action to actually output some workspace and project files so we can begin to get a sense for how things work.
|
||||
|
||||
First we need to know what we want to generate. Let's start with a very simple Premake project script, then we'll figure out how we want it to appear when we translate it to Lua.
|
||||
|
||||
```lua
|
||||
workspace "Greetings"
|
||||
configurations { "Debug", "Release" }
|
||||
|
||||
project "HelloApp"
|
||||
kind "ConsoleApp"
|
||||
language "C++"
|
||||
files { "hello.h", "hello.cpp" }
|
||||
```
|
||||
|
||||
There are, of course, many ways we could express this in Lua. For the purposes of this tutorial, we'll start by creating two files, starting with `Greetings.wks.lua`:
|
||||
|
||||
```lua
|
||||
workspace = {
|
||||
name = "Greetings",
|
||||
projects = {
|
||||
["HelloApp"] = {
|
||||
path = "HelloApp.prj.lua",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Workspaces generally are used to manage a list of projects, so we'll try to do the same with our Lua version.
|
||||
|
||||
We'll also generate a second file named `HelloApp.prj.lua`, containing some of the easily accessible project information.
|
||||
|
||||
```lua
|
||||
project = {
|
||||
name = "MyConsoleApp",
|
||||
uuid = "B19F86AA-524E-4260-B200-243C70F2DA04",
|
||||
kind = "ConsoleApp",
|
||||
language = "C++",
|
||||
}
|
||||
```
|
||||
|
||||
This is just to get things started; we'll come back to the configurations and the source code files and all of the other settings later.
|
||||
|
||||
|
||||
## Creating the Files
|
||||
|
||||
Creating these files is easy: Premake has a built-in function to do just that, which we can leverage in our action's `onWorkspace()` and `onProject()` callbacks.
|
||||
|
||||
```lua
|
||||
-- lua/lua.lua
|
||||
|
||||
premake.modules.lua = {}
|
||||
local m = premake.modules.lua
|
||||
|
||||
local p = premake
|
||||
|
||||
newaction {
|
||||
trigger = "lua",
|
||||
description = "Export project information as Lua",
|
||||
|
||||
onStart = function ()
|
||||
end,
|
||||
|
||||
-- create a new file with a ".wks.lua" extension and
|
||||
-- then call our generateWorkspace() function.
|
||||
onWorkspace = function(wks)
|
||||
p.generate(wks, ".wks.lua", m.generateWorkspace)
|
||||
end,
|
||||
|
||||
-- create a new file with a ".prj.lua" extension and
|
||||
-- then call our generateProject() function.
|
||||
onProject = function(prj)
|
||||
p.generate(prj, ".prj.lua", m.generateProject)
|
||||
end,
|
||||
}
|
||||
|
||||
|
||||
function m.generateWorkspace(wks)
|
||||
p.w('This is a Lua "workspace" file.')
|
||||
end
|
||||
|
||||
|
||||
function m.generateProject(prj)
|
||||
p.w('This is a Lua "project" file.')
|
||||
end
|
||||
|
||||
|
||||
return m
|
||||
```
|
||||
|
||||
The `premake.generate()` function uses the information contained in the workspace or project to figure out the right name of location for the file, and then creates it on the disk. Once the file has been successfully created and opened, it then calls the function we provide as the last argument in the call (`generateWorkspace()` and `generateProject()` respectively) and passes it the corresponding workspace or project object to be exported.
|
||||
|
||||
The `p.w()` function, which stands for "Premake write", simply outputs a text string to the currently open file. You'll be seeing much more of this one.
|
||||
|
||||
If you go ahead and generate that project (i.e. run `premake5 lua` again), you will see the files get created on disk, each containing the corresponding "This is a..." message.
|
||||
|
||||
|
||||
## Populating the Workspace
|
||||
|
||||
Now we can begin to fill in our workspace and project files. Let's begin with the easy parts of the workspace.
|
||||
|
||||
```lua
|
||||
function m.generateWorkspace(wks)
|
||||
p.push('workspace = {')
|
||||
p.w('name = "%s",', wks.name)
|
||||
|
||||
p.push('projects = {')
|
||||
p.pop('},')
|
||||
|
||||
p.pop('}')
|
||||
end
|
||||
```
|
||||
|
||||
A couple of new functions here: `p.push()` writes the provided string to the output file, and increments an internal indentation level. `p.pop()` decrements the indentation level, and then writes its provided string to the output. `p.w()`, which we saw earlier, outputs its string at the current indentation level as set by `push()` and `pop()`.
|
||||
|
||||
So between all that pushing and popping, we end up with a nicely indented workspace file with an empty list of projects.
|
||||
|
||||
```lua
|
||||
workspace = {
|
||||
name = "Greetings",
|
||||
projects = {
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Let's tackle that project list next. Premake has an entire API for working with workspaces, which you can find by browsing the [src/base/workspace.lua](https://github.com/premake/premake-core/blob/master/src/base/workspace.lua) script in Premake's source code.
|
||||
|
||||
*(Coming soon, just need to make a few code changes...)*
|
||||
|
||||
|
||||
## Populating the Project
|
||||
|
||||
Since we're only exporting a few of the simple fields, generating our project file is quite easy:
|
||||
|
||||
```lua
|
||||
function m.generateProject(prj)
|
||||
p.push('project = {')
|
||||
p.w('name = "%s",', prj.name)
|
||||
p.w('uuid = "%s",', prj.uuid)
|
||||
p.w('kind = "%s"', prj.kind)
|
||||
p.pop('}')
|
||||
end
|
||||
```
|
||||
|
||||
Which gives us a project file like:
|
||||
|
||||
```lua
|
||||
project = {
|
||||
name = "MyConsoleApp",
|
||||
uuid = "B19F86AA-524E-4260-B200-243C70F2DA04",
|
||||
kind = "ConsoleApp",
|
||||
language = "C++",
|
||||
}
|
||||
```
|
||||
|
||||
## Escapes and Indents and EOLs
|
||||
|
||||
For the sake of completeness, a few last points.
|
||||
|
||||
First, indentation. By default, Premake will uses tab characters to indent the output. If your target format uses a different character sequence, two spaces for instances, you can adjust that using Premake's `p.indent()` function.
|
||||
|
||||
```lua
|
||||
p.indent(" ")
|
||||
```
|
||||
|
||||
Similarly, Premake will output Unix-style "\n" line endings by default, which can be changed with the `p.eol()` function.
|
||||
|
||||
```lua
|
||||
p.eol("\r\n")
|
||||
```
|
||||
|
||||
If you wish to change these values for both your generated workspaces and projects, you can place them in your action's `onStart()` function. If the values are different between workspaces and projects, put then in `onWorkspace()` and `onProject()` instead.
|
||||
|
||||
```lua
|
||||
onStart = function()
|
||||
p.indent(" ")
|
||||
p.eol("\r\n")
|
||||
end
|
||||
```
|
||||
|
||||
Finally, before we go we should consider string escaping. If, for example, someone were to name their project `Joe's "Lucky" Diner`, we would try to generate this Lua script...
|
||||
|
||||
```lua
|
||||
name = "Joe's "Lucky" Diner",
|
||||
```
|
||||
|
||||
...which would fail to load in a Lua interpreter, since the double quotes aren't properly matched. Instead, we ought to be generating:
|
||||
|
||||
```lua
|
||||
name = "Joe's \"Lucky\" Diner",
|
||||
```
|
||||
|
||||
Premake allows exporters to define an "escaper", a function which is used to transform values before they are written to the output. For our Lua exporter, we want to escape those double quotes with a backslash, and we should also escape backslashes while we're at it, which we can do by adding this function to our module:
|
||||
|
||||
```lua
|
||||
function m.esc(value)
|
||||
value = value:gsub('\\', '\\\\')
|
||||
value = value:gsub('"', '\\"')
|
||||
return value
|
||||
end
|
||||
```
|
||||
|
||||
We can then tell Premake to use this function for both our workspaces and our project by registering our escaper in our action's `onStart()`.
|
||||
|
||||
```lua
|
||||
onStart = function()
|
||||
p.escaper(m.escaper)
|
||||
end
|
||||
```
|
||||
|
||||
One more step: since we don't *always* want to escape values, Premake provides a separate call `p.x()` for those times when we do. For our example case, we really only need to worry about the workspace and solution names right now, since the other fields are limited to values which do not contain special characters (while there is no harm in using `p.x()` on values that do not contain special characters, there is a small performance hit which can add up for large projects).
|
||||
|
||||
So our final script looks like this:
|
||||
|
||||
```lua
|
||||
-- lua/lua.lua
|
||||
|
||||
premake.modules.lua = {}
|
||||
local m = premake.modules.lua
|
||||
|
||||
local p = premake
|
||||
|
||||
newaction {
|
||||
trigger = "lua",
|
||||
description = "Export project information as Lua",
|
||||
|
||||
onStart = function ()
|
||||
p.escaper(m.esc)
|
||||
end,
|
||||
|
||||
onWorkspace = function(wks)
|
||||
p.generate(wks, ".wks.lua", m.generateWorkspace)
|
||||
end,
|
||||
|
||||
onProject = function(prj)
|
||||
p.generate(prj, ".prj.lua", m.generateProject)
|
||||
end,
|
||||
}
|
||||
|
||||
|
||||
function m.generateWorkspace(wks)
|
||||
p.push('workspace = {')
|
||||
p.x('name = "%s",', wks.name)
|
||||
|
||||
p.push('projects = {')
|
||||
p.pop('},')
|
||||
|
||||
p.pop('}')
|
||||
end
|
||||
|
||||
|
||||
function m.generateProject(prj)
|
||||
p.push('project = {')
|
||||
p.x('name = "%s",', prj.name)
|
||||
p.w('uuid = "%s",', prj.uuid)
|
||||
p.w('kind = "%s"', prj.kind)
|
||||
p.pop('}')
|
||||
end
|
||||
|
||||
|
||||
function m.esc(value)
|
||||
value = value:gsub('\\', '\\\\')
|
||||
value = value:gsub('"', '\\"')
|
||||
return value
|
||||
end
|
||||
|
||||
|
||||
return m
|
||||
```
|
||||
@ -4,10 +4,8 @@ title: Getting Help
|
||||
|
||||
For questions about **using Premake** and **authoring project scripts,** please [ask on StackOverflow, adding the #premake tag to your question](http://stackoverflow.com/questions/tagged/premake). More people (including the Premake developers) will be able to see and respond to your questions, and you will have the opportunity to reward the best answers.
|
||||
|
||||
For discussions about **developing, customizing, or extending Premake and add-on modules**, please use the [Premake Developers Google Groups forum](https://groups.google.com/forum/#!forum/premake-development).
|
||||
|
||||
If you found a bug or would like to request a feature, you can open a ticket in [the issue tracker on GitHub](https://github.com/premake/premake-core/issues) (for Premake 5.x; the Premake 4.x issue tracker is [over here](https://github.com/premake/premake-4.x/issues)).
|
||||
|
||||
### Frequently Asked Questions ###
|
||||
|
||||
* [How do I reuse configuration settings between different projects?](Sharing-Configuration-Settings.md)
|
||||
* [How do I reuse configuration settings between different projects?](sharing-configuration-settings)
|
||||
|
||||
@ -2,6 +2,6 @@
|
||||
title: Getting Premake
|
||||
---
|
||||
|
||||
Visit [the Downloads page](http://premake.github.io/download.html) for the latest pre-built binary and source packages. Or, clone the premake-core Git repository right here on GitHub: find the "Clone" option in the sidebar to the right and follow the instructions there, then see [Building Premake](Building-Premake.md) to learn how to create binaries for your system.
|
||||
Visit [the Downloads page](http://premake.github.io/download.html) for the latest pre-built binary and source packages. Or, clone the premake-core Git repository right here on GitHub: find the "Clone" option in the sidebar to the right and follow the instructions there, then see [Building Premake](building-premake) to learn how to create binaries for your system.
|
||||
|
||||
Premake 5.0 is still in very active development, and we haven't yet reached the point of making official releases yet (though we're getting close). There will absolutely be bugs and [missing functionality](Feature-Matrix.md) right now. Please help us by [reporting issues you find](https://github.com/premake/premake-core/issues) so we can get them fixed before the final release.
|
||||
Premake 5.0 is still in very active development, and we haven't yet reached the point of making official releases yet (though we're getting close). There will absolutely be bugs and [missing functionality](feature-matrix) right now. Please help us by [reporting issues you find](https://github.com/premake/premake-core/issues) so we can get them fixed before the final release.
|
||||
|
||||
@ -3,7 +3,7 @@ title: Home
|
||||
slug: /
|
||||
---
|
||||
|
||||
Welcome to the **Premake 5 User Guide** !
|
||||
Welcome to the **Premake 5 User Guide**!
|
||||
|
||||
## Getting Started ##
|
||||
|
||||
@ -13,7 +13,6 @@ Welcome to the **Premake 5 User Guide** !
|
||||
* [Building Premake](Building-Premake.md)
|
||||
* [Getting Help](Getting-Help.md)
|
||||
* [Who Uses Premake?](Who-Uses-Premake.md)
|
||||
* [About This Wiki](About-This-Wiki.md)
|
||||
|
||||
## Writing Premake Scripts ##
|
||||
|
||||
@ -27,7 +26,6 @@ Welcome to the **Premake 5 User Guide** !
|
||||
* [Build Settings](Build-Settings.md)
|
||||
* [Command Line Arguments](Command-Line-Arguments.md)
|
||||
* [Using Modules](Using-Modules.md)
|
||||
* [Tutorials](Tutorials.md)
|
||||
* [More Topics…](Topics.md)
|
||||
|
||||
## Extending Premake ##
|
||||
@ -37,8 +35,7 @@ Welcome to the **Premake 5 User Guide** !
|
||||
* [Coding Conventions](Coding-Conventions.md)
|
||||
* [Overrides and Call Arrays](Overrides-and-Call-Arrays.md)
|
||||
* [Developing Modules](Developing-Modules.md)
|
||||
* [Adding a New Action](Adding-a-new-Action.md)
|
||||
* Adding a New Toolset
|
||||
* [Adding a New Action](Adding-New-Action.md)
|
||||
|
||||
## Premake Reference ##
|
||||
|
||||
@ -46,11 +43,11 @@ Welcome to the **Premake 5 User Guide** !
|
||||
* [Lua Library Additions](Lua-Library-Additions.md)
|
||||
* [Available Modules](Modules.md)
|
||||
* [Supported Feature Matrix](Feature-Matrix.md)
|
||||
* [What's New in 5.0](What's-New-in-5.0.md)
|
||||
* [What's New in 5.0](Whats-New-in-5.0.md)
|
||||
* [Migrating From 4.x](Migrating-From-4.x.md)
|
||||
|
||||
## Contributing to Premake ##
|
||||
|
||||
* [How You Can Help](How-To-Help.md)
|
||||
* [How You Can Help](How-to-Help.md)
|
||||
* [Development Roadmap](Development-Roadmap.md)
|
||||
* [How To Submit Changes](Contribution-Guidelines.md)
|
||||
* [How To Submit Changes](https://github.com/premake/premake-core/blob/master/CONTRIBUTING.md)
|
||||
|
||||
13
website/docs/How-to-Help.md
Normal file
13
website/docs/How-to-Help.md
Normal file
@ -0,0 +1,13 @@
|
||||
---
|
||||
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).
|
||||
|
||||
Here are some other ways you can help:
|
||||
|
||||
* Review and try out incoming [pull requests](https://github.com/premake/premake-core/pulls)
|
||||
|
||||
* Review and fix [issues](https://github.com/premake/premake-core/issues)
|
||||
|
||||
* Help create a New Contributor's Guide (like [this](http://drupal.org/contribute) and [this](http://www.ogre3d.org/developers))
|
||||
91
website/docs/Introducing-Modules.md
Normal file
91
website/docs/Introducing-Modules.md
Normal file
@ -0,0 +1,91 @@
|
||||
---
|
||||
title: Introducing Modules
|
||||
---
|
||||
|
||||
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 script should be placed in a folder of the same name
|
||||
* the folder should be placed [somewhere Premake can find it](locating-scripts)
|
||||
|
||||
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:
|
||||
|
||||
```lua
|
||||
-- lucky.lua
|
||||
-- My lucky Premake module
|
||||
|
||||
-- Start by defining a table to hold the interface to my module. By
|
||||
-- convention we call this "m".
|
||||
|
||||
local m = {}
|
||||
|
||||
-- Print out a message to show that our module has loaded.
|
||||
|
||||
print("The lucky module has loaded!")
|
||||
|
||||
-- Finish by returning my module's interface
|
||||
|
||||
return m
|
||||
```
|
||||
|
||||
To use our new module, we just need to require it in any of our project scripts, something like this:
|
||||
|
||||
```lua
|
||||
require "lucky"
|
||||
|
||||
workspace "MyWorkspace"
|
||||
configurations { "Debug", "Release" }
|
||||
|
||||
project "MyProject"
|
||||
-- and so on...
|
||||
```
|
||||
|
||||
When we generate this project, we should see our message displayed in the output:
|
||||
|
||||
```
|
||||
$ premake5 vs2012
|
||||
The lucky module has loaded!
|
||||
Building configurations...
|
||||
Running action 'vs2010'...
|
||||
Generating MyWorkspace.sln...
|
||||
Generating MyProject.vcxproj...
|
||||
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.
|
||||
|
||||
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()`.
|
||||
|
||||
Here is an example of a public function which accesses a private variable:
|
||||
|
||||
```lua
|
||||
-- lucky.lua
|
||||
-- My lucky Premake module
|
||||
|
||||
local m = {}
|
||||
|
||||
-- This variable is private and won't be accessible elsewhere
|
||||
|
||||
local secretLuckyNumber = 7
|
||||
|
||||
-- This function is public, and can be called via the interface
|
||||
|
||||
function m.makeNumberLucky(number)
|
||||
return number * secretLuckyNumber
|
||||
end
|
||||
|
||||
return m
|
||||
```
|
||||
|
||||
You could then use this module's functions in your project scripts like so:
|
||||
|
||||
|
||||
```lua
|
||||
local lucky = require "lucky"
|
||||
local luckyEight = lucky.makeNumberLucky(8)
|
||||
```
|
||||
|
||||
That's all there to it!
|
||||
|
||||
Note that if you decide you want to [share your module](modules) with other people, there are a [few other considerations to make](sharing-your-module).
|
||||
|
||||
42
website/docs/Linking.md
Normal file
42
website/docs/Linking.md
Normal file
@ -0,0 +1,42 @@
|
||||
---
|
||||
title: Linking
|
||||
---
|
||||
|
||||
Linking to external libraries is done with the [`links`](links) function.
|
||||
|
||||
```lua
|
||||
links { "png", "zlib" }
|
||||
```
|
||||
|
||||
When specifying libraries, system-specific decorations, such as prefixes or file extensions, should be omitted. Premake will synthesize the correct format based on the target platform automatically. The one exception to the rule is Mac OS X frameworks, where the file extension is required to identify it as such.
|
||||
|
||||
```lua
|
||||
links { "Cocoa.framework" }
|
||||
```
|
||||
|
||||
To link to a sibling project (a project in the same workspace) use the **project name**. Premake will deduce the correct library path and name based on the current platform and configuration.
|
||||
|
||||
```lua
|
||||
workspace "MyWorkspace"
|
||||
|
||||
project "MyLibraryProject"
|
||||
-- ...project settings here...
|
||||
|
||||
project "MyExecutableProject"
|
||||
-- ...project settings here...
|
||||
links { "MyLibraryProject" }
|
||||
```
|
||||
|
||||
### Finding Libraries ###
|
||||
|
||||
You can tell Premake where to search for libraries with the [`libdirs`](libdirs) function.
|
||||
|
||||
```lua
|
||||
libdirs { "libs", "../mylibs" }
|
||||
```
|
||||
|
||||
If you need to discover the location of a library, use the [`os.findlib`](os.findlib) function.
|
||||
|
||||
```lua
|
||||
libdirs { os.findlib("X11") }
|
||||
```
|
||||
25
website/docs/Locating-Scripts.md
Normal file
25
website/docs/Locating-Scripts.md
Normal file
@ -0,0 +1,25 @@
|
||||
---
|
||||
title: Locating Scripts
|
||||
---
|
||||
|
||||
When Premake needs to load a script file, via a call to `dofile()` or `include()`, or a module via a call to `require()`, it uses the `premake.path` variable to locate it. This is a semicolon-delimited string which, by default, includes the following locations, in the specified order:
|
||||
|
||||
* Relative to the currently executing script
|
||||
|
||||
* On the path specified by the `--scripts` command line argument
|
||||
|
||||
* On the paths listed in the `PREMAKE_PATH` environment variable
|
||||
|
||||
* In the `~/.premake` directory
|
||||
|
||||
* In the `~/Library/Application Support/Premake` directory (Mac OS X only)
|
||||
|
||||
* In the `/usr/local/share/premake` directory
|
||||
|
||||
* In the `/usr/share/premake` directory
|
||||
|
||||
* 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).
|
||||
|
||||
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.
|
||||
136
website/docs/Lua-Library-Additions.md
Normal file
136
website/docs/Lua-Library-Additions.md
Normal file
@ -0,0 +1,136 @@
|
||||
### Globals
|
||||
|
||||
* [dofileopt](dofileopt)
|
||||
* [include](include)
|
||||
* [includeexternal](includeexternal)
|
||||
* [require](require)
|
||||
|
||||
### Debugging
|
||||
|
||||
* [debug.prompt](debug.prompt)
|
||||
|
||||
### HTTP/S
|
||||
|
||||
* [http.download](http.download)
|
||||
* [http.get](http.get)
|
||||
* [http.post](http.post)
|
||||
|
||||
### I/O
|
||||
|
||||
* [io.readfile](io.readfile)
|
||||
* [io.writefile](io.writefile)
|
||||
|
||||
### JSON
|
||||
|
||||
* [json.decode](json.decode)
|
||||
* [json.encode](json.encode)
|
||||
|
||||
### OS
|
||||
|
||||
* [os.chdir](os.chdir)
|
||||
* [os.chmod](os.chmod)
|
||||
* [os.comparefiles](os.comparefiles)
|
||||
* [os.copyfile](os.copyfile)
|
||||
* [os.executef](os.executef)
|
||||
* [os.findheader](os.findheader)
|
||||
* [os.findlib](os.findlib)
|
||||
* [os.get](os.get)
|
||||
* [os.getcwd](os.getcwd)
|
||||
* [os.getpass](os.getpass)
|
||||
* [os.getversion](os.getversion)
|
||||
* [os.host](os.host)
|
||||
* [os.is](os.is)
|
||||
* [os.is64bit](os.is64bit)
|
||||
* [os.isdir](os.isdir)
|
||||
* [os.isfile](os.isfile)
|
||||
* [os.islink](os.islink)
|
||||
* [os.locate](os.locate)
|
||||
* [os.matchdirs](os.matchdirs)
|
||||
* [os.matchfiles](os.matchfiles)
|
||||
* [os.mkdir](os.mkdir)
|
||||
* [os.outputof](os.outputof)
|
||||
* [os.pathsearch](os.pathsearch)
|
||||
* [os.realpath](os.realpath)
|
||||
* [os.remove](os.remove)
|
||||
* [os.rmdir](os.rmdir)
|
||||
* [os.stat](os.stat)
|
||||
* [os.target](os.target)
|
||||
* [os.touchfile](os.touchfile)
|
||||
* [os.translateCommands](os.translateCommands)
|
||||
* [os.uuid](os.uuid)
|
||||
* [os.writefile_ifnotequal](os.writefile_ifnotequal)
|
||||
|
||||
### Path
|
||||
|
||||
* [path.appendextension](path.appendextension)
|
||||
* [path.appendExtension](path.appendExtension)
|
||||
* [path.getabsolute](path.getabsolute)
|
||||
* [path.getbasename](path.getbasename)
|
||||
* [path.getdirectory](path.getdirectory)
|
||||
* [path.getdrive](path.getdrive)
|
||||
* [path.getextension](path.getextension)
|
||||
* [path.getname](path.getname)
|
||||
* [path.getrelative](path.getrelative)
|
||||
* [path.hasextension](path.hasextension)
|
||||
* [path.isabsolute](path.isabsolute)
|
||||
* [path.iscfile](path.iscfile)
|
||||
* [path.iscppfile](path.iscppfile)
|
||||
* [path.iscppheader](path.iscppheader)
|
||||
* [path.isframework](path.isframework)
|
||||
* [path.islinkable](path.islinkable)
|
||||
* [path.isobjectfile](path.isobjectfile)
|
||||
* [path.isresourcefile](path.isresourcefile)
|
||||
* [path.join](path.join)
|
||||
* [path.normalize](path.normalize)
|
||||
* [path.rebase](path.rebase)
|
||||
* [path.replaceextension](path.replaceextension)
|
||||
* [path.translate](path.translate)
|
||||
* [path.wildcards](path.wildcards)
|
||||
|
||||
### String
|
||||
|
||||
* [string.capitalized](string.capitalized)
|
||||
* [string.contains](string.contains)
|
||||
* [string.endswith](string.endswith)
|
||||
* [string.escapepattern](string.escapepattern)
|
||||
* [string.explode](string.explode)
|
||||
* [string.findlast](string.findlast)
|
||||
* [string.hash](string.hash)
|
||||
* [string.lines](string.lines)
|
||||
* [string.plural](string.plural)
|
||||
* [string.sha1](string.sha1)
|
||||
* [string.startswith](string.startswith)
|
||||
|
||||
### Table
|
||||
|
||||
* [table.arraycopy](table.arraycopy)
|
||||
* [table.contains](table.contains)
|
||||
* [table.deepcopy](table.deepcopy)
|
||||
* [table.extract](table.extract)
|
||||
* [table.filterempty](table.filterempty)
|
||||
* [table.flatten](table.flatten)
|
||||
* [table.fold](table.fold)
|
||||
* [table.foreachi](table.foreachi)
|
||||
* [table.implode](table.implode)
|
||||
* [table.indexof](table.indexof)
|
||||
* [table.insertafter](table.insertafter)
|
||||
* [table.insertflat](table.insertflat)
|
||||
* [table.isempty](table.isempty)
|
||||
* [table.join](table.join)
|
||||
* [table.keys](table.keys)
|
||||
* [table.merge](table.merge)
|
||||
* [table.replace](table.replace)
|
||||
* [table.tostring](table.tostring)
|
||||
* [table.translate](table.translate)
|
||||
|
||||
### Term
|
||||
|
||||
* [term.getTextColor](term.getTextColor)
|
||||
* [term.setTextColor](term.setTextColor)
|
||||
* [term.pushColor](term.pushColor)
|
||||
* [term.popColor](term.popColor)
|
||||
|
||||
### Zip
|
||||
|
||||
* [zip.extract](zip.extract)
|
||||
|
||||
58
website/docs/Makefile-Projects.md
Normal file
58
website/docs/Makefile-Projects.md
Normal file
@ -0,0 +1,58 @@
|
||||
---
|
||||
title: Makefile Projects
|
||||
---
|
||||
|
||||
Makefile projects give you the ability to completely specify the build and clean commands for a project, and are useful when you would like to shell out to an existing Makefile or other command line process.
|
||||
|
||||
## Example Usage
|
||||
|
||||
```lua
|
||||
workspace "MyWorkspace"
|
||||
configurations { "Debug", "Release" }
|
||||
|
||||
project "MyProject"
|
||||
kind "Makefile"
|
||||
|
||||
buildcommands {
|
||||
"make %{cfg.buildcfg}"
|
||||
}
|
||||
|
||||
rebuildcommands {
|
||||
"make %{cfg.buildcfg} rebuild"
|
||||
}
|
||||
|
||||
cleancommands {
|
||||
"make clean %{cfg.buildcfg}"
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
This closely follows Visual Studio's own Makefile project feature, 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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
## Current Issues
|
||||
|
||||
Makefile projects currently have a few shortcomings. Help fixing these issues, or any other gaps, would be most appreciated!
|
||||
|
||||
* The feature only works for Visual Studio currently.
|
||||
|
||||
* There is limited detection of paths in the build commands. Tokens that
|
||||
expand to absolute paths (most of them do, i.e. %{cfg.objdir}) are properly
|
||||
made project relative. Custom tokens, or paths hardcoded inline with the
|
||||
commands, must be specified relative to the generated project location.
|
||||
|
||||
(Did I miss anything?)
|
||||
|
||||
|
||||
## See Also ##
|
||||
|
||||
* [Custom Build Commands](custom-build-commands)
|
||||
* [Custom Rules](custom-rules)
|
||||
* [buildcommands](buildcommands)
|
||||
* [buildoutputs](buildoutputs)
|
||||
* [cleancommands](cleancommands)
|
||||
* [rebuildcommands](rebuildcommands)
|
||||
24
website/docs/Migrating-From-4.x.md
Normal file
24
website/docs/Migrating-From-4.x.md
Normal file
@ -0,0 +1,24 @@
|
||||
---
|
||||
title: Migrating from Premake 4.x
|
||||
---
|
||||
|
||||
# Function name changes
|
||||
|
||||
The function [`workspace`](workspace) 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.
|
||||
|
||||
# Flag changes
|
||||
|
||||
Many of the old [`flags`](flags) have become full-fledged functions. This should be a comprehensive list of such changes.
|
||||
|
||||
| Old flags | New Function |
|
||||
| --------- | ------------ |
|
||||
| `EnableSSE`, `EnableSSE2` | [`vectorextensions`](vectorextensions) |
|
||||
| `ExtraWarnings`, `NoWarnings` | [`warnings`](warnings) |
|
||||
| `FloatFast`, `FloatStrict` | [`floatingpoint`](floatingpoint) |
|
||||
| `Managed`, `Unsafe` | [`clr`](clr) |
|
||||
| `NativeWChar` | [`nativewchar`](nativewchar) |
|
||||
| `NoEditAndContinue` | [`editandcontinue`](editandcontinue) |
|
||||
| `NoRTTI` | [`rtti`](rtti) |
|
||||
| `OptimizeSize`, `OptimizeSpeed` | [`optimize`](optimize) |
|
||||
60
website/docs/Modules.md
Normal file
60
website/docs/Modules.md
Normal file
@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Modules
|
||||
---
|
||||
|
||||
## Built-In Modules ##
|
||||
|
||||
These modules are shipped as part of Premake, and may be used out of the box with any source or binary package.
|
||||
|
||||
* [Android](https://github.com/premake/premake-core/tree/master/modules/android) : Android support
|
||||
* [CodeLite](https://github.com/premake/premake-core/tree/master/modules/codelite) : [CodeLite](http://www.codelite.org) support
|
||||
* [D](https://github.com/premake/premake-core/tree/master/modules/d) : [D](http://dlang.org) programming language support
|
||||
* [gmake](https://github.com/premake/premake-core/tree/master/modules/gmake) : Makefile generator (deprecated by gmake2)
|
||||
* [gmake2](https://github.com/premake/premake-core/tree/master/modules/gmake2) : Makefile generator
|
||||
* [Raw](https://github.com/premake/premake-core/tree/master/modules/raw) : Generate raw representation of Premake structures
|
||||
* [Visual Studio](https://github.com/premake/premake-core/tree/master/modules/vstudio) : Visual Studio (2005 - 2019) support
|
||||
* [XCode](https://github.com/premake/premake-core/tree/master/modules/xcode) : XCode support
|
||||
|
||||
## Third-Party Modules ##
|
||||
|
||||
These add-on modules are available from other developers; follow the links for more information. If you've developed a module you would like to share with others, feel free to add a link to the list!
|
||||
|
||||
### IDE Modules ###
|
||||
|
||||
* [Android Studio](https://github.com/polymonster/premake-android-studio) : Generate .gradle and CMakeLists for Android Studio
|
||||
* [Code::Blocks](https://github.com/chris-be/premake-codeblocks) : [Code::Blocks](http://www.codeblocks.org/) support
|
||||
* [Eclipse](https://github.com/premake/premake-eclipse) : [Eclipse](http://www.eclipse.org) support
|
||||
* [NetBeans](https://github.com/TurkeyMan/premake-netbeans) : [NetBeans](https://netbeans.org) support
|
||||
* [SlickEdit](https://github.com/TurkeyMan/premake-slickedit) : [SlickEdit](http://www.slickedit.com) support
|
||||
* [qmake](https://github.com/Gaztin/premake-qmake) : [QtCreator](https://doc.qt.io/qtcreator/creator-overview.html) and [qmake](http://doc.qt.io/qt-5/qmake-manual.html) support
|
||||
|
||||
### Platform Modules ###
|
||||
|
||||
* [Android.mk](https://github.com/Meoo/premake-androidmk) : Generator for Android NDK's [ndk-build system](https://developer.android.com/ndk/guides/build.html)
|
||||
* [Emscripten](https://github.com/TurkeyMan/premake-emscripten) : [Emscripten](http://kripken.github.io/emscripten-site/) support
|
||||
* [NaCL](https://github.com/TurkeyMan/premake-nacl) : [Google Native Client](https://developer.chrome.com/native-client) support
|
||||
* [VSLinux](https://github.com/LORgames/premake-vslinux) : [VSLinux](https://visualstudiogallery.msdn.microsoft.com/725025cf-7067-45c2-8d01-1e0fd359ae6e) support
|
||||
* [VS-Tool](https://github.com/TurkeyMan/premake-vstool) : GCC and Clang toolset Visual Studio support via [vs-tool](https://github.com/juj/vs-tool)
|
||||
* [WinRT](https://github.com/LORgames/premake-winrt) : Windows Runtime support
|
||||
* [Xbox 360](https://github.com/redorav/premake-xbox360) : Xbox 360 support
|
||||
|
||||
### Build System Modules ###
|
||||
|
||||
* [CMake](https://github.com/Geequlim/premake-modules/tree/master/cmake) : CMakeLists exporter for premake
|
||||
* [Ninja](https://github.com/jimon/premake-ninja) : [Ninja](https://github.com/martine/ninja) support
|
||||
|
||||
### Tool Modules ###
|
||||
|
||||
* [Autoconf](https://github.com/Blizzard/premake-autoconf) : Autoconf tools for premake
|
||||
* [CompilationUnit](https://github.com/dcourtois/premake-compilationunit) : [Single compilation unit](https://en.wikipedia.org/wiki/Single_Compilation_Unit) support
|
||||
* [Export](https://github.com/Meoo/premake-export) : premake usage/export module
|
||||
* [Generate compile_commands.json](https://github.com/tarruda/premake-export-compile-commands) : Export clang compilation database
|
||||
* [GitHub Packages](https://github.com/mversluys/premake-ghp) : Consume libraries directly from GitHub releases
|
||||
* [Pkgconfig](https://github.com/tarruda/premake-pkgconfig) : Pure lua implementation of pkgconfig for premake
|
||||
* [Pkgconfig](https://github.com/Geequlim/premake-modules/tree/master/pkgconfig) : pkg-config loader for premake
|
||||
* [Platform test](https://github.com/tarruda/premake-platform-test) : Perform platform checks in your premake configuration
|
||||
|
||||
### Library Modules ###
|
||||
|
||||
* [Qt](https://github.com/dcourtois/premake-qt) : [Qt](https://www.qt.io) support
|
||||
* [WIX](https://github.com/mikisch81/premake-wix) : Premake extension to support [WIX](http://wixtoolset.org/) project files on Visual Studio
|
||||
149
website/docs/Overrides-and-Call-Arrays.md
Normal file
149
website/docs/Overrides-and-Call-Arrays.md
Normal file
@ -0,0 +1,149 @@
|
||||
---
|
||||
title: Overrides & Call Arrays
|
||||
---
|
||||
|
||||
Premake's extensibility is built around two coding conventions: *overrides*, a formalized way of replacing one function with another, and *call arrays*, a way of sequencing a series of steps at runtime.
|
||||
|
||||
## Your First Customization
|
||||
|
||||
Let's jump right in with a simple example. Let's say that we're planning to keep our Premake-generated Visual Studio projects around for a while and, for historical reference, we'd like to know which version of Premake was used to generate them. To do so, we would like to add an XML comment to the top of the generated project files, like so:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- Generated by Premake 5.0.0-alpha3 -->
|
||||
<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
|
||||
<ItemGroup Label="ProjectConfigurations">
|
||||
<!-- ... and so on... -->
|
||||
```
|
||||
|
||||
We don't want to modify Premake's own source code, because then our changes would be overwritten by each new update, and we'd be stuck maintaining our own fork of the code. It would also mean that everyone who generated our projects would need to have the customized version of Premake, otherwise we'd end up with generated projects that did not contain our version commment.
|
||||
|
||||
Instead, we'd really like to implement this customization right in our project scripts. That way we can share the scripts with any developer, and they can then generate a new project that has the version comment in it.
|
||||
|
||||
|
||||
## 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!).
|
||||
|
||||
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:
|
||||
|
||||
|
||||
```lua
|
||||
function m.project(prj)
|
||||
local action = premake.action.current()
|
||||
p.push('<Project DefaultTargets="Build" ToolsVersion="%s" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">',
|
||||
action.vstudio.toolsVersion)
|
||||
end
|
||||
```
|
||||
|
||||
(Or, if you are using a tool which supports it, it can be quicker to just run a full text search across the Premake sources for the markup you are looking to override.)
|
||||
|
||||
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:
|
||||
|
||||
```lua
|
||||
local p = premake
|
||||
local m = p.vstudio.vc2010
|
||||
```
|
||||
|
||||
Expanding that out, we can deduce that the fully-qualified name of the function we want to override is `premake.vstudio.vc2010.project()`.
|
||||
|
||||
|
||||
## Introducing Overrides
|
||||
|
||||
Now that we've identified the function that emits the markup we wish to change, we can override it using Premake's aptly named `override()` function.
|
||||
|
||||
Note that actions don't get pulled in until they are actually used so you will need to require it in order to access it
|
||||
|
||||
```lua
|
||||
require('vstudio')
|
||||
```
|
||||
|
||||
Then (and only then) you can go ahead and call the override function !
|
||||
|
||||
```lua
|
||||
premake.override(premake.vstudio.vc2010, "project", function(base, prj)
|
||||
premake.w('<!-- Generated by Premake ' .. _PREMAKE_VERSION .. ' -->')
|
||||
base(prj)
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
After emitting the comment we call `base(prj)`, the original implementation of `m.project()`, to do the rest of the work for us. Easy!
|
||||
|
||||
To enable our override, place that code anywhere in your project or system scripts. Perhaps something like:
|
||||
|
||||
```lua
|
||||
workspace "MyWorkspace"
|
||||
configurations { "Debug", "Release" }
|
||||
|
||||
project "MyProject"
|
||||
kind "ConsoleApp"
|
||||
-- ... the rest of the project settings...
|
||||
|
||||
-- Write the current Premake version into our generated files, for reference
|
||||
premake.override(premake.vstudio.vc2010, "project", function(base, prj)
|
||||
premake.w('<!-- Generated by Premake ' .. _PREMAKE_VERSION .. ' -->')
|
||||
base(prj)
|
||||
end)
|
||||
```
|
||||
|
||||
The next time you generate a Visual Studio project from your scripts, the comment header will be placed before the Project element.
|
||||
|
||||
## 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).
|
||||
|
||||
If you look at the top of `vs2010_vcxproj.lua`, you will see that `m.project()` is called via an array of function references:
|
||||
|
||||
```lua
|
||||
m.elements.project = function(prj)
|
||||
return {
|
||||
m.xmlDeclaration,
|
||||
m.project,
|
||||
m.projectConfigurations,
|
||||
m.globals,
|
||||
m.importDefaultProps,
|
||||
m.configurationPropertiesGroup,
|
||||
m.importExtensionSettings,
|
||||
m.propertySheetGroup,
|
||||
m.userMacros,
|
||||
m.outputPropertiesGroup,
|
||||
m.itemDefinitionGroups,
|
||||
m.assemblyReferences,
|
||||
m.files,
|
||||
m.projectReferences,
|
||||
m.importExtensionTargets,
|
||||
}
|
||||
end
|
||||
|
||||
function m.generate(prj)
|
||||
io.utf8()
|
||||
p.callArray(m.elements.project, prj)
|
||||
p.out('</Project>')
|
||||
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.
|
||||
|
||||
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()`.
|
||||
|
||||
```lua
|
||||
local function premakeVersionComment(prj)
|
||||
premake.w('<!-- Generated by Premake ' .. _PREMAKE_VERSION .. ' -->')
|
||||
end
|
||||
|
||||
premake.override(premake.vstudio.vc2010.elements, "project", function(base, prj)
|
||||
local calls = base(prj)
|
||||
table.insertafter(calls, m.xmlDeclaration, premakeVersionComment)
|
||||
return calls
|
||||
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.
|
||||
|
||||
*(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.)*
|
||||
115
website/docs/Precompiled-Headers.md
Normal file
115
website/docs/Precompiled-Headers.md
Normal file
@ -0,0 +1,115 @@
|
||||
---
|
||||
title: Precompiled Headers
|
||||
---
|
||||
|
||||
Due to differences between how the different toolsets handle precompiled headers, this subject is far more complex than it needs to be.
|
||||
|
||||
Visual Studio requires two pieces of information in order to enable precompiled headers: the *header file* to be precompiled, and a *source file* to trigger and control the compilation. In a default, out-of-the-box Visual Studio generated C++ project, these are called *stdafx.h* and *stdafx.cpp* respectively. You can set these in Premake like so:
|
||||
|
||||
```lua
|
||||
pchheader "stdafx.h"
|
||||
pchsource "stdafx.cpp"
|
||||
```
|
||||
|
||||
Every other toolset (so far anyway) requires only the header file.
|
||||
|
||||
The PCH source file is just a regular old source code file containing a single line: an include statement that pulls in the header to be precompiled:
|
||||
|
||||
```c
|
||||
#include "stdafx.h"
|
||||
```
|
||||
|
||||
Nothing special, but you must have this file in order for precompiled headers to work in Visual Studio. You may call this file whatever you want, and put it wherever you want in your source tree. Like any other file, the path to the precompiled header source file should be set relative to the project script, and is automatically made relative to the generated project file. Non-Visual Studio toolsets will ignore the `pchsource` value, so it's safe to set it unconditionally.
|
||||
|
||||
Setting the header file, on the other hand, get a bit more complicated.
|
||||
|
||||
## Setting the Header File
|
||||
|
||||
When setting the precompiled header file, you don't provide the path to the file as you might expect. Rather, you specify how the include will appear in the source code. Most of the time your header is located at the root level of your project source tree, in the same folder as the project file, and you include it like this:
|
||||
|
||||
```c
|
||||
#include "stdafx.h"
|
||||
```
|
||||
|
||||
In this case, your precompiled header should be set to "stdafx.h". Simple enough. In your Premake script, you would set:
|
||||
|
||||
```lua
|
||||
pchheader "stdafx.h"
|
||||
```
|
||||
|
||||
What if you have source code that is nested in a subfolder, such as `./utils/myhelper.cpp`? Normally, you'd want to modify your include statement in that case to reference the header file that is at the project root, one level above you:
|
||||
|
||||
```c
|
||||
#include "../stdafx.h"
|
||||
```
|
||||
|
||||
But Visual Studio will give you an error, claiming that the precompiled header could not be found. It is, all all files of the project, looking for an exact match to the precompiled header string "stdafx.h". If your source code is nested in multiple levels of folders, they must all include the precompiled header using the same string, with the folder containing the header listed in the include file search paths. In Premake-speak, you must do:
|
||||
|
||||
```lua
|
||||
pchheader "stdafx.h"
|
||||
includedirs { "." } -- assuming the project file will be in this directory
|
||||
```
|
||||
|
||||
And all of your source code files must include the header as:
|
||||
|
||||
```c
|
||||
#include "stdafx.h"
|
||||
```
|
||||
|
||||
If you actually do want to include a path in the include statement, you must match it exactly in your Premake script.
|
||||
|
||||
```c
|
||||
#include "include/stdafx.h"
|
||||
```
|
||||
```lua
|
||||
pchheader "include/stdafx.h"
|
||||
```
|
||||
|
||||
If you need more information, or a more step-by-step explanation, here is [a good article on CodeProject](http://www.codeproject.com/Articles/320056/Projects-in-Visual-Cplusplus-2010-Part-3-Precompil) that covers the process of setting up precompiled headers for Visual Studio.
|
||||
|
||||
Note: When specifying `pchsource` make sure to include the path to the `pchsource` file just like you would for your regular source files. Otherwise Visual Studio will not build the ***.pch** file. An example is provided where src_dir is the path to your source code.
|
||||
|
||||
```lua
|
||||
pchsource(src_dir.."stdafx.cpp")
|
||||
files{src_dir.."**.h", src_dir.."**.cpp"}
|
||||
```
|
||||
|
||||
## Considerations for Non-Visual Studio Tools
|
||||
|
||||
Premake does its best to make all of this just work transparently across all of its supported toolsets. For instance, if your header is located in a folder called `includes` and you set up your project like:
|
||||
|
||||
```lua
|
||||
pchheader "stdafx.h"
|
||||
includedirs { "includes" }
|
||||
```
|
||||
|
||||
...Premake is smart enough to check the include search paths to locate the header, and create required force include in your generated Makefiles.
|
||||
|
||||
```make
|
||||
FORCE_INCLUDE = -include includes/stdafx.h
|
||||
```
|
||||
|
||||
If, for whatever reason, you can't follow the Visual Studio convention on your other platforms, you can always nest the header description in the appropriate configuration blocks.
|
||||
|
||||
```lua
|
||||
filter "action:vs*" -- for Visual Studio actions
|
||||
pchheader "stdafx.h"
|
||||
pchsource "stdafx.cpp"
|
||||
|
||||
filter "action:not vs*" -- for everything else
|
||||
pchheader "includes/std.afx.h"
|
||||
```
|
||||
|
||||
For reference, here is the [Clang Compiler User's Manual section on precompiled headers](http://clang.llvm.org/docs/UsersManual.html#usersmanual-precompiled-headers).
|
||||
|
||||
## Summary
|
||||
|
||||
The important things to remember here are:
|
||||
|
||||
* If you want your code to build with precompiled headers in Visual Studio, your `#include` statement must be exactly the same in all source code files. Or you can use compiler option /FI (Name Forced Include File) https://docs.microsoft.com/en-us/cpp/build/reference/fi-name-forced-include-file?view=vs-2017
|
||||
|
||||
* When specifying the PCH header in your Premake script, the value provided should match the value in your source code's `#include` statements exactly.
|
||||
|
||||
* The value provided to `pchheader` is treated as a *string*, not a *path* and is not made relative to the generated project file. Rather is it passed through as-is.
|
||||
|
||||
* If you have multiple folder levels in your source code tree, you must add the folder containing the header to be precompiled to your include file search paths.
|
||||
194
website/docs/Project-API.md
Normal file
194
website/docs/Project-API.md
Normal file
@ -0,0 +1,194 @@
|
||||
### Core APIs ###
|
||||
|
||||
| API | Brief |
|
||||
|-----------------------------------------------------------|--------------------|
|
||||
| [_ACTION](_ACTION) | The action that will be run |
|
||||
| [_ARGS](_ARGS) | Array of action args |
|
||||
| [_MAIN_SCRIPT](_MAIN_SCRIPT) | |
|
||||
| [_MAIN_SCRIPT_DIR](_MAIN_SCRIPT_DIR) | |
|
||||
| [_OPTIONS](_OPTIONS) | |
|
||||
| [_OS](_OS) | The currently targeted operating system |
|
||||
| [_PREMAKE_COMMAND](_PREMAKE_COMMAND) | |
|
||||
| [_PREMAKE_DIR](_PREMAKE_DIR) | |
|
||||
| [_PREMAKE_VERSION](_PREMAKE_VERSION) | The version of the currently executing instance of Premake |
|
||||
| [_WORKING_DIR](_WORKING_DIR) | |
|
||||
| [architecture](architecture) | |
|
||||
| [atl](atl) | Use Microsoft's Active Template Library |
|
||||
| [basedir](basedir) | |
|
||||
| [bindirs](bindirs) | |
|
||||
| [buildaction](buildaction) | |
|
||||
| [buildcommands](buildcommands) | |
|
||||
| [buildcustomizations](buildcustomizations) | |
|
||||
| [builddependencies](builddependencies) | |
|
||||
| [buildinputs](buildinputs) | |
|
||||
| [buildlog](buildlog) | |
|
||||
| [buildmessage](buildmessage) | |
|
||||
| [buildoptions](buildoptions) | Additional build options (passed directly to compiler) |
|
||||
| [buildoutputs](buildoutputs) | |
|
||||
| [buildrule](buildrule) | |
|
||||
| [callingconvention](callingconvention) | Sets the function calling convention |
|
||||
| [cdialect](cdialect) | |
|
||||
| [characterset](characterset) | Set the character encoding |
|
||||
| [cleancommands](cleancommands) | |
|
||||
| [cleanextensions](cleanextensions) | |
|
||||
| [clr](clr) | Use Microsoft's Common Language Runtime |
|
||||
| [compileas](compileas) | |
|
||||
| [compilebuildoutputs](compilebuildoutputs) | |
|
||||
| [configfile](configfile) | |
|
||||
| [configmap](configmap) | |
|
||||
| [configuration](configuration) | |
|
||||
| [configurations](configurations) | |
|
||||
| [copylocal](copylocal) | |
|
||||
| [cppdialect](cppdialect) | |
|
||||
| [customtoolnamespace](customtoolnamespace) | |
|
||||
| [debugargs](debugargs) | |
|
||||
| [debugcommand](debugcommand) | |
|
||||
| [debugconnectcommands](debugconnectcommands) | Debugger commands to execute on remote target connection |
|
||||
| [debugconstants](debugconstants) | |
|
||||
| [debugdir](debugdir) | Working directory for debug session |
|
||||
| [debugenvs](debugenvs) | Env vars for debug session |
|
||||
| [debugextendedprotocol](debugextendedprotocol) | Use gdb 'extended' protocol; maintain a persistent connection |
|
||||
| [debugformat](debugformat) | Format for embedded debug information |
|
||||
| [debugger](debugger) | |
|
||||
| [debuggertype](debuggertype) | |
|
||||
| [debuglevel](debuglevel) | |
|
||||
| [debugpathmap](debugpathmap) | |
|
||||
| [debugport](debugport) | Port to use for remote debugging |
|
||||
| [debugremotehost](debugremotehost) | Target for remote debugging |
|
||||
| [debugsearchpaths](debugsearchpaths) | Search paths for source code while debugging |
|
||||
| [debugstartupcommands](debugstartupcommands) | Debugger commands to execute on debugger startup |
|
||||
| [debugtoolargs](debugtoolargs) | |
|
||||
| [debugtoolcommand](debugtoolcommand) | |
|
||||
| [defaultplatform](defaultplatform) | |
|
||||
| [defaultplatform](defaultplatform) | |
|
||||
| [defines](defines) | |
|
||||
| [dependson](dependson) | |
|
||||
| [deploymentoptions](deploymentoptions) | |
|
||||
| [disablewarnings](disablewarnings) | |
|
||||
| [display](display) | |
|
||||
| [display](display) | |
|
||||
| [docdir](docdir) | |
|
||||
| [docname](docname) | |
|
||||
| [editandcontinue](editandcontinue) | |
|
||||
| [editorintegration](editorintegration) | Enable or disable IDE integration |
|
||||
| [enablewarnings](enablewarnings) | |
|
||||
| [endian](endian) | |
|
||||
| [entrypoint](entrypoint) | Specify the program entry point function |
|
||||
| [exceptionhandling](exceptionhandling) | Enable or disable exception handling |
|
||||
| [external](external) | |
|
||||
| [externalRule](externalRule) | |
|
||||
| [fatalwarnings](fatalwarnings) | |
|
||||
| [fileextension](fileextension) | |
|
||||
| [filename](filename) | |
|
||||
| [files](files) | |
|
||||
| [filter](filter) | |
|
||||
| [flags](flags) | |
|
||||
| [floatingpoint](floatingpoint) | |
|
||||
| [floatingpointexceptions](floatingpointexceptions) | |
|
||||
| [forceincludes](forceincludes) | |
|
||||
| [forceusings](forceusings) | |
|
||||
| [fpu](fpu) | |
|
||||
| [framework](framework) | |
|
||||
| [functionlevellinking](functionlevellinking) | |
|
||||
| [gccprefix](gccprefix) | |
|
||||
| [group](group) | |
|
||||
| [headerdir](headerdir) | |
|
||||
| [headername](headername) | |
|
||||
| [icon](icon) | |
|
||||
| [ignoredefaultlibraries](ignoredefaultlibraries) | Specify a list of default libraries to ignore |
|
||||
| [imageoptions](imageoptions) | |
|
||||
| [imagepath](imagepath) | |
|
||||
| [implibdir](implibdir) | |
|
||||
| [implibextension](implibextension) | |
|
||||
| [implibname](implibname) | |
|
||||
| [implibprefix](implibprefix) | |
|
||||
| [implibsuffix](implibsuffix) | |
|
||||
| [include](include) | |
|
||||
| [includedirs](includedirs) | |
|
||||
| [includeexternal](includeexternal) | |
|
||||
| [inlining](inlining) | Tells the compiler when it should inline functions |
|
||||
| [intrinsics](intrinsics) | |
|
||||
| [kind](kind) | |
|
||||
| [language](language) | |
|
||||
| [largeaddressaware](largeaddressaware) | |
|
||||
| [libdirs](libdirs) | |
|
||||
| [linkbuildoutputs](linkbuildoutputs) | |
|
||||
| [linkgroups](linkgroups) | Turn on/off linkgroups for gcc/clang |
|
||||
| [linkoptions](linkoptions) | Additional linker options (passed directly to linker) |
|
||||
| [links](links) | |
|
||||
| [locale](locale) | |
|
||||
| [location](location) | Specifies the directory for the generated workspace/project file |
|
||||
| [makesettings](makesettings) | |
|
||||
| [namespace](namespace) | |
|
||||
| [nativewchar](nativewchar) | |
|
||||
| [nuget](nuget) | |
|
||||
| [nugetsource](nugetsource) | |
|
||||
| [objdir](objdir) | Output dir for object/intermediate files |
|
||||
| [optimize](optimize) | Optimization level |
|
||||
| [pchheader](pchheader) | Precompiled header file |
|
||||
| [pchsource](pchsource) | Precompiled header source file (which should build the PCH) |
|
||||
| [pic](pic) | Position independent code |
|
||||
| [platforms](platforms) | |
|
||||
| [postbuildcommands](postbuildcommands) | |
|
||||
| [postbuildmessage](postbuildmessage) | |
|
||||
| [prebuildcommands](prebuildcommands) | |
|
||||
| [prebuildmessage](prebuildmessage) | |
|
||||
| [preferredtoolarchitecture](preferredtoolarchitecture) | |
|
||||
| [prelinkcommands](prelinkcommands) | |
|
||||
| [prelinkmessage](prelinkmessage) | |
|
||||
| [project](project) | |
|
||||
| [propertydefinition](propertydefinition) | |
|
||||
| [rebuildcommands](rebuildcommands) | |
|
||||
| [resdefines](resdefines) | |
|
||||
| [resincludedirs](resincludedirs) | |
|
||||
| [resoptions](resoptions) | |
|
||||
| [resourcegenerator](resourcegenerator) | |
|
||||
| [rtti](rtti) | Enable or disable runtime type information |
|
||||
| [rule](rule) | |
|
||||
| [rules](rules) | |
|
||||
| [runtime](runtime) | |
|
||||
| [sharedlibtype](sharedlibtype) | |
|
||||
| [startproject](startproject) | |
|
||||
| [strictaliasing](strictaliasing) | |
|
||||
| [stringpooling](stringpooling) | |
|
||||
| [symbols](symbols) | Turn symbol generation on/off |
|
||||
| [symbolspath](symbolspath) | Allows you to specify the target location of the symbols |
|
||||
| [sysincludedirs](sysincludedirs) | |
|
||||
| [syslibdirs](syslibdirs) | |
|
||||
| [system](system) | |
|
||||
| [tags](tags) | |
|
||||
| [targetdir](targetdir) | |
|
||||
| [targetextension](targetextension) | |
|
||||
| [targetname](targetname) | |
|
||||
| [targetprefix](targetprefix) | |
|
||||
| [targetsuffix](targetsuffix) | |
|
||||
| [toolset](toolset) | |
|
||||
| [undefines](undefines) | |
|
||||
| [usingdirs](usingdirs) | |
|
||||
| [uuid](uuid) | Set project GUID (for VS projects/workspaces) |
|
||||
| [vectorextensions](vectorextensions) | Enable hardware vector extensions |
|
||||
| [versionconstants](versionconstants) | |
|
||||
| [versionlevel](versionlevel) | |
|
||||
| [vpaths](vpaths) | |
|
||||
| [warnings](warnings) | |
|
||||
| [workspace](workspace) | |
|
||||
|
||||
### Builtin Extension APIs ###
|
||||
|
||||
The following API reference is for use with various built-in extensions.
|
||||
|
||||
| D language APIs | Brief |
|
||||
|------------------------------------------------|--------------------|
|
||||
| [debugconstants](https://github.com/premake/premake-dlang/wiki/debugconstants) | Declare debug identifiers |
|
||||
| [debuglevel](https://github.com/premake/premake-dlang/wiki/debuglevel) | Declare debug level |
|
||||
| [docdir](https://github.com/premake/premake-dlang/wiki/docdir) | Output dir for ddoc generation |
|
||||
| [docname](https://github.com/premake/premake-dlang/wiki/docname) | Filename for the ddoc output |
|
||||
| [headerdir](https://github.com/premake/premake-dlang/wiki/headerdir) | Output dir for interface file generation |
|
||||
| [headername](https://github.com/premake/premake-dlang/wiki/headername) | Filename for the interface (.di) file |
|
||||
| [versionconstants](https://github.com/premake/premake-dlang/wiki/versionconstants) | Declare version identifiers |
|
||||
| [versionlevel](https://github.com/premake/premake-dlang/wiki/versionlevel) | Declare version level |
|
||||
|
||||
| Xcode APIs | Brief |
|
||||
|------------------------------------------------|--------------------|
|
||||
| [xcodebuildsettings](xcodebuildsettings) | |
|
||||
| [xcodebuildresources](xcodebuildresources) | |
|
||||
32
website/docs/Removing-Values.md
Normal file
32
website/docs/Removing-Values.md
Normal file
@ -0,0 +1,32 @@
|
||||
---
|
||||
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.
|
||||
|
||||
```lua
|
||||
remove... { "values_to_remove" }
|
||||
```
|
||||
|
||||
## Applies To ##
|
||||
|
||||
Project configurations.
|
||||
|
||||
## Parameters ##
|
||||
|
||||
One or more values to remove. If multiple values are specified, use the Lua table syntax.
|
||||
|
||||
## Examples ##
|
||||
|
||||
Remove the NoExceptions flag from a previous configuration.
|
||||
|
||||
```lua
|
||||
removeflags "NoExceptions"
|
||||
```
|
||||
|
||||
You can use wildcards in removes. This example will remove both WIN32 and WIN64 from the defines.
|
||||
|
||||
```lua
|
||||
defines { "WIN32", "WIN64", "LINUX", "MACOSX" }
|
||||
removedefines "WIN*"
|
||||
```
|
||||
60
website/docs/Scopes-and-Inheritance.md
Normal file
60
website/docs/Scopes-and-Inheritance.md
Normal file
@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Scopes & Inheritance
|
||||
---
|
||||
|
||||
As you may have noticed from the previous samples, Premake uses a pseudo-declarative syntax for specifying project information. You specify a *scope* (i.e. a workspace or project) for the settings, and then the settings to be placed in that scope.
|
||||
|
||||
Scopes have a hierarchy: a *global* scope containing workspaces, which in turn contains projects. Values placed into the outer scopes are inherited by the inner ones, so workspaces inherit the values stored at the global scope, and projects inherit values stored in workspaces.
|
||||
|
||||
```lua
|
||||
-- global scope, all workspaces will receive these values
|
||||
defines { "GLOBAL" }
|
||||
|
||||
workspace "MyWorkspaces"
|
||||
-- workspace scope inherits the global scope; the list value
|
||||
-- will now be { "GLOBAL", "WORKSPACE" }
|
||||
defines { "WORKSPACE" }
|
||||
|
||||
project "MyProject"
|
||||
-- project scope inherits from its workspace; the list value
|
||||
-- will now be { "GLOBAL", "WORKSPACE", "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.
|
||||
|
||||
```lua
|
||||
-- declare my workspace
|
||||
workspace "MyWorkspace"
|
||||
defines { "WORKSPACE1" }
|
||||
|
||||
-- declare a project or two
|
||||
project "MyProject"
|
||||
defines { "PROJECT" }
|
||||
|
||||
-- re-select my workspace to add more settings, which will be inherited
|
||||
-- by all projects in the workspace
|
||||
workspace "MyWorkspace"
|
||||
defines { "WORKSPACE2" } -- value is now { "WORKSPACE1", "WORKSPACE2" }
|
||||
```
|
||||
|
||||
You can also select the parent or container of the current scope without having to know its name by using the special "*" name.
|
||||
|
||||
```lua
|
||||
-- declare my workspace
|
||||
workspace "MyWorkspace"
|
||||
defines { "WORKSPACE1" }
|
||||
|
||||
-- declare a project or two
|
||||
project "MyProject"
|
||||
defines { "PROJECT" }
|
||||
|
||||
-- re-select my workspace to add more settings
|
||||
project "*"
|
||||
defines { "WORKSPACE2" } -- value is now { "WORKSPACE1", "WORKSPACE2" }
|
||||
|
||||
-- re-select the global scope
|
||||
workspace "*"
|
||||
```
|
||||
|
||||
Think of the "*" as a wilcard meaning "all projects in my parent container" or "all workspaces in the global scope".
|
||||
33
website/docs/Sharing-Your-Module.md
Normal file
33
website/docs/Sharing-Your-Module.md
Normal file
@ -0,0 +1,33 @@
|
||||
---
|
||||
title: Sharing Your Module
|
||||
---
|
||||
|
||||
## Versioning
|
||||
|
||||
To ensure compatibility, Premake allows project script authors to specify a minimum version or range of versions for the modules they require.
|
||||
|
||||
```lua
|
||||
require("foo", ">=1.1")
|
||||
```
|
||||
|
||||
To support this feature, your module should include a `_VERSION` field specifying the current version.
|
||||
|
||||
```lua
|
||||
m._VERSION = "1.0.0" -- for the 1.0 release
|
||||
m._VERSION = "1.0.0-dev" -- for the development (i.e. what's in your code repository) version
|
||||
m._VERSION = "1.0.0-alpha3" -- for a pre-release version
|
||||
```
|
||||
|
||||
When updating your version number between releases, try to follow the conventions set by the [semantic versioning](http://semver.org) standard.
|
||||
|
||||
## Publishing
|
||||
|
||||
If you intend your module to be available to the public, consider creating a new repository on [GitHub](http://github.com/) (where Premake is hosted) for it, and taking a look at some of the [existing third-party modules](modules) for examples. Some tips:
|
||||
|
||||
* Name your repository something like `premake-modulename`
|
||||
|
||||
* Include a `README.md` file which explains what your module does, how to use it, and any requirements it has on other modules or libraries.
|
||||
|
||||
* Set up a wiki and briefly document any new features and functions it adds. See [Premake's own documentation](https://github.com/premake/premake-core/wiki) for lots of examples.
|
||||
|
||||
Finally, regardless of where you host it, be sure to add a link on the [Available Modules](modules) page to help people find it.
|
||||
140
website/docs/Starting-Your-New-Action.md
Normal file
140
website/docs/Starting-Your-New-Action.md
Normal file
@ -0,0 +1,140 @@
|
||||
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).
|
||||
|
||||
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).
|
||||
|
||||
Copy this simple skeleton action definition into your `lua.lua`:
|
||||
|
||||
|
||||
```lua
|
||||
-- lua/lua.lua
|
||||
|
||||
premake.modules.lua = {}
|
||||
local m = premake.modules.lua
|
||||
|
||||
local p = premake
|
||||
|
||||
newaction {
|
||||
trigger = "lua",
|
||||
description = "Export project information as Lua tables",
|
||||
|
||||
onStart = function()
|
||||
print("Starting Lua generation")
|
||||
end,
|
||||
|
||||
onWorkspace = function(wks)
|
||||
printf("Generating Lua for workspace '%s'", wks.name)
|
||||
end,
|
||||
|
||||
onProject = function(prj)
|
||||
printf("Generating Lua for project '%s'", prj.name)
|
||||
end,
|
||||
|
||||
execute = function()
|
||||
print("Executing Lua action")
|
||||
end,
|
||||
|
||||
onEnd = function()
|
||||
print("Lua generation complete")
|
||||
end
|
||||
}
|
||||
|
||||
return m
|
||||
```
|
||||
|
||||
I'll explain what all of that means in a moment, but first let's try it out and make sure everything is working. To see our new action in action, we'll need to require it into an existing project's `premake5.lua` script.
|
||||
|
||||
```lua
|
||||
require "lua" -- add this to load your module
|
||||
|
||||
workspace "MyWorkspace"
|
||||
configurations { "Debug", "Release" }
|
||||
|
||||
project "MyProject"
|
||||
-- etc.
|
||||
```
|
||||
|
||||
Then we can generate that project with our new `lua` action and see the `print()` functions get called.
|
||||
|
||||
```
|
||||
$ premake5 lua
|
||||
Building configurations...
|
||||
Running action 'lua'...
|
||||
Starting Lua generation
|
||||
Generating Lua for workspace 'MyWorkspace'
|
||||
Generating Lua for project 'MyProject'
|
||||
Executing Lua action
|
||||
Lua generation complete
|
||||
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.)
|
||||
|
||||
|
||||
### Explain. ###
|
||||
|
||||
We start out by creating a table to hold our module's interface. Since we'll be referencing this interface quite a lot in our code, we assign it to the shortcut `m` for "module".
|
||||
|
||||
```lua
|
||||
premake.modules.lua = {}
|
||||
local m = premake.modules.lua
|
||||
```
|
||||
|
||||
We will also be calling functions from the `premake` namespace frequently, so we assign that to the shortcut `p` for "premake".
|
||||
|
||||
```lua
|
||||
local p = premake
|
||||
```
|
||||
|
||||
Now we're ready to register our new action with Premake, using `newaction()`.
|
||||
|
||||
```lua
|
||||
newaction {
|
||||
trigger = "lua",
|
||||
description = "Export project information as Lua",
|
||||
```
|
||||
|
||||
`trigger` is the token that should be typed on the Premake command line to cause our action to be triggered (i.e. `premake5 lua`).
|
||||
|
||||
`description` is the string which should appear in Premake's help text to describe what our action does. You can view this by running `premake5 --help` against the project script we modified above.
|
||||
|
||||
Next, we register callbacks for Premake to use when it is time to export the project:
|
||||
|
||||
```lua
|
||||
onStart = function()
|
||||
print("Starting Lua generation")
|
||||
end,
|
||||
|
||||
onWorkspace = function(wks)
|
||||
printf("Generating Lua for workspace '%s'", wks.name)
|
||||
end,
|
||||
|
||||
onProject = function(prj)
|
||||
printf("Generating Lua for project '%s'", prj.name)
|
||||
end,
|
||||
|
||||
execute = function()
|
||||
print("Executing Lua action")
|
||||
end,
|
||||
|
||||
onEnd = function()
|
||||
print("Lua generation complete")
|
||||
end
|
||||
```
|
||||
|
||||
All of these callbacks are optional; you only need to include the ones you are actually interested in receiving.
|
||||
|
||||
`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.
|
||||
|
||||
`onProject` is called once for every project that was declared, via the [`project`](project) 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.
|
||||
|
||||
`onEnd` is called to indicate the processing is complete.
|
||||
|
||||
Finally, we return our module's interface back to the caller (the `require("lua")` call in our project or system script).
|
||||
|
||||
```lua
|
||||
return m
|
||||
```
|
||||
15
website/docs/System-Scripts.md
Normal file
15
website/docs/System-Scripts.md
Normal file
@ -0,0 +1,15 @@
|
||||
---
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
You can override the default system script file name and location using the `--systemscript` command line argument.
|
||||
|
||||
```
|
||||
$ premake5 /systemscript=../scripts/my_system_script.lua vs2010
|
||||
```
|
||||
|
||||
There is nothing particularly special about this file other than its run-first priority. You can put any Premake code in the system script, including configurations, workspaces, and projects.
|
||||
116
website/docs/Tokens.md
Normal file
116
website/docs/Tokens.md
Normal file
@ -0,0 +1,116 @@
|
||||
---
|
||||
title: Tokens
|
||||
---
|
||||
|
||||
Tokens provide the ability to substitute computed values into a configuration setting. Using tokens, you can specify a single value that automatically adjusts itself to different platforms and configurations.
|
||||
|
||||
Tokens come in two varieties: *value tokens*, and *command tokens*.
|
||||
|
||||
## Value Tokens
|
||||
|
||||
Value tokens are expressions wrapped in a `%{}` sequence. Tokens have access to one or more context objects, depending on their scope within the project: `wks`, `prj`, `cfg`, and `file`. You can access all of the fields of these context objects within the token.
|
||||
|
||||
```lua
|
||||
%{wks.name}
|
||||
%{prj.location}
|
||||
%{cfg.targetdir}
|
||||
```
|
||||
|
||||
The contents of the %{} are run through loadstring() and executed at token-replacement time, so more complex replacements can be used. You can access any global value.
|
||||
|
||||
```lua
|
||||
%{wks.name:gsub(' ', '_')}
|
||||
```
|
||||
|
||||
You can use `wks`, `prj`, `cfg`, and `file` to represent the current workspace, project, configuration, and file configuration respectively. Note that these values must be in scope for the type of value you are trying to substitute or the object will be nil. You'll have to hunt around for the available fields until I have a chance to document them, but in general they follow the API names (includedirs, location, flags, etc.).
|
||||
|
||||
Some known tokens (feel free to add more as you use them):
|
||||
|
||||
```lua
|
||||
wks.name
|
||||
wks.location -- (location where the workspace/solution is written, not the premake-wks.lua file)
|
||||
|
||||
prj.name
|
||||
prj.location -- (location where the project is written, not the premake-prj.lua file)
|
||||
prj.language
|
||||
prj.group
|
||||
|
||||
cfg.longname
|
||||
cfg.shortname
|
||||
cfg.kind
|
||||
cfg.architecture
|
||||
cfg.platform
|
||||
cfg.system
|
||||
cfg.buildcfg
|
||||
cfg.buildtarget -- (see [target], below)
|
||||
cfg.linktarget -- (see [target], below)
|
||||
cfg.objdir
|
||||
|
||||
file.path
|
||||
file.abspath
|
||||
file.relpath
|
||||
file.directory
|
||||
file.reldirectory
|
||||
file.name
|
||||
file.basename -- (file part without extension)
|
||||
file.extension -- (including '.'; eg ".cpp")
|
||||
|
||||
-- These values are available on build and link targets
|
||||
-- Replace [target] with one of "cfg.buildtarget" or "cfg.linktarget"
|
||||
-- Eg: %{cfg.buildtarget.abspath}
|
||||
[target].abspath
|
||||
[target].relpath
|
||||
[target].directory
|
||||
[target].name
|
||||
[target].basename -- (file part without extension)
|
||||
[target].extension -- (including '.'; eg ".cpp")
|
||||
[target].bundlename
|
||||
[target].bundlepath
|
||||
[target].prefix
|
||||
[target].suffix
|
||||
```
|
||||
|
||||
## Command Tokens
|
||||
|
||||
Command tokens represent a system level command in a platform-neutral way.
|
||||
|
||||
```lua
|
||||
postbuildcommands {
|
||||
"{COPY} file1.txt file2.txt"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
You can use command tokens anywhere you specify a command line, including:
|
||||
|
||||
* [buildcommands](buildcommands)
|
||||
* [cleancommands](cleancommands)
|
||||
* [os.execute](os.execute)
|
||||
* [os.executef](os.executef)
|
||||
* [postbuildcommands](postbuildcommands)
|
||||
* [prebuildcommands](prebuildcommands)
|
||||
* [prelinkcommands](prelinkcommands)
|
||||
* [rebuildcommands](rebuildcommands)
|
||||
|
||||
Command tokens are replaced with an appropriate command for the target platform. For Windows, path separators in the commmand arguments are converted to backslashes.
|
||||
|
||||
The available tokens, and their replacements:
|
||||
|
||||
| Token | DOS | Posix |
|
||||
|------------|---------------------------------------------|-----------------|
|
||||
| {CHDIR} | chdir {args} | cd {args} |
|
||||
| {COPYFILE} | copy /B /Y {args} | cp -f {args} |
|
||||
| {COPYDIR} | xcopy /Q /E /Y /I {args} | cp -rf {args} |
|
||||
| {DELETE} | del {args} | rm -rf {args} |
|
||||
| {ECHO} | echo {args} | echo {args} |
|
||||
| {MKDIR} | mkdir {args} | mkdir -p {args} |
|
||||
| {MOVE} | move /Y {args} | mv -f {args} |
|
||||
| {RMDIR} | rmdir /S /Q {args} | rm -rf {args} |
|
||||
| {TOUCH} | type nul >> {arg} && copy /b {arg}+,, {arg} | touch {args} |
|
||||
|
||||
Note that this token exists but is deprecated in favor of {COPYDIR} and {COPYFILE}
|
||||
| {COPY} | xcopy /Q /E /Y /I {args} | cp -rf {args} |
|
||||
|
||||
## Tokens and Filters
|
||||
|
||||
Tokens are not expanded in filters. See [issue 1306](https://github.com/premake/premake-core/issues/1036#issuecomment-379685035) for some illustrative examples.
|
||||
13
website/docs/Topics.md
Normal file
13
website/docs/Topics.md
Normal file
@ -0,0 +1,13 @@
|
||||
---
|
||||
title: More Authoring Topics
|
||||
---
|
||||
|
||||
* [Locating Scripts](locating-scripts)
|
||||
* [System Scripts](system-scripts)
|
||||
* [Removing Values](removing-values)
|
||||
* [Tokens](tokens)
|
||||
* [Precompiled Headers](precompiled-headers)
|
||||
* [Custom Build Commands](custom-build-commands)
|
||||
* [Custom Rules](custom-rules)
|
||||
* [Makefile Projects](makefile-projects)
|
||||
* [Debugging Scripts](debugging-scripts)
|
||||
28
website/docs/Usages.md
Normal file
28
website/docs/Usages.md
Normal file
@ -0,0 +1,28 @@
|
||||
---
|
||||
title: Usages
|
||||
---
|
||||
|
||||
See [moomalade/premake-usage](https://github.com/moomalade/premake-usage).
|
||||
|
||||
*Usages* are an idea that has been batted around for years now, but never quite made it to the light of day. The goal it to allow a project script to specify how to *use* a library or component, as opposed to how to build it: what libraries to link, what header files and search paths to include, what symbols to define, and so on.
|
||||
|
||||
The syntax proposal is a new call `usage` to define the settings:
|
||||
|
||||
```lua
|
||||
-- Define how to build the project
|
||||
project "MyLibrary"
|
||||
-- …
|
||||
|
||||
-- Define how to use the project
|
||||
usage "MyLibrary"
|
||||
links { "my-library" }
|
||||
includedirs { "./includes" }
|
||||
defines { "MY_LIBRARY" }
|
||||
```
|
||||
|
||||
Another project can then pull these settings in by calling `uses`:
|
||||
|
||||
```lua
|
||||
project "MyApp"
|
||||
uses { "MyLibrary" }
|
||||
```
|
||||
46
website/docs/Using-Modules.md
Normal file
46
website/docs/Using-Modules.md
Normal file
@ -0,0 +1,46 @@
|
||||
---
|
||||
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. We keep [a community-maintained list of modules here on the wiki](modules).
|
||||
|
||||
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**.
|
||||
|
||||
````
|
||||
$ git clone https://github.com/dcourtois/premake-qt qt
|
||||
````
|
||||
|
||||
Then simply call `require()` from your project or [system script](system-scripts) to include it.
|
||||
|
||||
```lua
|
||||
require "qt"
|
||||
```
|
||||
|
||||
### Including a Module With Your Project ###
|
||||
|
||||
For convenience, you may wish to keep a copy of the modules you require in your project's source tree. In that case you may place them anywhere you wish, and provide the relative path when requiring it. For instance, if your main **premake5.lua** is located at the root of your project tree, and your modules are in a folder named **build**, you may load it like:
|
||||
|
||||
```lua
|
||||
require "build/qt"
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
```lua
|
||||
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.
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
```lua
|
||||
require("qt", ">=1.1")
|
||||
```
|
||||
|
||||
See [the `require()` documentation](require) for more information and examples.
|
||||
@ -2,21 +2,23 @@
|
||||
title: Using Premake
|
||||
---
|
||||
|
||||
*New to Premake? You might want to start with [What is Premake?](/docs/)*
|
||||
*New to Premake? You might want to start with [What is Premake?](what-is-premake)*
|
||||
|
||||
|
||||
### Getting Premake ###
|
||||
## Getting Premake
|
||||
|
||||
If you don't have Premake already, see [Getting Premake](Getting-Premake.md) to learn how.
|
||||
If you don't have Premake already, see [Getting Premake](getting-premake) to learn how.
|
||||
|
||||
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
|
||||
|
||||
The simplest Premake command is:
|
||||
|
||||
premake5 [action]
|
||||
```
|
||||
premake5 [action]
|
||||
```
|
||||
|
||||
Premake defines the following list of actions out of the box; projects may also add their own custom actions.
|
||||
|
||||
@ -32,38 +34,47 @@ Premake defines the following list of actions out of the box; projects may also
|
||||
| vs2005 | Generate Visual Studio 2005 project files |
|
||||
| gmake | Generate GNU Makefiles (This generator is deprecated by gmake2) |
|
||||
| gmake2 | Generate GNU Makefiles (including [Cygwin][1] and [MinGW][2]) |
|
||||
| xcode4 | XCode projects (built-in [extension](https://github.com/premake/premake-core/tree/master/modules/xcode)) |
|
||||
| codelite | CodeLite projects (built-in [extension](https://github.com/premake/premake-core/tree/master/modules/codelite)) |
|
||||
| xcode4 | XCode 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.md) 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) for the whole list.)
|
||||
|
||||
To generate Visual Studio 2013 project files, use the command:
|
||||
|
||||
premake5 vs2013
|
||||
```
|
||||
premake5 vs2013
|
||||
```
|
||||
|
||||
You can see a complete list of the actions and other options supported by a project with the command:
|
||||
|
||||
premake5 --help
|
||||
```
|
||||
premake5 --help
|
||||
```
|
||||
|
||||
|
||||
### Using the Generated Projects ###
|
||||
## Using the Generated Projects
|
||||
|
||||
For toolsets like Visual Studio and Xcode, you can simply load the generated workspace or workspace into your IDE and build as you normally would.
|
||||
|
||||
If you have generated makefiles, running **make** with no options will build all targets using the default configuration, as set by the project author. To see the list of available configurations, type:
|
||||
If you have generated makefiles, running `make` with no options will build all targets using the default configuration, as set by the project author. To see the list of available configurations, type:
|
||||
|
||||
make help
|
||||
```
|
||||
make help
|
||||
```
|
||||
|
||||
To build a different configuration, add the **config** argument:
|
||||
|
||||
make config=release
|
||||
```
|
||||
make config=release
|
||||
```
|
||||
|
||||
To remove all generated binaries and intermediate files:
|
||||
|
||||
make clean # to clean the default target
|
||||
make config=release clean # to clean a different target
|
||||
```
|
||||
make clean # to clean the default 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.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).
|
||||
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).
|
||||
|
||||
[1]: http://www.cygwin.com/
|
||||
[2]: http://www.mingw.org/
|
||||
|
||||
@ -1,12 +1,9 @@
|
||||
---
|
||||
title: What is Premake
|
||||
title: What is Premake?
|
||||
---
|
||||
|
||||
Premake is a command line utility which reads a scripted definition of a software project and, most commonly, uses it to generate project files for toolsets like Visual Studio, Xcode, or GNU Make.
|
||||
|
||||
|
||||
-----------------------------------------
|
||||
|
||||
```lua
|
||||
workspace "MyWorkspace"
|
||||
configurations { "Debug", "Release" }
|
||||
@ -37,9 +34,8 @@ Done.
|
||||
```
|
||||
*Premake reads the script and generates project scripts.*
|
||||
|
||||
-----------------------------------------
|
||||
|
||||
### Use Premake To… ###
|
||||
## Use Premake To…
|
||||
|
||||
* Maximize your potential audience by allowing developers to use the platforms and toolsets they prefer.
|
||||
|
||||
@ -56,7 +52,7 @@ Done.
|
||||
* Script common configuration and build maintenance tasks.
|
||||
|
||||
|
||||
### Key Features ###
|
||||
## Key Features
|
||||
|
||||
The current development version of Premake 5.0 can generate C, C++, or C# projects targeting:
|
||||
|
||||
@ -72,7 +68,7 @@ Premake 5.0 generated projects can support:
|
||||
* 32- and 64-bit builds
|
||||
* Xbox 360 (Visual Studio only)
|
||||
|
||||
[Add-on modules](Modules.md) can extend Premake with support for additional languages, frameworks, and toolsets.
|
||||
[Add-on modules](modules) can extend Premake with support for additional languages, frameworks, and toolsets.
|
||||
|
||||
In addition to its project generation capabilities, Premake also provides a complete [Lua](http://lua.org/) scripting environment, enabling the automation of complex configuration tasks such as setting up new source tree checkouts or creating deployment packages. These scripts will run on any platform, ending batch/shell script duplication.
|
||||
|
||||
|
||||
153
website/docs/Whats-New-in-5.0.md
Normal file
153
website/docs/Whats-New-in-5.0.md
Normal file
@ -0,0 +1,153 @@
|
||||
---
|
||||
title: What's New in 5.0
|
||||
---
|
||||
|
||||
## Name Changes ##
|
||||
|
||||
* The executable is now named **premake5**
|
||||
* The default project script is now **premake5.lua**; premake4.lua remains as a fallback.
|
||||
|
||||
## Flags and Actions ##
|
||||
|
||||
* --interactive (open an interactive command prompt)
|
||||
* vs2012, vs2013, vs2015, vs2019 (Visual Studio 2012, 2013, 2015, 2019)
|
||||
|
||||
## Major Features ##
|
||||
|
||||
* [Custom Rules](custom-rules) (still experimental)
|
||||
* [Makefile Projects](makefile-projects)
|
||||
* [Modules](modules)
|
||||
* [Per-Configuration File Lists](files)
|
||||
* [Per-File Configurations](configuration)
|
||||
* [Per-Project Configurations](configurations-and-platforms)
|
||||
* [Platforms](configurations-and-platforms)
|
||||
* [Removes](removing-values)
|
||||
* [System Scripts](system-scripts)
|
||||
* [Tokens](tokens)
|
||||
* [HTTP support](http.download)
|
||||
|
||||
## New or Modified Globals ##
|
||||
|
||||
* [_MAIN_SCRIPT](_main_script)
|
||||
* [_MAIN_SCRIPT_DIR](_main_script_dir)
|
||||
* [_PREMAKE_DIR](_premake_dir)
|
||||
|
||||
## New or Modified API calls ##
|
||||
|
||||
* [architecture](architecture) (new)
|
||||
* [buildaction](buildaction) (new values)
|
||||
* [buildcommands](buildcommands) (new)
|
||||
* [builddependencies](builddependencies) (new)
|
||||
* [buildlog](buildlog) (new)
|
||||
* [buildmessage](buildmessage) (new)
|
||||
* [buildoutputs](buildoutputs) (new)
|
||||
* [characterset](characterset) (new)
|
||||
* [callingconvention](callingconvention) (new)
|
||||
* [cleancommands](cleancommands) (new)
|
||||
* [cleanextensions](cleanextensions) (new)
|
||||
* [clr](clr) (new, replaces flags `Managed` and `Unsafe`)
|
||||
* [configfile](configfile) (new)
|
||||
* [configmap](configmap) (new)
|
||||
* [configuration](configuration) (retired)
|
||||
* [configurations](configurations) (modified)
|
||||
* [copylocal](copylocal) (new)
|
||||
* [debugcommand](debugcommand) (new)
|
||||
* [debugconnectcommands](debugconnectcommands) (new)
|
||||
* [debugextendedprotocol](debugextendedprotocol) (new)
|
||||
* [debugport](debugport) (new)
|
||||
* [debugremotehost](debugremotehost) (new)
|
||||
* [debugsearchpaths](debugsearchpaths) (new)
|
||||
* [debugstartupcommands](debugstartupcommands) (new)
|
||||
* [dependson](dependson) (new)
|
||||
* [disablewarnings](disablewarnings) (new)
|
||||
* [dotnetframework](dotnetframework) (new)
|
||||
* [editandcontinue](editandcontinue) (new, replaces flag `NoEditAndContinue`)
|
||||
* [editorintegration](editorintegration) (new)
|
||||
* [enablewarnings](enablewarnings) (new)
|
||||
* [endian](endian) (new)
|
||||
* [entrypoint](entrypoint) (new)
|
||||
* [exceptionhandling](exceptionhandling) (new)
|
||||
* [external](external) (new)
|
||||
* [externalproject](externalproject) (new)
|
||||
* [externalrule](externalrule) (new)
|
||||
* [fatalwarnings](fatalwarnings) (new)
|
||||
* [fileextension](fileextension) (new)
|
||||
* [filename](filename) (new)
|
||||
* [filter](filter) (new)
|
||||
* [flags](flags) (new values)
|
||||
* [floatingpoint](floatingpoint) (new, replaces flags `FloatFast` and `FloatStrict`)
|
||||
* [forceincludes](forceincludes) (new)
|
||||
* [forceusings](forceusings) (new)
|
||||
* [fpu](fpu) (new)
|
||||
* [gccprefix](gccprefix) (new)
|
||||
* [group](group) (new)
|
||||
* [icon](icon) (new)
|
||||
* [inlining](inlining) (new)
|
||||
* [kind](kind) (Makefile, None)
|
||||
* [linkbuildoutputs](linkbuildoutputs) (new)
|
||||
* [links](links)
|
||||
* [language](language) (new values)
|
||||
* [locale](locale) (new)
|
||||
* [makesettings](makesettings) (new)
|
||||
* [namespace](namespace) (new)
|
||||
* [nativewchar](nativewchar) (new, replaces flag `NativeWChar`)
|
||||
* [newaction](newaction) (modified)
|
||||
* [nuget](nuget) (new)
|
||||
* [objdir](objdir) (modified)
|
||||
* [optimize](optimize) (new, replaces flags `OptimizeSize` and `OptimizeSpeed`)
|
||||
* [pic](pic) (new)
|
||||
* [platforms](platforms) (modified)
|
||||
* [postbuildmessage](postbuildmessage) (new)
|
||||
* [prebuildmessage](prebuildmessage) (new)
|
||||
* [prelinkmessage](prelinkmessage) (new)
|
||||
* [project](project) (modified)
|
||||
* [propertydefinition](propertydefinition) (new)
|
||||
* [rebuildcommands](rebuildcommands) (new)
|
||||
* [rtti](rtti) (new, replaces flag `NoRTTI`)
|
||||
* [rule](rule) (new)
|
||||
* [rules](rules) (new)
|
||||
* [runtime](runtime) (new)
|
||||
* [solution](workspace) (name changed)
|
||||
* [startproject](startproject) (new)
|
||||
* [strictaliasing](strictaliasing) (new)
|
||||
* [sysincludedirs](sysincludedirs) (new)
|
||||
* [syslibdirs](syslibdirs) (new)
|
||||
* [system](system) (new)
|
||||
* [toolset](toolset) (new)
|
||||
* [undefines](undefines) (new)
|
||||
* [vectorextensions](vectorextensions) (new, replaces flags `EnableSSE` and `EnableSSE2`)
|
||||
* [warnings](warnings) (new, replaces flags `ExtraWarnings` and `NoWarnings`)
|
||||
* [workspace](workspace) (new)
|
||||
|
||||
## New or Modified Lua library calls ##
|
||||
|
||||
* [includeexternal](includeexternal) (new)
|
||||
* [require](require) (modified)
|
||||
|
||||
* [debug.prompt](debug.prompt) (new)
|
||||
|
||||
* [http.download](http.download) (new)
|
||||
* [http.get](http.get) (new)
|
||||
|
||||
* [os.chmod](os.chmod) (new)
|
||||
* [os.islink](os.islink) (new)
|
||||
* [os.realpath](os.realpath) (new)
|
||||
* [os.uuid](os.uuid) (can now generated deterministic name-based UUIDs)
|
||||
|
||||
* [path.getabsolute](path.getabsolute) (new "relative to" argument)
|
||||
|
||||
* [string.hash](string.hash) (new)
|
||||
|
||||
## Deprecated Values and Functions ##
|
||||
|
||||
* [buildrule](buildrule)
|
||||
* [flags](flags):
|
||||
* Component
|
||||
* EnableSSE, EnableSSE2: use [vectorextensions](vectorextensions) instead
|
||||
* ExtraWarnings, NoWarnings: use [warnings](warnings) instead
|
||||
* FloatFast, FloatStrict: use [floatingpoint](floatingpoint) instead
|
||||
* Managed, Unsafe: use [clr](clr) instead
|
||||
* NativeWChar: use [nativewchar](nativewchar) instead
|
||||
* NoEditAndContinue: use [editandcontinue](editandcontinue) instead
|
||||
* NoRTTI: use [rtti](rtti) instead.
|
||||
* OptimizeSize, OptimizeSpeed: use [optimize](optimize) instead
|
||||
61
website/docs/Why-Do-Call-Arrays-Need-Functions.md
Normal file
61
website/docs/Why-Do-Call-Arrays-Need-Functions.md
Normal file
@ -0,0 +1,61 @@
|
||||
---
|
||||
title: Why Do Call Arrays Need Functions?
|
||||
---
|
||||
|
||||
*"Hang on a minute,"* you're now thinking. *"Why do I need to override a function, call it to get the table, and then insert my new call? Why don't you just have a global table? Then I could insert my new call and skip that override business."*
|
||||
|
||||
In other words, why couldn't the list of functions look like this instead?
|
||||
|
||||
```lua
|
||||
m.elements.project = {
|
||||
m.xmlDeclaration,
|
||||
m.project,
|
||||
m.projectConfigurations,
|
||||
-- and so on...
|
||||
}
|
||||
|
||||
-- then I could do this:
|
||||
|
||||
table.insertafter(m.elements.project, m.xmlDeclaration, myNewFunction)
|
||||
|
||||
-- instead of this!
|
||||
|
||||
premake.override(m.elements, "project", function(base, prj)
|
||||
local calls = base(prj)
|
||||
table.insertafter(calls, m.xmlDeclaration, myNewFunction)
|
||||
return calls
|
||||
end)
|
||||
```
|
||||
|
||||
The answer: that would break the ability to override the functions in the array. Let me explain...
|
||||
|
||||
The functions being included in the array are resolved at the time the code is evaluated. For a global table that means at the time the script is first loaded and executed.
|
||||
|
||||
When the code is executed, `m.project` (perhaps better thought of here as `m["project"]`) is evaluated and *the function it represents* is stored into the array. Kind of like this:
|
||||
|
||||
```lua
|
||||
m.elements.project = {
|
||||
function: 0x10017b280
|
||||
function: 0x100124dd0
|
||||
function: 0x10017b2c0
|
||||
-- and so on...
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
That's all well and good: `m.project` evaluates to `function: 0x100124dd0` and that's what is in the array.
|
||||
|
||||
Now what happens if want to override `m.project`?
|
||||
|
||||
```lua
|
||||
premake.override(m, "project", function(base, prj)
|
||||
print("All your base are belong to us")
|
||||
base(prj)
|
||||
end)
|
||||
```
|
||||
|
||||
`premake.override()` takes your new replacement function and assigns it to `m.project` (or `m["project"]` if that's easier to visualize). Which means the symbol `m.project` now evaluates to a different function, say `function: 0x100300360`.
|
||||
|
||||
If you call `m.project(prj)` directly, your replacement function will be executed as expected. However, since the `m.elements.project` table has already been evaluated, it still points to the original `function: 0x100124dd0`. Which means that when the Visual Studio project is generated and that call array is processed, your override will be ignored.
|
||||
|
||||
So getting to the point: by putting the call array table inside a function, we defer evaluation *until the function is actually called*. Since all of the user scripts are called before the Visual Studio project is generated, your override will already be in place, `m.project` will evaluate to your replacement function (`function: 0x100300360` instead of `function: 0x100124dd0`), and the correct code will be run.
|
||||
73
website/docs/Workspaces-and-Projects.md
Normal file
73
website/docs/Workspaces-and-Projects.md
Normal file
@ -0,0 +1,73 @@
|
||||
---
|
||||
title: Workspaces & Projects
|
||||
---
|
||||
|
||||
For convenience, Premake follows the Visual Studio conventions for structuring a build and the naming of its components.
|
||||
|
||||
|
||||
## Workspaces ##
|
||||
|
||||
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 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.
|
||||
|
||||
```lua
|
||||
workspace "HelloWorld"
|
||||
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.
|
||||
|
||||
```lua
|
||||
workspace "Hello World"
|
||||
filename "Hello"
|
||||
configurations { "Debug", "Release" }
|
||||
```
|
||||
|
||||
*(Note: Due to [a bug in the way Xcode handles target dependencies](http://stackoverflow.com/questions/1456806/xcode-dependencies-across-different-build-directories), we currently don't generate a "workspace" file for it.
|
||||
|
||||
|
||||
## Projects ##
|
||||
|
||||
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.
|
||||
|
||||
```lua
|
||||
workspace "MyWorkspace"
|
||||
configurations { "Debug", "Release" }
|
||||
|
||||
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.
|
||||
|
||||
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 also specifies which programming language it uses, such as C++ or C#. The [`language`](language) function is used to set this value.
|
||||
|
||||
```lua
|
||||
project "MyProject"
|
||||
kind "ConsoleApp"
|
||||
language "C++"
|
||||
```
|
||||
|
||||
|
||||
## Locations ##
|
||||
|
||||
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.
|
||||
|
||||
```lua
|
||||
workspace "MyWorkspace"
|
||||
configurations { "Debug", "Release" }
|
||||
location "build"
|
||||
|
||||
project "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`.
|
||||
150
website/docs/Your-First-Script.md
Normal file
150
website/docs/Your-First-Script.md
Normal file
@ -0,0 +1,150 @@
|
||||
---
|
||||
title: Your First Script
|
||||
---
|
||||
|
||||
Let's start by configuring a build for the traditional ["Hello, world!" program](https://en.wikipedia.org/wiki/%22Hello,_world!%22_program), as written in C:
|
||||
|
||||
```c
|
||||
/* hello.c */
|
||||
#include <stdio.h>
|
||||
|
||||
int main(void) {
|
||||
puts("Hello, world!");
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
The Premake script for a typical C program, such as this example, would be:
|
||||
|
||||
```lua
|
||||
-- premake5.lua
|
||||
workspace "HelloWorld"
|
||||
configurations { "Debug", "Release" }
|
||||
|
||||
project "HelloWorld"
|
||||
kind "ConsoleApp"
|
||||
language "C"
|
||||
targetdir "bin/%{cfg.buildcfg}"
|
||||
|
||||
files { "**.h", "**.c" }
|
||||
|
||||
filter "configurations:Debug"
|
||||
defines { "DEBUG" }
|
||||
symbols "On"
|
||||
|
||||
filter "configurations:Release"
|
||||
defines { "NDEBUG" }
|
||||
optimize "On"
|
||||
```
|
||||
|
||||
If you save this script as a file named `premake5.lua`, and place it in the same directory as `hello.c` above, you can then generate project files by running a command like this one:
|
||||
|
||||
```bash
|
||||
$ 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.
|
||||
|
||||
If you happened to be on Linux, you could generate and build a makefile like so:
|
||||
|
||||
```bash
|
||||
$ premake5 gmake
|
||||
$ make # build default (Debug) configuration
|
||||
$ make config=release # build release configuration
|
||||
$ make help # show available configurations
|
||||
```
|
||||
|
||||
If you'd like to use a name for your script other than the default "premake5.lua", use Premake's `--file` argument to tell it which file it should load.
|
||||
|
||||
```bash
|
||||
$ premake5 --file=MyProjectScript.lua vs2013
|
||||
```
|
||||
|
||||
|
||||
## What's Going On Here? ##
|
||||
|
||||
Through the rest of this manual I'll break this sample down and walk through all of the features of Premake in a somewhat logical fashion. It isn't rocket science, and you probably already have the gist of it from the example above, so feel free to skip around. But first, it is helpful to know a few things about Premake scripts in general.
|
||||
|
||||
|
||||
### Premake is Lua ###
|
||||
|
||||
Premake is built on [Lua](http://www.lua.org/about.html), a powerful, fast, lightweight scripting language. Premake scripts are really Lua programs, so anything you can do in Lua can also be done in a Premake script.
|
||||
|
||||
Premake builds on the Lua runtime, adding functions for defining workspaces, projects, and configurations as well as common build and file management tasks. It also provides conventions for setting your own command line options and arguments, allowing for construction of sophisticated build configuration and automation scripts.
|
||||
|
||||
Because of the descriptive nature of the Lua language, your build scripts will often look more like static configuration files than mini-programs, as you can see from the example above.
|
||||
|
||||
You can [learn more about Lua here](http://www.lua.org/about.html) or from their [excellent reference manual](http://www.lua.org/manual/5.3/), but here's what you need to know to understand this example:
|
||||
|
||||
* The identation whitespace is arbitrary; this is the way I happen to like it.
|
||||
|
||||
* A double dash "--" starts a single line comment.
|
||||
|
||||
* Curly braces "{" and "}" are used to denote lists of values.
|
||||
|
||||
|
||||
### Functions and Arguments ###
|
||||
|
||||
Each line in the sample script is actually a function call. When you call a Lua function with a simple string or table argument you may omit the usual parenthesis for readability. So the first two lines of the sample could also be written as:
|
||||
|
||||
```lua
|
||||
workspace("HelloWorld")
|
||||
configurations({ "Debug", "Release" })
|
||||
```
|
||||
|
||||
If you use anything *other* than a simple string or table, the parenthesis become mandatory.
|
||||
|
||||
```lua
|
||||
local lang = "C++"
|
||||
language (lang) -- using a variable, needs parenthesis
|
||||
|
||||
workspace("HelloWorld" .. _ACTION) -- using string concatenation, needs parenthesis
|
||||
```
|
||||
|
||||
|
||||
### Values and Lists ###
|
||||
|
||||
Most of Premake's functions accept either a single string or a list of strings as arguments. Single string arguments are easy to use and understand.
|
||||
|
||||
```lua
|
||||
language "C++"
|
||||
```
|
||||
|
||||
If multiple values are encountered for a simple value, the last one seen wins.
|
||||
|
||||
```lua
|
||||
language "C++" -- the value is now "C++"
|
||||
language "C" -- the value is now "C"
|
||||
```
|
||||
|
||||
For functions that accept a list of values, you may supply a list using Lua's curly brace syntax, or a single string value.
|
||||
|
||||
```lua
|
||||
defines { "DEBUG", "TRACE" } -- defines multiple values using list syntax
|
||||
defines { "NDEBUG" } -- defines a single value using list syntax
|
||||
defines "NDEBUG" -- defines a single value as a simple string
|
||||
```
|
||||
|
||||
If multiple values are encountered for a list, they are concatenated.
|
||||
|
||||
```lua
|
||||
defines { "DEBUG", "TRACE" } -- value is now { "DEBUG", "TRACE" }
|
||||
defines { "WINDOWS" } -- value is now { "DEBUG", "TRACE", "WINDOWS" }
|
||||
```
|
||||
|
||||
If you ever wish to remove a previously set value, all list functions define a corresponding remove...() call.
|
||||
|
||||
```lua
|
||||
defines { "DEBUG", "TRACE" } -- value is now { "DEBUG", "TRACE" }
|
||||
removedefines { "TRACE" } -- value is now { "DEBUG" }
|
||||
```
|
||||
|
||||
|
||||
### Paths ###
|
||||
|
||||
You'll be specifying lots of paths in your Premake scripts. There are two rules to remember:
|
||||
|
||||
* Always specify paths relative to the script file in which they appear.
|
||||
|
||||
* Always use forward slashes ("/") as a path separator. Premake will translate to the appropriate separator when generating the output files.
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
buildcustomizations
|
||||
Imports custom .props files for Visual Studio.
|
||||
|
||||
```lua
|
||||
buildcustomizations { "string" }
|
||||
|
||||
@ -12,7 +12,7 @@ configuration { "keywords" }
|
||||
|
||||
The available sources for keywords. Keywords are not case-sensitive.
|
||||
|
||||
* **Configuration names.** Any of the configuration names supplied to the **[configurations](configurations.md)** or **[platforms](Platforms.md)** functions.
|
||||
* **Configuration names.** Any of the configuration names supplied to the **[configurations](configurations.md)** or **[platforms](platforms.md)** functions.
|
||||
|
||||
* **Action names** such as **vs2010** or **gmake**. See the [Using Premake](Using-Premake.md) for a complete list.
|
||||
|
||||
|
||||
@ -1,4 +1,8 @@
|
||||
* `progress` is a Lua callback function that receives two numeric arguments representing total and current download progress in bytes.
|
||||
---
|
||||
title: HTTP Options
|
||||
---
|
||||
|
||||
* `progress` is a Lua callback function that receives two numeric arguments representing total and current download progress in bytes.
|
||||
* `headers` is a Lua table with HTTP headers to be used on the request.
|
||||
* `userpwd` is a username and optional password in the format of username:password which will be used to authenticate the request
|
||||
* `username` is the username which will be used to authenticate the request
|
||||
@ -30,4 +34,4 @@ Premake 5.0 or later.
|
||||
|
||||
* [http.get](http.get.md)
|
||||
* [http.post](http.post.md)
|
||||
* [http.download](http.download.md)
|
||||
* [http.download](http.download.md)
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
Translate [command tokens](Tokens#command-tokens.md) into their OS or action specific equivalents.
|
||||
Translate [command tokens](Tokens#command-tokens) into their OS or action specific equivalents.
|
||||
|
||||
```lua
|
||||
cmd = os.translateCommands("cmd", map)
|
||||
|
||||
@ -1,347 +1,427 @@
|
||||
module.exports = {
|
||||
mainSidebar: [
|
||||
{
|
||||
collapsed: false,
|
||||
type: 'category',
|
||||
label: 'Getting Started',
|
||||
items: [
|
||||
'Home',
|
||||
'What-Is-Premake',
|
||||
'Building-Premake',
|
||||
'Getting-Premake',
|
||||
'Using-Premake',
|
||||
'Getting-Help',
|
||||
'Who-Uses-Premake'
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'Guides',
|
||||
items: [
|
||||
'Sharing-Configuration-Settings'
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'Reference',
|
||||
items: [
|
||||
'_ACTION',
|
||||
'_ARGS',
|
||||
'_MAIN_SCRIPT_DIR',
|
||||
'_MAIN_SCRIPT',
|
||||
'_OPTIONS',
|
||||
'_OS',
|
||||
'_PREMAKE_COMMAND',
|
||||
'_PREMAKE_DIR',
|
||||
'_PREMAKE_VERSION',
|
||||
'_WORKING_DIR',
|
||||
'architecture',
|
||||
'atl',
|
||||
'basedir',
|
||||
'bindirs',
|
||||
'buildaction',
|
||||
'buildcommands',
|
||||
'buildcustomizations',
|
||||
'builddependencies',
|
||||
'buildinputs',
|
||||
'buildlog',
|
||||
'buildmessage',
|
||||
'buildoptions',
|
||||
'buildoutputs',
|
||||
'buildrule',
|
||||
'callingconvention',
|
||||
'cdialect',
|
||||
'characterset',
|
||||
'cleancommands',
|
||||
'cleanextensions',
|
||||
'clr',
|
||||
'compileas',
|
||||
'compilebuildoutputs',
|
||||
'configfile',
|
||||
'configmap',
|
||||
'configuration',
|
||||
'configurations',
|
||||
'copylocal',
|
||||
'cppdialect',
|
||||
'csversion',
|
||||
'customtoolnamespace',
|
||||
'debug.prompt',
|
||||
'debugargs',
|
||||
'debugcommand',
|
||||
'debugconnectcommands',
|
||||
'debugconstants',
|
||||
'debugdir',
|
||||
'debugenvs',
|
||||
'debugextendedprotocol',
|
||||
'debugformat',
|
||||
'debugger',
|
||||
'debuggertype',
|
||||
'debuglevel',
|
||||
'debugpathmap',
|
||||
'debugport',
|
||||
'debugremotehost',
|
||||
'debugsearchpaths',
|
||||
'debugstartupcommands',
|
||||
'debugtoolargs',
|
||||
'debugtoolcommand',
|
||||
'defaultplatform',
|
||||
'defines',
|
||||
'dependson',
|
||||
'deploymentoptions',
|
||||
'disablewarnings',
|
||||
'display',
|
||||
'docdir',
|
||||
'docname',
|
||||
'dofileopt',
|
||||
'dotnetframework',
|
||||
'dpiawareness',
|
||||
'editAndContinue',
|
||||
'editorintegration',
|
||||
'enablewarnings',
|
||||
'endian',
|
||||
'entrypoint',
|
||||
'exceptionhandling',
|
||||
'external',
|
||||
'externalproject',
|
||||
'externalrule',
|
||||
'fatalwarnings',
|
||||
'fileextension',
|
||||
'filename',
|
||||
'files',
|
||||
'filter',
|
||||
'flags',
|
||||
'floatingpoint',
|
||||
'floatingpointexceptions',
|
||||
'forceincludes',
|
||||
'forceusings',
|
||||
'fpu',
|
||||
'framework',
|
||||
'functionlevellinking',
|
||||
'gccprefix',
|
||||
'group',
|
||||
'headerdir',
|
||||
'headername',
|
||||
'http-options-table',
|
||||
'http.download',
|
||||
'http.get',
|
||||
'http.post',
|
||||
'icon',
|
||||
'ignoredefaultlibraries',
|
||||
'iif',
|
||||
'imageoptions',
|
||||
'imagepath',
|
||||
'implibdir',
|
||||
'implibextension',
|
||||
'implibname',
|
||||
'implibprefix',
|
||||
'implibsuffix',
|
||||
'include',
|
||||
'includedirs',
|
||||
'includeexternal',
|
||||
'inlining',
|
||||
'intrinsics',
|
||||
'io.readfile',
|
||||
'io.utf8',
|
||||
'io.writefile',
|
||||
'json.decode',
|
||||
'json.encode',
|
||||
'kind',
|
||||
'language',
|
||||
'largeaddressaware',
|
||||
'libdirs',
|
||||
'linkbuildoutputs',
|
||||
'linkgroups',
|
||||
'linkoptions',
|
||||
'links',
|
||||
'locale',
|
||||
'location',
|
||||
'makesettings',
|
||||
'namespace',
|
||||
'nativewchar',
|
||||
'newaction',
|
||||
'newoption',
|
||||
'nuget',
|
||||
'nugetsource',
|
||||
'objdir',
|
||||
'optimize',
|
||||
{
|
||||
collapsed: false,
|
||||
type: 'category',
|
||||
label: 'os',
|
||||
items: [
|
||||
'os.chdir',
|
||||
'os.chmod',
|
||||
'os.comparefiles',
|
||||
'os.copyfile',
|
||||
'os.execute',
|
||||
'os.executef',
|
||||
'os.findheader',
|
||||
'os.findlib',
|
||||
'os.get',
|
||||
'os.getcwd',
|
||||
'os.getpass',
|
||||
'os.getversion',
|
||||
'os.host',
|
||||
'os.is',
|
||||
'os.is64bit',
|
||||
'os.isdir',
|
||||
'os.isfile',
|
||||
'os.islink',
|
||||
'os.locate',
|
||||
'os.matchdirs',
|
||||
'os.matchfiles',
|
||||
'os.mkdir',
|
||||
'os.outputof',
|
||||
'os.pathsearch',
|
||||
'os.realpath',
|
||||
'os.remove',
|
||||
'os.rmdir',
|
||||
'os.stat',
|
||||
'os.target',
|
||||
'os.touchfile',
|
||||
'os.translateCommands',
|
||||
'os.uuid',
|
||||
'os.writefile_ifnotequal',
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: false,
|
||||
type: 'category',
|
||||
label: 'path',
|
||||
items: [
|
||||
'path.appendExtension',
|
||||
'path.getabsolute',
|
||||
'path.getbasename',
|
||||
'path.getdirectory',
|
||||
'path.getdrive',
|
||||
'path.getextension',
|
||||
'path.getname',
|
||||
'path.getrelative',
|
||||
'path.hasextension',
|
||||
'path.isabsolute',
|
||||
'path.iscfile',
|
||||
'path.iscppfile',
|
||||
'path.iscppheader',
|
||||
'path.isframework',
|
||||
'path.islinkable',
|
||||
'path.isobjectfile',
|
||||
'path.isresourcefile',
|
||||
'path.join',
|
||||
'path.normalize',
|
||||
'path.rebase',
|
||||
'path.replaceextension',
|
||||
'path.translate',
|
||||
'path.wildcards',
|
||||
]
|
||||
},
|
||||
'pchheader',
|
||||
'pchsource',
|
||||
'pic',
|
||||
'platforms',
|
||||
'postbuildcommands',
|
||||
'postbuildmessage',
|
||||
'prebuildcommands',
|
||||
'prebuildmessage',
|
||||
'preferredtoolarchitecture',
|
||||
'prelinkcommands',
|
||||
'prelinkmessage',
|
||||
'printf',
|
||||
'project',
|
||||
'propertydefinition',
|
||||
'rebuildcommands',
|
||||
'require',
|
||||
'resdefines',
|
||||
'resincludedirs',
|
||||
'resoptions',
|
||||
'resourcegenerator',
|
||||
'rtti',
|
||||
'rule',
|
||||
'rules',
|
||||
'runpathdirs',
|
||||
'runtime',
|
||||
'sharedlibtype',
|
||||
'startproject',
|
||||
'staticruntime',
|
||||
'strictaliasing',
|
||||
{
|
||||
collapsed: false,
|
||||
type: 'category',
|
||||
label: 'string',
|
||||
items: [
|
||||
'string.capitalized',
|
||||
'string.contains',
|
||||
'string.endswith',
|
||||
'string.escapepattern',
|
||||
'string.explode',
|
||||
'string.findlast',
|
||||
'string.hash',
|
||||
'string.lines',
|
||||
'string.plural',
|
||||
'string.sha1',
|
||||
'string.startswith'
|
||||
]
|
||||
},
|
||||
'stringpooling',
|
||||
'symbols',
|
||||
'symbolspath',
|
||||
'sysincludedirs',
|
||||
'syslibdirs',
|
||||
'system',
|
||||
'systemversion',
|
||||
{
|
||||
collapsed: false,
|
||||
type: 'category',
|
||||
label: 'table',
|
||||
items: [
|
||||
'table.arraycopy',
|
||||
'table.contains',
|
||||
'table.deepcopy',
|
||||
'table.extract',
|
||||
'table.filterempty',
|
||||
'table.flatten',
|
||||
'table.fold',
|
||||
'table.foreachi',
|
||||
'table.implode',
|
||||
'table.indexof',
|
||||
'table.insertafter',
|
||||
'table.insertflat',
|
||||
'table.isempty',
|
||||
'table.join',
|
||||
'table.keys',
|
||||
'table.merge',
|
||||
'table.replace',
|
||||
'table.tostring',
|
||||
'table.translate',
|
||||
]
|
||||
},
|
||||
'tags',
|
||||
'targetdir',
|
||||
'targetextension',
|
||||
'targetname',
|
||||
'targetprefix',
|
||||
'targetsuffix',
|
||||
'term.getTextColor',
|
||||
'term.popColor',
|
||||
'term.pushColor',
|
||||
'term.setTextColor',
|
||||
'toolset',
|
||||
'undefines',
|
||||
'usingdirs',
|
||||
'uuid',
|
||||
'vectorextensions',
|
||||
'verbosef',
|
||||
'versionconstants',
|
||||
'versionlevel',
|
||||
'visibility',
|
||||
'vpaths',
|
||||
'warnings',
|
||||
'workspace',
|
||||
'xcodebuildresources',
|
||||
'xcodebuildsettings',
|
||||
'zip.extract',
|
||||
],
|
||||
}
|
||||
],
|
||||
mainSidebar: [
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'Getting Started',
|
||||
items: [
|
||||
'Home',
|
||||
'What-Is-Premake',
|
||||
'Building-Premake',
|
||||
'Getting-Premake',
|
||||
'Using-Premake',
|
||||
'Getting-Help',
|
||||
'Who-Uses-Premake'
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'Writing Premake Scripts',
|
||||
items: [
|
||||
'Your-First-Script',
|
||||
'Workspaces-and-Projects',
|
||||
'Scopes-and-Inheritance',
|
||||
'Adding-Source-Files',
|
||||
'Linking',
|
||||
'Configurations-and-Platforms',
|
||||
'Filters',
|
||||
'Build-Settings',
|
||||
'Command-Line-Arguments',
|
||||
'Using-Modules',
|
||||
'Topics'
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'Extending Premake',
|
||||
items: [
|
||||
'Extending-Premake',
|
||||
'Code-Overview',
|
||||
'Coding-Conventions',
|
||||
'Overrides-and-Call-Arrays',
|
||||
'Developing-Modules',
|
||||
'Adding-New-Action'
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'Guides',
|
||||
items: [
|
||||
'Sharing-Configuration-Settings'
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'Reference',
|
||||
items: [
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'Project Settings',
|
||||
items: [
|
||||
'architecture',
|
||||
'atl',
|
||||
'basedir',
|
||||
'bindirs',
|
||||
'buildaction',
|
||||
'buildcommands',
|
||||
'buildcustomizations',
|
||||
'builddependencies',
|
||||
'buildinputs',
|
||||
'buildlog',
|
||||
'buildmessage',
|
||||
'buildoptions',
|
||||
'buildoutputs',
|
||||
'buildrule',
|
||||
'callingconvention',
|
||||
'cdialect',
|
||||
'characterset',
|
||||
'cleancommands',
|
||||
'cleanextensions',
|
||||
'clr',
|
||||
'compileas',
|
||||
'compilebuildoutputs',
|
||||
'configfile',
|
||||
'configmap',
|
||||
'configuration',
|
||||
'configurations',
|
||||
'copylocal',
|
||||
'cppdialect',
|
||||
'csversion',
|
||||
'customtoolnamespace',
|
||||
'debug.prompt',
|
||||
'debugargs',
|
||||
'debugcommand',
|
||||
'debugconnectcommands',
|
||||
'debugconstants',
|
||||
'debugdir',
|
||||
'debugenvs',
|
||||
'debugextendedprotocol',
|
||||
'debugformat',
|
||||
'debugger',
|
||||
'debuggertype',
|
||||
'debuglevel',
|
||||
'debugpathmap',
|
||||
'debugport',
|
||||
'debugremotehost',
|
||||
'debugsearchpaths',
|
||||
'debugstartupcommands',
|
||||
'debugtoolargs',
|
||||
'debugtoolcommand',
|
||||
'defaultplatform',
|
||||
'defines',
|
||||
'dependson',
|
||||
'deploymentoptions',
|
||||
'disablewarnings',
|
||||
'display',
|
||||
'docdir',
|
||||
'docname',
|
||||
'dofileopt',
|
||||
'dotnetframework',
|
||||
'dpiawareness',
|
||||
'editAndContinue',
|
||||
'editorintegration',
|
||||
'enablewarnings',
|
||||
'endian',
|
||||
'entrypoint',
|
||||
'exceptionhandling',
|
||||
'external',
|
||||
'externalproject',
|
||||
'externalrule',
|
||||
'fatalwarnings',
|
||||
'fileextension',
|
||||
'filename',
|
||||
'files',
|
||||
'filter',
|
||||
'flags',
|
||||
'floatingpoint',
|
||||
'floatingpointexceptions',
|
||||
'forceincludes',
|
||||
'forceusings',
|
||||
'fpu',
|
||||
'framework',
|
||||
'functionlevellinking',
|
||||
'gccprefix',
|
||||
'group',
|
||||
'headerdir',
|
||||
'headername',
|
||||
'icon',
|
||||
'ignoredefaultlibraries',
|
||||
'imageoptions',
|
||||
'imagepath',
|
||||
'implibdir',
|
||||
'implibextension',
|
||||
'implibname',
|
||||
'implibprefix',
|
||||
'implibsuffix',
|
||||
'includedirs',
|
||||
'inlining',
|
||||
'intrinsics',
|
||||
'kind',
|
||||
'language',
|
||||
'largeaddressaware',
|
||||
'libdirs',
|
||||
'linkbuildoutputs',
|
||||
'linkgroups',
|
||||
'linkoptions',
|
||||
'links',
|
||||
'locale',
|
||||
'location',
|
||||
'makesettings',
|
||||
'namespace',
|
||||
'nativewchar',
|
||||
'newaction',
|
||||
'newoption',
|
||||
'nuget',
|
||||
'nugetsource',
|
||||
'objdir',
|
||||
'optimize',
|
||||
'pchheader',
|
||||
'pchsource',
|
||||
'pic',
|
||||
'platforms',
|
||||
'postbuildcommands',
|
||||
'postbuildmessage',
|
||||
'prebuildcommands',
|
||||
'prebuildmessage',
|
||||
'preferredtoolarchitecture',
|
||||
'prelinkcommands',
|
||||
'prelinkmessage',
|
||||
'project',
|
||||
'propertydefinition',
|
||||
'rebuildcommands',
|
||||
'resdefines',
|
||||
'resincludedirs',
|
||||
'resoptions',
|
||||
'resourcegenerator',
|
||||
'rtti',
|
||||
'rule',
|
||||
'rules',
|
||||
'runpathdirs',
|
||||
'runtime',
|
||||
'sharedlibtype',
|
||||
'startproject',
|
||||
'staticruntime',
|
||||
'strictaliasing',
|
||||
'stringpooling',
|
||||
'symbols',
|
||||
'symbolspath',
|
||||
'sysincludedirs',
|
||||
'syslibdirs',
|
||||
'system',
|
||||
'systemversion',
|
||||
'tags',
|
||||
'targetdir',
|
||||
'targetextension',
|
||||
'targetname',
|
||||
'targetprefix',
|
||||
'targetsuffix',
|
||||
'toolset',
|
||||
'undefines',
|
||||
'usingdirs',
|
||||
'uuid',
|
||||
'vectorextensions',
|
||||
'versionconstants',
|
||||
'versionlevel',
|
||||
'visibility',
|
||||
'vpaths',
|
||||
'warnings',
|
||||
'workspace',
|
||||
'xcodebuildresources',
|
||||
'xcodebuildsettings'
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'Globals',
|
||||
items: [
|
||||
'_ACTION',
|
||||
'_ARGS',
|
||||
'_MAIN_SCRIPT_DIR',
|
||||
'_MAIN_SCRIPT',
|
||||
'_OPTIONS',
|
||||
'_OS',
|
||||
'_PREMAKE_COMMAND',
|
||||
'_PREMAKE_DIR',
|
||||
'_PREMAKE_VERSION',
|
||||
'_WORKING_DIR',
|
||||
'iif',
|
||||
'include',
|
||||
'includeexternal',
|
||||
'printf',
|
||||
'require',
|
||||
'verbosef',
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'http',
|
||||
items: [
|
||||
'http.download',
|
||||
'http.get',
|
||||
'http.post',
|
||||
'http-options-table'
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'io',
|
||||
items: [
|
||||
'io.readfile',
|
||||
'io.utf8',
|
||||
'io.writefile'
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'json',
|
||||
items: [
|
||||
'json.decode',
|
||||
'json.encode'
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'os',
|
||||
items: [
|
||||
'os.chdir',
|
||||
'os.chmod',
|
||||
'os.comparefiles',
|
||||
'os.copyfile',
|
||||
'os.execute',
|
||||
'os.executef',
|
||||
'os.findheader',
|
||||
'os.findlib',
|
||||
'os.get',
|
||||
'os.getcwd',
|
||||
'os.getpass',
|
||||
'os.getversion',
|
||||
'os.host',
|
||||
'os.is',
|
||||
'os.is64bit',
|
||||
'os.isdir',
|
||||
'os.isfile',
|
||||
'os.islink',
|
||||
'os.locate',
|
||||
'os.matchdirs',
|
||||
'os.matchfiles',
|
||||
'os.mkdir',
|
||||
'os.outputof',
|
||||
'os.pathsearch',
|
||||
'os.realpath',
|
||||
'os.remove',
|
||||
'os.rmdir',
|
||||
'os.stat',
|
||||
'os.target',
|
||||
'os.touchfile',
|
||||
'os.translateCommands',
|
||||
'os.uuid',
|
||||
'os.writefile_ifnotequal',
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'path',
|
||||
items: [
|
||||
'path.appendExtension',
|
||||
'path.getabsolute',
|
||||
'path.getbasename',
|
||||
'path.getdirectory',
|
||||
'path.getdrive',
|
||||
'path.getextension',
|
||||
'path.getname',
|
||||
'path.getrelative',
|
||||
'path.hasextension',
|
||||
'path.isabsolute',
|
||||
'path.iscfile',
|
||||
'path.iscppfile',
|
||||
'path.iscppheader',
|
||||
'path.isframework',
|
||||
'path.islinkable',
|
||||
'path.isobjectfile',
|
||||
'path.isresourcefile',
|
||||
'path.join',
|
||||
'path.normalize',
|
||||
'path.rebase',
|
||||
'path.replaceextension',
|
||||
'path.translate',
|
||||
'path.wildcards',
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'string',
|
||||
items: [
|
||||
'string.capitalized',
|
||||
'string.contains',
|
||||
'string.endswith',
|
||||
'string.escapepattern',
|
||||
'string.explode',
|
||||
'string.findlast',
|
||||
'string.hash',
|
||||
'string.lines',
|
||||
'string.plural',
|
||||
'string.sha1',
|
||||
'string.startswith'
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'table',
|
||||
items: [
|
||||
'table.arraycopy',
|
||||
'table.contains',
|
||||
'table.deepcopy',
|
||||
'table.extract',
|
||||
'table.filterempty',
|
||||
'table.flatten',
|
||||
'table.fold',
|
||||
'table.foreachi',
|
||||
'table.implode',
|
||||
'table.indexof',
|
||||
'table.insertafter',
|
||||
'table.insertflat',
|
||||
'table.isempty',
|
||||
'table.join',
|
||||
'table.keys',
|
||||
'table.merge',
|
||||
'table.replace',
|
||||
'table.tostring',
|
||||
'table.translate',
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'term',
|
||||
items: [
|
||||
'term.getTextColor',
|
||||
'term.popColor',
|
||||
'term.pushColor',
|
||||
'term.setTextColor'
|
||||
]
|
||||
},
|
||||
{
|
||||
collapsed: true,
|
||||
type: 'category',
|
||||
label: 'zip',
|
||||
items: [
|
||||
'zip.extract'
|
||||
]
|
||||
}
|
||||
],
|
||||
}
|
||||
],
|
||||
};
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user