ViewDesignEngine/docs/dev-guide/building.md

# 构建指南

本文档说明如何从源码构建 ViewDesignEngine。

## 目录

1. [环境要求](#1-环境要求)
2. [快速构建](#2-快速构建)
3. [Docker 构建](#3-docker-构建)
4. [CMake 选项](#4-cmake-选项)
5. [依赖管理](#5-依赖管理)
6. [跨平台构建](#6-跨平台构建)
7. [常见问题](#7-常见问题)

---

## 1. 环境要求

| 组件 | 最低版本 | 推荐版本 |
|------|---------|---------|
| C++ 编译器 | GCC 11 / Clang 16 | GCC 13 / Clang 18 |
| CMake | 3.16 | 3.28+ |
| Eigen 3 | 3.3 | 3.4.0 (自动下载) |
| Python (可选) | 3.8 | 3.11+ |
| pybind11 (可选) | 2.10 | 2.12+ |
| CUDA (可选) | 10.0 | 12.0+ |

### 安装编译工具

**Ubuntu/Debian**:
```bash
sudo apt update
sudo apt install build-essential cmake g++-11
```

**CentOS/RHEL 8**:
```bash
sudo yum install gcc-toolset-11 cmake3
scl enable gcc-toolset-11 bash
```

**macOS**:
```bash
brew install cmake gcc@13
```

**Windows (MSYS2)**:
```bash
pacman -S mingw-w64-x86_64-cmake mingw-w64-x86_64-gcc
```

## 2. 快速构建

```bash
# 克隆仓库
git clone ssh://git@localhost:22/hm/ViewDesignEngine.git
cd ViewDesignEngine

# 创建构建目录
cmake -B build -DCMAKE_BUILD_TYPE=Release

# 构建（使用所有 CPU 核心）
cmake --build build -j$(nproc)

# 运行测试
cd build && ctest --output-on-failure
```

### 构建类型

| 类型 | 说明 |
|------|------|
| `Release` | 优化构建，生产环境使用 |
| `Debug` | 调试符号，无优化 |
| `RelWithDebInfo` | 优化 + 调试符号 |
| `MinSizeRel` | 最小体积 |

```bash
# Debug 构建（包含 Address Sanitizer）
cmake -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_SANITIZERS=ON
cmake --build build -j$(nproc)
```

## 3. Docker 构建

推荐使用 Docker 确保构建环境一致。

### 3.1 预构建镜像

```bash
# 拉取或构建镜像
docker build -t vde-builder -f docker/Dockerfile.dev .

# Release 构建
docker run --rm --cpus=4 --memory=8g \
    -v $(pwd):/ws vde-builder bash -c \
    "cd /ws && cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j4"

# 运行测试
docker run --rm --cpus=4 --memory=8g \
    -v $(pwd):/ws vde-builder bash -c \
    "cd /ws/build && ctest --output-on-failure"
```

### 3.2 资源限制

```bash
# 模拟低配环境（2 核 / 4GB）
docker run --rm --cpus=2 --memory=4g --memory-swap=4g \
    -v $(pwd):/ws vde-builder bash -c \
    "cd /ws && cmake -B build_ci -DCMAKE_BUILD_TYPE=Release && cmake --build build_ci -j2"
```

## 4. CMake 选项

| 选项 | 默认值 | 说明 |
|------|--------|------|
| `BUILD_TESTS` | ON | 构建测试 |
| `BUILD_BENCHMARKS` | OFF | 构建性能基准 |
| `BUILD_EXAMPLES` | ON | 构建示例程序 |
| `ENABLE_SANITIZERS` | OFF | 启用 Address Sanitizer |
| `VDE_USE_GMP` | OFF | GMP 精确运算 |
| `VDE_USE_OPENMP` | ON | OpenMP 并行 |
| `VDE_USE_CUDA` | OFF | CUDA GPU 加速 |
| `VDE_BUILD_PYTHON` | OFF | Python 绑定 |

### 常用组合

```bash
# 开发调试（ASan + Debug）
cmake -B build_asan \
    -DCMAKE_BUILD_TYPE=Debug \
    -DENABLE_SANITIZERS=ON \
    -DVDE_USE_OPENMP=OFF

# 生产构建（Release + OpenMP）
cmake -B build_release \
    -DCMAKE_BUILD_TYPE=Release \
    -DVDE_USE_OPENMP=ON

# GPU 加速
cmake -B build_gpu \
    -DCMAKE_BUILD_TYPE=Release \
    -DVDE_USE_CUDA=ON

# Python 绑定
cmake -B build_py \
    -DCMAKE_BUILD_TYPE=Release \
    -DVDE_BUILD_PYTHON=ON

# 基准测试
cmake -B build_bench \
    -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_BENCHMARKS=ON
```

## 5. 依赖管理

VDE 使用 CMake FetchContent 自动下载依赖，无需手动安装。

### 自动下载的依赖

| 依赖 | 版本 | 用途 |
|------|------|------|
| Eigen 3 | 3.4.0 | 线性代数 |
| Google Test | 1.14.0 | 单元测试 |
| Google Benchmark | (可选) | 性能基准 |
| pybind11 | (可选) | Python 绑定 |

### 系统依赖

| 依赖 | 检测方式 | 回退 |
|------|---------|------|
| Eigen 3 | `find_package(Eigen3)` | FetchContent 自动下载 |
| GMP | `find_package(GMP)` | `VDE_USE_GMP=OFF` 时跳过 |
| OpenMP | `find_package(OpenMP)` | `VDE_USE_OPENMP=OFF` 时跳过 |
| CUDA | `find_package(CUDAToolkit)` | `VDE_USE_CUDA=OFF` 时跳过 |

```bash
# 使用系统 Eigen（加速首次构建）
sudo apt install libeigen3-dev       # Ubuntu
sudo yum install eigen3-devel        # CentOS

# 使用系统 GTest
sudo apt install libgtest-dev        # Ubuntu
```

## 6. 跨平台构建

### Linux

```bash
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
```

### macOS

```bash
# 使用 Homebrew GCC
export CC=/usr/local/bin/gcc-13
export CXX=/usr/local/bin/g++-13
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(sysctl -n hw.ncpu)
```

### Windows (MSYS2 MinGW64)

```bash
cmake -B build -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
```

### Windows (Visual Studio)

```bash
cmake -B build -G "Visual Studio 17 2022"
cmake --build build --config Release
```

## 7. 常见问题

### Q: CMake 找不到编译器

```bash
export CC=/usr/bin/gcc-11
export CXX=/usr/bin/g++-11
cmake -B build ...
```

### Q: FetchContent 下载失败（网络问题）

手动下载并放到 `build/_deps/`：
```bash
mkdir -p build/_deps
# 下载 eigen-3.4.0.tar.gz 到 build/_deps/
# 下载 googletest-1.14.0.tar.gz 到 build/_deps/
```

### Q: 编译内存不足

```bash
# 限制并行数
cmake --build build -j2

# 或在 Docker 中限制内存
docker run --memory=4g ...
```

### Q: ASan 报告内存泄漏

```bash
# Debug + ASan 构建
cmake -B build_asan -DCMAKE_BUILD_TYPE=Debug -DENABLE_SANITIZERS=ON
cmake --build build_asan -j$(nproc)

# 运行测试并检查泄漏
cd build_asan
ASAN_OPTIONS=detect_leaks=1 ctest --output-on-failure
```

### Q: 如何加速增量构建

```bash
# 安装 ccache
sudo apt install ccache
export CMAKE_C_COMPILER_LAUNCHER=ccache
export CMAKE_CXX_COMPILER_LAUNCHER=ccache
cmake -B build ...
```

### Q: 构建产物位置

```
build/
├── src/               # 静态库 (.a)
│   ├── libvde_foundation.a
│   ├── libvde_core.a
│   ├── libvde_curves.a
│   ├── libvde_mesh.a
│   ├── libvde_spatial.a
│   ├── libvde_boolean.a
│   ├── libvde_collision.a
│   ├── libvde_brep.a
│   ├── libvde_sdf.a
│   ├── libvde_sketch.a
│   └── libvde_capi.a
├── tests/             # 测试可执行文件
├── bench/             # 基准测试 (BUILD_BENCHMARKS=ON)
├── examples/          # 示例程序
└── python/            # Python 绑定 (VDE_BUILD_PYTHON=ON)
```