Appendix F. --dump-data Format

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?,
<!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+)>
<!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?,
                      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.        -->
<!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