A Premake package describes a single binary target, such as an executable or shared library. It contains a list of the source code files that make up the target along with the configuration values to pass to the compiler and linker.

Here is an example of the simplest useful package script:

package.name = "MyPackage"
package.kind = "exe"
package.language = "c"
package.files = { "hello_world.c" }

The package name, like the project name earlier, is used as the name of the generated file so avoid special characters. Visual Studio 6, in particular, does not like them.

The package kind describes the type of binary you want to create. The options are:

Note that, as far as I know, only MS Windows distiguishes between a console and windowed executable.

The package language specifies the programming language used by the package. Your choices here are a bit more limited at the moment, and they all begin with C: c, c++, and c#. I would like to see support for more languages but I haven’t gotten around to it yet.

Finally, you must list the source code files that make up the package. Note the curly braces; those are used to designate a list and are required. You may put as many file names in the list as you like, separated by commas.

package.files = {
  "premake.c",
  "project.h",
  "project.c",
  "Lua/lapi.c",
  "Lua/lauxlib.c"
}

Premake provides a function called matchfiles() that makes building a list of files easier.

package.files = {
  matchfiles("*.h", "*.c"),
  matchrecursive("Lua/*.h", "Lua/*.c")
}

Using wildcards allows you to quickly add and remove files from within your IDE without having to worry about premake.lua falling out of date, which is handy. If you want to add an entire directory tree, use matchrecursive().

package.files = {
  matchrecursive("include/*.h", "src/*.cpp")
}

There are some situations where you want to include all of the files in a directory, except for one or two. In that case, use package.excludes to mask out those few.

package.files = {
  matchfiles(".h", "*.c")
}

package.excludes = {
  "dont_build_this.c"
}

A note for GNU make users: don’t edit the Premake generated makefiles. Instead, edit premake.lua. The makefile will automatically rebuild itself whenever premake.lua is edited. Also handy.

ASP.NET

If your package is ASP.NET web application, you must also specify the URL used to access the site using the url variable.

package.url = "http://localhost/MyProject"

Package Paths

Like the project object, you can have Premake create the makefile, workspace, etc. in a different location by setting the path variable.

package.path = "../build_files"

Package IDs

Visual Studio requires a unique GUID for each package, which Premake will generate for your automatically. However, if you plan to check the generated Visual Studio project files into you SCC system, you may want to specify the IDs manually. Otherwise, the automated IDs, which are different on each run of Premake, will make it appear as if the project files have changed, even if all of the files and build settings are the same.

To specify a new GUID, set the package.guid property.

package.guid = "A5F26200-7A60-4726-AB0D-5D4D5B82B939"

You can get a GUID by running Microsoft’s GuidGen command line tool, or by running Premake once and copying the generated IDs out of the solution file.