plugin system design

plugin system

doit has several components that can be extended and/or switched by users. As of today it is somewhat cumbersome to make use of this extension points as they require direct manipulation of doit API.

The plugin system goal is to easy the use and distribution of theses components without making it harder to write these components.

Candidates for plugin support are:

• command
• db-backend
• reporter
• runner
• task loader
• up-to-date checker

use-cases

1. private plugin

   A user creates a plugin that will only be used on his own project, this plugin wont be distributed. The plugin code is located inside the user's project.

2. public plugin

   This plugin is of general use and its author wishes to make it available to any doit user.

3. plugin extensible with other plugins

   A doit-plugin may require optional dependencies and needs to reuse doit's plugin mechanism to load and activate it's own plugins.

plugin design

explicit / auto-loaded

There are two styles of plugins.

• explicit - through some kind of configuration the user specifies which plugin should be loaded/activated.

• auto-loaded - after installing the plugin it is "automatically" to whatever project using doit in the system.

For doit initial implementation it was decided to use explicit style because:

• It is possible not only to control which plugin will be loaded but also enable the users pass configuration options to the plugin.

• auto-loaded plugins incur a costly "scan" operation to find all plugins or rely on a specific distribution system (like setuptools). Requiring on setuptools is already a blocker... It would also require authors of private plugins to create a setup.py for its own use, and thats certainly not desirable.

• Although the basic plugin system does not use setuptools by default. The usage of setuptools to auto-load plugins is still possible to be done in the future (but not the current focus). Patches welcome

configuration system

As of today doit has no real configuration system in place. dodo.py file might include a DOIT_CONFIG. dodo.py is an artifact used by the default task loader...

• being an artifact for a loader it means it used as part of a command, making it impossible to be used to include a plugin that implements a new command.
• not all commands use a task loader
• different task loaders might not have a dodo.py artifact at all.

So for the plugin system will require the addition of a doit.cfg file to hold plugin registration and general configuration.

With the introduction of doit.cfg, DOIT_CONFIG will be redundant. Use of both DOIT_CONFIG and doit.cfg can certainly be confusing but removing DOIT_CONFIG will cause backward compatibility problems and it can be handy sometimes.

TBD - doit.cfg will probably be available in 3 locations: project, user, and system levels.