Pileus Git - ~andy/gtk/blob - docs/reference/gtk/compiling.sgml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
   4 ]>
   5 <refentry id="gtk-compiling">
   6 <refmeta>
   7 <refentrytitle>Compiling GTK+ Applications</refentrytitle>
   8 <manvolnum>3</manvolnum>
   9 <refmiscinfo>GTK Library</refmiscinfo>
  10 </refmeta>
  11
  12 <refnamediv>
  13 <refname>Compiling GTK+ Applications</refname>
  14 <refpurpose>
  15 How to compile your GTK+ application
  16 </refpurpose>
  17 </refnamediv>
  18
  19 <refsect1>
  20 <title>Compiling GTK+ Applications on UNIX</title>
  21
  22 <para>
  23 To compile a GTK+ application, you need to tell the compiler where to
  24 find the GTK+ header files and libraries. This is done with the
  25 <literal>pkg-config</literal> utility.
  26 </para>
  27 <para>
  28 The following interactive shell session demonstrates how
  29 <literal>pkg-config</literal> is used (the actual output on
  30 your system may be different):
  31 <programlisting>
  32 $ pkg-config --cflags gtk+-3.0
  33  -pthread -I/usr/include/gtk-3.0 -I/usr/lib64/gtk-3.0/include -I/usr/include/atk-1.0 -I/usr/include/cairo -I/usr/include/pango-1.0 -I/usr/include/glib-2.0 -I/usr/lib64/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng12
  34 $ pkg-config --libs gtk+-3.0
  35  -pthread -lgtk-3 -lgdk-3 -latk-1.0 -lgio-2.0 -lpangoft2-1.0 -lgdk_pixbuf-2.0 -lpangocairo-1.0 -lcairo -lpango-1.0 -lfreetype -lfontconfig -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt -lglib-2.0
  36 </programlisting>
  37 </para>
  38 <para>
  39 The simplest way to compile a program is to use the "backticks"
  40 feature of the shell. If you enclose a command in backticks
  41 (<emphasis>not single quotes</emphasis>), then its output will be
  42 substituted into the command line before execution. So to compile
  43 a GTK+ Hello, World, you would type the following:
  44 <programlisting>
  45 $ cc `pkg-config --cflags --libs gtk+-3.0` hello.c -o hello
  46 </programlisting>
  47 </para>
  48
  49 <para>
  50 Deprecated GTK+ functions are annotated to make the compiler
  51 emit warnings when they are used (e.g. with gcc, you need to use
  52 the -Wdeprecated-declarations option). If these warnings are
  53 problematic, they can be turned off by defining the preprocessor
  54 symbol %GDK_DISABLE_DEPRECATION_WARNINGS by using the commandline
  55 option <literal>-DGDK_DISABLE_DEPRECATION_WARNINGS</literal>
  56 </para>
  57
  58 <para>
  59 GTK+ deprecation annotations are versioned; by defining the
  60 macros %GDK_VERSION_MIN_REQUIRED and %GDK_VERSION_MAX_ALLOWED,
  61 you can specify the range of GTK+ versions whose API you want
  62 to use. APIs that were deprecated before or introduced after
  63 this range will trigger compiler warnings.
  64 </para>
  65
  66 <para>
  67 Here is how you would compile hello.c if you want to allow it
  68 to use symbols that were not deprecated in 3.2:
  69 <programlisting>
  70 $ cc -DGDK_VERSION_MIN_REQUIRED=GDK_VERSION_3_2 `pkg-config --cflags --libs gtk+-3.0` hello.c -o hello
  71 </programlisting>
  72 </para>
  73
  74 <para>
  75 And here is how you would compile hello.c if you don't want
  76 it to use any symbols that were introduced after 3.4:
  77 <programlisting>
  78 $ cc -DGDK_VERSION_MAX_ALLOWED=GDK_VERSION_3_4 `pkg-config --cflags --libs gtk+-3.0` hello.c -o hello
  79 </programlisting>
  80 </para>
  81
  82 <para>
  83 The older deprecation mechanism of hiding deprecated interfaces
  84 entirely from the compiler by using the preprocessor symbol
  85 GTK_DISABLE_DEPRECATED is still used for deprecated macros,
  86 enumeration values, etc. To detect uses of these in your code,
  87 use the commandline option <literal>-DGTK_DISABLE_DEPRECATED</literal>.
  88 There are similar symbols GDK_DISABLE_DEPRECATED,
  89 GDK_PIXBUF_DISABLE_DEPRECATED and G_DISABLE_DEPRECATED for GDK, GdkPixbuf and
  90 GLib.
  91 </para>
  92
  93 <para>
  94 If you want to make sure that your program doesn't use any functions which
  95 may be problematic in a multihead setting, you can define the preprocessor
  96 symbol GDK_MULTIHEAD_SAFE by using the command line option
  97 <literal>-DGTK_MULTIHEAD_SAFE=1</literal>.
  98 </para>
  99
 100 <para>
 101 Similarly, if you want to make sure that your program doesn't use any
 102 functions which may be problematic in a multidevice setting, you can
 103 define the preprocessor symbol GDK_MULTIDEVICE_SAFE by using the command
 104 line option <literal>-DGTK_MULTIDEVICE_SAFE=1</literal>.
 105 </para>
 106
 107   <refsect2>
 108     <title>Useful autotools macros</title>
 109
 110     <para>
 111       GTK+ provides various macros for easily checking version and backends
 112       supported. The macros are
 113       <variablelist>
 114         <varlistentry>
 115           <term>AM_PATH_GTK_3_0([minimum-version], [if-found], [if-not-found], [modules])</term>
 116           <listitem>This macro should be used to check that GTK+ is installed
 117           and available for compilation. The four arguments are optional, and
 118           they are: <emphasis>minimum-version</emphasis>, the minimum version
 119           of GTK+ required for compilation; <emphasis>if-found</emphasis>, the
 120           action to perform if a valid version of GTK+ has been found;
 121           <emphasis>if-not-found</emphasis>, the action to perform if a valid
 122           version of GTK+ has not been found; <emphasis>modules</emphasis>, a
 123           list of modules to be checked along with GTK+.</listitem>
 124         </varlistentry>
 125         <varlistentry>
 126           <term>GTK_CHECK_BACKEND([backend-name], [minimum-version], [if-found], [if-not-found])</term>
 127           <listitem>This macro should be used to check if a specific backend
 128           is supported by GTK+. The <emphasis>minimum-version</emphasis>,
 129           <emphasis>if-found</emphasis> and <emphasis>if-not-found</emphasis>
 130           arguments are optional.</listitem>
 131         </varlistentry>
 132       </variablelist>
 133     </para>
 134   </refsect2>
 135
 136 </refsect1>
 137 </refentry>