User configuration

User configuration and preferences can be specified in a user provided configuration file, and usually also on the command line.

Values specified in a user provided configuration file override the defaults, while command line options take precedence over any other specified configurations.

Configuration file

Users can provide a configuration file to override parameters in the default configuration.

Unless a configuration file is explicitly specified on the command line when invoking bst, an attempt is made to load user specific configuration from $XDG_CONFIG_HOME/buildstream.conf. On most Linux based systems, the location will be ~/.config/buildstream.conf

Project specific value

The projects key can be used to specify project specific configurations, the supported configurations on a project wide basis are listed here.

Artifact server

The project you build will often specify a remote artifact cache already, but you may want to specify extra caches. There are two ways to do this. You can add one or more global caches:

Example

artifacts:
  url: https://artifacts.com/artifacts

Caches listed there will be considered lower priority than those specified by the project configuration.

You can also add project-specific caches:

Example

projects:
  project-name:
    artifacts:
      - url: https://artifacts.com/artifacts1
      - url: ssh://user@artifacts.com/artifacts2
        push: true

Caches listed here will be considered higher priority than those specified by the project.

If you give a list of URLs, earlier entries in the list will have higher priority than later ones.

Strict build plan

The strict build plan option decides whether you want elements to rebuild when their dependencies have changed. This is enabled by default, but recommended to turn off in developer scenarios where you might want to build a large system and test it quickly after modifying some low level component.

Example

projects:
  project-name:
    strict: False

Note

It is always possible to override this at invocation time using the --strict and --no-strict command line options.

Default Mirror

When using mirrors, a default mirror can be defined to be fetched first. The default mirror is defined by its name, e.g.

projects:
  project-name:
    default-mirror: oz

Note

It is possible to override this at invocation time using the --default-mirror command-line option.

Default configuration

The default BuildStream configuration is specified here for reference:

# Default BuildStream user configuration.

#
#    Work Directories
#
#
# Note that BuildStream forces the XDG Base Directory names
# into the environment if they are not already set, and allows
# expansion of '~' and environment variables when specifying
# paths.
#

# Location to store sources
sourcedir: ${XDG_CACHE_HOME}/buildstream/sources

# Location to perform builds
builddir: ${XDG_CACHE_HOME}/buildstream/build

# Location to store local binary artifacts
artifactdir: ${XDG_CACHE_HOME}/buildstream/artifacts

# Location to store build logs
logdir: ${XDG_CACHE_HOME}/buildstream/logs

#
#    Cache
#
cache:
  # Size of the artifact cache - BuildStream will attempt to keep the
  # artifact cache within this size.
  quota: infinity

#
#    Scheduler
#
scheduler:

  # Maximum number of simultaneous downloading tasks.
  fetchers: 10

  # Maximum number of simultaneous build tasks.
  builders: 4

  # Maximum number of simultaneous uploading tasks.
  pushers: 4

  # Maximum number of retries for network tasks.
  network-retries: 2

  # What to do when an element fails, if not running in
  # interactive mode:
  #
  #  continue  - Continue queueing jobs as much as possible
  #  quit      - Exit after all ongoing jobs complete
  #  terminate - Terminate any ongoing jobs and exit
  #
  on-error: quit


#
#    Logging
#
logging:

  # The abbreviated cache key length to display in the UI
  key-length: 8

  # Whether to show extra detailed messages
  verbose: True

  # Maximum number of lines to print from the
  # end of a failing build log
  error-lines: 20

  # Maximum number of lines to print in a detailed
  # message on the console or in the master log (the full
  # messages are always recorded in the individual build
  # logs)
  message-lines: 20

  # Whether to enable debugging messages
  debug: False

  # Format string for printing the pipeline at startup, this
  # also determines the default display format for `bst show`
  element-format: |

    %{state: >12} %{full-key} %{name} %{workspace-dirs}

  # Format string for all log messages.
  message-format: |

    [%{elapsed}][%{key}][%{element}] %{action} %{message}