第02章：源码获取、编译与开发环境配置

OCCT 是一个体量较大的 C++ 工程，初次构建经常因为依赖缺失、CMake 选项设置不当而受阻。本章按照官方仓库的 README.md、OCCT_BUILD.md 与 dox/dev_guides/building 文档梳理出一条稳定的搭建路径，覆盖 Windows、Linux、macOS 与常见可视化/数据交换依赖。

1. 获取源码

官方主仓库位于 GitHub：

git clone https://github.com/Open-Cascade-SAS/OCCT.git
cd OCCT
git fetch --tags
git checkout V7_8_0   # 或者最新稳定 tag

仓库默认分支是 master，长期稳定版本以 V7_x_y 形式打 tag，发布说明在 dox/dev_guides/upgrade 与每个版本的 release notes 中。如需贡献代码，应阅读 CONTRIBUTING.md 并使用 Open Cascade 的 mantis bugtracker 流程。

仓库中的 data/ 目录较大，包含示例与测试几何，可以使用 git clone --filter=blob:none --depth=N 之类策略减少带宽，但首次构建建议完整克隆，避免测试失败。

2. 系统级依赖

OCCT 的核心仅依赖 C++ 标准库与少量系统接口，但要启用完整功能需要以下第三方库：

Open Cascade 提供官方“Third-Party Components”包（针对 Windows）打包了 freetype/freeimage/tcl/tbb 等预编译版本，下载地址在官网下载页。Linux/macOS 通常使用系统包管理器安装。

Windows

通过 Visual Studio 2019/2022 + 官方第三方包：

• 安装 VS（含 C++ 开发工具）。
• 下载 3rdparty-vc14-64.zip 解压到例如 C:\OpenCASCADE\3rdparty。
• 安装 CMake 3.22+。

Linux（Ubuntu/Debian）

sudo apt install build-essential cmake \
    libfreetype-dev libtbb-dev tcl-dev tk-dev \
    libgl1-mesa-dev libglu1-mesa-dev libxmu-dev libxi-dev \
    libfreeimage-dev rapidjson-dev libdraco-dev

macOS

brew install cmake freetype tbb tcl-tk freeimage rapidjson draco

此外需要 Xcode Command Line Tools。

3. CMake 构建

OCCT 推荐使用 CMake 进行跨平台构建，旧的 genproj 脚本仍可用但不再优先。常用流程：

mkdir build && cd build
cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=$PWD/../install \
  -DBUILD_LIBRARY_TYPE=Shared \
  -DUSE_FREETYPE=ON \
  -DUSE_TK=ON \
  -DUSE_TBB=OFF \
  -DUSE_FREEIMAGE=ON \
  -DUSE_RAPIDJSON=ON \
  -DUSE_DRACO=ON \
  -DBUILD_MODULE_Draw=ON \
  -DBUILD_MODULE_Visualization=ON \
  -DBUILD_MODULE_DataExchange=ON \
  -DBUILD_MODULE_ApplicationFramework=ON
cmake --build . -j$(nproc)
cmake --install .

关键 CMake 选项：

• BUILD_LIBRARY_TYPE：Shared 或 Static，默认共享。Windows 上 Static 链接 toolkit 数量太大需要全 WHOLEARCHIVE。
• BUILD_MODULE_*：按模块开关裁剪，例如不需要数据交换可关闭 DataExchange。
• USE_*：是否使用某个第三方依赖，关闭后相关 toolkit 不会构建。
• BUILD_RELEASE_DISABLE_EXCEPTIONS：旧版本宏，默认 OFF，保留异常以便诊断。
• INSTALL_DIR_LAYOUT：Default 或 Unix，决定 install 目录布局，跨平台对齐时使用。
• BUILD_DOC_Overview：是否构建 Doxygen 文档。

4. 验证构建

构建完成后，运行 Draw Test Harness 是检验环境的最直接方式：

# 设置环境
source install/env.sh        # Linux/macOS
# 或 install\env.bat          # Windows

# 启动 Draw
draw.sh   # 或 draw.bat

# 在 Draw 控制台中执行
Draw[1]> pload ALL
Draw[2]> box b 100 50 30
Draw[3]> vinit View1
Draw[4]> vdisplay b
Draw[5]> vfit

如果窗口正常显示一个矩形盒子，则核心功能可用。再尝试：

Draw[6]> stepread test.step b1 *
Draw[7]> vdisplay b1_1

验证 STEP 数据交换是否启用。

5. IDE 集成

• Visual Studio：CMake 直接生成 .sln；建议把 Draw 设为启动项目调试。
• Qt Creator：导入 CMake 工程，配置 env.sh 作为运行环境。
• CLion：支持 CMake 多 Profile，可针对 Debug/Release 分别配置。
• VS Code：使用 CMake Tools 插件、C/C++ 插件、CodeLLDB。配置 cmake.configureSettings 即可。

6. 集成到自己的工程

OCCT 安装后会生成 OpenCASCADEConfig.cmake、OpenCASCADE<Module>Targets.cmake，使用方式：

find_package(OpenCASCADE 7.8 REQUIRED COMPONENTS
  FoundationClasses ModelingData ModelingAlgorithms
  Visualization DataExchange ApplicationFramework)
add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE
  TKernel TKMath TKG3d TKBRep TKTopAlgo TKBO TKPrim
  TKV3d TKOpenGl TKService TKSTEP TKIGES TKDEGLTF TKXCAF)

具体 toolkit 名称在 src/<Toolkit>/PACKAGES 与 src/<Toolkit>/EXTERNLIB 中可查；Modules 与 toolkit 的对应关系在 adm/cmake/occt_modules.cmake。

7. 常见构建问题

• 找不到 freetype/tbb：检查 3RDPARTY_FREETYPE_DIR 等 CMake 变量；Windows 上经常需要手动指定。
• OpenGL/Wayland 冲突：Linux 上若使用 Wayland 需安装 libxcb-* 一系列包，或回退到 X11。
• Tcl/Tk 版本错误：Draw 要求 Tcl 8.6 系列；macOS 自带的 Tcl 8.5 不兼容，需要 Homebrew 的 tcl-tk@9 之外的版本。
• 链接报 unresolved external _CLSID_（Windows）：缺少 User32.lib、ComCtl32.lib，应使用官方 CMake 模板。
• glTF 失败：未启用 USE_RAPIDJSON/USE_DRACO，检查 TKDEGLTF 是否生成。

8. 发布与裁剪

OCCT 体量较大（动态库总和数百 MB）。在嵌入式或商业产品中可以裁剪：

• 关闭不需要的模块；
• 仅链接实际使用的 toolkit；
• 在 Release 下开启 LTO、-Os；
• 移除不必要的资源（resources/）；
• 对数据交换格式选择性启用 TKDESTEP、TKDEIGES、TKDESTL、TKDEGLTF、TKDEOBJ、TKDEVRML 等。

9. Docker 与 CI

仓库 .github/workflows 提供 Linux/Windows/macOS 的 CI 配置，可作为持续集成的参考。社区也有维护 Docker 镜像（如 gitpod-io/template-occt、tpaviot/oce-debian），便于在容器中快速试用。建议自有项目使用 OCI 镜像缓存第三方依赖，以加速 CI。

完成本章的环境配置后，便可以开始进入代码层面的学习。下一章将从 OCCT 的底层基础类入手。