-
Notifications
You must be signed in to change notification settings - Fork 143
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Rationalise building section #98
Merged
+224
−245
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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`. | ||
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,11 +1,12 @@ | ||
| Getting Started | ||
| =============== | ||
|
|
||
| First steps with Flatpak, including installation, basic usage, and building your first app. | ||
| Information on how to take your first steps with Flatpak, including basic command line usage and how to build a simple application. | ||
|
|
||
| To complete this section, Flatpak should have been installed and the Flathub repository have been enabled. The Flatpak website provides `instructions for how to do this with a range of distributions <https://flatpak.org/setup/>`_. | ||
|
|
||
| .. toctree:: | ||
| :maxdepth: 2 | ||
|
|
||
| setup | ||
| using-flatpak | ||
| first-build |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I realize you are trying to be minimal but this leaves some bad habits like not including
--socket=waylandand--share=ipcfor Gtk3 applications.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The only reason those are the only sandbox permissions in the example is that they're what's in the manifest I inherited. I'd love to have a better demo with a sane set of options in it (that's #97)!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
All Gtk3 applications will have like 7 or so permissions to just be fully functional.