This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
构建指南
本文档说明如何从源码构建 ViewDesignEngine。
目录
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)