Node:Options, Next:Environment variables, Previous:Running Transbuild, Up:Running Transbuild

Command line options

Transbuild is a program run from the command line. It recognises a number of options.

Command line options usually have a long form and a single character form following the GNU conventions (e.g. --verbose and -v). For a summary list of available options, use --help (or -h). On some platforms, only the short form is available.

The options are:

 -h, --help               prints a short
 -f, --file filename      read file as the build script
 -a, --all                force all files to be
 -k, --keep-going         keep going when source files match no rules
 -n, --dry-run            don't build files
 -i, --ignore-errors      ignore errors in file builds
 -d, --debug flags        print debug information
 -s, --silent, --quiet    don't print progress
 -v, --verbose            verbose
 -T, --target dir         target tree to use
 -S, --source dir         source tree to use
 -o, --options spec       set options
 -V, --version            show version information

-help, -h

This option displays a short summary of the available options and major environment variables used.

-file, -f

Specifies the filename of the build script. If this option is not present, the program will try to look for a file called Transbuild.xml from the current directory.

-all, -a

Force all files to be rebuild. By default only files which need to be updated are processed. It does not process a source file if its target file already exists and its modified time is after that of the source file.

The dependency checking very simplistic, assuming that a target file only depends on its one source file. It does not take into account annotations or any usage of the XPath document. The --all option is useful for rebuilding everything to ensure that all changes in the source tree have been incorporated.

Transbuild does not delete old files from the target directory. If source files are renamed or the rules for naming target files have been changed, there may be old files left lying around in the target tree. For this reason, it may be necessary to occasionally delete the entire target directory and completely regenerate it.

-keep-going, -k

Force Transbuild to ignore errors detected in the source tree during the first phase of processing. Normally, it is an error if a file in the source tree does not have a matching rule in the build script. This option causes Transbuild to ignores those files and not to generate an error.

This option controls error handling in the first processing phase. To control errors in the second phase, use the --ignore-errors option.

-dry-run, -n

Finds the rules for the source files and determines which ones need to be built, but do not perform the build. Only the first phase processing is performed. No rules are executed, and the target tree is left unchanged.

-ignore-errors, -i

Normally, when an error occurs during an execution of a rule the program stops running. This option indicates that it should not stop, but keep processing the other files.

This option controls error handling in the second processing phase. To control errors in the first phase, use the --keep-going option.

-debug, -d

Print out debug trace information. This option takes a comma separated list of flags to determine which debugging information to show. The available flags are:

script

Prints information from the parsed build script.

tree

Displays the source tree files and directories. An asterisk indicates that the target file is out-of-date or missing and needs to be rebuilt.

tree2

Shows extra details about the source tree: the last modified time of the source and the full path names of the source file and target file. This flag automatically enables the tree flag as well.

xml-load

Shows the annotations made to each XML file, and the files used in the annotations.

cache

Prints out XML cache statistics at the end of the run.

all

Enables all the above debug information.

If an unknown flag is supplied, an error will occur and a short summary of the available flags printed.

The debug information is printed to stderr.

-silent, -quiet, -s

Do not print out details of the build process. If this option is not specified, the first phase processing will print out information about how many files need to be rebuilt and the second phase processing will print out a message for each directory and file built.

-verbose, -v

Print out verbose messages while running.

Currently, this option has no effect because there are no verbose messages.

-target, -T

Specifies the target directory. This value will override any target directory specified in the build script.

-source, -S

Specifies the source directory. This value will override any source directory specified in the build script.

-options, -o

Used to specify configuration options. The argument is a comma separated list of name-value pairs (with the name and value separated by an equal sign).

charset

Specifies the operating system character set and encoding to use.

cachesize

Size of the XML cache, as a non-negative integer.

validate

Validate against DTDs if a DTD has been specified in the source XML files. Value must either be "yes" (the default) or "no." See the SGML_CATALOG_FILES environment variable for specifying where the DTDs can be found.

-version, -V

Prints the program name, version number and copyright message.