A build forest is a collection of build trees that are connected to each other by virtue of one tree's root build item being referenced as a child of a build item in another tree in the forest. When abuild starts up, it looks for an Abuild.conf in the current directory. It then walks up the file system one directory at a time looking for additional Abuild.conf files. Eventually, it will either find the topmost Abuild.conf file, or it will find an Abuild.conf file that is not listed as a child of the next higher one. Whichever of these cases is found first, the resulting Abuild.conf file is the root of the build forest. The forest then consists of all the trees encountered by following all the child-dirs pointers from the forest root.

Note that, unlike with build items and trees, forests do not have names. Note also that, unlike with trees, there is no explicit marker of the root of a build forest. This is very important as it allows you to extend a forest from above without modifying the forest itself. For a more in-depth discussion, see Chapter 7, Multiple Build Trees.

Note that the hierarchy defined by the layout of build items in the file system is a file system hierarchy and nothing more. It doesn't have to have any bearing at all on the dependency relationships among the build items. That said, it is sensible to organize build items in a manner that relates to the architecture of the system, and this in turn usually has implications about dependencies. Still, it is important to keep in mind that abuild is not file-system driven but rather is dependency driven.