.. include:: defs.txt
.. include:: images.txt

.. _librem_5_software:

Installing and Updating Applications
====================================

.. image:: images/software/sm.puri.Store.svg
   :width: 128
   :align: right
   :alt: The PureOS Store application icon

The **PureOS Store** application provides an easy-to-use graphical interface for searching, installing and uninstalling applications and other software packages. It can also be used to manage and show information about system updates.

.. contents::
   :local:

Locate the icon shown above in the app drawer and press it to launch the application.

Getting Started
---------------

When you run the **PureOS Store** application, it shows a page like the one shown below, with **Editor's Picks** and **Recent Releases** above a list of **Categories**.

.. |software-highlights| image:: images/software/software-highlights.png
   :scale: 50%
   :alt: The PureOS Store start page, showing highlighted applications

.. |software-categories| image:: images/software/software-categories.png
   :scale: 50%
   :alt: The PureOS Store start page, providing access to application categories

.. centered:: |software-highlights| |software-categories|

The header bar contains a search button that can be used to :ref:`search for applications <librem_5_software_searching>` and a |menu| (menu) button that allows you to :ref:`add new software sources <librem_5_software_sources>`.

At the bottom of the screen, you can choose between three modes:

.. image:: images/software/software-modes.png
   :align: center
   :alt: The three modes that can be selected

These modes are used to perform different tasks:

 1. **Explore** allows you to browse all the applications, including those you have installed and those that are available to download.
 2. **Installed** shows only the :ref:`applications that have been installed <librem_5_software_installed>`, either as system defaults or by you.
 3. **Updates** shows the applications and other components that require updating, and allows you to :ref:`update them individually or as a whole <librem_5_software_updating>`

The following sections describe how to perform some common package management tasks.

.. _librem_5_software_installed:

Showing Installed Applications
------------------------------

Select the tab for the **Installed** mode at the bottom of the screen. The installed software page shows the applications and components that have been installed on the phone.

.. image:: images/software/software-installed.png
   :align: center
   :scale: 50%
   :alt: A list of installed applications

Applications can be uninstalled directly from this page. Press the |delete| (delete) button to the right of the application's name and icon. This is described in the :ref:`librem_5_software_uninstalling` section.

You can view more information about each of the installed applications by tapping its icon in the list.

.. image:: images/software/software-app-details.png
   :align: center
   :scale: 50%
   :alt: Showing the details of an application

Press the back button at the top-left of the screen to return to the list of installed applications.

.. _librem_5_software_searching:

Searching for Applications
--------------------------

On the main **PureOS Store** page, shown when the **Explore** tab is selected, you can find a search button at the top-left of the screen. Pressing this button causes a search bar to appear. The on-screen keyboard should also appear, allowing you to enter keywords.

.. image:: images/software/software-search-start.png
   :align: center
   :scale: 50%
   :alt: Opening the search bar

Enter the search terms for the application you are looking for. The page will update to show appropriate matches as you enter text, finding applications based on their metadata.

.. image:: images/software/software-search-results.png
   :align: center
   :scale: 50%
   :alt: Searching for an application

Once you have found a suitable application, select it in the list of search results to show more information about it. You can always return to the search results by pressing the back button at the top-left of the screen.

Installing an Application
-------------------------

Once you have found an application you want to install, you can review the description, software license and other details on its information page.

.. image:: images/software/software-install-app.png
   :align: center
   :scale: 50%
   :alt: Viewing an application's information

You may then choose to install the application by pressing the **Install** button, or press the back button at the top-left of the screen to return to the search results.

When you decide to install the application, progress on the installation process is reported above the description of the application.

.. image:: images/software/software-installing-app.png
   :align: center
   :alt: Installing an application

When the application has finished installing, you can launch it immediately by pressing the **Launch** button. If you changed your mind, you can also remove it by pressing the **Remove** button. You will be asked for confirmation before the application is uninstalled.

.. image:: images/software/software-installed-app.png
   :align: center
   :alt: Ready to launch an installed application

Installed applications are available in the app drawer, so you do not need to use the **PureOS Store** application to launch them.

.. _librem_5_software_uninstalling:

Uninstalling an Application
---------------------------

Applications can be uninstalled from the **Installed** tab by pressing the |delete| (delete) button to the right of the application's name and icon. You will be asked to confirm that you wish to uninstall the application.

.. image:: images/software/software-remove-app.png
   :align: center
   :scale: 50%
   :alt: Uninstalling an application

Press **Remove** to confirm that you want to uninstall the application, or press **Cancel** to keep it.

.. _librem_5_software_updating:

Updating Applications
---------------------

It is a good idea to update applications and other components regularly to ensure that you have the latest versions of them. These should contain fixes for any problems that have been reported by users and developers.

Ensure that you have enabled a network connection, either via :ref:`librem_5_wlan` or a mobile data connection. Select the **Updates** tab at the bottom of the screen to show the list of pending updates. This may show a message indicating that the system is looking for updates.

.. image:: images/software/software-updates.png
   :align: center
   :scale: 50%
   :alt: Looking for updates to applications and system software

If you do not have a network connection, you will see a message indicating this.

.. image:: images/software/software-updates-offline.png
   :align: center
   :scale: 50%
   :alt: The network is offline

Press the **Network Settings** button to configure the network connection then return to the **PureOS Store** application and continue.

If the updates have been found, you will either see a message indicating that the software is up-to-date or a list of updates.

.. |software-up-to-date| image:: images/software/software-updates-up-to-date.png
   :scale: 50%
   :alt: The installed software is up-to-date

.. |software-updates-found| image:: images/software/software-updates.png
   :scale: 50%
   :alt: The Updates tab showing the pending updates

.. centered:: |software-up-to-date| |software-updates-found|

The updates are sorted into two sections: **Requires Restart** and **Application Updates**.

Each application that requires an update can be updated individually by pressing the button on the right hand side of its name. The amount of data that will be downloaded is shown below this button.

Alternatively, you can press the **Update All** button to update all applications that require updates. *Note that this may require large amounts of data to be downloaded.*

When you update an application, the button to the right of it becomes an update indicator which shows the progress being made to download new data.

.. image:: images/software/software-updating-app.png
   :align: center
   :alt: Updating a component

The application or component will be removed from the list of updates after it has been updated.

If there is a pending operating system (OS) update that requires a system restart, there will be one or more items in the **Requires Restart** section on the page. See the :ref:`librem_5_software_updating_system` section for more information about these.

.. _librem_5_software_update_notifications:

Update Notifications
--------------------

Depending on the configuration, notifications will be shown when software updates are available. These can be viewed by opening the settings panel at the top of the screen.

.. image:: images/software/software-updates-notification.png
   :align: center
   :scale: 50%
   :alt: Notifications indicate when software updates are available

You can dismiss a notification by pressing **Not Now** or press **View** to get more information about it.

.. _librem_5_software_updating_system:

Updating the System Software
----------------------------

Software updates that require the system to restart are shown in the **Requires Restart** section of the **Updates** tab.

.. image:: images/software/software-updates.png
   :align: center
   :scale: 50%
   :alt: Software updates including one that requires a system restart

You may want to shut down applications before installing an update in this section. Press the **Download** button to download the update, ready for installation. Note that the update may be downloaded automatically but not installed depending on the update configuration -- see the :ref:`librem_5_software_configuring_updates` section for more information.

When the update is ready to install, the **Download** button will change to **Restart & Update**.

.. image:: images/software/software-updating-restart.png
   :align: center
   :scale: 50%
   :alt: Ready to install an OS update

Press the button when you are ready to restart the system and install the update. The screen will fade to black then the system will restart.

.. _librem_5_software_configuring_updates:

Configuring Updates
-------------------

You can configure how updates are handled by opening the application menu and selecting the **Update Preferences** item.

.. image:: images/software/software-update-preferences-menu.png
   :align: center
   :alt: Opening the application menu

Selecting this item opens a page that allows you to configure how updates are performed.

.. image:: images/software/software-update-preferences.png
   :align: center
   :alt: The Update Preferences page

When you have adjusted the options, press the back button to return to the previous view.

.. _librem_5_software_sources:

Adding New Software Sources
---------------------------

Packages can be downloaded from a variety of sources. To configure these, open the menu by pressing the |menu| (menu) button at the top-right of the scren.

.. image:: images/software/software-menu.png
   :align: center
   :alt: Opening the application menu

Select the **Software Repositories** item to launch a separate tool for adding, removing and configuring the remote repositories containing software that can be downloaded.
