Commit bfb1862d authored by David Boddie's avatar David Boddie

Add most of the first tutorial

Update the development information with a PyGObject reference.
parent ac218a6f
.. _First_Application_building:
Building the Application
.. contents::
The ``app`` directory and its subdirectories contain ```` 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 ```` file begins with a
declaration of the project name, version and build system requirements:
.. literalinclude:: app/
We also declare the ``data`` and ``src`` subdirectories, causing Meson to
examine them for any ```` files they may contain.
The last line causes a special script to be run after installation. We will
cover this later.
Sources Build File
The ```` file in the ``src`` directory describes how the source
files are processed when the build occurs:
.. literalinclude:: app/src/
In this case, we instruct Meson to take the ```` file in the ``src``
directory and copy it into the build directory as ``your-first-application`` --
this is the name given as the executable in the :ref:`desktop entry file
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 ```` file in the ``data`` describes how the data files are
processed when the build occurs:
.. literalinclude:: app/data/
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.
We have examined the contents of some ```` 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 tutorial.
.. include:: /links.rst
.. _First_Application_data:
Data Files
.. contents::
Inside the ``data`` directory are three files: ``com.example.first_application.desktop``,
``com.example.first_application.svg`` and ````.
The ``com.example.first_application.desktop`` file is a `Desktop Entry`_ file.
The ``com.example.first_application.svg`` file is a `Scalable Vector Graphics`_
(SVG) file that contains the application icon.
The ```` file describes the build rules for the program -- we will
look at these later in :ref:`First_Application_building`.
.. _First_Application_desktop_file:
The Desktop Entry File
The ``com.example.first_application.desktop`` contains metadata about the
application that browsers and application launchers can use to show information
about the application, including its name, icon and the name of its executable
file. The contents of the file itself follows a simple format with many entries
being self-documenting:
.. literalinclude:: app/data/com.example.first_application.desktop
Less obvious entries are ``Exec`` and ``Terminal``. The ``Exec`` entry holds the
file name of the executable used to run the application. This will be defined
in the build script we use. The ``Terminal`` entry determines whether the
application should be run in a terminal program. We can ignore the other
entries for now.
The Icon File
The ``com.example.first_application.svg`` file is simply an SVG file:
.. image:: app/data/com.example.first_application.svg
We use an SVG file for convenience -- it can be rescaled as needed by the user
interface that shows it because the icon is stored in a vector file format. As
a result, we do not need to provide bitmaps of different sizes.
In this part of the tutorial we looked at two files that provide information
about the application (a desktop entry file) and a visual representation for it
(an SVG icon file).
Next, we will see how the main program and the data files are put together when
the application is built.
.. include:: /links.rst
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
This should result in the creation of a directory called ````
in your current directory. Enter this directory and find the application
directory for this tutorial::
You can build the application from the command line or open it in :ref:`gbuilder`.
.. include:: /links.rst
Overview of Files and Directories
The main ``app`` directory contains the following files and directories. Those
marked with a trailing slash are directories.
====================================== =========================================
Name Description
====================================== =========================================
**build-aux/** Helper scripts for the build system.
**com.example.first_application.json** Manifest file for deployment.
**data/** Data files for the installed application.
**** The main build file.
**src/** Source files for the application.
====================================== =========================================
The first four of these are concerned with building and packaging the
application, or contain data files that are not part of the application itself.
The ``src`` directory is where we will start to explore how the application is
put together.
.. _First_Application_src:
Source Files
.. contents::
Inside the ``src`` directory are two files: ```` and ````.
The ```` file describes the build rules for the program -- we will
look at these later in :ref:`First_Application_building`.
The ```` file contains the Python source code for the application.
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/
After the opening comments, there are three parts to the program: the module
imports, the application class, and the module level code at the end. We will
examine these parts of this program individually.
Importing Modules
The program begins by importing the modules it needs to create a user
interface. These are the ``sys`` module, which is needed to access the
command line arguments passed to the program when it is run, and the ``gi``
module, which provides a Python interface to the GNOME libraries:
.. literalinclude:: app/src/
:start-at: import
:end-at: repository
When importing the ``Gtk`` module, it is important to specify the version of
the API that will be used. Version 3.0 is the default in many environments, but
it is good practice to be explicit about the version in use.
Application Class
The application is represented by the ``Application`` class which is derived
from the standard ``Gtk.Application`` class. This class provides methods to set
up the application and perform tasks when it is run. It is defined in the
normal way, beginning with the ``__init__`` method:
.. literalinclude:: app/src/
:start-at: class Application
:end-at: GLib.set_application_name
This method performs two tasks that are necessary for the application to run
1. It uses the ``super`` built-function to call the ``__init__`` method of the
base class. This associates the application with the application ID given.
This ID must have a certain format which is described in the
`Gio.GApplication documentation`_.
2. It calls the ``GLib.set_application_name`` function to set a user-readable
application name that will be localized if translations are available.
It is not necessary to know what these things do. We just need to ensure that
they are done in this method.
When the application is run, the ``do_active`` method of the ``Application``
class is called. This is something that we need to implement if we want the
application to do something. In this case, we create a window and give it an
icon. Then we add a label to the window and show it:
.. literalinclude:: app/src/
:start-at: do_activate
:end-at: show_all
Going into detail, we create an instance of the ``Gtk.ApplicationWindow``
class, passing the application instance to it so that the application runs
until the window is closed -- see the `application property`_ documentation for
more information.
Text is displayed in the window using an instance of the ``Gtk.Label`` class
which we configure by calling ``set_markup`` to set its ``markup`` property.
This allows us to use simple HTML-like markup to show text with a specific size.
Because the window is a container, the label is added to it using the ``add``
method, and the window is shown using the ``show_all`` method so that both the
window and its contents are displayed.
Creating and Running an Application Instance
The last part of the program contains a standard Python idiom for checking that
the module is being run as a script:
.. literalinclude:: app/src/
:start-at: __main__
:end-at: exit
Here, we create the ``Application`` instance and call its ``run`` method with
any arguments that were passed to the application from its environment. When it
has finished running, its exit code is returned via the normal ``sys.exit``
This part of the tutorial showed the simple Python program that forms the core
of the application. It can be run as a standalone application.
However, if we want to install it, we need to build it in a particular way, and
we need to provide files that will allow the user to launch it from a GUI. The
next part of this tutorial describes how we provide the data files to do that.
.. include:: /links.rst
.. _`application property`:
.. _`Application section`:
#!/usr/bin/env python3
from os import environ, path
from subprocess import call
prefix = environ.get('MESON_INSTALL_PREFIX', '/usr/local')
datadir = path.join(prefix, 'share')
destdir = environ.get('DESTDIR', '')
# Package managers set this so we don't need to run
if not destdir:
print('Updating icon cache...')
call(['gtk-update-icon-cache', '-qtf', path.join(datadir, 'icons', 'hicolor')])
"app-id": "com.example.first_application",
"runtime": "org.gnome.Platform",
"runtime-version": "master",
"sdk": "org.gnome.Sdk",
"command": "your-first-application",
"finish-args": [
"build-options": {
"env": {
"V": "1"
"cleanup": [
"modules": [
"name": "first-application",
"buildsystem": "meson",
"builddir": true,
"subdir": "First_Application",
"sources": [
"branch": "master",
"type": "git",
"url": ""
[Desktop Entry]
Name=Your First Application
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<svg xmlns="" height="64" version="1.1" width="64"
viewBox="0 0 100 100">
<rect x="0" y="0" width="100" height="100" stroke="none" fill="#8080c0" />
<rect x="0" y="60" width="100" height="40" stroke="none" fill="#80c080" />
<circle cx="70" cy="30" r="20" stroke="none" fill="#f0f080" />
input: 'com.example.first_application.desktop',
output: 'com.example.first_application.desktop',
copy: true,
install: true,
install_dir: join_paths(get_option('datadir'), 'applications')
install_dir: join_paths(get_option('datadir'), 'icons', 'hicolor', 'scalable', 'apps'))
version: '0.1.0',
meson_version: '>= 0.40.0',
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Copyright (C) 2018 Purism SPC
# SPDX-License-Identifier: GPL-3.0+
# Author: David Boddie <>
import sys
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import GLib, Gtk
class Application(Gtk.Application):
def __init__(self):
GLib.set_application_name('Your First Application')
def do_activate(self):
window = Gtk.ApplicationWindow(application=self)
label = Gtk.Label()
label.set_markup('<span font="40">Hello World!</span>')
if __name__ == "__main__":
app = Application()
result =
input: '',
output: 'your-first-application',
copy: true,
install: true,
install_dir: get_option('bindir')
.. _First_Application:
Your First Application
In this tutorial we will create a simple Python 3 application that can be run
on the Librem 5. It is assumed that you have installed the tools mentioned in
the :ref:`workstation` and :ref:`workstation_gnome` sections of this manual
before trying to build and install it.
When run, the application described in this tutorial simply shows a window
containing a message. A number of files are provided with the application that
provide basic metadata and resources so that the application can be launched by
the phone environment.
.. image:: images/screenshot.png
:scale: 50%
:align: center
:alt: A screenshot of the application running in the phone environment
We will cover the different components that are needed for a basic application
like this one, including the files used to build it and the manifest needed to
deploy it.
.. toctree::
:maxdepth: 1
.. include:: /links.rst
.. _app_development_tutorials:
This section contains a collection of tutorials that aim to introduce you to
aspects of application development for the Librem 5.
We have chosen to implement many of the tutorial 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 tutorials 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
.. include:: /links.rst
......@@ -24,6 +24,7 @@ features of the phone and its software environment.
.. toctree::
:maxdepth: 1
......@@ -26,6 +26,14 @@ and build applications. The versions of these available in modern GNU/Linux
distributions should be sufficient. Debian-based distributions, such as PureOS,
provide packages called ``meson`` and ``ninja-build``.
Developers using the `Python 3`_ programming language should install the
PyGObject bindings for GObject-based libraries. Debian-based distributions
provide these in a package called ``python3-gi``. Installation on other
platforms is described in the `PyGObject documentation`_.
.. _`Building your first Flatpak`:
.. _`Debian`:
.. _`Debian package submission procedures`:
.. _`Desktop Entry`:
.. _` issues`:
.. _`EmCraft i.MX 8M SoM`:
.. _`Flatpak`:
.. _`Flatpak Builder documentation`:
.. _`Flatpak Building Introduction`:
.. _`Flatpak documentation`:
.. _`Gio.GApplication documentation`:
.. _`git-buildpackage`:
.. _`Glade`:
.. _`Glade Tutorials`:
......@@ -39,6 +41,7 @@
.. _`libhandy library`:
.. _libhandy documentation :
.. _libhandy website :
.. _`Librem 5 developer documentation repository`:
.. _`linux-emcraft issue 2`:
.. _`Meson`:
.. _`Nightly GNOME Apps`:
......@@ -46,6 +49,9 @@
.. _`Plasma Mobile`:
.. _`Plasma Mobile application development`:
.. _`PureOS`:
.. _`PyGObject documentation`:
.. _`Python 3`:
.. _`Python GTK+ 3 Tutorial`:
.. _`python-evdev`:
.. _`python-evdev tutorial`:
.. _`python-periphery`:
......@@ -56,6 +62,7 @@
.. _`Qt Quick`:
.. _`Qt Quick Controls 2`:
.. _`Running GTK+ Applications`:
.. _`Scalable Vector Graphics`:
.. _`FH34SRJ-6S-0.5SH(50) (Touch)`:
.. _`74LVC2G241DC,125`:
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment