Builder Plugins

***DRAFT: Related to https://github.com/evansde77/cirrus/pull/167 ***

Builders

Builders are responsible for creating, cleaning and activating test environments such as a virtualenv or conda environment. Since this can be quite heavily dependent on the machine the user is running on, these are plugins that can be switched in various ways, via CLI, .gitconfig or hinted at in a packages cirrus.conf.

Plugins

Plugin Documentation

• VirtualenvPipBuilder - Virtualenv/Pip Builder
• CondaPipBuilder - Conda/Pip Builder
• CondaBuilder - Conda and conda install Builder
• CondaEnvBuilder - Conda builder that uses conda environment definitions

Adding a plugin

To implement a new plugin, create a module in src/cirrus/plugins/builders and add an import of that module to the __init__.py in that module to register it with the plugin factory. The name of the Builder class will be the name of the plugin. The plugin should inherit cirrus.builder_plugin.Builder and implement the following methods:

• create - Used to build/rebuild or update the development environment (eg: create a venv and pip install requirements)
• clean - Used to remove the development environment (eg: rm venv)
• activate - return a shell command that activates the environment for sub commands

There is also a hook for processing plugin specific command line options for a builder plugin when invoked in the git cirrus build tool.

The Builder base class provides several helper attributes such as the cirrus package configuration instance, and the build subsection. Attributes include:

• self.config - this packages cirrus configuration
• self.build_config - this packages cirrus configuration build section
• self.working_dir - the top level working dir for this package
• self.venv_name - dev environment name (defaults to 'venv')
• self.reqs_name - requirements/dependency file name
• self.extra_reqs - list of additional requirement files (for eg test dependencies)
• self.python_bin - optional python binary to use for creating the dev environment
• self.venv_path - location of the dev environment for this package