== Global Functions ==

The build process is about creating files from other files. Most of these processes are internal to the object, but it is possible to do some advanced configuration allowing the `wscript` writer to take more control over the build process. The functions described here should be considered advanced, and the beginning authors should not need to concern themselves with them initially.

cmd(cmd, [input files], **options)::
    The `cmd()` function specifies a command to be executed in the build directory and then a list of one or more dependent input files.
+
The first parameter to the function is the command string to execute, which is executed from the build directory. Placeholders within the string are replaced with filenames:

* `${TGT}` will be replaced by the name of the target file (which is given by the context of the `cmd()` function)
* `${SRC}` will be replace by the list of dependent input files
* `${SRC[n]}` will be replaced by the nth dependent input file (0 indexed)

+
There are various options that can be added to a `cmd()`:

    late;;
        If set to non zero, this says that the command should be executed as late in the sequence of commands to be run on a file as possible.

    targets;;
        This is a list of extra targets that this command generates. So a single command can create more than one file.

    shell;;
        If set, says that the command should not be broken on spaces into elements to pass to an exec call, but to be passed through the shell for shell processing. Use this if you use file redirection, for example.

create()::
    The `create()` function takes an initial parameter of the filename of the file to be created. The next parameter is a command to create the specified file. Usually this is a `cmd()` function. For example, consider a processing path on an input font:
+
[source,python,linenums]
----
source = create('xyz.ufo', cmd('myfirstprocess ${SRC} ${TGT}', ['infile.ufo']),
                           cmd('mysecondprocess ${DEP} ${TGT}'))
----

process()::
    This function does an in place modification of the first parameter file that is assumed to already exist. The remaining functions are used to process the file in place. Often this is a `cmd()` function, but some other file type specific functions do exist. For details of them, see the relevant component type section. To reference the temporary input file referenced, use `${DEP}`
+
[source,python,linenums]
----
target = process('outfile.ttf', cmd('ttfautohint ${DEP} ${TGT}'))
----
+
When `process()` is used on a source file, smith has to think a little harder.
smith works to a strict rule that no files are created or changed in the main
source tree. This means that smith cannot change a source file in its original
position. For similar reasons (which file should one read?), smith does not allow
there to be an identically named file with the same path in the source tree and
in the build tree. So we can't simply copy the source file into the build tree
and work on it there. Instead, smith creates a copy of the source file in the
buildtree by stripping its path component and storing it in the `tmp/`
directory. It then processes that in place. For the most part authors do not
have to consider this, and using `process()` on a source file will 'just work'.
But there are rare situations where knowledge of the underlying actions are
necessary.
+
Parameters for this function are:

    nochange;;
        If set, tells the system that there is no need to copy the dependency 
        file before running the task. This is an internal parameter that users
        are very unlikely to need to use.

test()::
    This function applies a process to its output file with no expected output, so any `cmd()` would only have a `${TGT}` in the string. Of course other dependent inputs may be used. This is used for running files through checking processes that can fail, and give reports.

getversion(format)::
    This function is designed to help generate a version string of your choosing. It gives access to various values
    that can be formatted using a format string. The default format string is: `dev-{vcssha:.6}{vcsmodified}`. This function
    supports git, mercurial and svn. If the command line option `--release` or `-r` is given, then this function will return
    different values. The keys for which there is access are:

    vcssha;;
        A unique identifier, depending on version control system for this commit. Blank if `--release`.

    vcsmodified;;
        If the current code is different from that committed at this version, this value is `M`. Blank if `--release`.

    buildnumber;;
        If being auto built, this is the build number

== Environment Variables ==

The following environment variables are supported by smith:

SMITHARGS::
    append this string to the end of each command line, e.g. -r
