Contributing to the UI

As we wish to cleanly separate BuildStream’s core from the frontend, anything user facing should be defined within the modules contained within the _frontend directory.

BuildStream’s frontend includes:

• Implementation of the command line interface (cli.py)

• Logline/text formatting (widget.py)

• The main application state (app.py) which initializes the stream to handle logging and user interactions.

• Colour profiles (profile.py)

• Rendering of the status bar (status.py)

• Autocompletion behaviour (completions.py)

The command line interface

All of BuildStream’s commands are defined within the module cli.py -, the main entry point which implements the CLI.

The command line interface is generated with Click - a third party Python package. Click is easy to use and automatically generates help pages.

When working with commands, please adhere to the following checklist:

1. All commands should be defined with a help text

2. The command should be placed within the appropriate sub group

   • If the command manipulates sources, it should be part of the Source subcommands.

   • If the command manipulates cached artifacts, it should be part of the Artifact subcommands.

   • If the command has anything to do with workspaces, it should be part of the Workspace subcommands.

3. If the command is intended to work with artifact refs as well as element names, the command’s argument should be “artifacts” as this supports the auto-completion of artifact refs.

4. The supported –deps options are: “run”, “build”, “all”, “plan” and “none”. These are always of type click.Choice and should always be specified with a default. If the default is “none”, note that we use the string “none”, not the Python built-in None. In addition to this, the show_default flag should be set to True.

5. Commands should use the app and go through the stream (via a similarly named method within Stream) in order to communicate to BuildStream’s core.

Displaying information

Output which we wish to display to the user from the frontend should use the implemented classes in widget.py. This module contains classes which represent widgets for displaying information to the user.

To report messages back to the frontend, we use the Message() object which is available from the Context.

Supported message types are defined in _message.py and various uses of the messenger are defined in _messenger.py

The Messenger class defines various methods which allow us to report back to the frontend in particular ways. The common methods are:

• Messenger.message() - the central point through which all messages pass

• Messenger.timed_activity() - a context manager for performing and logging timed activities.

• Messenger.simple_task() - a Context manager for creating a task to report progress too.