2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
5 <refentry id="gtk-running" revision="10 Jan 2002">
7 <refentrytitle>Running GTK+ Applications</refentrytitle>
8 <manvolnum>3</manvolnum>
9 <refmiscinfo>GTK Library</refmiscinfo>
13 <refname>Running GTK+ Applications</refname>
15 How to run and debug your GTK+ application
20 <title>Running and debugging GTK+ Applications</title>
23 <title>Common commandline options</title>
26 All GTK+ applications support a number of standard commandline
27 options. These are removed from <literal>argv</literal> by gtk_init().
28 Modules may parse and remove further options. The
29 <link linkend="x11-cmdline">X11</link> and
30 <link linkend="win32-cmdline">Windows</link> GDK backends parse
31 some additional commandline options.
35 <title><systemitem>--gtk-module <replaceable>module</replaceable></systemitem></title>
38 A list of modules to load in addition to those specified in the
39 <envar>GTK_MODULES</envar> environment variable and the
40 <literal>gtk-modules</literal> setting.
45 <title><systemitem>--g-fatal-warnings</systemitem></title>
48 Make GTK+ abort on all warnings. This is useful to stop on the first
49 warning in a debugger, if your application is printing multiple
50 warnings. It's almost always best to start debugging with the first
56 <title><systemitem>--gtk-debug <replaceable>options</replaceable></systemitem></title>
59 A list of <link linkend="GTK-Debug-Options">debug options</link>
60 to turn on in addition to those specified in the <envar>GTK_DEBUG</envar>
62 This option is only available if GTK+ has been configured with
63 <option>--enable-debug=yes</option>.
68 <title><systemitem>--gtk-no-debug <replaceable>options</replaceable></systemitem></title>
71 A list of <link linkend="GTK-Debug-Options">debug options</link>
73 This option is only available if GTK+ has been configured with
74 <option>--enable-debug=yes</option>.
79 The following options are really used by GDK, not by GTK+, but we
80 list them here for completeness nevertheless.
84 <title><systemitem>--class <replaceable>class</replaceable></systemitem></title>
87 Sets the program class; see gdk_set_program_class().
92 <title><systemitem>--name <replaceable>name</replaceable></systemitem></title>
95 Sets the program name.
100 <title><systemitem>--gdk-debug <replaceable>options</replaceable></systemitem></title>
103 A list of <link linkend="GDK-Debug-Options">debug options</link>
104 to turn on in addition to those specified in the <envar>GDK_DEBUG</envar>
105 environment variable. This option is only available if GTK+ has been
106 configured with <option>--enable-debug=yes</option>.
111 <title><systemitem>--gdk-no-debug <replaceable>options</replaceable></systemitem></title>
114 A list of <link linkend="GDK-Debug-Options">debug options</link>
115 to turn off. This option is only available if GTK+ has been configured with
116 <option>--enable-debug=yes</option>.
123 <title>Environment variables</title>
126 GTK+ inspects a number of environment variables in addition to standard
127 variables like <envar>LANG</envar>, <envar>PATH</envar>, <envar>HOME</envar>
128 or <envar>DISPLAY</envar>; mostly to determine paths to look for certain
129 files. The <link linkend="x11-envar">X11</link>,
130 <link linkend="win32-envar">Windows</link> and
131 <link linkend="fb-envar">Framebuffer</link> GDK backends use some
132 additional environment variables.
135 <formalpara id="GTK-Debug-Options">
136 <title><envar>GTK_DEBUG</envar></title>
139 If GTK+ has been configured with <option>--enable-debug=yes</option>,
140 this variable can be set to a list of debug options, which cause GTK+
141 to print out different types of debugging information.
145 <listitem><para>Miscellaneous information</para></listitem>
148 <term>plugsocket</term>
149 <listitem><para>Cross-process embedding</para></listitem>
153 <listitem><para>Text widget internals</para></listitem>
157 <listitem><para>Tree widget internals</para></listitem>
161 <listitem><para>Visual feedback about window updates</para></listitem>
164 <term>keybindings</term>
165 <listitem><para>Keybindings</para></listitem>
168 <term>multihead</term>
169 <listitem><para>Working on multiple displays</para></listitem>
173 <listitem><para>Loading of modules</para></listitem>
176 <term>geometry</term>
177 <listitem><para>Size allocation</para></listitem>
180 <term>icontheme</term>
181 <listitem><para>Icon themes</para></listitem>
184 <term>printing</term>
185 <listitem><para>Printing support</para></listitem>
189 The special value <literal>all</literal> can be used to turn on all
195 <title><envar>GTK_MODULES</envar></title>
198 A list of modules to load. Note that GTK+ also allows to specify modules to load via a commandline option (<option>--gtk-module</option>) and with the <literal>gtk-modules</literal> setting.
203 <title><envar>GTK_PATH</envar></title>
206 Specifies a list of directories to search when GTK+ is looking for
207 dynamically loaded objects such as the modules specified by
208 <envar>GTK_MODULES</envar>, theme engines, input method
209 modules, file system backends and print backends. If the path to
210 the dynamically loaded object is given as an absolute path name,
211 then GTK+ loads it directly.
212 Otherwise, GTK+ goes in turn through the directories in GTK_PATH,
213 followed by the directory <filename>.gtk-2.0</filename> in the user's
214 home directory, followed by the system default directory,
215 which is <filename><replaceable>libdir</replaceable>/gtk-2.0/modules</filename>.
216 (If <envar>GTK_EXE_PREFIX</envar> is defined, <replaceable>libdir</replaceable> is
217 <filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
218 specified when GTK+ was configured, usually
219 <filename>/usr/lib</filename>, or
220 <filename>/usr/local/lib</filename>.)
221 For each directory in this list, GTK+ actually looks in a
223 <filename><replaceable>directory</replaceable>/<replaceable>version</replaceable>/<replaceable>host</replaceable>/<replaceable>type</replaceable></filename>
224 Where <replaceable>version</replaceable> is derived from the
225 version of GTK+ (use <literal>pkg-config
226 --variable=gtk_binary_version gtk+-2.0</literal> to determine this from a
227 script), <replaceable>host</replaceable> is the architecture on
228 which GTK+ was built. (use <literal>pkg-config
229 --variable=gtk_host gtk+-2.0</literal> to determine this from a
230 script), and <replaceable>type</replaceable> is a directory
231 specific to the type of modules; currently it can be
232 <literal>modules</literal>, <literal>engines</literal>,
233 <literal>immodules</literal>, <literal>filesystems</literal> or
234 <literal>printbackends</literal>, corresponding to the types of
235 modules mentioned above. Either <replaceable>version</replaceable>,
236 <replaceable>host</replaceable>, or both may be omitted. GTK+ looks
237 first in the most specific directory, then in directories with
239 The components of GTK_PATH are separated by the ':' character on
240 Linux and Unix, and the ';' character on Windows.
245 <title><envar>GTK_IM_MODULE</envar></title>
248 Specifies an IM module to use in preference to the one determined
249 from the locale. If this isn't set and you are running on the system
250 that enables <literal>XSETTINGS</literal> and has a value in
251 <literal>Gtk/IMModule</literal>, that will be used for the default
256 <formalpara id="im-module-file">
257 <title><envar>GTK_IM_MODULE_FILE</envar></title>
260 Specifies the file listing the IM modules to load. This environment
261 variable overrides the <literal>im_module_file</literal> specified in
262 the RC files, which in turn overrides the default value
263 <filename><replaceable>sysconfdir</replaceable>/gtk-2.0/gtk.immodules</filename>
264 (<replaceable>sysconfdir</replaceable> is the sysconfdir specified when GTK+ was configured,
265 usually <filename>/usr/local/etc</filename>.)
270 <title><envar>GTK2_RC_FILES</envar></title>
273 Specifies a list of RC files to parse instead of the default ones;
274 see <link linkend="gtk-Resource-Files">Resource Files</link>.
279 <title><envar>GTK_EXE_PREFIX</envar></title>
282 If set, GTK+ uses <filename>$GTK_EXE_PREFIX/lib</filename> instead of
283 the libdir configured when GTK+ was compiled.
288 <title><envar>GTK_DATA_PREFIX</envar></title>
291 If set, makes GTK+ use <filename>$GTK_DATA_PREFIX</filename>
292 instead of the prefix configured when GTK+ was compiled.
297 The following environment variables are used by GdkPixbuf, GDK or
298 Pango, not by GTK+ itself, but we list them here for completeness
303 <title><envar>GDK_PIXBUF_MODULE_FILE</envar></title>
306 Specifies the file listing the GdkPixbuf loader modules to load.
307 This environment variable overrides the default value
308 <filename><replaceable>sysconfdir</replaceable>/gtk-2.0/gdk-pixbuf.loaders</filename>
309 (<replaceable>sysconfdir</replaceable> is the sysconfdir specified when
310 GTK+ was configured, usually <filename>/usr/local/etc</filename>.)
314 <formalpara id="GDK-Debug-Options">
315 <title><envar>GDK_DEBUG</envar></title>
318 If GTK+ has been configured with <option>--enable-debug=yes</option>,
319 this variable can be set to a list of debug options, which cause GDK
320 to print out different types of debugging information.
324 <listitem><para>Miscellaneous information</para></listitem>
328 <listitem><para>Show all events received by GDK</para></listitem>
332 <listitem><para>Information about drag-and-drop</para></listitem>
336 <listitem><para>Information about XIM support</para></listitem>
339 The special value <literal>all</literal> can be used to turn on all
345 <title><envar>GDK_NATIVE_WINDOWS</envar></title>
348 If set, GDK creates all windows as native windows. This can help
349 applications that make assumptions about 1-1 correspondence between
350 GDK windows and X11 windows.
355 <title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
358 GTK+ uses these environment variables to locate icon themes
359 and MIME information. For more information, see
360 <ulink url="http://freedesktop.org/Standards/icon-theme-spec">Icon Theme Specification</ulink>,
361 the <ulink url="http://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
362 and the <ulink url="http://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.