running.sgml 11.2 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
options. These are removed from <literal>argv</literal> by <link
linkend="gtk-init">gtk_init()</link>. Modules may parse and remove
25 26 27
further options. The <link linkend="x11-cmdline">X11</link> and
<link linkend="win32-cmdline">Windows</link> GDK backends parse
some additional commandline options.
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
28 29 30 31 32 33 34
</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 
35 36
<envar>GTK_MODULES</envar> environment variable and the 
<literal>gtk-modules</literal> setting.
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
37 38 39 40 41 42 43
</para>
</formalpara>

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

<para>
Havoc Pennington's avatar
Havoc Pennington committed
44 45 46 47
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
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
</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>
83
Sets the program class; see <link linkend="gdk-set-program-class"><function>gdk_set_program_class</function>()</link>. 
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
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
</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>

</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> 
126 127 128 129 130
or <envar>DISPLAY</envar>; mostly to determine paths to look for certain 
files. The <link linkend="x11-envar">X11</link>, 
<link linkend="win32-envar">Windows</link> and 
<link linkend="fb-envar">Framebuffer</link> GDK backends use some
additional environment variables.
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
131 132 133 134 135 136 137 138 139 140 141 142 143 144
</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>
145 146 147 148
    <varlistentry>
      <term>plugsocket</term>
      <listitem><para>Cross-process embedding</para></listitem>
    </varlistentry>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
149 150
    <varlistentry>
      <term>text</term>
151
      <listitem><para>Text widget internals</para></listitem>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
152 153 154
    </varlistentry>
    <varlistentry>
      <term>tree</term>
155
      <listitem><para>Tree widget internals</para></listitem>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
156 157 158 159 160
    </varlistentry>
    <varlistentry>
      <term>updates</term>
      <listitem><para>Visual feedback about window updates</para></listitem>
    </varlistentry>
161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177
    <varlistentry>
      <term>keybindings</term>
      <listitem><para>Keybindings</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>multihead</term>
      <listitem><para>Working on multiple displays</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>modules</term>
      <listitem><para>Loading of modules</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>geometry</term>
      <listitem><para>Size allocation</para></listitem>
    </varlistentry>

Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
178
  </variablelist>
Havoc Pennington's avatar
Havoc Pennington committed
179
  The special value <literal>all</literal> can be used to turn on all debug options.
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
180 181 182 183 184 185 186 187 188 189 190 191
  </para>
</formalpara>

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

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

<formalpara>
192
  <title><envar>GTK_PATH</envar></title>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
193 194

  <para>
195 196 197 198 199 200 201 202 203 204
    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
205
    <filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227
    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
228 229 230 231 232 233 234 235 236 237 238 239
  </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
240
<formalpara id="im-module-file">
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
241 242 243 244
  <title><envar>GTK_IM_MODULE_FILE</envar></title>

  <para>
    Specifies the file listing the IM modules to load. This environment
245 246
    variable overrides the <literal>im_module_file</literal> specified in 
    the RC files, which in turn overrides the default value 
247 248
    <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
249
     usually <filename>/usr/local/etc</filename>.)
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
250
  </para>
Havoc Pennington's avatar
Havoc Pennington committed
251
</formalpara>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
252 253

<formalpara>
254
  <title><envar>GTK2_RC_FILES</envar></title>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
255 256 257 258
  
  <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
259
  </para>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
260 261 262 263 264 265 266 267 268 269 270 271 272 273 274
</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
275
    If set, makes GTK+ use <filename>$GTK_DATA_PREFIX</filename>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
276 277 278 279 280 281 282 283 284 285 286
    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>
287
  <title><envar>GDK_PIXBUF_MODULE_FILE</envar></title>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
288 289

  <para>
290
    Specifies the file listing the GdkPixbuf loader modules to load. 
291
    This environment variable overrides the default value 
292 293 294
    <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
295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322
  </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
323
  The special value <literal>all</literal> can be used to turn on all debug options.
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
324 325 326 327
  </para>
</formalpara>

<formalpara>
328
  <title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
329 330

  <para>
331 332 333 334 335
    GTK+ uses these environment variables to locate icon themes
    and MIME information. For more information, see 
    <ulink url="http://freedesktop.org/Standards/icon-theme-spec">Icon Theme Specification</ulink>,
    the <ulink url="http://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink> 
    and the <ulink url="http://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
336 337 338 339 340 341 342 343
  </para>
</formalpara>

</refsect2>

</refsect1>

</refentry>