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:
All commands should be defined with a help text
The command should be placed within the appropriate sub group
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.
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_defaultflag should be set to
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.
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
which is available from 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.