Fab Library 

fab.glob(pattern)

pattern: string: Glob pattern to match.
varargs: string: Glob patterns to ignore.
returns: string[]: List of found paths.

Matches a glob against the project root, excludes matches of ignore globs, returns the remaining matches.

-- Example usage
local c_files = fab.glob("**/*.c", "test/**/*.c")

fab.path_join(…)

varargs: string: Path components to join.
returns: string: Joined path.

Joins path components together using the golang filepath.Join function.

-- Example usage
local path = fab.path_join("/home", username, "project")

fab.path_abs(path)

path: string: Path to make absolute.
returns: string: Absolute path.

Make a relative path absolute based on the current directory (directory of the config) or return the original path if it already absolute. Uses the golang filepath.Abs function internally.

-- Example usage
local abs_path = fab.path_abs("test.c")

fab.path_rel(path)

path: string: Path to make relative.
returns: string: Relative path.

Make a path relative to the build directory. Uses the golang filepath.Rel function internally.

fab.string_split(str, sep, n)

str: string: String to split by separator.
sep: string: Separator to use.
n: number?: Number of substrings to return.
returns: string[]: Array of substrings.

Split a string by seprator. The n parameter defines how many substrings to return, negative values mean all of them.

fab.project_root()

returns: string: An absolute path to the root of the project.

-- Example usage
local something_file = fab.path_join(fab.project_root(), "support/something.txt")

fab.build_directory()

returns: string: An absolute path to the build directory.

fab.find_executable(search)

search: string: Executable name.
returns: Executable | nil: If the executable is found, it is returned, otherwise nil.

Searches the system for an executable. The default system search paths are used (for example, /bin and /usr/bin). Internally this uses the which golang package.

-- Example usage
local neofetch = fab.find_executable("neofetch")

fab.get_executable(path)

path: string: Path to an executable.
returns: Executable: Executable at the path.

Get an executable by path. Prefer find_executable, this is meant for more complex methods of finding the executable.

Hint: Can be used to turn an output into an executable.

fab.option(option, default)

name: string: The name of the option (unique and an identifier).
type: “string” | “number” | []string: The type of the option.
required: bool?: Whether the option is required.
returns: any: Value of the option, either nil or the value passed by the user.

Defines and returns the value of an option that can be passed to fab by the caller using the option CLI argument.

-- Example usage
local build_type = fab.option("buildtype", { "development", "release" }) or "development"

if build_type == "development" then
    ...
end

fab.source(path)

path: string: Path to a source file.
returns: Source: A Source representing the path given.

Ensures the path is a valid source file and turns it into a Source object.

-- Example usage
local c_sources = {}
for _, v in ipairs(fab.glob("*.c")) do
    table.insert(c_sources, fab.source(v))
end

fab.rule(config)

config: table: Rule configuration, described below.
returns: Rule: The Rule produced by the configuration.

Produces a rule based on the following options:

Key	Type	Required	Description
name	string	yes	Unique name of the rule (an identifier)
command	string \| (string \| Executable)[]	yes	Command invoked on a build of the rule
description	string \| (string \| Executable)[]	no	Description of one rule invocation
depstyle	“normal” \| “gcc” \| “clang” \| “msvc”	no	The type of dependency files generated by this rule
compdb	bool	no	Whether to generate the compilation db, defaults to false

The command and description allows for “embed variables”, the embeds take the following form: @EMBED@. The names of the embeds are case-insensitive. They are replaced by values passed at each invocation of a rule build. Fabricate supports a few special embeds:

Name	Description
`@IN@`	Source file path
`@OUT@`	Output file path
`@DEPFILE@`	Dependency file path

fab.dependency(name, url, revision)

name: string: Unique name of the dependency (an identifier).
url: string: Git URL to the repository of the dependency.
revision: string: Git revision to use. Can be commit hash, branch, tag, etc.
returns: Dependency: A Dependency representing the input parameters.

Defines a project dependency, in short these are just git repos that Fabricate handles. For more information check out the dependencies section.

-- Example usage
local stb = fab.dependency("stb", "https://github.com/nothings/stb.git", "master")