Skip to content

Commit 0d76666

Browse files
shymega-ctshymega-ct
committed
docs: Move BuildElement's "Built-in functionality" to new doc page
1 parent e4dcda0 commit 0d76666

2 files changed

Lines changed: 156 additions & 133 deletions

File tree

‎doc/source/using_buildelement.rst‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
..
2+
Licensed under the Apache License, Version 2.0 (the "License");
3+
you may not use this file except in compliance with the License.
4+
You may obtain a copy of the License at
5+
6+
http://www.apache.org/licenses/LICENSE-2.0
7+
8+
Unless required by applicable law or agreed to in writing, software
9+
distributed under the License is distributed on an "AS IS" BASIS,
10+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11+
See the License for the specific language governing permissions and
12+
limitations under the License.
13+
14+
15+
.. _commands:
16+
17+
Using BuildElements
18+
===================
19+
This page contains documentation about the built-in functionality of
20+
``BuildElement`` and how to use them.
21+
22+
23+
Built-in functionality
24+
----------------------
25+
The BuildElement base class provides built in functionality that could be
26+
overridden by the individual plugins.
27+
28+
This section will give a brief summary of how some of the common features work,
29+
some of them or the variables they use will be further detailed in the following
30+
sections.
31+
32+
33+
The `strip-binaries` variable
34+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
35+
The `strip-binaries` variable is by default **empty**. You need to use the
36+
appropiate commands depending of the system you are building.
37+
If you are targeting Linux, ones known to work are the ones used by the
38+
`freedesktop-sdk <https://freedesktop-sdk.io/>`_, you can take a look to them in their
39+
`project.conf <https://gitlab.com/freedesktop-sdk/freedesktop-sdk/blob/freedesktop-sdk-18.08.21/project.conf#L74>`_
40+
41+
42+
Location for staging dependencies
43+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
44+
The BuildElement supports the "location" :term:`dependency configuration <Dependency configuration>`,
45+
which means you can use this configuration for any BuildElement class.
46+
47+
The "location" configuration defines where the dependency will be staged in the
48+
build sandbox.
49+
50+
**Example:**
51+
52+
Here is an example of how one might stage some dependencies into
53+
an alternative location while staging some elements in the sandbox root.
54+
55+
.. code:: yaml
56+
57+
# Stage these build dependencies in /opt
58+
#
59+
build-depends:
60+
- baseproject.bst:opt-dependencies.bst
61+
config:
62+
location: /opt
63+
64+
# Stage these tools in "/" and require them as
65+
# runtime dependencies.
66+
depends:
67+
- baseproject.bst:base-tools.bst
68+
69+
.. note::
70+
71+
The order of dependencies specified is not significant.
72+
73+
The staging locations will be sorted so that elements are staged in parent
74+
directories before subdirectories.
75+
76+
77+
`digest-environment` for dependencies
78+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
79+
The BuildElement supports the ``digest-environment`` :term:`dependency configuration <Dependency configuration>`,
80+
which sets the specified environment variable in the build sandbox to the CAS digest
81+
corresponding to a directory that contains all dependencies that are configured
82+
with the same ``digest-environment``.
83+
84+
This is useful for REAPI clients in the sandbox such as `recc <https://buildgrid.gitlab.io/recc>`_,
85+
see ``remote-apis-socket`` in the :ref:`sandbox configuration <format_sandbox>`.
86+
87+
**Example:**
88+
89+
Here is an example of how to set the environment variable `GCC_DIGEST` to the
90+
CAS digest of a directory that contains ``gcc.bst`` and its runtime dependencies.
91+
The ``libpony.bst`` dependency will not be included in that CAS directory.
92+
93+
.. code:: yaml
94+
95+
build-depends:
96+
- baseproject.bst:gcc.bst
97+
config:
98+
digest-environment: GCC_DIGEST
99+
- libpony.bst
100+
101+
102+
Location for running commands
103+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104+
The ``command-subdir`` variable sets where commands will be executed,
105+
and the directory will be created automatically if it does not exist.
106+
107+
The ``command-subdir`` is a relative path from ``%{build-root}``, and
108+
cannot be a parent or adjacent directory, it must expand to a subdirectory
109+
of ``${build-root}``.
110+
111+
112+
Location for configuring the project
113+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
114+
The ``conf-root`` is the location that specific build elements can use to look for build configuration files.
115+
This is used by elements such as `autotools <https://apache.github.io/buildstream-plugins/elements/autotools.html>`_,
116+
`cmake <https://apache.github.io/buildstream-plugins/elements/cmake.html>`_,
117+
`meson <https://apache.github.io/buildstream-plugins/elements/meson.html>`_,
118+
`setuptools <https://apache.github.io/buildstream-plugins/elements/setuptools.html>`_ and
119+
`pip <https://apache.github.io/buildstream-plugins/elements/pip.html>`_.
120+
121+
The default value of ``conf-root`` is defined by default as ``.``. This means that if
122+
the ``conf-root`` is not explicitly set to another directory, the configuration
123+
files are expected to be found in ``command-subdir``.
124+
125+
126+
Separating source and build directories
127+
'''''''''''''''''''''''''''''''''''''''
128+
A typical example of using ``conf-root`` is when performing
129+
`autotools <https://apache.github.io/buildstream-plugins/elements/autotools.html>`_ builds
130+
where your source directory is separate from your build directory.
131+
132+
This can be achieved in build elements which use ``conf-root`` as follows:
133+
134+
.. code:: yaml
135+
136+
variables:
137+
# Specify that build configuration scripts are found in %{build-root}
138+
conf-root: "%{build-root}"
139+
140+
# The build will run in the `_build` subdirectory
141+
command-subdir: _build
142+
143+
144+
Install Location
145+
~~~~~~~~~~~~~~~~
146+
Build elements must install the build output to the directory defined by ``install-root``.
147+
148+
You need not set or change the ``install-root`` variable as it will be defined
149+
automatically on your behalf, and it is used to collect build output when creating
150+
the resulting artifacts.
151+
152+
It is important to know about ``install-root`` in order to write your own
153+
custom install instructions, for example the
154+
`cmake <https://apache.github.io/buildstream-plugins/elements/cmake.html>`_
155+
element will use it to specify the ``DESTDIR``.

‎src/buildstream/buildelement.py‎

Lines changed: 1 addition & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -22,140 +22,8 @@
2222
2323
.. _core_buildelement_builtins:
2424
25-
Built-in functionality
25+
Built-in functionality # TODO: Should we link this to the 'Using BuildElements' section in the docs?
2626
----------------------
27-
The BuildElement base class provides built in functionality that could be
28-
overridden by the individual plugins.
29-
30-
This section will give a brief summary of how some of the common features work,
31-
some of them or the variables they use will be further detailed in the following
32-
sections.
33-
34-
35-
The `strip-binaries` variable
36-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
37-
The `strip-binaries` variable is by default **empty**. You need to use the
38-
appropiate commands depending of the system you are building.
39-
If you are targetting Linux, ones known to work are the ones used by the
40-
`freedesktop-sdk <https://freedesktop-sdk.io/>`_, you can take a look to them in their
41-
`project.conf <https://gitlab.com/freedesktop-sdk/freedesktop-sdk/blob/freedesktop-sdk-18.08.21/project.conf#L74>`_
42-
43-
44-
Location for staging dependencies
45-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46-
The BuildElement supports the "location" :term:`dependency configuration <Dependency configuration>`,
47-
which means you can use this configuration for any BuildElement class.
48-
49-
The "location" configuration defines where the dependency will be staged in the
50-
build sandbox.
51-
52-
**Example:**
53-
54-
Here is an example of how one might stage some dependencies into
55-
an alternative location while staging some elements in the sandbox root.
56-
57-
.. code:: yaml
58-
59-
# Stage these build dependencies in /opt
60-
#
61-
build-depends:
62-
- baseproject.bst:opt-dependencies.bst
63-
config:
64-
location: /opt
65-
66-
# Stage these tools in "/" and require them as
67-
# runtime dependencies.
68-
depends:
69-
- baseproject.bst:base-tools.bst
70-
71-
.. note::
72-
73-
The order of dependencies specified is not significant.
74-
75-
The staging locations will be sorted so that elements are staged in parent
76-
directories before subdirectories.
77-
78-
79-
`digest-environment` for dependencies
80-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
81-
The BuildElement supports the ``digest-environment`` :term:`dependency configuration <Dependency configuration>`,
82-
which sets the specified environment variable in the build sandbox to the CAS digest
83-
corresponding to a directory that contains all dependencies that are configured
84-
with the same ``digest-environment``.
85-
86-
This is useful for REAPI clients in the sandbox such as `recc <https://buildgrid.gitlab.io/recc>`_,
87-
see ``remote-apis-socket`` in the :ref:`sandbox configuration <format_sandbox>`.
88-
89-
**Example:**
90-
91-
Here is an example of how to set the environment variable `GCC_DIGEST` to the
92-
CAS digest of a directory that contains ``gcc.bst`` and its runtime dependencies.
93-
The ``libpony.bst`` dependency will not be included in that CAS directory.
94-
95-
.. code:: yaml
96-
97-
build-depends:
98-
- baseproject.bst:gcc.bst
99-
config:
100-
digest-environment: GCC_DIGEST
101-
- libpony.bst
102-
103-
104-
Location for running commands
105-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
106-
The ``command-subdir`` variable sets where commands will be executed,
107-
and the directory will be created automatically if it does not exist.
108-
109-
The ``command-subdir`` is a relative path from ``%{build-root}``, and
110-
cannot be a parent or adjacent directory, it must expand to a subdirectory
111-
of ``${build-root}``.
112-
113-
114-
Location for configuring the project
115-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
116-
The ``conf-root`` is the location that specific build elements can use to look for build configuration files.
117-
This is used by elements such as `autotools <https://apache.github.io/buildstream-plugins/elements/autotools.html>`_,
118-
`cmake <https://apache.github.io/buildstream-plugins/elements/cmake.html>`_,
119-
`meson <https://apache.github.io/buildstream-plugins/elements/meson.html>`_,
120-
`setuptools <https://apache.github.io/buildstream-plugins/elements/setuptools.html>`_ and
121-
`pip <https://apache.github.io/buildstream-plugins/elements/pip.html>`_.
122-
123-
The default value of ``conf-root`` is defined by default as ``.``. This means that if
124-
the ``conf-root`` is not explicitly set to another directory, the configuration
125-
files are expected to be found in ``command-subdir``.
126-
127-
128-
Separating source and build directories
129-
'''''''''''''''''''''''''''''''''''''''
130-
A typical example of using ``conf-root`` is when performing
131-
`autotools <https://apache.github.io/buildstream-plugins/elements/autotools.html>`_ builds
132-
where your source directory is separate from your build directory.
133-
134-
This can be achieved in build elements which use ``conf-root`` as follows:
135-
136-
.. code:: yaml
137-
138-
variables:
139-
# Specify that build configuration scripts are found in %{build-root}
140-
conf-root: "%{build-root}"
141-
142-
# The build will run in the `_build` subdirectory
143-
command-subdir: _build
144-
145-
146-
Install Location
147-
~~~~~~~~~~~~~~~~
148-
Build elements must install the build output to the directory defined by ``install-root``.
149-
150-
You need not set or change the ``install-root`` variable as it will be defined
151-
automatically on your behalf, and it is used to collect build output when creating
152-
the resulting artifacts.
153-
154-
It is important to know about ``install-root`` in order to write your own
155-
custom install instructions, for example the
156-
`cmake <https://apache.github.io/buildstream-plugins/elements/cmake.html>`_
157-
element will use it to specify the ``DESTDIR``.
158-
15927
16028
Abstract method implementations
16129
-------------------------------

0 commit comments

Comments
 (0)