Command Line Arguments

Home > [Scripting With Premake](Scripting With Premake) > Command Line Arguments

---

Command Line Arguments

Premake provides the ability to define and handle new command-line arguments from within your project script using the newaction and 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 vs2005 action indicates that Visual Studio 2005 project files should be generated. The clean action causes all generated files to be deleted. Only one action may be specified at a time (this is different than Premake 3.x).

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 global variable, a string value. You can check for an option using the _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"] )

Creating New Options

New command-line options are created using the 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 value 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:

#!lua
--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 if fired should be placed in the execute() function.

That's the simple version. If you are interested in developing more complex actions, for instance to add support for a new toolset, see [Create a new action](Create A New Action) in the Extending Premake section.