Отладка

Этот раздел включает документацию по отладке приложений Flatpak.

Debug packages

Before debugging, it is essential to install the debug packages used by the application. This can be done by:

$ flatpak install --include-sdk --include-debug $FLATPAK_ID

This will install the SDK, the Debug SDK and the Debug extension for the application.

Debug shell

A debugging environment can be created by starting a shell inside the sandbox:

$ flatpak run --command=sh --devel --filesystem=$(pwd) $FLATPAK_ID

This creates a sandbox for the application with the given ID and, instead of running the application, runs a shell inside the sandbox. The --devel option tells Flatpak to use the SDK as the runtime, which includes various debugging tools and it also adjusts the sandbox setup to enable debugging.

Также возможно получить оболочку внутри песочницы приложения без ее установки. Это делается с помощью параметра flatpak-builder’s --run:

$ flatpak-builder --run <build-dir> <manifest> sh

Это устанавливает песочницу, которая заполняется результатами сборки, найденными в каталоге сборки, и запускает оболочку внутри нее.

Using GDB in the sandbox

Note that Debug packages must be installed to get meaningful traces from GDB. Once inside the Debug shell to run the application with gdb

$ gdb /app/bin/<application-binary>

To pass arguments to the application:

$ gdb --args /app/bin/<application-binary> <arguments>
$ (gdb) run

A breakpoint can also be set for example on the main function and once it is reached the source code can be listed:

$ (gdb) break main
  (gdb) run
  (gdb) list

Once the bug is reproduced, if it is a crash it will automatically return to the gdb prompt. In case of a freeze pressing Ctrl+c will cause it to return to the gdb prompt. Now enable logging to a file (this will be saved in the working directory and the Flatpak needs filesystem access to that --filesystem=$(pwd)):

$ (gdb) set logging enabled on

Then to get the backtrace:

$ (gdb) bt full

Or for all threads, in case of a multi-threaded program:

$ (gdb) thread apply all backtrace

Note that gdb inside the sandbox cannot use debug symbols from host’s debuginfod servers.

Please also see the GDB user manual for a more complete overview on how to use GDB.

Getting stacktraces from a crash

If an application crashed and the system has coredumps and systemd-coredump enabled, a coredump will be logged. Get the PID from that coredump:

$ coredumpctl list

Now run flatpak-coredumpctl (this requires Debug packages to be installed):

$ flatpak-coredumpctl -m <PID> $FLATPAK_ID
(gdb) bt full

Using other debugging tools

org.freedesktop.Sdk also includes other debugging tools like Valgrind which is useful to find memory leaks. Once inside the Debug shell, it can be run with:

$ valgrind --leak-check=full --track-origins=yes --show-leak-kinds=all --log-file="valgrind.log" /app/bin/<application-binary>

Strace can be useful to check what an application is doing. For example, to trace openat(), read() calls:

$ strace -e trace=openat,read -o strace.log -f /app/bin/<application-binary>

Perf requires access to --filesystem=/sys to run:

$ flatpak run --command=perf --filesystem=/sys --filesystem=$(pwd) --devel $FLATPAK_ID record -v -- <command>

Creating a Debug extension

Like many other packaging systems, Flatpak separates bulky debug information from regular content and ships it separately, in a Debug extension.

When an application is built, flatpak-builder automatically creates a Debug extension. This can be disabled with the no-debuginfo option.

To install the Debug extension created locally, pass --install to flatpak-builder which will set up a new remote for the build. The remotes available can be checked with:

$ flatpak remotes --columns=name,url

Then install the Debug extension from that remote:

$ flatpak install foo-origin $FLATPAK_ID.Debug

Переопределение разрешений песочницы

Иногда бывает полезно иметь дополнительные разрешения в песочнице при отладке. Этого можно добиться с помощью различных параметров песочницы, которые принимает команда запуска. Например:

$ flatpak run --devel --command=sh --system-talk-name=org.freedesktop.login1 <application-id>

Эта команда запускает оболочку в изолированной программной среде для данного приложения, предоставляя ему доступ к системной шине с именем шины, принадлежащим logind.

Проверка разрешений портала

Flatpak имеет ряд команд, позволяющих управлять разрешениями портала для приложений.

Чтобы увидеть все права доступа приложения к порталу, используйте:

$ flatpak permission-show <application-id>

Чтобы сбросить все права доступа приложения к порталу, используйте:

$ flatpak permission-reset <application-id>

Взаимодействие с запущенными песочницами

Вы можете увидеть все приложения, которые в настоящее время работают в песочницах Flatpak (начиная с версии 1.2):

$ flatpak ps

И, при необходимости, вы можете прекратить его принудительно (начиная с версии 1.2):

$ flatpak kill <application-id>

Audit session or system bus traffic

A --socket=session-bus or a --socket=system-bus permission must not be present for the logging to work.

Session or system bus traffic can be audited by passing --log-session-bus and --log-system-bus respectively to flatpak run:

flatpak run --log-session-bus <application-id>

This can be useful to figure out the bus names used by an application and the corresponding --talk-name or --own-name permissions required:

flatpak --log-session-bus run <application-id>| grep '(required 1)'