doc/examples/directives: Add user guide for using project options and directives

10 files changed, 318 insertions, 0 deletions

diff --git a/doc/examples/directives/elements/base.bst b/doc/examples/directives/elements/base.bst
new file mode 100644
index 000000000..1b85a9e8c
--- /dev/null
+++ b/doc/examples/directives/elements/base.bst
@@ -0,0 +1,5 @@
+kind: stack
+description: Base stack
+
+depends:
+- base/alpine.bst
diff --git a/doc/examples/directives/elements/base/alpine.bst b/doc/examples/directives/elements/base/alpine.bst
new file mode 100644
index 000000000..cf85df5bf
--- /dev/null
+++ b/doc/examples/directives/elements/base/alpine.bst
@@ -0,0 +1,13 @@
+kind: import
+description: |
+
+    Alpine Linux base runtime
+
+sources:
+- kind: tar
+
+  # This is a post doctored, trimmed down system image
+  # of the Alpine linux distribution.
+  #
+  url: alpine:integration-tests-base.v1.x86_64.tar.xz
+  ref: 3eb559250ba82b64a68d86d0636a6b127aa5f6d25d3601a79f79214dc9703639
diff --git a/doc/examples/directives/elements/hello.bst b/doc/examples/directives/elements/hello.bst
new file mode 100644
index 000000000..dc660823c
--- /dev/null
+++ b/doc/examples/directives/elements/hello.bst
@@ -0,0 +1,27 @@
+kind: manual
+description: |
+
+  A hello world program with a custom greeting message
+
+# Depend on the base system
+depends:
+- base.bst
+
+# Stage the files/src directory for building
+sources:
+  - kind: local
+    path: files/src
+
+# This include file defines the %{greeting} variable used below
+variables:
+  (@): include/greeting.bst
+
+# Now configure the commands to run
+config:
+
+  # This time we inform the Makefile of which greeting we want
+  build-commands:
+  - make PREFIX="%{prefix}" GREETING="%{greeting}"
+
+  install-commands:
+  - make -j1 PREFIX="%{prefix}" DESTDIR="%{install-root}" install
diff --git a/doc/examples/directives/files/src/Makefile b/doc/examples/directives/files/src/Makefile
new file mode 100644
index 000000000..8e928b0e9
--- /dev/null
+++ b/doc/examples/directives/files/src/Makefile
@@ -0,0 +1,12 @@
+# Sample makefile for hello.c
+#
+.PHONY: all install
+
+all: hello
+
+install:
+	install -d ${DESTDIR}${PREFIX}/bin
+	install -m 755 hello ${DESTDIR}${PREFIX}/bin
+
+hello: hello.c
+	$(CC) -DGREETING_MESSAGE="\"${GREETING}\"" -Wall -o $@ $<
diff --git a/doc/examples/directives/files/src/hello.c b/doc/examples/directives/files/src/hello.c
new file mode 100644
index 000000000..df3ca1ea2
--- /dev/null
+++ b/doc/examples/directives/files/src/hello.c
@@ -0,0 +1,10 @@
+/*
+ * hello.c - Simple hello world program
+ */
+#include <stdio.h>
+
+int main(int argc, char *argv[])
+{
+  printf(GREETING_MESSAGE);
+  return 0;
+}
diff --git a/doc/examples/directives/include/greeting.bst b/doc/examples/directives/include/greeting.bst
new file mode 100644
index 000000000..c5808d744
--- /dev/null
+++ b/doc/examples/directives/include/greeting.bst
@@ -0,0 +1,16 @@
+# We define the greeting message here conditionally
+(?):
+- flavor == "normal":
+    greeting: |
+
+      Hello world !
+
+- flavor == "somber":
+    greeting: |
+
+      Hey world.
+
+- flavor == "excited":
+    greeting: |
+
+      Howdy there, and what a world it is !
diff --git a/doc/examples/directives/project.conf b/doc/examples/directives/project.conf
new file mode 100644
index 000000000..c078a5af8
--- /dev/null
+++ b/doc/examples/directives/project.conf
@@ -0,0 +1,24 @@
+# Unique project name
+name: directives
+
+# Required BuildStream format version
+format-version: 18
+
+# Subdirectory where elements are stored
+element-path: elements
+
+# Define an alias for our alpine tarball
+aliases:
+  alpine: https://bst-integration-test-images.ams3.cdn.digitaloceanspaces.com/
+
+# Define an option for this project
+#
+options:
+  flavor:
+    type: enum
+    description: Flavor of the greeting in the hello world program
+    values:
+    - normal
+    - somber
+    - excited
+    default: normal
diff --git a/doc/sessions/directives.run b/doc/sessions/directives.run
new file mode 100644
index 000000000..5fd10bd3d
--- /dev/null
+++ b/doc/sessions/directives.run
@@ -0,0 +1,35 @@
+
+commands:
+# Make it fetch first
+- directory: ../examples/directives
+  command: source fetch hello.bst
+
+# Capture a build output
+- directory: ../examples/directives
+  output: ../source/sessions/directives-build-normal.html
+  command: build hello.bst
+
+# Capture a build output
+- directory: ../examples/directives
+  output: ../source/sessions/directives-build-somber.html
+  command: --option flavor somber build hello.bst
+
+# Capture a build output
+- directory: ../examples/directives
+  output: ../source/sessions/directives-build-excited.html
+  command: --option flavor excited build hello.bst
+
+# Capture a shell output
+- directory: ../examples/directives
+  output: ../source/sessions/directives-shell-normal.html
+  command: shell hello.bst -- hello
+
+# Capture a shell output
+- directory: ../examples/directives
+  output: ../source/sessions/directives-shell-somber.html
+  command: --option flavor somber shell hello.bst -- hello
+
+# Capture a shell output
+- directory: ../examples/directives
+  output: ../source/sessions/directives-shell-excited.html
+  command: --option flavor excited shell hello.bst -- hello
diff --git a/doc/source/tutorial/directives.rst b/doc/source/tutorial/directives.rst
new file mode 100644
index 000000000..a23b5f9a1
--- /dev/null
+++ b/doc/source/tutorial/directives.rst
@@ -0,0 +1,175 @@
+
+
+.. _tutorial_directives:
+
+Optionality and directives
+==========================
+In this chapter we're going to go over some of the more flexible constructs
+which BuildStream offers for :ref:`optionality <project_options>`, and
+show how we can use :ref:`directives <format_directives>` in the BuildStream
+YAML format.
+
+.. note::
+
+   This example is distributed with BuildStream
+   in the `doc/examples/directives
+   <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/directives>`_
+   subdirectory.
+
+
+Overview
+--------
+This chapter's example will build another ``hello.c`` program which much
+resembles the program in the :ref:`running commands <tutorial_running_commands>` example,
+but here we're going to make the greeting string *configurable* using the C
+preprocessor.
+
+We'll be compiling the following C file:
+
+
+``files/src/hello.c``
+~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: ../../examples/directives/files/src/hello.c
+   :language: c
+
+And we're going to build it using ``make``, using the following Makefile:
+
+
+``files/src/Makefile``
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/directives/files/src/Makefile
+   :language: Makefile
+
+Notice the addition of ``-DGREETING_MESSAGE="\"${GREETING}\""`` in the above
+Makefile, this will allow us to configure the greeting message from the
+``hello.bst`` element declaration.
+
+We will need to add support to our project for *optionality*, and we'll
+have to make *conditional statements* to resolve what kind of greeting
+we want from the hello world program.
+
+
+Project structure
+-----------------
+Since this project has much the same structure as the
+:ref:`running commands <tutorial_running_commands>` chapter did, we won't go over all of
+these elements in detail. Instead let's focus on the addition of the new
+:ref:`project options <project_options>` in ``project.conf``, the added
+file in the ``include/`` project subdirectory, and how these come together
+in the the ``hello.bst`` element.
+
+
+``project.conf``
+~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/directives/project.conf
+   :language: yaml
+
+Here, our ``project.conf`` declares a project option called ``flavor``, and this
+will inform what kind of greeting message we want to use when building the project.
+
+
+``elements/hello.bst``
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/directives/elements/hello.bst
+   :language: yaml
+
+Notice the ``(@)`` symbol we've added in the ``variables:`` section, this
+symbol is used to invoke the :ref:`include directive <format_directives_include>`,
+which can be useful for code sharing between elements or simply to improve readability.
+
+In this case, we are compositing the content of ``include/greeting.bst`` into the
+:ref:`variables <format_variables>` section of the element declaration, directives
+can however be used virtually anywhere in the BuildStream YAML format.
+
+
+``include/greeting.bst``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/directives/include/greeting.bst
+   :language: yaml
+
+Here we can see the dictionary which will be composited into the ``variables:``
+section of the ``hello.bst`` element described above.
+
+Note the usage of the ``(?)`` symbol at the toplevel of the YAML dictionary,
+this is how we perform :ref:`conditional statements <format_directives_conditional>`
+in the BuildStream YAML format.
+
+This include file uses the ``flavor`` project option we declared in ``project.conf`` to
+decide what value will end up being assigned to the ``%{greeting}`` variable, which
+will ultimately be used in the ``hello.bst`` element.
+
+
+Using the project
+-----------------
+Now that we have a project which uses options and conditional statements,
+lets build the project with a few different options and observe the outputs.
+
+
+Building hello.bst element with options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Since the :ref:`flavor option <project_options>` we've declared above
+has a default, we can build it the first time using :ref:`bst build <invoking_build>`
+without any special command line options:
+
+.. raw:: html
+   :file: ../sessions/directives-build-normal.html
+
+If we want to build the ``somber`` flavor, we just need to specify the
+additional ``--option`` command line option to :ref:`bst <invoking_bst>`
+in order to inform BuildStream of the options we want.
+
+.. raw:: html
+   :file: ../sessions/directives-build-somber.html
+
+Note that the ``--option`` option can be specified many times on the
+``bst`` command line, so as to support projects which have multiple
+options.
+
+Finally lets get the ``excited`` flavor built as well:
+
+.. raw:: html
+   :file: ../sessions/directives-build-excited.html
+
+If you observe the cache keys above, you will notice that while
+we have only three elements in the pipeline, counting ``base/alpine.bst``,
+``base.bst`` and ``hello.bst``, we have actually built *five artifacts*,
+because the ``hello.bst`` is built differently each time, it has a
+different cache key and is stored separately in the artifact cache.
+
+
+Run the hello world program with options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Since the ``--option`` command line option to :ref:`bst <invoking_bst>`
+is a main option, it can be used in any command.
+
+Let's run the ``hello`` program using :ref:`bst shell <invoking_shell>`
+three times in a row, each time using a different option so we can
+observe the results.
+
+
+.. raw:: html
+   :file: ../sessions/directives-shell-normal.html
+
+
+.. raw:: html
+   :file: ../sessions/directives-shell-somber.html
+
+
+.. raw:: html
+   :file: ../sessions/directives-shell-excited.html
+
+
+Summary
+-------
+In this chapter we've demonstrated how to declare :ref:`project options <project_options>`,
+how to use :ref:`conditional directives <format_directives_conditional>`, and also
+how to use :ref:`include directives <format_directives_include>`.
+
+To get more familliar with these concepts, you may want to explore the remaining
+:ref:`directives <format_directives>` in the BuildStream YAML format, and also take
+a look at the various :ref:`types of project options <project_options>` that
+are also supported.
diff --git a/doc/source/using_tutorial.rst b/doc/source/using_tutorial.rst
index 55201012e..96a9da2a2 100644
--- a/doc/source/using_tutorial.rst
+++ b/doc/source/using_tutorial.rst
@@ -16,3 +16,4 @@ projects.
    tutorial/running-commands
    tutorial/autotools
    tutorial/integration-commands
+   tutorial/directives