Commit 5173c75a authored by David Boddie's avatar David Boddie

Add extension to provide substitutions in code blocks, reuse text

parent 8c5ad974
.. _App_Resources_tutorial_packaging:
Packaging the Application
=========================
.. |manifest| replace:: ``com.example.app_resources.json``
.. |manifest-path| replace:: app/com.example.app_resources.json
.. |app-id| replace:: com.example.app_resources
.. contents::
:local:
The ``app`` directory contains a ``com.example.app_resources.json``
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:
.. literalinclude:: app/com.example.app_resources.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:
.. literalinclude:: app/com.example.app_resources.json
: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:
.. literalinclude:: app/com.example.app_resources.json
: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:
.. literalinclude:: app/com.example.app_resources.json
: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:
.. literalinclude:: app/com.example.app_resources.json
:start-at: modules
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`::
flatpak-builder --arch=aarch64 --repo=myrepo _flatpak com.example.app_resources.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::
flatpak build-bundle --arch=aarch64 myrepo app.flatpak com.example.app_resources
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::
flatpak run com.example.app_resources
When you are finished with the application and want to uninstall it, use the
following command::
flatpak uninstall com.example.app_resources
You can also uninstall the runtime needed by the application, but it may be
useful to keep it installed for future use.
.. include:: ../common/Packaging_the_App.txt
.. _First_Application_packaging:
Packaging the Application
=========================
.. |manifest| replace:: ``com.example.first_application.json``
.. |manifest-path| replace:: app/com.example.first_application.json
.. |app-id| replace:: com.example.first_application
.. contents::
:local:
The ``app`` directory contains a ``com.example.first_application.json``
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:
.. literalinclude:: app/com.example.first_application.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:
.. literalinclude:: app/com.example.first_application.json
: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:
.. literalinclude:: app/com.example.first_application.json
: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:
.. literalinclude:: app/com.example.first_application.json
: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:
.. literalinclude:: app/com.example.first_application.json
:start-at: modules
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`::
flatpak-builder --arch=aarch64 --repo=myrepo _flatpak com.example.first_application.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::
flatpak build-bundle --arch=aarch64 myrepo app.flatpak com.example.first_application
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::
flatpak run com.example.first_application
When you are finished with the application and want to uninstall it, use the
following command::
flatpak uninstall com.example.first_application
You can also uninstall the runtime needed by the application, but it may be
useful to keep it installed for future use.
.. include:: ../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|
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.
from docutils import nodes
from docutils.parsers.rst import directives
import re
from six import text_type
from sphinx.directives.code import CodeBlock, LiteralInclude, \
LiteralIncludeReader
from sphinx.util.nodes import set_source_info
class LiteralIncludeParam(LiteralInclude):
"""
Like ``.. literalinclude``, but expects a replacement/substitution to be
used as the file name.
"""
def run(self):
# type: () -> List[nodes.Node]
document = self.state.document
subst_text = self.arguments[0]
if subst_text[:1] != '|' or subst_text[-1:] != '|':
return [document.reporter.warning(
'Argument should be a replacement/subsitution with the format '
'|<text>|', line=self.lineno)]
else:
# Dereference the substitution text to produce a filename.
subst_name = subst_text[1:-1]
try:
filename = str(document.substitution_defs[subst_name].next_node())
except KeyError:
return [document.reporter.warning(
'Replacement/substitution {0} not defined'.format(subst_name),
line=self.lineno)]
self.arguments[0] = filename
return LiteralInclude.run(self)
class CodeParam(CodeBlock):
"""
Like ``.. code-block``, but replaces |<text>| with the corresponding text
defined in a replacement/substitution.
"""
required_arguments = 0
optional_arguments = 1
# Define a regular expression for locating placeholders.
placeholder_re = re.compile('\\|([^|]+)\\|')
def run(self):
# type: () -> List[nodes.Node]
document = self.state.document
# Find placeholders in the text and replace them with replacements
# defined for the document.
for i, line in enumerate(self.content):
for match in self.placeholder_re.findall(line):
try:
text = str(document.substitution_defs[match].next_node())
line = line.replace('|' + match + '|', text)
except KeyError:
pass
self.content[i] = line
# In Sphinx 2.0 the language argument to code-block is optional, but
# in earlier versions we need to add one if no argument is given.
if len(self.arguments) < 1:
self.arguments = ['text']
return CodeBlock.run(self)
def setup(app):
directives.register_directive('include-par', LiteralIncludeParam)
directives.register_directive('code-par', CodeParam)
return {'version': '0.1'}
......@@ -17,23 +17,26 @@
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
import os
import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# We use literalinclude options introduced in version 1.6.
needs_sphinx = '1.6'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
sys.path.append(os.path.abspath("./_extensions"))
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.imgmath',
'include_par'
]
# Add any paths that contain templates here, relative to this directory.
......
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