forked from AuroraMiddleware/gtk
0f24fddaf7
We need to adapt to both the change in the name of the project, and to the name change in the pkg-config file.
580 lines
20 KiB
XML
580 lines
20 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
|
|
]>
|
|
<refentry id="gtk-running">
|
|
<refmeta>
|
|
<refentrytitle>Running GTK Applications</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
<refmiscinfo>GTK Library</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>Running GTK Applications</refname>
|
|
<refpurpose>
|
|
How to run and debug your GTK application
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1>
|
|
<title>Running and debugging GTK Applications</title>
|
|
|
|
<refsect2>
|
|
<title>Environment variables</title>
|
|
|
|
<para>
|
|
GTK inspects a number of environment variables in addition to standard
|
|
variables like <envar>LANG</envar>, <envar>PATH</envar>, <envar>HOME</envar>
|
|
or <envar>DISPLAY</envar>; mostly to determine paths to look for certain
|
|
files. The <link linkend="x11-envar">X11</link>,
|
|
<link linkend="win32-envar">Windows</link> and
|
|
<link linkend="broadway-envar">Broadway</link> GDK backends use some
|
|
additional environment variables.
|
|
</para>
|
|
|
|
<formalpara id="GTK-Debug-Options">
|
|
<title><envar>GTK_DEBUG</envar></title>
|
|
|
|
<para>
|
|
Unless GTK has been configured with <option>--enable-debug=no</option>,
|
|
this variable can be set to a list of debug options, which cause GTK
|
|
to print out different types of debugging information.
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>actions</term>
|
|
<listitem><para>Actions and menu models</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>builder</term>
|
|
<listitem><para>GtkBuilder support</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>geometry</term>
|
|
<listitem><para>Size allocation</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>icontheme</term>
|
|
<listitem><para>Icon themes</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>keybindings</term>
|
|
<listitem><para>Keybindings</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>modules</term>
|
|
<listitem><para>Loading of modules</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>printing</term>
|
|
<listitem><para>Printing support</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>size-request</term>
|
|
<listitem><para>Size requests</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>text</term>
|
|
<listitem><para>Text widget internals</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>tree</term>
|
|
<listitem><para>Tree widget internals</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
A number of keys are influencing behavior instead of just logging:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>interactive</term>
|
|
<listitem><para>Open the <link linkend="interactive-debugging">interactive debugger</link></para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>no-css-cache</term>
|
|
<listitem><para>Bypass caching for CSS style properties</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>touchscreen</term>
|
|
<listitem><para>Pretend the pointer is a touchscreen device</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>baselines</term>
|
|
<listitem><para>Show baselines</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>updates</term>
|
|
<listitem><para>Visual feedback about window updates</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>resize</term>
|
|
<listitem><para>Highlight resizing widgets</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>layout</term>
|
|
<listitem><para>Show layout borders</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>snapshot</term>
|
|
<listitem><para>Include debug render nodes in the generated snapshots</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
The special value <literal>all</literal> can be used to turn on all
|
|
debug options. The special value <literal>help</literal> can be used
|
|
to obtain a list of all supported debug options.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara id="gtk-path">
|
|
<title><envar>GTK_PATH</envar></title>
|
|
|
|
<para>
|
|
Specifies a list of directories to search when GTK is looking for
|
|
dynamically loaded objects such as input method
|
|
modules and print backends. If the path to
|
|
the dynamically loaded object is given as an absolute path name,
|
|
then GTK loads it directly.
|
|
Otherwise, GTK goes in turn through the directories in <envar>GTK_PATH</envar>,
|
|
followed by the directory <filename>.gtk-4.0</filename> in the user's
|
|
home directory, followed by the system default directory,
|
|
which is <filename><replaceable>libdir</replaceable>/gtk-4.0/modules</filename>.
|
|
(If <envar>GTK_EXE_PREFIX</envar> is defined, <replaceable>libdir</replaceable> is
|
|
<filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
|
|
specified when GTK was configured, usually
|
|
<filename>/usr/lib</filename>, or
|
|
<filename>/usr/local/lib</filename>.)
|
|
For each directory in this list, GTK actually looks in a
|
|
subdirectory
|
|
<filename><replaceable>directory</replaceable>/<replaceable>version</replaceable>/<replaceable>host</replaceable>/<replaceable>type</replaceable></filename>
|
|
Where <replaceable>version</replaceable> is derived from the
|
|
version of GTK (use <literal>pkg-config
|
|
--variable=gtk_binary_version gtk4</literal> to determine this from a
|
|
script), <replaceable>host</replaceable> is the architecture on
|
|
which GTK was built. (use <literal>pkg-config
|
|
--variable=gtk_host gtk4</literal> to determine this from a
|
|
script), and <replaceable>type</replaceable> is a directory
|
|
specific to the type of modules; currently it can be
|
|
<literal>modules</literal>, <literal>engines</literal>,
|
|
<literal>immodules</literal>, <literal>filesystems</literal> or
|
|
<literal>printbackends</literal>, corresponding to the types of
|
|
modules mentioned above. Either <replaceable>version</replaceable>,
|
|
<replaceable>host</replaceable>, or both may be omitted. GTK looks
|
|
first in the most specific directory, then in directories with
|
|
fewer components.
|
|
The components of GTK_PATH are separated by the ':' character on
|
|
Linux and Unix, and the ';' character on Windows.
|
|
</para>
|
|
<warning>
|
|
Note that this environment variable is read by GTK 2.x and GTK 3.x too,
|
|
which makes it unsuitable for setting it system-wide (or session-wide),
|
|
since doing so will cause applications using different GTK versions
|
|
to see incompatible modules.
|
|
</warning>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><envar>GTK_IM_MODULE</envar></title>
|
|
|
|
<para>
|
|
Specifies an IM module to use in preference to the one determined
|
|
from the locale. If this isn't set and you are running on the system
|
|
that enables <literal>XSETTINGS</literal> and has a value in
|
|
<literal>Gtk/IMModule</literal>, that will be used for the default
|
|
IM module.
|
|
This also can be a colon-separated list of input-methods, which
|
|
GTK will try in turn until it finds one available on the system.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><envar>GTK_EXE_PREFIX</envar></title>
|
|
|
|
<para>
|
|
If set, GTK uses <filename>$GTK_EXE_PREFIX/lib</filename> instead of
|
|
the libdir configured when GTK was compiled.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><envar>GTK_DATA_PREFIX</envar></title>
|
|
|
|
<para>
|
|
If set, makes GTK use <filename>$GTK_DATA_PREFIX</filename>
|
|
instead of the prefix configured when GTK was compiled.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><envar>GTK_THEME</envar></title>
|
|
|
|
<para>
|
|
If set, makes GTK use the named theme instead of the theme
|
|
that is specified by the gtk-theme-name setting. This is intended
|
|
mainly for easy debugging of theme issues.
|
|
</para>
|
|
<para>
|
|
It is also possible to specify a theme variant to load, by appending
|
|
the variant name with a colon, like this: `GTK_THEME=Adwaita:dark`.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<para>
|
|
The following environment variables are used by GdkPixbuf, GDK or
|
|
Pango, not by GTK itself, but we list them here for completeness
|
|
nevertheless.
|
|
</para>
|
|
|
|
<formalpara>
|
|
<title><envar>GDK_PIXBUF_MODULE_FILE</envar></title>
|
|
|
|
<para>
|
|
Specifies the file listing the GdkPixbuf loader modules to load.
|
|
This environment variable overrides the default value
|
|
<filename><replaceable>libdir</replaceable>/gtk-4.0/4.0.0/loaders.cache</filename>
|
|
(<replaceable>libdir</replaceable> is the sysconfdir specified when
|
|
GTK was configured, usually <filename>/usr/local/lib</filename>.)
|
|
</para>
|
|
<para>
|
|
The <filename>loaders.cache</filename> file is generated by the
|
|
<command>gdk-pixbuf-query-loaders</command> utility.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara id="GDK-Debug-Options">
|
|
<title><envar>GDK_DEBUG</envar></title>
|
|
|
|
<para>
|
|
If GTK has been configured with <option>--enable-debug=yes</option>,
|
|
this variable can be set to a list of debug options, which cause GDK
|
|
to print out different types of debugging information.
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>cursor</term>
|
|
<listitem><para>Information about cursor objects (only win32)</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>eventloop</term>
|
|
<listitem><para>Information about event loop operation (mostly Quartz)</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>misc</term>
|
|
<listitem><para>Miscellaneous information</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>frames</term>
|
|
<listitem><para>Information about the frame clock</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>settings</term>
|
|
<listitem><para>Information about xsettings</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>selection</term>
|
|
<listitem><para>Information about selections</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>clipboard</term>
|
|
<listitem><para>Information about clipboards</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>dnd</term>
|
|
<listitem><para>Information about drag-and-drop</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>opengl</term>
|
|
<listitem><para>Information about OpenGL</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>vulkan</term>
|
|
<listitem><para>Information about Vulkan</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
A number of options affect behavior instead of logging:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>nograbs</term>
|
|
<listitem><para>Turn off all pointer and keyboard grabs</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>gl-disable</term>
|
|
<listitem><para>Disable OpenGL support</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>gl-software</term>
|
|
<listitem><para>Force OpenGL software rendering</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>gl-texture-rect</term>
|
|
<listitem><para>Use the OpenGL texture rectangle extension, if available</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>gl-legacy</term>
|
|
<listitem><para>Use a legacy OpenGL context</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>gl-gles</term>
|
|
<listitem><para>Use a GLES OpenGL context</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>vulkan-disable</term>
|
|
<listitem><para>Disable Vulkan support</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>vulkan-validate</term>
|
|
<listitem><para>Load the Vulkan validation layer, if available</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
The special value <literal>all</literal> can be used to turn on all
|
|
debug options. The special value <literal>help</literal> can be used
|
|
to obtain a list of all supported debug options.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara id="GSK-Debug-Options">
|
|
<title><envar>GSK_DEBUG</envar></title>
|
|
|
|
<para>
|
|
If GTK has been configured with <option>--enable-debug=yes</option>,
|
|
this variable can be set to a list of debug options, which cause GSK
|
|
to print out different types of debugging information.
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>renderer</term>
|
|
<listitem><para>General renderer information</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>cairo</term>
|
|
<listitem><para>cairo renderer information</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>opengl</term>
|
|
<listitem><para>OpenGL renderer information</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>shaders</term>
|
|
<listitem><para>Shaders</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>ssurface</term>
|
|
<listitem><para>Surfaces</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>vulkan</term>
|
|
<listitem><para>Vulkan renderer information</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>fallback</term>
|
|
<listitem><para>Information about fallbacks</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>glyphcache</term>
|
|
<listitem><para>Information about glyph caching</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
A number of options affect behavior instead of logging:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>diff</term>
|
|
<listitem><para>Show differences</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>geometry</term>
|
|
<listitem><para>Show borders</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>full-redraw</term>
|
|
<listitem><para>Force full redraws for every frame</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>sync</term>
|
|
<listitem><para>Sync after each frame</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>vulkan-staging-image</term>
|
|
<listitem><para>Use a staging image for Vulkan texture upload</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>vulkan-staging-buffer</term>
|
|
<listitem><para>Use a staging buffer for Vulkan texture upload</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
The special value <literal>all</literal> can be used to turn on all
|
|
debug options. The special value <literal>help</literal> can be used
|
|
to obtain a list of all supported debug options.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><envar>GDK_BACKEND</envar></title>
|
|
|
|
<para>
|
|
If set, selects the GDK backend to use. Selecting a backend requires that
|
|
GTK is compiled with support for that backend. The following backends can
|
|
be selected, provided they are included in the GDK libraries you are using:
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term>quartz</term>
|
|
<listitem><para>Selects the native Quartz backend</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>win32</term>
|
|
<listitem><para>Selects the native backend for Microsoft Windows</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>x11</term>
|
|
<listitem><para>Selects the native backend for connecting to X11 servers.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>broadway</term>
|
|
<listitem><para>Selects the Broadway backend for display in web browsers</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>wayland</term>
|
|
<listitem><para>Selects the Wayland backend for connecting to Wayland display servers</para></listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
Since 3.10, this environment variable can contain a comma-separated list
|
|
of backend names, which are tried in order. The list may also contain
|
|
a *, which means: try all remaining backends. The special value "help" can
|
|
be used to make GDK print out a list of all available backends.
|
|
For more information about selecting backends, see the gdk_display_manager_get() function.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><envar>GDK_VULKAN_DEVICE</envar></title>
|
|
|
|
<para>
|
|
This variable can be set to the index of a Vulkan device to override the
|
|
default selection of the device that is used for Vulkan rendering.
|
|
The special value <literal>list</literal> can be used to obtain a list
|
|
of all Vulkan devices.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><envar>GSK_RENDERER</envar></title>
|
|
|
|
<para>
|
|
If set, selects the GSK renderer to use. The following renderers can
|
|
be selected, provided they are included in the GTK library you are using
|
|
and the GDK backend supports them:
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term>help</term>
|
|
<listitem><para>Prints information about available options</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>broadway</term>
|
|
<listitem><para>Selects the Broadway-backend specific renderer</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>cairo</term>
|
|
<listitem><para>Selects the fallback Cairo renderer</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>gl</term>
|
|
<listitem><para>Selects the default OpenGL renderer</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>vulkan</term>
|
|
<listitem><para>Selects the Vulkan renderer</para></listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><envar>GTK_CSD</envar></title>
|
|
|
|
<para>
|
|
The default value of this environment variable is 1. If changed to 0, this
|
|
disables the default use of client-side decorations on GTK windows, thus
|
|
making the window manager responsible for drawing the decorations of
|
|
windows that do not have a custom titlebar widget.
|
|
</para>
|
|
<para>
|
|
CSD is always used for windows with a custom titlebar widget set, as the WM
|
|
should not draw another titlebar or other decorations around the custom one.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
|
|
|
|
<para>
|
|
GTK uses these environment variables to locate icon themes
|
|
and MIME information. For more information, see
|
|
<ulink url="https://freedesktop.org/Standards/icon-theme-spec">Icon Theme Specification</ulink>,
|
|
the <ulink url="https://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
|
|
and the <ulink url="https://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><envar>DESKTOP_STARTUP_ID</envar></title>
|
|
|
|
<para>
|
|
GTK uses this environment variable to provide startup notification
|
|
according to the <ulink url="https://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">Startup Notification Spec</ulink>.
|
|
Following the specification, GTK unsets this variable after reading
|
|
it (to keep it from leaking to child processes). So, if you need its
|
|
value for your own purposes, you have to read it before calling
|
|
gtk_init().
|
|
</para>
|
|
</formalpara>
|
|
|
|
</refsect2>
|
|
|
|
<refsect2 id="interactive-debugging">
|
|
<title>Interactive debugging</title>
|
|
|
|
<inlinegraphic fileref="inspector.png" format="PNG"></inlinegraphic>
|
|
|
|
<para>
|
|
GTK includes an interactive debugger, called the GTK Inspector, which
|
|
lets you explore the widget tree of any GTK application at runtime, as
|
|
well as tweak the theme and trigger visual debugging aids. You can
|
|
easily try out changes at runtime before putting them into the code.
|
|
</para>
|
|
<para>
|
|
Note that the GTK inspector can only show GTK internals. It can not
|
|
understand the application-specific logic of a GTK application. Also,
|
|
the fact that the GTK inspector is running in the application process
|
|
limits what it can do. It is meant as a complement to full-blown debuggers
|
|
and system tracing facilities such as DTrace, not as a replacement.
|
|
</para>
|
|
<para>
|
|
To enable the GTK inspector, you can use the Control-Shift-I or
|
|
Control-Shift-D keyboard shortcuts, or set the
|
|
<envar>GTK_DEBUG=interactive</envar> environment variable.
|
|
</para>
|
|
<para>
|
|
There are a few more environment variables that can be set to influence
|
|
how the inspector renders its UI. <envar>GTK_INSPECTOR_DISPLAY</envar> and
|
|
<envar>GTK_INSPECTOR_RENDERER</envar> determine the GDK display and
|
|
the GSK renderer that the inspector is using.
|
|
</para>
|
|
|
|
<para>
|
|
In some situations, it may be inappropriate to give users access to the
|
|
GTK inspector. The keyboard shortcuts can be disabled with the
|
|
`enable-inspector-keybinding` key in the `org.gtk.Settings.Debug`
|
|
GSettings schema.
|
|
</para>
|
|
|
|
</refsect2>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|