依赖图拓扑排序必须先解析语义化版本并构建带版本的有向边（如pkgA→pkgB@v1.2.3），再用Kahn或DFS检测环；std::map<string,vector<string>>直接存依赖会忽略版本约束、漏判循环，且无法处理多平台条件依赖与缓存一致性。
依赖图拓扑排序必须处理循环引用和版本冲突
直接用 std::map<std::string, std::vector<std::string>> 存依赖关系是常见错误——它不记录版本约束，也无法区分 foo@1.2 和 foo@^2.0。真实场景中，一个包可能同时声明 bar>=3.1 和 bar<4.0，而另一个包要求 bar~3.5，此时必须用语义化版本解析器（如 semverpp 或轻量自实现）先归一化再比对。
拓扑排序前务必做两件事：
• 对每个包的每个依赖项调用 resolve_version() 获取满足所有约束的最高兼容版本
• 构建有向图时，边应为 pkgA → pkgB@vX.Y.Z 而非 pkgA → pkgB，否则循环检测会漏判（例如 A→B@1.0、B@1.0→A 是环，但 A→B、B→A 可能被误认为可解）
实操建议：
• 用 std::unordered_map<std::string, std::shared_ptr<Package>> 缓存已解析的包实例，避免重复解析同一版本
• 检测到环时，抛出带完整路径的异常： "cycle detected: zlib→cmake→zlib@1.2.12"，而不是只报 "cycle"
源码编译必须隔离构建目录并显式传递工具链
跨平台最常崩在构建阶段：Windows 上用 MSVC 编译 Linux 风格的 Makefile，或 macOS 上默认用 Clang 却链接了 GCC 编译的静态库。核心原则是——**绝不复用源码目录作为构建目录**，且工具链必须由包自身声明，不能继承宿主环境。
立即学习“C++免费学习笔记（深入）”；
每个包的 build() 方法应强制创建独立子目录（如 build-<os>-<arch>-<toolchain></toolchain></arch></os>），并在其中执行：
cmake -S . -B ./build-win-x64-msvc -DCMAKE_TOOLCHAIN_FILE=toolchains/vs2022.cmake cmake --build ./build-win-x64-msvc --config Release
关键点：
• 工具链文件（toolchains/ 下）需按平台预置，Linux 用 gcc-x86_64-linux-gnu.cmake，macOS 用 clang-apple-silicon.cmake
• CMake 的 -G 参数必须动态选择：Ninja（全平台）、Unix Makefiles（Linux/macOS）、Visual Studio 17 2022（Windows）
• 若包无 CMakeLists.txt，需 fallback 到 configure && make，但必须设置 CC/CXX 环境变量，不能依赖 $PATH
安装路径与符号链接在不同系统行为差异极大
Linux/macOS 习惯把头文件装到 /usr/local/include，库到 /usr/local/lib；Windows 则倾向 C:Program Filesmypkginclude。硬编码路径必然失败。更麻烦的是符号链接：ln -s 在 Windows 默认不可用，而 mklink 需管理员权限。
正确做法是：
• 所有安装路径通过 get_install_prefix() 统一获取，该函数根据 OS + INSTALL_MODE（system/user/portable）返回根路径
• 头文件、库、bin 三类路径再由 join_path(prefix, "include") 等生成，而非拼接字符串
• 符号链接逻辑必须降级：Linux/macOS 用 symlink()，Windows 用 CreateHardLinkW()（仅同卷）或直接复制（portable 模式）
容易踩的坑：
• 忽略 Windows 的长路径限制（MAX_PATH=260），需在创建目录前调用 SetCurrentDirectoryA("\\?\C:\full\path")
• macOS 的 @rpath 依赖必须用 install_name_tool -add_rpath 修正，否则运行时报 dyld: Library not loaded
包元数据格式必须支持多源与条件依赖
纯 JSON 或 INI 不够用。比如一个包在 Linux 依赖 libcurl-dev，在 Windows 依赖 winhttp，在 macOS 用 CFNetwork——这需要条件字段。YAML 支持锚点和条件块，但解析库（如 yaml-cpp）在 Windows 上编译麻烦；TOML 更轻量，且 cpptoml 兼容性好。
推荐元数据结构示例：
[dependencies]
zlib = "1.2.12"
openssl = { version = "3.0.0", optional = true }
[platform.linux.dependencies]
libcurl = "7.85.0"
[platform.windows.dependencies]
winhttp = "10.0"
[features.json]
dependencies = ["jsoncpp"]
解析时注意：
• 条件块（[platform.*]）只在匹配 OS 时合并进主依赖表
• optional = true 的包不参与拓扑排序，但若被其他包显式启用（如 features = ["json"]），则必须加入图中
• 所有版本字段统一走 parse_semver()，拒绝 "latest" 或 "master" 这类非确定值
真正难的是缓存一致性：同一个 zlib@1.2.12 在不同平台可能对应不同源码压缩包（zlib-1.2.12.tar.gz vs zlib-1.2.12-win.zip），校验和必须按平台分开存，不能共用一个 sha256 字段。
