# 构建指南

## 目录

1. [环境要求](#1-环境要求)
2. [获取源码](#2-获取源码)
3. [构建步骤](#3-构建步骤)
4. [CMake 选项](#4-cmake-选项)
5. [作为依赖集成](#5-作为依赖集成)
6. [文档生成](#6-文档生成)
7. [故障排查](#7-故障排查)

---

## 1. 环境要求

| 依赖 | 最低版本 | 说明 |
|------|---------|------|
| CMake | 3.16+ | 构建系统 |
| C++ 编译器 | GCC 9+ / Clang 12+ / MSVC 2019+ | C++17 支持 |
| Eigen | 3.3+（自动下载） | 线性代数（header-only） |
| Google Test | 自动下载 | 单元测试 |
| Doxygen | 1.9+ | API 文档生成（可选） |

---

## 2. 获取源码

```bash
git clone <仓库地址>
cd ViewDesignEngine
```

---

## 3. 构建步骤

### Linux / macOS

```bash
cmake -B build -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_TESTS=ON \
    -DBUILD_EXAMPLES=ON
cmake --build build -j$(nproc)
cd build && ctest --output-on-failure
```

### Windows

```powershell
cmake -B build -G "Visual Studio 17 2022"
cmake --build build --config Release
cd build && ctest --config Release
```

---

## 4. CMake 选项

| 选项 | 默认值 | 说明 |
|------|--------|------|
| `BUILD_TESTS` | ON | 构建单元测试 |
| `BUILD_EXAMPLES` | ON | 构建示例程序 |
| `BUILD_BENCHMARKS` | OFF | 构建性能测试 |
| `BUILD_SHARED_LIBS` | OFF | 构建共享库（默认静态库） |
| `ENABLE_SANITIZERS` | OFF | 启用 ASan/UBSan |
| `ENABLE_LTO` | ON | 启用链接时优化 |

---

## 5. 作为依赖集成

### CMake FetchContent

```cmake
include(FetchContent)
FetchContent_Declare(ViewDesignEngine
    GIT_REPOSITORY <仓库地址>
    GIT_TAG v0.1.0
)
FetchContent_MakeAvailable(ViewDesignEngine)
target_link_libraries(你的项目 PRIVATE vde)
```

### find_package（安装后）

```cmake
find_package(ViewDesignEngine REQUIRED)
target_link_libraries(你的项目 PRIVATE vde::engine)
```

---

## 6. 文档生成

```bash
cmake -B build -DVDE_BUILD_DOCS=ON
cmake --build build --target doc
# 输出：build/docs/html/index.html
```

---

## 7. 故障排查

| 问题 | 解决方案 |
|------|---------|
| Eigen 未找到 | 将自动通过 FetchContent 下载 |
| 编译时间过长 | 使用 `-j` 并行编译，关闭 LTO |
| 链接错误 | 确认 C++17 标准库链接正确 |