Node:Processing rules, Previous:Build script, Up:Build script
Inside each rule, there are zero or more processing steps. Data is passed from one processing step to the next. The input to the first processing step is the raw data from the source file. The output from the last processing step is saved into the target file. The only exception is if there are no processing steps the output file is not created.
There are two types of data passed between processing steps: raw data and XML data. Raw data is arbitrary data that is stored in a file (it may be a text file, a binary file or even serialized XML). The XML data is parsed XML data (think of it as a DOM tree in memory).
You can arbitrarily mix processing steps, because they can
convert the input data into the required format. For example,
xslt will parse raw data input into XML before
applying the XSLT stylesheet, or system will
serialize XML input before running the command on it. The only
combination that is not permitted is two xml-load
steps in a row (once in XML form, it makes no sense to reload it).
Also, any conversion from raw data to XML data will only
work if the raw data is proper XML.
There are four processing steps. They can be used in any order, and repeated any number of times, in a rule (subject to any noted limitations).
The xml-load processing step converts raw
input data into XML data. It cannot accept XML data as input.
A significant feature of xml-load is that it
can add extra information to the parsed XML from other files. These
are known as annotations inside the xml-load
element. Annotations can be nested in other annotations.
Each annotation adds an element to the XML data from the
annotation namespace of
http://hoylen.com/ns/xmlns/2002/transbuild/annotation. Inside
that element, the matching annotation files are added.
The members annotation adds files from the current working directory whose name matches a given suffix. If the current source file's name matches, it too will be included in the annotation. They are ordered according to lexical order of the filenames.
The children annotation adds files of a given name from the immediate subdirectories under the current working directory. They are ordered according to the lexical order of the directory names.
The ancestors annotation adds all the files matching a given name from the list of directories above and including the current working directory. The are added in order, from the root of the source tree down to the current working directory.
The set of annotations immediately under the
xml-load element uses the directory containing the
source file being processed as the current working
directory. Annotations nested inside other annotations will use the
directory containing the file being annotated as the working
directory.
The current working directory can be changed using a
dir annotation element. This operates like a change
directory command, and it can be passed a directory relative to the
current directory or an absolute directory name based from the root of
the source tree.
By default, annotation files will be parsed as XML and appended
to the top XML element of the file being annotated. Only the contents
of the root element is added (comments and processing instructions not
inside the root element are ignored). This embedding behaviour can be
disabled, in which case it will simply add an empty element called
file from the Transbuild annotation namespace.
This is useful for annotations that obtain a list of non-XML files
(e.g. image files).
By default, annotation file elements and added root elements have
a source attribute to identify the source file. This attribute
is from the Transbuild annotation namespace. It can be omitted by
setting annotate-with-source to "no" it in the annotation.
All annotation elements can have an name attribute. This value
will be used to create a name in the annotation
element in the parsed data. The name attribute is
from the Transbuild annotations namespace. You can use it as a label
to distinguish between the different annotations.
See the tutorial and demonstrations for more discussions and examples of annotations.
The xslt processing step applies an XSLT
transformation to the input data, and produces XML data output. It
accepts both types of input data (automatically parsing raw input data
as XML before using it).
Parameters can be passed to the XSLT script using the
param element. Parameters can either be literal
string values or XPath expressions.
The system processing step applies a system
command to the input data, and produces raw data output. It accepts
both types of input data (automatically serializing XML input
data into a text stream).
The command must read its input from stdin and output its data to stdout. If the command does not terminate with a status of zero, Transbuild will exit with an error.
The command is executed from the directory where the build script resides.
The file-copy processing step indicates that
the input data should be copied to the target file. It used when the
source file is to be copied to the target file with no processing
performed on it (by creating a rule with a single
file-copy processing step in it.)