Merge branch 'document-network-state' into 'master'

Document the network state example

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

.gitmodules

@@ -13,3 +13,6 @@
 [submodule "Apps/Tutorials/App_Resources/app"]
 	path = Apps/Tutorials/App_Resources/app
 	url = https://source.puri.sm/librem5-examples/app-resources.git
+[submodule "Apps/Examples/Networking/NetworkState/app"]
+	path = Apps/Examples/Networking/NetworkState/app
+	url = https://source.puri.sm/librem5-examples/network-state.git

Apps/Examples/Networking/NetworkState/Building_the_App.rst

+.. |executable| replace:: ``network-state``
+.. |desktop-entry-ref| replace:: desktop entry file
+
+.. include:: /Apps/Examples/common/Building_the_App.txt

Apps/Examples/Networking/NetworkState/Getting_the_App.rst

+.. |project| replace:: https://source.puri.sm/librem5-examples
+
+.. |repo| replace:: network-state.git
+
+.. |project-repo| replace:: ``https://source.puri.sm/librem5-examples/network-state.git``
+
+.. include:: /Apps/Examples/common/Getting_the_App.txt

Apps/Examples/Networking/NetworkState/Packaging_the_App.rst

+.. |manifest| replace:: ``com.example.network_state.json``
+.. |manifest-path| replace:: app/com.example.network_state.json
+.. |app-id| replace:: com.example.network_state
+
+.. include:: ../../common/Packaging_the_App.txt

Apps/Examples/Networking/NetworkState/Source_Code.rst

+.. _Network_State_example_src:
+
+Source Files
+============
+
+.. contents::
+   :local:
+
+The main source code for the application can be found in the ``main.py`` file
+within the ``src`` directory. The purpose of the other files is explained in
+other tutorials, such as the :ref:`First_Application` tutorial.
+
+The Program
+-----------
+
+Because the application is very simple, we show the whole main program here to
+provide an overview before looking at the details:
+
+.. literalinclude:: app/src/main.py
+   :language: python3
+
+Much of the is very similar to other examples and tutorials. We will focus on
+the parts that are specific to this example.
+
+Relevant Modules
+~~~~~~~~~~~~~~~~
+
+The ``Gio`` module provides classes and functions that perform a range of
+tasks, including one that allows us to read the network state. This module is
+imported in the same way as the ``Gtk`` module:
+
+.. literalinclude:: app/src/main.py
+   :language: python3
+   :start-at: import gi
+   :end-at: repository
+
+It can be helpful to specify the version of the ``Gio`` module before importing
+it, but it is not necessary in this case.
+
+Application Class
+~~~~~~~~~~~~~~~~~
+
+The ``Application`` class provides the usual methods to set up the application
+and perform tasks when it is run.
+
+In the ``do_activate`` method we set up the user interface, creating a
+``Gtk.Button`` instance and adding it to the layout of the window:
+
+.. literalinclude:: app/src/main.py
+   :language: python3
+   :start-at: do_activate
+   :end-at: show_all
+
+By connecting the ``clicked`` signal of the button to the ``update_label``
+method, the application can respond when the user clicks the button. The
+``update_label`` method receives the button itself as an argument:
+
+.. literalinclude:: app/src/main.py
+   :language: python3
+   :start-at: do_activate
+   :end-at: set_text('Other')
+
+In this method we create an instance of the ``Gio.NetworkMonitor`` class and
+call its ``get_connectivity`` method to obtain the current network state.
+We interpret the different values of ``Gio.NetworkConnectivity`` to provide
+updated text for the labels.
+
+Summary
+-------
+
+You can use the ``Gio`` module to query the network state. You can specify the
+version of the module if you require, using ``gi.require_version``, and import
+the module from the ``gi.repository`` package.
+
+To obtain the network state, create an instance of the ``Gio.NetworkMonitor``
+class and call its ``get_connectivity`` method.
+
+.. include:: /links.txt

app @ c6b47057

+Subproject commit c6b470577f8240fea7d1cec13a9c4256049eb6e9

Apps/Examples/Networking/NetworkState/index.rst

+.. _examples_Network_State:
+
+Network State
+=============
+
+This example shows how to check the network state. When run, the application
+simply shows a window containing a button and a label. When the button is
+clicked, the network state is shown in the label.
+
+.. image:: images/screenshot.png
+   :scale: 50%
+   :align: center
+   :alt: A screenshot of the application running in the phone environment
+
+We will focus on the parts of the application that are related to checking the
+network state and updating the user interface.
+
+.. toctree::
+   :maxdepth: 1
+
+   Getting_the_App
+   Source_Code
+   Building_the_App
+   Packaging_the_App
+
+.. include:: /links.txt

Apps/Examples/common/Building_the_App.txt

+Building the Application
+========================
+
+.. contents::
+   :local:
+
+The ``app`` directory and its subdirectories contain ``meson.build`` files that
+describe how the application is built. These are used by the `Meson`_ build
+tool to configure the build process.
+
+Meson is usually run so that it creates a build directory. This is where all
+the resources are put so that the `Ninja`_ build tool can perform the actual
+process of building and installing the application.
+
+Top-Level Build File
+--------------------
+
+In the ``app`` directory itself, the ``meson.build`` file begins with a
+declaration of the project name, version and build system requirements:
+
+.. literalinclude:: app/meson.build
+   :language: python3
+
+We also declare the ``data`` and ``src`` subdirectories, causing Meson to
+examine them for any ``meson.build`` files they may contain.
+
+The last line causes a special script to be run after installation. It is not
+important to know what this is doing at this point.
+
+Sources Build File
+------------------
+
+The ``meson.build`` file in the ``src`` directory describes how the source
+files are processed when the build occurs:
+
+.. literalinclude:: app/src/meson.build
+   :language: python3
+
+In this case, we instruct Meson to take the ``main.py`` file in the ``src``
+directory and copy it into the build directory as |executable| --
+this is the name given as the executable in the |desktop-entry-ref|.
+
+We also declare that the file should be installed, and that its installation
+directory is the system location for executables (``bindir``).
+
+Data Build File
+---------------
+
+The ``meson.build`` file in the ``data`` describes how the data files are
+processed when the build occurs:
+
+.. literalinclude:: app/data/meson.build
+   :language: python3
+
+Here, we tell Meson to simply copy the ``com.example.first_application.desktop``
+file into the build directory. We also declare that it should be installed, and
+that its installation directory is the ``applications`` subdirectory of the
+system location for data files (``datadir``).
+
+The ``com.example.first_application.svg`` file is more easily described to
+Meson. It will be installed in the appropriate subdirectory of the system
+location for data files that is used for icons.
+
+Building using Meson and Ninja
+------------------------------
+
+When building the application for deployment on the phone, we will use Flatpak
+to coordinate the build process. However, behind the scenes, we are using Meson
+and Ninja to perform the actual configuration and build. If you want to try and
+build the application for testing on your workstation, you can follow the steps
+below to build, install, and finally uninstall it.
+
+To configure the build on the command line, enter the ``app`` directory and
+run Meson, specifying the source and build directories::
+
+   meson . _build
+
+Build the application using Ninja, passing the build directory as an argument
+so that the build occurs within that directory. There is no need to specify a
+build rule because the default rule builds the application::
+
+   ninja -C _build
+
+Finally, use ``sudo`` to install the application in a standard location on your
+system using the ``install`` build rule::
+
+   sudo ninja -C _build install
+
+To uninstall the application, run its ``uninstall`` rule::
+
+   sudo ninja -C _build uninstall
+
+All of the files that were installed should now have been cleanly removed from
+system locations.
+
+Summary
+-------
+
+We have examined the contents of some ``meson.build`` files to see how simple
+rules are used to describe the configuration process. We have also seen how
+Meson and Ninja are used to configure and build the application.
+
+The application can also be packaged for more convenient installation using the
+Flatpak framework. This is the subject of the next part of the example.
+
+.. include:: /links.txt

Apps/Examples/common/Getting_the_App.txt

+.. Template text indicating how to obtain an application for an example
+
+Getting the Application
+=======================
+
+The application associated with this example can be found in the collection of
+repositories at the `Librem 5 examples project`_. You can either clone and build
+the application from the command line or open it in :ref:`gbuilder`.
+
+Using GNOME Builder
+-------------------
+
+Follow these steps to obtain the example:
+
+#. Start GNOME Builder and click the **Clone Repository…** button.
+#. Enter |project-repo| in the repository URL field and choose a directory
+   that will contain the working directory for the repository. The default
+   ``~/Projects`` directory is usually fine for this purpose.
+#. Click **Clone Project**.
+
+The repository will then be cloned and installed inside the chosen directory.
+
+Command Line
+------------
+
+To clone the repository on the command line, enter a suitable directory on your
+system and run the following command:
+
+.. code-par::
+
+   git clone |project|/|repo|
+
+This should result in the creation of a working directory for the repository in
+the current directory. The source code can be found in the working directory.
+
+.. include:: /links.txt

Apps/Examples/common/Packaging_the_App.txt

+Packaging the Application
+=========================
+
+.. contents::
+   :local:
+
+The ``app`` directory contains a |manifest|
+manifest file for use with Flatpak. This describes where the application
+source code can be obtained from, how the application is built, the
+dependencies that need to be built with it, and the permissions it needs when
+it is run.
+
+Writing the Manifest
+--------------------
+
+The manifest for this simple application is short, so we include the whole file
+here to provide an overview before looking at the details:
+
+.. include-par:: |manifest-path|
+   :language: json
+
+We examine the three main parts of the manifest individually.
+
+Application Information
+~~~~~~~~~~~~~~~~~~~~~~~
+
+In the manifest we record information about the application, including its ID
+and the command used to run it:
+
+.. include-par:: |manifest-path|
+   :start-at: {
+   :end-at: command
+
+The ``runtime`` and ``runtime-version`` values define precisely which
+collection of libraries the application needs to run. The corresponding ``sdk``
+value tells Flatpak which SDK is needed to build the application. When building
+applications for a GNOME-based platform the corresponding SDK is required.
+
+Permissions
+~~~~~~~~~~~
+
+The ``finish-args`` list is typically used to state which permissions the
+application needs. In this case it will need access to the Wayland display
+server to be able to show a window:
+
+.. include-par:: |manifest-path|
+   :start-at: finish-args
+   :end-at: ],
+
+Other permissions will be required if you want to store and modify settings for
+your application, access peripherals, and perform other tasks that require the
+user's consent.
+
+Modules
+~~~~~~~
+
+The ``modules`` list describes the application components (or modules),
+including any dependencies that need to be bundled with it, in a list of
+dictionaries:
+
+.. include-par:: |manifest-path|
+   :start-at: modules
+   :end-at: builddir
+
+The ``name`` of the application should be unique in the list of modules but can
+be otherwise freely assigned. We indicate that we are using the Meson build
+system and instruct Flatpak to use a separate build directory.
+
+After this, we describe where the sources of the application should be obtained
+from. For many applications we would describe the location of a repository.
+However, to make things simple, we indicate that the sources are in the same
+directory as the manifest:
+
+.. include-par:: |manifest-path|
+   :start-at: "sources"
+
+This concludes the description of the main (and only) module.
+
+Building the Application
+------------------------
+
+Following the instructions in :ref:`cross_building_flatpaks_app`, we use
+``flatpak-builder`` to build a flatpak for the application. To do this we need
+to install the runtime and SDK that the application depends on. These are the
+same as those mentioned in :ref:`flatpak_setup_gnome` except that we need the
+ones for the aarch64 architecture::
+
+   flatpak --user install flathub org.gnome.Platform/aarch64/3.30 org.gnome.Sdk/aarch64/3.30
+
+After installing these, build the application with ``flatpak-builder``:
+
+.. code-par::
+
+   flatpak-builder --arch=aarch64 --repo=myrepo _flatpak |app-id|.json
+
+The result is stored in the ``myrepo`` directory, which is a local repository.
+It can be exported from the repository as a binary bundle for deployment on
+the target device. We do this by running ``flatpak`` with the ``build-bundle``
+command, passing the repository, the name of the bundle to create and the
+application ID:
+
+.. code-par::
+
+   flatpak build-bundle --arch=aarch64 myrepo app.flatpak |app-id|
+
+In this case the bundle is written to the ``app.flatpak`` file. This can be
+copied to the phone or development board for installation.
+
+Installing the Application
+--------------------------
+
+One way to install the application is to use the ``flatpak`` tool on the
+command line to install the binary bundle. Other more user-friendly ways are
+also possible.
+
+First of all, copy the bundle to the target device and make it readable by the
+``purism`` user. Then, log in to the device and ensure that the ``flathub``
+remote is registered for the user::
+
+   flatpak --user remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
+
+Assuming that the ``app.flatpak`` file is in the current directory, install it
+for the user by running the ``install`` command::
+
+   flatpak --user install app.flatpak
+
+Flatpak will resolve the dependencies of the bundle using the remote we
+registered and ask you if you want to install them if they are not already
+present. It will then install the application itself.
+
+You can run the application using ``flatpak`` in the usual way:
+
+.. code-par::
+
+   flatpak run |app-id|
+
+When you are finished with the application and want to uninstall it, use the
+following command:
+
+.. code-par::
+
+   flatpak uninstall |app-id|
+
+You can also uninstall the runtime needed by the application, but it may be
+useful to keep it installed for future use.

Apps/Examples/index.rst

+.. _app_development_examples:
+
+Examples
+========
+
+This section contains a collection of example applications that highlight
+different aspects of application development and features of the Librem 5.
+
+We have chosen to implement many of the applications using the `Python 3`_
+programming language because it is accessible to a wide range of developers,
+and users of other languages should be able to read and understand the source
+code. We encourage others to port the examples to other programming languages
+-- see :ref:`contributing` if you are interested in doing this.
+
+Before you begin, review the :ref:`workstation` and :ref:`workstation_gnome`
+sections of this manual to ensure that you have installed the required
+development tools and libraries.
+
+.. toctree::
+   :maxdepth: 1
+
+   Networking/NetworkState/index
+
+.. include:: /links.txt

Apps/index.rst

@@ -25,6 +25,7 @@ features of the phone and its software environment.
    :maxdepth: 1
 
    Tutorials/index
+   Examples/index
    Guides/index
    Packaging_Apps/index
    PublishingApps