Add some debugging and manifest docs

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 <application-id>
 
@@ -190,3 +190,9 @@ and the corresponding ``--talk-name`` or ``--own-name`` permissions
 required::
 
   flatpak --log-session-bus run <application-id>| 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 <application-id>

docs/manifests.rst

@@ -143,22 +143,95 @@
 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
@@ -184,48 +257,88 @@
 
 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 <https://mesonbuild.com/>`_
 - `qmake <https://doc.qt.io/qt-5/qmake-overview.html>`_
-- the "`Build API <https://github.com/cgwalters/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) <https://github.com/flathub/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 <https://github.com/flathub/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 <https://github.com/flathub/shared-modules/blob/master/README.md>`_
+for details on how to use this.
 
 Flatpak Builder Tools
 `````````````````````
@@ -235,7 +348,5 @@
 Example manifests
 -----------------
 
-A `complete manifest for GNOME Dictionary built from Git
-<https://github.com/flathub/org.gnome.Dictionary/blob/master/org.gnome.Dictionary.yml>`_.
-It is also possible to browse `all the manifests hosted by Flathub
-<https://github.com/flathub>`_.
+Flathub hosts a large collection of applications and the respective
+manifests can be browsed and searched via `GitHub <https://github.com/flathub>`_.