running.sgml 12.6 KB
Newer Older
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
<refentry id="gtk-running" revision="10 Jan 2002">
<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>Common commandline options</title>

<para>
All GTK+ applications support a number of standard commandline
Havoc Pennington's avatar
Havoc Pennington committed
23 24 25
options. These are removed from <literal>argv</literal> by <link
linkend="gtk-init">gtk_init()</link>. Modules may parse and remove
further options.
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
</para>

<formalpara>
<title><systemitem>--gtk-module <replaceable>module</replaceable></systemitem></title>

<para>
A list of modules to load in addition to those specified in the 
<envar>GTK_MODULES</envar> environment variable.
</para>
</formalpara>

<formalpara>
<title><systemitem>--g-fatal-warnings</systemitem></title>

<para>
Havoc Pennington's avatar
Havoc Pennington committed
41 42 43 44
Make GTK+ abort on all warnings. This is useful to stop on the first
warning in a debugger, if your application is printing multiple
warnings.  It's almost always best to start debugging with the first
warning that occurs.
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
</para>
</formalpara>

<formalpara>
<title><systemitem>--gtk-debug <replaceable>options</replaceable></systemitem></title>

<para>
A list of <link linkend="GTK-Debug-Options">debug options</link> 
to turn on in addition to those specified in the <envar>GTK_DEBUG</envar> 
environment variable. 
This option is only available if GTK+ has been configured with
<option>--enable-debug=yes</option>.
</para>
</formalpara>

<formalpara>
<title><systemitem>--gtk-no-debug <replaceable>options</replaceable></systemitem></title>

<para>
A list of <link linkend="GTK-Debug-Options">debug options</link> 
to turn off.
This option is only available if GTK+ has been configured with
<option>--enable-debug=yes</option>.
</para>
</formalpara>

<para>
The following options are really used by GDK, not by GTK+, but we
list them here for completeness nevertheless.
</para>

<formalpara>
<title><systemitem>--class <replaceable>class</replaceable></systemitem></title>

<para>
Sets the program class; see gdk_set_program_class(). 
</para>
</formalpara>

<formalpara>
<title><systemitem>--name <replaceable>name</replaceable></systemitem></title>

<para>
Sets the program name.
</para>
</formalpara>

<formalpara>
<title><systemitem>--gdk-debug <replaceable>options</replaceable></systemitem></title>

<para>
A list of <link linkend="GDK-Debug-Options">debug options</link> 
to turn on in addition to those 
specified in the <envar>GDK_DEBUG</envar> environment variable. 
This option is only available if GTK+ has been configured with
<option>--enable-debug=yes</option>.
</para>
</formalpara>

<formalpara>
<title><systemitem>--gdk-no-debug <replaceable>options</replaceable></systemitem></title>

<para>
A list of <link linkend="GDK-Debug-Options">debug options</link> 
to turn off.
This option is only available if GTK+ has been configured with
<option>--enable-debug=yes</option>.
</para>
</formalpara>

<formalpara>
<title><systemitem>--display <replaceable>display</replaceable></systemitem></title>

<para>
The name of the X display to open instead of the one specified
Owen Taylor's avatar
Owen Taylor committed
120
in the <envar>DISPLAY</envar> environment variable. 
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
121 122 123 124 125
This option is only available if GTK+ has been configured with
<option>--gdk-target=x11</option>.
</para>
</formalpara>

Owen Taylor's avatar
Owen Taylor committed
126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
<formalpara>
<title><systemitem>--screen <replaceable>screen_number</replaceable></systemitem></title>

<para>
  The number of the screen within the default display. This overrides
  any screen number specified in the display name specified by
  by he <systemitem>--display</systemitem> command line option or
  the <envar>DISPLAY</envar> environment variable. If this screen
  cannot be opened, then GTK+ will fall back to the screen
  specified in the display name. This option is not useful
  interactively; the intended purposes is that when a program
  registers its command line with a <firstterm>session
  manager</firstterm> for later restarting, it can save the
  screen it is on, without having to worry if it might be
  restarted on a different display.
</para>
</formalpara>

Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
<formalpara>
<title><systemitem>--sync</systemitem></title>

<para>
Makes all X requests synchronously. This is a useful option for 
debugging, but it will slow down the performance considerably.
This option is only available if GTK+ has been configured with
<option>--gdk-target=x11</option>.
</para>
</formalpara>

<formalpara>
<title><systemitem>--gxid-host <replaceable>host</replaceable></systemitem></title>

<para>
159
The host to contact the <application>gxid</application> daemon on; overrides 
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
160 161 162 163 164 165 166 167 168 169
the <link linkend="GXID"><envar>GXID_HOST</envar></link> environment variable.
This option is only available if GTK+ has been configured with
<option>--gdk-target=x11</option>.
</para>
</formalpara>

<formalpara>
<title><systemitem>--gxid-port <replaceable>port</replaceable></systemitem></title>

<para>
170
The port for the connection to <application>gxid</application>; overrides 
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212
the <link linkend="GXID"><envar>GXID_PORT</envar></link> environment variable.
This option is only available if GTK+ has been configured with
<option>--gdk-target=x11</option>.
</para>
</formalpara>

</refsect2>

<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.
</para>

<formalpara id="GTK-Debug-Options">
  <title><envar>GTK_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 GTK+
  to print out different types of debugging information.
  <variablelist>
    <varlistentry>
      <term>misc</term>
      <listitem><para>Miscellaneous information</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>text</term>
      <listitem><para>Information about text widget internals</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>tree</term>
      <listitem><para>Information about tree widget internals</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>updates</term>
      <listitem><para>Visual feedback about window updates</para></listitem>
    </varlistentry>
  </variablelist>
Havoc Pennington's avatar
Havoc Pennington committed
213
  The special value <literal>all</literal> can be used to turn on all debug options.
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
214 215 216 217 218 219 220 221 222 223 224 225
  </para>
</formalpara>

<formalpara>
  <title><envar>GTK_MODULES</envar></title>

  <para>
    A list of modules to load.
  </para>
</formalpara>

<formalpara>
226
  <title><envar>GTK_PATH</envar></title>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
227 228

  <para>
229 230 231 232 233 234 235 236 237 238
    Specifies a list of directories to search when GTK+ is looking for
    dynamically loaded objects such as the modules specified by
    <envar>GTK_MODULES</envar>, theme engines, and input method
    modules. 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 GTK_PATH, followed
    by the directory <filename>.gtk-2.0</filename> in the user's home
    directory, followed by the system default directory, 
    which is <filename><replaceable>libdir</replaceable>/gtk-2.0/modules</filename>.
    (If <envar>GTK_EXE_PREFIX</envar> is defined, <replaceable>libdir</replaceable> is 
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
239
    <filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261
    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 gtk+-2.0</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 gtk+-2.0</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> or
    <literal>immodules</literal> corresponding to the three types of
    modules 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.
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
262 263 264 265 266 267 268 269 270 271 272 273
  </para>
</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. 
  </para>
</formalpara>

Matthias Clasen's avatar
Matthias Clasen committed
274
<formalpara id="im-module-file">
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
275 276 277 278
  <title><envar>GTK_IM_MODULE_FILE</envar></title>

  <para>
    Specifies the file listing the IM modules to load. This environment
279 280
    variable overrides the <literal>im_module_file</literal> specified in 
    the RC files, which in turn overrides the default value 
281 282
    <filename><replaceable>sysconfdir</replaceable>/gtk-2.0/gtk.immodules</filename>
    (<replaceable>sysconfdir</replaceable> is the sysconfdir specified when GTK+ was configured, 
Havoc Pennington's avatar
Havoc Pennington committed
283
     usually <filename>/usr/local/etc</filename>.)
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
284
  </para>
Havoc Pennington's avatar
Havoc Pennington committed
285
</formalpara>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
286 287 288 289 290 291 292

<formalpara>
  <title><envar>GTK_RC_FILES</envar></title>
  
  <para>
    Specifies a list of RC files to parse instead of the default ones;
    see <link linkend="gtk-Resource-Files">Resource Files</link>.
Havoc Pennington's avatar
Havoc Pennington committed
293
  </para>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
294 295 296 297 298 299 300 301 302 303 304 305 306 307 308
</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>
Havoc Pennington's avatar
Havoc Pennington committed
309
    If set, makes GTK+ use <filename>$GTK_DATA_PREFIX</filename>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
310 311 312 313 314 315 316 317 318 319 320
    instead of the prefix configured when GTK+ was compiled.
  </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>
321
  <title><envar>GDK_PIXBUF_MODULE_FILE</envar></title>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
322 323

  <para>
324
    Specifies the file listing the GdkPixbuf loader modules to load. 
325
    This environment variable overrides the default value 
326 327 328
    <filename><replaceable>sysconfdir</replaceable>/gtk-2.0/gdk-pixbuf.loaders</filename>
    (<replaceable>sysconfdir</replaceable> is the sysconfdir specified when
	  GTK+ was configured, usually <filename>/usr/local/etc</filename>.)
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356
  </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>misc</term>
      <listitem><para>Miscellaneous information</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>events</term>
      <listitem><para>Show all events received by GDK</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>dnd</term>
      <listitem><para>Information about drag-and-drop</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>xim</term>
      <listitem><para>Information about XIM support</para></listitem>
    </varlistentry>
  </variablelist>
Havoc Pennington's avatar
Havoc Pennington committed
357
  The special value <literal>all</literal> can be used to turn on all debug options.
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388
  </para>
</formalpara>

<formalpara id="GXID">
  <title><envar>GXID_HOST</envar> and <envar>GXID_PORT</envar></title>

  <para>
    The host and port to contact the <application>gxid</application> daemon on. 
    <application>gxid</application> is only necessary on X servers which 
    don't support using the pointer and extension devices at once, and is
    only built if GTK+ is configured with <option>--with-xinput=gxi</option>. 
    The <application>XFree86</application> X servers don't have this 
    restriction.
  </para>
</formalpara>

<formalpara>
  <title><envar>GDK_USE_XFT</envar></title>

  <para>
    If this variable is set to 1, GTK+ will use the Pango Xft backend instead
    of the X backend when possible (i.e. when the X server supports the XRender
    extension and Pango has been built with Xft support). 
  </para>
</formalpara>

</refsect2>

</refsect1>

</refentry>