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> environment variable.
 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>--screen <replaceable>screen_number</replaceable></systemitem></title>
 128
 129 <para>
 130   The number of the screen within the default display. This overrides
 131   any screen number specified in the display name specified by
 132   by he <systemitem>--display</systemitem> command line option or
 133   the <envar>DISPLAY</envar> environment variable. If this screen
 134   cannot be opened, then GTK+ will fall back to the screen
 135   specified in the display name. This option is not useful
 136   interactively; the intended purposes is that when a program
 137   registers its command line with a <firstterm>session
 138   manager</firstterm> for later restarting, it can save the
 139   screen it is on, without having to worry if it might be
 140   restarted on a different display.
 141 </para>
 142 </formalpara>
 143
 144 <formalpara>
 145 <title><systemitem>--sync</systemitem></title>
 146
 147 <para>
 148 Makes all X requests synchronously. This is a useful option for
 149 debugging, but it will slow down the performance considerably.
 150 This option is only available if GTK+ has been configured with
 151 <option>--gdk-target=x11</option>.
 152 </para>
 153 </formalpara>
 154
 155 <formalpara>
 156 <title><systemitem>--gxid-host <replaceable>host</replaceable></systemitem></title>
 157
 158 <para>
 159 The host to contact the <application>gxid</application> daemon on; overrides
 160 the <link linkend="GXID"><envar>GXID_HOST</envar></link> environment variable.
 161 This option is only available if GTK+ has been configured with
 162 <option>--gdk-target=x11</option>.
 163 </para>
 164 </formalpara>
 165
 166 <formalpara>
 167 <title><systemitem>--gxid-port <replaceable>port</replaceable></systemitem></title>
 168
 169 <para>
 170 The port for the connection to <application>gxid</application>; overrides
 171 the <link linkend="GXID"><envar>GXID_PORT</envar></link> environment variable.
 172 This option is only available if GTK+ has been configured with
 173 <option>--gdk-target=x11</option>.
 174 </para>
 175 </formalpara>
 176
 177 </refsect2>
 178
 179 <refsect2>
 180 <title>Environment variables</title>
 181
 182 <para>
 183 GTK+ inspects a number of environment variables in addition to standard
 184 variables like <envar>LANG</envar>, <envar>PATH</envar>, <envar>HOME</envar>
 185 or <envar>DISPLAY</envar>; mostly to determine paths to look for certain files.
 186 </para>
 187
 188 <formalpara id="GTK-Debug-Options">
 189   <title><envar>GTK_DEBUG</envar></title>
 190
 191   <para>
 192   If GTK+ has been configured with <option>--enable-debug=yes</option>,
 193   this variable can be set to a list of debug options, which cause GTK+
 194   to print out different types of debugging information.
 195   <variablelist>
 196     <varlistentry>
 197       <term>misc</term>
 198       <listitem><para>Miscellaneous information</para></listitem>
 199     </varlistentry>
 200     <varlistentry>
 201       <term>text</term>
 202       <listitem><para>Information about text widget internals</para></listitem>
 203     </varlistentry>
 204     <varlistentry>
 205       <term>tree</term>
 206       <listitem><para>Information about tree widget internals</para></listitem>
 207     </varlistentry>
 208     <varlistentry>
 209       <term>updates</term>
 210       <listitem><para>Visual feedback about window updates</para></listitem>
 211     </varlistentry>
 212   </variablelist>
 213   The special value <literal>all</literal> can be used to turn on all debug options.
 214   </para>
 215 </formalpara>
 216
 217 <formalpara>
 218   <title><envar>GTK_MODULES</envar></title>
 219
 220   <para>
 221     A list of modules to load.
 222   </para>
 223 </formalpara>
 224
 225 <formalpara>
 226   <title><envar>GTK_PATH</envar></title>
 227
 228   <para>
 229     Specifies a list of directories to search when GTK+ is looking for
 230     dynamically loaded objects such as the modules specified by
 231     <envar>GTK_MODULES</envar>, theme engines, and input method
 232     modules. If the path to the dynamically loaded object is given
 233     as an absolute path name, then GTK+ loads it directly. Otherwise,
 234     GTK+ goes in turn through the directories in GTK_PATH, followed
 235     by the directory <filename>.gtk-2.0</filename> in the user's home
 236     directory, followed by the system default directory,
 237     which is <filename><replaceable>libdir</replaceable>/gtk-2.0/modules</filename>.
 238     (If <envar>GTK_EXE_PREFIX</envar> is defined, <replaceable>libdir</replaceable> is
 239     <filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
 240     specified when GTK+ was configured, usually
 241     <filename>/usr/lib</filename>, or
 242     <filename>/usr/local/lib</filename>.)
 243     For each directory in this list, GTK+ actually looks in a
 244     subdirectory
 245     <filename><replaceable>directory</replaceable>/<replaceable>version</replaceable>/<replaceable>host</replaceable>/<replaceable>type</replaceable></filename>
 246     Where <replaceable>version</replaceable> is derived from the
 247     version of GTK+ (use <literal>pkg-config
 248     --variable=gtk_binary_version gtk+-2.0</literal> to determine this from a
 249     script), <replaceable>host</replaceable> is the architecture on
 250     which GTK+ was built. (use <literal>pkg-config
 251     --variable=gtk_host gtk+-2.0</literal> to determine this from a
 252     script), and <replaceable>type</replaceable> is a directory
 253     specific to the type of modules; currently it can be
 254     <literal>modules</literal>, <literal>engines</literal> or
 255     <literal>immodules</literal> corresponding to the three types of
 256     modules above. Either <replaceable>version</replaceable>,
 257     <replaceable>host</replaceable>, or both may be omitted. GTK+ looks
 258     first in the most specific directory, then in directories with
 259     fewer components.
 260     The components of GTK_PATH are separated by the ':' character on
 261     Linux and Unix, and the ';' character on Windows.
 262   </para>
 263 </formalpara>
 264
 265 <formalpara>
 266   <title><envar>GTK_IM_MODULE</envar></title>
 267
 268   <para>
 269     Specifies an IM module to use in preference to the one determined
 270     from the locale.
 271   </para>
 272 </formalpara>
 273
 274 <formalpara id="im-module-file">
 275   <title><envar>GTK_IM_MODULE_FILE</envar></title>
 276
 277   <para>
 278     Specifies the file listing the IM modules to load. This environment
 279     variable overrides the <literal>im_module_file</literal> specified in
 280     the RC files, which in turn overrides the default value
 281     <filename><replaceable>sysconfdir</replaceable>/gtk-2.0/gtk.immodules</filename>
 282     (<replaceable>sysconfdir</replaceable> is the sysconfdir specified when GTK+ was configured,
 283      usually <filename>/usr/local/etc</filename>.)
 284   </para>
 285 </formalpara>
 286
 287 <formalpara>
 288   <title><envar>GTK_RC_FILES</envar></title>
 289
 290   <para>
 291     Specifies a list of RC files to parse instead of the default ones;
 292     see <link linkend="gtk-Resource-Files">Resource Files</link>.
 293   </para>
 294 </formalpara>
 295
 296 <formalpara>
 297   <title><envar>GTK_EXE_PREFIX</envar></title>
 298
 299   <para>
 300     If set, GTK+ uses <filename>$GTK_EXE_PREFIX/lib</filename> instead of
 301     the libdir configured when GTK+ was compiled.
 302   </para>
 303 </formalpara>
 304
 305 <formalpara>
 306   <title><envar>GTK_DATA_PREFIX</envar></title>
 307
 308   <para>
 309     If set, makes GTK+ use <filename>$GTK_DATA_PREFIX</filename>
 310     instead of the prefix configured when GTK+ was compiled.
 311   </para>
 312 </formalpara>
 313
 314 <para>
 315 The following environment variables are used by GdkPixbuf, GDK or
 316 Pango, not by GTK+ itself, but we list them here for completeness
 317 nevertheless.
 318 </para>
 319
 320 <formalpara>
 321   <title><envar>GDK_PIXBUF_MODULE_FILE</envar></title>
 322
 323   <para>
 324     Specifies the file listing the GdkPixbuf loader modules to load.
 325     This environment variable overrides the default value
 326     <filename><replaceable>sysconfdir</replaceable>/gtk-2.0/gdk-pixbuf.loaders</filename>
 327     (<replaceable>sysconfdir</replaceable> is the sysconfdir specified when
 328           GTK+ was configured, usually <filename>/usr/local/etc</filename>.)
 329   </para>
 330  </formalpara>
 331
 332 <formalpara id="GDK-Debug-Options">
 333   <title><envar>GDK_DEBUG</envar></title>
 334
 335   <para>
 336   If GTK+ has been configured with <option>--enable-debug=yes</option>,
 337   this variable can be set to a list of debug options, which cause GDK
 338   to print out different types of debugging information.
 339   <variablelist>
 340     <varlistentry>
 341       <term>misc</term>
 342       <listitem><para>Miscellaneous information</para></listitem>
 343     </varlistentry>
 344     <varlistentry>
 345       <term>events</term>
 346       <listitem><para>Show all events received by GDK</para></listitem>
 347     </varlistentry>
 348     <varlistentry>
 349       <term>dnd</term>
 350       <listitem><para>Information about drag-and-drop</para></listitem>
 351     </varlistentry>
 352     <varlistentry>
 353       <term>xim</term>
 354       <listitem><para>Information about XIM support</para></listitem>
 355     </varlistentry>
 356   </variablelist>
 357   The special value <literal>all</literal> can be used to turn on all debug options.
 358   </para>
 359 </formalpara>
 360
 361 <formalpara id="GXID">
 362   <title><envar>GXID_HOST</envar> and <envar>GXID_PORT</envar></title>
 363
 364   <para>
 365     The host and port to contact the <application>gxid</application> daemon on.
 366     <application>gxid</application> is only necessary on X servers which
 367     don't support using the pointer and extension devices at once, and is
 368     only built if GTK+ is configured with <option>--with-xinput=gxi</option>.
 369     The <application>XFree86</application> X servers don't have this
 370     restriction.
 371   </para>
 372 </formalpara>
 373
 374 <formalpara>
 375   <title><envar>GDK_USE_XFT</envar></title>
 376
 377   <para>
 378     If this variable is set to 1, GTK+ will use the Pango Xft backend instead
 379     of the X backend when possible (i.e. when the X server supports the XRender
 380     extension and Pango has been built with Xft support).
 381   </para>
 382 </formalpara>
 383
 384 </refsect2>
 385
 386 </refsect1>
 387
 388 </refentry>