running.sgml 11.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 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194
</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
in the <envar>DISPLAY</envar>. 
This option is only available if GTK+ has been configured with
<option>--gdk-target=x11</option>.
</para>
</formalpara>

<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>
The host to contact the <application>gxid</application> daemon on; overwrites 
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>
The port for the connection to <application>gxid</application>; overwrites 
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
195
  The special value <literal>all</literal> can be used to turn on all debug options.
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
196 197 198 199 200 201 202 203 204 205 206 207
  </para>
</formalpara>

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

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

<formalpara>
208
  <title><envar>GTK_PATH</envar></title>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
209 210

  <para>
211 212 213 214 215 216 217 218 219 220
    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
221
    <filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243
    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
244 245 246 247 248 249 250 251 252 253 254 255
  </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
256
<formalpara id="im-module-file">
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
257 258 259 260 261 262
  <title><envar>GTK_IM_MODULE_FILE</envar></title>

  <para>
    Specifies the file listing the IM modules to load. This environment
    variable overwrites the <literal>im_module_file</literal> specified in 
    the RC files, which in turn overwrites the default value 
263 264
    <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
265
     usually <filename>/usr/local/etc</filename>.)
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
266
  </para>
Havoc Pennington's avatar
Havoc Pennington committed
267
</formalpara>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
268 269 270 271 272 273 274

<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
275
  </para>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
276 277 278 279 280 281 282 283 284 285 286 287 288 289 290
</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
291
    If set, makes GTK+ use <filename>$GTK_DATA_PREFIX</filename>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307
    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>
  <title><envar>GDK_PIXBUF_MODULEDIR</envar></title>

  <para>
    Specifies the directory to look for GdkPixbuf loader modules. 
    By default, GdkPixbuf looks for its loaders in 
308
    <filename><replaceable>libdir</replaceable>/gtk-2.0/<replaceable>version</replaceable>/loaders</filename>.
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336
  </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
337
  The special value <literal>all</literal> can be used to turn on all debug options.
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368
  </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>