| .. _examples_alpine_autotools: |
| |
| Alpine Demo |
| =========== |
| This is a simple example using Buildstream to build a sandbox from a tarball containing a minimal |
| `Alpine <https://alpinelinux.org/>`_ image as the base runtime. The example will use autotools to |
| build the hello world example from `automake |
| <https://www.gnu.org/software/automake/manual/automake.html#Hello-World>`_ |
| and install it in the sandbox. |
| |
| .. note:: |
| |
| This example is distributed with Buildstream in the |
| `doc/examples/alpine-demo |
| <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/alpine-demo>`_ |
| subdirectory. |
| |
| Project structure |
| ----------------- |
| |
| project.conf |
| ~~~~~~~~~~~~ |
| Bellow is a basic :ref:`project <projectconf>` definition: |
| |
| .. literalinclude:: ../../examples/alpine-autotools/project.conf |
| :language: yaml |
| |
| This specifies the name of the project, and the location where the project's |
| elements are stored. |
| |
| For convenience, aliases are defined for Automake and Alpine Linux source |
| locations. |
| |
| base.bst |
| ~~~~~~~~ |
| This is the :mod:`import <elements.import>` element used to provide the sandbox |
| runtime for this project. As a :mod:`tar <sources.tar>` element, it imports a source tarball found at the given url. This |
| tarball will be automatically extracted into the root directory of the project's sandbox. In general, the extraction location of a tar source can be specified with the base-dir attribute. |
| |
| .. literalinclude:: ../../examples/alpine-autotools/elements/base.bst |
| :language: yaml |
| |
| amhello.bst |
| ~~~~~~~~~~~ |
| This :mod:`autotools <elements.autotools>` element is the hello world example from |
| GNU autotools. |
| |
| .. literalinclude:: ../../examples/alpine-autotools/elements/amhello.bst |
| :language: yaml |
| |
| The command-subdir variable specifies the working directory in the sandbox for |
| this element. |
| |
| Using the project |
| ----------------- |
| The instructions here assume you are in the alpine-demo root directory (the |
| directory containing project.conf). |
| |
| Running *bst show* will show the pipeline that needs to be built in order to use the amhello.bst |
| element. This includes the element's dependencies, in this case only base.bst. |
| |
| .. raw:: html |
| :file: ../sessions/alpine-autotools-show.html |
| |
| To build this pipeline, use the `bst build` command. For the purpose of this |
| example, we will :ref:`track <invoking_track>` all the elements in the pipeline this tells buildstream to use the most recent reference for each element |
| |
| .. raw:: html |
| :file: ../sessions/alpine-autotools-build.html |
| |
| After building, it is now possible to :ref:`shell <invoking_shell>` into the sandbox with |
| the *bst shell* command. The hello world example will be installed in the sandbox. |
| |
| .. raw:: html |
| :file: ../sessions/alpine-autotools-shell.html |
| |
| Running *bst show* again will show that both base.bst and amhello.bst have been cached with associated |
| :ref:`keys <cachekeys>`. Running `bst build` again will only rebuild cached elements |
| if the key generated from the current state of an element does not match the |
| cached key. |