This is an automated email from the ASF dual-hosted git repository. juergbi pushed a commit to branch jbilleter/doc-buildelement-buildsteps in repository https://gitbox.apache.org/repos/asf/buildstream.git
commit 4808724f13b06993549862e243fbb7190c8e3835 Author: Jürg Billeter <[email protected]> AuthorDate: Fri May 29 16:47:15 2026 +0200 doc/source/core_buildelement.rst: Add 'Build steps' section Co-authored-by: Dom Rodriguez <[email protected]> --- doc/source/core_buildelement.rst | 94 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 90 insertions(+), 4 deletions(-) diff --git a/doc/source/core_buildelement.rst b/doc/source/core_buildelement.rst index 8f880e76f..78b3c3657 100644 --- a/doc/source/core_buildelement.rst +++ b/doc/source/core_buildelement.rst @@ -24,15 +24,101 @@ 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 :doc:`API reference <buildstream.buildelement>`. +.. contents:: + :local: -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. +Build steps +~~~~~~~~~~~ + +The sandbox is prepared +----------------------- + +The sandbox is prepared as a temporary filesystem, where build dependencies +are staged, along with their own runtime dependencies. This happens in +an abstract state, which can quickly spot repeated files and :ref:`overlaps <handling_files_overlaps>`. + +When a dependency is being staged, the produced artifact is added from the root +(``/``). This can be changed using the ``location:`` attribute, as described in +:ref:`location for staging dependencies <core_buildelement_dep_location>`. + +The sandbox root directory with the staged dependencies is read-only. + +After the dependencies are staged, BuildStream stages the sources in the +``build-root`` location. The actual location of this differs slightly +depending on the project file structure, which is why it is common to +see elements use the variable ``%{build-root}`` which resolves to the +correct location. + +Configure and build commands +---------------------------- + +Now that all dependencies and sources are staged in a temporary filesystem, +BuildBox uses this filesystem as root filesystem for the build :ref:`sandbox <sandboxing>`. + +The first commands to be run are configure commands and it is +recommended to include things like moving the sources about, generating +config files and other “configure” related actions into this section. +These should be the commands that can only be run once (for example a +folder can only be moved once), this is due to BuildStream +workspaces. + +.. note:: + + **Workspaces and configure commands** + + When a :ref:`workspace <developing_workspace>` is opened, + it stages all the sources for the indicated + element locally, then when doing a build of that element it uses these local + sources instead of pulling in fresh sources. Builds using workspaces only + run configure commands once, and any subsequent builds using the same + workspace will skip the configure commands step, therefore steps of the + build that can't be executed multiple times (without re-staging sources) + should be added to configure commands. + +After configure commands are run, then build commands are next. Build +commands are intended to contain the actual build process, for example +if the build uses ``make`` then this stage should run the +``make target`` command. + +Install commands and caching artifacts +-------------------------------------- + +Install and strip commands are the final commands that are run before BuildStream +collects the artifacts and closes the build sandbox. Install commands +should mainly be comprised of moving the built artifacts from the +``${build-root}`` to the ``${install-root}``. + +The `install-commands` should not clean up any of the sources, as they can be stored as a _buildtree_, which allows for introspection after the build. + +Directories can be created under the install location, for example +``%{install-root}/example/``, and these will be maintained when another +element depends on this one, for example this will become +``/example/``. + +Strip commands are run after install commands to strip debugging symbols of +binaries in the install root. Plugins are expected to use the ``strip-binaries`` +variable as strip command. That project 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 <https://freedesktop-sdk.io/>`_, you can take a look to them in their `project.conf <https://gitlab.com/freedesktop-sdk/freedesktop-sdk/blob/freedesktop-sdk-18.08.21/project.conf#L74>`_ +The contents of the install root are cached. BuildStream caches the +produced artifact to reduce the need to rebuild elements, instead it can +pull from this artifact cache. It will only rebuild an element if the +element file changes, or if the dependencies for an element changes. + +.. note:: + + BuildStream will also **cache build errors**, and if no file has changed + (including the dependencies) then BuildStream will display this cached error, + without attempting a rebuild. This is sometimes not the desired behaviour, + especially if the error was caused by a remote issue, like a source site + being temporarily unavailable. To force an attempted build use the + ``-r``/``--retry-failed`` option, documented :ref:`here <invoking_build>`. + + +.. _core_buildelement_dep_location: Location for staging dependencies ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
