Xmake 项目中 header-only 包的正确配置方式

问题背景

在使用 Xmake 构建系统管理 C++ 项目时，开发者经常会遇到需要集成第三方库的情况。其中，nlohmann-json 是一个非常流行的 C++ JSON 库，它以纯头文件(header-only)的形式提供。最近 Xmake 开发版本(v2.9.3+)对这类纯头文件库的包管理方式做了重要调整。

问题现象

当用户尝试安装 nlohmann-json 包时，构建过程会失败并显示错误信息"package(nlohmann-json): links not found!"。这是因为 Xmake 默认会检查包的链接库，而纯头文件库实际上并不需要编译或链接任何库文件。

解决方案

Xmake 开发版本现在要求所有纯头文件库必须显式声明为 headeronly 类型。对于 nlohmann-json 这样的纯头文件库，正确的包定义方式是在 xmake.lua 中添加 set_kind("headeronly") 声明：

package("nlohmann-json")
    set_kind("headeronly")  -- 关键声明
    set_homepage("https://nlohmann.github.io/json/")
    set_description("JSON for Modern C++")
    set_license("MIT")
    
    -- 其余配置保持不变
    add_urls("[e-mail]:ceph/nlohmann-json.git")
    add_versions("v3.11.3", "9cca280a4d0ccf0c08f47a99aa71d1b0e52f8d03")
    add_deps("cmake")
    
    on_install(function (package)
        local configs = {"-DJSON_BuildTests=OFF"}
        import("package.tools.cmake").install(package, configs)
    end)
    
    on_test(function (package)
        -- 测试代码保持不变
    end)

技术原理

纯头文件库(header-only)与常规库有以下重要区别：

1. 无需编译：代码实现全部在头文件中，直接包含即可使用
2. 无链接步骤：不会生成静态库(.a)或动态库(.so/.dll)文件
3. 即时可用：包含头文件后立即可调用功能

Xmake 通过 headeronly 标记来识别这类特殊库，从而跳过不必要的编译和链接检查步骤。这种显式声明的方式比隐式推断更加可靠，能避免各种边界情况下的问题。

最佳实践

对于纯头文件库的 Xmake 包定义，建议：

1. 始终明确设置 set_kind("headeronly")
2. 在 on_install 阶段只需处理头文件的安装
3. 测试阶段验证头文件能否正常包含和使用
4. 不需要处理任何链接库相关的配置

这种声明方式不仅适用于 nlohmann-json，也适用于任何其他纯头文件库，如 Catch2、fmt 等。

总结

Xmake 对纯头文件库管理的改进体现了构建系统对现代 C++ 开发模式的支持。通过显式声明库类型，开发者可以更精确地控制构建过程，而构建系统也能做出更合理的决策。这一变化虽然简单，但对于确保构建可靠性和一致性非常重要。