Premake scripts have the ability to define and handle new command-line options. These options may be used to customize the build environment, select packages, or to perform special processing. To create a new command-line option, use the addoption() function:

addoption("use-opengl", "Use OpenGL instead of Direct3D")

Options may be specified in both project and package scripts.

Developers can discover your custom options by typing premake --help in the project directory. For the example above, the following text will be added to the normal Premake help text:

  MyProject Options:
    --use-opengl    Use OpenGL instead of Direct3D

Within your script, you can respond to command-line options in two ways. For simple boolean tests, you can use the options variable:

if (options["use-opengl"]) then
  table.insert(package.links, "GL")
end

The value of an item in the options table is the argument supplied to the flag, or a value of 1 if no argument was provided. Suppose you wanted to allow the developer to specify where the binary files should be placed. You could define a new option called “out”, and read the value from options.

addoption("out", "Specify a location for the compiled binaries")

if (options["out"]) then
  project.bindir = options[out]
end

In this example, a developer could type premake --out out/debug to place the binaries in a directory called “out/debug”.

For even more control, Premake can call a function for each command. Here’s an example of a simple install script that allows the developer to specify the path.

addoption("install", "Copy the application to the specified path")

function doinstall(cmd, arg)
  if (not arg) then
    error("You must specify an install location")
  end
  os.copyfile("bin/myapp" arg.."/myapp")
end

If you want to override a built-in command, you can use the docommand() function to still get the default behavior.

function doclean(cmd, arg)
  docommand(cmd, arg)        -- do the default `--clean`
  os.remove("bin/myapp.log") -- remove an additional file
end