Merge branch '128-updates-needed-to-developing-for-gnome-section' into 'master'

Resolve "Updates needed to "Developing for GNOME" section"

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

Apps/GNOME/GBuilder.rst

@@ -7,33 +7,35 @@ GNOME Builder
           :ref:`flatpak_setup_gnome` section to setup flatpak on your
           workstation.
 
-This section will show you how to use GNOME Builder for developing, building,
-and deploying app flatpaks to a phone shell environment. Apps built from GNOME
-Builder can theoretically be deployed on Plasma Mobile as well.
+GNOME Builder is an Integrated Development Environment (IDE) traditionally used for building GNOME applications. This guide will show you how to set up Builder in preparation for developing, building, and deploying app flatpaks to a phone shell environment.
 
-Builder is a fantastic IDE traditionally used for building GNOME GTK apps however the fun doesn't have to stop there. It can build KDE apps as long as there is flatpak metadata for the application - more on that later.
+It may be useful to refer to the `GNOME Builder documentation`_ for more detailed information about setting up and using the IDE.
 
-First, checkout the `GNOME Builder documentation`_.
+Installing Builder
+------------------
 
-**Install the stable version of GNOME Builder**::
+First, ensure that you have set up Flatpak as described in ref:`flatpak_setup_gnome`. This enables installation of up-to-date versions of Builder.
+
+At the command line, run ``flatpak`` to install the latest version of GNOME Builder on the stable branch::
 
    $ flatpak install flathub org.gnome.Builder
 
-**Run GNOME Builder**::
+You may be asked to confirm installation. Once installed, you can run Builder in the following way::
 
    $ flatpak run org.gnome.Builder
 
-**You can later update the stable version of GNOME Builder**::
+You can later update the stable version of Builder using this command::
 
    $ flatpak update org.gnome.Builder
 
-***************************************
-Setting up QEMU on Debian based systems
-***************************************
+See the :ref:`package_management_flatpaks` guide for an overview of commands for installing, updating and uninstalling flatpaks.
+
+Setting up QEMU on Debian-Based Systems
+---------------------------------------
 
-Since Builder relies on statically linked qemu binaries, you will either need to run an OS that already does this for you (like Fedora, Debian Buster, or PureOS) or fix up your Debian stable workstation to enforce static linking before starting Builder. Manually fixing Debian qemu binaries (setting flags: F) is required until a patched version of qemu is distributed by your OS. Without statically linked qemu binaries, you will not be able to build an installable armhf or aarch64 flatpak from Builder.
+Since Builder relies on statically linked `qemu`_ binaries for cross-building, you will either need to run an OS that provides these for you (like Fedora, Debian Buster, or PureOS) or fix up your Debian Stable workstation to enforce static linking before starting Builder. Manually fixing Debian qemu binaries (setting flags: F) is required until a patched version of qemu is distributed by your OS. Without statically linked qemu binaries, you will not be able to build an installable armhf or aarch64 flatpak from Builder.
 
-To perform these operations, you will need to be the root user (sudo is not good enough).
+To perform these operations, you will need to be the ``root`` user (sudo is not good enough).
 
 You can first check what the flags are set to for qemu-arm and then perform a similar operation to see the flags for qemu-aarch64::
 
@@ -71,85 +73,11 @@ qemu-aarch64::
    magic 7f454c460201010000000000000000000200b700
    mask ffffffffffffff00fffffffffffffffffeffffff
 
+Further Reading
+---------------
 
+The `GNOME Builder documentation`_ contains more in-depth information about all aspects of the IDE.
 
-********************************************************
-Building a C/GTK 3 (libhandy) flatpak with GNOME Builder
-********************************************************
-For this example, the `geary <https://gitlab.gnome.org/aplazas/geary/tree/wip/aplazas/stackablebox>`_ application will be built (written in C and available in Debian apt repositories). This build was done on an x86 system running Debian testing.
-
-The `libhandy <https://source.puri.sm/Librem5/libhandy>`_ repository has already been cloned and the master branch checked out.
-
-When you open Builder, select to "Open" a new project and navigate to the libhandy folder.
-
-When Builder opens a project, it immediately tries to build it for your host's architecture. You can see this by clicking the build log (brick wall). If you would like to build for a different architecture, this is a good time to cancel the build. After the build is cancelled, select what architecture you would like to build for from the devices drop down menu:
-
-.. image:: images/devices.png
-   :width: 500px
-   :height: 300px
-   :align: left 
-
-|
-|
-
-As soon as you select a different architecture, a build is started for that architecture. 
-
-|
-|
-|
-|
-|
-|
-|
-|
-
-.. note:: If your build dependencies for the project are not installed you will know from watching the Builder "Build Log" in the bottom panel (brick wall icon) where the unsatisfied dependencies will be complained about until they are resolved.
-
-.. image:: images/build_log.png
-   :width: 500px
-   :height: 300px
-   :align: left 
-
-Builder will stop after configuring the project. To complete the flatpak bundle creation, you can click any of the remaining build steps listed in the "Build Details" drop-down to resolve the build through that step.
-
-|
-|
-|
-|
-
-Alternatively, you can click the omnibar in Builder and select the "Export Bundle" button and patiently wait while Builder progresses through flatpak creation.
-
-.. image:: images/builder_export_bundle.png
-   :width: 500px
-   :height: 300px
-   :align: center
-
-When the flatpak creation is finished, a nautilus window will pop up in the directory where the sm.puri.Handy.Example.flatpak is located. In this example, the flatpak can be found here: ~/.var/app/org.gnome.Builder/cache/gnome-builder/projects/libhandy/flatpak/staging/arm-wip-stackablebox/sm.puri.Handy.Example.flatpak
-
-**********************************************************************
-Deploying a C/GTK 3 (libhandy) flatpak to Phosh running on i.MX6 board
-**********************************************************************
-
-To run this flatpak you must first get the flatpak onto the dev board and install it. 
-The dev board should have a working networking setup and IP address that you can use to ssh/scp. The OS has ssh running and enabled by default (port 22). The system should also have flatpak installed.
-
-Scp the flatpak to the system, install it and run it (from an ssh session)::
-
-   user@workstation:~$ scp ~/.var/app/org.gnome.Builder/cache/gnome-builder/projects/libhandy/flatpak/staging/arm-wip-stackablebox/sm.puri.Handy.Example.flatpak purism@<sut_ip>:~/
-   purism@pureos:~$ sudo flatpak install sm.puri.Handy.Example.flatpak
-   purism@pureos:~$ flatpak run sm.puri.Handy.Example
-
-You will see the application start on the screen connected to the board.
-
-|pic1| |pic2|
-
-.. |pic1| image:: images/libhandy_welcome.jpg
-   :width: 300px
-   :height: 400px
-
-
-.. |pic2| image:: images/libhandy_dialer.jpg
-   :width: 300px
-   :height: 400px
+See the :ref:`tutorial_build_flatpak_gnome_builder` tutorial for a practical guide to building and deploying a flatpak on a development board.
 
 .. include:: /links.txt

Apps/Tutorials/GNOME_Builder_Flatpak/index.rst

+.. _tutorial_build_flatpak_gnome_builder:
+
+Building and Deploying an Application with GNOME Builder
+========================================================
+
+This tutorial describes how to use GNOME Builder to build an application written in C using GTK 3 and the `libhandy library`_, package it as a flatpak, and finally deploy it to a development board or phone.
+
+Setting up
+----------
+
+The phone should have a working networking setup and IP address, as well as a running ``sshd`` listening on port 22 that enables the use of the ``ssh`` and ``scp`` tools. The system should also have flatpak installed. If you are using a development board, it can help to review the :ref:`devkit_howto` to ensure that all of these things are set up.
+
+In the steps below we assume that the phone has an IP address of ``192.168.42.2``. Replace this address with the real address of your phone or development board where appropriate.
+
+Getting SDKs and Runtimes
+-------------------------
+
+Review the :ref:`flatpak_setup_gnome` instructions to ensure that you have suitable runtimes installed on the phone. It is also useful to install the latest runtimes from the gnome-nightly repository.
+
+Log in to the phone using ``ssh``::
+
+   user@workstation:~$ ssh purism@192.168.42.2
+
+Add a new remote to the Flatpak configuration and install the latest GNOME runtime::
+
+   purism@pureos:~$ flatpak remote-add --if-not-exists gnome-nightly https://sdk.gnome.org/gnome-nightly.flatpakrepo
+   purism@pureos:~$ flatpak install org.gnome.Platform/aarch64/master
+
+This should provide the dependencies needed for the application. You can now log out of the phone.
+
+Cloning the Application Repository
+----------------------------------
+
+For this example, the libhandy demo application will be built from the master branch of the libhandy repository.
+
+When you start Builder, open the application menu in the top-right of title bar, and select *Clone Repository*.
+
+.. image:: images/gnome-builder-clone-repo.png
+   :scale: 50%
+   :align: center
+   :alt: Cloning the libhandy repository
+
+Fill in the Repository URL for the libhandy repository::
+
+   https://source.puri.sm/Librem5/libhandy.git
+
+You can leave the Project Directory to be the default directory, or change it if you like.
+
+If the values in the form are valid, or reasonable, the *Clone Project* button should be highlighted. Click it to start cloning the project -- note that this may take a few seconds.
+
+Starting Builder
+----------------
+
+When Builder opens a project or clones a repository, it may try to build it for your host's architecture. You can see this by clicking the build log -- the brick wall icon at the top of the window. If you would like to build for a different architecture, this is a good time to cancel the build by pressing the stop button that appears in place of the build icon. After the build is cancelled, select what architecture you would like to build for from the devices drop down menu:
+
+.. image:: images/gnome-builder-select-architecture.png
+   :scale: 50%
+   :align: center
+   :alt: Selecting the target architecture
+
+As soon as you select a different architecture, a build is started for that architecture. Select the ``aarch64`` architecture by opening the devices menu to the left of the omnibar at the top of the window.
+
+.. note:: If your build dependencies for the project are not installed you can open the Builder "Build Log" in the bottom panel (brick wall icon) to see which unsatisfied dependencies need to be resolved.
+
+.. image:: images/gnome-builder-build-output.png
+   :scale: 50%
+   :align: center
+   :alt: Viewing build output
+
+Builder will stop after configuring the project. To complete the flatpak bundle creation, you can click any of the remaining build steps listed in the "Build Details" drop-down to resolve the build through that step.
+
+Alternatively, you can click the omnibar at the top of the window and select the *Export Bundle* button to start creation of a flatpak bundle that can be deployed to the phone.
+
+.. image:: images/gnome-builder-export-bundle.png
+   :scale: 50%
+   :align: center
+   :alt: Exporting a flatpak bundle
+
+When the flatpak creation is finished, a file manager window will pop up in the directory where the ``sm.puri.Handy.Example.flatpak`` is located. Make a note of this location.
+
+Deploying the flatpak to the Phone
+----------------------------------
+
+To run this flatpak you must first transfer it onto the phone or development board and install it. On your workstation, open a terminal and change directory to the one containing the ``sm.puri.Handy.Example.flatpak`` file.
+
+Copy the flatpak to the phone using the ``scp`` tool::
+
+   user@workstation:~$ scp sm.puri.Handy.Example.flatpak purism@192.168.42.2:~/
+
+Log in to the phone using ``ssh``::
+
+   user@workstation:~$ ssh purism@192.168.42.2
+
+Install the flatpak on the phone::
+
+   purism@pureos:~$ flatpak install sm.puri.Handy.Example.flatpak
+
+You may be asked to install additional packages for the runtimes that the application needs to run.
+
+If installation fails due to missing runtimes, you may need to review the instructions at the start of this document.
+
+If it was installed successfully then you can run the installed application::
+
+   purism@pureos:~$ flatpak run sm.puri.Handy.Example
+
+You will see the application start on the screen connected to the board.
+
+.. image:: images/libhandy-welcome.png
+   :scale: 50%
+   :align: center
+   :alt: A screenshot of the application running in the phone environment
+
+.. include:: /links.txt

Apps/Tutorials/index.rst

@@ -23,5 +23,6 @@ information about the APIs used by applications.
    First_Application/index
    App_Resources/index
    Adaptive_UI/index
+   GNOME_Builder_Flatpak/index
 
 .. include:: /links.txt

links.txt

@@ -106,8 +106,9 @@
 .. _`KDE Community`: https://www.kde.org
 .. _`KDE project`: https://www.kde.org
 .. _`Kirigami`: https://api.kde.org/frameworks/kirigami/html/index.html
-.. _`libhandy library`: https://source.puri.sm/Librem5/libhandy
+.. _`libhandy demo application`: https://source.puri.sm/Librem5/libhandy/examples/
 .. _`libhandy documentation`: http://developer.puri.sm/projects/libhandy/doc/
+.. _`libhandy library`: https://source.puri.sm/Librem5/libhandy
 .. _`libhandy PyGObject API documentation`: https://lazka.github.io/pgi-docs/#Handy-0.0
 .. _libhandy website : https://source.puri.sm/Librem5/libhandy
 .. _`Librem 5 developer documentation repository`: https://source.puri.sm/Librem5/developer.puri.sm