Pileus Git - ~andy/gtk/blob - docs/reference/gtk/running.sgml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
   4 ]>
   5 <refentry id="gtk-running">
   6 <refmeta>
   7 <refentrytitle>Running GTK+ Applications</refentrytitle>
   8 <manvolnum>3</manvolnum>
   9 <refmiscinfo>GTK Library</refmiscinfo>
  10 </refmeta>
  11
  12 <refnamediv>
  13 <refname>Running GTK+ Applications</refname>
  14 <refpurpose>
  15 How to run and debug your GTK+ application
  16 </refpurpose>
  17 </refnamediv>
  18
  19 <refsect1>
  20 <title>Running and debugging GTK+ Applications</title>
  21
  22 <refsect2>
  23 <title>Common commandline options</title>
  24
  25 <para>
  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.
  32 </para>
  33
  34 <formalpara>
  35 <title><systemitem>--gtk-module <replaceable>module</replaceable></systemitem></title>
  36
  37 <para>
  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.
  41 </para>
  42 </formalpara>
  43
  44 <formalpara>
  45 <title><systemitem>--g-fatal-warnings</systemitem></title>
  46
  47 <para>
  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
  51 warning that occurs.
  52 </para>
  53 </formalpara>
  54
  55 <formalpara>
  56 <title><systemitem>--gtk-debug <replaceable>options</replaceable></systemitem></title>
  57
  58 <para>
  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>
  61 environment variable. This option is only available if GTK+ has been
  62 configured with <option>--enable-debug=yes</option>.
  63 </para>
  64 </formalpara>
  65
  66 <formalpara>
  67 <title><systemitem>--gtk-no-debug <replaceable>options</replaceable></systemitem></title>
  68
  69 <para>
  70 A list of <link linkend="GTK-Debug-Options">debug options</link>
  71 to turn off. This option is only available if GTK+ has been configured with
  72 <option>--enable-debug=yes</option>.
  73 </para>
  74 </formalpara>
  75
  76 <para>
  77 The following options are really used by GDK, not by GTK+, but we
  78 list them here for completeness nevertheless.
  79 </para>
  80
  81 <formalpara>
  82 <title><systemitem>--class <replaceable>class</replaceable></systemitem></title>
  83
  84 <para>
  85 Sets the program class; see gdk_set_program_class().
  86 </para>
  87 </formalpara>
  88
  89 <formalpara>
  90 <title><systemitem>--name <replaceable>name</replaceable></systemitem></title>
  91
  92 <para>
  93 Sets the program name.
  94 </para>
  95 </formalpara>
  96
  97 <formalpara>
  98 <title><systemitem>--gdk-debug <replaceable>options</replaceable></systemitem></title>
  99
 100 <para>
 101 A list of <link linkend="GDK-Debug-Options">debug options</link>
 102 to turn on in addition to those specified in the <envar>GDK_DEBUG</envar>
 103 environment variable. This option is only available if GTK+ has been
 104 configured with <option>--enable-debug=yes</option>.
 105 </para>
 106 </formalpara>
 107
 108 <formalpara>
 109 <title><systemitem>--gdk-no-debug <replaceable>options</replaceable></systemitem></title>
 110
 111 <para>
 112 A list of <link linkend="GDK-Debug-Options">debug options</link>
 113 to turn off. This option is only available if GTK+ has been configured with
 114 <option>--enable-debug=yes</option>.
 115 </para>
 116 </formalpara>
 117
 118 </refsect2>
 119
 120 <refsect2>
 121 <title>Environment variables</title>
 122
 123 <para>
 124 GTK+ inspects a number of environment variables in addition to standard
 125 variables like <envar>LANG</envar>, <envar>PATH</envar>, <envar>HOME</envar>
 126 or <envar>DISPLAY</envar>; mostly to determine paths to look for certain
 127 files. The <link linkend="x11-envar">X11</link>,
 128 <link linkend="win32-envar">Windows</link> and
 129 <link linkend="fb-envar">Framebuffer</link> GDK backends use some
 130 additional environment variables.
 131 </para>
 132
 133 <formalpara id="GTK-Debug-Options">
 134   <title><envar>GTK_DEBUG</envar></title>
 135
 136   <para>
 137   If GTK+ has been configured with <option>--enable-debug=yes</option>,
 138   this variable can be set to a list of debug options, which cause GTK+
 139   to print out different types of debugging information.
 140   <variablelist>
 141     <varlistentry>
 142       <term>misc</term>
 143       <listitem><para>Miscellaneous information</para></listitem>
 144     </varlistentry>
 145     <varlistentry>
 146       <term>plugsocket</term>
 147       <listitem><para>Cross-process embedding</para></listitem>
 148     </varlistentry>
 149     <varlistentry>
 150       <term>text</term>
 151       <listitem><para>Text widget internals</para></listitem>
 152     </varlistentry>
 153     <varlistentry>
 154       <term>tree</term>
 155       <listitem><para>Tree widget internals</para></listitem>
 156     </varlistentry>
 157     <varlistentry>
 158       <term>updates</term>
 159       <listitem><para>Visual feedback about window updates</para></listitem>
 160     </varlistentry>
 161     <varlistentry>
 162       <term>keybindings</term>
 163       <listitem><para>Keybindings</para></listitem>
 164     </varlistentry>
 165     <varlistentry>
 166       <term>multihead</term>
 167       <listitem><para>Working on multiple displays</para></listitem>
 168     </varlistentry>
 169     <varlistentry>
 170       <term>modules</term>
 171       <listitem><para>Loading of modules</para></listitem>
 172     </varlistentry>
 173     <varlistentry>
 174       <term>geometry</term>
 175       <listitem><para>Size allocation</para></listitem>
 176     </varlistentry>
 177     <varlistentry>
 178       <term>icontheme</term>
 179       <listitem><para>Icon themes</para></listitem>
 180     </varlistentry>
 181     <varlistentry>
 182       <term>printing</term>
 183       <listitem><para>Printing support</para></listitem>
 184     </varlistentry>
 185     <varlistentry>
 186       <term>builder</term>
 187       <listitem><para>GtkBuilder support</para></listitem>
 188     </varlistentry>
 189
 190   </variablelist>
 191   The special value <literal>all</literal> can be used to turn on all
 192   debug options.
 193   </para>
 194 </formalpara>
 195
 196 <formalpara>
 197   <title><envar>GTK_MODULES</envar></title>
 198
 199   <para>
 200     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.
 201   </para>
 202   <warning>
 203     Note that this environment variable is read by GTK+ 2.x too,
 204     which may not have the same set of modules available for loading.
 205   </warning>
 206 </formalpara>
 207
 208 <formalpara id="gtk-path">
 209   <title><envar>GTK_PATH</envar></title>
 210
 211   <para>
 212     Specifies a list of directories to search when GTK+ is looking for
 213     dynamically loaded objects such as the modules specified by
 214     <envar>GTK_MODULES</envar>, theme engines, input method
 215     modules, file system backends and print backends. If the path to
 216     the dynamically loaded object is given as an absolute path name,
 217     then GTK+ loads it directly.
 218     Otherwise, GTK+ goes in turn through the directories in <envar>GTK_PATH</envar>,
 219     followed by the directory <filename>.gtk-3.0</filename> in the user's
 220     home directory, followed by the system default directory,
 221     which is <filename><replaceable>libdir</replaceable>/gtk-3.0/modules</filename>.
 222     (If <envar>GTK_EXE_PREFIX</envar> is defined, <replaceable>libdir</replaceable> is
 223     <filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
 224     specified when GTK+ was configured, usually
 225     <filename>/usr/lib</filename>, or
 226     <filename>/usr/local/lib</filename>.)
 227     For each directory in this list, GTK+ actually looks in a
 228     subdirectory
 229     <filename><replaceable>directory</replaceable>/<replaceable>version</replaceable>/<replaceable>host</replaceable>/<replaceable>type</replaceable></filename>
 230     Where <replaceable>version</replaceable> is derived from the
 231     version of GTK+ (use <literal>pkg-config
 232     --variable=gtk_binary_version gtk+-3.0</literal> to determine this from a
 233     script), <replaceable>host</replaceable> is the architecture on
 234     which GTK+ was built. (use <literal>pkg-config
 235     --variable=gtk_host gtk+-3.0</literal> to determine this from a
 236     script), and <replaceable>type</replaceable> is a directory
 237     specific to the type of modules; currently it can be
 238     <literal>modules</literal>, <literal>engines</literal>,
 239     <literal>immodules</literal>, <literal>filesystems</literal> or
 240     <literal>printbackends</literal>, corresponding to the types of
 241     modules mentioned above. Either <replaceable>version</replaceable>,
 242     <replaceable>host</replaceable>, or both may be omitted. GTK+ looks
 243     first in the most specific directory, then in directories with
 244     fewer components.
 245     The components of GTK_PATH are separated by the ':' character on
 246     Linux and Unix, and the ';' character on Windows.
 247   </para>
 248   <warning>
 249     Note that this environment variable is read by GTK+ 2.x too, which
 250     makes it unsuitable for setting it system-wide (or session-wide),
 251     since doing so will cause either GTK+ 2.x applications or GTK+ 3
 252     applications to see incompatible modules.
 253   </warning>
 254 </formalpara>
 255
 256 <formalpara>
 257   <title><envar>GTK_IM_MODULE</envar></title>
 258
 259   <para>
 260     Specifies an IM module to use in preference to the one determined
 261     from the locale. If this isn't set and you are running on the system
 262     that enables <literal>XSETTINGS</literal> and has a value in
 263     <literal>Gtk/IMModule</literal>, that will be used for the default
 264     IM module.
 265   </para>
 266 </formalpara>
 267
 268 <formalpara id="gtk-im-module-file">
 269   <title><envar>GTK_IM_MODULE_FILE</envar></title>
 270
 271   <para>
 272     Specifies the file listing the IM modules to load. This environment
 273     variable the default value
 274     <filename><replaceable>libdir</replaceable>/gtk-3.0/3.0.0/immodules.cache</filename>
 275     (<replaceable>libdir</replaceable> has the same meaning here as explained for <envar>GTK_PATH</envar>).
 276   </para>
 277   <para>
 278     The <filename>immodules.cache</filename> file is generated by the
 279     <command>gtk-query-immodules-3.0</command> utility.
 280   </para>
 281   <warning>
 282     Note that this environment variable is read by GTK+ 2.x too, which
 283     makes it unsuitable for setting it system-wide (or session-wide),
 284     since doing so will cause either GTK+ 2.x applications or GTK+ 3
 285     applications to see the wrong list of IM modules.
 286   </warning>
 287 </formalpara>
 288
 289 <formalpara>
 290   <title><envar>GTK_EXE_PREFIX</envar></title>
 291
 292   <para>
 293     If set, GTK+ uses <filename>$GTK_EXE_PREFIX/lib</filename> instead of
 294     the libdir configured when GTK+ was compiled.
 295   </para>
 296 </formalpara>
 297
 298 <formalpara>
 299   <title><envar>GTK_DATA_PREFIX</envar></title>
 300
 301   <para>
 302     If set, makes GTK+ use <filename>$GTK_DATA_PREFIX</filename>
 303     instead of the prefix configured when GTK+ was compiled.
 304   </para>
 305 </formalpara>
 306
 307 <para>
 308 The following environment variables are used by GdkPixbuf, GDK or
 309 Pango, not by GTK+ itself, but we list them here for completeness
 310 nevertheless.
 311 </para>
 312
 313 <formalpara>
 314   <title><envar>GDK_PIXBUF_MODULE_FILE</envar></title>
 315
 316   <para>
 317     Specifies the file listing the GdkPixbuf loader modules to load.
 318     This environment variable overrides the default value
 319     <filename><replaceable>libdir</replaceable>/gtk-3.0/3.0.0/loaders.cache</filename>
 320     (<replaceable>libdir</replaceable> is the sysconfdir specified when
 321     GTK+ was configured, usually <filename>/usr/local/lib</filename>.)
 322   </para>
 323   <para>
 324     The <filename>loaders.cache</filename> file is generated by the
 325     <command>gdk-pixbuf-query-loaders</command> utility.
 326   </para>
 327  </formalpara>
 328
 329 <formalpara id="GDK-Debug-Options">
 330   <title><envar>GDK_DEBUG</envar></title>
 331
 332   <para>
 333   If GTK+ has been configured with <option>--enable-debug=yes</option>,
 334   this variable can be set to a list of debug options, which cause GDK
 335   to print out different types of debugging information.
 336   <variablelist>
 337     <varlistentry>
 338       <term>misc</term>
 339       <listitem><para>Miscellaneous information</para></listitem>
 340     </varlistentry>
 341     <varlistentry>
 342       <term>events</term>
 343       <listitem><para>Show all events received by GDK</para></listitem>
 344     </varlistentry>
 345     <varlistentry>
 346       <term>dnd</term>
 347       <listitem><para>Information about drag-and-drop</para></listitem>
 348     </varlistentry>
 349     <varlistentry>
 350       <term>xim</term>
 351       <listitem><para>Information about XIM support</para></listitem>
 352     </varlistentry>
 353     <varlistentry>
 354       <term>nograbs</term>
 355       <listitem><para>Turn off all pointer and keyboard grabs</para></listitem>
 356     </varlistentry>
 357     <varlistentry>
 358       <term>multihead</term>
 359       <listitem><para>Information related to multiple screens</para></listitem>
 360     </varlistentry>
 361     <varlistentry>
 362       <term>xinerama</term>
 363       <listitem><para>Simulate a multi-monitor setup</para></listitem>
 364     </varlistentry>
 365     <varlistentry>
 366       <term>cursor</term>
 367       <listitem><para>Information about cursor objects (only win32)</para></listitem>
 368     </varlistentry>
 369     <varlistentry>
 370       <term>draw</term>
 371       <listitem><para>Information about drawing operations (only win32)</para></listitem>
 372     </varlistentry>
 373     <varlistentry>
 374       <term>eventloop</term>
 375       <listitem><para>Information about event loop operation (mostly Quartz)</para></listitem>
 376     </varlistentry>
 377
 378   </variablelist>
 379   The special value <literal>all</literal> can be used to turn on all
 380   debug options.
 381   </para>
 382 </formalpara>
 383
 384 <formalpara>
 385   <title><envar>GDK_RENDERING</envar></title>
 386
 387   <para>
 388     If set, selects the way how GDK creates similar surfaces. This affects both the
 389     functionality of the function gdk_window_create_similar_surface() as well as the
 390     way GDK creates backing surfaces for double buffering. The following values can
 391     be used:
 392     <variablelist>
 393
 394       <varlistentry>
 395         <term>similar</term>
 396         <listitem><para>Create similar surfaces to the window in use. This is the
 397           default behavior when the variable is not set.</para></listitem>
 398       </varlistentry>
 399
 400       <varlistentry>
 401         <term>image</term>
 402         <listitem><para>Always create image surfaces. This essentially turns off
 403           all hardware acceleration inside GTK.</para></listitem>
 404       </varlistentry>
 405
 406       <varlistentry>
 407         <term>recording</term>
 408         <listitem><para>Always create recording surfaces. This causes bare rendering
 409           to the backend without the creation of intermediate surfaces (Pixmaps in X)
 410           and will likely cause flicker.</para></listitem>
 411       </varlistentry>
 412
 413     </variablelist>
 414     All other values will be ignored and fall back to the default behavior. More
 415     values might be added in the future.
 416   </para>
 417 </formalpara>
 418
 419 <formalpara>
 420   <title><envar>GDK_BACKEND</envar></title>
 421
 422   <para>
 423     If set, selects the GDK backend to use. Selecting a backend requires that GTK is compiled
 424     with support for that backend. The following backends can be selected:
 425     <variablelist>
 426
 427       <varlistentry>
 428         <term>quartz</term>
 429         <listitem><para>Selects the native Quartz backend</para></listitem>
 430       </varlistentry>
 431
 432       <varlistentry>
 433         <term>win32</term>
 434         <listitem><para>Selects the native backend for Microsoft Windows</para></listitem>
 435       </varlistentry>
 436
 437       <varlistentry>
 438         <term>x11</term>
 439         <listitem><para>Selects the native backend for connecting to X11 servers.</para></listitem>
 440       </varlistentry>
 441
 442     </variablelist>
 443     For more information about selecting backends, see the gdk_display_manager_get() function.
 444   </para>
 445 </formalpara>
 446
 447 <formalpara>
 448   <title><envar>GDK_SYNCHRONIZE</envar></title>
 449
 450   <para>
 451     If set, GDK makes all X requests synchronously. This is a useful
 452     option for debugging, but it will slow down the performance considerably.
 453   </para>
 454 </formalpara>
 455
 456 <formalpara>
 457   <title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
 458
 459   <para>
 460     GTK+ uses these environment variables to locate icon themes
 461     and MIME information. For more information, see
 462     <ulink url="http://freedesktop.org/Standards/icon-theme-spec">Icon Theme Specification</ulink>,
 463     the <ulink url="http://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
 464     and the <ulink url="http://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
 465   </para>
 466 </formalpara>
 467
 468 <formalpara>
 469   <title><envar>DESKTOP_STARTUP_ID</envar></title>
 470
 471   <para>
 472     GTK+ uses this environment variable to provide startup notification
 473     according to the <ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">Startup Notification Spec</ulink>.
 474     Following the specification, GTK+ unsets this variable after reading
 475     it (to keep it from leaking to child processes). So, if you need its
 476     value for your own purposes, you have to read it before calling
 477     gtk_init().
 478   </para>
 479 </formalpara>
 480
 481 </refsect2>
 482
 483 </refsect1>
 484
 485 </refentry>