diff options
| -rw-r--r-- | doc/Makefile | 2 | ||||
| -rw-r--r-- | doc/examples/first-project/project.conf | 2 | ||||
| -rw-r--r-- | doc/sessions/junctions.run | 10 | ||||
| -rw-r--r-- | doc/source/advanced-features/junction-elements.rst | 76 | ||||
| -rw-r--r-- | doc/source/developing/workspaces.rst | 4 | ||||
| -rw-r--r-- | doc/source/junctions/junction-elements.rst | 92 | ||||
| -rw-r--r-- | doc/source/junctions/junction-workspaces.rst | 51 | ||||
| -rw-r--r-- | doc/source/main_glossary.rst | 7 | ||||
| -rw-r--r-- | doc/source/main_using.rst | 4 | ||||
| -rw-r--r-- | doc/source/using_advanced_features.rst | 13 | ||||
| -rw-r--r-- | doc/source/using_junctions.rst | 13 |
11 files changed, 177 insertions, 97 deletions
diff --git a/doc/Makefile b/doc/Makefile index ba8934bde..a7150e6d7 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -143,7 +143,7 @@ html devhelp: templates sessions badges $(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) "$(BUILDDIR)/$@" \ $(wildcard source/*.rst) \ $(wildcard source/tutorial/*.rst) \ - $(wildcard source/advanced-features/*.rst) \ + $(wildcard source/junctions/*.rst) \ $(wildcard source/examples/*.rst) \ $(wildcard source/elements/*.rst) \ $(wildcard source/sources/*.rst) \ diff --git a/doc/examples/first-project/project.conf b/doc/examples/first-project/project.conf index 2e3d086b1..f66376146 100644 --- a/doc/examples/first-project/project.conf +++ b/doc/examples/first-project/project.conf @@ -2,7 +2,7 @@ name: first-project # Required BuildStream format version -format-version: 18 +format-version: 25 # Subdirectory where elements are stored element-path: elements diff --git a/doc/sessions/junctions.run b/doc/sessions/junctions.run index fc9014203..b03b06a15 100644 --- a/doc/sessions/junctions.run +++ b/doc/sessions/junctions.run @@ -10,11 +10,19 @@ commands: output: ../source/sessions/junctions-shell.html command: shell callHello.bst -- /bin/sh callHello.sh +# Open a workspace on the junction: +- directory: ../examples/junctions + output: ../source/sessions/junctions-workspace-open-subproject.html + command: workspace open --directory workspace_subproject hello-junction.bst + # Open a crossJunction workspace: - directory: ../examples/junctions output: ../source/sessions/junctions-workspace-open.html command: workspace open --directory workspace_hello hello-junction.bst:hello.bst -# Remove the workspace +# Remove the workspaces +- directory: ../examples/junctions + command: workspace close --remove-dir hello-junction.bst + - directory: ../examples/junctions command: workspace close --remove-dir hello-junction.bst:hello.bst diff --git a/doc/source/advanced-features/junction-elements.rst b/doc/source/advanced-features/junction-elements.rst deleted file mode 100644 index 6bdc962fb..000000000 --- a/doc/source/advanced-features/junction-elements.rst +++ /dev/null @@ -1,76 +0,0 @@ - - -.. _advanced_junction: - -Junction elements -================= -BuildStream's junction elements are used to import other BuildStream -projects. This allows you to depend on elements that are part of an -upstream project. - - -A simple example ----------------- - -.. note:: - - This example is distributed with BuildStream in the - `doc/examples/junctions <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/junctions>`_ - subdirectory. - -Below is a simple example of bst file for a junction element: - -.. literalinclude:: ../../examples/junctions/elements/hello-junction.bst - :language: yaml - -This element imports the autotools example subproject found in the -BuildStream doc/examples/junctions/autotools subdirectory. - -.. note:: - - While for this example we're using a local source, another common use-case, - for junction elements is including a remote, version contolled project, - having a source type such as `-kind: git`. - -The below bst file describes an element which depends on the hello.bst element -from the autotools example: - -.. literalinclude:: ../../examples/junctions/elements/callHello.bst - :language: yaml - -This element consists of a script which calls hello.bst's hello command. - -Building callHello.bst, - -.. raw:: html - :file: ../sessions/junctions-build.html - -You can see that the hello.bst element and its dependencies from the autotools -project have been build as part of the pipeline for callHello.bst. - -We can now invoke `bst shell` - -.. raw:: html - :file: ../sessions/junctions-shell.html - -This runs the script files/callHello.sh which will makes use of the hello command from the hello.bst element in the autotools project. - - -Cross-junction workspaces -------------------------- -You can open workspaces for elements in the project refered to by the junction -using the syntax `bst open ${junction-name}:{element-name}`. In this example, - -.. raw:: html - :file: ../sessions/junctions-workspace-open.html - -This has opened a workspace for the hello.bst element from the autotools project. -This workspace can now be used as normal. - - -Further reading ---------------- -For an example of junction elements being used in a real project, take a look -at the `freedesktop-sdk junction -<https://gitlab.gnome.org/GNOME/gnome-build-meta/blob/master/elements/freedesktop-sdk.bst>`_ -in the `gnome-build-meta <https://gitlab.gnome.org/GNOME/gnome-build-meta>`_ project. diff --git a/doc/source/developing/workspaces.rst b/doc/source/developing/workspaces.rst index e4ad66da8..2413c56ff 100644 --- a/doc/source/developing/workspaces.rst +++ b/doc/source/developing/workspaces.rst @@ -4,8 +4,8 @@ Workspaces ========== -In this section we will cover the use of BuildStream's workspaces feature when devloping on a -BuildStream project. +In this section we will cover the use of BuildStream's workspaces feature when +devloping a BuildStream project. .. note:: diff --git a/doc/source/junctions/junction-elements.rst b/doc/source/junctions/junction-elements.rst new file mode 100644 index 000000000..8de3d5361 --- /dev/null +++ b/doc/source/junctions/junction-elements.rst @@ -0,0 +1,92 @@ + + +.. _junction_elements: + +Junction elements +================= +BuildStream's :mod:`junction <elements.junction>` elements are the mechanism which +allow projects to interact and depend on eachother. + +Junction elements represent the BuildStream project you are depending, and behave +much like other elements in the sense that they can be :ref:`fetched <invoking_source_fetch>` +and :ref:`tracked <invoking_source_track>` like other elements, except that regular +elements cannot *depend* on junctions directly, nor can junctions be :ref:`built <invoking_build>`. +Instead, junctions act like a window into another project you depend on, and allow +elements of your project to depend on elements exposed by the project referenced by +the junction. + +Projects which are junctioned by your project are referred to as *subprojects*. + + +A simple example +---------------- + +.. note:: + + This example is distributed with BuildStream in the + `doc/examples/junctions <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/junctions>`_ + subdirectory. + +Below is a simple example of bst file for the junction element, which +we have called ``hello-junction.bst`` in this project: + +.. literalinclude:: ../../examples/junctions/elements/hello-junction.bst + :language: yaml + +This element imports the autotools example subproject distributed with BuildStream +in the `doc/examples/junctions/autotools <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/junctions/autotools>`_ +subdirectory. + +.. note:: + + For the sake of this example we are using a local source in a subdirectory + of the example project. + + Since junctions allow interoperability of projects, it would be more common + to use a junction to a remote project under separate revision control, possibly + using a ``kind: git`` source. + +The below bst file describes the element ``callHello.bst``, which depends on the +``hello.bst`` element from the autotools example: + +.. literalinclude:: ../../examples/junctions/elements/callHello.bst + :language: yaml + +Note how this element refers to the previously declared ``hello-junction.bst`` +junction in its :ref:`dependency dictionary <format_dependencies>`. This dependency +expresses that we are depending on the ``hello.bst`` element in the project +which ``hello-junction.bst`` refers to. + +The ``callHello.bst`` element simply imports a ``callHello.sh`` shell script which +calls the hello command provided by ``hello.bst``: + +.. literalinclude:: ../../examples/junctions/files/callHello.sh + :language: shell + + +Building and running +-------------------- +Building the ``callHello.bst`` element which requires an external project +is just a matter of invoking :ref:`bst build <invoking_build>` in the +regular way: + +.. raw:: html + :file: ../sessions/junctions-build.html + +You can see that the hello.bst element and its dependencies from the autotools +project have been built as a part of the pipeline for callHello.bst. + +We can now invoke :ref:`bst shell <invoking_shell>` and run our ``callHello.sh`` +script, which in turn also calls the ``hello`` program installed by the +subproject's ``hello.bst`` element. + +.. raw:: html + :file: ../sessions/junctions-shell.html + + +Further reading +--------------- +For an example of junction elements being used in a real project, take a look +at the `freedesktop-sdk junction +<https://gitlab.gnome.org/GNOME/gnome-build-meta/blob/master/elements/freedesktop-sdk.bst>`_ +in the `gnome-build-meta <https://gitlab.gnome.org/GNOME/gnome-build-meta>`_ project. diff --git a/doc/source/junctions/junction-workspaces.rst b/doc/source/junctions/junction-workspaces.rst new file mode 100644 index 000000000..a9176063c --- /dev/null +++ b/doc/source/junctions/junction-workspaces.rst @@ -0,0 +1,51 @@ + + +.. _junction_workspaces: + +Workspaces and subprojects +========================== +When developping a project with :mod:`junctions <elements.junction>` and +subprojects, you will probably end up needing to work on the subprojects +as well. + +Opening :ref:`workspaces <developing_workspaces>` works mostly in the +same way as it does with subprojects as it does for elements directly +in your own project. + +.. note:: + + This section runs commands on the same example project presented in the + :ref:`previous section <junction_elements>`, which is distributed with BuildStream in the + `doc/examples/junctions <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/junctions>`_ + subdirectory. + + +Workspacing a junction +---------------------- +Sometimes you need to work on the elements declared in a subproject +directly. As the downstream consumer of a junctioned project, it makes +sense that you might need to work on that project as well in order +to satisfy the needs of your downstream project. + +You can easily work on your subproject by :ref:`opening a workspace <invoking_workspace_open>` +on the junction element directly. + +.. raw:: html + :file: ../sessions/junctions-workspace-open-subproject.html + +After opening a workspace on the junction element, the open workspace +is used to define the subproject, allowing you to make changes to +how the subproject is built, add new dependencies and configure the +subproject in any way. + + +Cross-junction workspaces +------------------------- +You can open workspaces for elements in the project refered to by the junction +using the syntax ``bst open ${junction-name}:{element-name}``. In this example, + +.. raw:: html + :file: ../sessions/junctions-workspace-open.html + +This has opened a workspace for the hello.bst element from the autotools project. +This workspace can now be used as normal. diff --git a/doc/source/main_glossary.rst b/doc/source/main_glossary.rst index a2bb58540..fb9506c7f 100644 --- a/doc/source/main_glossary.rst +++ b/doc/source/main_glossary.rst @@ -77,7 +77,7 @@ Glossary See :mod:`Junction reference <elements.junction>` for details on how to configure junction elements. - See :ref:`Junction guide <advanced_junction>` for details on how to use + See :ref:`Junction guide <junction_elements>` for details on how to use junction elements. @@ -126,6 +126,11 @@ Glossary :term:`Element <Element>` configuration. + Subproject + Subprojects are :term:`projects <Project>` which are referred + to by a :term:`Junction`. + + Workspace Workspaces allow building one or more elements using a local, and potentially modified, copy of their sources. diff --git a/doc/source/main_using.rst b/doc/source/main_using.rst index 48553087c..067e7bb16 100644 --- a/doc/source/main_using.rst +++ b/doc/source/main_using.rst @@ -13,8 +13,8 @@ guides and information on user preferences and configuration. using_tutorial using_developing - using_advanced_features - using_examples + using_junctions using_config using_commands using_configuring_cache_server + using_examples diff --git a/doc/source/using_advanced_features.rst b/doc/source/using_advanced_features.rst deleted file mode 100644 index 585b3573c..000000000 --- a/doc/source/using_advanced_features.rst +++ /dev/null @@ -1,13 +0,0 @@ - - -Advanced features -================= -This section provides some step by step walkthroughs which are meant to help the -user quickly get more familiar with some of BuildStream's more advanced -features. - -.. toctree:: - :numbered: - :maxdepth: 1 - - advanced-features/junction-elements diff --git a/doc/source/using_junctions.rst b/doc/source/using_junctions.rst new file mode 100644 index 000000000..85f1638b1 --- /dev/null +++ b/doc/source/using_junctions.rst @@ -0,0 +1,13 @@ + + +Combining projects +================== +This section covers the features which allow BuildStream projects to +depend on eachother. + +.. toctree:: + :numbered: + :maxdepth: 1 + + junctions/junction-elements + junctions/junction-workspaces |