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>`.