Merge branch 'permissions' into 'master'

Start a guide to sandbox permissions

Closes #73

See merge request Librem5/developer.puri.sm!209

Apps/GNOME/Gtk+.rst

@@ -44,7 +44,7 @@ Adaptive Labels
 
 A GtkLabel_ can prevent your application's UI from reaching really small sizes, but there are simple tricks to make them do so. Consider using one of the following tricks on each of your labels!
 
-Allowing your label to ellipsize will cut a part of your string when there isn't enough space for it, you can enable it and choose which part will be cut with the `GtkLabel ellipize property`_. Use it if you really need your label to be on a single line.
+Allowing your label to ellipsize will cut a part of your string when there isn't enough space for it, you can enable it and choose which part will be cut with the `GtkLabel ellipsize property`_. Use it if you really need your label to be on a single line.
 
 .. note:: If you allow your label to be ellipsized, make sure that its `xalign property <GtkLabel xalign property_>`_ matches its justification or your label may not be properly aligned when ellipsized: 0 for left, 1 for right, or 0.5 for center.
 

Apps/GNOME/Settings.rst

+.. _gnome_settings:
+
+Settings, User Data and Files
+=============================
+
+Applications access three kinds of information from the user's account: settings, user data and files. These hold three different kinds of information.
+
+Settings
+--------
+
+Settings hold information about the way the user has configured an application, such as the font size, window size or theme. This information is typically about the application itself or metadata that describes data produced by the application.
+
+GNOME applications access their settings using the GSettings_ class. This stores data in a suitable directory in the user's home directory. Applications distributed as flatpaks require permissions to be granted in order to access the user's settings. See the :ref:`flatpak_app_permissions_guide` guide for details.
+
+.. _gnome_settings_user_data:
+
+User Data
+---------
+
+Some applications prefer to store data that the user has created or imported in a special data directory set aside for the application.
+
+Simple data can be accessed using keyfiles that record pieces of information as key-value pairs. Access to a suitable data directory is obtained using the `GLib.get_user_data_dir() <g_get_user_data_dir_>`_ function. The GKeyFile_ class is used to read and write keyfiles stored in a subdirectory of the data directory.
+
+.. Include a snippet of this from the treasure example
+
+More complex and larger data is also included in the user data directories by applications where it does not necessarily make sense for the user to decide where their data should be stored. These applications function like appliances, hiding the details of data storage, or using different ways to refer to user data than applications using the traditional *Open*, *Load* and *Save* actions.
+
+Applications distributed as flatpaks do not need to request permissions in order to access user data stored in a data directory that has been set aside for that purpose.
+
+Files
+-----
+
+Traditional applications can load and save files from arbitrary directories as long as the user has permission to access them. For types of files that can be opened by many different applications, such as music and video files, it is common to find that directories have been set aside for these files in the user's home directory. The `XDG Base Directory Specification`_ describes how these directories are organized.
+
+Some applications rely on finding data files in these standard locations, though they may also allow the user to select files from elsewhere, like traditional applications. These obtain the directory to access via the ``GLib.get_user_special_dir`` function, passing one of the ``Glib.UserDirectory`` values given in the table below.
+
+=========================== ====================================================
+**Directory**               **Contents**
+=========================== ====================================================
+``DIRECTORY_DOCUMENTS``     Documents, such as text or word processing files
+``DIRECTORY_DOWNLOAD``      Files downloaded by applications
+``DIRECTORY_MUSIC``         Music files
+``DIRECTORY_PICTURES``      Pictures and photographs
+``DIRECTORY_VIDEOS``        Movies and videos
+=========================== ====================================================
+
+The photographs and videos taken by the camera are stored in the directories represented by ``DIRECTORY_PICTURES`` and ``DIRECTORY_VIDEOS`` respectively.
+
+A more complete list of directories that can be accessed is provided in the `XDG Base Directory Specification`_ document.
+
+.. Provide an example showing how to obtain the directory.
+
+An application distributed as a flatpak needs to declare permissions in the ``finish-args`` entry of its manifest to be able to access these directories. The following table shows which permission corresponds to each directory, as described by the table above.
+
+=================================== =======================
+**Directory**                       **Flatpak Permission**
+=================================== =======================
+``DIRECTORY_DOCUMENTS``             ``--xdg-documents``
+``DIRECTORY_DOWNLOAD``              ``--xdg-download``
+``DIRECTORY_MUSIC``                 ``--xdg-music``
+``DIRECTORY_PICTURES``              ``--xdg-pictures``
+``DIRECTORY_VIDEOS``                ``--xdg-videos``
+=================================== =======================
+
+See the :ref:`flatpak_app_permissions_guide` for a more complete description of permissions, and consult the `Sandbox Permissions`_ section of the Flatpak documentation for a more extensive list of permissions.
+
+.. include:: /links.txt

Apps/Gnome.rst

@@ -18,12 +18,14 @@ a typical GNOME development environment. The following sections cover use of
 these tools in more detail.
 
 .. toctree::
+   :maxdepth: 1
 
    GNOME/Flatpak_setup
    GNOME/GBuilder
    GNOME/Gtk+
    GNOME/Glade
    GNOME/Application_Resources
+   GNOME/Settings
    GNOME/Resources
 
 .. include:: /links.txt

Apps/Guides/Permissions/_files/example.json

+{
+    "app-id": "com.example.some_example",
+    "runtime": "org.gnome.Platform",
+    "runtime-version": "3.32",
+    "sdk": "org.gnome.Sdk",
+    "command": "my-program",
+    "finish-args": [
+        "--socket=wayland",
+        "--filesystem=~/.config/dconf:ro",
+        "--talk-name=ca.desrt.dconf",
+        "--env=DCONF_USER_CONFIG_DIR=.config/dconf"
+    ],

Apps/Guides/Permissions/index.rst

+.. _flatpak_app_permissions_guide:
+
+Application Permissions
+=======================
+
+.. |br| raw:: html
+
+   <br />
+
+When an application is distributed as a flatpak it needs permission to access
+certain features on the phone, such as using the network, or reading and
+writing the user's files. This is done by requesting permissions in the Flatpak
+manifest file.
+
+The permissions required by an application are included in the ``finish-args``
+entry of its manifest. The following example shows the first part of a manifest
+for an application that uses the display and maintains user-specific settings:
+
+.. literalinclude:: _files/example.json
+   :language: json
+
+Some tasks can be performed without the need to request permissions. For
+example, each application can store and retrieve user data in its own private
+area. This mechanism for storing persistent data is described in the section
+about :ref:`gnome_settings_user_data`.
+
+Permissions for Common Features
+-------------------------------
+
+The table below shows the permissions that correspond to some common features
+used by applications.
+
+======================================= ================================================
+Feature                                 Flatpak Permissions
+======================================= ================================================
+Display a graphical user interface      ``--socket=wayland``
+Access the Internet using sockets       ``--share=network``
+Access settings (GNOME applications)    ``--filesystem=~/.config/dconf:ro`` |br|
+                                        ``--talk-name=ca.desrt.dconf`` |br|
+                                        ``--env=DCONF_USER_CONFIG_DIR=.config/dconf``
+Access Bluetooth devices                ``--allow=bluetooth``
+Read and write user's documents         ``--xdg-documents``
+Read and write user's downloads         ``--xdg-download``
+Read and write user's music             ``--xdg-music``
+Read and write user's pictures          ``--xdg-pictures``
+Read and write user's videos            ``--xdg-videos``
+======================================= ================================================
+
+A more detailed description of permissions is given in the `Sandbox Permissions`_
+section of the Flatpak documentation, which also contains a more extensive list.
+
+.. include:: /links.txt

Apps/Guides/index.rst

@@ -11,6 +11,7 @@ to encounter. We aim to add more guides to this collection over time.
    :maxdepth: 1
 
    Design/index
+   Permissions/index
    Porting_GNOME_Applications/index
    Simple_Input_Output/index
 

links.txt

@@ -12,29 +12,40 @@
 .. _`Flatpak Building Introduction`: http://docs.flatpak.org/en/latest/building-introduction.html
 .. _`Flatpak debugging documentation`: http://docs.flatpak.org/en/latest/debugging.html
 .. _`Flatpak documentation`: http://docs.flatpak.org/en/latest/
+.. _`Freedesktop quick reference`: http://docs.flatpak.org/en/latest/freedesktop-quick-reference.html
 .. _`Gio.GApplication documentation`: https://developer.gnome.org/gio/stable/GApplication.html#g-application-id-is-valid
 .. _`git-buildpackage`: http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.html
+.. _`GKeyFile`: https://developer.gnome.org/glib/stable/glib-Key-value-file-parser.html
 .. _`Glade`: https://glade.gnome.org/
 .. _`Glade Tutorials`: https://wiki.gnome.org/action/show/Apps/Glade/Tutorials
 .. _`glib-compile-resources`: https://developer.gnome.org/gio/stable/glib-compile-resources.html
+.. _`g_get_user_data_dir`: https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-get-user-data-dir
+.. _`GMenu`: https://developer.gnome.org/gio/2.60/GMenu.html
 .. _`GNOME API Reference`: https://developer.gnome.org/references
 .. _`GNOME Builder`: https://wiki.gnome.org/Apps/Builder
 .. _`GNOME Builder documentation`: https://builder.readthedocs.io/en/latest/
 .. _`GNOME git client`: https://wiki.gnome.org/Apps/Gitg
 .. _`GNOME`: https://www.gnome.org
+.. _`GNOME Human Interface Guidelines`: https://developer.gnome.org/hig/stable/
 .. _`The GNU Privacy Handbook`: https://gnupg.org/gph/en/manual.html
 .. _`GResource`: https://developer.gnome.org/gio/stable/GResource.html
+.. _`GSettings`: https://developer.gnome.org/gio/stable/GSettings.html
+.. _`GSimpleAction`: https://developer.gnome.org/gio/2.60/GSimpleAction.html
 .. _`GTK+ 3 documentation`: https://developer.gnome.org/gtk3/stable/
+.. _`GtkApplicationWindow`: https://developer.gnome.org/gtk3/stable/GtkApplicationWindow.html
+.. _GtkButton : https://developer.gnome.org/gtk3/stable/GtkButton.html
 .. _GtkHeaderBar : https://developer.gnome.org/gtk3/stable/GtkHeaderBar.html
 .. _`GTK+ Inspector`: https://wiki.gnome.org/Projects/GTK+/Inspector
-.. _GtkLabel ellipize property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--ellipsize
+.. _GtkLabel ellipsize property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--ellipsize
 .. _GtkLabel : https://developer.gnome.org/gtk3/stable/GtkLabel.html
 .. _GtkLabel wrap-mode property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--wrap-mode
 .. _GtkLabel wrap property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--wrap
 .. _GtkLabel xalign property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--xalign
+.. _GtkMenuButton: https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkMenuButton
 .. _GtkSeparator : https://developer.gnome.org/gtk3/stable/GtkSeparator.html
 .. _GtkScrolledWindow : https://developer.gnome.org/gtk3/stable/GtkScrolledWindow.html
 .. _GtkSizeGroup : https://developer.gnome.org/gtk3/stable/GtkSizeGroup.html
+.. _GtkToolButton : https://developer.gnome.org/gtk3/stable/GtkToolButton.html
 .. _`GTK+ toolkit`: https://www.gtk.org
 .. _`GTK+ website`: https://www.gtk.org/
 .. _HdyHeaderGroup : https://honk.sigxcpu.org/projects/libhandy/doc/HdyHeaderGroup.html
@@ -70,7 +81,9 @@
 .. _`Qt Quick`: https://doc.qt.io/qt-5/qtquick-index.html
 .. _`Qt Quick Controls 2`: https://doc.qt.io/qt-5/qtquickcontrols2-index.html
 .. _`Running GTK+ Applications`: https://developer.gnome.org/gtk3/stable/gtk-running.html
+.. _`Sandbox Permissions`: http://docs.flatpak.org/en/latest/sandbox-permissions-reference.html
 .. _`Scalable Vector Graphics`: https://www.w3.org/TR/SVG/
+.. _`XDG Base Directory Specification`: http://www.freedesktop.org/Standards/basedir-spec
 
 .. _`FH34SRJ-6S-0.5SH(50) (Touch)`: https://www.hirose.com/product/download/?distributor=digikey&type=2d&lang=en&num=FH34SRJ-6S-0.5SH(50)
 .. _`74LVC2G241DC,125`: https://assets.nexperia.com/documents/data-sheet/74LVC2G241.pdf

setup.cfg

@@ -7,3 +7,6 @@
 #         from gi.repository import GLib, Gtk
 ignore=E402,E501,W504
 exclude=conf.py,_themes/,_extensions/,_build/
+builtins=
+    _,
+    ngettext