<chapter id="gtk-building">
  <title>Compiling the GTK Libraries</title>
  <sect1>
    <title>Building GTK</title>
    <para>
      Before we get into the details of how to compile GTK, we should
      mention that in many cases, binary packages of GTK prebuilt for
      your operating system will be available, either from your
      operating system vendor or from independent sources. If such a set
      of packages is available, installing it will get you programming
      with GTK much faster than building it yourself. In fact, you may
      well already have GTK installed on your system already.
    </para>
    <para>
      In order to build GTK, you will need <emphasis>meson</emphasis>
      installed on your system. On Linux, and other UNIX-like operating
      systems, you will also need <emphasis>ninja</emphasis>. This guide
      does not cover how to install these two requirements, but you can
      refer to the <ulink url="http://mesonbuild.com">Meson
      website</ulink> for more information. The
      <ulink url="https://ninja-build.org">Ninja</ulink> build tool is
      also usable on various operating systems, so we will refer to it
      in the examples.
    </para>
    <para>
      If you are building GTK from a source distribution or from a Git
      clone, you will need to use <emphasis>meson</emphasis> to
      configure the project. The most commonly useful argument is the
      <literal>--prefix</literal> one, which determines where the files
      will go once installed. To install GTK under a prefix like
      <literal>/opt/gtk</literal> you would run Meson as:
    </para>
    <programlisting>
meson setup --prefix /opt/gtk builddir
</programlisting>
    <para>
      Meson will create the <literal>builddir</literal> directory and
      place all the build artefacts there.
    </para>
    <para>
      You can get a list of all available options for the build by
      running <literal>meson configure</literal>.
    </para>
    <para>
      After Meson successfully configured the build directory, you then
      can run the build, using Ninja:
    </para>
    <programlisting>
cd builddir
ninja
ninja install
</programlisting>
    <para>
      If you don’t have permission to write to the directory you are
      installing in, you may have to change to root temporarily before
      running <literal>ninja install</literal>.
    </para>
    <para>
      Several environment variables are useful to pass to set before
      running <emphasis>meson</emphasis>. <literal>CPPFLAGS</literal>
      contains options to pass to the C compiler, and is used to tell
      the compiler where to look for include files. The
      <literal>LDFLAGS</literal> variable is used in a similar fashion
      for the linker. Finally the <literal>PKG_CONFIG_PATH</literal>
      environment variable contains a search path that
      <literal>pkg-config</literal> (see below) uses when looking for
      files describing how to compile programs using different
      libraries. If you were installing GTK and it’s dependencies into
      <literal>/opt/gtk</literal>, you might want to set these variables
      as:
    </para>
    <programlisting>
CPPFLAGS=&quot;-I/opt/gtk/include&quot;
LDFLAGS=&quot;-L/opt/gtk/lib&quot;
PKG_CONFIG_PATH=&quot;/opt/gtk/lib/pkgconfig&quot;
export CPPFLAGS LDFLAGS PKG_CONFIG_PATH
</programlisting>
    <para>
      You may also need to set the <literal>LD_LIBRARY_PATH</literal>
      environment variable so the systems dynamic linker can find the
      newly installed libraries, and the <literal>PATH</literal>
      environment program so that utility binaries installed by the
      various libraries will be found.
    </para>
    <programlisting>
LD_LIBRARY_PATH=&quot;/opt/gtk/lib&quot;
PATH=&quot;/opt/gtk/bin:$PATH&quot;
export LD_LIBRARY_PATH PATH
</programlisting>
  </sect1>
  <sect1 id="build-types">
    <title>Build types</title>
    <para>
      Meson has different build types, exposed by the
      <literal>buildtype</literal> configuration option. GTK enables and
      disables functionality depending on the build type used when
      calling <emphasis>meson</emphasis> to configure the build.
    </para>
    <sect2>
      <title>Debug builds</title>
      <para>
        GTK will enable debugging code paths in both the
        <literal>debug</literal> and <literal>debugoptimized</literal>
        build types. Builds with <literal>buildtype</literal> set to
        <literal>debug</literal> will additionally enable consistency
        checks on the internal state of the toolkit.
      </para>
      <para>
        It is recommended to use the <literal>debug</literal> or
        <literal>debugoptimized</literal> build types when developing
        GTK itself. Additionally, <literal>debug</literal> builds of GTK
        are recommended for profiling and debugging GTK applications, as
        they include additional validation of the internal state.
      </para>
      <para>
        The <literal>debugoptimized</literal> build type is the default
        for GTK if no build type is specified when calling
        <emphasis>meson</emphasis>.
      </para>
    </sect2>
    <sect2>
      <title>Release builds</title>
      <para>
        The <literal>release</literal> build type will disable debugging
        code paths and additional run time safeties, like checked casts
        for object instances.
      </para>
      <para>
        The <literal>plain</literal> build type provided by Meson should
        only be used when packaging GTK, and it’s expected that
        packagers will provide their own compiler flags when building
        GTK. See the previous section for the list of environment
        variables to be used to define compiler and linker flags. Note
        that with the plain build type, you are also responsible for
        controlling the debugging features of GTK with
        <literal>-DG_ENABLE_DEBUG</literal> and
        <literal>-DG_DISABLE_CAST_CHECKS</literal>.
      </para>
    </sect2>
  </sect1>
  <sect1 id="dependencies">
    <title>Dependencies</title>
    <para>
      Before you can compile the GTK widget toolkit, you need to have
      various other tools and libraries installed on your system.
      Dependencies of GTK have their own build systems, so you will need
      to refer to their own installation instructions.
    </para>
    <para>
      A particular important tool used by GTK to find its dependencies
      is <literal>pkg-config</literal>.
    </para>
    <para>
      <ulink url="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</ulink>
      is a tool for tracking the compilation flags needed for libraries
      that are used by the GTK libraries. (For each library, a small
      <literal>.pc</literal> text file is installed in a standard
      location that contains the compilation flags needed for that
      library along with version number information.)
    </para>
    <para>
      Some of the libraries that GTK depends on are maintained by the
      GTK team: GLib, GdkPixbuf, Pango, and GObject Introspection. Other
      libraries are maintained separately.
    </para>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          The GLib library provides core non-graphical functionality
          such as high level data types, Unicode manipulation, and an
          object and type system to C programs. It is available from
          <ulink url="https://download.gnome.org/sources/glib/">here</ulink>.
        </para>
      </listitem>
      <listitem>
        <para>
          The
          <ulink url="https://git.gnome.org/browse/gdk-pixbuf/">GdkPixbuf</ulink>
          library provides facilities for loading images in a variety of
          file formats. It is available
          <ulink url="ttps://download.gnome.org/sources/gdk-pixbuf/">here</ulink>.
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="http://www.pango.org">Pango</ulink> is a library
          for internationalized text handling. It is available
          <ulink url="https://download.gnome.org/sources/pango/">here</ulink>.
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="https://wiki.gnome.org/Projects/GObjectIntrospection">GObject
          Introspection</ulink> is a framework for making introspection
          data available to language bindings. It is available
          <ulink url="https://download.gnome.org/sources/gobject-introspection/">here</ulink>.
        </para>
      </listitem>
      <listitem>
        <para>
          The <ulink url="https://www.gnu.org/software/libiconv/">GNU
          libiconv</ulink> library is needed to build GLib if your
          system doesn’t have the <link linkend="iconv"><function>iconv()</function></link> function for doing conversion
          between character encodings. Most modern systems should have
          <link linkend="iconv"><function>iconv()</function></link>.
        </para>
      </listitem>
      <listitem>
        <para>
          The libintl library from the
          <ulink url="https://www.gnu.org/software/gettext/">GNU
          gettext</ulink> package is needed if your system doesn’t have
          the <link linkend="gettext"><function>gettext()</function></link> functionality for handling message translation
          databases.
        </para>
      </listitem>
      <listitem>
        <para>
          The libraries from the X window system are needed to build
          Pango and GTK. You should already have these installed on your
          system, but it’s possible that you’ll need to install the
          development environment for these libraries that your
          operating system vendor provides.
        </para>
      </listitem>
      <listitem>
        <para>
          The
          <ulink url="https://www.freedesktop.org/wiki/Software/fontconfig/">fontconfig</ulink>
          library provides Pango with a standard way of locating fonts
          and matching them against font names.
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="https://www.cairographics.org">Cairo</ulink> is a
          graphics library that supports vector graphics and image
          compositing. Both Pango and GTK use Cairo for drawing. Note
          that we also need the auxiliary cairo-gobject library.
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="https://github.com/anholt/libepoxy">libepoxy</ulink>
          is a library that abstracts the differences between different
          OpenGL libraries. GTK uses it for cross-platform GL support
          and for its own drawing.
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="http://ebassi.github.io/graphene/">Graphene</ulink>
          is a library that provides vector and matrix types for 2D and
          3D transformations. GTK uses it internally for drawing.
        </para>
      </listitem>
      <listitem>
        <para>
          The
          <ulink url="https://wayland.freedesktop.org">Wayland</ulink>
          libraries are needed to build GTK with the Wayland backend.
        </para>
      </listitem>
      <listitem>
        <para>
          The
          <ulink url="https://www.freedesktop.org/wiki/Software/shared-mime-info">shared-mime-info</ulink>
          package is not a hard dependency of GTK, but it contains
          definitions for mime types that are used by GIO and,
          indirectly, by GTK. gdk-pixbuf will use GIO for mime type
          detection if possible. For this to work, shared-mime-info
          needs to be installed and <literal>XDG_DATA_DIRS</literal> set
          accordingly at configure time. Otherwise, gdk-pixbuf falls
          back to its built-in mime type detection.
        </para>
      </listitem>
    </itemizedlist>
  </sect1>
  <sect1 id="building">
    <title>Building and testing GTK</title>
    <para>
      First make sure that you have the necessary external dependencies
      installed: <literal>pkg-config</literal>, Meson, Ninja, the JPEG,
      PNG, and TIFF libraries, FreeType, and, if necessary, libiconv and
      libintl. To get detailed information about building these
      packages, see the documentation provided with the individual
      packages. On any average Linux system, it’s quite likely you’ll
      have all of these installed already, or they will be easily
      accessible through your operating system package repositories.
    </para>
    <para>
      Then build and install the GTK libraries in the order: GLib,
      Cairo, Pango, then GTK. For each library, follow the instructions
      they provide, and make sure to share common settings between them
      and the GTK build; if you are using a separate prefix for GTK, for
      instance, you will need to use the same prefix for all its
      dependencies you build. If you’re lucky, this will all go
      smoothly, and you’ll be ready to
      <link linkend="gtk-compiling">start compiling your own GTK
      applications</link>. You can test your GTK installation by running
      the <literal>gtk4-demo</literal> program that GTK installs.
    </para>
    <para>
      If one of the projects you’re configuring or building fails, look
      closely at the error messages printed; these will often provide
      useful information as to what went wrong. Every build system has
      its own log that can help you understand the issue you’re
      encountering. If all else fails, you can ask for help on the
      <link linkend="gtk-resources">GTK forums</link>.
    </para>
  </sect1>
  <sect1 id="extra-configuration-options">
    <title>Extra Configuration Options</title>
    <para>
      In addition to the normal options provided by Meson, GTK defines
      various arguments that modify what should be built. All of these
      options are passed to <literal>meson</literal> as
      <literal>-Doption=value</literal>. Most of the time, the value can
      be <literal>true</literal> or <literal>false</literal>, or
      <literal>enabled</literal>, <literal>disabled</literal> or
      <literal>auto</literal>.
    </para>
    <para>
      To see a summary of all supported options and their allowed
      values, run
    </para>
    <programlisting>
meson configure builddir
</programlisting>
    <sect2>
      <title><literal>x11-backend</literal>,
      <literal>win32-backend</literal>,
      <literal>broadway-backend</literal>,
      <literal>wayland-backend</literal> and
      <literal>macos-backend</literal></title>
      <para>
        Enable specific backends for GDK. If none of these options are
        given, the Wayland backend will be enabled by default, if the
        platform is Linux; the X11 backend will also be enabled by
        default, unless the platform is Windows, in which case the
        default is win32, or the platform is macOS, in which case the
        default is macOS. If any backend is explicitly enabled or
        disabled, no other platform will be enabled automatically.
      </para>
    </sect2>
    <sect2>
      <title><literal>vulkan</literal></title>
      <para>
        By default, GTK will try to build with support for the Vulkan
        graphics API in addition to cairo and OpenGL. This option can be
        used to explicitly control whether Vulkan should be used.
      </para>
    </sect2>
    <sect2>
      <title><literal>xinerama</literal></title>
      <para>
        By default, GTK will try to link against the Xinerama libraries
        if they are found. This option can be used to explicitly control
        whether Xinerama should be used.
      </para>
    </sect2>
    <sect2>
      <title><literal>media</literal></title>
      <para>
        By default, GTK will try to build the gstreamer backend for
        media playback support. This option can be used to explicitly
        control which media backends should be built.
      </para>
    </sect2>
    <sect2>
      <title><literal>print</literal></title>
      <para>
        By default, GTK will try to build various print backends if
        their dependencies are found. This option can be used to
        explicitly control which print backends should be built.
      </para>
    </sect2>
    <sect2>
      <title><literal>cloudproviders</literal></title>
      <para>
        This option controls whether GTK should use libcloudproviders
        for supporting various Cloud storage APIs in the file chooser.
      </para>
    </sect2>
    <sect2>
      <title><literal>sysprof</literal></title>
      <para>
        This option controls whether GTK should include support for
        tracing with sysprof.
      </para>
    </sect2>
    <sect2>
      <title><literal>tracker</literal></title>
      <para>
        This option controls whether GTK should use Tracker for search
        support in the file chooser.
      </para>
    </sect2>
    <sect2>
      <title><literal>colord</literal></title>
      <para>
        This option controls whether GTK should use colord for color
        calibration support in the cups print backend.
      </para>
    </sect2>
    <sect2>
      <title><literal>gtk_doc</literal> and
      <literal>man-pages</literal></title>
      <para>
        The <emphasis>gtk-doc</emphasis> package is used to generate the
        reference documentation included with GTK. By default support
        for <emphasis>gtk-doc</emphasis> is disabled because it requires
        various extra dependencies to be installed. If you have
        <emphasis>gtk-doc</emphasis> and <emphasis>pandoc</emphasis>
        installed and are modifying GTK, you may want to enable
        <emphasis>gtk-doc</emphasis> support by passing in
        <literal>-Dgtk_doc=true</literal>.
      </para>
      <para>
        Additionally, some tools provided by GTK have their own manual
        pages generated using a similar set of dependencies; if you have
        <emphasis>xsltproc</emphasis> then you can generate manual pages
        by passing <literal>-Dman-pages=true</literal> when configuring
        the build.
      </para>
    </sect2>
    <sect2>
      <title><literal>introspection</literal></title>
      <para>
        Allows to disable building introspection support. This is option
        is mainly useful for shortening turnaround times on developer
        systems. Installed builds of GTK should always have
        introspection support.
      </para>
    </sect2>
    <sect2>
      <title><literal>build-tests</literal>,
      <literal>install-tests</literal>, <literal>demos</literal></title>
      <para>
        By default, GTK will build quite a few tests and demos. While
        these are useful on a developer system, they are not needed when
        GTK is built e.g. for a flatpak runtime. These options allow to
        disable building tests and demos.
      </para>
    </sect2>
  </sect1>
</chapter>
