SerenityOS GML 编译用法指南:通过 `compile_gml` 将 GML 布局代码生成并接入 C++ 应用

原创2026-09-09 19:44:021,678 阅读
文章标签:操作系统内核驱动系统编程桌面应用图形学WebAssembly

SerenityOS GML 编译用法指南:通过 compile_gml 将 GML 布局代码生成并接入 C++ 应用

导读

GML(GUI Markup Language)是 SerenityOS 中用于描述 LibGUI 界面结构的声明式标记语言。本篇文章聚焦 GML 的编译期用法:如何通过 CMake 的 compile_gml() 将 .gml 文件编译为 C++ 源码,如何让生成的 try_create() 自动构建窗口/控件结构,以及如何配合 initialize() 模式与 find_descendant_of_type_named() 完成初始化与控件绑定。读完本文,你将掌握在 SerenityOS C++ 应用中把 GML 从"手写界面代码"升级为"自动生成 + 声明式布局"的完整链路。

本文对应仓库文档:Base/usr/share/man/man5/GML/Usage.md。文中所引示例、路径与实现细节均以当前仓库实际源码为准。

背景:两种加载 GML 的方式

在 SerenityOS 中,GML 文件的加载存在两条路径:

  • 编译期生成(推荐):通过 compile_gml() 在构建时调用 GMLCompiler 工具,把 .gml 文件编译成一份 C++ 源文件。生成的代码提供 try_create() 实现,无需运行时解析,类型安全且启动开销低。
  • 运行时加载(特殊场景):通过 load_from_gml 函数在运行时解析 GML 字符串。其行为与编译期生成一致,但仅在特定场景下使用,例如 GMLPlayground 这类需要动态编辑和预览 GML 的调试工具。

从源码结构看,load_from_gml 的实现位于 LibGUI 库中(Userland/Libraries/LibGUI/ 下),日常应用程序应优先走编译期路径。

CMake 集成:compile_gml() 的用法与原理

在应用的 CMakeLists.txt 中加入 compile_gml() 即可把 GML 纳入构建管线。以仓库中的实际应用为例,Userland/Applications/Calculator/CMakeLists.txt 中的写法为:

compile_gml(CalculatorWindow.gml CalculatorGML.cpp)

即第一个参数是源 .gml 文件,第二个参数是生成的 C++ 文件名(命名不固定,但建议遵循 XXXGML.cpp 的惯例)。随后把生成的文件加入 SOURCES:

set(SOURCES
    CalculatorGML.cpp
)

compile_gml() 的底层实现

该函数定义在 Meta/CMake/code_generators.cmake(第 53 行起):

function(compile_gml source output)
    set(source ${CMAKE_CURRENT_SOURCE_DIR}/${source})
    add_custom_command(
        OUTPUT ${output}
        COMMAND $<TARGET_FILE:Lagom::GMLCompiler> ${source} > ${output}.tmp
        COMMAND "${CMAKE_COMMAND}" -E copy_if_different ${output}.tmp ${output}
        COMMAND "${CMAKE_COMMAND}" -E remove ${output}.tmp
        VERBATIM
        DEPENDS Lagom::GMLCompiler
        MAIN_DEPENDENCY ${source}
    )
    get_filename_component(output_name ${output} NAME)
    add_custom_target(generate_${output_name} DEPENDS ${output})
    add_dependencies(all_generated generate_${output_name})
endfunction()

其要点:

  1. 调用 GMLCompiler:通过 $<TARGET_FILE:Lagom::GMLCompiler> 定位编译工具的可执行文件,将 GML 源文件作为输入,标准输出重定向到 .tmp 临时文件。GMLCompiler 的构建目标定义在 Meta/Lagom/Tools/CodeGenerators/GMLCompiler/CMakeLists.txt,Lagom::GMLCompiler 是 Lagom 构建体系(SerenityOS 在宿主机上的交叉构建/工具链)提供的主机侧工具。
  2. 原子落盘:copy_if_different 仅在内容有变化时才覆盖目标文件,避免不必要的重编译;随后删除临时文件。
  3. 依赖追踪:MAIN_DEPENDENCY 指定 GML 源文件作为主依赖,DEPENDS Lagom::GMLCompiler 保证工具本身更新后也会重新生成;同时通过 add_dependencies(all_generated ...) 把生成目标挂到全局的 all_generated 目标上,确保构建顺序正确。

仓库中大量应用使用了这一模式,例如 Userland/Applications/BrowserSettings/CMakeLists.txt 中一次性编译多个 GML 文件:

compile_gml(AutoplaySettingsWidget.gml AutoplaySettingsWidgetGML.cpp)
compile_gml(BrowserSettingsWidget.gml BrowserSettingsWidgetGML.cpp)
compile_gml(ContentFilterSettingsWidget.gml ContentFilterSettingsWidgetGML.cpp)

C++ 侧接入:try_create() 的契约

编译生成的 C++ 源文件会为 GML 根控件的类提供一个 try_create() 的实现,其签名固定为:

ErrorOr<NonnullRefPtr<MyApp::Widget>> MyApp::Widget::try_create()

使用它需要满足两个前提:

  1. GML 根元素必须是 MyApp::Widget 这个类,即 GML 文件最外层写成 @MyApp::Widget { ... }。
  2. 头文件声明:需要在 MyApp::Widget 类的头文件中自行声明 try_create() 函数。该函数不会与 Core::Object 提供的函数冲突,可以放心声明。
  3. 无参构造函数:MyApp::Widget 必须提供无参构造函数,供 try_create() 实现内部调用。

一旦完成上述准备,直接或间接调用 try_create()(例如通过 Window::try_set_main_widget 把根控件挂到窗口上)就会自动加载 GML 中定义的控件结构。

用 find_descendant_of_type_named 绑定控件

GML 布局建立后,需要把声明式定义的控件"翻译"为 C++ 成员变量。标准做法是给控件设置 name 属性,再通过 find_descendant_of_type_named<类型>("名称") 按名称查找后代控件。

以文档中的示例为例,GML 文件如下:

@MyApp::Widget {
    @GUI::Button {
        name: "mem_add_button"
        text: "M+"
        fixed_width: 35
        fixed_height: 28
        foreground_color: "red"
    }
}

对应的 C++ 代码:

// MyApp::Widget::foo_bar
m_mem_add_button = *find_descendant_of_type_named<GUI::Button>("mem_add_button");

仓库中的真实调用

这一模式在仓库中应用广泛。例如浏览器窗口 Userland/Applications/Browser/BrowserWindow.cpp 中:

auto& top_line = *widget->find_descendant_of_type_named<GUI::HorizontalSeparator>("top_line");
m_tab_widget = *widget->find_descendant_of_type_named<GUI::TabWidget>("tab_widget");

对应的 GML 结构见 Base/usr/share/man/man5/GML/Syntax.md 中的 Browser 示例(top_line 是 @GUI::HorizontalSeparator,tab_widget 是 @GUI::TabWidget)。

再如 Userland/Applications/Browser/FindInPageWidget.cpp 中的批量绑定:

m_close_button = find_descendant_of_type_named<GUI::Button>("close_button");
m_previous_button = find_descendant_of_type_named<GUI::Button>("previous_button");
m_next_button = find_descendant_of_type_named<GUI::Button>("next_button");
m_search_textbox = find_descendant_of_type_named<GUI::TextBox>("search_textbox");
m_match_case_checkbox = find_descendant_of_type_named<GUI::CheckBox>("match_case_checkbox");
m_result_label = find_descendant_of_type_named<GUI::Label>("result_label");

该函数位于 Widget 基类中(Userland/Libraries/LibGUI 的 Widget 实现),支持在任意后代层级中按类型 + 名称查找,且返回值用引用/指针形式,配合 * 解引用即可安全使用。

initialize() 模式:结构就绪后的初始化钩子

控件结构由生成代码搭建完成后,通常还需要做额外初始化,比如添加数据模型、挂接回调等。GML 编译体系规定了一个约定式入口:成员函数 ErrorOr<void> initialize()。

// MyApp::Widget
ErrorOr<void> initialize();

只要该类存在 initialize() 成员函数,自动生成的 GML 代码就会在控件结构搭建完成后自动调用它。这保证了"结构已就绪、可以安全绑定控件"这一时机是确定的,开发者无需关心调用顺序。

唯一无法使用该函数的场景是:初始化过程需要额外参数(例如需要一个 GUI 窗口对象)。此时应尽量把不依赖额外参数的部分放进 initialize(),把剩余部分留在调用方完成。

综合实战:一个完整的接入清单

将上述各环节串联起来,一个 SerenityOS 应用使用编译期 GML 的完整清单如下:

  1. 编写 GML 文件(如 MyAppWidget.gml),根元素写成 @MyApp::Widget,为需要绑定的控件设置 name。
  2. CMake 接入:在 CMakeLists.txt 中调用 compile_gml(MyAppWidget.gml MyAppWidgetGML.cpp),并把 MyAppWidgetGML.cpp 加入 SOURCES。
  3. 类头文件声明:在 MyApp::Widget 头文件中声明 static ErrorOr<NonnullRefPtr<MyApp::Widget>> try_create();(或无参形式),并确保有无参构造函数。
  4. 接入窗口:通过 Window::try_set_main_widget(间接调用 try_create)把根控件设置为主窗口内容。
  5. 初始化:实现 ErrorOr<void> initialize(),在其中调用 find_descendant_of_type_named<T>("name") 绑定控件成员,并挂接回调、设置模型。
  6. 运行:构建时 GMLCompiler 自动把 .gml 编译为 C++,应用直接使用生成的结构。

GML 的语法细节(属性取值类型、layout 特殊属性、margins/rect/ui_dimension 等类型说明)可进一步参阅 GML/Syntax.md 与 GML/Widget.md;各类控件支持的属性清单见 Base/usr/share/man/man5/GML/Widget/ 目录下的各控件手册。仓库中大量 *.gml 源文件与 CMakeLists.txt 配对出现,是学习该模式的直接范例。

小结

  • GML 的编译期生成是 SerenityOS 应用构建 UI 的主流方式,运行时 load_from_gml 仅保留给 GMLPlayground 等特殊场景。
  • compile_gml() 通过 Meta/CMake/code_generators.cmake 中的自定义命令调用 Lagom::GMLCompiler,并纳入 all_generated 构建依赖。
  • 生成的 try_create() 要求 GML 根元素与类名一致、头文件有声明、类有无参构造函数。
  • 初始化工作统一放入 ErrorOr<void> initialize(),通过 find_descendant_of_type_named 完成"声明式布局 → C++ 成员"的绑定,是保持代码整洁、可维护的关键实践。
登录后查看全文
serenity