From c205991ed80c0f18067e0daa5d67318735bc575d Mon Sep 17 00:00:00 2001 From: Tristan Van Berkom Date: Wed, 16 May 2018 15:14:36 +0900 Subject: doc/source/examples_flatpak_autotools.rst: Enhanced example This has now changed to: * Have explanations of the project.conf and each element in the example, explaining what they are for * Have links into the reference for the specific features this example uses, such that the reader can get familiar with the reference manual from example windows --- doc/source/examples_flatpak_autotools.rst | 129 +++++++++++++++++++++++++++--- 1 file changed, 117 insertions(+), 12 deletions(-) diff --git a/doc/source/examples_flatpak_autotools.rst b/doc/source/examples_flatpak_autotools.rst index d30e5435d..2c03fa621 100644 --- a/doc/source/examples_flatpak_autotools.rst +++ b/doc/source/examples_flatpak_autotools.rst @@ -1,33 +1,138 @@ .. _examples_flatpak_autotools: -Using flatpak runtimes to build and run from source -=================================================== +Building on a Flatpak SDK +========================= Here we demonstrate how to build and run software using a Flatpak SDK for the base runtime. -Config files -- project.conf +Project structure +----------------- + + +project.conf +~~~~~~~~~~~~ +The following is a simple :ref:`project ` definition: .. literalinclude:: ../examples/flatpak-autotools/project.conf :language: yaml -- element +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/flatpak-autotools.bst +.. literalinclude:: ../examples/flatpak-autotools/elements/base/sdk.bst :language: yaml -- element +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 -.. literalinclude:: ../examples/flatpak-autotools/elements/dependencies/usrmerge.bst +* **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 -Building:: +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. + + This example is a part of the BuildStream source repository in + the doc/examples/flatpak-autotools subdirectory. + + +Build the hello.bst element +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To build the project, run :ref:`bst build ` in the +following way:: + + bst build hello.bst - bst build flatpak-autotools.bst -Running:: +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 `. - bst shell flatpak-autotools.bst hello +To just run the program, run :ref:`bst shell ` in the +following way:: + bst shell hello.bst -- hello -- cgit v1.2.1