This is an automated email from the ASF dual-hosted git repository. root pushed a commit to branch tlater/freedocstop-sdk in repository https://gitbox.apache.org/repos/asf/buildstream.git
commit d608e92a48f21fd4ecacde416f0b8ea3fdd2f562 Author: Tristan Maat <[email protected]> AuthorDate: Fri Apr 5 18:05:06 2019 +0100 WIP: Use freedesktop-sdk as a base for tutorials as much as possible WIP because: [] - We need to introduce a buildstream docs cache since this takes ages to compile. [] - I'm not happy with the integration-commands doc - I *should* add another nested dependency. [] - Session output has not yet been updated - this will need to be done post-cache implementation. --- .../autotools/elements/freedesktop-sdk.bst | 9 ++ .../autotools/elements/hello.bst | 4 +- .../autotools/project.conf | 14 +- .../elements/callHello.bst | 0 .../elements/freedesktop-sdk.bst | 9 ++ .../elements/hello-junction.bst | 0 .../elements/hello.bst} | 8 +- .../files/callHello.sh | 0 doc/examples/advanced-junctions/files/src/Makefile | 12 ++ doc/examples/advanced-junctions/files/src/hello.c | 10 ++ .../{junctions => advanced-junctions}/project.conf | 11 ++ doc/examples/autotools/elements/base.bst | 5 - doc/examples/autotools/elements/base/alpine.bst | 13 -- .../autotools/elements/freedesktop-sdk.bst | 9 ++ doc/examples/autotools/elements/hello.bst | 4 +- doc/examples/autotools/project.conf | 12 +- .../integration-commands/elements/base.bst | 5 - .../integration-commands/elements/base/alpine.bst | 17 --- .../elements/freedesktop-sdk.bst | 9 ++ .../integration-commands/elements/libhello.bst | 7 +- doc/examples/integration-commands/project.conf | 13 +- doc/examples/junctions/autotools/elements/base.bst | 5 - .../junctions/autotools/elements/base/alpine.bst | 13 -- .../junctions/elements/freedesktop-sdk.bst | 9 ++ .../libhello.bst => junctions/elements/hello.bst} | 8 +- doc/examples/junctions/files/src/Makefile | 12 ++ doc/examples/junctions/files/src/hello.c | 10 ++ doc/examples/junctions/project.conf | 11 ++ doc/sessions/advanced-junctions.run | 20 +++ doc/sessions/junctions.run | 35 +++-- doc/source/advanced-features/junction-elements.rst | 17 +-- doc/source/tutorial/autotools.rst | 10 +- doc/source/tutorial/integration-commands.rst | 38 +++-- doc/source/tutorial/junctions.rst | 158 +++++++++++++++++++++ doc/source/tutorial/running-commands.rst | 7 + doc/source/using_tutorial.rst | 1 + tests/examples/advanced-junctions.py | 54 +++++++ 37 files changed, 455 insertions(+), 124 deletions(-) diff --git a/doc/examples/advanced-junctions/autotools/elements/freedesktop-sdk.bst b/doc/examples/advanced-junctions/autotools/elements/freedesktop-sdk.bst new file mode 100644 index 0000000..9fe54d4 --- /dev/null +++ b/doc/examples/advanced-junctions/autotools/elements/freedesktop-sdk.bst @@ -0,0 +1,9 @@ +kind: junction +sources: +- kind: git + url: https://gitlab.com/freedesktop-sdk/freedesktop-sdk/ + track: '18.08' + ref: ddde36212f574fbdb66b5cca3d4b411aec22ee82 +config: + options: + target_arch: '%{arch}' diff --git a/doc/examples/junctions/autotools/elements/hello.bst b/doc/examples/advanced-junctions/autotools/elements/hello.bst similarity index 88% rename from doc/examples/junctions/autotools/elements/hello.bst rename to doc/examples/advanced-junctions/autotools/elements/hello.bst index ce3ea74..7950a3a 100644 --- a/doc/examples/junctions/autotools/elements/hello.bst +++ b/doc/examples/advanced-junctions/autotools/elements/hello.bst @@ -18,4 +18,6 @@ sources: ref: 80da43bb5665596ee389e6d8b64b4f122ea4b92a685b1dbd813cd1f0e0c2d83f depends: -- base.bst +- freedesktop-sdk.bst:public-stacks/buildsystems.bst + + diff --git a/doc/examples/junctions/autotools/project.conf b/doc/examples/advanced-junctions/autotools/project.conf similarity index 52% rename from doc/examples/junctions/autotools/project.conf rename to doc/examples/advanced-junctions/autotools/project.conf index 2cf5824..964d974 100644 --- a/doc/examples/junctions/autotools/project.conf +++ b/doc/examples/advanced-junctions/autotools/project.conf @@ -9,5 +9,15 @@ element-path: elements # Define some aliases for the tarballs we download aliases: - alpine: https://bst-integration-test-images.ams3.cdn.digitaloceanspaces.com/ - gnu: https://ftpmirror.gnu.org/gnu/automake/ + gnu: http://ftpmirror.gnu.org/gnu/automake/ + +options: + arch: + type: arch + description: Machine architecture + variable: arch + values: + - arm + - aarch64 + - i686 + - x86_64 diff --git a/doc/examples/junctions/elements/callHello.bst b/doc/examples/advanced-junctions/elements/callHello.bst similarity index 100% rename from doc/examples/junctions/elements/callHello.bst rename to doc/examples/advanced-junctions/elements/callHello.bst diff --git a/doc/examples/advanced-junctions/elements/freedesktop-sdk.bst b/doc/examples/advanced-junctions/elements/freedesktop-sdk.bst new file mode 100644 index 0000000..9fe54d4 --- /dev/null +++ b/doc/examples/advanced-junctions/elements/freedesktop-sdk.bst @@ -0,0 +1,9 @@ +kind: junction +sources: +- kind: git + url: https://gitlab.com/freedesktop-sdk/freedesktop-sdk/ + track: '18.08' + ref: ddde36212f574fbdb66b5cca3d4b411aec22ee82 +config: + options: + target_arch: '%{arch}' diff --git a/doc/examples/junctions/elements/hello-junction.bst b/doc/examples/advanced-junctions/elements/hello-junction.bst similarity index 100% rename from doc/examples/junctions/elements/hello-junction.bst rename to doc/examples/advanced-junctions/elements/hello-junction.bst diff --git a/doc/examples/integration-commands/elements/libhello.bst b/doc/examples/advanced-junctions/elements/hello.bst similarity index 62% copy from doc/examples/integration-commands/elements/libhello.bst copy to doc/examples/advanced-junctions/elements/hello.bst index 53496c8..dc4db56 100644 --- a/doc/examples/integration-commands/elements/libhello.bst +++ b/doc/examples/advanced-junctions/elements/hello.bst @@ -1,16 +1,16 @@ kind: manual description: | - The libhello library + Building using freedesktop-sdk as a base # Depend on the base system depends: -- base.bst + - freedesktop-sdk.bst:public-stacks/buildsystems.bst -# Stage the files/libhello directory for building +# Stage the files/src directory for building sources: - kind: local - path: files/libhello + path: files/src # Now configure the commands to run config: diff --git a/doc/examples/junctions/files/callHello.sh b/doc/examples/advanced-junctions/files/callHello.sh similarity index 100% rename from doc/examples/junctions/files/callHello.sh rename to doc/examples/advanced-junctions/files/callHello.sh diff --git a/doc/examples/advanced-junctions/files/src/Makefile b/doc/examples/advanced-junctions/files/src/Makefile new file mode 100644 index 0000000..8c84251 --- /dev/null +++ b/doc/examples/advanced-junctions/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) -Wall -o $@ $< diff --git a/doc/examples/advanced-junctions/files/src/hello.c b/doc/examples/advanced-junctions/files/src/hello.c new file mode 100644 index 0000000..b534082 --- /dev/null +++ b/doc/examples/advanced-junctions/files/src/hello.c @@ -0,0 +1,10 @@ +/* + * hello.c - Simple hello world program + */ +#include <stdio.h> + +int main(int argc, char *argv[]) +{ + printf("Hello World\n"); + return 0; +} diff --git a/doc/examples/junctions/project.conf b/doc/examples/advanced-junctions/project.conf similarity index 50% copy from doc/examples/junctions/project.conf copy to doc/examples/advanced-junctions/project.conf index 7f8ca6a..d10c25c 100644 --- a/doc/examples/junctions/project.conf +++ b/doc/examples/advanced-junctions/project.conf @@ -6,3 +6,14 @@ format-version: 9 # Subdirectory where elements are stored element-path: elements + +options: + arch: + type: arch + description: Machine architecture + variable: arch + values: + - arm + - aarch64 + - i686 + - x86_64 diff --git a/doc/examples/autotools/elements/base.bst b/doc/examples/autotools/elements/base.bst deleted file mode 100644 index 1b85a9e..0000000 --- a/doc/examples/autotools/elements/base.bst +++ /dev/null @@ -1,5 +0,0 @@ -kind: stack -description: Base stack - -depends: -- base/alpine.bst diff --git a/doc/examples/autotools/elements/base/alpine.bst b/doc/examples/autotools/elements/base/alpine.bst deleted file mode 100644 index cf85df5..0000000 --- a/doc/examples/autotools/elements/base/alpine.bst +++ /dev/null @@ -1,13 +0,0 @@ -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/autotools/elements/freedesktop-sdk.bst b/doc/examples/autotools/elements/freedesktop-sdk.bst new file mode 100644 index 0000000..9fe54d4 --- /dev/null +++ b/doc/examples/autotools/elements/freedesktop-sdk.bst @@ -0,0 +1,9 @@ +kind: junction +sources: +- kind: git + url: https://gitlab.com/freedesktop-sdk/freedesktop-sdk/ + track: '18.08' + ref: ddde36212f574fbdb66b5cca3d4b411aec22ee82 +config: + options: + target_arch: '%{arch}' diff --git a/doc/examples/autotools/elements/hello.bst b/doc/examples/autotools/elements/hello.bst index ce3ea74..7950a3a 100644 --- a/doc/examples/autotools/elements/hello.bst +++ b/doc/examples/autotools/elements/hello.bst @@ -18,4 +18,6 @@ sources: ref: 80da43bb5665596ee389e6d8b64b4f122ea4b92a685b1dbd813cd1f0e0c2d83f depends: -- base.bst +- freedesktop-sdk.bst:public-stacks/buildsystems.bst + + diff --git a/doc/examples/autotools/project.conf b/doc/examples/autotools/project.conf index 96e0284..964d974 100644 --- a/doc/examples/autotools/project.conf +++ b/doc/examples/autotools/project.conf @@ -9,5 +9,15 @@ element-path: elements # Define some aliases for the tarballs we download aliases: - alpine: https://bst-integration-test-images.ams3.cdn.digitaloceanspaces.com/ gnu: http://ftpmirror.gnu.org/gnu/automake/ + +options: + arch: + type: arch + description: Machine architecture + variable: arch + values: + - arm + - aarch64 + - i686 + - x86_64 diff --git a/doc/examples/integration-commands/elements/base.bst b/doc/examples/integration-commands/elements/base.bst deleted file mode 100644 index 1b85a9e..0000000 --- a/doc/examples/integration-commands/elements/base.bst +++ /dev/null @@ -1,5 +0,0 @@ -kind: stack -description: Base stack - -depends: -- base/alpine.bst diff --git a/doc/examples/integration-commands/elements/base/alpine.bst b/doc/examples/integration-commands/elements/base/alpine.bst deleted file mode 100644 index 433f477..0000000 --- a/doc/examples/integration-commands/elements/base/alpine.bst +++ /dev/null @@ -1,17 +0,0 @@ -kind: import -description: | - - Alpine Linux base runtime - -sources: -- kind: tar - url: alpine:integration-tests-base.v1.x86_64.tar.xz - ref: 3eb559250ba82b64a68d86d0636a6b127aa5f6d25d3601a79f79214dc9703639 - -# -# Run ldconfig in the libdir before running anything -# -public: - bst: - integration-commands: - - ldconfig "%{libdir}" diff --git a/doc/examples/integration-commands/elements/freedesktop-sdk.bst b/doc/examples/integration-commands/elements/freedesktop-sdk.bst new file mode 100644 index 0000000..9fe54d4 --- /dev/null +++ b/doc/examples/integration-commands/elements/freedesktop-sdk.bst @@ -0,0 +1,9 @@ +kind: junction +sources: +- kind: git + url: https://gitlab.com/freedesktop-sdk/freedesktop-sdk/ + track: '18.08' + ref: ddde36212f574fbdb66b5cca3d4b411aec22ee82 +config: + options: + target_arch: '%{arch}' diff --git a/doc/examples/integration-commands/elements/libhello.bst b/doc/examples/integration-commands/elements/libhello.bst index 53496c8..a184b21 100644 --- a/doc/examples/integration-commands/elements/libhello.bst +++ b/doc/examples/integration-commands/elements/libhello.bst @@ -5,7 +5,7 @@ description: | # Depend on the base system depends: -- base.bst +- freedesktop-sdk.bst:public-stacks/buildsystems.bst # Stage the files/libhello directory for building sources: @@ -20,3 +20,8 @@ config: install-commands: - make -j1 PREFIX="%{prefix}" DESTDIR="%{install-root}" install + +public: + bst: + integration-commands: + - ldconfig "%{libdir}" diff --git a/doc/examples/integration-commands/project.conf b/doc/examples/integration-commands/project.conf index 9ae5b2a..0aaf5d5 100644 --- a/doc/examples/integration-commands/project.conf +++ b/doc/examples/integration-commands/project.conf @@ -7,6 +7,13 @@ format-version: 9 # 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/ +options: + arch: + type: arch + description: Machine architecture + variable: arch + values: + - arm + - aarch64 + - i686 + - x86_64 diff --git a/doc/examples/junctions/autotools/elements/base.bst b/doc/examples/junctions/autotools/elements/base.bst deleted file mode 100644 index 1b85a9e..0000000 --- a/doc/examples/junctions/autotools/elements/base.bst +++ /dev/null @@ -1,5 +0,0 @@ -kind: stack -description: Base stack - -depends: -- base/alpine.bst diff --git a/doc/examples/junctions/autotools/elements/base/alpine.bst b/doc/examples/junctions/autotools/elements/base/alpine.bst deleted file mode 100644 index cf85df5..0000000 --- a/doc/examples/junctions/autotools/elements/base/alpine.bst +++ /dev/null @@ -1,13 +0,0 @@ -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/junctions/elements/freedesktop-sdk.bst b/doc/examples/junctions/elements/freedesktop-sdk.bst new file mode 100644 index 0000000..9fe54d4 --- /dev/null +++ b/doc/examples/junctions/elements/freedesktop-sdk.bst @@ -0,0 +1,9 @@ +kind: junction +sources: +- kind: git + url: https://gitlab.com/freedesktop-sdk/freedesktop-sdk/ + track: '18.08' + ref: ddde36212f574fbdb66b5cca3d4b411aec22ee82 +config: + options: + target_arch: '%{arch}' diff --git a/doc/examples/integration-commands/elements/libhello.bst b/doc/examples/junctions/elements/hello.bst similarity index 62% copy from doc/examples/integration-commands/elements/libhello.bst copy to doc/examples/junctions/elements/hello.bst index 53496c8..dc4db56 100644 --- a/doc/examples/integration-commands/elements/libhello.bst +++ b/doc/examples/junctions/elements/hello.bst @@ -1,16 +1,16 @@ kind: manual description: | - The libhello library + Building using freedesktop-sdk as a base # Depend on the base system depends: -- base.bst + - freedesktop-sdk.bst:public-stacks/buildsystems.bst -# Stage the files/libhello directory for building +# Stage the files/src directory for building sources: - kind: local - path: files/libhello + path: files/src # Now configure the commands to run config: diff --git a/doc/examples/junctions/files/src/Makefile b/doc/examples/junctions/files/src/Makefile new file mode 100644 index 0000000..8c84251 --- /dev/null +++ b/doc/examples/junctions/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) -Wall -o $@ $< diff --git a/doc/examples/junctions/files/src/hello.c b/doc/examples/junctions/files/src/hello.c new file mode 100644 index 0000000..b534082 --- /dev/null +++ b/doc/examples/junctions/files/src/hello.c @@ -0,0 +1,10 @@ +/* + * hello.c - Simple hello world program + */ +#include <stdio.h> + +int main(int argc, char *argv[]) +{ + printf("Hello World\n"); + return 0; +} diff --git a/doc/examples/junctions/project.conf b/doc/examples/junctions/project.conf index 7f8ca6a..d10c25c 100644 --- a/doc/examples/junctions/project.conf +++ b/doc/examples/junctions/project.conf @@ -6,3 +6,14 @@ format-version: 9 # Subdirectory where elements are stored element-path: elements + +options: + arch: + type: arch + description: Machine architecture + variable: arch + values: + - arm + - aarch64 + - i686 + - x86_64 diff --git a/doc/sessions/advanced-junctions.run b/doc/sessions/advanced-junctions.run new file mode 100644 index 0000000..28578a8 --- /dev/null +++ b/doc/sessions/advanced-junctions.run @@ -0,0 +1,20 @@ + + commands: +# Build callHello.bst + - directory: ../examples/junctions + output: ../source/sessions/junctions-build.html + command: build callHello.bst + +# Run callHello.sh in a shell + - directory: ../examples/junctions + output: ../source/sessions/junctions-shell.html + command: shell callHello.bst -- /bin/sh callHello.sh + +# 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 + - directory: ../examples/junctions + command: workspace close --remove-dirs hello-junction.bst:hello.bst diff --git a/doc/sessions/junctions.run b/doc/sessions/junctions.run index 74c3a4f..4b03271 100644 --- a/doc/sessions/junctions.run +++ b/doc/sessions/junctions.run @@ -1,20 +1,25 @@ commands: -# Build callHello.bst -- directory: ../examples/junctions - output: ../source/sessions/junctions-build.html - command: build callHello.bst +# We need to fetch the junction +- directory: ../examples/advanced-junctions + command: source fetch freedesktop-sdk.bst -# Run callHello.sh in a shell -- directory: ../examples/junctions - output: ../source/sessions/junctions-shell.html - command: shell callHello.bst -- /bin/sh callHello.sh +# We want to show the project contents +- directory: ../examples/advanced-junctions + command: show hello.bst + output: ../source/sessions/advanced-junctions-show-before.html -# 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 +# We want to build the project +- directory: ../examples/advanced-junctions + command: build hello.bst + output: ../source/sessions/advanced-junctions-build.html -# Remove the workspace -- directory: ../examples/junctions - command: workspace close --remove-dirs hello-junction.bst:hello.bst +# We want to show post-build show output +- directory: ../examples/advanced-junctions + command: show hello.bst + output: ../source/sessions/advanced-junctions-show-after.html + +# We want to show the application running +- directory: ../examples/advanced-junctions + command: run hello.bst -- hello + output: ../source/sessions/advanced-junctions-shell.html diff --git a/doc/source/advanced-features/junction-elements.rst b/doc/source/advanced-features/junction-elements.rst index b6065d3..521c4c0 100644 --- a/doc/source/advanced-features/junction-elements.rst +++ b/doc/source/advanced-features/junction-elements.rst @@ -13,16 +13,16 @@ 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>`_ + `doc/examples/advanced-junctions <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/advanced-junctions>`_ subdirectory. Below is a simple example of bst file for a junction element: -.. literalinclude:: ../../examples/junctions/elements/hello-junction.bst +.. literalinclude:: ../../examples/advanced-junctions/elements/hello-junction.bst :language: yaml This element imports the autotools example subproject found in the -BuildStream doc/examples/junctions/autotools subdirectory. +BuildStream doc/examples/advanced-junctions/autotools subdirectory. .. note:: @@ -33,7 +33,7 @@ BuildStream doc/examples/junctions/autotools subdirectory. The below bst file describes an element which depends on the hello.bst element from the autotools example: -.. literalinclude:: ../../examples/junctions/elements/callHello.bst +.. literalinclude:: ../../examples/advanced-junctions/elements/callHello.bst :language: yaml This element consists of a script which calls hello.bst's hello command. @@ -41,7 +41,7 @@ This element consists of a script which calls hello.bst's hello command. Building callHello.bst, .. raw:: html - :file: ../sessions/junctions-build.html + :file: ../sessions/advanced-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. @@ -49,7 +49,7 @@ 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 + :file: ../sessions/advanced-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. @@ -59,8 +59,9 @@ 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 +.. + .. raw:: html + :file: ../sessions/advanced-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/tutorial/autotools.rst b/doc/source/tutorial/autotools.rst index ea28358..8a01e6e 100644 --- a/doc/source/tutorial/autotools.rst +++ b/doc/source/tutorial/autotools.rst @@ -2,7 +2,7 @@ Using the autotools element =========================== -In :ref:`the last chapter <tutorial_running_commands>` we observed how the +In :ref:`the previous chapters <tutorial_junctions>` we observed how the :mod:`manual <elements.manual>` element works, allowing one to specify and run commands manually in the process of constructing an *artifact*. @@ -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/freedesktop-sdk.bst`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The freedesktop-sdk junction is 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..7f31407 100644 --- a/doc/source/tutorial/integration-commands.rst +++ b/doc/source/tutorial/integration-commands.rst @@ -31,20 +31,21 @@ Project structure ----------------- -``project.conf`` and ``elements/base.bst`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The project.conf and base stack :mod:`stack <elements.stack>` element are configured in the +``project.conf`` and ``elements/freedesktop-sdk.bst`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The project.conf and freedesktop-sdk element are configured in the same way as in the previous chapter: :ref:`tutorial_running_commands`. -``elements/base/alpine.bst`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``elements/libhello.bst`` +~~~~~~~~~~~~~~~~~~~~~~~~~ -.. literalinclude:: ../../examples/integration-commands/elements/base/alpine.bst +.. literalinclude:: ../../examples/integration-commands/elements/libhello.bst :language: yaml -This is the same ``base/alpine.bst`` we've seen in previous chapters, -except that we've added an :ref:`integration command <public_integration>`. +This is a simple library to be used by ``elements/hello.bst`` - it is +very similar to elements we have already seen, except that we have +added an :ref:`integration command <public_integration>`. This informs BuildStream that whenever the output of this element is expected to *run*, this command should be run first. In this case we @@ -67,16 +68,11 @@ the dependency chain about details of its artifact, or to suggest how it should be processed. -``elements/libhello.bst`` and ``elements/hello.bst`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -These are basically manual elements very similar to the ones we've -seen in the previous chapter: :ref:`tutorial_running_commands`. +``elements/hello.bst`` +~~~~~~~~~~~~~~~~~~~~~~ -These produce a library and a hello program which uses the library, -we will consider these irrelevant to the topic and leave examination -of `their sources -<https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/integration-commands/files>`_ -as an exercise for the reader. +This is, in essence, the same element we have seen in the previous +chapter: :ref:`tutorial_running_commands`. Using the project @@ -91,10 +87,10 @@ 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 ``libhello.bst`` element is run after staging the dependency +artifacts into the build sandbox and before running any of the build +commands. 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/junctions.rst b/doc/source/tutorial/junctions.rst new file mode 100644 index 0000000..dd4bb08 --- /dev/null +++ b/doc/source/tutorial/junctions.rst @@ -0,0 +1,158 @@ +.. _tutorial_junctions: + +Depending on other BuildStream projects +======================================= +In :ref:`the last chapter <tutorial_running_commands>` we saw how +BuildStream can be used to compile a simple C project. We used a +slightly modified Alpine tarball for this. + +While this works, and is not an uncommon practice, this way we lose +out on some of BuildStream's features, and cannot necessarily +reproduce the whole system from scratch. We would also need to supply +different base images for different architectures if we wanted to +support more than ``x86_64``. It would be better if we could use +BuildStream elements to build everything from scratch, but this would +take a lot of effort. + +Instead, in this chapter, we will introduce the concept of "junctions" +that allow us to depend on other BuildStream projects, so that we can +have a definition of the whole system without needing to specify every +detail ourselves. + +.. note:: + + This example is distributed with BuildStream + in the `doc/examples/junctions + <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/autotools>`_ + subdirectory. + + +Overview +-------- +In this example we will replace the ``elements/base.bst`` and +``elements/base/alpine.bst`` elements with a junction to +`freedesktop-sdk <https://freedesktop-sdk.io/>`_. + + +Project structure +----------------- + +For this project, we will only use two element declarations, and the +usual ``project.conf``, with some slight modifications. + +If we look at what this project builds using :ref:`bst show +<invoking_show>` we will see a pipeline with a lot more elements than +we defined: + +.. + .. raw:: html + :file: ../sessions/junctions-show-before.html + +.. note:: + + You will likely need to fetch the freedesktop-sdk project first. To + do so, simply run ``bst source fetch freedesktop-sdk.bst`` as + suggested. + +This is because we use a number of elements from the freedesktop-sdk +junction. Those are clearly marked with a ``freedesktop-sdk:`` +prefix. In fact, the only element we seem to define is ``hello.bst``. + +Let's explain the files that we do define: + +.. _tutorial_junctions_project_conf: + + +``project.conf`` +~~~~~~~~~~~~~~~~ + +.. literalinclude:: ../../examples/junctions/project.conf + :language: yaml + +freedesktop-sdk provides bindings for multiple architectures, but to +use these we need to add an :ref:`option <project_options>` to +``project.conf``. We define options for ``arm``, ``aarch64``, ``i686`` +and ``x86_64``. BuildStream will automatically pick the correct +architecture for our system. + + +``elements/freedesktop-sdk.bst`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. literalinclude:: ../../examples/junctions/elements/freedesktop-sdk.bst + :language: yaml + +This is the magic element that allows us to access elements from +another project. We instruct BuildStream to clone the freedesktop-sdk +project and use its ``18.08`` branch, which is the recommended version +at the time of writing this guide. + +We also set the ``target_arch`` option to the option we defined in +``project.conf`` - if we only wanted to target one architecture, we +could specify a specific architecture here. + + +``elements/hello.bst`` +~~~~~~~~~~~~~~~~~~~~~~ + +.. literalinclude:: ../../examples/junctions/elements/hello.bst + :language: yaml + +Finally, we modify our build element. We replace our Alpine-based base +system with an element from freedesktop sdk - +`public-stacks/buildsystems.bst +<https://gitlab.com/freedesktop-sdk/freedesktop-sdk/blob/master/elements/public-stacks/buildsystems.bst>`_. We +do this using a normal dependency, but we specify the junction from +which to take the element by prepending the element name with +``freedesktop-sdk.bst``, which refers to our junction element. + +Since the ``freedesktop-sdk.bst:public-stacks/buildsystems.bst`` +element provides all runtime components we need for our build, just +like alpine did, we need to make no other changes. + +Using the project +----------------- + +This project can be used in exactly the same way the +:ref:`running_commands <tutorial_running_commands>` project was used - +we build and run ``hello.bst``. The difference is that ``bst show`` +will now list every individual component, as we saw earlier. + +Build the hello.bst element +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To build the project, run :ref:`bst build <invoking_build>` in the +following way: + +.. + .. raw:: html + :file: ../sessions/junctions-build.html + +BuildStream will automatically build elements provided by the +freedesktop-sdk project, and even download ready-made binaries +wherever possible. It then uses ``make`` and the C compiler provided +by freedesktop-sdk to build our hello world program. + +All the elements, including the freedesktop-sdk elements, will now +show up as ``cached`` in the pipeline: + +.. + .. raw:: html + :file: ../sessions/junctions-show-after.html + +Run the hello world program +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Just like in the previous example, we can run our program using +:ref:`bst shell <invoking_shell>`: + +.. + .. raw:: html + :file: ../sessions/junctions-shell.html + +Summary +------- + +In this chapter we introduced the concept of project junctions, and +explained how they can be used to define a basic sysroot that is +transparent to buildstream. diff --git a/doc/source/tutorial/running-commands.rst b/doc/source/tutorial/running-commands.rst index 1708145..7e164c6 100644 --- a/doc/source/tutorial/running-commands.rst +++ b/doc/source/tutorial/running-commands.rst @@ -92,6 +92,13 @@ 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:: + + This alpine sysroot will only work on ``x86_64`` systems, so don't + panic if you are using a different architecture! The `next chapter + <tutorial_junctions>` will go over an alternative that resolves + this problem. + ``elements/base.bst`` ~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/using_tutorial.rst b/doc/source/using_tutorial.rst index 297f234..20a3e08 100644 --- a/doc/source/using_tutorial.rst +++ b/doc/source/using_tutorial.rst @@ -14,5 +14,6 @@ projects. tutorial/first-project tutorial/running-commands + tutorial/junctions tutorial/autotools tutorial/integration-commands diff --git a/tests/examples/advanced-junctions.py b/tests/examples/advanced-junctions.py new file mode 100644 index 0000000..536523c --- /dev/null +++ b/tests/examples/advanced-junctions.py @@ -0,0 +1,54 @@ +# Pylint doesn't play well with fixtures and dependency injection from pytest +# pylint: disable=redefined-outer-name + +import os +import pytest + +from buildstream.testing import cli_integration as cli # pylint: disable=unused-import +from buildstream.testing._utils.site import IS_LINUX, HAVE_BWRAP + +pytestmark = pytest.mark.integration + +DATA_DIR = os.path.join( + os.path.dirname(os.path.realpath(__file__)), '..', '..', 'doc', 'examples', 'advanced-junctions' +) + + +# Test that the project builds successfully +# @pytest.mark.skipif(not IS_LINUX or not HAVE_BWRAP, reason='Only available on linux with bubblewrap') [email protected](DATA_DIR) +def test_build(cli, datafiles): + project = str(datafiles) + + result = cli.run(project=project, args=['build', 'callHello.bst']) + result.assert_success() + + +# Test the callHello script works as expected. +# @pytest.mark.skipif(not IS_LINUX or not HAVE_BWRAP, reason='Only available on linux with bubblewrap') [email protected](DATA_DIR) +def test_shell_call_hello(cli, datafiles): + project = str(datafiles) + + result = cli.run(project=project, args=['build', 'callHello.bst']) + result.assert_success() + + result = cli.run(project=project, args=['shell', 'callHello.bst', '--', '/bin/sh', 'callHello.sh']) + result.assert_success() + assert result.output == 'Calling hello:\nHello World!\nThis is amhello 1.0.\n' + + +# Test opening a cross-junction workspace +# @pytest.mark.skipif(not IS_LINUX, reason='Only available on linux') [email protected](DATA_DIR) +def test_open_cross_junction_workspace(cli, tmpdir, datafiles): + project = str(datafiles) + workspace_dir = os.path.join(str(tmpdir), "workspace_hello_junction") + + result = cli.run(project=project, + args=['workspace', 'open', '--directory', workspace_dir, 'hello-junction.bst:hello.bst']) + result.assert_success() + + result = cli.run(project=project, + args=['workspace', 'close', '--remove-dir', 'hello-junction.bst:hello.bst']) + result.assert_success()
