茂之钳
486a0fe011
New structure: - docs/index.md — main navigation - docs/getting-started.md — 5-minute quick start - docs/guides/module-manual.md — all 11 modules with file listing - docs/guides/api-usage.md — API reference with code examples - docs/guides/ — architecture, building, testing, contributing - docs/reference/ — competitive analysis, gap analysis, versioning - docs/api/ — Doxygen generated HTML - docs/archive/ — historical development plans Old development plans archived. Clean 4-directory layout.
293 lines
6.4 KiB
Markdown
293 lines
6.4 KiB
Markdown
# 构建指南
|
||
|
||
本文档说明如何从源码构建 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)
|
||
```
|