---
name: wind-third-party-libs
description: wind_power_cal 第三方库管理规范。用于新增/引用/重新编译 third_party 下的 Drogon、nlohmann 等库时，按 ensure_third_party.sh 的源码编译与调用约定操作。
---

# 第三方库管理

## 现有
| 目录 | 说明 | 是否入库 |
| --- | --- | --- |
| `third_party/drogon_repo/` | Drogon + Trantor 源码（vendored，无 .git/build） | ✅ 入库 |
| `third_party/nlohmann/` | header-only json（`json.hpp` + `json_fwd.hpp`） | ✅ 入库 |
| `third_party/drogon/install/<arch>/` | 源码编译产物 | ❌ gitignored |

## 源码编译 Drogon
`third_party/ensure_third_party.sh`：
- 架构检测 `x64 / arm64 / arm32`
- cmake flags：`BUILD_SHARED_LIBS=ON USE_SUBMODULE=ON BUILD_CTL=OFF BUILD_EXAMPLES=OFF BUILD_ORM=OFF BUILD_TESTING=OFF BUILD_BROTLI=ON BUILD_YAML_CONFIG=OFF`，`CMAKE_INSTALL_LIBDIR=libs`
- 安装到 `third_party/drogon/install/<arch>/`；产物存在（`libs/cmake/Drogon/DrogonConfig.cmake`）则跳过

## 调用约定（重要，踩过坑）
- **被 source 时**显式传 `THIRD_PARTY=<root>/third_party`：调用方（如 `package.sh`）可能已预设 `SCRIPT_DIR`，会让本脚本 `${SCRIPT_DIR:-}` 推导到错误目录。
  ```bash
  THIRD_PARTY="${ROOT_DIR}/third_party" source "${ROOT_DIR}/third_party/ensure_third_party.sh"
  ```
- 脚本内**软失败用 `return`，不要用 `exit`**（被 source 时 `exit` 会杀掉父 shell）。本仓库写法：`return 0 2>/dev/null || exit 0`。
- 导出 `TARGET_ARCH` 与 `DROGON_INSTALL` 供后续 cmake / run.sh 使用。

## 引用方式
- 后端 CMake：`find_package(Drogon CONFIG REQUIRED)`，由顶层 `DROGON_LOCAL_PREFIX` 注入查找路径。
- json：`#include <nlohmann/json.hpp>`（third_parent 在 include path）。

## 新增第三方库
- header-only（如 nlohmann）：直接放 `third_party/<name>/`，CMake 加 include path。
- 需编译：仿照 `ensure_third_party.sh` 的 Drogon 块，源码放 `third_party/<name>_repo/`，编译安装到 `third_party/<name>/install/<arch>/`，产物 gitignore。