debugging: Add info on installing GL debug extension

docs/debugging.rst

@@ -15,6 +15,22 @@ the application. This can be done by::
 This will install the SDK, the Debug SDK and the Debug extension for
 the application.
 
+If it's a crash in the graphics stack, the GL debug extension will also
+be needed.
+
+First, note down the runtime branch used by the application::
+
+  $ flatpak info --show-runtime $FLATPAK_ID
+  org.freedesktop.Platform/x86_64/24.08
+
+In the above example it is the Freedesktop SDK and the branch is
+``24.08``. Then install the ``GL.debug`` extension for the above branch::
+
+  $ flatpak install org.freedesktop.Platform.{GL,GL32}.Debug.default//24.08
+
+The same process should be followed for any extension or baseapp used
+by the app.
+
 Debug shell
 -----------
 

po/de/LC_MESSAGES/debugging.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version:  Flatpak\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2025-02-05 01:10+0530\n"
+"POT-Creation-Date: 2025-02-18 06:55+0530\n"
 "PO-Revision-Date: 2018-05-20 10:36-0400\n"
 "Last-Translator: Copied by Zanata <[email protected]>\n"
 "Language: de\n"
@@ -17,7 +17,7 @@ msgstr ""
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=utf-8\n"
 "Content-Transfer-Encoding: 8bit\n"
-"Generated-By: Babel 2.16.0\n"
+"Generated-By: Babel 2.17.0\n"
 
 #: ../../debugging.rst:2
 msgid "Debugging"
@@ -43,17 +43,39 @@ msgid ""
 "application."
 msgstr ""
 
-#: ../../debugging.rst:19
-msgid "Debug shell"
+#: ../../debugging.rst:18
+msgid ""
+"If it's a crash in the graphics stack, the GL debug extension will also "
+"be needed."
 msgstr ""
 
 #: ../../debugging.rst:21
+msgid "First, note down the runtime branch used by the application::"
+msgstr ""
+
+#: ../../debugging.rst:26
+msgid ""
+"In the above example it is the Freedesktop SDK and the branch is "
+"``24.08``. Then install the ``GL.debug`` extension for the above branch::"
+msgstr ""
+
+#: ../../debugging.rst:31
+msgid ""
+"The same process should be followed for any extension or baseapp used by "
+"the app."
+msgstr ""
+
+#: ../../debugging.rst:35
+msgid "Debug shell"
+msgstr ""
+
+#: ../../debugging.rst:37
 msgid ""
 "A debugging environment can be created by starting a shell inside the "
 "sandbox::"
 msgstr ""
 
-#: ../../debugging.rst:26
+#: ../../debugging.rst:42
 msgid ""
 "This creates a sandbox for the application with the given ID and, instead"
 " of running the application, runs a shell inside the sandbox. The "
@@ -62,41 +84,41 @@ msgid ""
 " enable debugging."
 msgstr ""
 
-#: ../../debugging.rst:32
+#: ../../debugging.rst:48
 msgid ""
 "It is also possible to get a shell inside an application sandbox without "
 "having to install it. This is done using ``flatpak-builder``'s ``--run`` "
 "option::"
 msgstr ""
 
-#: ../../debugging.rst:38
+#: ../../debugging.rst:54
 msgid ""
 "This sets up a sandbox that is populated with the build results found in "
 "the build directory, and runs a shell inside it."
 msgstr ""
 
-#: ../../debugging.rst:42
+#: ../../debugging.rst:58
 msgid "Using GDB in the sandbox"
 msgstr ""
 
-#: ../../debugging.rst:44
+#: ../../debugging.rst:60
 msgid ""
 "Note that :ref:`debugging:Debug packages` must be installed to get "
 "meaningful traces from GDB. Once inside the :ref:`debugging:Debug shell` "
 "to run the application with ``gdb`` ::"
 msgstr ""
 
-#: ../../debugging.rst:50
+#: ../../debugging.rst:66
 msgid "To pass arguments to the application::"
 msgstr ""
 
-#: ../../debugging.rst:55
+#: ../../debugging.rst:71
 msgid ""
 "A breakpoint can also be set for example on the ``main`` function and "
 "once it is reached the source code can be listed::"
 msgstr ""
 
-#: ../../debugging.rst:62
+#: ../../debugging.rst:78
 msgid ""
 "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 "
@@ -105,169 +127,169 @@ msgid ""
 " that ``--filesystem=$(pwd)``)::"
 msgstr ""
 
-#: ../../debugging.rst:70
+#: ../../debugging.rst:86
 msgid "Then to get the backtrace::"
 msgstr ""
 
-#: ../../debugging.rst:74
+#: ../../debugging.rst:90
 msgid "Or for all threads, in case of a multi-threaded program::"
 msgstr ""
 
-#: ../../debugging.rst:78
+#: ../../debugging.rst:94
 msgid ""
 "Note that ``gdb`` inside the sandbox cannot use debug symbols from host's"
 " `debuginfod servers <https://sourceware.org/elfutils/Debuginfod.html>`_."
 msgstr ""
 
-#: ../../debugging.rst:81
+#: ../../debugging.rst:97
 msgid ""
 "Please also see the `GDB user manual "
 "<https://sourceware.org/gdb/current/onlinedocs/gdb.html/>`_ for a more "
 "complete overview on how to use GDB."
 msgstr ""
 
-#: ../../debugging.rst:85
+#: ../../debugging.rst:101
 msgid "Getting stacktraces from a crash"
 msgstr ""
 
-#: ../../debugging.rst:87
+#: ../../debugging.rst:103
 msgid ""
 "If an application crashed and the system has coredumps and `systemd-"
 "coredump <https://www.freedesktop.org/software/systemd/man/latest"
 "/systemd-coredump.html#>`_ enabled, a coredump will be logged. Get the "
 "``PID`` from that coredump::"
 msgstr ""
 
-#: ../../debugging.rst:93
+#: ../../debugging.rst:109
 msgid ""
 "Now run ``flatpak-coredumpctl`` (this requires :ref:`debugging:Debug "
 "packages` to be installed)::"
 msgstr ""
 
-#: ../../debugging.rst:100
+#: ../../debugging.rst:116
 msgid "Using other debugging tools"
 msgstr ""
 
-#: ../../debugging.rst:102
+#: ../../debugging.rst:118
 msgid ""
 "``org.freedesktop.Sdk`` also includes other debugging tools like "
 "`Valgrind <https://valgrind.org/>`_ which is useful to find memory leaks."
 " Once inside the :ref:`debugging:Debug shell`, it can be run with::"
 msgstr ""
 
-#: ../../debugging.rst:108
+#: ../../debugging.rst:124
 msgid ""
 "`Strace <https://strace.io/>`_ can be useful to check what an application"
 " is doing. For example, to trace ``openat(), read()`` calls::"
 msgstr ""
 
-#: ../../debugging.rst:113
+#: ../../debugging.rst:129
 msgid ""
 "`Perf <https://perfwiki.github.io/main/>`_ requires access to "
 "``--filesystem=/sys`` to run::"
 msgstr ""
 
-#: ../../debugging.rst:119
+#: ../../debugging.rst:135
 msgid "Creating a Debug extension"
 msgstr ""
 
-#: ../../debugging.rst:121
+#: ../../debugging.rst:137
 msgid ""
 "Like many other packaging systems, Flatpak separates bulky debug "
 "information from regular content and ships it separately, in a Debug  "
 "extension."
 msgstr ""
 
-#: ../../debugging.rst:124
+#: ../../debugging.rst:140
 msgid ""
 "When an application is built, ``flatpak-builder`` automatically creates a"
 " Debug extension. This can be disabled with the ``no-debuginfo`` option."
 msgstr ""
 
-#: ../../debugging.rst:128
+#: ../../debugging.rst:144
 msgid ""
 "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::"
 msgstr ""
 
-#: ../../debugging.rst:134
+#: ../../debugging.rst:150
 msgid "Then install the Debug extension from that remote::"
 msgstr ""
 
-#: ../../debugging.rst:139
+#: ../../debugging.rst:155
 msgid "Overriding sandbox permissions"
 msgstr ""
 
-#: ../../debugging.rst:141
+#: ../../debugging.rst:157
 msgid ""
 "It is sometimes useful to have extra permissions in a sandbox when "
 "debugging. This can be achieved using the various sandbox options that "
 "are accepted by the run command. For example::"
 msgstr ""
 
-#: ../../debugging.rst:147
+#: ../../debugging.rst:163
 msgid ""
 "This command runs a shell in the sandbox for the given application, "
 "granting it system bus access to the bus name owned by logind."
 msgstr ""
 
-#: ../../debugging.rst:151
+#: ../../debugging.rst:167
 msgid "Inspecting portal permissions"
 msgstr ""
 
-#: ../../debugging.rst:153
+#: ../../debugging.rst:169
 msgid ""
 "Flatpak has a number of commands that allow to manage portal permissions "
 "for applications."
 msgstr ""
 
-#: ../../debugging.rst:156
+#: ../../debugging.rst:172
 msgid "To see all portal permissions of an application, use::"
 msgstr ""
 
-#: ../../debugging.rst:160
+#: ../../debugging.rst:176
 msgid "To reset all portal permissions of an application, use::"
 msgstr ""
 
-#: ../../debugging.rst:166
+#: ../../debugging.rst:182
 msgid "Interacting with running sandboxes"
 msgstr ""
 
-#: ../../debugging.rst:168
+#: ../../debugging.rst:184
 msgid ""
 "You can see all the apps that are currently running in Flatpak sandboxes "
 "(since 1.2)::"
 msgstr ""
 
-#: ../../debugging.rst:173
+#: ../../debugging.rst:189
 msgid "And, if you need to, you can terminate one by force (since 1.2)::"
 msgstr ""
 
-#: ../../debugging.rst:178
+#: ../../debugging.rst:194
 msgid "Audit session or system bus traffic"
 msgstr ""
 
-#: ../../debugging.rst:180
+#: ../../debugging.rst:196
 msgid ""
 "A ``--socket=session-bus`` or a ``--socket=system-bus`` permission must "
 "not be present for the logging to work."
 msgstr ""
 
-#: ../../debugging.rst:183
+#: ../../debugging.rst:199
 msgid ""
 "Session bus traffic can be audited by passing ``--log-session-bus`` to "
 "``flatpak run``::"
 msgstr ""
 
-#: ../../debugging.rst:188
+#: ../../debugging.rst:204
 msgid ""
 "This can be useful to figure out the bus names used by an application and"
 " the corresponding ``--talk-name`` or ``--own-name`` permissions "
 "required::"
 msgstr ""
 
-#: ../../debugging.rst:194
+#: ../../debugging.rst:210
 msgid ""
 "Similarly, system bus traffic can be audited by passing ``--log-system-"
 "bus`` to ``flatpak run``. This also requires a system bus name to be "