13.4. Control Options

These options change some aspect of how abuild starts or runs.

-C start-directory

Change directories to the given directory before building.

--clean-platforms=pattern

Specify a pattern that restricts which platform directories
are removed by any abuild clean operation. This argument
may be repeated any number of times. The
pattern given can be any valid
shell-style wild-card expression. Any output directory
belonging to any pattern that matches any of the given clean
patterns will be removed. All other output directories will
be left alone. This can be useful for removing only output
directories for platforms we no longer care about or for other
selective cleanup operations.

--compat-level=version

Set abuild's compatibility level to the specified version,
which may be either 1.0 or
1.1. You may also place the compatibility
level version in the ABUILD_COMPAT_LEVEL
environment variable. By default, early pre-release versions
of abuild attempt to detect deprecated constructs from older
versions and issue warnings about their use, while final
versions operate with deprecation support disabled by default.
Setting the compatibility level to a given version causes
abuild to not recognize constructs deprecated by that
version at all. For example, in compatibility level
1.1, use of the this
key in Abuild.conf would result in an
error about an unknown key rather than being treated as if it
were name, and the make variable
BUILD_ITEM_RULES would be treated like any
ordinary variable and would not influence the build in any
way. See also --deprecation-is-error.

--deprecation-is-error

Ordinarily, abuild detects deprecated constructs, issues
warnings about them, and continues operating by mapping
deprecated constructs into their intended replacements. When
this option is specified, any use of deprecated constructs are
detected and reported as errors instead of warnings. Note
that this is subtly different from specifying
--compat-level with the current major and
minor versions of abuild. For example, if
--deprecation-is-error is specified, use of
the make variable BUILD_ITEM_RULES will
result in an error message, while if
--compat-level=1.1 is specified, the variable
will simply be ignored. A good upgrade strategy is to use
--deprecation-is-error to first test to make
sure you've successfully eliminated all deprecated constructs,
and then to use --compat-level (or to set the
ABUILD_COMPAT_LEVEL environment variable) to
turn off abuild's backward compatibility support, if
desired.

-e | --emacs

Tell ant to run in emacs mode by passing the
-e flag to it and also setting the property
abuild.private.emacs-mode. Ant targets can
use this information to pass to programs whose output may need
to be dependent upon whether or not emacs mode is in effect.

--find-conf

Locates the first directory at or above the current directory
that contains an Abuild.conf file, and
changes directories to that location before building.

--full-integrity

Performs abuild's integrity checks for all items in the
local tree, tree dependencies, and backing areas. Ordinarily,
abuild performs its integrity check only for items that are
being built in the current build. The
--full-integrity flag would generally be
useful only for people who are maintaining backing areas that
are used by other people. For detailed information about
abuild's integrity checks, please see Section 11.3, “Integrity Checks”.

-jn| --jobs=n

Build up to n build items in parallel by
invoking up to n simultaneous instances
of the backend. Does not cause the backend to run multiple
jobs in parallel. See also --make-jobs.

--jvm-append-args ... --end-jvm-args

Appends any arguments between
--jvm-append-args and
--end-jvm-args to the list of extra arguments
that abuild passes to the JVM when it invokes the java
builder backend. This option is intended for use in debugging
abuild. If you have to use it to make your build work,
please report this as a bug.

--jvm-replace-args ... --end-jvm-args

Replaces abuild's internal list of extra JVM arguments with
any arguments between --jvm-replace-args and
--end-jvm-args. This option is intended for
use in debugging abuild. If you have to use it to make your
build work, please report this as a bug.

-k | --keep-going

Don't stop the build after the first failed build item, but
instead continue building additional build items that don't
depend on any failed items. Also tells backend to continue
after its first failure. Even with -k,
abuild will never try to build an item if any of its
dependencies failed. This behavior may be changed by
also specifying --no-dep-failures.

Allow make to run up to n jobs in parallel.
Omit n to allow make to run as many jobs as
it wants. Be aware that if this option is used in combination
with --jobs, the total number of threads
could potentially be the product of the two numerical
arguments.

Note that certain types of make rules and certain may cause
problems for parallel builds. For example, if your build
involves invoking a compiler or other tool that writes poorly
named temporary files, it's possible that two simultaneous
invocations of that tool may interfere with each other.
Starting with abuild 1.1, it is possible to place
attributes: serial in a make-based build
item's Abuild.conf file to prevent
--make-jobs from applying to that specific
item. This will force serial compilation of items that you
know don't build properly in parallel. This can be useful for
build items that use the autoconf rules,
which are known to sometimes cause trouble for parallel
builds.

Must be combined with -k. By default,
abuild does not attempt to build any items whose
dependencies have failed even if -k is
specified. When the --no-dep-failures option
is specified along with -k, abuild will
attempt to build items even if one or more of their
dependencies have failed. Using -k and
--no-dep-failures together enables abuild
to attempt to build everything that the backends will allow.
Note that cascading errors (i.e., errors
resulting from earlier errors) are likely when this option is
used.

--platform-selector=selector | -p selector

Specify a platform selector. This argument may be repeated
any number of times. Later instances supersede earlier ones
when they specify selection criteria for the same platform
type. When two selectors refer to different platform types,
both selectors are used. Platform selectors may also be given
in the ABUILD_PLATFORM_SELECTORS environment
variable. For details on platform selectors, see Section 24.1, “Platform Selection”.