Implementing a Custom Application-Manager Example

Basic structure and starting point for a custom application-manager executable.

Screenshot

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 appman executable.

Walkthrough

Following is a breakdown of the minimal code needed for such a custom implementation:

#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

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 - QT_USE_NAMESPACE_AM will expand to the matching using statement.

    QCoreApplication::setApplicationName(qSL("Custom ApplicationManager"));
    QCoreApplication::setApplicationVersion("0.1");

Not application-manager specific, but having an application name and version set is generally a good idea.

    Logging::initialize(argc, argv);

We want the logging part of the application-manager initialized as early as possible, especially when dealing with DLT logging.

    Package::ensureCorrectLocale();

If you are using the installer part of the application-manager, this function needs to be called 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 libarchive with non-ASCII filenames).

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 fork of a child process which keeps the root privileges while the main process permanently drop them.

    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;
    }

This try block is the heart of the custom application-manager. You need to create a 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 DefaultConfiguration object. The rest of the function consists of parsing the configuration and then calling the relevant setup routines on the Main object. Since 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 MainBase typedef will circumvent that problem though.

Keep in mind that most functions in the application-manager will throw exceptions that are derived from std::exception, so a catch handler is a must.

© 2018 Pelagicore AG. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.