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

Note

If you have have multiple major versions of BuildStream installed, you can have separate configuration files in your ${XDG_CONFIG_HOME}.

You can do this by naming them according to the major versions of BuildStream you have installed. BuildStream 1 will load it’s configuration from $XDG_CONFIG_HOME/buildstream1.conf and BuildStream 2 will load it’s configuration from $XDG_CONFIG_HOME/buildstream2.conf, while any version will fallback to $XDG_CONFIG_HOME/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 in bytes - BuildStream will attempt to keep the
  # artifact cache within this size.
  # If the value is suffixed with K, M, G or T, the specified memory size is
  # parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base
  # 1024), respectively.
  # Alternatively, a percentage value may be specified, which is taken relative
  # to the isize of the file system containing the cache.
  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


#
# Build related configuration
#
build:

  #
  # Maximum number of jobs to run per build task.
  #
  # The default behavior when this is set to 0, is to use the
  # maximum number of threads available, with a maximum of 8.
  #
  max-jobs: 0


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