BuildElement - Built-in functionality

The manual core plugin and various common element plugins available in other repositories are based on the BuildElement base class, which provides built in functionality that could be overridden by the individual plugins.

This page will give a brief summary of how some of the common features work, some of them or the variables they use will be further detailed in the API reference.

The strip-binaries variable

The strip-binaries variable is by default empty. You need to use the appropiate commands depending of the system you are building. If you are targeting Linux, ones known to work are the ones used by the freedesktop-sdk, you can take a look to them in their project.conf

Location for staging dependencies

The BuildElement supports the “location” dependency configuration, which means you can use this configuration for any BuildElement class.

The “location” configuration defines where the dependency will be staged in the build sandbox.

Example:

Here is an example of how one might stage some dependencies into an alternative location while staging some elements in the sandbox root.

# Stage these build dependencies in /opt
#
build-depends:
- baseproject.bst:opt-dependencies.bst
  config:
    location: /opt

# Stage these tools in "/" and require them as
# runtime dependencies.
depends:
- baseproject.bst:base-tools.bst

Note

The order of dependencies specified is not significant.

The staging locations will be sorted so that elements are staged in parent directories before subdirectories.

digest-environment for dependencies

The BuildElement supports the digest-environment dependency configuration, which sets the specified environment variable in the build sandbox to the CAS digest corresponding to a directory that contains all dependencies that are configured with the same digest-environment.

This is useful for REAPI clients in the sandbox such as recc, see remote-apis-socket in the sandbox configuration.

Example:

Here is an example of how to set the environment variable GCC_DIGEST to the CAS digest of a directory that contains gcc.bst and its runtime dependencies. The libpony.bst dependency will not be included in that CAS directory.

build-depends:
- baseproject.bst:gcc.bst
  config:
    digest-environment: GCC_DIGEST
- libpony.bst

Location for running commands

The command-subdir variable sets where commands will be executed, and the directory will be created automatically if it does not exist.

The command-subdir is a relative path from %{build-root}, and cannot be a parent or adjacent directory, it must expand to a subdirectory of ${build-root}.

Location for configuring the project

The conf-root is the location that specific build elements can use to look for build configuration files. This is used by elements such as autotools, cmake, meson, setuptools and pip.

The default value of conf-root is defined by default as .. This means that if the conf-root is not explicitly set to another directory, the configuration files are expected to be found in command-subdir.

Separating source and build directories

A typical example of using conf-root is when performing autotools builds where your source directory is separate from your build directory.

This can be achieved in build elements which use conf-root as follows:

variables:
  # Specify that build configuration scripts are found in %{build-root}
  conf-root: "%{build-root}"

  # The build will run in the `_build` subdirectory
  command-subdir: _build

Install Location

Build elements must install the build output to the directory defined by install-root.

You need not set or change the install-root variable as it will be defined automatically on your behalf, and it is used to collect build output when creating the resulting artifacts.

It is important to know about install-root in order to write your own custom install instructions, for example the cmake element will use it to specify the DESTDIR.