Skip to content

Commit

Permalink
Rationalise building section
Browse files Browse the repository at this point in the history 
- Get rid of the spurious flatpak-builder tutorial
- Make the flatpak-builder tutorial more instructive
- Integrate the tutorial into the rest of the building pages
- Expand some the pages on flatpak-builder and manifests

Fixes #74. Helps with #24, #66 and #69
  • Loading branch information
@allanday
allanday committed Mar 22, 2018
1 parent bd2d7ca commit 3825566
Show file tree
Hide file tree
Showing 9 changed files with 224 additions and 245 deletions.
41 changes: 41 additions & 0 deletions docs/building-basics.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
Building Concepts and Setup
===========================

The :doc:`introduction` and page on :doc:`first-build` have already shown how applications get built as Flatpaks, and have introduced many of the core ideas. This page describes some of these ideas and concepts in more detail. In doing so, it provides guidance on picking a runtime, getting setup to build applications, and when to bundle dependencies yourself.

Runtimes
--------

As was described in the :doc:`introduction`, runtimes provide basic dependencies that can be used by applications. They also provide the environment that applications run in.

Flatpak requires each application to specify a runtime, and this runtime must be present on a system for it to run. Therefore, one of the first decisions you need to make when building an application with Flatpak, is which runtime it will use.

An overview of the runtimes that are available can be found in the :doc:`available-runtimes` page. There are deliberately only a small number of runtimes to choose from. Typically, runtimes are picked on the basis of which dependencies an application requires. If a runtime exists that provides libraries that you plan on using, this is usually the correct runtime to use!

.. tip::

Runtimes require regular maintenance, and application developers should generally not consider creating their own.

Runtimes are automatically installed for users when they install an application, and build tools can also automatically install them for you (``flatpak-builder``'s ``--install-deps-from`` option is useful for this). However, if you do need to manually install your chosen runtime, this can be done in the same way as installing an application, with the ``flatpak install`` command. For example, the command to install the GNOME 3.26 runtime is::

$ flatpak install flathub org.gnome.Platform//3.26

Software Development Kits (SDKs)
--------------------------------

Each runtime is paired with an SDK (Software Develpment Kit). For example, the GNOME 3.26 runtime is accompanied by the GNOME 3.26 SDK. The SDK includes the same things as the regular runtime, but also includes all the development resources and tools that are required to build an application, such as build and packaging tools, header files, compilers and debuggers.

Applications must be built with the SDK that corresponds to their runtime, so that applications that use the GNOME 3.26 runtime must be built with the GNOME 3.26 SDK.

Like runtimes, SDKs will sometimes be automatically installed for you, but if you do need to manually install them, they are installed in the same was as applications and runtimes, such as::

$ flatpak install flathub org.gnome.Sdk//3.26

Bundling
--------

One of the key advantages of Flatpak is that it allows application authors to bundle whatever libraries or dependencies that they want. This means that developers aren't constrained by which libraries are available through Linux distributions. It also provides flexibility, allowing particular versions of libraries to be used, or the use of libraries that have been patched.

While bundling is very powerful and flexible, it also places a greater maintenance burden on the application developer. Therefore, while it is possible to bundle as much as you would like, it is generally recommended to try and keep the number of bundled modules as low as possible. If a dependency is available as part of a runtime, it is generally better to use the version from the runtime rather than bundle it yourself.

The specifics of how to bundle libraries is covered in the :doc:`manifests` section.
7 changes: 4 additions & 3 deletions docs/building.rst
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
Building
========

This section includes documentation on how to build apps with Flatpak. It covers runtimes and SDKs in more detail, followed by details on how use ``flatpak-builder``.
This section contains detailed information on how to build applications as Flatpaks, including information on concepts, guidance on key decisions, detailed information on how to use ``flatpak-builder``, and how to write manifest files.

If you haven't already, it is recommended to run through :doc:`first-build` before reading this section.

.. toctree::
:maxdepth: 2

runtimes-sdks
building-basics
flatpak-builder
manifests
flatpak-builder-tutorial
156 changes: 62 additions & 94 deletions docs/first-build.rst
View file
Original file line number Diff line number Diff line change
@@ -1,130 +1,98 @@
Building your first Flatpak
Building Your First Flatpak
===========================

This tutorial provides a quick introduction to building Flatpaks. In it, you will learn how to create a basic Flatpak application, which can be installed and run.
This tutorial provides a quick, step-by-step example of how to build a simple application as a Flatpak. It also takes the opportunity to explain a few key concepts.

Please follow the :doc:`setup` page before doing this tutorial.
In order to complete this tutorial, you should have followed the `setup guide on flatpak.org <http://flatpak.org/setup/>`_. You also need to have installed ``flatpak-builder``, which is usually available from the same repository as the ``flatpak`` package.

1. Install a runtime and the matching SDK
-----------------------------------------
1. Create a manifest
--------------------

Flatpak requires every app to specify a runtime that it uses for its basic
dependencies. Each runtime has a matching SDK (Software Development Kit), which
contains all the things that are in the runtime, plus headers and development
tools. This SDK is required to build apps for the runtime.

In this tutorial we will use the Freedesktop 1.6 runtime and SDK. To install these, run::

$ flatpak install flathub org.freedesktop.Platform//1.6 org.freedesktop.Sdk//1.6

2. Create the app
-----------------

The app that is going to be created for this tutorial is a simple script. To
create it, copy the following::

#!/bin/sh
echo "Hello world, from a sandbox"

Now paste this into an empty file and save it as `hello.sh`.

3. Add a manifest
-----------------

Each Flatpak is built using a manifest file which provides basic information about the application and instructions for how it is to be built. To add a manifest to the hello world app, add the following to an empty file:
The input to ``flatpak-builder`` is a JSON file that describes the parameters for building the application. This is called the manifest. The following example is the manifest for the GNOME Dictionary application:

.. code-block:: json
{
"app-id": "org.flatpak.Hello",
"runtime": "org.freedesktop.Platform",
"runtime-version": "1.6",
"sdk": "org.freedesktop.Sdk",
"command": "hello.sh",
"modules": [
"app-id": "org.gnome.Dictionary",
"runtime": "org.gnome.Platform",
"runtime-version": "3.26",
"sdk": "org.gnome.Sdk",
"command": "gnome-dictionary",
"finish-args": [
"--socket=x11",
"--share=network"
],
"modules": [
{
"name": "gnome-dictionary",
"sources": [
{
"name": "hello",
"buildsystem": "simple",
"build-commands": [
"install -D hello.sh /app/bin/hello.sh"
],
"sources": [
{
"type": "file",
"path": "hello.sh"
}
]
"type": "archive",
"url": "https://download.gnome.org/sources/gnome-dictionary/3.26/gnome-dictionary-3.26.0.tar.xz",
"sha256": "387ff8fbb8091448453fd26dcf0b10053601c662e59581097bc0b54ced52e9ef"
}
]
]
}
]
}
Now save the file alongside `hello.sh` and call it `org.flatpak.Hello.json`.

In a more complex application, the manifest would list multiple modules. The
last one would typically be the application itself, and the earlier ones would
be dependencies that are bundled with the app because they are not part of the
runtime.
As can be seen, this manifest includes basic information about the application, including:

4. Build the application
------------------------
- ``app-id`` - the application ID
- ``runtime`` - the runtime, which provides the environment that the application will run in, as well as basic dependencies it can use
- ``sdk`` - the Software Development Kit, which is a version of the runtime with development files and headers; this is required to build the app
- ``command`` - the command that is used to run the application
- ``finish-args`` - configuration options which give the application access to resources outside of its sandbox; in this case, the application is being given network access and access to the X11 display server

Now that the app has a manifest, `flatpak-builder` can be used to build it.
This is done by specifying the manifest file and a target directory::
The next part of the manifest is the ``modules`` list. This describes each of the modules that are to be built as part of the build process. One of these modules is always the application. Others can be libraries and other resources that are bundled as part of the application.

$ flatpak-builder app-dir org.flatpak.Hello.json
Module sources can be of several types, including ``.tar`` or ``.zip`` archives, Git or Bzr repositories. In this case, there is only one module, which is a ``.tar`` file which will be downloaded and built.

This command will build each module that is listed in the manifest and install
it to the `/app` subdirectory, inside the `app-dir` directory.
The modules section of the Dictionary manifest is short, because only one module is built: the application itself.

5. Test the build
-----------------
To create a manifest for the Dictionary, create a file called ``org.gnome.Dictionary.json`` and paste the JSON from above into it.

To verify that the build was successful, run the following::
2. Run the build
----------------

$ flatpak-builder --run app-dir org.flatpak.Hello.json hello.sh
To use the manifest to build the Dictionary application, run the following command::

Congratulations, you've made an app!
$ flatpak-builder --repo=tutorial-repo dictionary org.gnome.Dictionary.json

6. Put the app in a repository
------------------------------
This will:

Before you can install and run the app, it first needs to be put in a
repository. This is done by passing the `--repo` argument to `flatpak-builder`::
* Create a new directory called dictionary
* Download and verify the Dictionary source code
* Build and install the source code, inside the SDK rather than the host system
* Finish the build, by setting permissions (in this case giving access to X11 and the network)
* Create a new repository called repo (if it doesn't exist) and export the resulting build into it

$ flatpak-builder --repo=repo --force-clean app-dir org.flatpak.Hello.json
``flatpak-builder`` will also do some other useful things, like creating a separately installable debug runtime (called ``org.gnome.Dictionary.Debug`` in this case) and a separately installable translation runtime (called ``org.gnome.Dictionary.Locale``).

This does the build again, and at the end exports the result to a local
directory called `repo`. Note that `flatpak-builder` keeps a cache of previous
builds in the `.flatpak-builder` subdirectory, so doing a second build like
this is very fast.
3. Add the new repository
-------------------------

This second time we passed in `--force-clean`, which means that the previously
created `app-dir` directory was deleted before the new build was started.
To test the application that has been built, you need to add the new repository that has been created::

7. Install the app
------------------
$ flatpak --user remote-add --no-gpg-verify --if-not-exists tutorial-repo tutorial-repo

Now we're ready to add the repository that was just created and install the
app. This is done with two commands::
4. Install the application
--------------------------

$ flatpak --user remote-add --no-gpg-verify tutorial-repo repo
$ flatpak --user install tutorial-repo org.flatpak.Hello
The next step is to install the Dictionary application from the repository. To do this, run::

The first command adds the repository that was created in the previous step.
The second command installs the app from the repository.
$ flatpak --user install tutorial-repo org.gnome.Dictionary

Both these commands use the `--user` argument, which means that the repository
and the app are added per-user rather than system-wide. This is useful for testing.
To check that the application has been successfully installed, you can compare the sha256 commit of the installed app with the commit ID that was printed by ``flatpak-builder``::

Note that the repository was added with `--no-gpg-verify`, since a GPG key
wasn't specified when the app was built. This is fine for testing, but for
official repositories you should sign them with a private GPG key.
$ flatpak info org.gnome.Dictionary
$ flatpak info org.gnome.Dictionary.Locale

8. Run the app
--------------
5. Run the application
----------------------

All that's left is to try the app. This can be done with the following command::
Finally, you can run the application that you've built::

$ flatpak run org.flatpak.Hello
$ flatpak run org.gnome.Dictionary

This runs the app, so that it prints `Hello world, from a sandbox`.
The rest of the documentation provides a complete guide to using ``flatpak-builder``. If you are new to Flatpak, it is recommended to start with the :doc:`introduction`.
52 changes: 0 additions & 52 deletions docs/flatpak-builder-tutorial.rst
View file

This file was deleted.

32 changes: 22 additions & 10 deletions docs/flatpak-builder.rst
View file
Original file line number Diff line number Diff line change
@@ -1,42 +1,54 @@
Flatpak Builder
===============

Flatpaks are built using the ``flatpak-builder`` tool. This allows a series of modules to be built into a single application bundle. These modules can include libraries and dependencies in addition to the application itself.
``flatpak-builder`` has already been introduced in :doc:`first-build`, which gave a basic example of how it can be used. This page provides additional detail on how to use ``flatpak-builder``, including the various command options that are available.

Modules can be built with a variety of build systems, including `autotools <https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html>`_, `cmake <https://cmake.org/>`_, `cmake-ninja <https://cmake.org/cmake/help/v3.0/generator/Ninja.html>`_, `meson <http://mesonbuild.com/>`_, and the so called `Build API <https://github.com/cgwalters/build-api/>`_. A "simple" build method is also available, which allows a series of commands to be specified.
Invocation
----------

The basic format used to invoke ``flatpak-builder`` is::

$ flatpak-builder <directory> <manifest>

Where ``<directory>`` is the path to the directory that the application will be built into, and ``<manifest>`` is the path to a manifest JSON file.

The contents of ``<directory>`` can be useful for testing and debugging purposes, but is generally treated as an artifact of the build process.

Exporting
---------

The result of the build process can be exported to a repository or automatically installed locally.
``flatpak-builder`` provides two options for exporting an application in order to run it. The first is to export to a repository, from which the application can be run. The second is to automatically install locally.

Exporting to a repository
`````````````````````````

The ``--repo`` option allows a repository to be specified, which the resulting application will be added to. This takes the format::
The ``--repo`` option allows a repository to be specified, for the application to be exported to. This takes the format::

$ flatpak-builder --repo=<repository-destination> application.id.json
$ flatpak-builder --repo=<repository> <directory> <manifest>

Here, ``<repository>`` is a path to a repository. If no repository exists at the specified location, the repository will be created. If the application is already in the specified repository, ``flatpak-builder`` will add the build as a new version of the existing application.

.. note::

By default, flatpak-builder splits off translations and debug information into separate `.Locale` and `.Debug` extensions. These extensions are automatically exported into a repository along with the application.
By default, ``flatpak-builder`` splits off translations and debug information into separate `.Locale` and `.Debug` extensions. These extensions are automatically exported into a repository along with the application.


Installing builds directly
``````````````````````````

Instead of exporting to a repository, the application bundle that is produced by ``flatpak-builder`` can be automatically installed locally::
Instead of exporting to a repository, the Flatpak that is produced by ``flatpak-builder`` can be automatically installed locally, using the ``--install`` option::

$ flatpak-builder --install <directory> <manifest>

$ flatpak-builder --install application.id.json
This approach has the advantage of skipping the separate install step that is needed when exporting to a repository.

Signing
-------

Every commit to a Flatpak repository should be signed with a GPG signature. If ``flatpak-builder`` is being used to modify or create a repository, a GPG key should therefore be passed to it. This can be done with the ``--gpg-sign`` option, such as::

$ flatpak-builder --gpg-sign=<key-id> --repo=<repository-destination> application.id.json
$ flatpak-builder --gpg-sign=<key> --repo=<repository> <manifest>

The ``--gpg-homedir`` option can also be used to specify the home directory of the key that is being used.
Here, ``<key>`` is the ID of the GPG key that is to be used. The ``--gpg-homedir`` option can also be used to specify the home directory of the key that is being used.

Though it generally isn't recommended, it is possible not to use GPG verification. In this case, the ``--no-gpg-verify`` option should be used when adding the repository. Note that it is necessary to become root in order to update a repository that does not have GPG verification enabled.
Loading

0 comments on commit 3825566

Please sign in to comment.