ViewDesignEngine/docs/dev-guide/building.md

构建指南

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

目录

1. 环境要求
2. 快速构建
3. Docker 构建
4. CMake 选项
5. 依赖管理
6. 跨平台构建
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:

sudo apt update
sudo apt install build-essential cmake g++-11

CentOS/RHEL 8:

sudo yum install gcc-toolset-11 cmake3
scl enable gcc-toolset-11 bash

macOS:

brew install cmake gcc@13

Windows (MSYS2):

pacman -S mingw-w64-x86_64-cmake mingw-w64-x86_64-gcc

2. 快速构建

# 克隆仓库
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	最小体积

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

3. Docker 构建

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

3.1 预构建镜像

# 拉取或构建镜像
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 资源限制

# 模拟低配环境（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 绑定

常用组合

# 开发调试（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 时跳过

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

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

6. 跨平台构建

Linux

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

macOS

# 使用 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)

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

Windows (Visual Studio)

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

7. 常见问题

Q: CMake 找不到编译器

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

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

手动下载并放到 build/_deps/：

mkdir -p build/_deps
# 下载 eigen-3.4.0.tar.gz 到 build/_deps/
# 下载 googletest-1.14.0.tar.gz 到 build/_deps/

Q: 编译内存不足

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

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

Q: ASan 报告内存泄漏

# 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: 如何加速增量构建

# 安装 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)