Commit 842df384 authored by Guido Gunther's avatar Guido Gunther

Merge branch 'doc-restage-1' into 'master'

Add introductory and setup information

See merge request Librem5/developer.puri.sm!93
parents ebb60cec ffeae62d
Pipeline #2734 passed with stage
in 3 minutes and 36 seconds
.. index:: API Docs
.. api_docs:
API Docs
========
API Documentation
=================
This chapter contains API documentation specific to the Librem 5 as well as
links to upstream documentation.
......
.. _app_development:
App Development
===============
Application Development
=======================
.. toctree::
......
.. _gtk+:
.. _GTK+ website : https://www.gtk.org/
.. _GTK+ 3 documentation : https://developer.gnome.org/gtk3/stable/
.. _GTK+ Inspector : https://wiki.gnome.org/Projects/GTK+/Inspector
.. _selection mode : https://developer.gnome.org/hig/stable/selection-mode.html.en
.. _enable dconf access : http://docs.flatpak.org/en/latest/sandbox-permissions.html#dconf-access
.. _application menu design : https://gitlab.gnome.org/Community/Design/os-mockups/tree/master/app-menu
.. _application menu example application : https://source.puri.sm/Librem5/purism-gtk-3-examples/tree/app-menu
.. _adaptive labels example application : https://source.puri.sm/Librem5/purism-gtk-3-examples/tree/adaptive-labels
.. _adaptive grid layout example application : https://source.puri.sm/Librem5/purism-gtk-3-examples/tree/adaptive-grid-layout-0-0-4
.. _GtkHeaderBar : https://developer.gnome.org/gtk3/stable/GtkHeaderBar.html
.. _GtkLabel : https://developer.gnome.org/gtk3/stable/GtkLabel.html
.. _GtkLabel ellipize property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--ellipsize
.. _GtkLabel wrap property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--wrap
.. _GtkLabel wrap-mode property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--wrap-mode
.. _GtkLabel xalign property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--xalign
.. _GtkSeparator : https://developer.gnome.org/gtk3/stable/GtkSeparator.html
.. _GtkSizeGroup : https://developer.gnome.org/gtk3/stable/GtkSizeGroup.html
.. _libhandy website : https://source.puri.sm/Librem5/libhandy
.. _libhandy documentation : http://honk.sigxcpu.org/projects/libhandy/doc/
.. _HdyHeaderGroup : https://honk.sigxcpu.org/projects/libhandy/doc/HdyHeaderGroup.html
.. _HdyLeaflet : https://honk.sigxcpu.org/projects/libhandy/doc/HdyLeaflet.html
.. _HdyTitleBar : https://honk.sigxcpu.org/projects/libhandy/doc/HdyTitleBar.html
.. note:: New advice on adaptive GTK+ applications development are regularly documented on this page, don't hesitate to visit it regularly.
.. note:: New advice on adaptive GTK+ applications development are regularly
documented on this page.
GTK+
====
......@@ -92,46 +65,9 @@ It is a very convenient widget as it allows header bars to look good when animat
Some title bars are composed of multiple header bars, in such a case it is advised to separate them with a GtkSeparator_ with the `sidebar` style class.
To help spreading the window decoration across all header bars as if they were only one, just show the close button on all of your header bars and put them into a HdyHeaderGroup_ in the same order they appear in the title bar.
Here is an simple `GtkBuilder` example showing this section's advises:
.. code:: xml
<?xml version="1.0" encoding="UTF-8"?>
<interface>
<object class="GtkWindow">
<child type="titlebar">
<object class="HdyTitleBar">
<child>
<object class="GtkBox">
<child>
<object class="GtkHeaderBar" id="start_header">
<property name="show-close-button">True</property>
</object>
</child>
<child>
<object class="GtkSeparator">
<style>
<class name="sidebar"/>
</style>
</object>
</child>
<child>
<object class="GtkHeaderBar" id="end_header">
<property name="show-close-button">True</property>
</object>
</child>
</object>
</child>
</object>
</child>
</object>
<object class="HdyHeaderGroup">
<headerbars>
<headerbar name="start_header"/>
<headerbar name="end_header"/>
</headerbars>
</object>
</interface>
Here is an simple `GtkBuilder` example showing this section's advice:
.. literalinclude:: /Apps/_files/window.ui
Selection Mode
--------------
......@@ -177,3 +113,12 @@ Navigate in the layout:
:align: center
To help you implement these, we created an `example application <adaptive grid layout example application_>`_, just clone it in :ref:`gbuilder` and check the ``adaptive-grid-layout-0-0-3`` branch out.
.. include:: ../../links.rst
.. _selection mode : https://developer.gnome.org/hig/stable/selection-mode.html.en
.. _enable dconf access : http://docs.flatpak.org/en/latest/sandbox-permissions.html#dconf-access
.. _application menu design : https://gitlab.gnome.org/Community/Design/os-mockups/tree/master/app-menu
.. _application menu example application : https://source.puri.sm/Librem5/purism-gtk-3-examples/tree/app-menu
.. _adaptive labels example application : https://source.puri.sm/Librem5/purism-gtk-3-examples/tree/adaptive-labels
.. _adaptive grid layout example application : https://source.puri.sm/Librem5/purism-gtk-3-examples/tree/adaptive-grid-layout-0-0-4
<?xml version="1.0" encoding="UTF-8"?>
<interface>
<object class="GtkWindow">
<child type="titlebar">
<object class="HdyTitleBar">
<child>
<object class="GtkBox">
<child>
<object class="GtkHeaderBar" id="start_header">
<property name="show-close-button">True</property>
</object>
</child>
<child>
<object class="GtkSeparator">
<style>
<class name="sidebar"/>
</style>
</object>
</child>
<child>
<object class="GtkHeaderBar" id="end_header">
<property name="show-close-button">True</property>
</object>
</child>
</object>
</child>
</object>
</child>
</object>
<object class="HdyHeaderGroup">
<headerbars>
<headerbar name="start_header"/>
<headerbar name="end_header"/>
</headerbars>
</object>
</interface>
.. workstation:
.. _workstation:
Workstation
===========
.. contents::
Application development for the Librem 5 is not tied to a particular set of
technologies. However, for simplicity, we recommend that you use the same set
of tools and libraries that the Librem 5 developers have used.
* GNOME technologies: A run through the various GNOME technologies.
* GNOME Builder documentation: Documentation for the GNOME IDE.
* Meson: The recommended build system.
* Flatpak: Application sandboxing and distribution.
* gitg: The GNOME git client.
Where appropriate you can use the versions of these that are provided with your
operating system. However, it may be necessary to install more up-to-date
versions of some tools when new features are needed. The preferred method for
doing this is to use Flatpak to install sandboxed versions of the required
applications.
GNOME and GNOME Builder
-----------------------
The default software stack is based on many of the `technologies`_ from the
`GNOME`_ desktop environment. The applications supplied with the phone are
also built using components from GNOME, such as the `GTK+ toolkit`_. It can be
useful to install the latest development versions of these components.
We suggest that developers use the `GNOME Builder`_ Integrated Development
Environment (IDE) to develop applications. The `latest documentation`_ for
Builder describes the `preferred installation`_ method for the IDE. This can
be used to ensure that you have the latest version.
Meson and Ninja
---------------
Many applications will use the `Meson`_ and `Ninja`_ build tools to configure
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``.
Flatpak
-------
`Flatpak`_ provides features for application sandboxing and distribution.
Applications for the phone can be distributed as Flatpaks - packages that can
be distributed via repositories. Documentation for the ``flatpak`` tool and
its ``flatpak-builder`` wrapper can be found in the `Flatpak documentation`_.
Versions of these tools provided with modern GNU/Linux distributions should be
sufficient. Debian-based distributions provide packages called ``flatpak`` and
``flatpak-builder``.
gitg
----
This `GNOME git client`_ can be useful for visualizing git repositories. This
is particularly helpful if you are considering porting an application with an
extensive development history.
Versions of this tool provided with modern GNU/Linux distributions should be
sufficient. Debian-based distributions provide a package called ``gitg``.
.. include:: ../links.rst
.. _`technologies`: https://www.gnome.org/technologies/
.. _`latest documentation`: https://builder.readthedocs.io/en/latest/
.. _`preferred installation`: https://builder.readthedocs.io/en/latest/installation.html
.. _hardware_ref:
.. _hardware_reference:
Hardware Reference
==================
......
......@@ -3,18 +3,26 @@
Introduction
============
The Librem 5 will be an i.MX8 phone running PureOS, a Debian derivative. The
kernel will be the 4.18 mainline kernel with some additional drivers. For the
graphical windowing system, it will make use of a Wayland compositor together
with a shell named phosh. The graphical environment will be based on the GNOME
platform with a variety of modifications. Below you can find a diagram on the
overall software architecture stack.
.. image:: images/L5-stack.png
:width: 700px
:height: 500px
:align: center
The Librem 5 is a smartphone built using free software components with a
focus on user privacy. Key features include:
* Based on `PureOS`_, a `Debian`_ derivative operating system.
* Runs a modern, supported Linux kernel.
* Separates the CPU from baseband components for additional privacy.
* Provides hardware kill switches for microphone, camera and radio components.
See the :ref:`software_reference` chapter for information about the software
components that are supplied with the phone. See the :ref:`hardware_reference`
chapter for details of the hardware used in the phone.
This document aims to provide information needed by developers who want to
create applications to run on the Librem 5. It also contains information for
those interested in the underlying software platform and hardware, as well as
developers of alternative software platforms who wish to deploy those on the
phone.
.. toctree::
Introduction/History
.. include:: /links.rst
......@@ -9,6 +9,18 @@ Software Reference
This chapter provides information about the software components used in the
Librem 5 stack and includes links to useful external resources.
The Librem 5 will be an i.MX8 phone running PureOS, a Debian derivative. The
kernel will be the 4.18 mainline kernel with some additional drivers. For the
graphical windowing system, it will make use of a Wayland compositor together
with a shell named phosh. The graphical environment will be based on the GNOME
platform with a variety of modifications. Below you can find a diagram on the
overall software architecture stack.
.. image:: images/L5-stack.png
:width: 700px
:height: 500px
:align: center
.. toctree::
Software_Reference/Environments
......
.. _`Debian`: https://www.debian.org
.. _`Flatpak documentation`: http://docs.flatpak.org/en/latest/
.. _`Flatpak`: https://flatpak.org/
.. _`GNOME Builder`: https://wiki.gnome.org/Apps/Builder
.. _`GNOME git client`: https://wiki.gnome.org/Apps/Gitg
.. _`GNOME`: https://www.gnome.org
.. _`GTK+ 3 documentation`: https://developer.gnome.org/gtk3/stable/
.. _GtkHeaderBar : https://developer.gnome.org/gtk3/stable/GtkHeaderBar.html
.. _`GTK+ Inspector`: https://wiki.gnome.org/Projects/GTK+/Inspector
.. _GtkLabel ellipize property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--ellipsize
.. _GtkLabel : https://developer.gnome.org/gtk3/stable/GtkLabel.html
.. _GtkLabel wrap-mode property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--wrap-mode
.. _GtkLabel wrap property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--wrap
.. _GtkLabel xalign property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--xalign
.. _GtkSeparator : https://developer.gnome.org/gtk3/stable/GtkSeparator.html
.. _GtkSizeGroup : https://developer.gnome.org/gtk3/stable/GtkSizeGroup.html
.. _`GTK+ toolkit`: https://www.gtk.org
.. _`GTK+ website`: https://www.gtk.org/
.. _HdyHeaderGroup : https://honk.sigxcpu.org/projects/libhandy/doc/HdyHeaderGroup.html
.. _HdyLeaflet : https://honk.sigxcpu.org/projects/libhandy/doc/HdyLeaflet.html
.. _HdyTitleBar : https://honk.sigxcpu.org/projects/libhandy/doc/HdyTitleBar.html
.. _libhandy documentation : http://honk.sigxcpu.org/projects/libhandy/doc/
.. _libhandy website : https://source.puri.sm/Librem5/libhandy
.. _`Meson`: https://mesonbuild.com/
.. _`Ninja`: https://ninja-build.org/
.. _`PureOS`: https://pureos.net
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