Troubleshooting

This section lists possible issues you may encounter while using QtApplicationManager and how to solve them.

What does Unknown CMake command "qt_am_add_systemui_wrapper" mean?

The most common reason for this error message is that you installed the application manager via the Qt Installer, but your Linux system is lacking the libwayland-dev development package. See here for more information.

How do I check whether my application manager instance is running in multi-process mode?

Start the Application manager with the --verbose argument and verify that you see WindowManager: running in Wayland mode in the output. Alternatively, start an application and make sure that you can see at least one appman-launcher-qml process running.

How do I find out why my application manager instance doesn't support multi-process mode?

Check the "Application Manager configuration" summary, which is visible at the end of the configuration step. It's possible that your Qt installation doesn't come with the QtCompositor module.

My applications are running slowly within the application manager. What are some possible solutions?

Verify if your applications are running with hardware acceleration.

How do I find out if my applications use hardware acceleration?

Run the appman, with the environment variable QSG_INFO=1. When you start an application, you should see a similar output:

[DBG  | qt.scenegraph.general | c.p.music] Using sg animation driver
[DBG  | qt.scenegraph.general | c.p.music] Animation Driver: using vsync: 16.95 ms
[DBG  | qt.scenegraph.general | c.p.music] texture atlas dimensions: 1024x1024
[DBG  | qt.scenegraph.general | c.p.music] R/G/B/A Buffers:    8 8 8 8
[DBG  | qt.scenegraph.general | c.p.music] Depth Buffer:       24
[DBG  | qt.scenegraph.general | c.p.music] Stencil Buffer:     8
[DBG  | qt.scenegraph.general | c.p.music] Samples:            0
[DBG  | qt.scenegraph.general | c.p.music] GL_VENDOR:          VMware, Inc.
[DBG  | qt.scenegraph.general | c.p.music] GL_RENDERER:        llvmpipe (LLVM 5.0, 256 bits)
[DBG  | qt.scenegraph.general | c.p.music] GL_VERSION:         3.0 Mesa 17.3.0

If GL_RENDERER is llvmpipe, you're using software rendering for your Wayland clients.

How do I enable hardware acceleration?

This depends on your hardware and operating system:

You need to make sure that you have the correct drivers installed:

• For NVIDIA on Ubuntu or Debian you need nvidia-egl-wayland-icd
• For Intel on Ubuntu or Debian you need libwayland-egl1-mesa

On desktop systems, make sure your Qt is configured to use at least OpenGL ES2/ES3 instead of Desktop OpenGL. In Qt's configure summary, verify that you see the following line:

OpenGL ES 2.0 ........................ yes

You can force Qt to use OpenGL ES2 by using the --opengl es2 configure option.

Additionally, you also need to make sure that the wayland-egl integration plugin is built. If the plugin built successfully, you should have the following file: <QT_DIR>/plugins/wayland-graphics-integration-client/libqt-plugin-wayland-egl.so

If that file isn't available, check QtWayland's configure summary and make sure this plugin is built.

My applications are crashing immediately within the application manager. What are some possible solutions?

Your system setup might not allow Wayland clients to use OpenGL. In this case both the application manager and the QML application launcher output a critical log message if hardware accelerated rendering is not possible for applications.

Make sure to enable hardware acceleration.

You can also force software rendering by setting the environment variable $QT_QUICK_BACKEND to software, but only if your applications aren't using OpenGL features explicitly. For example, shaders.

Why does the appman-controller not see any of my appman instances?

Most likely your appman-controller and the appman instances are running under different Unix user accounts on your target device. If your shell user is root, but the appman is running under an unprivileged account, you can use this setup: rename the appman-controller executable to appman-controller.bin and save the following script as appman-controller in place of the original executable. Don't forget to replace <your-appman-user> with the actual user name.

#!/bin/sh

APPMAN_USER="<your-appman-user>"
APPMAN_CONTROLLER="`dirname $0`/appman-controller.bin"

CURRENT_UID=`id -u`
APPMAN_UID=`id -u $APPMAN_USER`

if [ "$CURRENT_UID" = "$APPMAN_UID" ]; then
  "$APPMAN_CONTROLLER" "$@"
elif [ "$CURRENT_UID" = "0" ]; then
  su "$APPMAN_USER" -s "$APPMAN_CONTROLLER" -- "$@"
else
  echo >&2 "The current user (`id -un`) is neither the appman user ($APPMAN_USER) nor root."
  exit 2
fi

How can I reduce RAM usage?

Transparent Huge Pages

If the Linux kernel has transparent huge pages (THP) enabled system-wide (always in /sys/kernel/mm/transparent_hugepage/enabled), anonymous memory is backed by 2 MB pages instead of 4 KB pages whenever possible. A partially used heap then occupies a lot more physical RAM than it actually needs. Since every application in multi-process mode is a separate process, this overhead adds up quickly.

You can change the THP policy for the application manager processes by setting the environment variable AM_TRANSPARENT_HUGE_PAGES to one of these values:

The policy is inherited by all child processes, so setting the variable when starting the System UI also covers all applications started by it. If you only want to change the policy for the applications, but not for the System UI, set the variable for specific runtimes via their environmentVariables in the runtime configuration instead.

If a policy was requested, the resulting state is logged in the am.system logging category, together with a warning if the policy could not be applied. You can also check the state of any process via the THP_enabled field in /proc/<pid>/status, and the amount of memory backed by huge pages via the AnonHugePages field in /proc/<pid>/smaps_rollup.

If you are using systemd 260 or newer, its MemoryTHP service setting provides similar functionality, but a policy set this way cannot be reset by the processes in that service.