安装目录结构规范
本文描述了 kmpkg 安装目录的结构约定。安装目录用于存储每个包的安装文件，端口作者应确保其包遵循本文所述的规范。
在 经典模式 中，安装目录位于 $KMPKG_ROOT/installed（其中 $KMPKG_ROOT 是你的 kmpkg 安装路径）；在 清单模式 中，每个清单文件对应一个 kmpkg_installed 目录。可通过 --x-install-root 选项修改安装目录的位置。无论使用哪种模式，安装目录的结构保持一致。
安装目录会在首次安装包时自动创建。若未看到该目录，请先 安装一些包。
根目录结构
安装目录的根级别包含以下内容：
kmpkg目录：跟踪已安装的包和文件；- 每个 三元组 对应的目录：存储该三元组下所有包的安装文件。
三元组目录结构
每个包的安装输出都存储在对应的三元组目录中。例如，为 x64-windows 三元组安装的包位于 installed/x64-windows 目录下。
所有三元组目录的子目录结构完全一致：
部分包可能会生成不符合以下约定的文件，端口作者应根据文件的用途确定其最终存储位置。
| 子目录 | 文件类型 |
|---|---|
bin | Release 版本的 .dll 和 .pdb 文件 |
debug/bin | Debug 版本的 .dll 和 .pdb 文件 |
debug/lib | Debug 版本的 .lib、.so、.dylib 和 .a 文件 |
debug/lib/manual-link | 需手动链接的 Debug 版本 .lib、.so、.dylib 和 .a 文件 |
debug/plugins/<group> | 运行时加载的 Debug 版本 .dll 文件 |
debug/lib/pkgconfig | Debug 版本的 pkgconfig 文件（.pc） |
include | 头文件（.h、.hpp、.hxx） |
lib | Release 版本的 .lib、.so、.dylib 和 .a 文件 |
lib/manual-link | 需手动链接的 Release 版本 .lib、.so、.dylib 和 .a 文件 |
lib/pkgconfig | Release 版本的 pkgconfig 文件（.pc） |
plugins/<group> | 运行时加载的 Release 版本 .dll 文件 |
share/<port> | 独立于配置的额外文件（如许可证、脚本等） |
share/<port>/copyright | 包的许可证文本文件 |
share/<port>/usage | 构建系统集成说明文件 |
share/<port>/kmpkg-port-config.cmake | 端口定义的 CMake 函数和变量 |
share/<小写包名>/<包名>Config.cmake | 支持 find_package(package) 的 CMake 集成文件 |
share/<cmakepackagename>/kmpkg-cmake-wrapper.cmake | CMake find_package(<cmakepackagename>) 覆盖文件 |
share/pkgconfig | 独立于配置的 pkgconfig 文件（.pc） |
tools/<port> | 可执行工具 |
bin 和 debug/bin 目录
在 Windows 平台，这两个目录分别存储 Release 和 Debug 配置的 DLL 和 PDB 文件。端口生成的任何可执行文件应移至 tools/<port> 目录。
include 目录
存储头文件（.h、.hpp、.hxx）。该目录下的结构应反映包的头文件使用方式。例如，若 contoso 库希望通过 #include <contoso/contoso.h> 引用，应将头文件放置在 include/contoso/contoso.h 路径下。
kmpkg 禁止在 include 根目录安装部分保留头文件名（如 err.h、user.h、time.h 等）。若库需要提供这些禁止的头文件名，应将其放置在 include/<port> 目录下；若库意图替换系统头文件，需在 portfile.cmake 中设置 KMPKG_POLICY_ALLOW_RESTRICTED_HEADERS 策略。
lib 和 debug/lib 目录
存储静态库、导入库（Windows 平台）和共享库（非 Windows 平台）。
lib/manual-link 和 debug/lib/manual-link 目录
存储必须手动链接的库。
若库在自动链接时可能引发问题（例如，库定义了程序的 main() 函数），需将其放置在 lib/manual-link 目录而非 lib 目录。
lib/pkgconfig、debug/lib/pkgconfig 和 share/pkgconfig 目录
存储 pkgconfig 集成文件（.pc）。一个库不应同时提供“配置相关”和“配置独立”的 pkgconfig 文件（例如，不应同时安装 lib/pkgconfig/contoso.pc 和 share/pkgconfig/contoso.pc）。
plugins/<group> 和 debug/plugins/<group> 目录
存储供应用程序运行时加载的共享库。
share/<port> 目录
存储端口安装的杂项文件（如 SPDX 许可证文件、脚本、文档等）。
share/<port>/copyright 文件
kmpkg 要求端口提供 copyright 文件，包含安装包的许可证信息。详情请参考 维护者指南。
share/<port>/usage 文件
文本文件，包含库在项目中的集成说明。详情请参考 为包提供使用文档的指南。
share/<小写包名>/<包名>Config.cmake、share/<包名>/<包名>-config.cmake 文件
CMake 集成文件应放置在 share 目录下，并遵循 CMake 的 find_package(package) 配置模式搜索规则。
例如，若端口需要支持 find_package(MyPackage REQUIRED)，必须提供 share/mypackage/MyPackageConfig.cmake 或 share/mypackage/MyPackage-config.cmake。
若包提供 CMake 集成文件，应调用 kmpkg_cmake_config_fixup() 辅助函数，以修复非可重定位路径并合并构建配置。
tools/<port> 目录
kmpkg 本质上是一个 C++ 库依赖管理器。端口作者在决定是否将工具包含在安装输出中时应谨慎。例如：仅当调试工具不必要时，可只安装 Release 版本的可执行文件；若工具用于运行时，则应同时提供 Release 和 Debug 版本。
存储端口生成的可执行工具。强烈建议（但非强制）将每个可执行文件放置在与端口名对应的子目录下。例如，contoso 端口可将 ContosoGenerator.exe 安装到 tools/contoso/ContosoGenerator.exe。
部分端口要求其可执行文件放置在 bin 子目录中，此时推荐的路径是 tools/<port>/bin。