Chapter 15. The Abuild.conf File

Table of Contents

15.1. Abuild.conf Syntax

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.

15.1. Abuild.conf Syntax

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=interface-flag arguments. This causes the 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=selector 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 -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=interface-flag option in their deps key. For more information, see Chapter 23, Interface Flags.


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=build-item option. For more information about traits, see Section 9.5, “Traits”.


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.