gtk2/docs/reference/gtk/building.xml

<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>
<refentry id="gtk-building">
<refmeta>
<refentrytitle>Compiling the GTK libraries</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Compiling the GTK Libraries</refname>
<refpurpose>
How to compile GTK itself
</refpurpose>
</refnamediv>
  <refsect1 id="overview">
    <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 <application>meson</application>
      installed on your system. On Linux, and other UNIX-like operating
      systems, you will also need <application>ninja</application>. 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 <application>meson</application> to
      configure the project. The most commonly useful argument is the
      <systemitem>--prefix</systemitem> one, which determines where the
      files will go once installed. To install GTK under a prefix
      like <filename>/opt/gtk</filename> you would run Meson as:
    </para>
    <informalexample>
      <programlisting>
        meson --prefix /opt/gtk builddir
      </programlisting>
    </informalexample>
    <para>
      Meson will create the <filename>builddir</filename> directory and
      place all the build artefacts there.
    </para>
    <para>
      You can get a list of all available options for the build by
      running <application>meson configure</application>.
    </para>
    <para>
      After Meson successfully configured the build directory, you then
      can run the build, using Ninja:
    </para>
    <informalexample>
      <programlisting>
        cd builddir
        ninja
        ninja install
      </programlisting>
    </informalexample>
    <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 <application>meson</application>. <envar>CPPFLAGS</envar>
      contains options to pass to the C compiler, and is used to tell
      the compiler where to look for include files. The <envar>LDFLAGS</envar>
      variable is used in a similar fashion for the linker. Finally the
      <envar>PKG_CONFIG_PATH</envar> environment variable contains
      a search path that <command>pkg-config</command> (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 <filename>/opt/gtk</filename>, you
      might want to set these variables as:
    </para>
    <programlisting>
      CPPFLAGS="-I/opt/gtk/include"
      LDFLAGS="-L/opt/gtk/lib"
      PKG_CONFIG_PATH="/opt/gtk/lib/pkgconfig"
      export CPPFLAGS LDFLAGS PKG_CONFIG_PATH
    </programlisting>
    <para>
      You may also need to set the <envar>LD_LIBRARY_PATH</envar>
      environment variable so the systems dynamic linker can find
      the newly installed libraries, and the <envar>PATH</envar>
      environment program so that utility binaries installed by
      the various libraries will be found.
    </para>
    <programlisting>
      LD_LIBRARY_PATH="/opt/gtk/lib"
      PATH="/opt/gtk/bin:$PATH"
      export LD_LIBRARY_PATH PATH
    </programlisting>
  </refsect1>

  <refsect1 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 <application>meson</application> to
    configure the build.</para>

    <formalpara>
      <title><systemitem>debug</systemitem> and <systemitem>debugoptimized</systemitem></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
        <application>meson</application>
      </para>
    </formalpara>

    <formalpara>
      <title><systemitem>release</systemitem></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>
    </formalpara>

    <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.
    </para>
  </refsect1>

  <refsect1 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 <application>pkg-config</application>.
    </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
      by the GTK team: GLib, GdkPixbuf, Pango, ATK and GObject Introspection.
      Other libraries are maintained separately.
    </para>
    <itemizedlist>
      <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 library</ulink>
          provides facilities for loading images in a variety of file formats.
          It is available <ulink url="https://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>
          ATK is the Accessibility Toolkit. It provides a set of generic
          interfaces allowing accessibility technologies such as
          screen readers to interact with a graphical user interface.
          It is available
          <ulink url="https://download.gnome.org/sources/atk/">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>
    </itemizedlist>
    <itemizedlist>
      <title>External dependencies</title>
      <listitem>
        <para>
          The <ulink url="https://www.gnu.org/software/libiconv/">GNU
          libiconv library</ulink> is needed to build GLib if your
          system doesn't have the <function>iconv()</function>
          function for doing conversion between character
          encodings. Most modern systems should have
          <function>iconv()</function>.
        </para>
      </listitem>
      <listitem>
        <para>
          The libintl library from the <ulink
          url="https://www.gnu.org/software/gettext/">GNU gettext
          package</ulink> is needed if your system doesn't have the
          <function>gettext()</function> 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.
        </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="https://github.com/anholt/libepoxy">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
          <envar>XDG_DATA_DIRS</envar> set accordingly at configure time.
          Otherwise, gdk-pixbuf falls back to its built-in mime type detection.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>
  <refsect1 id="building">
    <title>Building and testing GTK</title>
    <para>
      First make sure that you have the necessary external
      dependencies installed: <command>pkg-config</command>, 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, ATK, 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 <command>gtk4-demo</command> 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 gtk-list mailing list.
      See <xref linkend="gtk-resources"/> for more information.
    </para>
  </refsect1>

  <refsect1 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.

      <cmdsynopsis>
        <command>meson</command>
        <sbr/>
        <group>
          <arg choice="plain">-Dx11-backend=true</arg>
          <arg choice="plain">-Dx11-backend=false</arg>
        </group>
        <sbr/>
        <group>
          <arg choice="plain">-Dwayland-backend=true</arg>
          <arg choice="plain">-Dwayland-backend=false</arg>
        </group>
        <sbr/>
        <group>
          <arg choice="plain">-Dbroadway-backend=true</arg>
          <arg choice="plain">-Dbroadway-backend=false</arg>
        </group>
        <sbr/>
        <group>
          <arg choice="plain">-Dwin32-backend=true</arg>
          <arg choice="plain">-Dwin32-backend=false</arg>
        </group>
        <sbr/>
        <group>
          <arg choice="plain">-Dquartz-backend=true</arg>
          <arg choice="plain">-Dquartz-backend=false</arg>
        </group>
        <sbr/>
        <group>
          <arg choice="plain">-Dmedia=gstreamer</arg>
          <arg choice="plain">-Dmedia=ffmpeg</arg>
          <arg choice="plain">-Dmedia=all</arg>
          <arg choice="plain">-Dmedia=none</arg>
        </group>
        <sbr/>
        <group>
          <arg choice="plain">-Dvulkan=yes</arg>
          <arg choice="plain">-Dvulkan=no</arg>
          <arg choice="plain">-Dvulkan=auto</arg>
        </group>
        <sbr/>
        <group>
          <arg choice="plain">-Dxinerama=yes</arg>
          <arg choice="plain">-Dxinerama=no</arg>
          <arg choice="plain">-Dxinerama=auto</arg>
        </group>
        <sbr/>
        <group>
          <arg choice="plain">-Dcloudproviders=true</arg>
          <arg choice="plain">-Dcloudproviders=false</arg>
        </group>
        <sbr/>
        <group>
          <arg choice="plain">-Dprint-backends=all</arg>
          <arg choice="plain">-Dprint-backends=none</arg>
          <arg choice="plain">-Dprint-backends=cups,lpr,...</arg>
        </group>
        <sbr/>
        <group>
          <arg choice="plain">-Dcolord=yes</arg>
          <arg choice="plain">-Dcolord=no</arg>
          <arg choice="plain">-Dcolord=auto</arg>
        </group>
        <sbr/>
        <group>
          <arg choice="plain">-Dgtk_doc=true</arg>
          <arg choice="plain">-Dgtk_doc=false</arg>
        </group>
        <sbr/>
        <group>
          <arg choice="plain">-Dman-pages=true</arg>
          <arg choice="plain">-Dman-pages=false</arg>
        </group>
        <sbr/>
        <group>
          <arg choice="plain">-Dintrospection=true</arg>
          <arg choice="plain">-Dintrospection=false</arg>
        </group>
      </cmdsynopsis>
    </para>

    <formalpara>
      <title><systemitem>xinerama</systemitem></title>

      <para>
        By default GTK will try to link against the Xinerama libraries
        if they are found. This options can be used to explicitly control
        whether Xinerama should be used.
      </para>
    </formalpara>

    <formalpara>
      <title><systemitem>gtk_doc</systemitem> and
        <systemitem>man-pages</systemitem></title>

      <para>
        The <application>gtk-doc</application> package is
        used to generate the reference documentation included
        with GTK. By default support for <application>gtk-doc</application>
        is disabled because it requires various extra dependencies
        to be installed. If you have
        <application>gtk-doc</application> installed and
        are modifying GTK, you may want to enable
        <application>gtk-doc</application> support by passing
        in <systemitem>gtk_doc</systemitem>.
      </para>
      <para>
        Additionally, some tools provided by GTK have their own
        manual pages generated using a similar set of dependencies;
        if you have <application>xsltproc</application> then you
        can generate manual pages by passing <systemitem>man-pages</systemitem>
        when configuring the build.
      </para>
    </formalpara>

    <formalpara>
      <title><systemitem>print-backends</systemitem></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>
    </formalpara>

    <formalpara>
      <title><systemitem>x11-backend</systemitem>,
        <systemitem>win32-backend</systemitem>,
        <systemitem>quartz-backend</systemitem>,
        <systemitem>broadway-backend</systemitem> and
        <systemitem>wayland-backend</systemitem></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 quartz. If any backend is explicitly enabled or disabled,
        no other platform will be enabled automatically.
      </para>
    </formalpara>

    <formalpara>
      <title><systemitem>introspection</systemitem></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>
    </formalpara>

    <formalpara>
      <title><systemitem>build-tests</systemitem>,
             <systemitem>install-tests</systemitem>,
             <systemitem>demos</systemitem></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>
    </formalpara>

  </refsect1>

</refentry>