.. _config-obj:

============
Object Types
============

There are a number of opaque *objects* (really `userdata <https://www.lua.org/pil/28.1.html>`_) that fabricate defines.
They are used both for convenience and correctness.

.. _config-obj-executable:

Executable
==========
Represents an executable.

.name: string
-------------
The basename of the binary.

.path: string
-------------
Absolute path to the executable.

:invoke(...)
------------
varargs: string
    Arguments to invoke the executable with.
returns: string
    Stdout produced by the executable.

Invokes (executes) the executable with given arguments. If the invocation fails, Fabricate will panic. Stderr is passed through and Stdout is captured into the return.

.. _config-obj-source:

Source
======
Represents a singular source file. Source files have to be located within the project root or within the root of a dependency.

.name: string
-------------
Filename of the source file.

.path: string
-------------
Absolute path of the source file.

.. _config-obj-rule:

Rule
========
Represents a :ref:`ninja <ninjaa>` rule. This is the core object type that Fabricate builds generators, compilers, assembler, and linkers on.

.name: string
-------------
Unique name of the rule.

:build(output, input, variables)
--------------------------------
output: string
    The filename (or relative path) of the output file generated by this build.
input: (Source | Output)[]
    The inputs used.
variables: { [string]: string }
    The variable values.
returns: Output
    Output object representing the produced file.

Builds the rule once into a named output file with given sources.
The variables are :ref:`described <config-fab-rule-embeds>` when the rule is defined and are embedded into the invocation.

.. _config-obj-output:

Output
======
Represents an output file.

.name: string
-------------
Filename of the output file.

.path: string
-------------
Absolute path to the output file.

:install(dest)
--------------
dest: string
    Path to install the output at.

Tells fabricate to install an output when the :ref:`install <cli-subcommand-install>` subcommand is invoked.
The path is relative to the :ref:`prefix <cli-flag-prefix>`.

.. _config-obj-dependency:

Dependency
==========
Represents a downloaded dependency. See the :ref:`dependencies <dependencies>` section.

.name: string
-------------
Name given to the dependency.

.url: string
------------
The git URL of the dependency.

.revision: string
-----------------
The git revision of the dependency.

.path: string
-------------
Absolute path to the downloaded dependency.

:glob(pattern, ...)
-------------------
pattern: string
    Glob pattern to match.
varargs: string
    Glob patterns to ignore.
returns: string[]
    List of found paths.

Practically identical to :ref:`fab.glob <config-fab-glob>` except relative to the directory of the downloaded dependency.