From b99511ee5524f9009a2dfafe67a4df4dfa31f045 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 24 May 2020 00:04:36 -0400 Subject: [PATCH] docs: Convert building, compiling, running to markdown --- docs/reference/gtk/building.md | 270 ++++++++ docs/reference/gtk/building.xml | 518 --------------- .../gtk/{compiling.xml => compiling.md} | 81 +-- docs/reference/gtk/gtk4-docs.xml | 2 +- docs/reference/gtk/meson.build | 7 +- docs/reference/gtk/running.md | 350 ++++++++++ docs/reference/gtk/running.xml | 601 ------------------ 7 files changed, 645 insertions(+), 1184 deletions(-) create mode 100644 docs/reference/gtk/building.md delete mode 100644 docs/reference/gtk/building.xml rename docs/reference/gtk/{compiling.xml => compiling.md} (61%) create mode 100644 docs/reference/gtk/running.md delete mode 100644 docs/reference/gtk/running.xml diff --git a/docs/reference/gtk/building.md b/docs/reference/gtk/building.md new file mode 100644 index 0000000000..6aa2891b24 --- /dev/null +++ b/docs/reference/gtk/building.md @@ -0,0 +1,270 @@ +# Compiling the GTK Libraries {#gtk-building} + +## 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 +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. + +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](http://mesonbuild.com) for more information. The +[Ninja](https://ninja-build.org) build tool is also usable on +various operating systems, so we will refer to it in the examples. + +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: + +``` +meson setup --prefix /opt/gtk builddir +``` + +Meson will create the `builddir` directory and place all the build +artefacts there. + +You can get a list of all available options for the build by +running `meson configure`. + +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 `ninja install`. + +Several environment variables are useful to pass to set before +running *meson*. `CPPFLAGS` contains options to pass to the C +compiler, and is used to tell the compiler where to look for +include files. The `LDFLAGS` variable is used in a similar fashion +for the linker. Finally the `PKG_CONFIG_PATH` environment variable +contains a search path that `pkg-config` (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 +`/opt/gtk`, you might want to set these variables as: + +``` +CPPFLAGS="-I/opt/gtk/include" +LDFLAGS="-L/opt/gtk/lib" +PKG_CONFIG_PATH="/opt/gtk/lib/pkgconfig" +export CPPFLAGS LDFLAGS PKG_CONFIG_PATH +``` + +You may also need to set the `LD_LIBRARY_PATH` environment variable +so the systems dynamic linker can find the newly installed libraries, +and the `PATH` environment program so that utility binaries installed +by the various libraries will be found. + +``` +LD_LIBRARY_PATH="/opt/gtk/lib" +PATH="/opt/gtk/bin:$PATH" +export LD_LIBRARY_PATH PATH +``` + +## Build types {#build-types} + +Meson has different build types, exposed by the `buildtype` +configuration option. GTK enables and disables functionality +depending on the build type used when calling *meson* to +configure the build. + +### Debug builds + +GTK will enable debugging code paths in both the `debug` and +`debugoptimized` build types. Builds with `buildtype` set to +`debug` will additionally enable consistency checks on the +internal state of the toolkit. + +It is recommended to use the `debug` or `debugoptimized` build +types when developing GTK itself. Additionally, `debug` builds of +GTK are recommended for profiling and debugging GTK applications, +as they include additional validation of the internal state. + +The `debugoptimized` build type is the default for GTK if no build +type is specified when calling *meson*. + +### Release builds + +The `release` build type will disable debugging code paths and +additional run time safeties, like checked casts for object +instances. + +The `plain` 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. + +## Dependencies {#dependencies} + +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. + +A particular important tool used by GTK to find its dependencies +is `pkg-config`. + +[pkg-config](https://www.freedesktop.org/wiki/Software/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.) + +Some of the libraries that GTK depends on are maintained by the +GTK team: GLib, GdkPixbuf, Pango, ATK and GObject Introspection. +Other libraries are maintained separately. + +- 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 [here](https://download.gnome.org/sources/glib/). +- The [GdkPixbuf](https://git.gnome.org/browse/gdk-pixbuf/) + library provides facilities for loading images in a variety of + file formats. It is available [here](ttps://download.gnome.org/sources/gdk-pixbuf/). +- [Pango](http://www.pango.org) is a library for internationalized + text handling. It is available [here](https://download.gnome.org/sources/pango/). +- 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 [here](https://download.gnome.org/sources/atk/). +- [GObject Introspection](https://wiki.gnome.org/Projects/GObjectIntrospection) + is a framework for making introspection data available to language + bindings. It is available [here](https://download.gnome.org/sources/gobject-introspection/). +- The [GNU libiconv](https://www.gnu.org/software/libiconv/) library + is needed to build GLib if your system doesn't have the iconv() + function for doing conversion between character encodings. Most + modern systems should have iconv(). +- The libintl library from the [GNU gettext](https://www.gnu.org/software/gettext/) + package is needed if your system doesn't have the gettext() + functionality for handling message translation databases. +- 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. +- The [fontconfig](https://www.freedesktop.org/wiki/Software/fontconfig/) + library provides Pango with a standard way of locating + fonts and matching them against font names. +- [Cairo](https://www.cairographics.org) is a graphics library that + supports vector graphics and image compositing. Both Pango and GTK + use Cairo for drawing. +- [libepoxy](https://github.com/anholt/libepoxy) is a library that + abstracts the differences between different OpenGL libraries. GTK + uses it for cross-platform GL support and for its own drawing. +- [Graphene](http://ebassi.github.io/graphene/) is a library that + provides vector and matrix types for 2D and 3D transformations. + GTK uses it internally for drawing. +- The [Wayland](https://wayland.freedesktop.org) libraries are needed + to build GTK with the Wayland backend. +- The [shared-mime-info](https://www.freedesktop.org/wiki/Software/shared-mime-info) + 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 + `XDG_DATA_DIRS` set accordingly at configure time. Otherwise, + gdk-pixbuf falls back to its built-in mime type detection. + +## Building and testing GTK {#building} + +First make sure that you have the necessary external +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 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, 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](#gtk-compiling). You can test your GTK installation +by running the `gtk4-demo` program that GTK installs. + +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 forums](#gtk-resources). + +## Extra Configuration Options {#extra-configuration-options} + +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 `meson` +as `-Doption=value`. Most of the time, the value can +be `true` or `false`. To see a summary of all supported +options and their allowed values, run +``` +meson configure builddir +``` + +### `xinerama` + +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. + +### `gtk_doc` and `man-pages` + +The *gtk-doc* package is used to generate the reference documentation +included with GTK. By default support for *gtk-doc* is disabled +because it requires various extra dependencies to be installed. +If you have *gtk-doc* installed and are modifying GTK, you may want +to enable *gtk-doc* support by passing in `-Dgtk_doc=true`. + +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 `-Dman-pages=true` when configuring the build. + +### `print-backends` + +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. + +### `x11-backend`, `win32-backend`, `broadway-backend`, `wayland-backend` and `quartz-backend` + +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. + +### `introspection` + +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. + +### `build-tests`, `install-tests`, `demos` + +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. diff --git a/docs/reference/gtk/building.xml b/docs/reference/gtk/building.xml deleted file mode 100644 index 49b45b1d65..0000000000 --- a/docs/reference/gtk/building.xml +++ /dev/null @@ -1,518 +0,0 @@ - - - - -Compiling the GTK libraries -3 -GTK Library - - - -Compiling the GTK Libraries - -How to compile GTK itself - - - - 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 - 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. - - - 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 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: - - - - meson setup --prefix /opt/gtk builddir - - - - Meson will create the builddir directory and - place all the build artefacts there. - - - You can get a list of all available options for the build by - running meson configure. - - - 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 ninja install. - - - Several environment variables are useful to pass to set before - running meson. CPPFLAGS - contains options to pass to the C compiler, and is used to tell - the compiler where to look for include files. The LDFLAGS - variable is used in a similar fashion for the linker. Finally the - PKG_CONFIG_PATH environment variable contains - a search path that pkg-config (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 /opt/gtk, you - might want to set these variables as: - - - CPPFLAGS="-I/opt/gtk/include" - LDFLAGS="-L/opt/gtk/lib" - PKG_CONFIG_PATH="/opt/gtk/lib/pkgconfig" - export CPPFLAGS LDFLAGS PKG_CONFIG_PATH - - - You may also need to set the LD_LIBRARY_PATH - environment variable so the systems dynamic linker can find - the newly installed libraries, and the PATH - environment program so that utility binaries installed by - the various libraries will be found. - - - LD_LIBRARY_PATH="/opt/gtk/lib" - PATH="/opt/gtk/bin:$PATH" - export LD_LIBRARY_PATH PATH - - - - - Build types - - Meson has different build types, exposed by the buildtype - configuration option. GTK enables and disables functionality depending on - the build type used when calling meson to - configure the build. - - - <systemitem>debug</systemitem> and <systemitem>debugoptimized</systemitem> - - - GTK will enable debugging code paths in both the - debug and debugoptimized - build types. Builds with buildtype set - to debug will additionally enable - consistency checks on the internal state of the toolkit. - - - - It is recommended to use the debug or - debugoptimized build types when developing - GTK itself. Additionally, debug builds of - GTK are recommended for profiling and debugging GTK applications, - as they include additional validation of the internal state. - - - - The debugoptimized build type is the - default for GTK if no build type is specified when calling - meson - - - - - <systemitem>release</systemitem> - - - The release build type will disable - debugging code paths and additional run time safeties, like - checked casts for object instances. - - - - - The plain 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. - - - - - Dependencies - - 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. - - - 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.) - - - 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. - - - - - 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 here. - - - - - The GdkPixbuf library - provides facilities for loading images in a variety of file formats. - It is available here. - - - - - Pango is a library - for internationalized text handling. It is available - here. - - - - - 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 - here. - - - - - Gobject Introspection - is a framework for making introspection data available to - language bindings. It is available - here. - - - - - External dependencies - - - The GNU - libiconv library is needed to build GLib if your - system doesn't have the iconv() - function for doing conversion between character - encodings. Most modern systems should have - iconv(). - - - - - The libintl library from the GNU gettext - package is needed if your system doesn't have the - gettext() functionality for handling - message translation databases. - - - - - 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. - - - - - The fontconfig - library provides Pango with a standard way of locating - fonts and matching them against font names. - - - - - Cairo - is a graphics library that supports vector graphics and image - 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 - 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. - - - - - The Wayland libraries - are needed to build GTK with the Wayland backend. - - - - - The shared-mime-info - 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 - XDG_DATA_DIRS set accordingly at configure time. - Otherwise, gdk-pixbuf falls back to its built-in mime type detection. - - - - - - Building and testing GTK - - First make sure that you have the necessary external - 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 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, 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 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. - - - - - Extra Configuration Options - - - In addition to the normal options provided by Meson, GTK defines - various arguments that modify what should be built. - - - meson - - - -Dx11-backend=true - -Dx11-backend=false - - - - -Dwayland-backend=true - -Dwayland-backend=false - - - - -Dbroadway-backend=true - -Dbroadway-backend=false - - - - -Dwin32-backend=true - -Dwin32-backend=false - - - - -Dquartz-backend=true - -Dquartz-backend=false - - - - -Dmedia=gstreamer - -Dmedia=ffmpeg - -Dmedia=all - -Dmedia=none - - - - -Dvulkan=yes - -Dvulkan=no - -Dvulkan=auto - - - - -Dxinerama=yes - -Dxinerama=no - -Dxinerama=auto - - - - -Dcloudproviders=true - -Dcloudproviders=false - - - - -Dprint-backends=all - -Dprint-backends=none - -Dprint-backends=cups,lpr,... - - - - -Dcolord=yes - -Dcolord=no - -Dcolord=auto - - - - -Dgtk_doc=true - -Dgtk_doc=false - - - - -Dman-pages=true - -Dman-pages=false - - - - -Dintrospection=true - -Dintrospection=false - - - - - - <systemitem>xinerama</systemitem> - - - 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>gtk_doc</systemitem> and - <systemitem>man-pages</systemitem> - - - The gtk-doc package is - used to generate the reference documentation included - with GTK. By default support for gtk-doc - is disabled because it requires various extra dependencies - to be installed. If you have - gtk-doc installed and - are modifying GTK, you may want to enable - gtk-doc support by passing - in gtk_doc. - - - 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 man-pages - when configuring the build. - - - - - <systemitem>print-backends</systemitem> - - - 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. - - - - - <systemitem>x11-backend</systemitem>, - <systemitem>win32-backend</systemitem>, - <systemitem>quartz-backend</systemitem>, - <systemitem>broadway-backend</systemitem> and - <systemitem>wayland-backend</systemitem> - - - 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>introspection</systemitem> - - - 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. - - - - - <systemitem>build-tests</systemitem>, - <systemitem>install-tests</systemitem>, - <systemitem>demos</systemitem> - - - 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. - - - - - - diff --git a/docs/reference/gtk/compiling.xml b/docs/reference/gtk/compiling.md similarity index 61% rename from docs/reference/gtk/compiling.xml rename to docs/reference/gtk/compiling.md index 25ea551120..f0351029fd 100644 --- a/docs/reference/gtk/compiling.xml +++ b/docs/reference/gtk/compiling.md @@ -1,94 +1,55 @@ - - - - -Compiling GTK Applications -3 -GTK Library - +# Compiling GTK Applications on UNIX {#gtk-compiling} - -Compiling GTK Applications - -How to compile your GTK application - - - - -Compiling GTK Applications on UNIX - - To compile a GTK application, you need to tell the compiler where to find the GTK header files and libraries. This is done with the -pkg-config utility. - - -The following interactive shell session demonstrates how -pkg-config is used (the actual output on -your system may be different): - +`pkg-config` utility. + +The following interactive shell session demonstrates how `pkg-config` +is used (the actual output on your system may be different): + +``` $ pkg-config --cflags gtk4 -pthread -I/usr/include/gtk-4.0 -I/usr/lib64/gtk-4.0/include -I/usr/include/atk-1.0 -I/usr/include/cairo -I/usr/include/pango-1.0 -I/usr/include/glib-2.0 -I/usr/lib64/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng12 $ pkg-config --libs gtk4 -pthread -lgtk-4 -lgdk-4 -latk-1.0 -lgio-2.0 -lpangoft2-1.0 -lgdk_pixbuf-2.0 -lpangocairo-1.0 -lcairo -lpango-1.0 -lfreetype -lfontconfig -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt -lglib-2.0 - - - +``` The simplest way to compile a program is to use the "backticks" feature of the shell. If you enclose a command in backticks -(not single quotes), then its output will be -substituted into the command line before execution. So to compile -a GTK Hello, World, you would type the following: - +(*not single quotes*), then its output will be substituted into the +command line before execution. So to compile a GTK Hello, World, you +would type the following: +``` $ cc `pkg-config --cflags gtk4` hello.c -o hello `pkg-config --libs gtk4` - - - - +``` Deprecated GTK functions are annotated to make the compiler emit warnings when they are used (e.g. with gcc, you need to use the -Wdeprecated-declarations option). If these warnings are problematic, they can be turned off by defining the preprocessor symbol %GDK_DISABLE_DEPRECATION_WARNINGS by using the commandline -option -DGDK_DISABLE_DEPRECATION_WARNINGS - +option `-DGDK_DISABLE_DEPRECATION_WARNINGS`. - GTK deprecation annotations are versioned; by defining the macros %GDK_VERSION_MIN_REQUIRED and %GDK_VERSION_MAX_ALLOWED, you can specify the range of GTK versions whose API you want to use. APIs that were deprecated before or introduced after this range will trigger compiler warnings. - - Here is how you would compile hello.c if you want to allow it to use symbols that were not deprecated in 4.2: - +``` $ cc `pkg-config --cflags gtk4` -DGDK_VERSION_MIN_REQIRED=GDK_VERSION_4_2 hello.c -o hello `pkg-config --libs gtk4` - - +``` - And here is how you would compile hello.c if you don't want it to use any symbols that were introduced after 4.2: - +``` $ cc `pkg-config --cflags gtk4` -DGDK_VERSION_MAX_ALLOWED=GDK_VERSION_4_2 hello.c -o hello `pkg-config --libs gtk4` - - - - +``` The older deprecation mechanism of hiding deprecated interfaces entirely from the compiler by using the preprocessor symbol GTK_DISABLE_DEPRECATED is still used for deprecated macros, enumeration values, etc. To detect uses of these in your code, -use the commandline option -DGTK_DISABLE_DEPRECATED. +use the commandline option `-DGTK_DISABLE_DEPRECATED`. There are similar symbols GDK_DISABLE_DEPRECATED, -GDK_PIXBUF_DISABLE_DEPRECATED and G_DISABLE_DEPRECATED for GDK, GdkPixbuf and -GLib. - - - - +GDK_PIXBUF_DISABLE_DEPRECATED and G_DISABLE_DEPRECATED for GDK, +GdkPixbuf and GLib. diff --git a/docs/reference/gtk/gtk4-docs.xml b/docs/reference/gtk/gtk4-docs.xml index a0ec153bbd..18dd293336 100644 --- a/docs/reference/gtk/gtk4-docs.xml +++ b/docs/reference/gtk/gtk4-docs.xml @@ -419,7 +419,7 @@ GTK Platform Support - + diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build index 13b4072023..dadb199297 100644 --- a/docs/reference/gtk/meson.build +++ b/docs/reference/gtk/meson.build @@ -341,8 +341,6 @@ images = [ content_files = [ 'broadway.xml', - 'building.xml', - 'compiling.xml', 'glossary.xml', 'gtk4-broadwayd.xml', 'gtk4-builder-tool.xml', @@ -359,7 +357,6 @@ content_files = [ 'overview.xml', 'question_index.xml', 'resources.xml', - 'running.xml', 'text_widget.xml', 'tree_widget.xml', 'visual_index.xml', @@ -369,7 +366,6 @@ content_files = [ ] expand_content_files = [ - 'compiling.xml', 'glossary.xml', 'question_index.xml', 'text_widget.xml', @@ -377,6 +373,9 @@ expand_content_files = [ ] expand_content_md_files = [ + 'building.md', + 'compiling.md', + 'running.md', 'migrating-2to4.md', 'migrating-3to4.md', 'actions.md', diff --git a/docs/reference/gtk/running.md b/docs/reference/gtk/running.md new file mode 100644 index 0000000000..7ac5c811f0 --- /dev/null +++ b/docs/reference/gtk/running.md @@ -0,0 +1,350 @@ +# Running and debugging GTK Applications {#gtk-running} + +## Environment variables + +GTK inspects a number of environment variables in addition to +standard variables like `LANG`, `PATH`, `HOME` or `DISPLAY`; mostly +to determine paths to look for certain files. The [X11]{#x11-envar}, +[Windows]{#win32-envar} and [Broadway]{#broadway-envar} GDK backends +use some additional environment variables. + +### GTK_DEBUG {#GTK_Debug-Options} + +Unless GTK has been configured with `-Ddebug=false`, this variable +can be set to a list of debug options, which cause GTK to print out +different types of debugging information. + +actions + : Actions and menu models +builder + : GtkBuilder support +geometry + : Size allocation +icontheme + : Icon themes +keybindings + : Keybindings +modules + : Loading of modules +printing + : Printing support +size-request + : Size requests +text + : Text widget internals +tree + : Tree widget internals + + A number of keys are influencing behavior instead of just logging: + +interactive + : Open the [interactive debugger](#interactive-debugging) +no-css-cache + : Bypass caching for CSS style properties +touchscreen + : Pretend the pointer is a touchscreen device +updates + : Visual feedback about window updates +resize + : Highlight resizing widgets +layout + : Show layout borders +snapshot + : Include debug render nodes in the generated snapshots + +The special value `all` can be used to turn on all debug options. +The special value `help` can be used to obtain a list of all +supported debug options. + +### GTK_PATH {#gtk-path} + +Specifies a list of directories to search when GTK is looking for +dynamically loaded objects such as input method modules and print +backends. If the path to the dynamically loaded object is given as +an absolute path name, then GTK loads it directly. Otherwise, GTK +goes in turn through the directories in `GTK_PATH`, followed by +the directory `.gtk-4.0` in the user's home directory, followed +by the system default directory, which is `libdir/gtk-4.0/modules`. +(If `GTK_EXE_PREFIX` is defined, `libdir` is `$GTK_EXE_PREFIX/lib`. +Otherwise it is the libdir specified when GTK was configured, usually +`/usr/lib`, or `/usr/local/lib`.) + +For each directory in this list, GTK actually looks in a subdirectory +`directory/version/host/type`. Where `version` is derived from the +version of GTK (use `pkg-config --variable=gtk_binary_version gtk4` +to determine this from a script), `host` is the architecture on +which GTK was built. (use `pkg-config --variable=gtk_host gtk4` to +determine this from a script), and `type` is a directory specific to +the type of modules; currently it can be `modules`, `immodules` or +`printbackends`, corresponding to the types of modules mentioned +above. Either `version`, `host`, or both may be omitted. GTK looks +first in the most specific directory, then in directories with +fewer components. +The components of `GTK_PATH` are separated by the ':' character on +Linux and Unix, and the ';' character on Windows. + +Note that this environment variable is read by GTK 2.x and GTK 3.x +too, which makes it unsuitable for setting it system-wide (or +session-wide), since doing so will cause applications using +different GTK versions to see incompatible modules. + +### GTK_IM_MODULE + +Specifies an IM module to use in preference to the one determined +from the locale. If this isn't set and you are running on the system +that enables `XSETTINGS` and has a value in `Gtk/IMModule`, that will +be used for the default IM module. This also can be a colon-separated +list of input-methods, which GTK will try in turn until it finds one +available on the system. + +### GTK_EXE_PREFIX + +If set, GTK uses `$GTK_EXE_PREFIX/lib` instead of the libdir +configured when GTK was compiled. + +### GTK_DATA_PREFIX + +If set, GTK uses `$GTK_DATA_PREFIX` instead of the prefix +configured when GTK was compiled. + +### GTK_THEME + +If set, makes GTK use the named theme instead of the theme +that is specified by the gtk-theme-name setting. This is intended +mainly for easy debugging of theme issues. + +It is also possible to specify a theme variant to load, by appending +the variant name with a colon, like this: `GTK_THEME=Adwaita:dark`. + +The following environment variables are used by GdkPixbuf, GDK or +Pango, not by GTK itself, but we list them here for completeness +nevertheless. + +### GDK_PIXBUF_MODULE_FILE + +Specifies the file listing the GdkPixbuf loader modules to load. +This environment variable overrides the default value +`libdir/gtk-4.0/4.0.0/loaders.cache` (`libdir` is the sysconfdir +specified when GTK was configured, usually `/usr/lib`.) + +The `loaders.cache` file is generated by the +`gdk-pixbuf-query-loaders` utility. + +### GDK_DEBUG + +Unless GTK has been configured with `-Ddebug=false`, this variable +can be set to a list of debug options, which cause GDK to print out +different types of debugging information. + +cursor + : Information about cursor objects (only win32) +eventloop + : Information about event loop operation (mostly Quartz) +misc + : Miscellaneous information +frames + : Information about the frame clock +settings + : Information about xsettings +selection + : Information about selections +clipboard + : Information about clipboards +dnd + : Information about drag-and-drop +opengl + : Information about OpenGL +vulkan + : Information about Vulkan + +A number of options affect behavior instead of logging: + +nograbs + : Turn off all pointer and keyboard grabs +gl-disable + : Disable OpenGL support +gl-software + : Force OpenGL software rendering +gl-texture-rect + : Use the OpenGL texture rectangle extension, if available +gl-legacy + : Use a legacy OpenGL context +gl-gles + : Use a GLES OpenGL context +vulkan-disable + : Disable Vulkan support +vulkan-validate + : Load the Vulkan validation layer, if available + +The special value `all` can be used to turn on all +debug options. The special value `help` can be used +to obtain a list of all supported debug options. + +### GSK_DEBUG {#GSK-Debug-Options} + +Unless GTK has been configured with `-Ddebug=false`, +this variable can be set to a list of debug options, +which cause GSK to print out different types of debugging +information. + +renderer + : General renderer information +cairo + : cairo renderer information +opengl + : OpenGL renderer information +shaders + : Shaders +surface + : Surfaces +vulkan + : Vulkan renderer information +fallback + : Information about fallbacks +glyphcache + : Information about glyph caching + + A number of options affect behavior instead of logging: + +diff + : Show differences +geometry + : Show borders +full-redraw + : Force full redraws for every frame +sync + : Sync after each frame +vulkan-staging-image + : Use a staging image for Vulkan texture upload +vulkan-staging-buffer + : Use a staging buffer for Vulkan texture upload + +The special value `all` can be used to turn on all +debug options. The special value `help` can be used +to obtain a list of all supported debug options. + +### GDK_BACKEND + +If set, selects the GDK backend to use. Selecting a backend +requires that GTK is compiled with support for that backend. +The following backends can be selected, provided they are +included in the GDK libraries you are using: + +quartz + : Selects the native Quartz backend +win32 + : Selects the native backend for Microsoft Windows +x11 + : Selects the native backend for connecting to X11 servers +broadway + : Selects the Broadway backend for display in web browsers +wayland + : Selects the Wayland backend for connecting to Wayland compositors + +This environment variable can contain a comma-separated list of +backend names, which are tried in order. The list may also contain +a *, which means: try all remaining backends. The special value +`help` can be used to make GDK print out a list of all available +backends. For more information about selecting backends, +see the gdk_display_manager_get() function. + +### GDK_VULKAN_DEVICE + +This variable can be set to the index of a Vulkan device to override +the default selection of the device that is used for Vulkan rendering. +The special value `list` can be used to obtain a list of all Vulkan +devices. + +### GSK_RENDERER + +If set, selects the GSK renderer to use. The following renderers can +be selected, provided they are included in the GTK library you are +using and the GDK backend supports them: + +help + : Prints information about available options +broadway + : Selects the Broadway-backend specific renderer +cairo + : Selects the fallback Cairo renderer +gl + : Selects the default OpenGL renderer +vulkan + : Selects the Vulkan renderer + +### GTK_CSD + +The default value of this environment variable is 1. If changed +to 0, this disables the default use of client-side decorations +on GTK windows, thus making the window manager responsible for +drawing the decorations of windows that do not have a custom +titlebar widget. + +CSD is always used for windows with a custom titlebar widget set, +as the WM should not draw another titlebar or other decorations +around the custom one. + +### XDG_DTA_HOME, XDG_DATA_DIRS + +GTK uses these environment variables to locate icon themes +and MIME information. For more information, see the +[Icon Theme Specification](https://freedesktop.org/Standards/icon-theme-spec) +the [Shared MIME-Info Database](https://freedesktop.org/Standards/shared-mime-info-spec) +and the [Base Directory Specification](https://freedesktop.org/Standards/basedir-spec). + +### DESKTOP_STARTUP_ID + +GTK uses this environment variable to provide startup notification +according to the [Startup Notification Spec](https://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). +Following the specification, GTK unsets this variable after reading +it (to keep it from leaking to child processes). So, if you need its +value for your own purposes, you have to read it before calling +gtk_init(). + +## Interactive debugging {#interactive-debugging} + +![The inspector](inspector.png) + +GTK includes an interactive debugger, called the GTK Inspector, which +lets you explore the widget tree of any GTK application at runtime, +as well as tweak the theme and trigger visual debugging aids. You can +easily try out changes at runtime before putting them into the code. + +Note that the GTK inspector can only show GTK internals. It can not +understand the application-specific logic of a GTK application. Also, +the fact that the GTK inspector is running in the application process +limits what it can do. It is meant as a complement to full-blown +debuggers and system tracing facilities such as DTrace, not as a +replacement. + +To enable the GTK inspector, you can use the Control-Shift-I or +Control-Shift-D keyboard shortcuts, or set the `GTK_DEBUG=interactive` +environment variable. + +There are a few more environment variables that can be set to influence +how the inspector renders its UI. `GTK_INSPECTOR_DISPLAY` and +`GTK_INSPECTOR_RENDERER` determine the GDK display and the GSK +renderer that the inspector is using. + +In some situations, it may be inappropriate to give users access to +the GTK inspector. The keyboard shortcuts can be disabled with the +`enable-inspector-keybinding` key in the `org.gtk.Settings.Debug` +GSettings schema. + +## Profiling {#profiling} + +GTK supports profiling with sysprof. It exports timing information +about frameclock phases and various characteristics of GskRenders +in a format that can be displayed by sysprof or GNOME Builder. + +A simple way to capture data is to set the `GTK_TRACE` environment +variable. When it is set, GTK will write profiling data to a file +called `gtk.PID.syscap`. + +When launching the application from sysprof, it will set the +`SYSPROF_TRACE_FD` environment variable to point GTK at a file +descriptor to write profiling data to. + +When GtkApplication registers with D-Bus, it exports the +`org.gnome.Sysprof2.Profiler` D-Bus interface that lets sysprof +request profiling data at runtime. diff --git a/docs/reference/gtk/running.xml b/docs/reference/gtk/running.xml deleted file mode 100644 index 1c4df5ad43..0000000000 --- a/docs/reference/gtk/running.xml +++ /dev/null @@ -1,601 +0,0 @@ - - - - -Running GTK Applications -3 -GTK Library - - - -Running GTK Applications - -How to run and debug your GTK application - - - - -Running and debugging GTK Applications - - -Environment variables - - -GTK inspects a number of environment variables in addition to standard -variables like LANG, PATH, HOME -or DISPLAY; mostly to determine paths to look for certain -files. The X11, -Windows and -Broadway GDK backends use some -additional environment variables. - - - - <envar>GTK_DEBUG</envar> - - - Unless GTK has been configured with , - this variable can be set to a list of debug options, which cause GTK - to print out different types of debugging information. - - - actions - Actions and menu models - - - builder - GtkBuilder support - - - geometry - Size allocation - - - icontheme - Icon themes - - - keybindings - Keybindings - - - modules - Loading of modules - - - printing - Printing support - - - size-request - Size requests - - - text - Text widget internals - - - tree - Tree widget internals - - - A number of keys are influencing behavior instead of just logging: - - - interactive - Open the interactive debugger - - - no-css-cache - Bypass caching for CSS style properties - - - touchscreen - Pretend the pointer is a touchscreen device - - - updates - Visual feedback about window updates - - - resize - Highlight resizing widgets - - - layout - Show layout borders - - - snapshot - Include debug render nodes in the generated snapshots - - - The special value all can be used to turn on all - debug options. The special value help can be used - to obtain a list of all supported debug options. - - - - - <envar>GTK_PATH</envar> - - - Specifies a list of directories to search when GTK is looking for - dynamically loaded objects such as input method - modules and print backends. If the path to - the dynamically loaded object is given as an absolute path name, - then GTK loads it directly. - Otherwise, GTK goes in turn through the directories in GTK_PATH, - followed by the directory .gtk-4.0 in the user's - home directory, followed by the system default directory, - which is libdir/gtk-4.0/modules. - (If GTK_EXE_PREFIX is defined, libdir is - $GTK_EXE_PREFIX/lib. Otherwise it is the libdir - specified when GTK was configured, usually - /usr/lib, or - /usr/local/lib.) - For each directory in this list, GTK actually looks in a - subdirectory - directory/version/host/type - Where version is derived from the - version of GTK (use pkg-config - --variable=gtk_binary_version gtk4 to determine this from a - script), host is the architecture on - which GTK was built. (use pkg-config - --variable=gtk_host gtk4 to determine this from a - script), and type is a directory - specific to the type of modules; currently it can be - modules, engines, - immodules, filesystems or - printbackends, corresponding to the types of - modules mentioned above. Either version, - host, or both may be omitted. GTK looks - first in the most specific directory, then in directories with - fewer components. - The components of GTK_PATH are separated by the ':' character on - Linux and Unix, and the ';' character on Windows. - - - Note that this environment variable is read by GTK 2.x and GTK 3.x too, - which makes it unsuitable for setting it system-wide (or session-wide), - since doing so will cause applications using different GTK versions - to see incompatible modules. - - - - - <envar>GTK_IM_MODULE</envar> - - - Specifies an IM module to use in preference to the one determined - from the locale. If this isn't set and you are running on the system - that enables XSETTINGS and has a value in - Gtk/IMModule, that will be used for the default - IM module. - This also can be a colon-separated list of input-methods, which - GTK will try in turn until it finds one available on the system. - - - - - <envar>GTK_EXE_PREFIX</envar> - - - If set, GTK uses $GTK_EXE_PREFIX/lib instead of - the libdir configured when GTK was compiled. - - - - - <envar>GTK_DATA_PREFIX</envar> - - - If set, makes GTK use $GTK_DATA_PREFIX - instead of the prefix configured when GTK was compiled. - - - - - <envar>GTK_THEME</envar> - - - If set, makes GTK use the named theme instead of the theme - that is specified by the gtk-theme-name setting. This is intended - mainly for easy debugging of theme issues. - - - It is also possible to specify a theme variant to load, by appending - the variant name with a colon, like this: `GTK_THEME=Adwaita:dark`. - - - - -The following environment variables are used by GdkPixbuf, GDK or -Pango, not by GTK itself, but we list them here for completeness -nevertheless. - - - - <envar>GDK_PIXBUF_MODULE_FILE</envar> - - - Specifies the file listing the GdkPixbuf loader modules to load. - This environment variable overrides the default value - libdir/gtk-4.0/4.0.0/loaders.cache - (libdir is the sysconfdir specified when - GTK was configured, usually /usr/local/lib.) - - - The loaders.cache file is generated by the - gdk-pixbuf-query-loaders utility. - - - - - <envar>GDK_DEBUG</envar> - - - Unless GTK has been configured with , - this variable can be set to a list of debug options, which cause GDK - to print out different types of debugging information. - - - cursor - Information about cursor objects (only win32) - - - eventloop - Information about event loop operation (mostly Quartz) - - - misc - Miscellaneous information - - - frames - Information about the frame clock - - - settings - Information about xsettings - - - selection - Information about selections - - - clipboard - Information about clipboards - - - dnd - Information about drag-and-drop - - - opengl - Information about OpenGL - - - vulkan - Information about Vulkan - - - A number of options affect behavior instead of logging: - - - nograbs - Turn off all pointer and keyboard grabs - - - gl-disable - Disable OpenGL support - - - gl-software - Force OpenGL software rendering - - - gl-texture-rect - Use the OpenGL texture rectangle extension, if available - - - gl-legacy - Use a legacy OpenGL context - - - gl-gles - Use a GLES OpenGL context - - - vulkan-disable - Disable Vulkan support - - - vulkan-validate - Load the Vulkan validation layer, if available - - - The special value all can be used to turn on all - debug options. The special value help can be used - to obtain a list of all supported debug options. - - - - - <envar>GSK_DEBUG</envar> - - - Unless GTK has been configured with , - this variable can be set to a list of debug options, which cause GSK - to print out different types of debugging information. - - - renderer - General renderer information - - - cairo - cairo renderer information - - - opengl - OpenGL renderer information - - - shaders - Shaders - - - ssurface - Surfaces - - - vulkan - Vulkan renderer information - - - fallback - Information about fallbacks - - - glyphcache - Information about glyph caching - - - A number of options affect behavior instead of logging: - - - diff - Show differences - - - geometry - Show borders - - - full-redraw - Force full redraws for every frame - - - sync - Sync after each frame - - - vulkan-staging-image - Use a staging image for Vulkan texture upload - - - vulkan-staging-buffer - Use a staging buffer for Vulkan texture upload - - - The special value all can be used to turn on all - debug options. The special value help can be used - to obtain a list of all supported debug options. - - - - - <envar>GDK_BACKEND</envar> - - - If set, selects the GDK backend to use. Selecting a backend requires that - GTK is compiled with support for that backend. The following backends can - be selected, provided they are included in the GDK libraries you are using: - - - - quartz - Selects the native Quartz backend - - - - win32 - Selects the native backend for Microsoft Windows - - - - x11 - Selects the native backend for connecting to X11 servers. - - - - broadway - Selects the Broadway backend for display in web browsers - - - - wayland - Selects the Wayland backend for connecting to Wayland display servers - - - - This environment variable can contain a comma-separated list of backend names, - which are tried in order. The list may also contain a *, which means: try all - remaining backends. The special value "help" can be used to make GDK print out - a list of all available backends. For more information about selecting backends, - see the gdk_display_manager_get() function. - - - - - <envar>GDK_VULKAN_DEVICE</envar> - - - This variable can be set to the index of a Vulkan device to override the - default selection of the device that is used for Vulkan rendering. - The special value list can be used to obtain a list - of all Vulkan devices. - - - - - <envar>GSK_RENDERER</envar> - - - If set, selects the GSK renderer to use. The following renderers can - be selected, provided they are included in the GTK library you are using - and the GDK backend supports them: - - - - help - Prints information about available options - - - - broadway - Selects the Broadway-backend specific renderer - - - - cairo - Selects the fallback Cairo renderer - - - - gl - Selects the default OpenGL renderer - - - - vulkan - Selects the Vulkan renderer - - - - - - - - <envar>GTK_CSD</envar> - - - The default value of this environment variable is 1. If changed to 0, this - disables the default use of client-side decorations on GTK windows, thus - making the window manager responsible for drawing the decorations of - windows that do not have a custom titlebar widget. - - - CSD is always used for windows with a custom titlebar widget set, as the WM - should not draw another titlebar or other decorations around the custom one. - - - - - <envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar> - - - GTK uses these environment variables to locate icon themes - and MIME information. For more information, see - Icon Theme Specification, - the Shared MIME-info Database - and the Base Directory Specification. - - - - - <envar>DESKTOP_STARTUP_ID</envar> - - - GTK uses this environment variable to provide startup notification - according to the Startup Notification Spec. - Following the specification, GTK unsets this variable after reading - it (to keep it from leaking to child processes). So, if you need its - value for your own purposes, you have to read it before calling - gtk_init(). - - - - - - -Interactive debugging - - - - - GTK includes an interactive debugger, called the GTK Inspector, which - lets you explore the widget tree of any GTK application at runtime, as - well as tweak the theme and trigger visual debugging aids. You can - easily try out changes at runtime before putting them into the code. - - - Note that the GTK inspector can only show GTK internals. It can not - understand the application-specific logic of a GTK application. Also, - the fact that the GTK inspector is running in the application process - limits what it can do. It is meant as a complement to full-blown debuggers - and system tracing facilities such as DTrace, not as a replacement. - - - To enable the GTK inspector, you can use the Control-Shift-I or - Control-Shift-D keyboard shortcuts, or set the - GTK_DEBUG=interactive environment variable. - - - There are a few more environment variables that can be set to influence - how the inspector renders its UI. GTK_INSPECTOR_DISPLAY and - GTK_INSPECTOR_RENDERER determine the GDK display and - the GSK renderer that the inspector is using. - - - - In some situations, it may be inappropriate to give users access to the - GTK inspector. The keyboard shortcuts can be disabled with the - `enable-inspector-keybinding` key in the `org.gtk.Settings.Debug` - GSettings schema. - - - - - - Profiling - - - GTK supports profiling with sysprof. It exports timing information - about frameclock phases and various characteristics of GskRenders - in a format that can be displayed by sysprof or GNOME Builder. - - - A simple way to capture data is to set the GTK_TRACE - environment variable. When it is set, GTK will write profiling - data to a file called - gtk.PID.syscap. - - - When launching the application from sysprof, it will set the - SYSPROF_TRACE_FD environment variable to point - GTK at a file descriptor to write profiling data to. - - - When GtkApplication registers with D-Bus, it exports the - org.gnome.Sysprof2.Profiler interface - that lets sysprof request profiling data at runtime. - - - - - -