Skip to content

Commit 4e94758

Browse files
allandayallanday
authored
Merge pull request #98 from flatpak/building-improvements
Rationalise building section
2 parents bd2d7ca + 3825566 commit 4e94758

9 files changed

+224
-245
lines changed

‎docs/building-basics.rst

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
Building Concepts and Setup
2+
===========================
3+
4+
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.
5+
6+
Runtimes
7+
--------
8+
9+
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.
10+
11+
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.
12+
13+
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!
14+
15+
.. tip::
16+
17+
Runtimes require regular maintenance, and application developers should generally not consider creating their own.
18+
19+
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::
20+
21+
$ flatpak install flathub org.gnome.Platform//3.26
22+
23+
Software Development Kits (SDKs)
24+
--------------------------------
25+
26+
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.
27+
28+
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.
29+
30+
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::
31+
32+
$ flatpak install flathub org.gnome.Sdk//3.26
33+
34+
Bundling
35+
--------
36+
37+
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.
38+
39+
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.
40+
41+
The specifics of how to bundle libraries is covered in the :doc:`manifests` section.

‎docs/building.rst

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
Building
22
========
33

4-
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``.
4+
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.
5+
6+
If you haven't already, it is recommended to run through :doc:`first-build` before reading this section.
57

68
.. toctree::
79
:maxdepth: 2
810

9-
runtimes-sdks
11+
building-basics
1012
flatpak-builder
1113
manifests
12-
flatpak-builder-tutorial

‎docs/first-build.rst

+62-94
Original file line numberDiff line numberDiff line change
@@ -1,130 +1,98 @@
1-
Building your first Flatpak
1+
Building Your First Flatpak
22
===========================
33

4-
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.
4+
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.
55

6-
Please follow the :doc:`setup` page before doing this tutorial.
6+
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.
77

8-
1. Install a runtime and the matching SDK
9-
-----------------------------------------
8+
1. Create a manifest
9+
--------------------
1010

11-
Flatpak requires every app to specify a runtime that it uses for its basic
12-
dependencies. Each runtime has a matching SDK (Software Development Kit), which
13-
contains all the things that are in the runtime, plus headers and development
14-
tools. This SDK is required to build apps for the runtime.
15-
16-
In this tutorial we will use the Freedesktop 1.6 runtime and SDK. To install these, run::
17-
18-
$ flatpak install flathub org.freedesktop.Platform//1.6 org.freedesktop.Sdk//1.6
19-
20-
2. Create the app
21-
-----------------
22-
23-
The app that is going to be created for this tutorial is a simple script. To
24-
create it, copy the following::
25-
26-
#!/bin/sh
27-
echo "Hello world, from a sandbox"
28-
29-
Now paste this into an empty file and save it as `hello.sh`.
30-
31-
3. Add a manifest
32-
-----------------
33-
34-
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:
11+
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:
3512

3613
.. code-block:: json
3714
3815
{
39-
"app-id": "org.flatpak.Hello",
40-
"runtime": "org.freedesktop.Platform",
41-
"runtime-version": "1.6",
42-
"sdk": "org.freedesktop.Sdk",
43-
"command": "hello.sh",
44-
"modules": [
16+
"app-id": "org.gnome.Dictionary",
17+
"runtime": "org.gnome.Platform",
18+
"runtime-version": "3.26",
19+
"sdk": "org.gnome.Sdk",
20+
"command": "gnome-dictionary",
21+
"finish-args": [
22+
"--socket=x11",
23+
"--share=network"
24+
],
25+
"modules": [
26+
{
27+
"name": "gnome-dictionary",
28+
"sources": [
4529
{
46-
"name": "hello",
47-
"buildsystem": "simple",
48-
"build-commands": [
49-
"install -D hello.sh /app/bin/hello.sh"
50-
],
51-
"sources": [
52-
{
53-
"type": "file",
54-
"path": "hello.sh"
55-
}
56-
]
30+
"type": "archive",
31+
"url": "https://download.gnome.org/sources/gnome-dictionary/3.26/gnome-dictionary-3.26.0.tar.xz",
32+
"sha256": "387ff8fbb8091448453fd26dcf0b10053601c662e59581097bc0b54ced52e9ef"
5733
}
58-
]
34+
]
35+
}
36+
]
5937
}
6038
61-
Now save the file alongside `hello.sh` and call it `org.flatpak.Hello.json`.
62-
63-
In a more complex application, the manifest would list multiple modules. The
64-
last one would typically be the application itself, and the earlier ones would
65-
be dependencies that are bundled with the app because they are not part of the
66-
runtime.
39+
As can be seen, this manifest includes basic information about the application, including:
6740

68-
4. Build the application
69-
------------------------
41+
- ``app-id`` - the application ID
42+
- ``runtime`` - the runtime, which provides the environment that the application will run in, as well as basic dependencies it can use
43+
- ``sdk`` - the Software Development Kit, which is a version of the runtime with development files and headers; this is required to build the app
44+
- ``command`` - the command that is used to run the application
45+
- ``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
7046

71-
Now that the app has a manifest, `flatpak-builder` can be used to build it.
72-
This is done by specifying the manifest file and a target directory::
47+
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.
7348

74-
$ flatpak-builder app-dir org.flatpak.Hello.json
49+
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.
7550

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

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

82-
To verify that the build was successful, run the following::
55+
2. Run the build
56+
----------------
8357

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

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

88-
6. Put the app in a repository
89-
------------------------------
62+
This will:
9063

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

94-
$ flatpak-builder --repo=repo --force-clean app-dir org.flatpak.Hello.json
70+
``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``).
9571

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

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

104-
7. Install the app
105-
------------------
77+
$ flatpak --user remote-add --no-gpg-verify --if-not-exists tutorial-repo tutorial-repo
10678

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

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

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

116-
Both these commands use the `--user` argument, which means that the repository
117-
and the app are added per-user rather than system-wide. This is useful for testing.
86+
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``::
11887

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

123-
8. Run the app
124-
--------------
91+
5. Run the application
92+
----------------------
12593

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

128-
$ flatpak run org.flatpak.Hello
96+
$ flatpak run org.gnome.Dictionary
12997

130-
This runs the app, so that it prints `Hello world, from a sandbox`.
98+
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`.

‎docs/flatpak-builder-tutorial.rst

-52
This file was deleted.

‎docs/flatpak-builder.rst

+22-10
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,54 @@
11
Flatpak Builder
22
===============
33

4-
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.
4+
``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.
55

6-
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.
6+
Invocation
7+
----------
8+
9+
The basic format used to invoke ``flatpak-builder`` is::
10+
11+
$ flatpak-builder <directory> <manifest>
12+
13+
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.
14+
15+
The contents of ``<directory>`` can be useful for testing and debugging purposes, but is generally treated as an artifact of the build process.
716

817
Exporting
918
---------
1019

11-
The result of the build process can be exported to a repository or automatically installed locally.
20+
``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.
1221

1322
Exporting to a repository
1423
`````````````````````````
1524

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

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

29+
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.
2030

2131
.. note::
2232

23-
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.
33+
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.
2434

2535

2636
Installing builds directly
2737
``````````````````````````
2838

29-
Instead of exporting to a repository, the application bundle that is produced by ``flatpak-builder`` can be automatically installed locally::
39+
Instead of exporting to a repository, the Flatpak that is produced by ``flatpak-builder`` can be automatically installed locally, using the ``--install`` option::
40+
41+
$ flatpak-builder --install <directory> <manifest>
3042

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

3345
Signing
3446
-------
3547

3648
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::
3749

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

40-
The ``--gpg-homedir`` option can also be used to specify the home directory of the key that is being used.
52+
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.
4153

4254
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.

0 commit comments

Comments
 (0)