Ladybird 浏览器：Qt Creator 项目配置实战——从工程导入到 clang-format 自动格式化

本文基于 Ladybird 官方文档 QtCreatorConfiguration.md，系统讲解如何把 Ladybird 这个以 CMake 管理的大型 C++ 浏览器工程导入 Qt Creator 并配置为可日常开发的工作区：包括通过 Import Existing Project 重建文件清单、编辑 .config/.cxxflags/.includes 三个工程文件、用 Beautifier 插件接入项目级 .clang-format 规则，以及配置输入 lic 即可插入版权声明的 License 模板。读完本文，你可以在 Qt Creator 中获得与 Ladybird 代码风格一致的补全、跳转与自动格式化能力。

一、前置条件：先确保命令行构建链路可用

在配置 Qt Creator 之前，文档明确要求：先拥有一个可用的工具链，并且能够用命令行完成 Ladybird 的构建与运行。构建步骤请参考 BuildInstructionsLadybird.md。

原因很直接：后文要向工程里添加 Build/release/ 等生成目录作为头文件搜索路径，这些目录只有在真正执行过一次 CMake 构建之后才存在；同时 Ladybird 依赖 vcpkg 管理的第三方库（如 Skia），其头文件位于构建目录下，只有完成构建，IDE 的索引与跳转才有意义。

Qt Creator 本身不需要安装整套 Qt SDK——从 Qt 官网下载离线安装器后，在组件列表左侧只勾选 "Qt Creator" 即可，这只是一步纯 IDE 的安装，不引入额外的 Qt 框架依赖。

二、导入工程：Import Existing Project 与文件清单重建

按官方文档的操作序列，在 Qt Creator 中完成导入：

1. 打开 Qt Creator，选择 File -> New File or Project...；
2. 选择 Import Existing Project；
3. 给工程起一个名字（注意：部分工具默认假设小写的 ladybird），并将目录定位到你的 Ladybird 仓库检出根目录，点击 Next；
4. 等待文件列表生成，可能需要一两分钟；
5. 忽略 Qt Creator 自动生成的文件列表——它并不完整，后文会覆盖；
6. 将 Add to version control 设为 <None>，点击 Finish。

2.1 为什么要手动重新生成 ladybird.files

导入完成后，官方要求回到 shell 中进入 Ladybird 工程目录，执行 refresh-ladybird-qtcreator.sh 脚本来重新生成根目录下的 ladybird.files 清单文件，并且此后每次删除或新增文件都要重新执行一次。

阅读该脚本源码可以理解它做了什么：

find . \( \
        -name Base \
        -o -name Patches \
        -o -name Ports \
        -o -name Root \
        -o -name Build \
    \) -prune \
    -o \( \
        -name '*.ipc' \
        -o -name '*.cpp' \
        -o -name '*.idl' \
        -o -name '*.c' \
        -o -name '*.h' \
        -o -name '*.in' \
        -o -name '*.css' \
        -o -name '*.cmake' \
        -o -name '*.json' \
        -o -name 'CMakeLists.txt' \
    \) \
    -print > ladybird.files
find Build/release/ \( \
        -name '*.cpp' \
        -o -name '*.idl' \
        -o -name '*.h' \
    \) \
    -print >> ladybird.files

从源码结构看，脚本分两段工作：

• 第一段 find 遍历仓库（未设置 LADYBIRD_SOURCE_DIR 时用 git rev-parse --show-toplevel 自动定位），剪枝跳过 Base、Patches、Ports、Root、Build 这几个与开发无关或体积巨大的目录，只收录源码相关的扩展名——*.ipc、*.cpp、*.idl、*.c、*.h、*.in、*.css、*.cmake、*.json 和 CMakeLists.txt；
• 第二段 find 专门把 Build/release/ 下的生成文件（*.cpp、*.idl、*.h）追加到清单末尾。Ladybird 通过 CMake 代码生成器（例如从 .idl/.ipc 定义生成的 C++ 代码）产出大量源文件，这些文件是 IDE 补全和跳转所必需的，因此单独追加。

注意清单中特意包含了 *.ipc 与 *.idl——这两类是 Ladybird 的接口/IPC 定义文件，后续还会在自动格式化一节中专门处理。

2.2 编辑 ladybird.config：加入编译期格式检查宏

用 Qt Creator 的跨文件搜索打开 ladybird.config（快捷键 ^K，macOS 上为 CMD+K，输入文件名后回车即可打开），在其中追加：

#define ENABLE_COMPILETIME_FORMAT_CHECK

该宏作用于 Ladybird 的格式化库 AK/Format.h：Ladybird 的 fmt::format/DebugStringf 等格式化接口支持在编译期对格式串与参数类型做一致性检查，开启此宏后，格式化字符串写错（占位符与参数类型不匹配）会在编译阶段直接报错，而不是留到运行时才暴露。在 IDE 的日常开发中提前打开它，能显著减少此类低级错误。

2.3 编辑 ladybird.cxxflags：对齐项目的编译标准

将 ladybird.cxxflags 的内容改为：

-std=c++23 -fsigned-char -fconcepts -fno-exceptions -fno-semantic-interposition -fPIC

这些是 Ladybird 实际构建所使用的关键编译选项，让 IDE 的语义分析与真实构建保持一致：

• -std=c++23：Ladybird 是 C++23 工程；
• -fsigned-char：规定 char 默认有符号，保证跨平台行为一致；
• -fconcepts：启用 C++20/23 的 concepts 语法（GCC 的显式开关）；
• -fno-exceptions：整个工程不使用异常，错误处理走 Error/Result 等显式类型（可参考 AK/Error.h、AK/Result.h）；
• -fno-semantic-interposition：禁止语义插桩，保证内联与链接行为可预期；
• -fPIC：生成位置无关代码。

2.4 编辑 ladybird.includes：补齐头文件搜索路径

将 ladybird.includes 改为如下内容（Skia 路径需按你本地 Build/release/vcpkg_installed 的实际架构目录调整）：

./
Libraries/
Services/
Build/release/
Build/release/Libraries/
Build/release/Services/
Build/release/vcpkg_installed/x64-linux/include/skia/
AK/

各路径的用途：

• Libraries/、Services/、AK/：Ladybird 的三大源码区——基础库（Libraries/LibCore、Libraries/LibWeb 等）、多进程服务（Services/RequestServer、Services/WebContent 等）以及基础工具库 AK（字符串、容器、格式化等）；
• Build/release/ 及其子目录：放置 CMake 代码生成器输出的头文件/源码，IDE 索引这些生成物是跨模块跳转的前提；
• Build/release/vcpkg_installed/x64-linux/include/skia/：vcpkg 拉取的 Skia 2D 图形库头文件，供 LibGfx 等渲染相关代码补全使用。

2.5 收尾：处理 UTF-8 BOM

最后，在 Qt Creator 的选项中搜索 "BOM"（路径：Text Editor > Behavior > File Encodings > UTF-8 BOM），把行为切换为 "Always delete"（始终删除 BOM），避免保存时给源文件注入 BOM 污染 Ladybird 的代码库。

至此 Qt Creator 的工程配置完成，可以开始浏览工程、修改代码了。

三、自动格式化：接入项目级 .clang-format 规则

Ladybird 的低层代码风格（空格、括号、大括号位置等）统一由仓库根目录的 .clang-format 定义，整体规则参见 CodingStyle.md。在配置自动化之前，文档特别提醒：先确认你本地的 clang-format 版本与项目要求一致，因为部分操作系统默认携带的版本不同。

从源码看，CI 强制的版本由 Meta/Linters/lint_clang_format.py 决定：

CLANG_FORMAT_MAJOR_VERSION = 21

即 clang-format 21。如果发行版自带的版本太旧，需要单独安装新版，相关方法见 AdvancedBuildInstructions.md 中 "clang-format updates" 一节。

.clang-format 本身以 BasedOnStyle: WebKit 为基底并做了大量定制（AlignTrailingComments: Always、AfterFunction: true 的大括号换行、IndentPPDirectives: AfterHash、RemoveSemicolon: true 等），文件末尾还带有一段 Language: ObjC 的独立配置段，用于 macOS 上的 .mm 源文件。

3.1 启用 Beautifier 插件并注入自定义规则

按文档步骤在 Qt Creator 中配置：

1. 菜单 Help > About Plugins...；
2. 找到 Beautifier (experimental) 一行（在搜索框输入 beau 可以快速定位）；
3. 勾选其复选框；如被提示，重启 Qt Creator；
4. 菜单 Tools > Options...；
5. 在搜索框输入 "beau"，进入 Beautifier > Clang Format；
6. 选择 "customized" 风格，点击 "edit"；
7. 把 .clang-format 文件的完整内容粘贴进 "value" 框，点击 "OK"；
8. 切到 Beautifier > General 页，勾选 "Enable auto format on file save"；
9. 确认工具选中的是 "ClangFormat"，点击 "OK"。

文档还给出两条务实的注意事项：

• Ladybird 并非整个代码库都已通过 clang-format 清理，因此保存文件时偶尔会出现大面积 diff。作者建议自行判断：只有几行的话直接带上没问题；如果整文件都被重排，更好的做法是单独提交一次格式化，或者直接忽略这些格式改动。可以顺便学习 git add -p（按块暂存）与 git checkout -p（按块回退）的用法；
• IPC 定义文件会被误格式化：Qt Creator 倾向把 .ipc 文件当作 C++ 头文件并尝试格式化，这没有意义。解决办法是告诉 Qt Creator 这些文件是纯文本：
  1. 菜单 Tools > Options...；
  2. 搜索框输入 "beau"，进入 Environment > MIME Types；
  3. 在小的搜索框中输入 "plain"，选中 text/plain；
  4. 在 "details" 区可见 Patterns 列表（形如 *.txt;*.asc;*,v），将其扩展为 *.txt;*.asc;*,v;*.ipc;*.gml；
  5. 点击 "OK" 关闭对话框；
  6. 可能需要把已打开的 IPC 文件关掉再重新打开。验证方式：右键编辑器页签中的文件名，选择 "Properties..."，第三行应显示 MIME type: text/plain。

四、License 模板：输入 lic 自动插入版权声明

Ladybird 的源码文件统一以如下版权头开头：

/*
 * Copyright (c) 2024-present, the Ladybird developers.
 *
 * SPDX-License-Identifier: BSD-2-Clause
 */

文档演示的用法是：新建任意位置的一个文件（例如 license-template.creator），把上面的标准许可证模板写入其中，然后在 Qt Creator 中：

1. 打开菜单 Tools -> Options，找到 C++ 区域；
2. 切到 "File Naming" 标签页（文档作者吐槽了一句"不要问它为什么在这里"）；
3. 页面底部有 "License template:" 选项，点击 "Browse…" 选中刚才的 license-template.creator 文件；
4. 点击 "OK" 完成配置。

配置完成后，在 C++ 文件开头输入 lic 即可自动展开出完整的版权声明，配合第三节的保存时自动格式化，新文件从版权头到代码风格都与 Ladybird 代码库保持一致。

五、小结

本文覆盖的完整工作流可以归纳为四步：

1. 导入：Import Existing Project 导入仓库根目录，用 Meta/refresh-ladybird-qtcreator.sh 重建 ladybird.files（新增/删除文件后需重跑）；
2. 三文件对齐：ladybird.config 加 ENABLE_COMPILETIME_FORMAT_CHECK，ladybird.cxxflags 设为 -std=c++23 -fsigned-char -fconcepts -fno-exceptions -fno-semantic-interposition -fPIC，ladybird.includes 列出源码区、Build/release 生成目录与 Skia 头文件路径；
3. 格式化：确认 clang-format 21 后，用 Beautifier 插件注入根目录 .clang-format 规则，开启保存时自动格式化，并把 *.ipc、*.gml 归入 text/plain 以免被误格式化；
4. 版权头：通过 C++ > File Naming 的 License template 配置 lic 快捷模板。

这套配置让 Qt Creator 的索引、补全与格式化行为与 Ladybird 的 CMake 构建和 CI 风格检查（Meta/Linters/lint_clang_format.py）保持一致；其他编辑器（VS Code、CLion、Neovim 等）的配置可参考同目录下的 EditorConfiguration 系列文档。