Developing extensions to the headless framework (Buckminster)

Adding a Headless Command

Not surprisingly, the framework deals with making it possible to add a new command, for example 'helloworld', so you can write

buckminster helloworld

The name, an optional namespace (in addition to the plugin namespace, which is always prefixed to the name) and 0-M aliases are declared in the extension point along with an implementation class. The implementation class must derive from the base class AbstractCommand. In principle, only the method 'run' needs to be overridden, but likely you wish to override others, for example to declare option support and callbacks for detection of them. Also, the declaration can tag the command as 'hidden' (works, but not shown on listings) or 'disabled' (doesn't work). Finally, you may indicate whether the framework should automatically add support for the option flags '-?' '--help' (recommended).

Assuming the framework manages the help options, you should add a file with the same name as the command class name, but with a '.help' extension with the help text.

As noted, the long name of a command is always prefixed with the plugin id. Thus, a plugin with the id 'org.somedomain.plugin' declaring a command with the name 'helloworld' and alias 'hw' will in reality be known as 'org.somedomain.plugin.helloworld' and 'org.somedomain.plugin.hw'. As another example, the name can contain further namespace levels - e.g. 'my.name.space.helloworld', leading to 'org.somedomain.plugin.my.name.space.helloworld'. However, note that any aliases do not contain a namespace — they will just work in the same namespace as the main/real name.

Commands are supposed to cooperate with some settings supplied by the framework (which may be reflections of user selections): currently this deals with a suggested location for storing tmp files, and an implementation of progress monitor to provide to lower layers. See the 'context' for details. What is this context? where can I read about it?

Commands can typically write freely to System.out and System.err. Note that both or either may have been trapped by the frameworks logging mechanism.

Example

Here is an example: Adding a helloworld headless command

Adding a headless preference mapping

Write this section

Adding a headless progress monitor extension

Write this section