[gtk/doc-chapters-markdown: 17/29] docs: Convert building, compiling, running to markdown

[Matthias Clasen <matthiasc src gnome org>]

commit b99511ee5524f9009a2dfafe67a4df4dfa31f045
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun May 24 00:04:36 2020 -0400

    docs: Convert building, compiling, running to markdown

 docs/reference/gtk/building.md                     | 270 +++++++++
 docs/reference/gtk/building.xml                    | 518 ------------------
 docs/reference/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(-)
---
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/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 @@
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"; [
-]>
-<refentry id="gtk-compiling">
-<refmeta>
-<refentrytitle>Compiling GTK Applications</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
+# Compiling GTK Applications on UNIX {#gtk-compiling}
 
-<refnamediv>
-<refname>Compiling GTK Applications</refname>
-<refpurpose>
-How to compile your GTK application
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Compiling GTK Applications on UNIX</title>
-
-<para>
 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
-<literal>pkg-config</literal> utility.
-</para>
-<para>
-The following interactive shell session demonstrates how
-<literal>pkg-config</literal> is used (the actual output on
-your system may be different):
-<programlisting>
+`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
-</programlisting>
-</para>
-<para>
+```
 The simplest way to compile a program is to use the "backticks"
 feature of the shell. If you enclose a command in backticks
-(<emphasis>not single quotes</emphasis>), then its output will be
-substituted into the command line before execution. So to compile
-a GTK Hello, World, you would type the following:
-<programlisting>
+(*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`
-</programlisting>
-</para>
-
-<para>
+```
 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 <literal>-DGDK_DISABLE_DEPRECATION_WARNINGS</literal>
-</para>
+option `-DGDK_DISABLE_DEPRECATION_WARNINGS`.
 
-<para>
 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.
-</para>
 
-<para>
 Here is how you would compile hello.c if you want to allow it
 to use symbols that were not deprecated in 4.2:
-<programlisting>
+```
 $ cc `pkg-config --cflags gtk4` -DGDK_VERSION_MIN_REQIRED=GDK_VERSION_4_2 hello.c -o hello `pkg-config 
--libs gtk4`
-</programlisting>
-</para>
+```
 
-<para>
 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:
-<programlisting>
+```
 $ cc `pkg-config --cflags gtk4` -DGDK_VERSION_MAX_ALLOWED=GDK_VERSION_4_2 hello.c -o hello `pkg-config 
--libs gtk4`
-</programlisting>
-</para>
-
-<para>
+```
 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 <literal>-DGTK_DISABLE_DEPRECATED</literal>.
+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.
-</para>
-
-</refsect1>
-</refentry>
+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 @@
   <part id="platform-support">
     <title>GTK Platform Support</title>
     <xi:include href="building.xml" />
-    <xi:include href="xml/compiling.xml" />
+    <xi:include href="compiling.xml" />
     <xi:include href="running.xml" />
     <xi:include href="x11.xml" />
     <xi:include href="windows.xml" />
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.