diff --git a/docs/reference/gtk/building.sgml b/docs/reference/gtk/building.sgml
index eb4232bbba..fd5f076187 100644
--- a/docs/reference/gtk/building.sgml
+++ b/docs/reference/gtk/building.sgml
@@ -16,14 +16,7 @@ How to compile GTK+ itself
- Building GTK+ on UNIX-like systems
-
- 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.
-
+ Building GTK+
Before we get into the details of how to compile GTK+, we should
mention that in many cases, binary packages of GTK+ prebuilt for
@@ -35,64 +28,51 @@ How to compile GTK+ itself
already.
- On UNIX-like systems GTK+ uses the standard GNU build system,
- using autoconf for package
- configuration and resolving portability issues,
- automake for building makefiles that
- comply with the GNU Coding Standards, and
- libtool for building shared libraries
- on multiple platforms.
+ In order to build GTK+, you will need meson
+ installed on your system. On Linux, and other UNIX-like operating
+ systems, you will also need ninja. This
+ guide does not cover how to install these two requirements, but you
+ can refer to the Meson website
+ for more information. The Ninja
+ build tool is also usable on various operating systems, so we will
+ refer to it in the examples.
- If you are building GTK+ from the distributed source packages,
- then you won't need these tools installed; the necessary pieces
- of the tools are already included in the source packages. But
- it's useful to know a bit about how packages that use these
- tools work. A source package is distributed as a
- tar.bz2 or tar.xz file
- which you unpack into a directory full of the source files as follows:
+ If you are building GTK+ from a source distribution or from a Git
+ clone, you will need to use meson to
+ configure the project. The most commonly useful argument is the
+ --prefix one, which determines where the
+ files will go once installed. To install GTK+ under a prefix
+ like /opt/gtk you would run Meson as:
-
- tar xvfj gtk+-3.2.0.tar.bz2
- tar xvfJ gtk+-3.2.0.tar.xz
-
+
+
+ meson --prefix /opt/gtk builddir
+
+
- In the toplevel directory that is created, there will be
- a shell script called configure which
- you then run to take the template makefiles called
- Makefile.in in the package and create
- makefiles customized for your operating system.
- The configure script can be passed
- various command line arguments to determine how the package
- is built and installed. The most commonly useful argument is
- the --prefix argument which
- determines where the package is installed. To install a package
- in /opt/gtk you would run configure as:
+ Meson will create the builddir directory and
+ place all the build artefacts there.
-
- ./configure --prefix=/opt/gtk
-
- A full list of options can be found by running
- configure with the
- --help argument. In general, the defaults are
- right and should be trusted. After you've run
- configure, you then run the
- make command to build the package and install
- it.
+ You can get a list of all available options for the build by
+ running mesonconf.
-
- make
- make install
-
+
+ After Meson successfully configured the build directory, you then
+ can run the build, using Ninja:
+
+
+
+ cd builddir
+ ninja
+ ninja install
+
+
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 make install. Also, if you are
- installing in a system directory, on some systems (such as
- Linux), you will need to run ldconfig after
- make install so that the newly installed
- libraries will be found.
+ running ninja install.
Several environment variables are useful to pass to set before
@@ -131,35 +111,21 @@ How to compile GTK+ itself
Before you can compile the GTK+ widget toolkit, you need to have
various other tools and libraries installed on your
- system. The two tools needed during the build process (as
- differentiated from the tools used in when creating GTK+
- mentioned above such as autoconf)
- are pkg-config and GNU make.
+ system. Dependencies of GTK+ have their own build systems, so
+ you will need to refer to their own installation instructions.
+
+
+ A particular important tool used by GTK+ to find its dependencies
+ is pkg-config.
+
+
+ pkg-config
+ is a tool for tracking the compilation flags needed for
+ libraries that are used by the GTK+ libraries. (For each
+ library, a small .pc text file is installed
+ in a standard location that contains the compilation flags
+ needed for that library along with version number information.)
-
-
-
- pkg-config
- is a tool for tracking the compilation flags needed for
- libraries that are used by the GTK+ libraries. (For each
- library, a small .pc text file is installed
- in a standard location that contains the compilation flags
- needed for that library along with version number information.)
-
-
-
-
- The GTK+ makefiles will mostly work with different versions
- of make, however, there tends to be
- a few incompatibilities, so the GTK+ team recommends
- installing GNU
- make if you don't already have it on your system
- and using it. (It may be called gmake
- rather than make.)
-
-
-
Some of the libraries that GTK+ depends on are maintained by
by the GTK+ team: GLib, GdkPixbuf, Pango, ATK and GObject Introspection.
@@ -171,17 +137,14 @@ How to compile GTK+ itself
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 the GTK+
- FTP site or
- here.
+ from here.
The GdkPixbuf library
provides facilities for loading images in a variety of file formats.
- It is available
- here.
+ It is available here.
@@ -250,15 +213,22 @@ How to compile GTK+ itself
Cairo
is a graphics library that supports vector graphics and image
- compositing. Both Pango and GTK+ use cairo for all of their
- drawing.
+ compositing. Both Pango and GTK+ use Cairo for drawing.
libepoxy
is a library that abstracts the differences between different
- OpenGL libraries. GTK+ uses it for cross-platform GL support.
+ OpenGL libraries. GTK+ uses it for cross-platform GL support
+ and for its own drawing.
+
+
+
+
+ Graphene
+ is a library that provides vector and matrix types for 2D and
+ 3D transformations. GTK+ uses it internally for drawing.
@@ -284,35 +254,32 @@ How to compile GTK+ itself
Building and testing GTK+
First make sure that you have the necessary external
- dependencies installed: pkg-config, GNU make,
+ dependencies installed: pkg-config, 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 a Linux system, it's quite likely you'll have all of these
- installed already except for pkg-config.
+ 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.
Then build and install the GTK+ libraries in the order:
- GLib, Pango, ATK, then GTK+. For each library, follow the
- steps of configure, make,
- make install mentioned above. If you're
- lucky, this will all go smoothly, and you'll be ready to
- start compiling your own GTK+
- applications. You can test your GTK+ installation
- by running the gtk3-demo program that
+ 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 start compiling
+ your own GTK+ applications. You can test your GTK+ installation
+ by running the gtk4-demo program that
GTK+ installs.
- If one of the configure scripts fails or running
- make fails, look closely at the error
- messages printed; these will often provide useful information
- as to what went wrong. When configure
- fails, extra information, such as errors that a test compilation
- ran into, is found in the file config.log.
- Looking at the last couple of hundred lines in this file will
- frequently make clear what went wrong. If all else fails, you
- can ask for help on the gtk-list mailing list.
+ 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 for more information.
@@ -320,129 +287,124 @@ How to compile GTK+ itself
Extra Configuration Options
- In addition to the normal options, the
- configure script for the GTK+ library
- supports a number of additional arguments. (Command line
- arguments for the other GTK+ libraries are described in
- the documentation distributed with the those libraries.)
+ In addition to the normal options provided by Meson, GTK+ defines
+ various arguments that modify what should be built.
- configure
+ meson
- --disable-modules
- --enable-modules
+ -Ddisable-modules=true
+ -Ddisable-modules=false
- --with-included-immodules=MODULE1,MODULE2,...
+ -Dwith-included-immodules=MODULE1,MODULE2,...
+ -Dwith-included-immodules=all
+ -Dwith-included-immodules=none
- --enable-debug=[no/minimum/yes]
+ -Denable-documentation=true
+ -Denable-documentation=false
- --disable-Bsymbolic
- --enable-Bsymbolic
+ -Denable-man-pages=true
+ -Denable-man-pages=false
- --disable-xkb
- --enable-xkb
+ -Denable-cups-print-backend=yes
+ -Denable-cups-print-backend=no
+ -Denable-cups-print-backend=auto
- --disable-xinerama
- --enable-xinerama
+ -Denable-papi-print-backend=yes
+ -Denable-papi-print-backend=no
+ -Denable-papi-print-backend=auto
- --disable-gtk-doc
- --enable-gtk-doc
+ -Denable-cloudprint-print-backend=yes
+ -Denable-cloudprint-print-backend=no
+ -Denable-cloudprint-print-backend=auto
- --disable-cups
- --enable-cups
+ -Denable-test-print-backend=yes
+ -Denable-test-print-backend=no
+ -Denable-test-print-backend=auto
- --disable-papi
- --enable-papi
+ -Denable-colord=yes
+ -Denable-colord=no
+ -Denable-colord=auto
- --enable-xinput
- --disable-xinput
+ -Denable-vulkan=yes
+ -Denable-vulkan=no
+ -Denable-vulkan=auto
- --enable-packagekit
- --disable-packagekit
+ -Denable-x11-backend=true
+ -Denable-x11-backend=false
- --enable-x11-backend
- --disable-x11-backend
+ -Denable-xinerama=true
+ -Denable-xinerama=false
- --enable-win32-backend
- --disable-win32-backend
+ -Denable-win32-backend=true
+ -Denable-win32-backend=false
- --enable-quartz-backend
- --disable-quartz-backend
+ -Denable-quartz-backend=true
+ -Denable-quartz-backend=false
- --enable-broadway-backend
- --disable-broadway-backend
+ -Denable-broadway-backend=true
+ -Denable-broadway-backend=false
- --enable-wayland-backend
- --disable-wayland-backend
+ -Denable-wayland-backend=true
+ -Denable-wayland-backend=false
- --enable-mir-backend
- --disable-mir-backend
-
-
-
- --enable-introspection=[no/auto/yes]
-
-
-
- --enable-installed-tests
- --disable-installed-tests
+ -Denable-mir-backend=true
+ -Denable-mir-backend=false
- --disable-modules and
- --enable-modules
+ disable-modules
Normally GTK+ will try to build the input method modules
as little shared libraries that are loaded on demand.
- The --disable-modules argument
+ The disable-modules option
indicates that they should all be built statically
into the GTK+ library instead. This is useful for
people who need to produce statically-linked binaries.
- If neither --disable-modules nor
- --enable-modules is specified,
+ If disable-modules is not specified,
then the configure script will try to
auto-detect whether shared modules work on your system.
- --with-included-immodules
+ with-included-immodules
This option allows you to specify which input method modules you
@@ -452,101 +414,18 @@ How to compile GTK+ itself
- --enable-debug
+ enable-xinerama
- Turns on various amounts of debugging support. Setting this to
- 'no' disables g_assert(), g_return_if_fail(), g_return_val_if_fail() and all cast checks between different object types. Setting it
- to 'minimum' disables only cast checks. Setting it to 'yes' enables
- runtime debugging.
- The default is 'minimum'.
- Note that 'no' is fast, but dangerous as it tends to destabilize
- even mostly bug-free software by changing the effect of many bugs
- from simple warnings into fatal crashes. Thus
- should not
- be used for stable releases of GTK+.
+ 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.
- --disable-Bsymbolic and
- --enable-Bsymbolic
-
- The option --disable-Bsymbolic
- turns off the use of the -Bsymbolic-functions linker flag.
- This is only necessary if you want to override GTK+ functions
- by using LD_PRELOAD.
-
-
-
-
- --enable-explicit-deps and
- --disable-explicit-deps
-
- If --enable-explicit-deps is
- specified then GTK+ will write the full set of libraries
- that GTK+ depends upon into its .pc files to be used when
- programs depending on GTK+ are linked. Otherwise, GTK+
- only will include the GTK+ libraries themselves, and
- will depend on system library dependency facilities to
- bring in the other libraries.
- By default GTK+ will disable explicit dependencies unless
- it detects that they are needed on the system. (If you
- specify --enable-static to force
- building of static libraries, then explicit dependencies
- will be written since library dependencies don't work
- for static libraries.) Specifying
- --enable-explicit-deps or
- --enable-static can cause
- compatibility
- problems when libraries that GTK+ depends upon change
- their versions, and should be avoided if possible.
-
-
-
-
- --disable-xkb and
- --enable-xkb
-
-
- By default the configure script will try
- to auto-detect whether the XKB extension is supported by
- the X libraries GTK+ is linked with.
- These options can be used to explicitly control whether
- GTK+ will support the XKB extension.
-
-
-
-
- --disable-xinerama and
- --enable-xinerama
-
-
- By default the configure script will try
- to link against the Xinerama libraries if they are found.
- These options can be used to explicitly control whether
- Xinerama should be used.
-
-
-
-
- --disable-xinput and
- --enable-xinput
-
- Controls whether GTK+ is built with support for the XInput
- or XInput2 extension. These extensions provide an extended
- interface to input devices such as graphics tablets.
- When this support is compiled in, specially written
- GTK+ programs can get access to subpixel positions,
- multiple simultaneous input devices, and extra "axes"
- provided by the device such as pressure and tilt
- information.
-
-
-
-
- --disable-gtk-doc and
- --enable-gtk-doc
+ enable-documentation and
+ enable-man-pages
The gtk-doc package is
@@ -557,93 +436,50 @@ How to compile GTK+ itself
gtk-doc installed and
are modifying GTK+, you may want to enable
gtk-doc support by passing
- in --enable-gtk-doc. If not
- enabled, pre-generated HTML files distributed with GTK+
- will be installed.
+ in enable-documentation.
+
+
+ Additionally, some tools provided by GTK+ have their own
+ manual pages generated using a similar set of dependencies;
+ if you have xsltproc then you
+ can generate manual pages by passing enable-man-pages
+ when configuring the build.
- --disable-cups and
- --enable-cups
+ enable-cups-print-backend,
+ enable-papi-print-backend,
+ enable-cloudprint-print-backend, and
+ enable-test-print-backend
- By default the configure script will try
- to build the cups print backend if the cups libraries are found.
- These options can be used to explicitly control whether
- the cups print backend should be built.
+ By default, GTK+ will try to build various print backends if
+ their dependencies are found. These options can be used to
+ explicitly control whether each print backend should be built
+ or not.
- --disable-papi and
- --enable-papi
+ -Denable-x11-backend,
+ -Denable-win32-backend,
+ -Denable-quartz-backend,
+ -Denable-broadway-backend,
+ -Denable-wayland-backend, and
+ -Denable-mir-backend
- By default the configure script will try
- to build the papi print backend if the papi libraries are found.
- These options can be used to explicitly control whether
- the papi print backend should be built.
+ 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.
-
- --disable-packagekit and
- --enable-packagekit
-
- By default the configure script will try
- to build the PackageKit support for the open-with dialog if
- the PackageKit libraries are found.
- These options can be used to explicitly control whether
- PackageKit support should be built.
-
-
-
-
- --enable-x11-backend,
- --disable-x11-backend,
- --enable-win32-backend,
- --disable-win32-backend,
- --enable-quartz-backend,
- --disable-quartz-backend,
- --enable-broadway-backend,
- --disable-broadway-backend,
- --enable-wayland-backend,
- --disable-wayland-backend
- --enable-mir-backend, and
- --disable-mir-backend
-
-
- Enables 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 OS X.
-
-
-
-
- --enable-introspection
-
-
- Build with or without introspection support.
- The default is 'auto'.
-
-
-
-
- --enable-installed-tests or
- --disable-installed-tests
-
-
- Whether to install tests on the system. If enabled, tests
- and their data are installed in ${libexecdir}/gtk+/installed-tests.
- Metadata for the tests is installed in ${prefix}/share/installed-tests/gtk+.
- To run the installed tests, gnome-desktop-testing-runner
- can be used.
-
-