413 lines
16 KiB
XML
413 lines
16 KiB
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+ on UNIX-like systems</title>
|
|
<para>
|
|
This chapter covers building and installing GTK+ on UNIX and
|
|
UNIX-like systems such as Linux. Compiling GTK+ on Microsoft
|
|
Windows is different in detail and somewhat more difficult to
|
|
get going since the necessary tools aren't included with
|
|
the operating system.
|
|
</para>
|
|
<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>
|
|
On all supported platforms, GTK+ uses the Meson build system.
|
|
</para>
|
|
<programlisting>
|
|
tar xvfJ gtk+-3.24.0.tar.xz
|
|
</programlisting>
|
|
<para>
|
|
Once you have extracted the files from the release archive, and
|
|
you entered the source directory, you can use the <command>meson</command>
|
|
command to configure the project.
|
|
</para>
|
|
<programlisting>
|
|
meson setup --prefix=/opt/gtk _builddir .
|
|
</programlisting>
|
|
<para>
|
|
A full list of options can be found by running
|
|
<command>meson configure</command> from within the build directory.
|
|
In general, the defaults are right and should be trusted.
|
|
</para>
|
|
<para>
|
|
After you've run <command>meson setup</command>, you then run the
|
|
<command>meson compile</command> command to build the project and
|
|
install it.
|
|
</para>
|
|
<programlisting>
|
|
meson compile -C _builddir
|
|
meson install -C _builddir
|
|
</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 <command>meson install</command>.
|
|
</para>
|
|
<para>
|
|
Several environment variables are useful to pass to set before
|
|
running configure. <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="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. The main tool needed during the build process (as
|
|
differentiated from the tools used in when creating GTK+
|
|
mentioned above such as <application>meson</application>)
|
|
is <command>pkg-config</command>.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<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>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<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 <ulink url="https://gitlab.gnome.org/GNOME/glib">GLib library</ulink>
|
|
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 <ulink url="https://download.gnome.org/sources/glib/">here</ulink>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <ulink url="https://gitlab.gnome.org/GNOME/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="https://gitlab.gnome.org/GNOME/pango">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://gitlab.gnome.org/GNOME/atk">ATK</ulink> 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://gitlab.gnome.org/GNOME/gobject-introspection">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 all of their
|
|
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.
|
|
</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>, GNU make,
|
|
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 a Linux system, it's quite likely you'll have all of these
|
|
installed already except for <command>pkg-config</command>.
|
|
</para>
|
|
<para>
|
|
Then build and install the GTK+ libraries in the order:
|
|
GLib, Pango, ATK, then GTK+. For each library, follow the
|
|
steps of <literal>configure</literal>, <literal>make</literal>,
|
|
<literal>make install</literal> mentioned above. 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>gtk3-demo</command> program that
|
|
GTK+ installs.
|
|
</para>
|
|
<para>
|
|
If either the <command>meson setup</command> or the
|
|
<command>meson compile</command> commands fail, look closely
|
|
at the error messages printed; these will often provide useful
|
|
information as to what went wrong.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="extra-configuration-options">
|
|
<title>Extra Configuration Options</title>
|
|
|
|
<para>
|
|
In addition to the standard <command>meson</command> options
|
|
when configuring the GTK+ project, you have a number of
|
|
additional arguments. (Command line arguments for the other
|
|
libraries are described in the documentation distributed with
|
|
the those libraries.)
|
|
|
|
<cmdsynopsis>
|
|
<command>meson setup</command>
|
|
<sbr/>
|
|
<group>
|
|
<arg choice="plain">-Dxinerama=[yes/no/auto]</arg>
|
|
</group>
|
|
<sbr/>
|
|
<group>
|
|
<arg choice="plain">-Dgtk_doc=[false/true]</arg>
|
|
</group>
|
|
<sbr/>
|
|
<group>
|
|
<arg choice="plain">-Dprint_backends=["cups,file,lpr,papi,test,auto"]</arg>
|
|
</group>
|
|
<sbr/>
|
|
<group>
|
|
<arg choice="plain">-Dx11_backend=[false/true]</arg>
|
|
</group>
|
|
<sbr/>
|
|
<group>
|
|
<arg choice="plain">-Dwin32_backend=[false/true]</arg>
|
|
</group>
|
|
<sbr/>
|
|
<group>
|
|
<arg choice="plain">-Dquartz_backend=[false/true]</arg>
|
|
</group>
|
|
<sbr/>
|
|
<group>
|
|
<arg choice="plain">-Dbroadway_backend=[false/true]</arg>
|
|
</group>
|
|
<sbr/>
|
|
<group>
|
|
<arg choice="plain">-Dwayland_backend=[false/true]</arg>
|
|
</group>
|
|
<sbr/>
|
|
<group>
|
|
<arg choice="plain">-Dintrospection=[false/true]</arg>
|
|
</group>
|
|
<sbr/>
|
|
<group>
|
|
<arg choice="plain">-Dinstalled_tests=[false/true]</arg>
|
|
</group>
|
|
</cmdsynopsis>
|
|
</para>
|
|
|
|
<formalpara>
|
|
<title><systemitem>-Dxinerama</systemitem></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>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><systemitem>-Dgtk_doc</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>-Dgtk_doc=true</systemitem>. If not
|
|
enabled, pre-generated HTML files distributed with GTK+
|
|
will be installed.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><systemitem>-Dprint_backends</systemitem></title>
|
|
|
|
<para>
|
|
By default GTK will try to build the appropriate print backend
|
|
for the system. You can specify the print backends manually to
|
|
explicitly control which backends should be build.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><systemitem>-Dx11_backend</systemitem>,
|
|
<systemitem>-Dwin32_backend</systemitem>,
|
|
<systemitem>-Dquartz_backend</systemitem>,
|
|
<systemitem>-Dbroadway_backend</systemitem>,
|
|
<systemitem>-Dwayland_backend</systemitem></title>
|
|
|
|
<para>
|
|
Enable specific backends for GDK. If none of these options
|
|
are given, the x11 backend will be enabled by default,
|
|
unless the platform is Windows, in which case the default is
|
|
win32. If any backend is explicitly enabled or disabled, no
|
|
other platform will be enabled automatically. Other
|
|
supported backends are the quartz backend for macOS, and the
|
|
HTML-based Broadway backend.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><systemitem>-Dintrospection</systemitem></title>
|
|
|
|
<para>
|
|
Build with or without introspection support.
|
|
The default is 'true'.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><systemitem>-Dinstalled-tests</systemitem></title>
|
|
|
|
<para>
|
|
Whether to install tests on the system. If enabled, tests
|
|
and their data are installed in <filename>${libexecdir}/gtk+/installed-tests</filename>.
|
|
Metadata for the tests is installed in <filename>${prefix}/share/installed-tests/gtk+</filename>.
|
|
To run the installed tests, <command>gnome-desktop-testing-runner</command>
|
|
can be used.
|
|
</para>
|
|
</formalpara>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<!-- Local Variables: -->
|
|
<!-- sgml-parent-document: ("gtk-docs.sgml" "chapter" "refentry") -->
|
|
<!-- End: -->
|