This is an automated email from the ASF dual-hosted git repository. tvb pushed a commit to branch tlater/freedesktop in repository https://gitbox.apache.org/repos/asf/buildstream.git
commit bf94f5e86a900a3342cb4fb22f7c5f9af7aeffac Author: Tristan Maat <[email protected]> AuthorDate: Tue Jun 25 13:06:50 2019 +0100 Reword documentation to talk about freedesktop-sdk, not alpine --- doc/source/advanced-features/junction-elements.rst | 2 ++ doc/source/format_declaring.rst | 2 +- doc/source/tutorial/autotools.rst | 8 ++--- doc/source/tutorial/integration-commands.rst | 17 +++++----- doc/source/tutorial/running-commands.rst | 37 +++++++++++++++------- tests/examples/autotools.py | 2 +- 6 files changed, 43 insertions(+), 25 deletions(-) diff --git a/doc/source/advanced-features/junction-elements.rst b/doc/source/advanced-features/junction-elements.rst index b6065d3..aca993f 100644 --- a/doc/source/advanced-features/junction-elements.rst +++ b/doc/source/advanced-features/junction-elements.rst @@ -1,5 +1,7 @@ +.. _junction_elements: + Junction elements ================= BuildStream's junction elements are used to import other BuildStream diff --git a/doc/source/format_declaring.rst b/doc/source/format_declaring.rst index a389733..afb602d 100644 --- a/doc/source/format_declaring.rst +++ b/doc/source/format_declaring.rst @@ -549,7 +549,7 @@ read-only variables are also dynamically declared by BuildStream: * ``element-name`` - The name of the element being processed (e.g base/alpine.bst). + The name of the element being processed (e.g ``base/freedesktop.bst``). * ``project-name`` diff --git a/doc/source/tutorial/autotools.rst b/doc/source/tutorial/autotools.rst index ea28358..0fbab8c 100644 --- a/doc/source/tutorial/autotools.rst +++ b/doc/source/tutorial/autotools.rst @@ -47,10 +47,10 @@ added another :ref:`source alias <project_source_aliases>` for ``gnu``, the loca 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/base/freedesktop.bst`` and ``elements/base.bst`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The freedesktop base and base stack element are defined in the same +way as in the last chapter: :ref:`tutorial_running_commands`. ``elements/hello.bst`` diff --git a/doc/source/tutorial/integration-commands.rst b/doc/source/tutorial/integration-commands.rst index ead5be8..8f0c572 100644 --- a/doc/source/tutorial/integration-commands.rst +++ b/doc/source/tutorial/integration-commands.rst @@ -37,13 +37,13 @@ The project.conf and base stack :mod:`stack <elements.stack>` element are config same way as in the previous chapter: :ref:`tutorial_running_commands`. -``elements/base/alpine.bst`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``elements/base/freedesktop.bst`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. literalinclude:: ../../examples/integration-commands/elements/base/alpine.bst +.. literalinclude:: ../../examples/integration-commands/elements/base/freedesktop.bst :language: yaml -This is the same ``base/alpine.bst`` we've seen in previous chapters, +This is the same ``base/freedesktop.bst`` we've seen in previous chapters, except that we've added an :ref:`integration command <public_integration>`. This informs BuildStream that whenever the output of this element is @@ -91,10 +91,11 @@ following way: .. raw:: html :file: ../sessions/integration-commands-build.html -Observe in the build process above, the integration command declared on the -``base/alpine.bst`` element is run after staging the dependency artifacts -into the build sandbox and before running any of the build commands, for -both of the ``libhello.bst`` and ``hello.bst`` elements. +Observe in the build process above, the integration command declared +on the ``base/freedesktop.bst`` element is run after staging the +dependency artifacts into the build sandbox and before running any of +the build commands, for both of the ``libhello.bst`` and ``hello.bst`` +elements. BuildStream assumes that commands which are to be run in the build sandbox need to be run in an *integrated* sandbox. diff --git a/doc/source/tutorial/running-commands.rst b/doc/source/tutorial/running-commands.rst index 1708145..7de6c02 100644 --- a/doc/source/tutorial/running-commands.rst +++ b/doc/source/tutorial/running-commands.rst @@ -70,7 +70,7 @@ in detail. :language: yaml Our ``project.conf`` is very much like the last one, except that we -have defined a :ref:`source alias <project_source_aliases>` for ``alpine``. +have defined a :ref:`source alias <project_source_aliases>` for ``freedesktop``. .. tip:: @@ -79,19 +79,34 @@ have defined a :ref:`source alias <project_source_aliases>` for ``alpine``. change the access scheme or URL for a group of repositories which belong together. -``elements/base/alpine.bst`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``elements/base/freedesktop.bst`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. literalinclude:: ../../examples/running-commands/elements/base/alpine.bst +.. literalinclude:: ../../examples/running-commands/elements/base/freedesktop.bst :language: yaml -This :mod:`import <elements.import>` element uses a :mod:`tar <sources.tar>` -source to download our Alpine Linux tarball to create our base runtime. +This :mod:`import <elements.import>` element uses a :mod:`tar +<sources.tar>` source to download our freedesktop-sdk Linux tarball to +create our base runtime. This tarball is a sysroot which provides the C runtime libraries and some programs - this is what will be providing the programs we're going to run in this example. +.. note:: + + The tarball used here is built with BuildStream, it consists of + everything included in the BuildStream-facing part of + `freedesktop-sdk <https://freedesktop-sdk.io/>`_ (specifically, + ``public-stacks/buildsystems.bst``, but don't worry if you don't + understand what's going on there yet). + + While we use it as a tarball here, freedesktop-sdk is a BuildStream + project, so we could alternatively depend on it as a :ref:`junction + element <junction_elements>`, but avoid doing this here to + introduce concepts slowly. We do recommend using a junction for + more serious projects! + ``elements/base.bst`` ~~~~~~~~~~~~~~~~~~~~~ @@ -100,7 +115,7 @@ going to run in this example. :language: yaml This is just a symbolic :mod:`stack <elements.stack>` element which declares that -anything which depends on it, will implicitly depend on ``base/alpine.bst``. +anything which depends on it, will implicitly depend on ``base/freedesktop.bst``. It is typical to use stack elements in places where the implementing logical software stack could change, but you rather not have your higher level components @@ -108,7 +123,7 @@ carry knowledge about those changing components. Any element which :ref:`runtime depends <format_dependencies_types>` on the ``base.bst`` will now be able to execute programs provided by the imported -``base/alpine.bst`` runtime. +``base/freedesktop.bst`` runtime. ``elements/hello.bst`` @@ -171,11 +186,11 @@ following way: :file: ../sessions/running-commands-build.html Now we've built our hello world program, using ``make`` -and the C compiler provided by the Alpine Linux image. +and the C compiler provided by Freedesktop-sdk. In the :ref:`first chapter <tutorial_first_project>` we observed that the inputs and output of an element are *directory trees*. In this example, the directory tree -generated by ``base/alpine.bst`` is consumed by ``hello.bst`` due to the +generated by ``base/freedesktop.bst`` is consumed by ``hello.bst`` due to the :ref:`implicit runtime dependency <format_dependencies_types>` introduced by ``base.bst``. .. tip:: @@ -184,7 +199,7 @@ generated by ``base/alpine.bst`` is consumed by ``hello.bst`` due to the the sake of a build, are staged at the root of the build sandbox. These comprise the runtime environment in which the depending element will run commands. - The result is that the ``make`` program and C compiler provided by ``base/alpine.bst`` + The result is that the ``make`` program and C compiler provided by ``base/freedesktop.bst`` were already in ``$PATH`` and ready to run when the commands were needed by ``hello.bst``. Now observe that all of the elements in the loaded pipeline are ``cached``, diff --git a/tests/examples/autotools.py b/tests/examples/autotools.py index ca311c4..a4e5b88 100644 --- a/tests/examples/autotools.py +++ b/tests/examples/autotools.py @@ -15,7 +15,7 @@ DATA_DIR = os.path.join( ) -# Tests a build of the autotools amhello project on a alpine-linux base runtime +# Tests a build of the autotools amhello project on a freedesktop base runtime @pytest.mark.skipif(MACHINE_ARCH != 'x86-64', reason='Examples are written for x86-64') @pytest.mark.skipif(not IS_LINUX or not HAVE_BWRAP, reason='Only available on linux with bubblewrap')
