docs/reference/gtk/html/gtk-running.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Running GTK+ Applications</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GTK+ 3 Reference Manual">
   8 <link rel="up" href="gtk.html" title="Part I. GTK+ Overview">
   9 <link rel="prev" href="gtk-compiling.html" title="Compiling GTK+ Applications">
  10 <link rel="next" href="gtk-x11.html" title="Using GTK+ on the X Window System">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
  16 <td><a accesskey="p" href="gtk-compiling.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="gtk.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  18 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  19 <th width="100%" align="center">GTK+ 3 Reference Manual</th>
  20 <td><a accesskey="n" href="gtk-x11.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="refentry">
  23 <a name="gtk-running"></a><div class="titlepage"></div>
  24 <div class="refnamediv"><table width="100%"><tr>
  25 <td valign="top">
  26 <h2><span class="refentrytitle">Running GTK+ Applications</span></h2>
  27 <p>Running GTK+ Applications —
  28 How to run and debug your GTK+ application
  29 </p>
  30 </td>
  31 <td valign="top" align="right"></td>
  32 </tr></table></div>
  33 <div class="refsect1">
  34 <a name="id405468"></a><h2>Running and debugging GTK+ Applications</h2>
  35 <div class="refsect2">
  36 <a name="id366848"></a><h3>Common commandline options</h3>
  37 <p>
  38 All GTK+ applications support a number of standard commandline
  39 options. These are removed from <code class="literal">argv</code> by gtk_init().
  40 Modules may parse and remove further options. The
  41 <a class="link" href="gtk-x11.html#x11-cmdline" title="X11-specific commandline options">X11</a> and
  42 <a class="link" href="gtk-windows.html#win32-cmdline" title="Windows-specific commandline options">Windows</a> GDK backends parse
  43 some additional commandline options.
  44 </p>
  45 <p><b><code class="systemitem">--gtk-module <em class="replaceable"><code>module</code></em></code>. </b>
  46 A list of modules to load in addition to those specified in the
  47 <code class="envar">GTK_MODULES</code> environment variable and the
  48 <code class="literal">gtk-modules</code> setting.
  49 </p>
  50 <p><b><code class="systemitem">--g-fatal-warnings</code>. </b>
  51 Make GTK+ abort on all warnings. This is useful to stop on the first
  52 warning in a debugger, if your application is printing multiple
  53 warnings.  It's almost always best to start debugging with the first
  54 warning that occurs.
  55 </p>
  56 <p><b><code class="systemitem">--gtk-debug <em class="replaceable"><code>options</code></em></code>. </b>
  57 A list of <a class="link" href="gtk-running.html#GTK-Debug-Options" title="GTK_DEBUG">debug options</a>
  58 to turn on in addition to those specified in the <code class="envar">GTK_DEBUG</code>
  59 environment variable. This option is only available if GTK+ has been
  60 configured with <code class="option">--enable-debug=yes</code>.
  61 </p>
  62 <p><b><code class="systemitem">--gtk-no-debug <em class="replaceable"><code>options</code></em></code>. </b>
  63 A list of <a class="link" href="gtk-running.html#GTK-Debug-Options" title="GTK_DEBUG">debug options</a>
  64 to turn off. This option is only available if GTK+ has been configured with
  65 <code class="option">--enable-debug=yes</code>.
  66 </p>
  67 <p>
  68 The following options are really used by GDK, not by GTK+, but we
  69 list them here for completeness nevertheless.
  70 </p>
  71 <p><b><code class="systemitem">--class <em class="replaceable"><code>class</code></em></code>. </b>
  72 Sets the program class; see gdk_set_program_class().
  73 </p>
  74 <p><b><code class="systemitem">--name <em class="replaceable"><code>name</code></em></code>. </b>
  75 Sets the program name.
  76 </p>
  77 <p><b><code class="systemitem">--gdk-debug <em class="replaceable"><code>options</code></em></code>. </b>
  78 A list of <a class="link" href="gtk-running.html#GDK-Debug-Options" title="GDK_DEBUG">debug options</a>
  79 to turn on in addition to those specified in the <code class="envar">GDK_DEBUG</code>
  80 environment variable. This option is only available if GTK+ has been
  81 configured with <code class="option">--enable-debug=yes</code>.
  82 </p>
  83 <p><b><code class="systemitem">--gdk-no-debug <em class="replaceable"><code>options</code></em></code>. </b>
  84 A list of <a class="link" href="gtk-running.html#GDK-Debug-Options" title="GDK_DEBUG">debug options</a>
  85 to turn off. This option is only available if GTK+ has been configured with
  86 <code class="option">--enable-debug=yes</code>.
  87 </p>
  88 </div>
  89 <hr>
  90 <div class="refsect2">
  91 <a name="id440017"></a><h3>Environment variables</h3>
  92 <p>
  93 GTK+ inspects a number of environment variables in addition to standard
  94 variables like <code class="envar">LANG</code>, <code class="envar">PATH</code>, <code class="envar">HOME</code>
  95 or <code class="envar">DISPLAY</code>; mostly to determine paths to look for certain
  96 files. The X11,
  97 <a class="link" href="gtk-windows.html#win32-envar" title="Windows-specific environment variables">Windows</a> and
  98 Framebuffer GDK backends use some
  99 additional environment variables.
 100 </p>
 101 <p><a name="GTK-Debug-Options"></a><b><code class="envar">GTK_DEBUG</code>. </b>
 102   If GTK+ has been configured with <code class="option">--enable-debug=yes</code>,
 103   this variable can be set to a list of debug options, which cause GTK+
 104   to print out different types of debugging information.
 105   </p>
 106 <div class="variablelist"><table border="0">
 107 <col align="left" valign="top">
 108 <tbody>
 109 <tr>
 110 <td><p><span class="term">misc</span></p></td>
 111 <td><p>Miscellaneous information</p></td>
 112 </tr>
 113 <tr>
 114 <td><p><span class="term">plugsocket</span></p></td>
 115 <td><p>Cross-process embedding</p></td>
 116 </tr>
 117 <tr>
 118 <td><p><span class="term">text</span></p></td>
 119 <td><p>Text widget internals</p></td>
 120 </tr>
 121 <tr>
 122 <td><p><span class="term">tree</span></p></td>
 123 <td><p>Tree widget internals</p></td>
 124 </tr>
 125 <tr>
 126 <td><p><span class="term">updates</span></p></td>
 127 <td><p>Visual feedback about window updates</p></td>
 128 </tr>
 129 <tr>
 130 <td><p><span class="term">keybindings</span></p></td>
 131 <td><p>Keybindings</p></td>
 132 </tr>
 133 <tr>
 134 <td><p><span class="term">multihead</span></p></td>
 135 <td><p>Working on multiple displays</p></td>
 136 </tr>
 137 <tr>
 138 <td><p><span class="term">modules</span></p></td>
 139 <td><p>Loading of modules</p></td>
 140 </tr>
 141 <tr>
 142 <td><p><span class="term">geometry</span></p></td>
 143 <td><p>Size allocation</p></td>
 144 </tr>
 145 <tr>
 146 <td><p><span class="term">icontheme</span></p></td>
 147 <td><p>Icon themes</p></td>
 148 </tr>
 149 <tr>
 150 <td><p><span class="term">printing</span></p></td>
 151 <td><p>Printing support</p></td>
 152 </tr>
 153 <tr>
 154 <td><p><span class="term">builder</span></p></td>
 155 <td><p>GtkBuilder support</p></td>
 156 </tr>
 157 </tbody>
 158 </table></div>
 159 <p>
 160   The special value <code class="literal">all</code> can be used to turn on all
 161   debug options.
 162   </p>
 163 <p><b><code class="envar">GTK_MODULES</code>. </b>
 164     A list of modules to load. Note that GTK+ also allows to specify modules to load via a commandline option (<code class="option">--gtk-module</code>) and with the <code class="literal">gtk-modules</code> setting.
 165   </p>
 166 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 167 <h3 class="title">Warning</h3>
 168     Note that this environment variable is read by GTK+ 2.x too,
 169     which may not have the same set of modules available for loading.
 170   </div>
 171 <p><a name="gtk-path"></a><b><code class="envar">GTK_PATH</code>. </b>
 172     Specifies a list of directories to search when GTK+ is looking for
 173     dynamically loaded objects such as the modules specified by
 174     <code class="envar">GTK_MODULES</code>, theme engines, input method
 175     modules, file system backends and print backends. If the path to
 176     the dynamically loaded object is given as an absolute path name,
 177     then GTK+ loads it directly.
 178     Otherwise, GTK+ goes in turn through the directories in <code class="envar">GTK_PATH</code>,
 179     followed by the directory <code class="filename">.gtk-3.0</code> in the user's
 180     home directory, followed by the system default directory,
 181     which is <code class="filename"><em class="replaceable"><code>libdir</code></em>/gtk-3.0/modules</code>.
 182     (If <code class="envar">GTK_EXE_PREFIX</code> is defined, <em class="replaceable"><code>libdir</code></em> is
 183     <code class="filename">$GTK_EXE_PREFIX/lib</code>. Otherwise it is the libdir
 184     specified when GTK+ was configured, usually
 185     <code class="filename">/usr/lib</code>, or
 186     <code class="filename">/usr/local/lib</code>.)
 187     For each directory in this list, GTK+ actually looks in a
 188     subdirectory
 189     <code class="filename"><em class="replaceable"><code>directory</code></em>/<em class="replaceable"><code>version</code></em>/<em class="replaceable"><code>host</code></em>/<em class="replaceable"><code>type</code></em></code>
 190     Where <em class="replaceable"><code>version</code></em> is derived from the
 191     version of GTK+ (use <code class="literal">pkg-config
 192     --variable=gtk_binary_version gtk+-3.0</code> to determine this from a
 193     script), <em class="replaceable"><code>host</code></em> is the architecture on
 194     which GTK+ was built. (use <code class="literal">pkg-config
 195     --variable=gtk_host gtk+-3.0</code> to determine this from a
 196     script), and <em class="replaceable"><code>type</code></em> is a directory
 197     specific to the type of modules; currently it can be
 198     <code class="literal">modules</code>, <code class="literal">engines</code>,
 199     <code class="literal">immodules</code>, <code class="literal">filesystems</code> or
 200     <code class="literal">printbackends</code>, corresponding to the types of
 201     modules mentioned above. Either <em class="replaceable"><code>version</code></em>,
 202     <em class="replaceable"><code>host</code></em>, or both may be omitted. GTK+ looks
 203     first in the most specific directory, then in directories with
 204     fewer components.
 205     The components of GTK_PATH are separated by the ':' character on
 206     Linux and Unix, and the ';' character on Windows.
 207   </p>
 208 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 209 <h3 class="title">Warning</h3>
 210     Note that this environment variable is read by GTK+ 2.x too, which
 211     makes it unsuitable for setting it system-wide (or session-wide),
 212     since doing so will cause either GTK+ 2.x applications or GTK+ 3
 213     applications to see incompatible modules.
 214   </div>
 215 <p><b><code class="envar">GTK_IM_MODULE</code>. </b>
 216     Specifies an IM module to use in preference to the one determined
 217     from the locale. If this isn't set and you are running on the system
 218     that enables <code class="literal">XSETTINGS</code> and has a value in
 219     <code class="literal">Gtk/IMModule</code>, that will be used for the default
 220     IM module.
 221     This also can be a colon-separated list of input-methods, which
 222     GTK+ will try in turn until it finds one available on the system.
 223   </p>
 224 <p><a name="gtk-im-module-file"></a><b><code class="envar">GTK_IM_MODULE_FILE</code>. </b>
 225     Specifies the file listing the IM modules to load. This environment
 226     variable the default value
 227     <code class="filename"><em class="replaceable"><code>libdir</code></em>/gtk-3.0/3.0.0/immodules.cache</code>
 228     (<em class="replaceable"><code>libdir</code></em> has the same meaning here as explained for <code class="envar">GTK_PATH</code>).
 229
 230     The <code class="filename">immodules.cache</code> file is generated by the
 231     <span class="command"><strong>gtk-query-immodules-3.0</strong></span> utility.
 232   </p>
 233 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 234 <h3 class="title">Warning</h3>
 235     Note that this environment variable is read by GTK+ 2.x too, which
 236     makes it unsuitable for setting it system-wide (or session-wide),
 237     since doing so will cause either GTK+ 2.x applications or GTK+ 3
 238     applications to see the wrong list of IM modules.
 239   </div>
 240 <p><b><code class="envar">GTK_EXE_PREFIX</code>. </b>
 241     If set, GTK+ uses <code class="filename">$GTK_EXE_PREFIX/lib</code> instead of
 242     the libdir configured when GTK+ was compiled.
 243   </p>
 244 <p><b><code class="envar">GTK_DATA_PREFIX</code>. </b>
 245     If set, makes GTK+ use <code class="filename">$GTK_DATA_PREFIX</code>
 246     instead of the prefix configured when GTK+ was compiled.
 247   </p>
 248 <p>
 249 The following environment variables are used by GdkPixbuf, GDK or
 250 Pango, not by GTK+ itself, but we list them here for completeness
 251 nevertheless.
 252 </p>
 253 <p><b><code class="envar">GDK_PIXBUF_MODULE_FILE</code>. </b>
 254     Specifies the file listing the GdkPixbuf loader modules to load.
 255     This environment variable overrides the default value
 256     <code class="filename"><em class="replaceable"><code>libdir</code></em>/gtk-3.0/3.0.0/loaders.cache</code>
 257     (<em class="replaceable"><code>libdir</code></em> is the sysconfdir specified when
 258     GTK+ was configured, usually <code class="filename">/usr/local/lib</code>.)
 259
 260     The <code class="filename">loaders.cache</code> file is generated by the
 261     <span class="command"><strong>gdk-pixbuf-query-loaders</strong></span> utility.
 262   </p>
 263 <p><a name="GDK-Debug-Options"></a><b><code class="envar">GDK_DEBUG</code>. </b>
 264   If GTK+ has been configured with <code class="option">--enable-debug=yes</code>,
 265   this variable can be set to a list of debug options, which cause GDK
 266   to print out different types of debugging information.
 267   </p>
 268 <div class="variablelist"><table border="0">
 269 <col align="left" valign="top">
 270 <tbody>
 271 <tr>
 272 <td><p><span class="term">misc</span></p></td>
 273 <td><p>Miscellaneous information</p></td>
 274 </tr>
 275 <tr>
 276 <td><p><span class="term">events</span></p></td>
 277 <td><p>Show all events received by GDK</p></td>
 278 </tr>
 279 <tr>
 280 <td><p><span class="term">dnd</span></p></td>
 281 <td><p>Information about drag-and-drop</p></td>
 282 </tr>
 283 <tr>
 284 <td><p><span class="term">xim</span></p></td>
 285 <td><p>Information about XIM support</p></td>
 286 </tr>
 287 <tr>
 288 <td><p><span class="term">nograbs</span></p></td>
 289 <td><p>Turn off all pointer and keyboard grabs</p></td>
 290 </tr>
 291 <tr>
 292 <td><p><span class="term">multihead</span></p></td>
 293 <td><p>Information related to multiple screens</p></td>
 294 </tr>
 295 <tr>
 296 <td><p><span class="term">xinerama</span></p></td>
 297 <td><p>Simulate a multi-monitor setup</p></td>
 298 </tr>
 299 <tr>
 300 <td><p><span class="term">cursor</span></p></td>
 301 <td><p>Information about cursor objects (only win32)</p></td>
 302 </tr>
 303 <tr>
 304 <td><p><span class="term">draw</span></p></td>
 305 <td><p>Information about drawing operations (only win32)</p></td>
 306 </tr>
 307 <tr>
 308 <td><p><span class="term">eventloop</span></p></td>
 309 <td><p>Information about event loop operation (mostly Quartz)</p></td>
 310 </tr>
 311 </tbody>
 312 </table></div>
 313 <p>
 314   The special value <code class="literal">all</code> can be used to turn on all
 315   debug options.
 316   </p>
 317 <p><b><code class="envar">GDK_RENDERING</code>. </b>
 318     If set, selects the way how GDK creates similar surfaces. This affects both the
 319     functionality of the function gdk_window_create_similar_surface() as well as the
 320     way GDK creates backing surfaces for double buffering. The following values can
 321     be used:
 322     </p>
 323 <div class="variablelist"><table border="0">
 324 <col align="left" valign="top">
 325 <tbody>
 326 <tr>
 327 <td><p><span class="term">similar</span></p></td>
 328 <td><p>Create similar surfaces to the window in use. This is the
 329           default behavior when the variable is not set.</p></td>
 330 </tr>
 331 <tr>
 332 <td><p><span class="term">image</span></p></td>
 333 <td><p>Always create image surfaces. This essentially turns off
 334           all hardware acceleration inside GTK.</p></td>
 335 </tr>
 336 <tr>
 337 <td><p><span class="term">recording</span></p></td>
 338 <td><p>Always create recording surfaces. This causes bare rendering
 339           to the backend without the creation of intermediate surfaces (Pixmaps in X)
 340           and will likely cause flicker.</p></td>
 341 </tr>
 342 </tbody>
 343 </table></div>
 344 <p>
 345     All other values will be ignored and fall back to the default behavior. More
 346     values might be added in the future.
 347   </p>
 348 <p><b><code class="envar">GDK_BACKEND</code>. </b>
 349     If set, selects the GDK backend to use. Selecting a backend requires that
 350     GTK+ is compiled with support for that backend. The following backends can
 351     be selected:
 352     </p>
 353 <div class="variablelist"><table border="0">
 354 <col align="left" valign="top">
 355 <tbody>
 356 <tr>
 357 <td><p><span class="term">quartz</span></p></td>
 358 <td><p>Selects the native Quartz backend</p></td>
 359 </tr>
 360 <tr>
 361 <td><p><span class="term">win32</span></p></td>
 362 <td><p>Selects the native backend for Microsoft Windows</p></td>
 363 </tr>
 364 <tr>
 365 <td><p><span class="term">x11</span></p></td>
 366 <td><p>Selects the native backend for connecting to X11 servers.</p></td>
 367 </tr>
 368 <tr>
 369 <td><p><span class="term">broadway</span></p></td>
 370 <td><p>Selects the HTML5 backend.</p></td>
 371 </tr>
 372 <tr>
 373 <td><p><span class="term">wayland</span></p></td>
 374 <td><p>Selects the Wayland backend for connecting to Wayland display servers.</p></td>
 375 </tr>
 376 </tbody>
 377 </table></div>
 378 <p>
 379     For more information about selecting backends, see the gdk_display_manager_get() function.
 380   </p>
 381 <p><b><code class="envar">GDK_SYNCHRONIZE</code>. </b>
 382     If set, GDK makes all X requests synchronously. This is a useful
 383     option for debugging, but it will slow down the performance considerably.
 384   </p>
 385 <p><b><code class="envar">XDG_DATA_HOME</code>, <code class="envar">XDG_DATA_DIRS</code>. </b>
 386     GTK+ uses these environment variables to locate icon themes
 387     and MIME information. For more information, see
 388     <a class="ulink" href="http://freedesktop.org/Standards/icon-theme-spec" target="_top">Icon Theme Specification</a>,
 389     the <a class="ulink" href="http://freedesktop.org/Standards/shared-mime-info-spec" target="_top">Shared MIME-info Database</a>
 390     and the <a class="ulink" href="http://freedesktop.org/Standards/basedir-spec" target="_top">Base Directory Specification</a>.
 391   </p>
 392 <p><b><code class="envar">DESKTOP_STARTUP_ID</code>. </b>
 393     GTK+ uses this environment variable to provide startup notification
 394     according to the <a class="ulink" href="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt" target="_top">Startup Notification Spec</a>.
 395     Following the specification, GTK+ unsets this variable after reading
 396     it (to keep it from leaking to child processes). So, if you need its
 397     value for your own purposes, you have to read it before calling
 398     gtk_init().
 399   </p>
 400 </div>
 401 </div>
 402 </div>
 403 <div class="footer">
 404 <hr>
 405           Generated by GTK-Doc V1.18</div>
 406 </body>
 407 </html>