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 30, Best Practices. If you think you may need to modify the main code of abuild itself, please see also Chapter 33, Abuild Internals. This section covers the most common uses for plugins. Examples of each topic presented may be found in Section 29.5, “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 tree
dependencies. In other words, if a tree your tree depends on
declares something as a plugin, it 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 tree dependencies 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 a tree dependency should
not necessarily cause that same set of restrictions to be applied
to the dependent tree. Plugins themselves are ordinary build
items and can be resolved in tree dependencies and backing areas
just like any other build item. This makes it possible for a
tree to provide a plugin without using it itself or for a build
tree to not use all plugins used by its tree dependencies.
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
toolchains directories containing
additional compiler support files
Additional make code in preplugin.mk that
is loaded by all make-based build items before their own
Abuild.mk files are loaded
Additional make code in plugin.mk that is
loaded by all make-based build items after their own
Abuild.mk files are loaded
Additional Groovy code in
preplugin.groovy that is loaded by all
Groovy-based build items before their own
Abuild.groovy files are loaded
Additional Groovy code in plugin.groovy
that is loaded by all Groovy-based build items after their own
Abuild.groovy files are loaded
Ant hook code in plugin-ant.xml that is used
as a hook file by all build items using the deprecated
xml-based ant framework.
Arbitrary hook code in preplugin-ant.xml
that is imported prior by all build items using the deprecated
xml-based ant framework prior to reading
Abuild-ant.properties.
Additionally, plugins may have rules
directories containing additional make
or Groovy rules files, as is true with
ordinary 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 a tree dependency.