环境变量

GTK 会检查许多环境变量，包括标准变量，例如 LANG、PATH、HOME 或 DISPLAY；主要用来确定查找特定文件的路径。 X11、Wayland、Windows 和 Broadway GDK 后端使用一些其他环境变量。

请注意，一般将环境变量用于调试目的。不能保证环境变量的 API 稳定，不应将环境变量用于最终用户配置和自定义。如果你觉得需要以编程方式设置其中一个变量，则应该要求提供 API 来实现你的目的。

GTK_DEBUG

此变量可以设置为一个调试选项列表，这会导致 GTK 打印出不同类型的调试信息。

操作

操作和菜单模型

构建器

GtkBuilder 支持

builder-objects

未使用的 GtkBuilder 对象

几何

大小分配

icontheme

图标主题

iconfallback

有关图标后备的信息

keybindings

键盘快捷键

modules

模块和扩展

printing

打印

size-request

大小请求

text

文本小组件内部

tree

树形小组件内部

constraints

约束和约束求解器

layout

布局管理器

accessibility

可访问性状态更改

一些键不仅用于记录，还用于影响行为

interactive

打开 交互式调试器

no-css-cache

绕过 CSS 样式属性的缓存

snapshot

在生成的快照中包括调试渲染节点

invert-text-dir

与语言环境相比，反转文本方向

特殊值 all 可用于开启所有调试选项。特殊值 help 可用于获取所有支持的调试选项的列表。

GTK_PATH

指定当 GTK 寻找动态加载的对象时（例如输入法模块和打印后端）要搜索的目录列表。如果动态加载的对象的路径被指定为绝对路径名，则 GTK 会直接加载该对象。否则，GTK 会依次遍历 GTK_PATH 中的目录，然后遍历系统默认目录（即 libdir/gtk-4.0/modules）。（如果定义了 GTK_EXE_PREFIX，则 libdir 为 $GTK_EXE_PREFIX/lib。否则，则为 GTK 在配置时的 libdir，通常为 /usr/lib 或 /usr/local/lib。）

对于此列表中的每个目录，GTK 实际上会以子目录进行查找 directory/version/host/type。其中 version 是从 GTK 版本中派生出来的（使用 pkg-config --variable=gtk_binary_version gtk4 从脚本中确定这一点），host 是构建 GTK 的体系结构。（使用 pkg-config --variable=gtk_host gtk4 从脚本中确定这一点），而 type 是特定于模块类型的目录；目前可以是 modules、immodules 或 printbackends，对应上面提到的模块类型。version、host 或两者都可以省略。GTK 首先在最具体的目录中查找，然后在具有较少组件的目录中查找。GTK_PATH 的组件在 Linux 和 Unix 上由“：”字符分隔，在 Windows 上由“；”字符分隔。

此环境变量会被 GTK 2.x 和 GTK 3.x 读取，这也使其不适合在系统范围内（或会话范围内）对其进行设置，因为这样做会导致使用不同 GTK 版本的应用程序看到不兼容的模块。

GTK_IM_MODULE

指定要优先使用的 IM 模块，而不是根据语言环境确定的模块。如果未在此设置，并且你使用的是启用了 `XSETTINGS` 且 `Gtk/IMModule` 中的值系统，那么该值将用作默认的 IM 模块。这也可以是输入法的冒号分隔列表，GTK 会依次尝试它们，直到它在系统中找到一个可用的。

GTK_MEDIA

指定为 GtkMediaFile 加载哪个后端。可能的值取决于构建 GTK 时使用的选项，其中可能包括“gstreamer”和“none”。如果设置为“none”，那么媒体播放将不可用。可以使用特殊值“help”来获取所有支持的媒体后端列表。

GTK_EXE_PREFIX

如果设置，GTK 将使用 $GTK_EXE_PREFIX/lib，而不是在编译 GTK 时配置的 libdir。

GTK_DATA_PREFIX

如果设置，GTK 将使用 $GTK_DATA_PREFIX，而不是在编译 GTK 时配置的前缀。

GTK_THEME

如果设置，则让 GTK 使用命名的主题，而不是由 gtk-theme-name 设置指定的主题。这主要用于轻松调试主题问题。

还可以通过在后面附加一个冒号和一个变体名称来指定一个主题变体进行加载，如下所示：GTK_THEME=Adwaita:dark。

以下环境变量由 GdkPixbuf、GDK 或 Pango 使用，而不是由 GTK 本身使用，但我们仍在此处列出它们以求完整性。

GDK_PIXBUF_MODULE_FILE

指定列出要加载的 GdkPixbuf 加载器模块的文件。此环境变量将覆盖默认值 `libdir/gtk-4.0/4.0.0/loaders.cache`（`libdir` 是配置 GTK 时指定的 sysconfdir，通常为 `/usr/lib`。）

loaders.cache 文件是由 gdk-pixbuf-query-loaders 实用程序生成的。

GDK_DEBUG

此变量可以设置成调试选项的列表，这会导致 GDK 打印出不同类型的调试信息。

misc

其他信息

events

有关事件的信息

dnd

有关拖放的信息

input

有关输入的信息（主要是 Windows）

eventloop

有关事件循环操作的信息（主要是 macOS）

帧

有关帧时钟的信息

设置

有关 xsettings 的信息

opengl

有关 OpenGL 的信息

vulkan

有关 Vulkan 的信息

选择

有关选择的信息

剪贴板

有关剪贴板的信息

dmabuf

有关 dmabuf 处理的信息（仅适用于 Linux）

卸载

有关子曲面和图形卸载的信息（仅适用于 Wayland）

许多选项会影响行为，而不是记录

门户

强制使用 门户

无门户

禁用 门户 的使用

强制卸载

强制对所有纹理进行图形卸载，即使速度较慢。这允许在没有 dmabuf 的情况下调试卸载。

gl-no-fractional

针对 OpenGL 禁用分数缩放。

gl-debug

在 OpenGL 中插入调试信息

gl-prefer-gl

相对于 OpenGL ES 而言，更喜欢 OpenGL。这是 GTK 4.14 之前的默认行为。

vulkan-validate

加载 Vulkan 验证层（如果可用）

默认设置

强制针对 xsettings 使用默认值

高深度

如果可能，使用高位深度渲染

线性

启用线性渲染

hdr

强制 HDR 渲染

无垂直同步

立即重新绘制（与动画使用 100% CPU）

特殊值 all 可用于开启所有调试选项。特殊值 help 可用于获取所有支持的调试选项的列表。

GSK_DEBUG

此变量可以设置为调试选项列表，导致 GSK 打印出不同类型的调试信息。

渲染器

一般性渲染器信息

vulkan

检查 Vulkan 错误

着色器

有关着色器的信息

后备

有关渲染器中后备用法的信息

高速缓存

有关高速缓存的信息

详细

在渲染时打印详细的输出

许多选项会影响行为，而不是记录

几何

显示边界（当使用 cairo 时）

全重绘

强制全重绘

临时存放

使用临时图像存储纹理上传（仅适用于 Vulkan）

cairo

覆盖 cairo 绘图中的错误模式（发现后备）

遮挡

通过遮挡剔除优化后的区域覆盖高亮

特殊值 all 可用于开启所有调试选项。特殊值 help 可用于获取所有支持的调试选项的列表。

GDK_BACKEND

如果设置，则选择要使用的 GDK 后端。选择后端需要使用对该后端提供支持编译的 GTK。如果在您所用的 GDK 库中包含以下后端，则可以选择这些后端

macos

选择本机 Quartz 后端

win32

选择适用于 Microsoft Windows 的本机后端

x11

选择用于连接到 X11 服务器的本机后端

broadway

选择 Broadway 后端，以供在网络浏览器中显示

wayland

选择用于连接到 Wayland 合成器的 Wayland 后端

此环境变量可以包含后端名称的逗号分隔列表，按照顺序尝试。列表中还可能包含一个 *，表示：尝试所有剩余的后端。可以使用特殊值 help 来使 GDK 打印出所有可用后端的列表。有关选择后端的详细信息，请参见 gdk_display_manager_get() 函数。

GDK_DISABLE

此变量可设置为值列表，造成 GDK 禁用某些功能。

gl

禁用 OpenGL 支持

gl-api

不允许使用 OpenGL GL API。这强制使用 GLES

gles-api

不允许使用 OpenGL GLES API。这强制使用 GL

egl

不允许使用 EGL 上下文

glx

不允许使用 GLX

wgl

不允许使用 WGL

vulkan

禁用 Vulkan 支持

dmabuf

禁用 dmabuf 支持

卸载

禁用图形卸载到子表面

color-mgmt

禁用颜色管理

aerosnap

禁用 Windows 上的 Aerosnap 支持

threads

禁用在可能的情况下使用线程

GDK_GL_DISABLE

此变量可设置为值列表，造成 GDK 禁用 OpenGL 支持的扩展功能。请注意，如果 GL 驱动程序不支持，这些功能可能已禁用。

debug

GL_KHR_debug

unpack-subimage :GL_EXT_unpack_subimage

half-float :GL_OES_vertex_half_float

sync :GL_ARB_sync

base-instance :GL_EXT_base_instance

GDK_VULKAN_DISABLE

此变量可设置为值列表，造成 GDK 禁用 Vulkan 支持的功能。请注意，如果 Vulkan 驱动程序不支持，这些功能可能已禁用。

dmabuf

从不导入 Dmabuf

ycbr

不支持 Ycbcr 纹理

semaphore-export

禁用导出的 dmabuf 的同步

semaphore-import

禁用导入的 dmabuf 的同步

incremental-present

不发送损坏区域

swapchain-maintenance

不使用高级 swapchain 功能

特殊值 all 可用于启用所有值。特殊值 help 可用于获取所有受支持值的列表。

GSK_RENDERER

如果设置，则选择要使用的 GSK 渲染器。可选择以下渲染器，只要它们包含在你正在使用的 GTK 库中，并且 GDK 后端支持它们

help

打印有关可用选项的信息

broadway

选择特定于百老汇后端的渲染器

cairo

选择后备 Cairo 渲染器

ngl

选择 OpenGL 渲染器

vulkan

选择 Vulkan 渲染器

GSK_GPU_DISABLE

此变量可以设置一个值列表，这些值会导致 GSK 禁用“ngl”和“vulkan”渲染器的某些优化。

clear

使用着色器而不是 vkCmdClearAttachment()/glClear()

merge

对每个操作使用一个 vkCmdDraw()/glDrawArrays()

blit

使用着色器而不是 vkCmdBlit()/glBlitFramebuffer()

gradients

不超采样渐变

mipmap

避免创建 MIP 贴图

to-image

不对节点图像创建快速路径

遮挡

禁用通过不透明度跟踪进行遮挡剔除

repeat

重复绘制操作，而不是使用屏幕外和 GL_REPEAT

特殊值 all 可用于启用所有值。特殊值 help 可用于获取所有受支持值的列表。

GSK_CACHE_TIMEOUT

覆盖“ngl”和“vulkan”渲染器中缓存 GC 的超时。该值可以为 -1 以完全禁用 GC，为 0 以强制 GC 在每一帧之前发生，或者为正数以在每 n 秒钟的超时时间内进行 GC。默认超时时间为 15 秒。

GSK_MAX_TEXTURE_SIZE

将纹理大小限制在这个值和 OpenGL 极限之间的较小值，用于“gl”渲染器中的纹理大小。这可以用来调试纹理切片的相关问题，在这些系统中，OpenGL 的纹理大小限制会让纹理切片难以进行测试。

GTK_CSD

此环境变量的默认值为 1。如果更改为 0，这将禁用在 GTK 窗口中默认使用客户端装饰，因此让窗口管理器负责绘制没有自定义标题栏小部件的窗口的装饰。

CSD 总是在设置了自定义标题栏小部件的窗口中使用，因为 WM 不会在自定义窗口周围绘制其他标题栏或其他装饰。

GTK_A11Y

如果设置，选择要使用的辅助功能后端。可以在以下后端中进行选择，只要它们包含在您使用的 GTK 库中

help

打印有关可用选项的信息

atspi

选择 AT-SPI 辅助功能后端

accesskit

选择 AccessKit 辅助功能后端

test

选择测试后端

none

禁用辅助功能后端

建议将 test 辅助功能后端用于测试套件和远程持续集成管道。

XDG_DATA_HOME, XDG_DATA_DIRS

GTK 使用这些环境变量查找图标主题和 MIME 信息。有关更多信息，请参阅 图标主题规范、共享 MIME-信息数据库和基本目录规范。

DESKTOP_STARTUP_ID

GTK 使用此环境变量根据 启动通知规范 提供启动通知。按照规范，GTK在读取此变量后取消设置此变量（以防止它泄漏到子进程）。因此，如果您需要将此值用于自己的目的，则必须在调用 gtk_init() 之前读取此值。

交互调试

GTK 包括一个交互调试器（称为 GTK 检查器），它使您能在运行时浏览任意 GTK 应用程序的小组件树，以及调整主题和触发可视化调试辅助工具。您可以在将更改应用于代码之前，轻松地尝试运行时更改。

请注意，GTK 检查器只能显示 GTK 内部信息。它无法理解 GTK 应用程序中特定于应用程序的逻辑。此外，GTK 检查器在应用程序进程中运行这一事实限制了它可以执行的操作。它被视为完全成熟的调试器和系统跟踪功能（如 DTrace）的补充，而不是替代品。

要启用 GTK 检查器，可以使用 Control+Shift+I 或 Control+Shift+D 快捷键，或者设置 GTK_DEBUG=interactive 环境变量。

打开检查器后，它会侦听一些快捷键，这些快捷键可让您使用其框架和事件记录功能，而无需将焦点移出应用程序窗口：Super+R 开启和关闭记录，Super+C 记录单个帧。

有另外一些环境变量可以设置，以影响检查器呈现其 UI 的方式。GTK_INSPECTOR_DISPLAY 和 GTK_INSPECTOR_RENDERER 确定检查器正在使用的 GDK 显示和 GSK 渲染器。

在某些情况下，向用户提供 GTK 检查器访问权限可能不合适。可以使用 enable-inspector-keybinding 在 org.gtk.Settings.Debug GSettings 架构中的键来禁用快捷键。

分析

GTK 支持使用 sysprof 进行分析。它以可由 sysprof 或 GNOME Builder 显示的格式，导出有关帧时钟阶段的时间信息和 GskRenderers 的各种特征。

获取数据的简单方法是在 sysprof-cli 包装器下运行应用程序，它会将分析数据写入名为 capture.syscap 的文件。

从 sysprof 启动应用程序时，它会设置 SYSPROF_TRACE_FD 环境变量，将 GTK 指向要写入分析数据的文件描述符。