Fix installation of the examples

- Only the project files and wrapper scripts were being installed
- They were being put directly into Qt's example dir. They should be grouped
  into a applicationmanager subdirectory there, similarly to what other
  modules do.

Task-number: AUTOSUITE-591
Change-Id: I1da6b28a8fe2e9210ad109309d30dfc1ad0d1e99
Reviewed-by: Robert Griebl <robert.griebl@pelagicore.com>

4 files changed, 216 insertions, 0 deletions

diff --git a/examples/applicationmanager/custom-appman/custom-appman.cpp b/examples/applicationmanager/custom-appman/custom-appman.cpp
new file mode 100644
index 00000000..decccd08
--- /dev/null
+++ b/examples/applicationmanager/custom-appman/custom-appman.cpp
@@ -0,0 +1,90 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 Pelagicore AG
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Pelagicore Application Manager.
+**
+** $QT_BEGIN_LICENSE:BSD-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.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+** SPDX-License-Identifier: BSD-3-Clause
+**
+****************************************************************************/
+
+#include <QtAppManCommon/global.h>
+#include <QtAppManCommon/logging.h>
+#include <QtAppManMain/main.h>
+#include <QtAppManMain/defaultconfiguration.h>
+#include <QtAppManPackage/package.h>
+#include <QtAppManInstaller/sudo.h>
+
+
+QT_USE_NAMESPACE_AM
+
+Q_DECL_EXPORT int main(int argc, char *argv[])
+{
+    QCoreApplication::setApplicationName(qSL("Custom ApplicationManager"));
+    QCoreApplication::setApplicationVersion("0.1");
+
+    Logging::initialize(argc, argv);
+
+    Package::ensureCorrectLocale();
+
+    try {
+        QStringList deploymentWarnings;
+        Sudo::forkServer(Sudo::DropPrivilegesPermanently, &deploymentWarnings);
+
+        Main a(argc, argv);
+
+        DefaultConfiguration cfg;
+        cfg.parse();
+
+        a.setup(&cfg, deploymentWarnings);
+        a.loadQml(cfg.loadDummyData());
+        a.showWindow(cfg.fullscreen() && !cfg.noFullscreen());
+
+        return MainBase::exec();
+    } catch (const std::exception &e) {
+        qCCritical(LogSystem) << "ERROR:" << e.what();
+        return 2;
+    }
+}
diff --git a/examples/applicationmanager/custom-appman/custom-appman.pro b/examples/applicationmanager/custom-appman/custom-appman.pro
new file mode 100644
index 00000000..e1ebab9e
--- /dev/null
+++ b/examples/applicationmanager/custom-appman/custom-appman.pro
@@ -0,0 +1,22 @@
+TEMPLATE = app
+TARGET   = custom-appman
+
+CONFIG += c++11 link_pkgconfig exceptions console
+CONFIG -= app_bundle qml_debug
+
+DEFINES += QT_MESSAGELOGCONTEXT
+
+QT = appman_main-private
+
+SOURCES = custom-appman.cpp
+
+OTHER_FILES += \
+    doc/src/*.qdoc \
+    doc/images/*.png \
+
+target.path = $$[QT_INSTALL_EXAMPLES]/applicationmanager/custom-appman
+INSTALLS += target
+
+example_sources.path = $$target.path
+example_sources.files = $SOURCES doc
+INSTALLS += example_sources
diff --git a/examples/applicationmanager/custom-appman/doc/images/custom-appman.png b/examples/applicationmanager/custom-appman/doc/images/custom-appman.png
new file mode 100644
index 00000000..64bae006
--- /dev/null
+++ b/examples/applicationmanager/custom-appman/doc/images/custom-appman.png
diff --git a/examples/applicationmanager/custom-appman/doc/src/custom-appman.qdoc b/examples/applicationmanager/custom-appman/doc/src/custom-appman.qdoc
new file mode 100644
index 00000000..5ea6d44f
--- /dev/null
+++ b/examples/applicationmanager/custom-appman/doc/src/custom-appman.qdoc
@@ -0,0 +1,104 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 Pelagicore AG
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Pelagicore 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 custom-appman
+\title Implementing a Custom Application-Manager Example
+\image custom-appman.png Screenshot
+\brief Basic structure and starting point for a custom application-manager executable.
+\ingroup applicationmanager-examples
+
+\section1 Introduction
+
+The application-manager is compiled as a self-contained executable that can be configured
+in large parts through the YAML based config file system and startup plugins. However it may still
+be necessary to implement a custom application-manager executable to have more influence over the
+startup behavior.
+
+\note Please note however, that all C++ classes in the application-manager modules are considered private
+API at the moment, so there are no compatibility guarantees at all.
+
+If you still desire to go down that road however, this example will provide you with an starting
+point to build your custom implementation upon.
+
+Keep in mind though, that this custom application-manager executable will need a System-UI to
+display something on the screen, just as the standard \c appman executable.
+
+\section1 Walkthrough
+
+Following is a breakdown of the minimal code needed for such a custom implementation:
+
+\quotefromfile custom-appman/custom-appman.cpp
+\skipto #include
+\printuntil QT_USE_NAMESPACE_AM
+
+The application-manager is split into functional building blocks/libraries. These includes will
+pull in the basic set of classes needed.
+In order to avoid possible clashes with QML plugins, all of the application-manager's symbols are
+namespaced - \c QT_USE_NAMESPACE_AM will expand to the matching \c using statement.
+
+\skipto QCoreApplication::setApplicationName
+\printuntil QCoreApplication::setApplicationVersion
+
+Not application-manager specific, but having an application name and version set is generally
+a good idea.
+
+\printline Logging::init
+
+We want the logging part of the application-manager initialized as early as possible, especially
+when dealing with DLT logging.
+
+\printline Package::ensure
+
+If you are using the installer part of the application-manager, this function needs to be called
+\e before the QApplication constructor to make sure your C locale is an UTF-8 variant (this is a
+requirement in order to get deterministic results when using \c libarchive with non-ASCII filenames).
+
+\printto try
+
+Again, for the installer part only, an additional setup step is necessary before running the
+QApplication constructor: if the executable is setuid-root, this call will \c fork of a child
+process which keeps the root privileges while the main process permanently drop them.
+
+\printuntil return 2
+\printline }
+
+This \c try block is the heart of the custom application-manager. You need to create a \c Main
+(which is a class derived from QGuiApplication) object plus a suitable configuration object: in
+this simple case we just use the application-manager's default YAML parsing, so we instantiate
+a \c DefaultConfiguration object.
+The rest of the function consists of parsing the configuration and then calling the relevant
+setup routines on the \c Main object.
+Since \c Main can be derived differently depending on your application-manager configuration
+(headless, with widgets or standard), you would need to know the correct base-class for the exec()
+call - the \c MainBase typedef will circumvent that problem though.
+
+Keep in mind that most functions in the application-manager will throw exceptions that are
+derived from \c std::exception, so a \c catch handler is a must.
+
+*/