1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
Using the autotools element
===========================
In :ref:`the last chapter <tutorial_running_commands>` we observed how the
:mod:`manual <elements.manual>` element works, allowing one to specify and
run commands manually in the process of constructing an *artifact*.
In this chapter, we'll go over a mostly automated build of a similar
hello world example. We will observe how our configurations of the
:mod:`autotools <elements.autotools>` element translate to configurations
on the :mod:`manual <elements.manual>` element, and observe how
:ref:`variable substitution <format_variables>` works.
.. note::
This example is distributed with BuildStream
in the `doc/examples/autotools
<https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/autotools>`_
subdirectory.
Overview
--------
Instead of using the :mod:`local <sources.local>` source as we have been using
in the previous examples, we're going to use a :mod:`tar <sources.tar>` source
this time to obtain the ``automake`` release tarball directly from the upstream
hosting.
In this example we're going to build the example program included in the
upstream ``automake`` tarball itself, and we're going to use the automated
:mod:`autotools <elements.autotools>` build element to do so.
Project structure
-----------------
``project.conf``
~~~~~~~~~~~~~~~~
.. literalinclude:: ../../examples/autotools/project.conf
:language: yaml
Like the :ref:`last project.conf <tutorial_running_commands_project_conf>`, we've
added another :ref:`source alias <project_source_aliases>` for ``gnu``, the location
from which we're going to download the ``automake`` tarball.
``elements/base/alpine.bst`` and ``elements/base.bst``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The alpine base and base stack element are defined in the
same way as in the last chapter: :ref:`tutorial_running_commands`.
``elements/hello.bst``
~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../examples/autotools/elements/hello.bst
:language: yaml
In this case, we haven't touched the element's ``config`` section
at all, instead we just slightly override the bahavior of the
:mod:`autotools <elements.autotools>` build element by overriding
the :ref:`command-subdir variable <format_variables>`
Looking at variables
''''''''''''''''''''
Let's take a moment and observe how :ref:`element composition
<format_composition>` works with variables.
As :ref:`the documentation <format_composition>` mentions:
* The initial settings of the ``project.conf`` variables are setup
using BuildStream's :ref:`builtin defaults <project_builtin_defaults>`.
* After this, your local ``project.conf`` may override some variables
on a project wide basis. Those will in turn be overridden by any
defaults provided by element classes, such as the variables set in the
documentation of the :mod:`autotools <elements.autotools>` build element.
The variables you set in your final ``<element.bst>`` *element declarations*,
will have the final say on the value of a particular variable.
* Finally, the variables, which may be composed of other variables,
are resolved after all composition has taken place.
The variable we needed to override was ``command-subdir``, which is an
automatic variable provided by the :mod:`BuildElement <buildstream.buildelement>`
abstract class. This variable simply instructs the :mod:`BuildElement <buildstream.buildelement>`
in which subdirectory of the ``%{build-root}`` to run it's commands in.
One can always display the resolved set of variables for a given
element's configuration using :ref:`bst show <invoking_show>`:
.. raw:: html
:file: ../sessions/autotools-show-variables.html
As an exercise, we suggest that you modify the ``hello.bst``
element to set the prefix like so:
.. code:: yaml
variables:
prefix: "/opt"
And rerun the above :ref:`bst show <invoking_show>` command to observe how this
changes the output.
Observe where the variables are declared in the :ref:`builtin defaults
<project_builtin_defaults>` and :mod:`autotools <elements.autotools>` element
documentation, and how overriding these effects the resolved set of variables.
Using the project
-----------------
Build the hello.bst element
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To build the project, run :ref:`bst build <invoking_build>` in the
following way:
.. raw:: html
:file: ../sessions/autotools-build.html
Run the hello world program
~~~~~~~~~~~~~~~~~~~~~~~~~~~
We probably know by now what's going to happen, but let's run
the program we've compiled anyway using :ref:`bst shell <invoking_shell>`:
.. raw:: html
:file: ../sessions/autotools-shell.html
Summary
-------
Now we've used a builtin :ref:`build element <plugins_build_elements>`, and
we've taken a look into :ref:`how variables work <format_variables>`.
When browsing the :ref:`build elements <plugins_build_elements>` in the
documentation, we are now equipped with a good idea of what an element is going
to do, based on their default YAML configuration and any configurations
we have in our project. We can also now observe what variables are in effect
for the build of a given element, using :ref:`bst show <invoking_show>`.
|
