running.sgml 10.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
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 145 146 147 148 149 150 151 152 153 154 155 156 157
</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
158
  The special value <literal>all</literal> can be used to turn on all debug options.
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
159 160 161 162 163 164 165 166 167 168 169 170
  </para>
</formalpara>

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

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

<formalpara>
171
  <title><envar>GTK_PATH</envar></title>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
172 173

  <para>
174 175 176 177 178 179 180 181 182 183
    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
184
    <filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206
    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
207 208 209 210 211 212 213 214 215 216 217 218
  </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
219
<formalpara id="im-module-file">
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
220 221 222 223
  <title><envar>GTK_IM_MODULE_FILE</envar></title>

  <para>
    Specifies the file listing the IM modules to load. This environment
224 225
    variable overrides the <literal>im_module_file</literal> specified in 
    the RC files, which in turn overrides the default value 
226 227
    <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
228
     usually <filename>/usr/local/etc</filename>.)
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
229
  </para>
Havoc Pennington's avatar
Havoc Pennington committed
230
</formalpara>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
231 232

<formalpara>
233
  <title><envar>GTK2_RC_FILES</envar></title>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
234 235 236 237
  
  <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
238
  </para>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
239 240 241 242 243 244 245 246 247 248 249 250 251 252 253
</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
254
    If set, makes GTK+ use <filename>$GTK_DATA_PREFIX</filename>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
255 256 257 258 259 260 261 262 263 264 265
    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>
266
  <title><envar>GDK_PIXBUF_MODULE_FILE</envar></title>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
267 268

  <para>
269
    Specifies the file listing the GdkPixbuf loader modules to load. 
270
    This environment variable overrides the default value 
271 272 273
    <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
274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301
  </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
302
  The special value <literal>all</literal> can be used to turn on all debug options.
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
303 304 305 306
  </para>
</formalpara>

<formalpara>
307
  <title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
Matthias Clasen's avatar
Expand.  
Matthias Clasen committed
308 309

  <para>
310 311 312 313 314
    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
315 316 317 318 319 320 321 322
  </para>
</formalpara>

</refsect2>

</refsect1>

</refentry>