executable

The executable command is used to run an arbitrary process. It forms the basis of all commands that involve running an external process. The success or failure of the command is determined by the exit code of the executed process (zero for success, non-zero for failure). The output of the command that is executed is captured as an artifact named "command output", with a single file "output.txt". A combination of the standard output and standard error streams for the process is captured into the file, so that errors appear in line with useful context. The output artifact may be post-processed just as any other artifact captured as part of the build. Full control over the working directory, arguments and environment for the executed process is provided.

Attributes

Attribute	Description	Required?	Default
args	A space-separated list of arguments to pass to the process. If you need to pass an argument containing a space, you must use an arg child element.	No
exe	The command to execute, which can be an absolute path, a path relative to the working directory, or the name of a file in the PATH.	Yes
force	If true, the command will run even if an earlier command failed.	No	false
input-file	The name of a file to feed as the input of the process.	No
name	The name of the command.	Yes (unless provided on a wrapping command element).
output-file	The name of a file that captures the standard output and error of the process. Note that these are always captured as an artifact: use this attribute as a replacement for shell redirection.	No
working-dir	Path to a directory to execute the process in, relative to the base directory for the recipe.	No	The base directory for the recipe.

Child Elements

Element	Description	Number
arg	Defines an argument to pass to the process. Arguments defined this way are passed in the order given, after all arguments defined in the `args` attribute. Only necessary when the argument contains a space.	0 or more
environment	Binds a value to a named variable in the child process' environment.	0 or more
process	Specifies a post-processor to apply to the output artifact from the child process.	0 or more

Examples

Run a custom build script:

<executable name="build" exe="bash" args="scripts/build.sh debug=true"/>

Execute make manually, passing environment variables, and apply a regular expression post-processor to the output:

<regex.pp name="compiler.pp">
    <pattern category="error" pattern=": error"/>
</regex.pp>

<recipe name="default">
    <executable exe="make" args="-f MyMakefile all">
        <environment name="BUILDMODE" value="debug"/>
        <process processor="${compiler.pp}"/>
    </executable>
</recipe>