Table of Contents
The Abuild.conf
file is the fundamental
configuration file that describes each build item and the
relationships between build items. It contains information about
dependencies, file system locations, and platform support. It
explicitly does not contain any information about how to build a
particular build item or what targets are built.
Every build item must contain Abuild.conf
.
The Abuild.conf
file is a simple text file
consisting of colon-separated key/value pairs. Blank lines and
lines that start with #
are ignored. Long
lines may be continued to the next line by ending them with a
backslash character (\
). Certain keys are
permitted for some kinds of build items and not for others. For a
discussion of different types of build items, please see Section 4.5, “Special Types of Build Items”.
The following keys are supported in
Abuild.conf
:
This is a “catch-all” key whose value is a list of white-space separate keywords that assign certain specific attributes to a build item. The following attributes are supported:
serial: valid only for build items
that are built using the make
backend, where it prevents the
--make-jobs
option from applying to that
build item, effectively forcing it to build serially
This key contains a list of whitespace-separated build items. Whenever abuild adds a given item to a build set, it also adds any items listed in its build-also key to the build set. No dependency relationship or any other relationship is implied. This is useful for creating pseudo-top-level build items that serve as starting points for multiple builds.
This key is used to specify all subdirectories of this item
that contain additional Abuild.conf
files. The value is a whitespace-separated list of relative
paths, each of which must point down in the file system.
A child directory may be followed by the
-optional
flag, in which case abuild will
not complain if the directory doesn't exist. This can be
especially useful for high-level
Abuild.conf
files whose children may
correspond to optional dependencies, optional build trees, or
self-contained trees that may or may not be included in a
particular configuration.
If a child directory contains more than one path element, the
intermediate directories may not contain their own
Abuild.conf
files. (In other words, you
can't skip over a directory that has an
Abuild.conf
file in it.)
This key's value is a whitespace-separated list of the names
of build items on which this build item depends. This is the
sole mechanism within abuild to specify inter-build-item
dependencies. Any dependency in this list may be optionally
followed by one or more
-flag=
arguments. This causes the
interface-flag
interface-flag
interface flag to
be set when this build item reads the interface of the
dependency (see Chapter 23, Interface Flags). It
is also possible to specify a
-platform=
option to a dependency to specify which of the dependency's
platforms applies to this dependency (see Section 24.3, “Explicit Cross-Platform Dependencies”). Dependencies
may be specified as optional by following the dependency name
with the selector
-optional
flag (see Chapter 28, Optional Dependencies).
This key can be used to add an information description to the
build item. Description information is intended to be human
readable. If present, it will be included in the output to
abuild --dump-data. Providing a
description here rather than just by using a comment in the
Abuild.conf
file can be useful to other
programs that provide additional visualization of build
items. For adding information that you may wish to
categorize items for build purposes, use traits instead (see
Section 9.5, “Traits”). The description field is only
permitted for named build items, though comments may appear
in any Abuild.conf
file.
This key is used to set the name of the build item. Build
item names consist of period-delimited segments. Each
segment consists of one or more alphanumeric characters,
dashes, or underscores. Some
Abuild.conf
files exist just to connect
parent directories with child directories in the file system.
In those cases, the name key may be
omitted. The name key is also optional
for root build items that don't build anything themselves.
This key is used to specify which platform types a given build item is expected to work on. It includes a whitespace-separated list of platform types. For details about platform types, see Chapter 5, Target Types, Platform Types, and Platforms. If a build item has a build file or an interface file, the platform-types key is mandatory. Otherwise, it must not be present. Note that a build item may have multiple platform types, but all platform types for a given build item must belong to the same target type.
This key is valid only in a root build item. It is used to
specify the list of build items that are treated plugins by
this tree. For information about plugins, see Chapter 29, Enhancing Abuild with Plugins. A plugin name may be followed by
the option -global
which makes it apply to
all build trees in the forest. Use this feature very
sparingly. For details, see Section 29.2, “Global Plugins”.
This key contains a list of whitespace-separated flags that
are supported by this build item. When a flag is listed
here, it becomes available to this item's
Abuild.interface
file for flag-specific
variable assignments. Other items can specify that this flag
should be turned on when they depend on this item by using
the
-flag=
option in their deps key. For more
information, see Chapter 23, Interface Flags.
interface-flag
This key is allowed only in a root build item. It contains a list of whitespace-separated traits that are supported by build items in the build tree. For more information about traits, see Section 9.5, “Traits”.
This key contains a list of whitespace-separated traits that
apply to this build item. A trait may be referent to one or
more additional build items. To name a referent build item,
follow the trait with the
-item=
option. For more information about traits, see Section 9.5, “Traits”.
build-item
This key is valid only in a root build item. It contains a
list of the names of trees on which this tree depends. For
information about tree dependencies, see Chapter 7, Multiple Build Trees. Tree dependencies may be
declared optional by following the name of the dependency
with -optional
(see Chapter 28, Optional Dependencies).
The presence of this key establish a build item as a root build item. This key's value is the name of the build tree. Build trees must be named uniquely in a forest. Build tree names may consist of alphanumeric characters, underscore, dash, and period. Unlike with build item names, there is no hierarchical or scoping structure implied by any of the characters in the names of build trees.
This key's value is an indicator of the scope at which this build item is visible. If present, it allows build items in the named scope to access this build item directly when they would ordinarily be prevented from doing so by normal scoping rules. For information about build item name scopes and build item visibility, see Section 6.3, “Build Item Name Scoping”. For a discussion of the visible-to key in particular, see Chapter 25, Build Item Visibility
Note that the child-dirs keys is the only key that deals with paths rather than names.