Merge branch '120-describe-how-apps-are-installed-and-updated' into 'master'

Resolve "Describe how apps are installed and updated"

Closes #120

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

Apps/Packaging_Apps/Building_Debian_Packages/index.rst

@@ -3,6 +3,15 @@
 Building Debian Packages
 ========================
 
-For building a deb package, `git-buildpackage`_ is the preferred build method.
+Debian (deb) packages are the standard way to distribute software in
+Debian-based distributions like PureOS. Packages provided in deb format files
+are managed using a suite of command line tools and are also supported by
+various graphical package managers.
+
+The `git-buildpackage`_ tool is the suggested way to build a deb package for
+core application developers who are not specifically targeting Debian or PureOS
+systems, or who are supporting a wider range of platforms. This tool provides a
+way to integrate deb package building with normal development practices if the
+`Git revision control system`_ is used for revision control.
 
 .. include:: /links.txt

Apps/Packaging_Apps/Building_Flatpaks/index.rst

@@ -10,7 +10,7 @@ Flatpak, building applications for testing on the development workstation, and
 cross-building applications for deployment on the Librem 5.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    Concepts
    Building
@@ -18,3 +18,6 @@ cross-building applications for deployment on the Librem 5.
    Debugging
    Translations
    Signing
+
+General management and installation of flatpaks is described in the
+:ref:`package_management` chapter of the documentation.

Apps/Packaging_Apps/index.rst

@@ -3,10 +3,14 @@
 Packaging Applications
 ======================
 
-Applications on the Librem 5 are supplied in two kinds of package: Debian
-packages that are provided as part of the `PureOS`_ operating system running on
-the phone, and flatpaks that have been created using the Flatpak suite of tools
-that contain third party applications.
+Applications on the Librem 5 are supplied in two different package formats:
+
+#. Debian packages are provided as part of the `PureOS`_ operating system
+   running on the phone. Core applications are provided in this format.
+#. Flatpaks are created using the Flatpak suite of tools. Third party
+   applications are provided in this format.
+
+The following sections describe how to create packages in each format.
 
 .. toctree::
    :maxdepth: 1
@@ -14,11 +18,6 @@ that contain third party applications.
    Building_Debian_Packages/index
    Building_Flatpaks/index
 
-Notes:
-
-  * :ref:`flatpak_setup_gnome` will show you how to setup flatpak on the dev board
-  * Deb packages are the official package formats for Debian-based
-    distributions. A deb package is installable from the apt package manager
-    and what is needed for the app to be distributed by Debian.
+Package management is described in the :ref:`package_management` chapter of the documentation.
 
 .. include:: /links.txt

Package_Management/Graphical_Tools/index.rst

+.. _package_management_graphical_tools:
+
+Graphical Tools
+===============
+
+Most users will prefer to use graphical applications and tools to manage the software on their phone. This page describes the default application for doing this as well as any alternatives.
+
+Users and software developers may prefer to use other tools that they are more comfortable with, or those that give them more control over package management on their phone. The later sections in this chapter cover installation, uninstallation, updating and upgrading of packages from a command line user's perspective.
+
+GNOME Software
+--------------
+
+Although there are two different types of package format used on the Librem 5, packaged software can be installed using the `GNOME Software`_ application, which provides an easy-to-use graphical interface for searching, installing and
+uninstalling packages.
+
+.. note:: This section will be expanded later to cover some common tasks, as well as describing some alternative tools for managing packages.

Package_Management/Managing_Debian_Packages.rst

+.. _package_management_debian:
+
+Managing Debian Packages
+========================
+
+Management of Debian packages can be performed using :ref:`graphical applications <package_management_graphical_tools>` or command line tools. This document describes how to perform common package management tasks using command line tools.
+
+.. contents::
+
+Note that management of flatpaks is discussed in the :ref:`package_management_flatpaks` section.
+
+Getting Started
+---------------
+
+Log in to the phone via a :ref:`serial console <imx8_devkit_booting>` or :ref:`network connection <devkit_ethernet_usb>`. You should now be able to issue commands at the shell prompt. In this document we prefix each of the commands with the shell prompt to indicate that they are entered at the command line on the phone::
+
+   purism@pureos:~$
+
+Next, ensure that the phone has access to the Internet.
+
+Tools
+-----
+
+The most useful tool for managing Debian packages is the ``apt`` tool. This is used to search for packages in remote repositories, request installation of packages and uninstall them when they are no longer needed.
+
+Another useful tool is ``dpkg``. This is useful for installing individual package files, removing packages, and showing a list of the currently installed packages.
+
+Both of these tools are already installed on the phone.
+
+Listing Packages
+----------------
+
+To see the list of Debian packages that are installed on your system, enter the following at the command line:
+
+.. code:: bash
+
+   purism@pureos:~$ dpkg -l
+
+This should cause a summary to be shown of the packages that the system knows about, as in the following snippet::
+
+   Desired=Unknown/Install/Remove/Purge/Hold
+   | Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend
+   |/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
+   ||/ Name                                           Version                                        Architecture Description
+   +++-==============================================-==============================================-============-=================================================
+   ii  accountsservice                                0.6.45-2                                       arm64        query and manipulate user account information
+   ii  acl                                            2.2.53-4                                       arm64        access control list - utilities
+   ii  adduser                                        3.118                                          all          add and remove users and groups
+   ii  adwaita-icon-theme                             3.30.1-1                                       all          default icon theme of GNOME
+
+Packages that have been correctly installed are prefixed with ``ii`` in the leftmost column.
+
+You may need to press the ``q`` key to quit the summary.
+
+Updating the Package Database
+-----------------------------
+
+The ``apt`` tool maintains a database of the Debian packages that are installed on the system. It uses this information to determine whether packages need to be upgraded.
+
+At the command line, enter the following:
+
+.. code:: bash
+
+   purism@pureos:~$ sudo apt update
+
+This should result in a series of communications to remote servers that produce output like the following::
+
+   Hit:1 http://deb.debian.org/debian buster InRelease
+   Hit:2 http://deb.debian.org/debian buster-updates InRelease
+   Hit:3 http://security.debian.org/debian-security buster/updates InRelease
+   Hit:4 http://ci.puri.sm scratch InRelease
+   Reading package lists... Done
+   Building dependency tree
+   Reading state information... Done
+   18 packages can be upgraded. Run 'apt list --upgradable' to see them.
+
+.. note:: The exact host names of the servers will change when the system software is finalized.
+
+As suggested by the ``apt`` tool, we can run a command to see which packages can be upgraded:
+
+.. code:: bash
+
+   purism@pureos:~$ apt list --upgradable
+
+Note that this command does not require ``sudo`` to be used to run it because it only reads information about the packages on the system. It does not need to modify that information.
+
+Upgrading Packages
+------------------
+
+Packages that are upgradable can be upgraded with this command, again using ``sudo`` because permission is needed to modify the database and install files on the system:
+
+.. code:: bash
+
+   purism@pureos:~$ sudo apt upgrade
+
+This should cause a few lines of information about the upgrades to be shown, the amount of data that will be fetched over the network, and the amount of storage required, followed by a question::
+
+   Do you want to continue? [Y/n]
+
+Press ``y`` to confirm. Otherwise, press ``n``.
+
+Searching for Software
+----------------------
+
+Applications and other components can be obtained from the remote repositories that are known to the system. The ``apt`` tool is used to search for items of software by their names. For example, the GNU ``hello`` program can be searched for with the following command:
+
+.. code:: bash
+
+   purism@pureos:~$ apt search hello
+
+This will produce a number of suggestions for suitable packages. Amongst these is the relevant package::
+
+   hello/stable 2.10-2 arm64
+     example package based on GNU hello
+
+The name of the package is on the left of the forward slash.
+
+Installing Packages
+-------------------
+
+To install a package, simply run the ``apt`` tool in the following way -- in this case to install the GNU ``hello`` program:
+
+.. code:: bash
+
+   purism@pureos:~$ sudo apt install hello
+
+If this is successful, the output produced should indicate that the package containing the program was downloaded, unpacked and installed.
+
+Uninstalling Packages
+---------------------
+
+When a piece of software is no longer needed, its package can be uninstalled using the ``apt`` tool, as in this example:
+
+.. code:: bash
+
+   purism@pureos:~$ sudo apt remove hello
+
+If the ``-y`` option is passed, the package will be removed automatically. Otherwise, you will be asked to confirm that you want to continue with the operation.
+
+Removing Extra Packages
+-----------------------
+
+When uninstalling a package, you may be notified about other packages that are installed but not required. Run the ``apt`` tool to clean up these extra packages:
+
+.. code:: bash
+
+   purism@pureos:~$ sudo apt autoremove
+
+You will be asked to confirm that you want to remove the extra packages unless you pass the ``-y`` option.
+
+Adding and Removing Repositories
+--------------------------------
+
+By default, you will only be able to install software from the repositories that are provided in the standard configuration for the phone. However, you can change the list of package sources (package repositories) using the ``apt`` tool:
+
+.. code:: bash
+
+   purism@pureos:~$ sudo apt edit-sources
+
+This may ask you to choose a text editor before opening the file containing the package sources for you to edit. Refer to the `Debian Administrator's Handbook`_ for guidance on how to customize this file.
+
+.. _`Debian Administrator's Handbook`: https://www.debian.org/doc/manuals/debian-handbook/apt.en.html#sect.apt-sources.list

Package_Management/Managing_Flatpaks.rst

+.. _package_management_flatpaks:
+
+Managing Flatpaks
+=================
+
+Management of flatpaks can be performed using :ref:`graphical applications <package_management_graphical_tools>` or command line tools. This document describes how to perform common package management tasks using command line tools.
+
+.. contents::
+
+Note that management of Debian packages is discussed in the :ref:`package_management_debian` section.
+
+Getting Started
+---------------
+
+It may be useful to review the :ref:`building_flatpaks_concepts` section before continuing.
+
+Log in to the phone via a :ref:`serial console <imx8_devkit_booting>` or :ref:`network connection <devkit_ethernet_usb>`. You should now be able to issue commands at the shell prompt. In this document we prefix each of the commands with the shell prompt to indicate that they are entered at the command line on the phone::
+
+   purism@pureos:~$
+
+Next, ensure that the phone has access to the Internet.
+
+Tools
+-----
+
+The most useful tool for managing Debian packages is the ``flatpak`` tool. This is used to search for packages in remote repositories, request installation of packages and uninstall them when they are no longer needed.
+
+The ``flatpak`` tool is already installed on the phone.
+
+Listing Packages
+----------------
+
+To see the list of flatpaks that are installed on your system, enter the following at the command line:
+
+.. code:: bash
+
+   purism@pureos:~$ flatpak list
+
+This should cause a summary to be shown of the packages that the system knows about, as in the following snippet::
+
+   Description                                                                 Application                Version Branch Arch    Origin                Installation
+   Play Sounds                                                                 com.example.play_sounds            master aarch64 play_sounds-origin    user
+   Read Buttons                                                                com.example.read_buttons           master aarch64 read_buttons-origin   user
+   Simple Weather                                                              com.example.simple_weather         master aarch64 simple_weather-origin user
+   GNOME Application Platform version 3.32 - Shared libraries used by GNOME a… org.gnome.Platform                 3.32   aarch64 flathub               user
+   GNOME Software Development Kit version 3.32 - Tools and headers for develo… org.gnome.Sdk                      3.32   aarch64 flathub               user
+
+The ``Application`` column contains the identifiers that are used to refer to applications when using the command line ``flatpak`` tool.
+
+Updating Packages
+-----------------
+
+Packages can be updated to the latest version either individually or as a complete upgrade of all flatpaks.
+
+To update a single flatpak, such as the :ref:`examples_Simple_Weather` example, enter the following, using the ``Application`` identifier given in the list of installed packages:
+
+.. code:: bash
+
+   purism@pureos:~$ flatpak update com.example.simple_weather
+
+To update all flatpaks, enter the following:
+
+.. code:: bash
+
+   purism@pureos:~$ flatpak update
+
+This should result in output beginning with text like the following::
+
+   Looking for updates…
+
+If there are updates available, you will be asked if you want to proceed with their installation. Otherwise, this message will be shown::
+
+   Nothing to do.
+
+This indicates that the installed software is up-to-date.
+
+Searching for Software
+----------------------
+
+Applications and other components can be obtained from the remote repositories that are known to the system. For example, the GNOME Weather program can be searched for with the following command:
+
+.. code:: bash
+
+   purism@pureos:~$ flatpak search weather
+
+This will produce a number of suggestions for suitable packages. Amongst these is the relevant package::
+
+   Description                                                                                             Application                   Version   Branch  Remotes
+   Weather - Show weather conditions and forecast                                                          org.gnome.Weather             3.32.2    stable  flathub
+
+The name of the package is in the ``Application`` column.
+
+Installing Packages
+-------------------
+
+To install a package, simply run the ``flatpak`` tool in the following way -- in this case to install the GNOME Weather application, using the name obtained above:
+
+.. code:: bash
+
+   purism@pureos:~$ flatpak install org.gnome.weather
+
+If this is successful, the output produced should indicate that the package containing the program was downloaded, unpacked and installed.
+
+Uninstalling Packages
+---------------------
+
+When a piece of software is no longer needed, its package can be uninstalled as in this example, using the same ``Application`` name as before:
+
+.. code:: bash
+
+   purism@pureos:~$ flatpak uninstall org.gnome.weather
+
+Uninstalling applications you no longer need will reduce the amount of data you need to download when updates for those applications become available.
+
+Adding and Removing Repositories
+--------------------------------
+
+By default, you will only be able to install software from the repositories that are provided in the standard configuration for the phone. However, you can change the list of remote repositories (remotes) using the ``flatpak`` tool's collection of commands for managing them.
+
+To list the remotes known to the system, enter the following:
+
+.. code:: bash
+
+   purism@pureos:~$ flatpak remotes
+
+Add a remote in the following way -- in this case, adding the `Nightly GNOME Apps`_ remote to the list of known remotes:
+
+.. code:: bash
+
+   flatpak remote-add --if-not-exists gnome-nightly https://sdk.gnome.org/gnome-nightly.flatpakrepo
+
+Remove a remote with the corresponding command:
+
+.. code:: bash
+
+   flatpak remote-delete gnome-nightly
+
+It can be useful to remove repositories that provide old versions or duplicates of software. This will make searching for packages quicker.
+
+.. include:: /links.txt

Package_Management/Package_Formats.rst

+.. _package_management_formats:
+
+Package Formats
+===============
+
+Applications on the Librem 5 are supplied in two different package formats:
+
+#. Debian packages are provided as part of the `PureOS`_ operating system
+   running on the phone. Core applications are provided in this format.
+#. Flatpaks are created using the Flatpak suite of tools. Third party
+   applications are provided in this format.
+
+This document describes the differences between these formats and the reasoning behind the use of two types of package on the phone.
+
+Debian Packages
+---------------
+
+System packages for PureOS, the operating system on the phone, are provided in the same format used by `Debian`_ because PureOS is itself based on Debian. The `Debian binary package format`_ used in deb package files describes an archive containing both packaging metadata and files that to be installed on a user's system.
+
+Because these packages can contain files that will be installed in critical locations on the system, only core applications and components are delivered in this format.
+
+Flatpaks
+--------
+
+Third party applications for the Librem 5 are supplied as flatpaks that are unpacked and run inside sandboxes, with access to the user's environment restricted to well-defined services.
+
+As a result, this format is more suitable for third party applications, since the user is not forced to trust the application with access to the entire system.
+
+Command Line Tools
+------------------
+
+Each package format has its own set of tools for installing packages at the command line, and this can be useful when installing many applications at once or installing dependencies for applications you are developing yourself.
+
+Both kinds of packages may be obtained from official Purism repositories as well as third party repositories, and the tools for managing these are different for each package format.
+
+.. include:: /links.txt

Package_Management/index.rst

+.. index:: Package Management
+
+.. _package_management:
+
+Package Management
+==================
+
+This chapter covers the use of packages on the Librem 5 phone. Packages are 
+used to deliver applications and other components to the user's system. When new features or bug fixes are made to these components, new packages are made available. The user can install new software and remove existing software from their phone.
+
+.. toctree::
+   :maxdepth: 1
+
+   Graphical_Tools/index
+   Package_Formats
+   Managing_Debian_Packages
+   Managing_Flatpaks
+
+Because this chapter is part of the developer documentation, it will focus on the use of command line tools instead of describing how to use a GUI application to manage packages. A brief summary of the graphical options for package management is given in the next section.
+
+..   Creating_New_Packages
+..   Publishing_Packages
+
+.. include:: /links.txt

index.rst

@@ -18,7 +18,8 @@ examples to help you accomplish your goals with the Librem 5 dev kit and phone.
 
    Introduction
    Development_Environment
-   Apps/index.rst
+   Apps/index
+   Package_Management/index
    APIs
    Contact
    FAQ

links.txt

@@ -10,6 +10,7 @@
 .. _`Debian Package Builds for the Librem 5`: https://arm01.puri.sm/job/debs/
 .. _`Debian package submission procedures`: https://www.debian.org/doc/manuals/distribute-deb/distribute-deb.html#adding-packages-to-debian
 .. _`deb-build-jobs`: https://source.puri.sm/Librem5/deb-build-jobs
+.. _`Debian binary package format`: https://manpages.debian.org/buster/dpkg-dev/deb.5.en.html
 .. _`Desktop Entry`: https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html
 .. _`developer.puri.sm issues`: https://source.puri.sm/Librem5/developer.puri.sm/issues
 .. _`EmCraft i.MX 8M SoM`: https://www.emcraft.com/products/868
@@ -24,6 +25,7 @@
 .. _`get in touch`: https://developer.puri.sm/Librem5/Contact.html
 .. _`Gio.GApplication documentation`: https://developer.gnome.org/gio/stable/GApplication.html#g-application-id-is-valid
 .. _`Gio.Menu`: https://lazka.github.io/pgi-docs/#Gio-2.0/classes/Menu.html
+.. _`Git revision control system`: https://git-scm.com/
 .. _`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/
@@ -43,6 +45,7 @@
 .. _`GNOME git client`: https://wiki.gnome.org/Apps/Gitg
 .. _`GNOME`: https://www.gnome.org
 .. _`GNOME Human Interface Guidelines`: https://developer.gnome.org/hig/stable/
+.. _`GNOME Software`: https://wiki.gnome.org/Apps/Software
 .. _`GNU gettext utilities`: https://www.gnu.org/software/gettext/manual/gettext.html
 .. _`The GNU Privacy Handbook`: https://gnupg.org/gph/en/manual.html
 .. _`GResource`: https://developer.gnome.org/gio/stable/GResource.html