diff options
author | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2020-04-12 23:01:52 +0900 |
---|---|---|
committer | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2020-04-17 20:58:24 +0900 |
commit | 0060e692b73aa4544a35345b220256ae76486205 (patch) | |
tree | 86dc4e7ddf6cc0186771e5376d6a5e2a48511c66 | |
parent | 5e79a84af8e9904f21d70735b61e999cca81ed27 (diff) | |
download | buildstream-0060e692b73aa4544a35345b220256ae76486205.tar.gz |
doc/examples/directives: Add user guide for using project options and directives
-rw-r--r-- | doc/examples/directives/elements/base.bst | 5 | ||||
-rw-r--r-- | doc/examples/directives/elements/base/alpine.bst | 13 | ||||
-rw-r--r-- | doc/examples/directives/elements/hello.bst | 27 | ||||
-rw-r--r-- | doc/examples/directives/files/src/Makefile | 12 | ||||
-rw-r--r-- | doc/examples/directives/files/src/hello.c | 10 | ||||
-rw-r--r-- | doc/examples/directives/include/greeting.bst | 16 | ||||
-rw-r--r-- | doc/examples/directives/project.conf | 24 | ||||
-rw-r--r-- | doc/sessions/directives.run | 35 | ||||
-rw-r--r-- | doc/source/tutorial/directives.rst | 175 | ||||
-rw-r--r-- | doc/source/using_tutorial.rst | 1 |
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 |