clice/docs/zh/dev/builtin-library.md

Builtin Libraries

Builtin library 会被直接编译进 clice 可执行文件，而不是在运行时通过 --plugin-path 动态加载。

这种方式适合以下场景：

• 插件源码位于 clice 源码树之外
• 希望该 builtin 默认随 clice 可执行文件一起发布
• 需要为该 builtin 单独补充 include 路径、编译宏或链接依赖

CMake 入口

clice 现在提供了一个辅助模块：cmake/builtin-libraries.cmake。

额外的 builtin library 通过缓存变量 CLICE_BUILTIN_LIBRARY_MODULES 注册。

CLICE_BUILTIN_LIBRARY_MODULES 中的每一项都必须是一个 CMake 文件。配置阶段 clice 会 include() 这些文件，而每个文件都需要调用 clice_add_builtin_library(...)。

最小示例

你可以在外部项目中创建一个 CMake 文件，例如 /path/to/my-plugin/clice-builtin.cmake：

clice_add_builtin_library(
    NAME my_plugin
    SOURCES
        "${CMAKE_CURRENT_LIST_DIR}/src/MyPlugin.cpp"
    INCLUDE_DIRECTORIES
        "${CMAKE_CURRENT_LIST_DIR}/include"
    ENTRYPOINT
        clice_get_my_plugin_server_plugin_info
)

然后在配置 clice 时传入：

cmake -B build -G Ninja \
    -DCLICE_BUILTIN_LIBRARY_MODULES="/path/to/my-plugin/clice-builtin.cmake"

如果要加载多个模块，可以传入以分号分隔的 CMake 列表：

cmake -B build -G Ninja \
    -DCLICE_BUILTIN_LIBRARY_MODULES="/path/to/a.cmake;/path/to/b.cmake"

clice_add_builtin_library

该辅助函数支持以下参数：

参数	必填	说明
NAME	是	逻辑名称，会用于创建内部 object target
SOURCES	是	要编译进 clice 的源文件，支持绝对路径和源码树外路径
ENTRYPOINT	是	clice 命名空间中的唯一函数名，返回值类型为 ::clice::PluginInfo
INCLUDE_DIRECTORIES	否	仅对当前 builtin 生效的额外头文件目录
LINK_LIBRARIES	否	当前 builtin 额外需要的库或 target
COMPILE_DEFINITIONS	否	当前 builtin 额外需要的编译宏
COMPILE_OPTIONS	否	当前 builtin 额外需要的编译选项

Entrypoint 要求

所有 builtin library 最终都会被链接进同一个可执行文件，因此每个 builtin 都必须在 clice 命名空间中使用唯一的入口函数名。

动态插件通常使用：

clice_get_server_plugin_info()

builtin library 应该改用类似下面的唯一名字：

clice_get_my_plugin_server_plugin_info()

例如：

#include "Server/Plugin.h"

namespace clice {

::clice::PluginInfo clice_get_my_plugin_server_plugin_info() {
    return {
        CLICE_PLUGIN_API_VERSION,
        "MyPlugin",
        "v0.0.1",
        CLICE_PLUGIN_DEF_HASH,
        [](clice::ServerPluginBuilder& builder) {
            // 在这里注册回调
        },
    };
}

}  // namespace clice

clice 会自动生成静态注册代码，因此只要模块被包含进来，就不需要再手动修改 src/clice.cc。