The --dump-data option outputs all the
information abuild knows about the build trees after reading all
the Abuild.conf files and performing all of
its validations. Its output is in an XML format that corresponds
to the following DTD. Comments in the DTD describe the meanings
of the fields. The DTD may be found in
doc/abuild_data.dtd in the abuild
distribution. For additional ways to use the build graph output,
see also Chapter 32, Sample XSL-T Scripts.
When there are no errors, the --dump-data output
always presents build trees and build items such that no
dependency reference is ever made to an item that has not already
been seen. (This does not apply to items referenced by
build-also since no dependency relationship
is implied in that case.) When there are errors, the
errors attribute to the
abuild-data element will be present and will
have the value 1. In this case, this guarantee
does not apply as the output may contain circular dependencies,
unknown build items, etc.
The contents of the abuild_data.dtd file are
included here for reference.
<!-- This DTD describes the format of abuild's dump-data output. -->
<!-- Inline comments explain the details. The file is called -->
<!-- abuild_data.dtd instead of abuild-data.dtd so we don't -->
<!-- accidentally ignore it because it matches the pattern -->
<!-- abuild-* (like abuild output directories). -->
<!-- By convention, we use "0" or "1" for boolean values. Some -->
<!-- boolean values are optional. In this case, omitted always -->
<!-- means "0". -->
<!ENTITY % boolean "(0|1)">
<!-- Whenever the target-type attribute appears, it may only -->
<!-- have one of these values. -->
<!ENTITY % target-type "(all|platform-independent|object-code|java)">
<!-- The version attribute is always "2". We will only -->
<!-- increment this if there is a change to the output such that -->
<!-- previously valid data is either no longer valid or is valid -->
<!-- but has different semantics. The version attribute was -->
<!-- incremented from "1" when a new build tree structure was -->
<!-- introduced in version 1.1. Adding new attributes with -->
<!-- default values, optional attributes, or optional elements -->
<!-- will not cause the version number to be increased. Code -->
<!-- that reads this output should be prepared to accept and -->
<!-- ignore unknown attributes or elements. The errors -->
<!-- attribute is present and has the value "1" whenever abuild -->
<!-- has detected errors. In this case, normal guarantees about -->
<!-- output consistency do not apply, and the output may contain -->
<!-- references to unknown build items, platform types, flags, -->
<!-- traits, etc. Abuild will still make every effort to -->
<!-- produce useful and coherent data and will also always -->
<!-- produce XML output that parses against this DTD. -->
<!ELEMENT abuild-data (platform-data, supported-traits?, forest+)>
<!ATTLIST abuild-data
version CDATA #REQUIRED
errors %boolean; #IMPLIED
>
<!-- The platform-data element provides information about all -->
<!-- platform types known and any platforms they contain. When -->
<!-- it appears directly under abuild-data, it refers to the -->
<!-- built-in platforms and platform types. When it appears -->
<!-- under build-tree, it refers to the platforms known to that -->
<!-- tree. This would include built-in platform information as -->
<!-- well as any platform information added by a plugin in that -->
<!-- tree. -->
<!ELEMENT platform-data (platform-type+)>
<!-- The platform-type element describes a platform type. When -->
<!-- used inside of platform-data, it gives the name of the -->
<!-- platform type, its target type, and the list of platforms -->
<!-- it contains. When used inside a build item, it just lists -->
<!-- a platform type on which that build item could be built. -->
<!ELEMENT platform-type (platform*)>
<!ATTLIST platform-type
name CDATA #REQUIRED
parent CDATA #IMPLIED
target-type %target-type; #IMPLIED
>
<!-- The selected attribute is present only when platform -->
<!-- appears inside of platform-type. In this case, it has the -->
<!-- value "1" when items in that platform type would always be -->
<!-- built on that platform (based on platform selection -->
<!-- criteria) and "0" otherwise. -->
<!ELEMENT platform EMPTY>
<!ATTLIST platform
name CDATA #REQUIRED
selected %boolean; #IMPLIED
>
<!-- Every build tree includes a list of traits that are allowed -->
<!-- on any items that appear natively to that build tree. -->
<!-- There is also an overall list of supported traits that are -->
<!-- available from the command line. This element lists all -->
<!-- traits when it appears under abuild-data and the traits -->
<!-- defined by any of the build tree or its externals when it -->
<!-- appears under build-tree. -->
<!ELEMENT supported-traits (supported-trait+)>
<!ELEMENT supported-trait EMPTY>
<!ATTLIST supported-trait
name CDATA #REQUIRED
>
<!-- forests are given IDs so that they may be referred to by -->
<!-- other forests and by build items. forests are always -->
<!-- output in an order such that no forest refers to a later -->
<!-- forest. Although not enforced by the DTD, readers may rely -->
<!-- on this if it is helpful. This constraint is satisfied -->
<!-- even with the errors attribute of the top-level element is -->
<!-- set. -->
<!ELEMENT forest (backing-area*, deleted-trees?, deleted-items?,
global-plugins?, build-tree+)>
<!ATTLIST forest
id ID #REQUIRED
absolute-path CDATA #REQUIRED
>
<!-- Each backing-area element contains a reference to a backing -->
<!-- area. It is omitted if there are no backing areas. -->
<!ELEMENT backing-area EMPTY>
<!ATTLIST backing-area
forest IDREF #REQUIRED
>
<!-- The deleted-trees and deleted-items elements contain a list -->
<!-- of build trees and build items that were deleted in this -->
<!-- forest. This information comes from Abuild.backing. -->
<!ELEMENT deleted-trees (deleted-tree+)>
<!ELEMENT deleted-tree EMPTY>
<!ATTLIST deleted-tree
name CDATA #REQUIRED
>
<!ELEMENT deleted-items (deleted-item+)>
<!ELEMENT deleted-item EMPTY>
<!ATTLIST deleted-item
name CDATA #REQUIRED
>
<!-- The global-plugins element contains a list of all plugins -->
<!-- that are declared as global in the forest. Such plugins -->
<!-- will also appear in the plugins element of every tree. -->
<!ELEMENT global-plugins (plugin+)>
<!-- One build-tree element appears for each build tree. -->
<!-- build-trees are output in dependency order such that no -->
<!-- build tree will depend on another build tree that has not -->
<!-- already been output. Readers may rely on this behavior if -->
<!-- it is helpful, unless the errors attribute of the top level -->
<!-- element is set. The home-forest and backing-depth -->
<!-- attributes have the same meaning as with build-item. See -->
<!-- its comment for a description. -->
<!ELEMENT build-tree (platform-data, supported-traits?, plugins?,
declared-tree-dependencies?,
expanded-tree-dependencies?,
omitted-tree-dependencies?,
build-item+)>
<!ATTLIST build-tree
name CDATA #REQUIRED
absolute-path CDATA #REQUIRED
home-forest IDREF #REQUIRED
backing-depth CDATA #REQUIRED
>
<!-- The plugins element contains a list of build items that are -->
<!-- declared as plugins in the tree. This includes any global -->
<!-- plugins. -->
<!ELEMENT plugins (plugin+)>
<!ELEMENT plugin EMPTY>
<!ATTLIST plugin
name CDATA #REQUIRED
>
<!-- declared-tree-dependencies contains the list of direct -->
<!-- dependencies in the order in which they were declared in -->
<!-- the Abuild.conf file. Additionally, any tree declared as a -->
<!-- global tree dependency will be included here as well. -->
<!ELEMENT declared-tree-dependencies (tree-dependency+)>
<!-- expanded-tree-dependencies contains the list of recursively -->
<!-- expanded tree dependencies in sorted order from least to -->
<!-- most dependent. In other words, if A depends on B and B -->
<!-- depends on C, A's expanded-tree-dependencies contains C, -->
<!-- and then B. -->
<!ELEMENT expanded-tree-dependencies (tree-dependency+)>
<!-- omitted-tree-dependencies contains the list of tree -->
<!-- dependencies that were declared optional and were not -->
<!-- present. -->
<!ELEMENT omitted-tree-dependencies (tree-dependency+)>
<!-- The tree-dependency element represents a single tree -->
<!-- dependency. -->
<!ELEMENT tree-dependency EMPTY>
<!ATTLIST tree-dependency
name CDATA #REQUIRED
>
<!-- One build-item element appears for each build-item. -->
<!-- build-items are output in dependency order such that no -->
<!-- build item will depend on another build item that has not -->
<!-- already been output. Readers may rely on this behavior if -->
<!-- it is helpful, unless the errors attribute of the top level -->
<!-- element is set. Note that there is no expectation of -->
<!-- dependency ordering for the build-also-items element since -->
<!-- the build-also key in Abuild.conf implies no dependency -->
<!-- relationship. -->
<!-- The attributes have the following meanings: -->
<!-- name: the name of the build item -->
<!-- description: an optional description of the build item for -->
<!-- informational purposes only -->
<!-- home-forest: a reference to the forest from which the build -->
<!-- item is resolved -->
<!-- absolute-path: the absolute path of the build item -->
<!-- backing-depth: the number of backing areas that have to be -->
<!-- crossed to reach this build item -->
<!-- has-shadowed-references: "1" if this build item uses any -->
<!-- plugins or dependencies that are shadowed by a tree that -->
<!-- backs to this item's tree. Items with shadowed references -->
<!-- are not able to be built. -->
<!-- visible-to: the scope at which this item is visible; -->
<!-- corresponds to the visible-to key in the Abuild.conf. If -->
<!-- absent, default visibility applies. -->
<!-- target-type: the target type of this build item -->
<!-- is-plugin: true if the item is used as a plugin by at least -->
<!-- one tree -->
<!-- serial true if the item is declared to be serial; absent -->
<!-- otherwise. -->
<!ELEMENT build-item (build-also-trees?, build-also-items?,
declared-dependencies?, expanded-dependencies?,
omitted-dependencies?,
platform-types?, buildable-platforms?,
supported-flags?, traits?)>
<!ATTLIST build-item
name CDATA #REQUIRED
description CDATA #IMPLIED
home-forest IDREF #REQUIRED
absolute-path CDATA #REQUIRED
backing-depth CDATA #REQUIRED
has-shadowed-references %boolean; "0"
visible-to CDATA #IMPLIED
target-type %target-type; #REQUIRED
is-plugin %boolean; #REQUIRED
serial %boolean; #IMPLIED
>
<!-- build-also-trees and build-also-items contain the list of -->
<!-- build trees/items named in the build-also key. Each item -->
<!-- appears in a nested build-also element. There is no -->
<!-- guarantee that the build item has appeared. Build-also -->
<!-- trees as well as the desc and with-tree-deps options were -->
<!-- added in abuild 1.1.4. For clarity, is-tree="1" always -->
<!-- appears with build also trees, and for backward -->
<!-- compatibility, the attribute is omitted for build also -->
<!-- items. -->
<!ELEMENT build-also-items (build-also+)>
<!ELEMENT build-also-trees (build-also+)>
<!ELEMENT build-also EMPTY>
<!ATTLIST build-also
name CDATA #REQUIRED
is-tree %boolean; "0"
desc %boolean; "0"
with-tree-deps %boolean; "0"
>
<!-- declared-dependencies contains the list of direct -->
<!-- dependencies in the order in which they were declared in -->
<!-- the Abuild.conf file. Any flags associated with direct -->
<!-- dependencies appear in a nested flag element. -->
<!ELEMENT declared-dependencies (dependency+)>
<!-- expanded-dependencies contains the list of recursively -->
<!-- expanded dependencies in sorted order from least to most -->
<!-- dependent. In other words, if A depends on B and B depends -->
<!-- on C, A's expanded-dependencies contains C, and then B. -->
<!-- Note that flags appear only with direct dependencies, so -->
<!-- nested dependencies here will never have flag attributes. -->
<!ELEMENT expanded-dependencies (dependency+)>
<!-- omitted-dependencies contains the names of any dependencies -->
<!-- that were declared "optional" and that do not exist. Such -->
<!-- items are not listed in declared-dependencies or -->
<!-- expanded-dependencies. Additionally, if they were listed -->
<!-- as referent items on any traits, they will have been -->
<!-- removed from there as well. -->
<!ELEMENT omitted-dependencies (dependency+)>
<!-- The dependency element represents a single dependency. For -->
<!-- direct dependencies declared with flags, the dependency -->
<!-- element will contain nested flag elements. Dependencies -->
<!-- that appear inside of expanded-dependencies never contain -->
<!-- flags elements since flags apply only to direct -->
<!-- dependencies. If a dependency is declared with a specific -->
<!-- platform type, the platform type appears in the -->
<!-- "platform-type" attribute. -->
<!ELEMENT dependency (flag*)>
<!ATTLIST dependency
name CDATA #REQUIRED
platform-type CDATA #IMPLIED
>
<!-- The flag element represents a single dependency flag. -->
<!ELEMENT flag EMPTY>
<!ATTLIST flag
name CDATA #REQUIRED
>
<!-- platform-types contains the list of platform types in the -->
<!-- order in which they appeared in the Abuild.conf. -->
<!ELEMENT platform-types (platform-type+)>
<!-- buildable-platforms contains the list of platforms on which -->
<!-- this item could be built. -->
<!ELEMENT buildable-platforms (platform+)>
<!-- supported-flags contains a list of flags that are supported -->
<!-- by this build item. -->
<!ELEMENT supported-flags (supported-flag+)>
<!ELEMENT supported-flag EMPTY>
<!ATTLIST supported-flag
name CDATA #REQUIRED
>
<!-- The traits element contains a list of traits that this -->
<!-- build item has. Any referent build items appear in nested -->
<!-- trait-referent elements. -->
<!ELEMENT traits (trait+)>
<!ELEMENT trait (trait-referent*)>
<!ATTLIST trait
name CDATA #REQUIRED
>
<!ELEMENT trait-referent EMPTY>
<!ATTLIST trait-referent
name CDATA #REQUIRED
>