diff options
author | Kavindra Palaraja <kpalaraja@luxoft.com> | 2019-08-06 08:24:06 +0200 |
---|---|---|
committer | Kavindra Palaraja <kpalaraja@luxoft.com> | 2019-08-09 10:24:42 +0200 |
commit | 9025202f528164618a67f06b984169dddcce2240 (patch) | |
tree | 68901cd5e160535b4ffc8faa14d2dbcc0feb89e9 /examples/applicationmanager | |
parent | 1968c30f07c4ed8e682829bb4264364d3bdf9341 (diff) | |
download | qtapplicationmanager-9025202f528164618a67f06b984169dddcce2240.tar.gz |
[doc] Add some documentation for the Software Container Plugin Example
* Minor fixes to the "Write Applications" topic that I've been looking at
Change-Id: I372729f3e08340d3a78569cb15ee05f2cc4c2e6e
Fixes: AUTOSUITE-867
Reviewed-by: Robert Griebl <robert.griebl@pelagicore.com>
Diffstat (limited to 'examples/applicationmanager')
-rw-r--r-- | examples/applicationmanager/softwarecontainer-plugin/README.md | 71 | ||||
-rw-r--r-- | examples/applicationmanager/softwarecontainer-plugin/doc/src/softwarecontainer-plugin.qdoc | 106 |
2 files changed, 106 insertions, 71 deletions
diff --git a/examples/applicationmanager/softwarecontainer-plugin/README.md b/examples/applicationmanager/softwarecontainer-plugin/README.md deleted file mode 100644 index 57d7eb3b..00000000 --- a/examples/applicationmanager/softwarecontainer-plugin/README.md +++ /dev/null @@ -1,71 +0,0 @@ -# SoftwareContainer Plugin - -This is a very basic PoC integration of Pelagicore's Software-Containers - -[https://github.com/Pelagicore/softwarecontainer][] - -Please also read the "Containers" page in the official Qt Application Manager -documentation: -[https://doc-snapshots.qt.io/qtapplicationmanager/containers.html] - -Parts of the container configuration are hardcoded in `softwarecontainer.cpp`, -while all of the capability definition is in the JSON manifest at -`service-manifest.d/io.qt.ApplicationManager.Application/`. - -The Wayland/OpenGL pass-through is tested against Intel GPUs and VMware's -virtual GPU. - -The softwarecontainer-agent needs to be started as root. By default it will -register itself on the system D-Bus, so a policy file must be in place, -allowing it to register itself on the system-bus. If you want to run the -agent on the session bus instead (via the `--session-bus` parameter), you -have to add the following to one of your config.yaml files: -``` -containers: - softwarecontainer: - dbus: 'session' -``` - -Passing the service-manifest directory that comes with the plugin via -`-m` is mandatory - otherwise the container setup will fail due to the -missing `io.qt.ApplicationManager.Application` capability. - -You have to make sure that the agent has access to the same session-bus -that the application-manager is using, if you intend on forwarding this -bus. This is a bit tricky if the agent is run as root and the application- -manager as non-root user, since the default session-bus policy in most -distros disallows root to access user session-busses: the workaround is to -add a `<allow user="root"/>` policy in `/etc/dbus-1/session.conf`. - -Please do also not forget to tell the agent about your environment, when -running it via sudo: -``` -sudo XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR -DBUS_SESSION_BUS_ADDRESS=$DBUS_SESSION_BUS_ADDRESS softwarecontainer-agent -m -/path/to/application-manager/examples/softwarecontainer-plugin/service-manifest.d/ -``` - -On the AM side, you need to activate the plugin by adding something like -this to one of your config.yaml files: -``` -plugins: - container: [ "/path/to/libsoftwarecontainer-plugin.so" ] -``` -In order to actually run apps within softwarecontainers, you have to add a -container selection configuration: -[https://doc-snapshots.qt.io/qtapplicationmanager/containers.html#container-selection-configuration][] - - -Please be aware that for easier development on the desktop, you normally want -your $HOME directory mounted into the container in read-only mode, so you do -not have to install your application-manager into /usr/ after every build -(given that your build directory is somewhere in $HOME, the container would -not see the appman-launcher-qml binary). -This is *not* done by default, but you can activate this behavior by adding -this to one of your config.yaml files: - -``` -containers: - softwarecontainer: - bindMountHome: yes -``` diff --git a/examples/applicationmanager/softwarecontainer-plugin/doc/src/softwarecontainer-plugin.qdoc b/examples/applicationmanager/softwarecontainer-plugin/doc/src/softwarecontainer-plugin.qdoc new file mode 100644 index 00000000..72fc309a --- /dev/null +++ b/examples/applicationmanager/softwarecontainer-plugin/doc/src/softwarecontainer-plugin.qdoc @@ -0,0 +1,106 @@ +/**************************************************************************** +** +** Copyright (C) 2019 Luxoft Sweden AB +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Luxoft Application Manager. +** +** $QT_BEGIN_LICENSE:FDL-QTAS$ +** Commercial License Usage +** Licensees holding valid commercial Qt Automotive Suite licenses may use +** this file in accordance with the commercial license agreement provided +** with the Software or, alternatively, in accordance with the terms +** contained in a written agreement between you and The Qt Company. For +** licensing terms and conditions see https://www.qt.io/terms-conditions. +** For further information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + +\example applicationmanager/softwarecontainer-plugin +\brief Learn how to integrate Software Containers with the Application Manager. +\ingroup applicationmanager-examples +\title Software Container Plugin example + +\section1 Introduction + +This example shows how to integrate \l{https://github.com/Pelagicore/softwarecontainer +{Pelagicore's Software Containers} with the Application Manager. + +\note As a prerequisite, familiarize yourself with \l{Containers} beforehand. + +In \c softwarecontainer.cpp, parts of the container's configuration is hardcoded; all of the +capability definition is in the JSON manifest file located in +\c{service-manifest.d/io.qt.AppliciationManager.Application/}. + +The Wayland/OpenGL passthrough is tested against Intel GPUs and VMWare's virtual GPU. + +\section1 Run the Software Container Agent + +To run the softwarecontainer-agent, you must start it as root. By default, this agent registers +itself on the system D-Bus. So, you need to have a policy file in place, to allow the agent to +register itself on the system-bus. + +If you want to run the agent on the session bus instead, via the \c{--session-bus} parameter, +then you have to add the following lines to one of your \c config.yaml files: + +\code +containers: + softwarecontainer: + dbus: 'session' +\endcode + +It's mandatory to pass the service manifest directory that comes with the plugin via \c{-m}. +Otherwise, the container setup fails due to the missing \c{io.qt.ApplicationManager.Application} +capability. + +Make sure that the agent has access to the same session bus that the application manager uses, +if you intend on forwarding this bus. If the agent is run as root, but the application manager is +a non-root user, this can be tricky -- since the default session bus policy in most Linux distros +disallows root to access user session busses. However, you can workaround this issue by adding +an \c{<allow user="root"/>} policy within the \c{<policy context="default">} element in +\c{/etc/dbus-1/session.conf}. + +Additionally, make sure to tell the agent about your environment, when running it via sudo: + +\code +sudo XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR +DBUS_SESSION_BUS_ADDRESS=$DBUS_SESSION_BUS_ADDRESS softwarecontainer-agent -m +/path/to/application-manager/examples/softwarecontainer-plugin/service-manifest.d/ +\endcode + +On the Application Manager side, you need to activate the plugin by adding a line similar to the +one shown below, to one of your \c config.yaml files: + +\code +plugins: + container: [ "/path/to/libsoftwarecontainer-plugin.so" ] +\endcode + +To actually run applications within software containers, you have to add a container selection +configuration. For more information, see \l{Container Selection Configuration}. + +To simplify developing on the desktop, normally, you want your \c $HOME directory mounted into +the container in \c read-only mode. This way, you don't have to install your application manager +into \c{/usr/} after every build. This behavior only works, given that your build direcctory is +located somewhere in \c{$HOME}, otherwise the container won't see the appman-launcher-qml binary. +This behavior is \b not enabled by default; but you can activate it with the following lines in +one of your \c config.yaml files: + +\code +containers: + softwarecontainer: + bindMountHome: yes +\endcode + +*/ |