docs/reference/glib/building.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-building">
   6   <refmeta>
   7     <refentrytitle>Compiling the GLib package</refentrytitle>
   8     <manvolnum>3</manvolnum>
   9     <refmiscinfo>GLib Library</refmiscinfo>
  10   </refmeta>
  11
  12   <refnamediv>
  13     <refname>Compiling the GLib Package</refname>
  14     <refpurpose>How to compile GLib itself</refpurpose>
  15   </refnamediv>
  16
  17   <refsect1 id="building">
  18     <title>Building the Library on UNIX</title>
  19     <para>
  20       On UNIX, GLib uses the standard GNU build system,
  21       using <application>autoconf</application> for package
  22       configuration and resolving portability issues,
  23       <application>automake</application> for building makefiles
  24       that comply with the GNU Coding Standards, and
  25       <application>libtool</application> for building shared
  26       libraries on multiple platforms.  The normal sequence for
  27       compiling and installing the GLib library is thus:
  28
  29       <literallayout>
  30         <userinput>./configure</userinput>
  31         <userinput>make</userinput>
  32         <userinput>make install</userinput>
  33       </literallayout>
  34     </para>
  35
  36     <para>
  37       The standard options provided by <application>GNU
  38       autoconf</application> may be passed to the
  39       <command>configure</command> script.  Please see the
  40       <application>autoconf</application> documentation or run
  41       <command>./configure --help</command> for information about
  42       the standard options.
  43     </para>
  44     <para>
  45       GLib is compiled with
  46       <ulink url="https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-fstrict-aliasing">strict aliasing</ulink>
  47       disabled. It is strongly recommended that this is not re-enabled by
  48       overriding the compiler flags, as GLib has not been tested with strict
  49       aliasing and cannot be guaranteed to work.
  50     </para>
  51     <para>
  52       The GTK+ documentation contains
  53       <ulink url="https://developer.gnome.org/gtk3/stable/gtk-building.html">further details</ulink>
  54       about the build process and ways to influence it.
  55     </para>
  56   </refsect1>
  57   <refsect1 id="dependencies">
  58     <title>Dependencies</title>
  59     <para>
  60       Before you can compile the GLib library, you need to have
  61       various other tools and libraries installed on your system.
  62       If you are building from a release archive, you will need
  63       <ulink url="https://wiki.gnome.org/Projects/GLib/CompilerRequirements">a compliant C toolchain</ulink>,
  64       GNU Make, and <application>pkg-config</application>;
  65       if you are building directly from a Git repository clone
  66       of GLib, you will also need the GNU Autotools mentioned
  67       above.
  68     </para>
  69     <itemizedlist>
  70       <listitem>
  71         <para>
  72           <ulink url="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</ulink>
  73           is a tool for tracking the compilation flags needed for
  74           libraries that are used by the GLib library. (For each
  75           library, a small <literal>.pc</literal> text file is
  76           installed in a standard location that contains the compilation
  77           flags needed for that library along with version number
  78           information).
  79         </para>
  80       </listitem>
  81       <listitem>
  82         <para>
  83           The GLib Makefiles make use of several features specific to
  84           <ulink url="http://www.gnu.org/software/make">GNU
  85           make</ulink>, and will not build correctly with other
  86           versions of <command>make</command>. You will need to
  87           install it if you don't already have it on your system. (It
  88           may be called <command>gmake</command> rather than
  89           <command>make</command>.)
  90         </para>
  91       </listitem>
  92     </itemizedlist>
  93     <para>
  94       A UNIX build of GLib requires that the system implements at
  95       least the original 1990 version of POSIX. Beyond this, it
  96       depends on a number of other libraries.
  97     </para>
  98     <itemizedlist>
  99       <listitem>
 100         <para>
 101           The <ulink url="http://www.gnu.org/software/libiconv/">GNU
 102           libiconv library</ulink> is needed to build GLib if your
 103           system doesn't have the <function>iconv()</function>
 104           function for doing conversion between character
 105           encodings. Most modern systems should have
 106           <function>iconv()</function>, however many older systems lack
 107           an <function>iconv()</function> implementation. On such systems,
 108           you must install the libiconv library. This can be found at:
 109           <ulink url="http://www.gnu.org/software/libiconv">http://www.gnu.org/software/libiconv</ulink>.
 110         </para>
 111         <para>
 112           If your system has an <function>iconv()</function> implementation but
 113           you want to use libiconv instead, you can pass the
 114           <option>--with-libiconv</option> option to configure. This forces
 115           libiconv to be used.
 116         </para>
 117         <para>
 118           Note that if you have libiconv installed in your default include
 119           search path (for instance, in <filename>/usr/local/</filename>), but
 120           don't enable it, you will get an error while compiling GLib because
 121           the <filename>iconv.h</filename> that libiconv installs hides the
 122           system iconv.
 123         </para>
 124         <para>
 125           If you are using the native iconv implementation on Solaris
 126           instead of libiconv, you'll need to make sure that you have
 127           the converters between locale encodings and UTF-8 installed.
 128           At a minimum you'll need the SUNWuiu8 package. You probably
 129           should also install the SUNWciu8, SUNWhiu8, SUNWjiu8, and
 130           SUNWkiu8 packages.
 131         </para>
 132         <para>
 133           The native iconv on Compaq Tru64 doesn't contain support for
 134           UTF-8, so you'll need to use GNU libiconv instead. (When
 135           using GNU libiconv for GLib, you'll need to use GNU libiconv
 136           for GNU gettext as well.) This probably applies to related
 137           operating systems as well.
 138         </para>
 139       </listitem>
 140       <listitem>
 141         <para>
 142           The libintl library from the <ulink
 143           url="http://www.gnu.org/software/gettext">GNU gettext
 144           package</ulink> is needed if your system doesn't have the
 145           <function>gettext()</function> functionality for handling
 146           message translation databases.
 147         </para>
 148       </listitem>
 149       <listitem>
 150         <para>
 151           A thread implementation is needed. The thread support in GLib
 152           can be based upon POSIX threads or win32 threads.
 153         </para>
 154       </listitem>
 155       <listitem>
 156         <para>
 157           GRegex uses the <ulink url="http://www.pcre.org/">PCRE library</ulink>
 158           for regular expression matching. The default is to use the system
 159           version of PCRE, to reduce the chances of security fixes going out
 160           of sync. GLib additionally provides an internal copy of PCRE in case
 161           the system version is too old, or does not support UTF-8; the internal
 162           copy is patched to use GLib for memory management and to share the
 163           same Unicode tables.
 164         </para>
 165       </listitem>
 166       <listitem>
 167         <para>
 168           The optional extended attribute support in GIO requires the
 169           <function>getxattr()</function> family of functions that may be
 170           provided by the C library or by the standalone libattr library. To
 171           build GLib without extended attribute support, use the
 172           <option>--disable-xattr</option> option.
 173         </para>
 174       </listitem>
 175       <listitem>
 176         <para>
 177           The optional SELinux support in GIO requires libselinux.
 178           To build GLib without SELinux support, use the
 179           <option>--disable-selinux</option> option.
 180         </para>
 181       </listitem>
 182       <listitem>
 183         <para>
 184           The optional support for DTrace requires the
 185           <filename>sys/sdt.h</filename> header, which is provided
 186           by SystemTap on Linux. To build GLib without DTrace, use
 187           the <option>--disable-dtrace</option> configure option.
 188         </para>
 189       </listitem>
 190       <listitem>
 191         <para>
 192           The optional support for
 193           <ulink url="http://sourceware.org/systemtap/">SystemTap</ulink>
 194           can be disabled with the <option>--disable-systemtap</option>
 195           configure option. Additionally, you can control the location
 196           where GLib installs the SystemTap probes, using the
 197           <option>--with-tapset-install-dir=DIR</option> configure option.
 198         </para>
 199       </listitem>
 200     </itemizedlist>
 201
 202   </refsect1>
 203   <refsect1 id="extra-configuration-options">
 204     <title>Extra Configuration Options</title>
 205
 206     <para>
 207       In addition to the normal options, the
 208       <command>configure</command> script in the GLib
 209       library supports these additional arguments:
 210     </para>
 211
 212     <formalpara>
 213       <title><option>--enable-debug</option></title>
 214
 215       <para>
 216         Turns on various amounts of debugging support. Setting this to 'no'
 217         disables <function>g_assert()</function>, <function>g_return_if_fail()</function>,
 218         <function>g_return_val_if_fail()</function> and all cast checks
 219         between different object types. Setting it to 'minimum' disables
 220         only cast checks. Setting it to 'yes' enables <link linkend="G-DEBUG:CAPS">runtime debugging</link>.
 221         The default is 'minimum' for stable releases, and 'yes' for development
 222         snapshots. Note that 'no' is fast, but dangerous as it tends to destabilize
 223         even mostly bug-free software by changing the effect of many bugs
 224         from simple warnings into fatal crashes. Thus
 225         <option>--enable-debug=no</option> should <emphasis>not</emphasis>
 226         be used for stable releases of GLib.
 227       </para>
 228     </formalpara>
 229
 230     <formalpara>
 231       <title><option>--with-threads</option></title>
 232
 233       <para>
 234         Specify a thread implementation to use. Available options are
 235         'posix' or 'win32'. Normally, <command>configure</command>
 236         should be able to work out the system threads API on its own.
 237       </para>
 238     </formalpara>
 239
 240     <formalpara>
 241       <title><option>--with-pcre</option></title>
 242
 243       <para>
 244         Specify whether to use the internal or the system-supplied
 245         PCRE library.
 246         <itemizedlist>
 247           <listitem>
 248             <para>
 249               'internal' means that GRegex will be compiled to use
 250               the internal PCRE library.
 251             </para>
 252           </listitem>
 253           <listitem>
 254             <para>
 255               'system' means that GRegex will be compiled to use
 256               the system-supplied PCRE library; this is the default
 257               setting.
 258             </para>
 259           </listitem>
 260         </itemizedlist>
 261         Using the internal PCRE is the preferred solution if:
 262         <itemizedlist>
 263           <listitem>
 264             <para>
 265               your system has strict resource constraints; the system-supplied
 266               PCRE has a separated copy of the tables used for Unicode
 267               handling, whereas the internal copy shares the Unicode tables
 268               used by GLib.
 269             </para>
 270           </listitem>
 271           <listitem>
 272             <para>
 273               your system has PCRE built without some needed features,
 274               such as UTF-8 and Unicode support.
 275             </para>
 276           </listitem>
 277           <listitem>
 278             <para>
 279               you are planning to use both GRegex and PCRE API at the same
 280               time, either directly or indirectly through a dependency; PCRE
 281               uses some global variables for memory management and
 282               other features, and if both GLib and PCRE try to access them
 283               at the same time, this could lead to undefined behavior.
 284             </para>
 285           </listitem>
 286         </itemizedlist>
 287       </para>
 288     </formalpara>
 289
 290     <formalpara>
 291       <title><option>--disable-included-printf</option> and
 292         <option>--enable-included-printf</option></title>
 293
 294       <para>
 295         By default the <command>configure</command> script will try
 296         to auto-detect whether the C library provides a suitable set
 297         of <function>printf()</function> functions. In detail,
 298         <command>configure</command> checks that the semantics of
 299         <function>snprintf()</function> are as specified by C99
 300         and that positional parameters as specified in the Single Unix
 301         Specification are supported. If this not the case, GLib will
 302         include an implementation of the <function>printf()</function>
 303         family.
 304       </para>
 305       <para>
 306         These options can be used to explicitly control whether
 307         an implementation of the <function>printf()</function> family
 308         should be included or not.
 309       </para>
 310     </formalpara>
 311
 312     <formalpara>
 313       <title><option>--disable-Bsymbolic</option> and
 314         <option>--enable-Bsymbolic</option></title>
 315
 316       <para>
 317         By default, GLib uses the <option>-Bsymbolic-functions</option>
 318         linker flag to avoid intra-library PLT jumps. A side-effect
 319         of this is that it is no longer possible to override
 320         internal uses of GLib functions with
 321         <envar>LD_PRELOAD</envar>. Therefore, it may make
 322         sense to turn this feature off in some situations.
 323         The <option>--disable-Bsymbolic</option> option allows
 324         to do that.
 325       </para>
 326     </formalpara>
 327
 328     <formalpara>
 329       <title><option>--disable-gtk-doc</option> and
 330         <option>--enable-gtk-doc</option></title>
 331
 332       <para>
 333         By default the <command>configure</command> script will try
 334         to auto-detect whether the
 335         <application>gtk-doc</application> package is installed.
 336         If it is, then it will use it to extract and build the
 337         documentation for the GLib library. These options
 338         can be used to explicitly control whether
 339         <application>gtk-doc</application> should be
 340         used or not. If it is not used, the distributed,
 341         pre-generated HTML files will be installed instead of
 342         building them on your machine.
 343       </para>
 344     </formalpara>
 345
 346     <formalpara>
 347       <title><option>--disable-man</option> and
 348         <option>--enable-man</option></title>
 349
 350       <para>
 351         By default the <command>configure</command> script will try
 352         to auto-detect whether <application>xsltproc</application>
 353         and the necessary Docbook stylesheets are installed.
 354         If they are, then it will use them to rebuild the included
 355         man pages from the XML sources. These options can be used
 356         to explicitly control whether man pages should be rebuilt
 357         used or not. The distribution includes pre-generated man
 358         pages.
 359       </para>
 360     </formalpara>
 361
 362     <formalpara>
 363       <title><option>--disable-xattr</option> and
 364         <option>--enable-xattr</option></title>
 365
 366       <para>
 367         By default the <command>configure</command> script will try
 368         to auto-detect whether the <function>getxattr()</function>
 369         family of functions is available. If it is, then extended
 370         attribute support will be included in GIO. These options can
 371         be used to explicitly control whether extended attribute
 372         support should be included or not. <function>getxattr()</function>
 373         and friends can be provided by glibc or by the standalone
 374         libattr library.
 375       </para>
 376     </formalpara>
 377
 378     <formalpara>
 379       <title><option>--disable-selinux</option> and
 380         <option>--enable-selinux</option></title>
 381
 382       <para>
 383         By default the <command>configure</command> script will
 384         auto-detect if libselinux is available and include
 385         SELinux support in GIO if it is. These options can be
 386         used to explicitly control whether SELinux support should
 387         be included.
 388       </para>
 389     </formalpara>
 390
 391     <formalpara>
 392       <title><option>--disable-dtrace</option> and
 393         <option>--enable-dtrace</option></title>
 394
 395       <para>
 396         By default the <command>configure</command> script will
 397         detect if DTrace support is available, and use it.
 398       </para>
 399     </formalpara>
 400
 401     <formalpara>
 402       <title><option>--disable-systemtap</option> and
 403         <option>--enable-systemtap</option></title>
 404
 405       <para>
 406         This option requires DTrace support. If it is available, then
 407         the <command>configure</command> script will also check for
 408         the presence of SystemTap.
 409       </para>
 410     </formalpara>
 411
 412     <formalpara>
 413       <title><option>--enable-coverage</option> and
 414         <option>--disable-coverage</option></title>
 415
 416       <para>
 417         Enable the generation of coverage reports for the GLib tests.
 418         This requires the lcov frontend to gcov from the
 419         <ulink url="http://ltp.sourceforge.net">Linux Test Project</ulink>.
 420         To generate a coverage report, use the lcov make target. The
 421         report is placed in the <filename>glib-lcov</filename> directory.
 422       </para>
 423     </formalpara>
 424
 425     <formalpara>
 426       <title><option>--with-runtime-libdir=RELPATH</option></title>
 427
 428       <para>
 429         Allows specifying a relative path to where to install the runtime
 430         libraries (meaning library files used for running, not developing,
 431         GLib applications). This can be used in operating system setups where
 432         programs using GLib needs to run before e.g. <filename>/usr</filename>
 433         is mounted.
 434         For example, if <varname>LIBDIR</varname> is <filename>/usr/lib</filename> and
 435         <filename>../../lib</filename> is passed to
 436         <option>--with-runtime-libdir</option> then the
 437         runtime libraries are installed into <filename>/lib</filename> rather
 438         than <filename>/usr/lib</filename>.
 439       </para>
 440     </formalpara>
 441
 442     <formalpara>
 443       <title><option>--with-python=PATH</option></title>
 444
 445       <para>
 446         Allows specifying the Python interpreter to use, either as an absolute path,
 447         or as a program name. GLib can be built with Python 2 (at least version 2.7)
 448         or, preferably, with Python 3.
 449       </para>
 450     </formalpara>
 451   </refsect1>
 452
 453 </refentry>