安装

环境要求

要求	最低版本	说明
CMake	3.25	现代 target 与安装规则
编译器	MSVC 19.4、Clang 17、GCC 13	C++23 是硬性要求
Git 子模块	固定修订	DataFrame、ImGui 与 ImPlot 源码
Python	不需要	只有工具、基准与文档使用它

核心库在构建时不需要 Python、Doxygen 或 Sphinx。这些工具只在构建本站点或运行基准测试时才需要。

从检出的源码构建

git clone https://github.com/cloudQuant/fincore_cpp.git
cd fincore_cpp
git submodule update --init --recursive
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
ctest --test-dir build --output-on-failure

测试套件共 1092 个用例，在桌面机器上不到一分钟。如果 configure 报告缺少 CMakeLists.txt，说明子模块没有初始化。

构建选项

选项	默认值	作用
`FINCORE_BUILD_TESTING`	`ON`	构建测试目标；消费者构建可关闭
`FINCORE_ENABLE_ASAN`	`OFF`	对 fincore 目标启用 AddressSanitizer
`FINCORE_ENABLE_UBSAN`	`OFF`	对 fincore 目标启用 UndefinedBehaviorSanitizer
`FINCORE_BUILD_IMPLOT`	`OFF`	构建 ImPlot 适配器；需要图形依赖
`FINCORE_BUILD_IMPLOT_DEMO`	`OFF`	构建示例；需要 `FINCORE_BUILD_IMPLOT=ON`
`FINCORE_DATAFRAME_SOURCE_DIR`	空	使用调用方提供的 DataFrame 检出而不是子模块

消毒器构建是另一种配置；不要把它混进 release 树：

cmake -S . -B build-asan -DCMAKE_BUILD_TYPE=RelWithDebInfo -DFINCORE_ENABLE_ASAN=ON
cmake --build build-asan --parallel
ctest --test-dir build-asan --output-on-failure

安装与使用

cmake --install build --prefix /path/to/prefix

它把头文件写到 <prefix>/include/fincore、库写到 <prefix>/lib（Windows 上是 bin），并把 CMake 包写到 <prefix>/lib/cmake/fincore，其中包含 fincoreConfig.cmake、fincoreConfigVersion.cmake（同主版本兼容）与导出的 target。

find_package(fincore CONFIG REQUIRED COMPONENTS fincore)
target_link_libraries(my_target PRIVATE fincore::fincore)

安装后的包会调用 find_dependency(DataFrame CONFIG REQUIRED)，因此消费者环境也必须能找到构建该库时使用的 DataFrame 包。如果两者没有并排安装，请把两个前缀都加入 CMAKE_PREFIX_PATH。

可选的 ImPlot 组件单独导出，只有用 FINCORE_BUILD_IMPLOT=ON 构建时才存在：

find_package(fincore CONFIG REQUIRED COMPONENTS fincore implot)

验证安装

#include <fincore/metrics/basic.hpp>
#include <cstdio>

int main() {
    std::printf("%.0f\n",
                fincore::annualization_factor(fincore::frequency::daily));
    return 0;
}

针对安装前缀编译并运行它。如果能链接，说明头文件、库与导出 target 对齐；如果 configure 失败，要检查的是 fincore_DIR 或 DataFrame 依赖。

平台说明

Windows。 从 Visual Studio 开发者命令行运行 CMake，使 cl.exe 在 PATH 上。多配置生成器会把二进制放在 Release/ 下；给 cmake --build 传 --config Release，给 ctest 传 -C Release。
macOS 与 Linux。 固定子模块用系统编译器构建；核心库不需要额外软件包。
CI。 每次推送都会覆盖 Windows 与 macOS；GCC 13 的 ubuntu-latest 任务存在已知的 constexpr 限制失败，记录在迭代说明中。

文档构建

站点是一个 Sphinx 项目，按语言构建两次：

python -m venv .venv-docs
.venv-docs/bin/pip install -r docs/requirements-docs.txt
cd docs/site
doxygen Doxyfile
python tools/normalize_doxygen_xml.py ../_build/doxygen/xml
sphinx-build -b html -W -n --keep-going . ../_build/html/en
FINCORE_DOCS_LANGUAGE=zh_CN sphinx-build -b html -W -n --keep-going . ../_build/html/zh_CN
cd ../..
python docs/site/tools/check_built_site.py

检查器在内部链接断开、构建页面出现机器路径、或目录条目未翻译/为 fuzzy 时以非零退出。docs/site/README.md 记录了维护规则，包括为什么标题不能以数字开头。