doc/source/examples/flatpak-autotools.rst

.. _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
   <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/flatpak-autotools>`_
   subdirectory.


Project structure
-----------------

The following is a simple :ref:`project <projectconf>` definition:

``project.conf``
~~~~~~~~~~~~~~~~

.. literalinclude:: ../../examples/flatpak-autotools/project.conf
   :language: yaml

Here we use an :ref:`arch option <project_options_arch>` 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 <project_source_aliases>` for
the ``https://sdk.gnome.org/`` repository to download the SDK from.


``elements/base/sdk.bst``
~~~~~~~~~~~~~~~~~~~~~~~~~

.. literalinclude:: ../../examples/flatpak-autotools/elements/base/sdk.bst
   :language: yaml

This is the :mod:`import <elements.import>` element used to import the
actual Flatpak SDK, it uses an :mod:`ostree <sources.ostree>` source to
download the Flatpak since these are hosted in OSTree repositories.

While declaring the :mod:`ostree <sources.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``, and can be downloaded from https://sdk.gnome.org/keys/.

We also use :ref:`conditional statements <format_directives_conditional>` to decide
which branch to download.

For the ``config`` section of this :mod:`import <elements.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 ``/``.


``elements/base/usrmerge.bst``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. literalinclude:: ../../examples/flatpak-autotools/elements/base/usrmerge.bst
   :language: yaml

This is another :mod:`import <elements.import>` element, and it uses
the :mod:`local <sources.local>` source type so that we can stage files
literally stored in the same repository as the project.

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.


``elements/base.bst``
~~~~~~~~~~~~~~~~~~~~~

.. literalinclude:: ../../examples/flatpak-autotools/elements/base.bst
   :language: yaml

This is just a :mod:`stack <elements.stack>` element for convenience sake.

Often times you will have a more complex base to build things on, and it
is convenient to just use a :mod:`stack <elements.stack>` element for
your elements to depend on without needing to know about the inner workings
of the base system build.


``elements/hello.bst``
~~~~~~~~~~~~~~~~~~~~~~

.. literalinclude:: ../../examples/flatpak-autotools/elements/hello.bst
   :language: yaml

Finally, we show an example of an :mod:`autotools <elements.autotools>` element
to build our sample "Hello World" program.

We use another :mod:`local <sources.local>` source to obtain the sample
autotools project, but normally you would probably use a :mod:`git <sources.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 <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/flatpak-autotools>`_.


Build the hello.bst element
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To build the project, run :ref:`bst build <invoking_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 <invoking_shell>`.

To just run the program, run :ref:`bst shell <invoking_shell>` in the
following way:

.. raw:: html
   :file: ../sessions/flatpak-autotools-shell.html