Chapter 29. Enhancing Abuild with Plugins

Table of Contents

29.1. Plugin Functionality
29.2. Global Plugins
29.3. Adding Platform Types and Platforms
29.3.1. Adding Platform Types
29.3.2. Adding Platforms
29.4. Adding Toolchains
29.5. Plugin Examples
29.5.1. Plugins with Rules and Interfaces
29.5.2. Adding Backend Code
29.5.3. Platforms and Platform Type Plugins
29.5.4. Plugins and Tree Dependencies
29.5.5. Native Compiler Plugins
29.5.6. Checking Project-Specific Rules
29.5.7. Install Target

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”.

29.1. Plugin Functionality

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 that is loaded by all make-based build items before their own files are loaded

  • Additional make code in that is loaded by all make-based build items after their own 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

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.