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 artifact server is usually specified by the project you build, but it can be overridden on a per project basis using the same format described here.

Example

projects:
  project-name:
    artifacts:
      url: https://artifacts.com/artifacts

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 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

#
#    Scheduler
#
scheduler:

  # Maximum number of simultaneous source downloading tasks.
  fetchers: 10

  # Maximum number of simultaneous build tasks.
  builders: 4

  # Maximum number of simultaneous artifact 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

#
#    Artifacts
#
artifacts:

  # A url from which to push and pull prebuilt artifacts.
  # Some protocols only support pushing.
  url: ''

#
#    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} %{key} %{name} %{workspace-dirs}