Implement a Custom Application Manager Example

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, if you need to have more control over the application's startup behavior, it may be necessary to implement a custom application manager executable.

If you still require this behavior, this example provides a starting point that you can build your custom implementation upon. Keep in mind, that this custom application manager executable needs a System UI to display something on the screen, just like the standard appman executable.

Linking against those application manager modules is prohibited by default to prevent potential problems with duplicate symbols coming from QML plugins. However here building against them is both intended and required, so we need to set the define AM_COMPILING_APPMAN:

target_compile_definitions(custom-appman PRIVATE AM_COMPILING_APPMAN)

The following is a breakdown of the minimal code necessary:

#include <QtAppManCommon/global.h>
#include <QtAppManCommon/logging.h>
#include <QtAppManMain/main.h>
#include <QtAppManMain/configuration.h>
#include <QtAppManPackage/packageutilities.h>
#include <QtAppManManager/sudo.h>

QT_USE_NAMESPACE_AM

The application manager is split into functional building blocks. These include statements pull in the basic set of classes that you need. To avoid possible clashes with QML plugins, all of the application manager's symbols are namespaced - QT_USE_NAMESPACE_AM expands to the equivalent using statement.

    QCoreApplication::setApplicationName(QStringLiteral("Custom Application Manager"));
    QCoreApplication::setApplicationVersion(QStringLiteral("0.1"));

Generally, it's a good idea to set an application name and version.

    Logging::initialize(argc, argv);

We want the application manager's logging part to be initialized as early as possible, especially when we are dealing with DLT logging.

    Sudo::forkServer(Sudo::DropPrivilegesPermanently);

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

    try {
        Main a(argc, argv);

        Configuration cfg;
        cfg.parseWithArguments(QCoreApplication::arguments());

        a.setup(&cfg);
        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 object, which is a class derived from QGuiApplication, plus a suitable configuration object. In this simple case, we use the application manager's default YAML parsing, so we instantiate a DefaultConfiguration object. The rest of the function involves parsing the configuration and then calling the relevant setup routines on the Main object.

Depending on your application manager's configuration, the Main object can be derived differently: with widgets, or standard. So, you need to know the correct base class for the exec() call. However, the MainBase typedef circumvents this problem.

Most functions in the application manager throw exceptions that are derived from std::exception, so a catch handler is compulsory.

Example project @ code.qt.io