diff --git a/docs/debugging.rst b/docs/debugging.rst index c90d097d..bad3bcc9 100644 --- a/docs/debugging.rst +++ b/docs/debugging.rst @@ -180,8 +180,8 @@ Audit session or system bus traffic A ``--socket=session-bus`` or a ``--socket=system-bus`` permission must not be present for the logging to work. -Session or system bus traffic can be audited by passing ``--log-session-bus`` -and ``--log-system-bus`` respectively to ``flatpak run``:: +Session bus traffic can be audited by passing ``--log-session-bus`` to +``flatpak run``:: flatpak run --log-session-bus @@ -190,3 +190,9 @@ and the corresponding ``--talk-name`` or ``--own-name`` permissions required:: flatpak --log-session-bus run | grep '(required 1)' + +Similarly, system bus traffic can be audited by passing ``--log-system-bus`` +to ``flatpak run``. This also requires a system bus name to be present +in the permissions. If not a bogus bus name can be passed:: + + flatpak run --log-system-bus --system-talk-name=org.example.foo diff --git a/docs/manifests.rst b/docs/manifests.rst index 4c4ef996..b24fa408 100644 --- a/docs/manifests.rst +++ b/docs/manifests.rst @@ -143,22 +143,95 @@ the Flatpak. While simple applications may only specify one or two modules, and therefore have short modules sections, some applications can bundle numerous modules and therefore have lengthy modules sections. -GNOME Dictionary's modules section is short, since it just contains the -application itself, and looks like: +Modules are built in the order they are declared in the manifest. If any +module changes, that module and all the subsequent modules below it will +be rebuilt, otherwise it should use the cache. + +The general recommendation is to place the "main" module, usually the +module for the main application as the last module in the manifest but +if there is a module which gets updated often and is independent from the +rest, that module can also be placed as the last module to avoid +rebuilding everything else. + +Modules can either be nested to clearly show the dependency structure +or be linearly declared. .. code-block:: yaml - modules: - - name: gnome-dictionary - buildsystem: meson - config-opts: - - -Dbuild_man=false - sources: - - type: archive - url: https://download.gnome.org/sources/gnome-dictionary/3.26/gnome-dictionary-3.26.1.tar.xz - sha256: 16b8bc248dcf68987826d5e39234b1bb7fd24a2607fcdbf4258fde88f012f300 - - type: patch - path: appdata_oars.patch + # Nested + + finish-args: + - --share=ipc + - --socket=fallback-x11 + - --socket=wayland + - --socket=pulseaudio + + modules: + - name: video-player-app + buildsystem: meson + config-opts: + - --buildtype=release + cleanup: + - /share/man + sources: + - type: archive + url: https://example.com/release.tar.gz + sha256: 216656c4495bb3ca02dc4ad9cf3da8e8f15c8f80e870eeac8eb1eedab4c3788b + modules: + - name: libmpv + buildsystem: meson + config-opts: + - -Dlibmpv=true + sources: + - type: archive + url: https://example.com/mpv.tar.gz + sha256: 2ca92437affb62c2b559b4419ea4785c70d023590500e8a52e95ea3ab4554683 + modules: + - "shared-modules/lua5.1/lua-5.1.5.json" + + - name: libv4l2 + buildsystem: meson + sources: + - type: archive + url: url: https://example.com/libv4l2.tar.gz + sha256: 0fa075ce59b6618847af6ea191b6155565ccaa44de0504581ddfed795a328a82 + # Linear + + finish-args: + - --share=ipc + - --socket=fallback-x11 + - --socket=wayland + - --socket=pulseaudio + + modules: + - "shared-modules/lua5.1/lua-5.1.5.json" + + - name: libv4l2 + buildsystem: meson + sources: + - type: archive + url: url: https://example.com/libv4l2.tar.gz + sha256: 0fa075ce59b6618847af6ea191b6155565ccaa44de0504581ddfed795a328a82 + + - name: libmpv + buildsystem: meson + config-opts: + - -Dlibmpv=true + sources: + - type: archive + url: https://example.com/mpv.tar.gz + sha256: 2ca92437affb62c2b559b4419ea4785c70d023590500e8a52e95ea3ab4554683 + + - name: video-player-app + buildsystem: meson + config-opts: + - --buildtype=release + cleanup: + - /share/man + sources: + - type: archive + url: https://example.com/release.tar.gz + sha256: 216656c4495bb3ca02dc4ad9cf3da8e8f15c8f80e870eeac8eb1eedab4c3788b As can be seen, each listed module has a ``name`` (which can be freely assigned) and a list of ``sources``. Each source has a ``type``, and available @@ -189,43 +262,83 @@ Modules can be built with a variety of build systems, including: - `cmake-ninja `_ - `meson `_ - `qmake `_ -- the "`Build API `_" - -A "simple" build method is also available, which allows a series of commands -to be specified. -Shared Modules -`````````````` +A "simple" build method is also available, which allows a series of +commands to be specified. -`Shared Modules (or shared-modules) `_ is a repository containing various manifests to build common libraries. It is intended to be used as a git submodule. +Each of the above buildsystem sets up the installation prefix, libdir +etc. and runs a series of commands to configure (``meson setup``, or +``./autogen.sh, ./configure`` or ``cmake``), build, install +(``ninja install, make install`` etc.) and optionally run tests +(``make check, ninja test`` etc.). -To add it to your repository, run this command: +Thus they can also be achieved by using the ``simple`` buildsystem and +manually specifying the commands. -.. code-block:: bash +.. note:: - git submodule add https://github.com/flathub/shared-modules.git + Using the proper buildsystem is almost always preferred rather than + manually handling the correct setup. -Then, add whichever module you want. In this example, we will use `gtk2`: +An example is provided below. .. code-block:: yaml - modules: - - shared-modules/gtk2/gtk2.json + # Using autotools without configure + - name: ffnvcodec + buildsystem: autotools + no-autogen: true + make-install-args: + - PREFIX=/app + sources: + - type: git + url: https://github.com/FFmpeg/nv-codec-headers.git + commit: 43d91706e097565f57b311e567f0219838bcc2f6 + tag: n11.1.5.3 + + # Using meson buildsystem + - name: libdrm + buildsystem: meson + builddir: true + config-opts: + - -Dtests=false + sources: + - type: git + url: https://gitlab.freedesktop.org/mesa/drm.git + tag: libdrm-2.4.124 + + # Using simple + + - name: ffnvcodec + buildsystem: simple + build-commands: + - make -j$FLATPAK_BUILDER_N_JOBS PREFIX=/app install + sources: + - type: git + url: https://github.com/FFmpeg/nv-codec-headers.git + commit: 43d91706e097565f57b311e567f0219838bcc2f6 + tag: n11.1.5.3 + + - name: libdrm + buildsystem: simple + build-commands: + - meson setup builddir --prefix=/app --libdir=/app/lib -Dtests=false + - ninja -C builddir install + sources: + - type: git + url: https://gitlab.freedesktop.org/mesa/drm.git + tag: libdrm-2.4.124 -To update the submodule, run this command: - -.. code-block:: bash - - git submodule update --remote --merge - -To remove the submodule, run these commands: +Shared Modules +`````````````` -.. code-block:: bash +Flathub contains a `shared modules `_ +repository containing build manifests for commonly used modules. These +are usally shared by apps on Flathub and maintained in a single place. +The repository is intended to be used as a git submodule. - git submodule deinit -f -- shared-modules - rm -rf .git/modules/shared-modules - git rm -f shared-modules - rm .gitmodules +Please see the `readme `_ +for details on how to use this. Flatpak Builder Tools ````````````````````` @@ -235,7 +348,5 @@ Flatpak Builder Tools Example manifests ----------------- -A `complete manifest for GNOME Dictionary built from Git -`_. -It is also possible to browse `all the manifests hosted by Flathub -`_. +Flathub hosts a large collection of applications and the respective +manifests can be browsed and searched via `GitHub `_.