Commit 9b5de481 authored by David Boddie's avatar David Boddie

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
parents 6c8c65e7 0c1e4486
......@@ -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
......@@ -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.
......@@ -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:
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_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_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_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
.. 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
......@@ -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
......
......@@ -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
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment