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 <QtAppManMain/main.h>
#include <QtAppManMain/configuration.h>

using namespace Qt::StringLiterals;

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(u"Custom Application Manager"_s);
    QCoreApplication::setApplicationVersion(u"0.1"_s);

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

    std::unique_ptr<Main> a;
    std::unique_ptr<Configuration> cfg;

    try {
        a = std::make_unique<Main>(argc, argv, Main::InitFlag::ForkSudoServer

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 (or QApplication, if widgets support is enabled). In this case, we are supplying two init flags to the Main constructor:

The first init flag, ForkSudoServer, is useful for the installer part of the application manager: if the executable is setuid-root, this will implicitly fork off a child process, which does keep the root privileges while the main process permanently drops them.

The second init flag, InitializeLogging, sets up the application manager's logging part implicitly for us (this is especially useful when dealing with DLT logging).

Both parts could be initialized explicitly as well, but this is not needed in most cases.

                                                   | Main::InitFlag::InitializeLogging);
        cfg = std::make_unique<Configuration>();
        cfg->parseWithArguments(QCoreApplication::arguments());

        a->setup(cfg.get());
        a->loadQml();
        a->showWindow(cfg->fullscreen() && !cfg->noFullscreen());

    } catch (const std::exception &e) {
        qCritical() << "ERROR:" << e.what();
        return 2;
    }

The application manager needs a suitable configuration object. In this case, we use the application manager's default YAML parsing, so we instantiate a Configuration object. The rest of the function involves parsing the configuration and then calling the relevant setup routines on the Main object.

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