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

   1 <refentry id="gtk-running" revision="10 Jan 2002">
   2 <refmeta>
   3 <refentrytitle>Running GTK+ Applications</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>GTK Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Running GTK+ Applications</refname>
  10 <refpurpose>
  11 How to run and debug your GTK+ application
  12 </refpurpose>
  13 </refnamediv>
  14
  15 <refsect1>
  16 <title>Running and debugging GTK+ Applications</title>
  17
  18 <refsect2>
  19 <title>Common commandline options</title>
  20
  21 <para>
  22 All GTK+ applications support a number of standard commandline
  23 options. These are removed from <literal>argv</literal> by <link
  24 linkend="gtk-init">gtk_init()</link>. Modules may parse and remove
  25 further options.
  26 </para>
  27
  28 <formalpara>
  29 <title><systemitem>--gtk-module <replaceable>module</replaceable></systemitem></title>
  30
  31 <para>
  32 A list of modules to load in addition to those specified in the
  33 <envar>GTK_MODULES</envar> environment variable.
  34 </para>
  35 </formalpara>
  36
  37 <formalpara>
  38 <title><systemitem>--g-fatal-warnings</systemitem></title>
  39
  40 <para>
  41 Make GTK+ abort on all warnings. This is useful to stop on the first
  42 warning in a debugger, if your application is printing multiple
  43 warnings.  It's almost always best to start debugging with the first
  44 warning that occurs.
  45 </para>
  46 </formalpara>
  47
  48 <formalpara>
  49 <title><systemitem>--gtk-debug <replaceable>options</replaceable></systemitem></title>
  50
  51 <para>
  52 A list of <link linkend="GTK-Debug-Options">debug options</link>
  53 to turn on in addition to those specified in the <envar>GTK_DEBUG</envar>
  54 environment variable.
  55 This option is only available if GTK+ has been configured with
  56 <option>--enable-debug=yes</option>.
  57 </para>
  58 </formalpara>
  59
  60 <formalpara>
  61 <title><systemitem>--gtk-no-debug <replaceable>options</replaceable></systemitem></title>
  62
  63 <para>
  64 A list of <link linkend="GTK-Debug-Options">debug options</link>
  65 to turn off.
  66 This option is only available if GTK+ has been configured with
  67 <option>--enable-debug=yes</option>.
  68 </para>
  69 </formalpara>
  70
  71 <para>
  72 The following options are really used by GDK, not by GTK+, but we
  73 list them here for completeness nevertheless.
  74 </para>
  75
  76 <formalpara>
  77 <title><systemitem>--class <replaceable>class</replaceable></systemitem></title>
  78
  79 <para>
  80 Sets the program class; see gdk_set_program_class().
  81 </para>
  82 </formalpara>
  83
  84 <formalpara>
  85 <title><systemitem>--name <replaceable>name</replaceable></systemitem></title>
  86
  87 <para>
  88 Sets the program name.
  89 </para>
  90 </formalpara>
  91
  92 <formalpara>
  93 <title><systemitem>--gdk-debug <replaceable>options</replaceable></systemitem></title>
  94
  95 <para>
  96 A list of <link linkend="GDK-Debug-Options">debug options</link>
  97 to turn on in addition to those
  98 specified in the <envar>GDK_DEBUG</envar> environment variable.
  99 This option is only available if GTK+ has been configured with
 100 <option>--enable-debug=yes</option>.
 101 </para>
 102 </formalpara>
 103
 104 <formalpara>
 105 <title><systemitem>--gdk-no-debug <replaceable>options</replaceable></systemitem></title>
 106
 107 <para>
 108 A list of <link linkend="GDK-Debug-Options">debug options</link>
 109 to turn off.
 110 This option is only available if GTK+ has been configured with
 111 <option>--enable-debug=yes</option>.
 112 </para>
 113 </formalpara>
 114
 115 <formalpara>
 116 <title><systemitem>--display <replaceable>display</replaceable></systemitem></title>
 117
 118 <para>
 119 The name of the X display to open instead of the one specified
 120 in the <envar>DISPLAY</envar>.
 121 This option is only available if GTK+ has been configured with
 122 <option>--gdk-target=x11</option>.
 123 </para>
 124 </formalpara>
 125
 126 <formalpara>
 127 <title><systemitem>--sync</systemitem></title>
 128
 129 <para>
 130 Makes all X requests synchronously. This is a useful option for
 131 debugging, but it will slow down the performance considerably.
 132 This option is only available if GTK+ has been configured with
 133 <option>--gdk-target=x11</option>.
 134 </para>
 135 </formalpara>
 136
 137 <formalpara>
 138 <title><systemitem>--gxid-host <replaceable>host</replaceable></systemitem></title>
 139
 140 <para>
 141 The host to contact the <application>gxid</application> daemon on; overwrites
 142 the <link linkend="GXID"><envar>GXID_HOST</envar></link> environment variable.
 143 This option is only available if GTK+ has been configured with
 144 <option>--gdk-target=x11</option>.
 145 </para>
 146 </formalpara>
 147
 148 <formalpara>
 149 <title><systemitem>--gxid-port <replaceable>port</replaceable></systemitem></title>
 150
 151 <para>
 152 The port for the connection to <application>gxid</application>; overwrites
 153 the <link linkend="GXID"><envar>GXID_PORT</envar></link> environment variable.
 154 This option is only available if GTK+ has been configured with
 155 <option>--gdk-target=x11</option>.
 156 </para>
 157 </formalpara>
 158
 159 </refsect2>
 160
 161 <refsect2>
 162 <title>Environment variables</title>
 163
 164 <para>
 165 GTK+ inspects a number of environment variables in addition to standard
 166 variables like <envar>LANG</envar>, <envar>PATH</envar>, <envar>HOME</envar>
 167 or <envar>DISPLAY</envar>; mostly to determine paths to look for certain files.
 168 </para>
 169
 170 <formalpara id="GTK-Debug-Options">
 171   <title><envar>GTK_DEBUG</envar></title>
 172
 173   <para>
 174   If GTK+ has been configured with <option>--enable-debug=yes</option>,
 175   this variable can be set to a list of debug options, which cause GTK+
 176   to print out different types of debugging information.
 177   <variablelist>
 178     <varlistentry>
 179       <term>misc</term>
 180       <listitem><para>Miscellaneous information</para></listitem>
 181     </varlistentry>
 182     <varlistentry>
 183       <term>text</term>
 184       <listitem><para>Information about text widget internals</para></listitem>
 185     </varlistentry>
 186     <varlistentry>
 187       <term>tree</term>
 188       <listitem><para>Information about tree widget internals</para></listitem>
 189     </varlistentry>
 190     <varlistentry>
 191       <term>updates</term>
 192       <listitem><para>Visual feedback about window updates</para></listitem>
 193     </varlistentry>
 194   </variablelist>
 195   The special value <literal>all</literal> can be used to turn on all debug options.
 196   </para>
 197 </formalpara>
 198
 199 <formalpara>
 200   <title><envar>GTK_MODULES</envar></title>
 201
 202   <para>
 203     A list of modules to load.
 204   </para>
 205 </formalpara>
 206
 207 <formalpara>
 208   <title><envar>GTK_PATH</envar></title>
 209
 210   <para>
 211     Specifies a list of directories to search when GTK+ is looking for
 212     dynamically loaded objects such as the modules specified by
 213     <envar>GTK_MODULES</envar>, theme engines, and input method
 214     modules. If the path to the dynamically loaded object is given
 215     as an absolute path name, then GTK+ loads it directly. Otherwise,
 216     GTK+ goes in turn through the directories in GTK_PATH, followed
 217     by the directory <filename>.gtk-2.0</filename> in the user's home
 218     directory, followed by the system default directory,
 219     which is <filename><replaceable>libdir</replaceable>/gtk-2.0/modules</filename>.
 220     (If <envar>GTK_EXE_PREFIX</envar> is defined, <replaceable>libdir</replaceable> is
 221     <filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
 222     specified when GTK+ was configured, usually
 223     <filename>/usr/lib</filename>, or
 224     <filename>/usr/local/lib</filename>.)
 225     For each directory in this list, GTK+ actually looks in a
 226     subdirectory
 227     <filename><replaceable>directory</replaceable>/<replaceable>version</replaceable>/<replaceable>host</replaceable>/<replaceable>type</replaceable></filename>
 228     Where <replaceable>version</replaceable> is derived from the
 229     version of GTK+ (use <literal>pkg-config
 230     --variable=gtk_binary_version gtk+-2.0</literal> to determine this from a
 231     script), <replaceable>host</replaceable> is the architecture on
 232     which GTK+ was built. (use <literal>pkg-config
 233     --variable=gtk_host gtk+-2.0</literal> to determine this from a
 234     script), and <replaceable>type</replaceable> is a directory
 235     specific to the type of modules; currently it can be
 236     <literal>modules</literal>, <literal>engines</literal> or
 237     <literal>immodules</literal> corresponding to the three types of
 238     modules above. Either <replaceable>version</replaceable>,
 239     <replaceable>host</replaceable>, or both may be omitted. GTK+ looks
 240     first in the most specific directory, then in directories with
 241     fewer components.
 242     The components of GTK_PATH are separated by the ':' character on
 243     Linux and Unix, and the ';' character on Windows.
 244   </para>
 245 </formalpara>
 246
 247 <formalpara>
 248   <title><envar>GTK_IM_MODULE</envar></title>
 249
 250   <para>
 251     Specifies an IM module to use in preference to the one determined
 252     from the locale.
 253   </para>
 254 </formalpara>
 255
 256 <formalpara id="im-module-file">
 257   <title><envar>GTK_IM_MODULE_FILE</envar></title>
 258
 259   <para>
 260     Specifies the file listing the IM modules to load. This environment
 261     variable overwrites the <literal>im_module_file</literal> specified in
 262     the RC files, which in turn overwrites 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>.)
 266   </para>
 267 </formalpara>
 268
 269 <formalpara>
 270   <title><envar>GTK_RC_FILES</envar></title>
 271
 272   <para>
 273     Specifies a list of RC files to parse instead of the default ones;
 274     see <link linkend="gtk-Resource-Files">Resource Files</link>.
 275   </para>
 276 </formalpara>
 277
 278 <formalpara>
 279   <title><envar>GTK_EXE_PREFIX</envar></title>
 280
 281   <para>
 282     If set, GTK+ uses <filename>$GTK_EXE_PREFIX/lib</filename> instead of
 283     the libdir configured when GTK+ was compiled.
 284   </para>
 285 </formalpara>
 286
 287 <formalpara>
 288   <title><envar>GTK_DATA_PREFIX</envar></title>
 289
 290   <para>
 291     If set, makes GTK+ use <filename>$GTK_DATA_PREFIX</filename>
 292     instead of the prefix configured when GTK+ was compiled.
 293   </para>
 294 </formalpara>
 295
 296 <para>
 297 The following environment variables are used by GdkPixbuf, GDK or
 298 Pango, not by GTK+ itself, but we list them here for completeness
 299 nevertheless.
 300 </para>
 301
 302 <formalpara>
 303   <title><envar>GDK_PIXBUF_MODULEDIR</envar></title>
 304
 305   <para>
 306     Specifies the directory to look for GdkPixbuf loader modules.
 307     By default, GdkPixbuf looks for its loaders in
 308     <filename><replaceable>libdir</replaceable>/gtk-2.0/<replaceable>version</replaceable>/loaders</filename>.
 309   </para>
 310  </formalpara>
 311
 312 <formalpara id="GDK-Debug-Options">
 313   <title><envar>GDK_DEBUG</envar></title>
 314
 315   <para>
 316   If GTK+ has been configured with <option>--enable-debug=yes</option>,
 317   this variable can be set to a list of debug options, which cause GDK
 318   to print out different types of debugging information.
 319   <variablelist>
 320     <varlistentry>
 321       <term>misc</term>
 322       <listitem><para>Miscellaneous information</para></listitem>
 323     </varlistentry>
 324     <varlistentry>
 325       <term>events</term>
 326       <listitem><para>Show all events received by GDK</para></listitem>
 327     </varlistentry>
 328     <varlistentry>
 329       <term>dnd</term>
 330       <listitem><para>Information about drag-and-drop</para></listitem>
 331     </varlistentry>
 332     <varlistentry>
 333       <term>xim</term>
 334       <listitem><para>Information about XIM support</para></listitem>
 335     </varlistentry>
 336   </variablelist>
 337   The special value <literal>all</literal> can be used to turn on all debug options.
 338   </para>
 339 </formalpara>
 340
 341 <formalpara id="GXID">
 342   <title><envar>GXID_HOST</envar> and <envar>GXID_PORT</envar></title>
 343
 344   <para>
 345     The host and port to contact the <application>gxid</application> daemon on.
 346     <application>gxid</application> is only necessary on X servers which
 347     don't support using the pointer and extension devices at once, and is
 348     only built if GTK+ is configured with <option>--with-xinput=gxi</option>.
 349     The <application>XFree86</application> X servers don't have this
 350     restriction.
 351   </para>
 352 </formalpara>
 353
 354 <formalpara>
 355   <title><envar>GDK_USE_XFT</envar></title>
 356
 357   <para>
 358     If this variable is set to 1, GTK+ will use the Pango Xft backend instead
 359     of the X backend when possible (i.e. when the X server supports the XRender
 360     extension and Pango has been built with Xft support).
 361   </para>
 362 </formalpara>
 363
 364 </refsect2>
 365
 366 </refsect1>
 367
 368 </refentry>