SerenityOS GML 编译用法指南:通过 `compile_gml` 将 GML 布局代码生成并接入 C++ 应用
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()
其要点:
- 调用 GMLCompiler:通过
$<TARGET_FILE:Lagom::GMLCompiler>定位编译工具的可执行文件,将 GML 源文件作为输入,标准输出重定向到.tmp临时文件。GMLCompiler的构建目标定义在 Meta/Lagom/Tools/CodeGenerators/GMLCompiler/CMakeLists.txt,Lagom::GMLCompiler是 Lagom 构建体系(SerenityOS 在宿主机上的交叉构建/工具链)提供的主机侧工具。 - 原子落盘:
copy_if_different仅在内容有变化时才覆盖目标文件,避免不必要的重编译;随后删除临时文件。 - 依赖追踪:
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()
使用它需要满足两个前提:
- GML 根元素必须是
MyApp::Widget这个类,即 GML 文件最外层写成@MyApp::Widget { ... }。 - 头文件声明:需要在
MyApp::Widget类的头文件中自行声明try_create()函数。该函数不会与Core::Object提供的函数冲突,可以放心声明。 - 无参构造函数:
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 的完整清单如下:
- 编写 GML 文件(如
MyAppWidget.gml),根元素写成@MyApp::Widget,为需要绑定的控件设置name。 - CMake 接入:在
CMakeLists.txt中调用compile_gml(MyAppWidget.gml MyAppWidgetGML.cpp),并把MyAppWidgetGML.cpp加入SOURCES。 - 类头文件声明:在
MyApp::Widget头文件中声明static ErrorOr<NonnullRefPtr<MyApp::Widget>> try_create();(或无参形式),并确保有无参构造函数。 - 接入窗口:通过
Window::try_set_main_widget(间接调用try_create)把根控件设置为主窗口内容。 - 初始化:实现
ErrorOr<void> initialize(),在其中调用find_descendant_of_type_named<T>("name")绑定控件成员,并挂接回调、设置模型。 - 运行:构建时
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++ 成员"的绑定,是保持代码整洁、可维护的关键实践。