Table of Contents
This chapter is geared toward people who may extend or enhance abuild by adding additional rules, platforms, or compilers. Anyone interested in extending abuild in this way should also be familiar with the material covered in Chapter 27, Best Practices. If you think you may need to modify the main code of abuild itself, please see also Chapter 29, Abuild Internals. This section covers the most common uses for plugins. Examples of each topic presented may be found in Section 26.4, “Plugin Examples”.
Plugins are build items that are named in the build tree root's
Abuild.conf in the
plugins key. The list of which items are
plugins is not inherited through either backing areas or
externals. In other words, having your external declare
something as a plugin does not automatically make you get it as a
plugin. The same applies to backing areas, but in practice, the
list of plugins is generally effectively inherited because your
local build tree's Abuild.conf is typically
a copy of its backing area's Abuild.conf,
assuming your partially populated build tree was checked out of
the same version control system. The non-inheritance of plugin
status through externals is appropriate: since plugins can change
abuild's behavior significantly, it should be possible for a
given build tree to retain tight control over which plugins are
active and which are not. For example, a build tree may include
a plugin that enforces certain coding practices by default, and
use of this build tree as an external should not necessarily
cause that same set of restrictions to be applied to the tree
that is using it. Plugins themselves are ordinary build items
and can be resolved in externals and backing areas just like any
other build item. This makes it possible for an external to
provide a plugin without using it itself or for a build tree to
not use all plugins used by its externals.
Plugins are loaded by abuild and its backends in the order in
which they are listed in a root build item's
Abuild.conf. Usually this doesn't matter,
but if multiple plugins add native compilers the order in which
plugins are listed can have an effect on which platforms are
built by default.
Plugins are subject to the following constraints beyond those imposed upon all build items:
Plugins may not have any forward or reverse dependencies. It
is good practice to put plugin build items in a private
namespace (such as prefixing their names with
plugin.) to prevent people from
accidentally declaring dependencies on them.
Plugins may not belong to a platform type, have a build file,
or have an Abuild.interface file.
Plugins may contain the following items that are not supported for ordinary build items:
Abuild interface code loaded from
plugin.interface
A platform-types file to add new object-code
platform types
A list_platforms perl script to add new object-code platforms
rules directories containing additional
make rules
files
toolchains directories containing
additional compiler support files
Additional make code in plugin.mk that is
loaded by all make-based build items
Ant hook code in plugin-ant.xml that is used
as a hook file by all ant-based build items.
Although plugins themselves can never be dependencies of other build items or have dependencies of their own, they are still subject to abuild's integrity guarantee. In the case of plugins, this means that it is impossible to have an item in your dependency tree whose build tree declares a plugin that you are shadowing in your local tree. One way to avoid having this become a significant limitation is to keep your plugins in a separate build tree that others declare as an external.