diff options
author | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2018-06-18 15:01:47 -0400 |
---|---|---|
committer | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2018-06-18 15:17:52 -0400 |
commit | b4105e8dea0f4aaaefbbd5a5dce344a939e736dc (patch) | |
tree | 6ef0af24afde022eea9b7ac00646314b0a711d15 /doc/source/tutorial/autotools.rst | |
parent | 72fbaa1c0c0f3ff59db0f8bd34268918c6db9865 (diff) | |
download | buildstream-b4105e8dea0f4aaaefbbd5a5dce344a939e736dc.tar.gz |
doc: Adding part 3 of the getting started tutorial: autotools element
This part of the tutorial uses a lot of the work from Phil Dawson
and James Ennis, and uses their example submitted on merge request
499 as a basis to introduce the user to yaml composition and variable
resolution.
This is a part of issue #103
Diffstat (limited to 'doc/source/tutorial/autotools.rst')
-rw-r--r-- | doc/source/tutorial/autotools.rst | 146 |
1 files changed, 146 insertions, 0 deletions
diff --git a/doc/source/tutorial/autotools.rst b/doc/source/tutorial/autotools.rst new file mode 100644 index 000000000..ddf490a38 --- /dev/null +++ b/doc/source/tutorial/autotools.rst @@ -0,0 +1,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 section, 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 affects 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>`. |