Tup supports writing build definitions using Lua. Tup uses a modified Lua 5.2 parser that supports all standard Lua syntax, with the addition of a new += operator. The statement a += b is equivalent to a = tup_append_assignment(a, b) where tup_append_assignment is a Lua function that, by default, concatenates strings or appends to tables. Tup also defines the tostring(argument) operation on tables with no metatable as table.concat(argument, ' ').
For each directory Tup scans, Tup looks for Tupfile.lua, or, if not present, a Tupdefault.lua file in the current directory or any parent directory up to the Tup root.
If a Tupfile.lua or Tupdefault.lua is found, Tup creates a Lua state and runs any Tuprules.lua files in the current directory and all parent directories up to the Tup root, then runs the located Tupfile.lua or Tupdefault.lua.
Non-Lua Tupfiles can include Lua files, which are able to read non-Lua variables when run.
Only a subset of the standard Lua library is defined, in order to prevent untracked dependencies. The standard library methods are filtered as follows:
Tup-specific functions are provided in the tup table. In the following documentation, PROCESSING refers to the directory Tup is currently processing, and RUNNING refers to the directory of the build definition file Tup is currently running. When Tup enters Tupfile.lua, PROCESSING and RUNNING are the same. When running Tuprules.lua, Tupdefault.lua, or an included file, PROCESSING AND RUNNING may be different.
Parses and runs the Lua file at path.
Defines a rule. See the Tup manual for more information on rules. command will be executed without any modifications, either directly or in a shell, in the directory PROCESSING. inputs and outputs are optional and are used to determine dependencies.
A wrapper for tup.definerule that performs substitutions on all parameters based on format patterns. Returns a table containing the filenames of all outputs.
If there is a single input, it can be specified as a string argument input, and a single output can be specified as string argument output. In addition to sequential, numerically indexed elements, input can contain a table at index 'extra_inputs', the elements of which are treated like normal inputs but are not used when substituting %f. Likewise, output can contain a table at index 'extra_outputs', the elements of which are treated like normal outputs but are not used when substituting %o. Be aware that you are using input and output as an argument to frule in that case, rather than inputs and outputs!
The substitutions are roughly the same as the substitutions in non-Lua Tupfile rules. See the Tup manual for more information on the format patterns.
A forwarding wrapper around tup.frule. inputs and outputs must always be tables, and command must be a string. Returns the result of tup.frule.
A forwarding wrapper around tup.frule. inputs and outputs must always be tables, and command must be a string. For each input INPUT, runs tup.frule with an input table containing INPUT and inputs.extra_inputs if present. Returns the aggregate result of all tup.frule calls.
Adds the environment variable named variable to the export list for future rules. See the Tup manual for more information.
Tells Tup to automatically generate a .gitignore file in PROCESSING which contains a list of the output files that are generated by Tup. See the Tup manual for more information.
Returns the relative path from PROCESSING to RUNNING.
Example: If /a/b/Tupfile.lua included /a/include.lua, tup.getcwd() would return the path ../.
Returns the name of RUNNING within RUNNING's parent directory.
Example: Running tup.getdirectory() in /a/b/Tupfile.lua would return b.
Returns a node variable referencing a file indicated by path relative to RUNNING. Calling tostring or concatenating the node variable with a string will convert the node variable to the relative path from RUNNING to the referenced file.
Example: A node variable created from path ./data.txt in /a/b/Tupfile.lua would resolve to ../b/data.txt in /a/c/Tupfile.lua.
Returns the value of the config item named 'CONFIG_' .. name or the empty string if the config item does not exist.
Returns a table of the relative paths of all files matching glob pattern pattern.
Modifies a by appending all elements of b.
Strips all parent directories from the path string filename and returns the result.
Strips all parent directories from the path string filename and the file extension (including the .), and returns the result.
Returns the extension in the filename filename (excluding the .) or the empty string if there is no extension.