From 4dfc8607172b217de844762e63474fff3b0ea131 Mon Sep 17 00:00:00 2001 From: Tristan Van Berkom Date: Tue, 12 Jun 2018 13:59:12 -0400 Subject: doc/source/examples.rst: Restructuring individual examples into an examples subdirectory --- doc/Makefile | 1 + doc/source/examples.rst | 4 +- doc/source/examples/flatpak-autotools.rst | 144 ++++++++++++++++++++++++++++++ doc/source/examples_flatpak_autotools.rst | 144 ------------------------------ 4 files changed, 146 insertions(+), 147 deletions(-) create mode 100644 doc/source/examples/flatpak-autotools.rst delete mode 100644 doc/source/examples_flatpak_autotools.rst diff --git a/doc/Makefile b/doc/Makefile index 2bd07faae..dbb293449 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -96,6 +96,7 @@ html devhelp: templates $(SESSION_HTML) PYTHONPATH=$(CURDIR)/../buildstream/plugins \ $(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) "$(BUILDDIR)/$@" \ $(wildcard source/*.rst) \ + $(wildcard source/examples/*.rst) \ $(wildcard source/elements/*.rst) \ $(wildcard source/sources/*.rst) @echo diff --git a/doc/source/examples.rst b/doc/source/examples.rst index e1511782b..aa100d007 100644 --- a/doc/source/examples.rst +++ b/doc/source/examples.rst @@ -1,6 +1,4 @@ -.. _examples: - Examples ======== This page contains documentation for real examples of BuildStream projects, @@ -11,4 +9,4 @@ maintained and work as expected. .. toctree:: :maxdepth: 1 - examples_flatpak_autotools + examples/flatpak-autotools diff --git a/doc/source/examples/flatpak-autotools.rst b/doc/source/examples/flatpak-autotools.rst new file mode 100644 index 000000000..78a3b9a24 --- /dev/null +++ b/doc/source/examples/flatpak-autotools.rst @@ -0,0 +1,144 @@ + +.. _examples_flatpak_autotools: + +Building on a Flatpak SDK +========================= +Here we demonstrate how to build and run software using +a Flatpak SDK for the base runtime. + +.. note:: + + This example is distributed with BuildStream + in the `doc/examples/flatpak-autotools + `_ + subdirectory. + + +Project structure +----------------- + + +project.conf +~~~~~~~~~~~~ +The following is a simple :ref:`project ` definition: + +.. literalinclude:: ../../examples/flatpak-autotools/project.conf + :language: yaml + +Here we use an :ref:`arch option ` to allow +conditional statements in this project to be made depending on machine +architecture. For this example we only support the ``i386`` and ``x86_64`` +architectures. + +Note that we've added a :ref:`source alias ` for +the ``https://sdk.gnome.org/`` repository to download the SDK from. + + +base/sdk.bst +~~~~~~~~~~~~ +This is the :mod:`import ` element used to import the +actual Flatpak SDK, it uses an :mod:`ostree ` source to +download the Flatpak since these are hosted in OSTree repositories. + +.. literalinclude:: ../../examples/flatpak-autotools/elements/base/sdk.bst + :language: yaml + +While declaring the :mod:`ostree ` source, we specify a GPG +public key to verify the OSTree download. This configuration is optional +but recommended for OSTree repositories. The key is stored in the project directory +at ``keys/gnome-sdk.gpg``. + +We also use :ref:`conditional statements ` to decide +which branch to download. + +For the ``config`` section of this :mod:`import ` element, +it's important to note two things: + +* **source**: We only want to extract the ``files/`` directory from the SDK, + + This is becase Flatpak runtimes dont start at the root of the OSTree checkout, + instead the actual files start in the ``files//`` subdirectory + +* **target**: The content we've extracted should be staged at ``/usr`` + + This is because Flatpak runtimes only contain the data starting at ``/usr``, + and they expect to be staged at ``/usr`` at runtime, in an environment + with the appropriate symlinks setup from ``/``. + + +base/usrmerge.bst +~~~~~~~~~~~~~~~~~ +This is another :mod:`import ` element, and it uses +the :mod:`local ` source type so that we can stage files +literally stored in the same repository as the project. + +.. literalinclude:: ../../examples/flatpak-autotools/elements/base/usrmerge.bst + :language: yaml + +The purpose of this element is simply to add the symlinks for +``/lib -> /usr/lib``, ``/bin -> /usr/bin`` and ``/etc -> /usr/etc``, we +have it depend on the ``base/sdk.bst`` element only to ensure that +it is staged *after*, i.e. the symlinks are created after the SDK is staged. + +As suggested by the ``.bst`` file, the symlinks themselves are a part +of the project and they are stored in the ``files/links`` directory. + + +base.bst +~~~~~~~~ +This is just a :mod:`stack ` element for convenience sake. + +.. literalinclude:: ../../examples/flatpak-autotools/elements/base.bst + :language: yaml + +Often times you will have a more complex base to build things on, and it +is convenient to just use a :mod:`stack ` element for +your elements to depend on without needing to know about the inner workings +of the base system build. + + +hello.bst +~~~~~~~~~ +Finally, we show an example of an :mod:`autotools ` element +to build our sample "Hello World" program. + +.. literalinclude:: ../../examples/flatpak-autotools/elements/hello.bst + :language: yaml + +We use another :mod:`local ` source to obtain the sample +autotools project, but normally you would probably use a :mod:`git ` +or other source to obtain source code from another repository. + + +Using the project +----------------- +Now that we've explained the basic layout of the project, here are +just a few things you can try to do with the project. + +.. note:: + + The following examples assume that you have first changed your working + directory to the + `project root `_. + + +Build the hello.bst element +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To build the project, run :ref:`bst build ` in the +following way: + +.. raw:: html + :file: ../sessions/flatpak-autotools-build.html + + +Run the hello world program +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The hello world program has been built into the standard ``/usr`` prefix, +and will automatically be in the default ``PATH`` for running things +in a :ref:`bst shell `. + +To just run the program, run :ref:`bst shell ` in the +following way: + +.. raw:: html + :file: ../sessions/flatpak-autotools-shell.html diff --git a/doc/source/examples_flatpak_autotools.rst b/doc/source/examples_flatpak_autotools.rst deleted file mode 100644 index f2c66174d..000000000 --- a/doc/source/examples_flatpak_autotools.rst +++ /dev/null @@ -1,144 +0,0 @@ - -.. _examples_flatpak_autotools: - -Building on a Flatpak SDK -========================= -Here we demonstrate how to build and run software using -a Flatpak SDK for the base runtime. - -.. note:: - - This example is distributed with BuildStream - in the `doc/examples/flatpak-autotools - `_ - subdirectory. - - -Project structure ------------------ - - -project.conf -~~~~~~~~~~~~ -The following is a simple :ref:`project ` definition: - -.. literalinclude:: ../examples/flatpak-autotools/project.conf - :language: yaml - -Here we use an :ref:`arch option ` to allow -conditional statements in this project to be made depending on machine -architecture. For this example we only support the ``i386`` and ``x86_64`` -architectures. - -Note that we've added a :ref:`source alias ` for -the ``https://sdk.gnome.org/`` repository to download the SDK from. - - -base/sdk.bst -~~~~~~~~~~~~ -This is the :mod:`import ` element used to import the -actual Flatpak SDK, it uses an :mod:`ostree ` source to -download the Flatpak since these are hosted in OSTree repositories. - -.. literalinclude:: ../examples/flatpak-autotools/elements/base/sdk.bst - :language: yaml - -While declaring the :mod:`ostree ` source, we specify a GPG -public key to verify the OSTree download. This configuration is optional -but recommended for OSTree repositories. The key is stored in the project directory -at ``keys/gnome-sdk.gpg``. - -We also use :ref:`conditional statements ` to decide -which branch to download. - -For the ``config`` section of this :mod:`import ` element, -it's important to note two things: - -* **source**: We only want to extract the ``files/`` directory from the SDK, - - This is becase Flatpak runtimes dont start at the root of the OSTree checkout, - instead the actual files start in the ``files//`` subdirectory - -* **target**: The content we've extracted should be staged at ``/usr`` - - This is because Flatpak runtimes only contain the data starting at ``/usr``, - and they expect to be staged at ``/usr`` at runtime, in an environment - with the appropriate symlinks setup from ``/``. - - -base/usrmerge.bst -~~~~~~~~~~~~~~~~~ -This is another :mod:`import ` element, and it uses -the :mod:`local ` source type so that we can stage files -literally stored in the same repository as the project. - -.. literalinclude:: ../examples/flatpak-autotools/elements/base/usrmerge.bst - :language: yaml - -The purpose of this element is simply to add the symlinks for -``/lib -> /usr/lib``, ``/bin -> /usr/bin`` and ``/etc -> /usr/etc``, we -have it depend on the ``base/sdk.bst`` element only to ensure that -it is staged *after*, i.e. the symlinks are created after the SDK is staged. - -As suggested by the ``.bst`` file, the symlinks themselves are a part -of the project and they are stored in the ``files/links`` directory. - - -base.bst -~~~~~~~~ -This is just a :mod:`stack ` element for convenience sake. - -.. literalinclude:: ../examples/flatpak-autotools/elements/base.bst - :language: yaml - -Often times you will have a more complex base to build things on, and it -is convenient to just use a :mod:`stack ` element for -your elements to depend on without needing to know about the inner workings -of the base system build. - - -hello.bst -~~~~~~~~~ -Finally, we show an example of an :mod:`autotools ` element -to build our sample "Hello World" program. - -.. literalinclude:: ../examples/flatpak-autotools/elements/hello.bst - :language: yaml - -We use another :mod:`local ` source to obtain the sample -autotools project, but normally you would probably use a :mod:`git ` -or other source to obtain source code from another repository. - - -Using the project ------------------ -Now that we've explained the basic layout of the project, here are -just a few things you can try to do with the project. - -.. note:: - - The following examples assume that you have first changed your working - directory to the - `project root `_. - - -Build the hello.bst element -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To build the project, run :ref:`bst build ` in the -following way: - -.. raw:: html - :file: sessions/flatpak-autotools-build.html - - -Run the hello world program -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The hello world program has been built into the standard ``/usr`` prefix, -and will automatically be in the default ``PATH`` for running things -in a :ref:`bst shell `. - -To just run the program, run :ref:`bst shell ` in the -following way: - -.. raw:: html - :file: sessions/flatpak-autotools-shell.html -- cgit v1.2.1