Project Configuration¶

The project configuration file should be named project.conf and be located at the project root. It holds information such as Source aliases relevant for the sources used in the given project as well as overrides for the configuration of element types used in the project.

Values specified in the project configuration override any of the default BuildStream project configuration, which is included here for reference.

Essentials¶

Project Name¶

The first thing to setup in your project.conf should be the name of your project.

name: my-project-name

The project name will be used in user configuration and anywhere that a project needs to be specified.

Format Version¶

The BuildStream format is guaranteed to be backwards compatible with any earlier releases. The project’s minimum required format version of BuildStream can be specified in project.conf with the format-version field, e.g.:

# The minimum base BuildStream format
format-version: 0

BuildStream will increment it’s core YAML format version at least once in any given minor point release where the format has been extended to support a new feature.

Note

Element and Source plugins also implement their own YAML configuration fragments and as such are revisioned separately from the core format. See External Plugins for details on specifying a minimum version of a specific plugin.

Element Path¶

To allow the user to structure their project nicely, BuildStream allows the user to specify a project subdirectory where element .bst files are stored.

element-path: elements

Note that elements are referred to by their relative paths, whenever elements are referred to in a .bst file or on the command line.

Source Aliases¶

In order to abstract the download location of source code and any assets which need to be downloaded, and also as a matter of convenience, BuildStream allows one to create named aliases for URLs which are to be used in the individual .bst files.

aliases:
  foo: git://git.foo.org/
  bar: http://bar.com/downloads/

Artifact Server¶

If you have setup an artifact server for your project then it is convenient to configure this in your project.conf so that users need not have any additional configuration to communicate with an artifact share.

artifacts:

  # A url from which to download prebuilt artifacts
  url: https://foo.com/artifacts

External Plugins¶

If your project makes use of any custom Element or Source plugins, then the project must inform BuildStream of the plugins it means to make use of and the origin from which it can be loaded.

Note that plugins with the same name from different origins are not permitted.

Core plugins¶

Plugins provided by the BuildStream core need not be explicitly specified here, but you may use this section to specify a minimal format version to ensure that they provide the features which your project requires.

plugins:
- origin: core

  # We require a new feature of the `git` source plugin, and
  # a new feature introduced in version 2 of the `patch` plugin.
  sources:
    git: 1
    patch: 2

  # ... And a new feature of the `script` element, added
  # in version 2 of it's own format version.
  elements:
    script: 2

Local Plugins¶

Local plugins are expected to be found in a subdirectory of the actual BuildStream project. Element and Source plugins should be stored in separate directories to avoid namespace collisions.

The versions of local plugins are largely immaterial since they are revisioned along with the project by the user, usually in a VCS like git. However, for the sake of consistency with other plugin loading origins we require that you specify a version, this can always be 0 for a local plugin.

plugins:

- origin: local
  path: plugins/sources

  # We want to use the `mysource` source plugin located in our
  # project's `plugins/sources` subdirectory.
  sources:
    mysource: 0

Pip Plugins¶

Plugins loaded from the pip origin are expected to be installed separately on the host operating system using python’s package management system.

plugins:

- origin: pip

  # Specify the name of the python package containing
  # the plugins we want to load. The name one would use
  # on the `pip install` command line.
  #
  package-name: potato

  # We again must specify a minimal format version for the
  # external plugin, it is allowed to be `0`.
  #
  elements:
    potato: 0

Options¶

Options are how BuildStream projects can define parameters which can be configured by users invoking BuildStream to build your project.

Options are declared in the project.conf in the main options dictionary.

options:
  debug:
    type: bool
    description: Whether to enable debugging
    default: False

Users can configure those options when invoking BuildStream with the --option argument:

$ bst --option debug True ...

Common Properties¶

All option types accept the following common attributes

type

Indicates the type of option to declare
description

A description of the meaning of the option
variable

Optionally indicate a variable name to export the option to. A string form of the selected option will be used to set the exported value.

If used, this value will override any existing value for the variable declared in project.conf, and will be overridden in the regular composition order.

Boolean¶

The bool option type allows specifying boolean values which can be cased in conditional expressions.

Declaring

options:
  debug:
    type: bool
    description: Whether to enable debugging
    default: False

Evaluating

Boolean options can be tested in expressions with equality tests:

variables:
  enable-debug: False
  (?):
  - debug == True:
      enable-debug: True

Or simply treated as truthy values:

variables:
  enable-debug: False
  (?):
  - debug:
      enable-debug: True

Exporting

When exporting boolean options as variables, a True option value will be exported as 1 and a False option as 0

Enumeration¶

The enum option type allows specifying a string value with a restricted set of possible values.

Declaring

options:
  loglevel:
    type: enum
    description: The logging level
    values:
    - debug
    - info
    - warning
    default: info

Evaluating

Enumeration options must be tested as strings in conditional expressions:

variables:
  enable-debug: False
  (?):
  - loglevel == "debug":
      enable-debug: True

Exporting

When exporting enumeration options as variables, the value is exported as a variable directly, as it is a simple string.

Flags¶

The flags option type allows specifying a list of string values with a restricted set of possible values.

In contrast with the enum option type, the default value need not be specified and will default to an empty set.

Declaring

options:
  logmask:
    type: flags
    description: The logging mask
    values:
    - debug
    - info
    - warning
    default:
    - info

Evaluating

Flags type options can be tested in conditional expressions using a pythonic in syntax to test if an element is present in a set:

variables:
  enable-debug: False
  (?):
  - ("debug" in logmask):
      enable-debug: True

Exporting

When exporting flags options as variables, the value is exported as a comma separated list of selected value strings.

Architecture¶

The arch type option is special enumeration option which defaults to the result of uname -m, and does not support assigning any default in the project configuration.

options:
  machine_arch:
    type: arch
    description: The machine architecture
    values:
    - arm
    - aarch64
    - i386
    - x86_64

Architecture options can be tested with the same expressions as other Enumeration options.

Element Mask¶

The element-mask option type is a special Flags option which automatically allows only element names as values.

options:
  debug_elements:
    type: element-mask
    description: The elements to build in debug mode

This can be convenient for automatically declaring an option which might apply to any element, and can be tested with the same syntax as other Flag options.

variables:
  enable-debug: False
  (?):
  - ("element.bst" in debug_elements):
      enable-debug: True

Specifying Defaults¶

The project.conf plays a role in defining elements by providing default values and also by overriding values declared by plugins on a plugin wide basis.

See the composition documentation for more detail on how elements are composed.

Variables¶

The defaults for Variables used in your project is defined here.

variables:
  prefix: "/usr"

Environment¶

The defaults environment for the build sandbox is defined here.

environment:
  PATH: /usr/bin:/bin:/usr/sbin:/sbin

Additionally, the special environment-nocache list which specifies which environment variables do not effect build output, and are thus not considered in the calculation of artifact keys can be defined here.

environment-nocache:
- MAXJOBS

Note that the environment-nocache list only exists so that we can control parameters such as make -j ${MAXJOBS}, allowing us to control the number of jobs for a given build without effecting the resulting cache key.

Split Rules¶

The project wide split rules defaults can be specified here.

split-rules:
  devel:
  - |
    %{includedir}
  - |
    %{includedir}/**
  - |
    %{libdir}/lib*.a
  - |
    %{libdir}/lib*.la

Element Overrides¶

Base attributes declared by element default yaml files can be overridden on a project wide basis. The elements dictionary can be used to override variables, environments or plugin specific configuration data as shown below.

elements:

  # Override default values for all autotools elements
  autotools:

    variables:
      bindir: "%{prefix}/bin"

    config:
      configure-commands: ...

    environment:
      PKG_CONFIG_PATH=%{libdir}/pkgconfig

Builtin Defaults¶

BuildStream defines some default values for convenience, the default values overridden by your project’s project.conf are presented here:

# Default BuildStream project configuration.


# Variable Configuration
#
variables:

  # Maximum number of parallel build processes within a given
  # build, support for this is conditional on the element type
  # and the build system used (any element using 'make' can
  # implement this).
  #
  # Note: this value defaults to the number of cores available
  max-jobs: 4

  # Path configuration, to be used in build instructions.
  #
  prefix: "/usr"
  exec_prefix: "%{prefix}"
  bindir: "%{exec_prefix}/bin"
  sbindir: "%{exec_prefix}/sbin"
  libexecdir: "%{exec_prefix}/libexec"
  datadir: "%{prefix}/share"
  sysconfdir: "/etc"
  sharedstatedir: "%{prefix}/com"
  localstatedir: "/var"
  lib: "lib"
  libdir: "%{prefix}/%{lib}"
  debugdir: "%{libdir}/debug"
  includedir: "%{prefix}/include"
  docdir: "%{datadir}/doc"
  infodir: "%{datadir}/info"
  mandir: "%{datadir}/man"

  # Indicates the default build directory where input is
  # normally staged
  build-root: /buildstream/build

  # Indicates the build installation directory in the sandbox
  install-root: /buildstream/install

  # Arguments for tooling used when stripping debug symbols
  objcopy-link-args: --add-gnu-debuglink
  objcopy-extract-args: |

    --only-keep-debug --compress-debug-sections

  strip-args: |

    --remove-section=.comment --remove-section=.note --strip-unneeded

  # Generic implementation for stripping debugging symbols
  strip-binaries: |

    find "%{install-root}" -type f \
      '(' -perm -111 -o -name '*.so*' \
          -o -name '*.cmxs' -o -name '*.node' ')' \
      -exec sh -ec \
      'read -n4 hdr <"$1" # check for elf header
       if [ "$hdr" != "$(printf \\x7fELF)" ]; then
           exit 0
       fi
       debugfile="%{install-root}%{debugdir}/$(basename "$1")"
       mkdir -p "$(dirname "$debugfile")"
       objcopy %{objcopy-extract-args} "$1" "$debugfile"
       chmod 644 "$debugfile"
       strip %{strip-args} "$1"
       objcopy %{objcopy-link-args} "$debugfile" "$1"' - {} ';'

  # Generic implementation for reproducible python builds
  fix-pyc-timestamps: |

    find "%{install-root}" -name '*.pyc' -exec \
      dd if=/dev/zero of={} bs=1 count=4 seek=4 conv=notrunc ';'


# Base sandbox environment, can be overridden by plugins
environment:
  PATH: /usr/bin:/bin:/usr/sbin:/sbin
  SHELL: /bin/sh
  TERM: dumb
  USER: tomjon
  USERNAME: tomjon
  LOGNAME: tomjon
  LC_ALL: C
  HOME: /tmp
  TZ: UTC

  # For reproducible builds we use 2011-11-11 as a constant
  SOURCE_DATE_EPOCH: 1320937200

# List of environment variables which should not be taken into
# account when calculating a cache key for a given element.
#
environment-nocache: []


# Defaults for the 'split-rules' public data found on elements
# in the 'bst' domain.
#
split-rules:

  # The runtime domain includes whatever is needed for the
  # built element to run, this includes stripped executables
  # and shared libraries by default.
  runtime:
  - |
    %{bindir}/*
  - |
    %{sbindir}/*
  - |
    %{libexecdir}/*
  - |
    %{libdir}/lib*.so*

  # The devel domain includes additional things which
  # you may need for development.
  #
  # By default this includes header files, static libraries
  # and other metadata such as pkgconfig files, m4 macros and
  # libtool archives.
  devel:
  - |
    %{includedir}
  - |
    %{includedir}/**
  - |
    %{libdir}/lib*.a
  - |
    %{libdir}/lib*.la
  - |
    %{libdir}/pkgconfig/*.pc
  - |
    %{datadir}/pkgconfig/*.pc
  - |
    %{datadir}/aclocal/*.m4

  # The debug domain includes debugging information stripped
  # away from libraries and executables
  debug:
  - |
    %{debugdir}
  - |
    %{debugdir}/**

  # The doc domain includes documentation
  doc:
  - |
    %{docdir}
  - |
    %{docdir}/**
  - |
    %{infodir}
  - |
    %{infodir}/**
  - |
    %{mandir}
  - |
    %{mandir}/**

  # The locale domain includes translations etc
  locale:
  - |
    %{datadir}/locale
  - |
    %{datadir}/locale/**
  - |
    %{datadir}/i18n
  - |
    %{datadir}/i18n/**
  - |
    %{datadir}/zoneinfo
  - |
    %{datadir}/zoneinfo/**

Project Configuration¶

Essentials¶

Project Name¶

Format Version¶

Element Path¶

Source Aliases¶

Artifact Server¶

External Plugins¶

Core plugins¶

Local Plugins¶

Pip Plugins¶

Options¶

Common Properties¶

Boolean¶

Enumeration¶

Flags¶

Architecture¶

Element Mask¶

Specifying Defaults¶

Variables¶

Environment¶

Split Rules¶

Element Overrides¶

Builtin Defaults¶

Table Of Contents

Related Topics