docs/reference/glib/compiling.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   4 ]>
   5 <refentry id="glib-compiling" revision="17 Jan 2002">
   6 <refmeta>
   7 <refentrytitle>Compiling GLib Applications</refentrytitle>
   8 <manvolnum>3</manvolnum>
   9 <refmiscinfo>GLib Library</refmiscinfo>
  10 </refmeta>
  11
  12 <refnamediv>
  13 <refname>Compiling GLib Applications</refname>
  14 <refpurpose>
  15 How to compile your GLib application
  16 </refpurpose>
  17 </refnamediv>
  18
  19 <refsect1>
  20 <title>Compiling GLib Applications on UNIX</title>
  21
  22 <para>
  23 To compile a GLib application, you need to tell the compiler where to
  24 find the GLib header files and libraries. This is done with the
  25 <application>pkg-config</application> utility.
  26 </para>
  27 <para>
  28 The following interactive shell session demonstrates how
  29 <application>pkg-config</application> is used (the actual output on
  30 your system may be different):
  31 <programlisting>
  32 $ pkg-config --cflags glib-2.0
  33  -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include
  34 $ pkg-config --libs glib-2.0
  35  -L/usr/lib -lm -lglib-2.0
  36 </programlisting>
  37 </para>
  38 <para>
  39 See the <ulink url="http://www.freedesktop.org/wiki/Software/pkg-config">pkg-config website</ulink>
  40 for more information about <application>pkg-config</application>.
  41 </para>
  42 <para>
  43 If your application uses or <structname>GObject</structname>
  44 features, it must be compiled and linked with the options returned
  45 by the following <application>pkg-config</application> invocation:
  46 <programlisting>
  47 $ pkg-config --cflags --libs gobject-2.0
  48 </programlisting>
  49 </para>
  50 <para>
  51 If your application uses modules, it must be compiled and linked
  52 with the options returned by one of the following
  53 <application>pkg-config</application> invocations:
  54 <programlisting>
  55 $ pkg-config --cflags --libs gmodule-no-export-2.0
  56 $ pkg-config --cflags --libs gmodule-2.0
  57 </programlisting>
  58 The difference between the two is that gmodule-2.0 adds
  59 <option>--export-dynamic</option> to the linker flags,
  60 which is often not needed.
  61 </para>
  62 <para>
  63 The simplest way to compile a program is to use the "backticks"
  64 feature of the shell. If you enclose a command in backticks
  65 (<emphasis>not single quotes</emphasis>), then its output will
  66 be substituted into the command line before execution. So to
  67 compile a GLib Hello, World, you would type the following:
  68 <programlisting>
  69 $ cc hello.c `pkg-config --cflags --libs glib-2.0` -o hello
  70 </programlisting>
  71 </para>
  72 <note><para>
  73 Note that the name of the file must come before the other options
  74 (such as <emphasis>pkg-config</emphasis>), or else you may get an
  75 error from the linker.
  76 </para></note>
  77
  78 <para>
  79 Deprecated GLib functions are annotated to make the compiler
  80 emit warnings when they are used (e.g. with gcc, you need to use
  81 the -Wdeprecated-declarations option). If these warnings are
  82 problematic, they can be turned off by defining the preprocessor
  83 symbol %GLIB_DISABLE_DEPRECATION_WARNINGS by using the commandline
  84 option <literal>-DGLIB_DISABLE_DEPRECATION_WARNINGS</literal>
  85 </para>
  86
  87 <para>
  88 GLib deprecation annotations are versioned; by defining the
  89 macros %GLIB_VERSION_MIN_REQUIRED and %GLIB_VERSION_MAX_ALLOWED,
  90 you can specify the range of GLib versions whose API you want
  91 to use. APIs that were deprecated before or introduced after
  92 this range will trigger compiler warnings.
  93 </para>
  94
  95 <para>
  96 Since GLib 2.62, the older deprecation mechanism of hiding deprecated interfaces
  97 entirely from the compiler by using the preprocessor symbol
  98 <literal>G_DISABLE_DEPRECATED</literal> has been removed. All deprecations
  99 are now handled using the above mechanism.
 100 </para>
 101
 102 <para>
 103 The recommended way of using GLib has always been to only include the
 104 toplevel headers <filename>glib.h</filename>,
 105 <filename>glib-object.h</filename>, <filename>gio.h</filename>.
 106 Starting with 2.32, GLib enforces this by generating an error
 107 when individual headers are directly included.
 108 </para>
 109
 110 <para>
 111 Still, there are some exceptions; these headers have to be included
 112 separately:
 113 <filename>gmodule.h</filename>,
 114 <filename>glib-unix.h</filename>,
 115 <filename>glib/gi18n-lib.h</filename> or
 116 <filename>glib/gi18n.h</filename> (see
 117 the <link linkend="glib-I18N">Internationalization section</link>),
 118 <filename>glib/gprintf.h</filename> and
 119 <filename>glib/gstdio.h</filename>
 120 (we don't want to pull in all of stdio).
 121 </para>
 122
 123 </refsect1>
 124
 125 </refentry>