Commit 557cf6e0 authored by David Boddie's avatar David Boddie

Import documentation for the network state example

parent 73b508a1
......@@ -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
.. |executable| replace:: ``network-state``
.. |desktop-entry-ref| replace:: desktop entry file
.. include:: /Apps/Examples/common/Building_the_App.txt
.. |app-dir| replace:: Network_State
.. include:: /Apps/Examples/common/Getting_the_App.txt
.. |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
.. _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
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
: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
: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
: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
Subproject commit c6b470577f8240fea7d1cec13a9c4256049eb6e9
.. _examples_Network_Status:
Network Status
==============
This example shows how to check the network status. When run, the application
simply shows a window containing a button and a label. When the button is
clicked, the network status 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
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
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
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
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
Getting the Application
=======================
The application can be found in the `Librem 5 developer documentation
repository`_. You can clone this repository locally with Git::
git clone https://source.puri.sm/Librem5/developer.puri.sm.git
This should result in the creation of a directory called ``developer.puri.sm``
in your current directory. Enter this directory and find the application
directory for this example:
.. code-par::
cd developer.puri.sm/Apps/Examples/|app-dir|/app
You can build the application from the command line or open it in :ref:`gbuilder`.
.. include:: /links.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|
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.
.. _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
Subproject commit ebe4180c915b858fd6026b726759123d17e0dfb8
Subproject commit dc3f4894b9575d13896a5ca222f5e77d0701b4af
Subproject commit cc04d11b1b5d8c70d0e95dca4dfa3ea219b39923
Subproject commit 6ab7e535b98de1a5549fc1654d92090173c4c4cb
......@@ -25,6 +25,7 @@ features of the phone and its software environment.
:maxdepth: 1
Tutorials/index
Examples/index
Guides/index
Packaging_Apps/index
PublishingApps
......
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