企业官网建设流程全解析

• 桌面应用
• 开发工具

导读

figura是桌面启动器 Vicinae 内置的一个 C++ 库/工具，用于以高层接口解析并处理 Freedesktop 规范（当前大致覆盖 mime-apps 与 desktop-entry 两类），是启动器在 Linux 桌面上识别应用入口、处理 MIME 关联的关键支撑。本文以 figura 官方 README 为骨架，结合仓库源码梳理其设计目标、构建方式、命令行入口与周边实现，帮助你快速掌握如何在 Vicinae 构建体系中复用它、或单独编译安装它。

一、figura 是什么：定位与设计目标

依据 README，figura 是一个C++ 库，目标是提供高层接口（high-level interfaces）来应对各种 Freedesktop 规范——最典型的就是 desktop entry（桌面入口规范）。它目前（粗略地）实现了两类规范：

• mime-apps：MIME 类型与默认应用程序的关联规范；
• desktop-entry：.desktop桌面入口文件规范。

需要特别强调的是两点前提：

1. 早期阶段：README 明确说明该库处于 very early stage；
2. 专属依赖：它“exclusively relied on by the Vicinae launcher”（完全由 Vicinae 启动器依赖），不属于对外发布的稳定 API，随时可能发生不兼容破坏性变更（Breaking changes WILL occur），自用请自行承担风险（use at your own risk）。

从仓库结构看，figura 位于 src/lib/figura，与另一套更成熟的 Freedesktop 实现库 src/lib/xdgpp 相邻——后者实现了 mime-apps、desktop-entry 与 desktop-bookmark（recently-used.xbel）三类规范。可以推断，figura 是 Vicinae 在 xdgpp 之外引入的、面向代码生成的另一条技术路线，二者在规范解析层面形成互补。

二、figura 源码结构：从库到 CLI 的组成

figura 目录下包含一个独立的 CMake 工程与一个 Makefile 包装：

构建目标：静态库还是动态库

Makefile 提供了两种库形态：

# 静态库（默认） make static # 动态库 make shared

底层实现上，static与shared均通过 Ninja 生成器调用 CMake：

static: cmake -GNinja -B $(BUILD_DIR) cmake --build $(BUILD_DIR) .PHONY: static shared: cmake -GNinja -DBUILD_SHARED_LIBS=ON -B $(BUILD_DIR) cmake --build $(BUILD_DIR) .PHONY: shared

区别仅在于shared额外传入-DBUILD_SHARED_LIBS=ON；BUILD_DIR默认为build。CMake 侧则要求：

• cmake_minimum_required(VERSION 3.16)；
• CMAKE_CXX_STANDARD 23且强制开启（CMAKE_CXX_STANDARD_REQUIRED ON）；
• 生成可执行目标figura（源文件 main.cpp 与 cli.cpp），并链接vicinae::common；
• 开启CMAKE_EXPORT_COMPILE_COMMANDS，便于 IDE/工具读取编译数据库。

也就是说，独立构建 figura 的前提是仓库内的vicinae::common目标（位于 src/lib/common）可被 CMake 解析到。README 也提醒：如果你不打算单独使用它，figura 会作为 Vicinae 整体构建流程的一部分被自动编译，无需任何手工步骤。

安装与测试

# 安装（本质为 cmake --install build） make install # 运行库自带测试（开启 XDGPP_BUILD_TESTS 并执行 xdgpp-tests） make test

注意make test实际编译并运行的是xdgpp-tests（见 Makefile），再次印证 figura/xdgpp 两套实现共享测试基础设施。此外 Makefile 还提供format（clang-format 统一格式化src下 hpp/cpp）与clean（删除build/）。

三、figura 命令行入口：json-rpc code gen

虽然 README 未展开 CLI 细节，但从源码可以确认figura是一个可执行代码生成工具：

// src/lib/figura/src/main.cpp int main(int ac, char **av) { CommandLineApp cli{"figura"}; cli.registerCommand<CompileCommand>(); return cli.run(ac, av); }

• 程序名figura，目前只注册了一个子命令CompileCommand（见 compile.hpp）。
• cli.cpp 中的Formatter::make_help在无描述信息时默认标题为"json-rpc code gen"——可以推断 figura 的核心职责是JSON-RPC 相关接口的代码生成，配合src/codegen/下的 glaze、glaze-qt、typescript 后端，为 Vicinae 的 TypeScript 扩展 API 体系（参见 src/typescript）生成绑定代码。
• CLI 基于 CLI11 实现：CommandLineApp::run会注册子命令、设置回调；当不带参数运行时（ac == 1）直接打印彩色 help；随后require_subcommand()强制要求提供子命令，解析失败时通过app.exit处理CLI::ParseError。
• 帮助信息末尾还会输出 Vicinae 官方文档与社区入口的提示（cli.cpp），说明该工具面向 Vicinae 生态的最终用户而非仅内部开发。

四、与 xdgpp 的关系：同一目标的两种实现路径

README 中提到的两类规范（mime-apps、desktop-entry）恰好也是 xdgpp README 声明的实现范围。xdgpp 在仓库中的落点包括：

• 公共头文件 xdgpp/xdgpp.hpp 与子模块mime/、desktop-entry/、bookmark/、locale/、uri/、utils/、xdg-terminal-exec/；
• 测试覆盖 src/lib/xdgpp/tests（entry、mime、bookmark、env、locale、file-uri 等）；
• 被 important-dir-watcher-linux.cpp 等上层组件通过#include "xdgpp/env/env.hpp"实际引用。

而 figura 的侧重点则是解析 + 代码生成：它从codegen/的 glaze 与 TypeScript 输出可以看出，其主要消费方是 Vicinae 的 TypeScript 扩展 API 编译管线。因此可以这样理解分工：xdgpp 负责运行时读取.desktop/MIME 数据供启动器查询应用与图标；figura 负责把 JSON-RPC 接口定义编译成各语言绑定，两者共同构成 Vicinae 在 Linux 桌面上"识别应用、执行扩展"的底层链路。

五、在自己项目中使用 figura 的注意事项

结合 README 的警告与源码事实，若你想在 Vicinae 之外复用 figura，请务必注意：

1. API 不稳定：没有语义化版本承诺，升级 Vicinae 源码即可能引入破坏性变更；
2. 依赖完整：编译依赖vicinae::common与 C++23 编译器（如 GCC 13+/Clang 16+），建议通过仓库根目录的 CMake 预设（见 CMakePresets.json）或顶层 CMakeLists.txt 构建以获得正确的依赖解析；
3. 首选集成方式：直接把它作为 Vicinae 构建的一部分，无需手工执行make static/make install；
4. 命令行用法：figura compile ...（当前唯一子命令），不带参数时打印彩色帮助；其生成目标覆盖 glaze / glaze-qt / TypeScript，具体选项可查看 compile.hpp 与 codegen 头文件。

结语

figura 虽是一个"早期阶段、仅供 Vicinae 使用"的库，但它承担了将 Freedesktop 规范能力与 JSON-RPC 代码生成衔接起来的角色：既有 README 明确声明的 mime-apps / desktop-entry 高层接口目标，也有figura compile这一可实际调用的代码生成入口。理解它的构建命令（make static/make shared/make install）、CLI 结构（json-rpc code gen）与 xdgpp 的分工，你就能在 Vicinae 的扩展开发或二次集成中准确使用这套工具链。

• 桌面应用
• 开发工具