This is an automated email from the ASF dual-hosted git repository. juergbi pushed a commit to branch jbilleter/doc-buildelement in repository https://gitbox.apache.org/repos/asf/buildstream.git
commit 1312bd8f51c3b70d3c96b75e4fc490dea8154f6c Author: Jürg Billeter <[email protected]> AuthorDate: Fri May 8 17:36:21 2026 +0200 docs: Move BuildElement's "Built-in functionality" to a new page The documentation of how to use the common features provided by the `BuildElement` base class is currently part of the API reference even though it's more relevant to project authors than plugin developers. This moves that section to a new page in the "Reference" section, next to other plugin-specific documentation. Co-authored-by: Dom Rodriguez <[email protected]> --- doc/source/core_buildelement.rst | 150 +++++++++++++++++++++++++++++++++++++++ doc/source/core_plugins.rst | 14 ++++ src/buildstream/buildelement.py | 137 +---------------------------------- 3 files changed, 166 insertions(+), 135 deletions(-) diff --git a/doc/source/core_buildelement.rst b/doc/source/core_buildelement.rst new file mode 100644 index 000000000..8f880e76f --- /dev/null +++ b/doc/source/core_buildelement.rst @@ -0,0 +1,150 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + +.. _core_buildelement_builtins: + +BuildElement - Built-in functionality +===================================== +The :doc:`manual <elements/manual>` core plugin and various common element plugins +available in other repositories are based on the :mod:`BuildElement <buildstream.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 +:doc:`API reference <buildstream.buildelement>`. + + +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 <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>`_ + + +Location for staging dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The BuildElement supports the "location" :term:`dependency configuration <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. + +.. code:: yaml + + # 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`` :term:`dependency configuration <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 <https://buildgrid.gitlab.io/recc>`_, +see ``remote-apis-socket`` in the :ref:`sandbox configuration <format_sandbox>`. + +**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. + +.. code:: yaml + + 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 <https://apache.github.io/buildstream-plugins/elements/autotools.html>`_, +`cmake <https://apache.github.io/buildstream-plugins/elements/cmake.html>`_, +`meson <https://apache.github.io/buildstream-plugins/elements/meson.html>`_, +`setuptools <https://apache.github.io/buildstream-plugins/elements/setuptools.html>`_ and +`pip <https://apache.github.io/buildstream-plugins/elements/pip.html>`_. + +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 <https://apache.github.io/buildstream-plugins/elements/autotools.html>`_ builds +where your source directory is separate from your build directory. + +This can be achieved in build elements which use ``conf-root`` as follows: + +.. code:: yaml + + 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 <https://apache.github.io/buildstream-plugins/elements/cmake.html>`_ +element will use it to specify the ``DESTDIR``. diff --git a/doc/source/core_plugins.rst b/doc/source/core_plugins.rst index 19080685d..a511d3b3a 100644 --- a/doc/source/core_plugins.rst +++ b/doc/source/core_plugins.rst @@ -27,8 +27,21 @@ given element specify their plugin specific configuration directly Elements -------- + + * :doc:`elements/stack` + * :doc:`elements/import` + * :doc:`elements/compose` + * :doc:`elements/script` + * :doc:`elements/link` + * :doc:`elements/junction` + * :doc:`elements/filter` + * :doc:`Build Elements <core_buildelement>` + + * :doc:`elements/manual` + .. toctree:: :maxdepth: 1 + :hidden: elements/stack elements/import @@ -37,6 +50,7 @@ Elements elements/link elements/junction elements/filter + Build Elements <core_buildelement> elements/manual diff --git a/src/buildstream/buildelement.py b/src/buildstream/buildelement.py index a5e6ed372..aebe5fb0b 100644 --- a/src/buildstream/buildelement.py +++ b/src/buildstream/buildelement.py @@ -20,141 +20,8 @@ The BuildElement class is a convenience element one can derive from for implementing the most common case of element. -.. _core_buildelement_builtins: - -Built-in functionality ----------------------- -The BuildElement base class provides built in functionality that could be -overridden by the individual plugins. - -This section 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 following -sections. - - -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 targetting 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>`_ - - -Location for staging dependencies -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The BuildElement supports the "location" :term:`dependency configuration <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. - -.. code:: yaml - - # 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`` :term:`dependency configuration <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 <https://buildgrid.gitlab.io/recc>`_, -see ``remote-apis-socket`` in the :ref:`sandbox configuration <format_sandbox>`. - -**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. - -.. code:: yaml - - 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 <https://apache.github.io/buildstream-plugins/elements/autotools.html>`_, -`cmake <https://apache.github.io/buildstream-plugins/elements/cmake.html>`_, -`meson <https://apache.github.io/buildstream-plugins/elements/meson.html>`_, -`setuptools <https://apache.github.io/buildstream-plugins/elements/setuptools.html>`_ and -`pip <https://apache.github.io/buildstream-plugins/elements/pip.html>`_. - -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 <https://apache.github.io/buildstream-plugins/elements/autotools.html>`_ builds -where your source directory is separate from your build directory. - -This can be achieved in build elements which use ``conf-root`` as follows: - -.. code:: yaml - - 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 <https://apache.github.io/buildstream-plugins/elements/cmake.html>`_ -element will use it to specify the ``DESTDIR``. +:doc:`Built-in functionality <core_buildelement>` +------------------------------------------------- Abstract method implementations
