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 - <systemitem>--disable-modules</systemitem> and - <systemitem>--enable-modules</systemitem> + <systemitem>disable-modules</systemitem> 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. - <systemitem>--with-included-immodules</systemitem> + <systemitem>with-included-immodules</systemitem> This option allows you to specify which input method modules you @@ -452,101 +414,18 @@ How to compile GTK+ itself - <systemitem>--enable-debug</systemitem> + <systemitem>enable-xinerama</systemitem> - 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. - <systemitem>--disable-Bsymbolic</systemitem> and - <systemitem>--enable-Bsymbolic</systemitem> - - 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. - - - - - <systemitem>--enable-explicit-deps</systemitem> and - <systemitem>--disable-explicit-deps</systemitem> - - 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. - - - - - <systemitem>--disable-xkb</systemitem> and - <systemitem>--enable-xkb</systemitem> - - - 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. - - - - - <systemitem>--disable-xinerama</systemitem> and - <systemitem>--enable-xinerama</systemitem> - - - 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. - - - - - <systemitem>--disable-xinput</systemitem> and - <systemitem>--enable-xinput</systemitem> - - 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. - - - - - <systemitem>--disable-gtk-doc</systemitem> and - <systemitem>--enable-gtk-doc</systemitem> + <systemitem>enable-documentation</systemitem> and + <systemitem>enable-man-pages</systemitem> 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. - <systemitem>--disable-cups</systemitem> and - <systemitem>--enable-cups</systemitem> + <systemitem>enable-cups-print-backend</systemitem>, + <systemitem>enable-papi-print-backend</systemitem>, + <systemitem>enable-cloudprint-print-backend</systemitem>, and + <systemitem>enable-test-print-backend</systemitem> - 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. - <systemitem>--disable-papi</systemitem> and - <systemitem>--enable-papi</systemitem> + <systemitem>-Denable-x11-backend</systemitem>, + <systemitem>-Denable-win32-backend</systemitem>, + <systemitem>-Denable-quartz-backend</systemitem>, + <systemitem>-Denable-broadway-backend</systemitem>, + <systemitem>-Denable-wayland-backend</systemitem>, and + <systemitem>-Denable-mir-backend</systemitem> - 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. - - <systemitem>--disable-packagekit</systemitem> and - <systemitem>--enable-packagekit</systemitem> - - 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. - - - - - <systemitem>--enable-x11-backend</systemitem>, - <systemitem>--disable-x11-backend</systemitem>, - <systemitem>--enable-win32-backend</systemitem>, - <systemitem>--disable-win32-backend</systemitem>, - <systemitem>--enable-quartz-backend</systemitem>, - <systemitem>--disable-quartz-backend</systemitem>, - <systemitem>--enable-broadway-backend</systemitem>, - <systemitem>--disable-broadway-backend</systemitem>, - <systemitem>--enable-wayland-backend</systemitem>, - <systemitem>--disable-wayland-backend</systemitem> - <systemitem>--enable-mir-backend</systemitem>, and - <systemitem>--disable-mir-backend</systemitem> - - - 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. - - - - - <systemitem>--enable-introspection</systemitem> - - - Build with or without introspection support. - The default is 'auto'. - - - - - <systemitem>--enable-installed-tests</systemitem> or - <systemitem>--disable-installed-tests</systemitem> - - - 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. - -