It is possible to extend the capabilities of BuildCache with Lua. See lua-examples for some examples of Lua wrappers.
BuildCache first searches for Lua scripts in the paths given in the environment
variable BUILDCACHE_LUA_PATH (colon separated on POSIX systems, and semicolon
separated on Windows), and then continues searching in $BUILDCACHE_DIR/lua.
If no matching script file was found, BuildCache falls back to the built in
compiler wrappers (as listed above).
The first line of a Lua based program wrapper script must be a Lua comment with a special "match"-statement that specifies a regex that matches the name of the program that is to be wrapped, e.g:
-- match(gcc.*)More detailed checks can be done in the optional can_handle_command method.
The following methods can be implemented (see program_wrapper.hpp for a more detailed documentation):
| Function | Returns | Default |
|---|---|---|
| can_handle_command() | Can the wrapper handle this program? | true |
| resolve_args() | (nothing) | - |
| get_capabilities() | A list of supported capabilities | An empty table |
| get_build_files() | A table of build result files | An empty table |
| get_program_id() | A unique program identification | The MD4 hash of the program binary |
| get_relevant_arguments() | Arguments that can affect the build output | All arguments |
| get_relevant_env_vars() | Environment variables that can affect the build output | An empty table |
| get_input_files()* | Get the paths to the input files for the command | And empty table |
| preprocess_source() | The preprocessed source code (e.g. for C/C++) | An empty string |
| get_implicit_input_files()* | Get a list of paths to implicit input files (includes) | And empty table |
| run_for_miss() | A sys::run_result_t compatible table |
See note** |
*: get_input_files and get_implicit_input_files are only used in direct
mode, which requires that direct_mode is reported by get_capabilities.
**: run_for_miss, when defined, shall run the actual command (as specified by
ARGS) if a cache miss occurs. The return value shall be a table consisting of
std_out, std_err and return_code (see
sys::run_result_t). The default implementation is
equivalent to bcache.run(ARGS, false).
All program arguments are available in the global ARGS array (an array of
strings). ARGS[1] is the path to the program that is being wrapped.
To use Lua standard libraries (coroutine, debug, io, math, os,
package, string, table or utf8), you must first load them by calling
require_std(name). For convenience it is possible to load all standard
libraries with require_std("*"), but beware that it is slower than to load
only the libraries that are actually used.
There is a bcache library that exposes some of the internal BuildCache
functions that may be useful. To use the library, call require_std("bcache").
The following functions are available (for more detailed information, look up the corresponding C++ function documentation):
| Function | Description |
|---|---|
| dir_exists(path) | Check if a directory exists |
| file_exists(path) | Check if a file exists |
| get_dir_part(path) | Get the directory part of a path |
| get_extension(path) | Get the file extension of a path |
| get_file_info(path) | Get file information about a single file or directory |
| get_file_part(path, include_ext) | Get the file name part of a path |
| log_debug(str) | Print a log message with log level "DEBUG" |
| log_error(str) | Print a log message with log level "ERROR" |
| log_fatal(str) | Print a log message with log level "FATAL" |
| log_info(str) | Print a log message with log level "INFO" |
| log_warning(str) | Print a log message with log level "WARNING" |
| run(args) | Run the given command (passed as a list of arguments) |
| split_args(str) | Construct a list of arguments from a string with a shell-like format |