企业官网建设流程全解析

F3D 从源码构建完整指南：依赖、CMake 配置、插件与安装

【免费下载链接】f3dFast and minimalist 3D viewer.项目地址: https://gitcode.com/GitHub_Trending/f3/f3d

F3D 是一个基于 CMake 构建系统的快速、极简 3D 查看器。本文是 F3D 的官方构建指南（对应 doc/dev/05-BUILD.md）的深度扩展版，完整覆盖从依赖安装、CMake 配置、可选模块与插件开关、VCPKG 依赖管理、Python 绑定构建，到cmake --install安装组件的全流程。读完本文，你将掌握如何在 Linux/macOS/Windows 上编译出可运行、可测试、可扩展的 F3D，并能按需裁剪或增补功能。

依赖要求

F3D 的构建体系以 CMake 为核心，因此只需安装所需依赖，然后完成「配置（configure）→ 构建（build）」两步即可。如果你是第一次接触 CMake 编译流程，建议先阅读 入门指南；面向 WebAssembly 的交叉编译请参考 WebAssembly 构建指南；其他专用工具链与构建环境见 工具链文档。

核心依赖（必需）

在根目录 CMakeLists.txt 中，F3D 通过find_package(VTK 9.4.0 REQUIRED ...)检索 VTK，并声明了CommonCore、RenderingOpenGL2、IOImage、IOCityGML、IOPLY、IOXML等必选组件，以及IOExodus、IOHDF、IONetCDF、IOOpenVDB、IOPDAL、RenderingGridAxes、RenderingRayTracing等可选组件——可选组件是否存在直接决定后续插件能否启用。

可选依赖（按需启用插件/模块）

持续集成按VFX 参考平台（VFX reference platform）CY2025定义的推荐版本进行连续测试，这也是上表「推荐版本」的来源。

VTK 兼容性说明

F3D 兼容 VTK >= 9.4.0，但部分特性可能不可用。官方建议使用VTK 9.7.0，并在 VTK 配置阶段启用以下模块以获得 F3D 的完整能力：

• RenderingRayTracing（光线追踪）
• IOExodus、IOHDF、IONetCDF（HDF 插件相关）
• IOPDAL、IOOpenVDB（点云与 VDB 插件相关）

需要特别注意的是：当 VTK 面向GLES编译时（通常仅出现在 Android 与 WebAssembly 场景），F3D 只兼容.github/workflows/versions.json中锁定的特定 VTK 版本，不要随意更换版本。

根目录 CMakeLists.txt 中，F3D 会依据VTK_OPENGL_USE_GLES、ANDROID、EMSCRIPTEN自动推导并定义F3D_USE_GLES变量，并在配置阶段打印该变量，便于确认当前构建是否为 GLES 模式。

配置与构建：基础流程

最基础的构建流程只有两步：

# 1. 配置并生成工程 cmake -S /path/to/source -B /path/to/build # 2. 使用生成的构建系统编译 cmake --build /path/to/build

如果你使用单配置生成器（如 Make/Ninja），根 CMakeLists.txt 会在未指定CMAKE_BUILD_TYPE时默认强制为Release；多配置生成器（Visual Studio、Xcode）则默认提供Debug;Release;RelWithDebInfo三种配置。

顶层构建选项

模块与插件开关

以下选项控制 F3D 的模块（modules）、格式插件（plugins）与语言绑定（bindings）。它们的声明集中在根 CMakeLists.txt 与 plugins/CMakeLists.txt，插件目录按开关逐个add_subdirectory引入。

模块（Modules）

插件（Plugins）

语言绑定（Bindings）

内置依赖与外部化

ImGui、dmon、clip、cxxopts、nlohmann_json 等依赖由仓库内置提供（见 external/），如需替换为系统版本，可使用F3D_USE_EXTERNAL_*系列变量，例如：

• F3D_USE_EXTERNAL_CXXOPTS
• F3D_USE_EXTERNAL_NLOHMANN_JSON
• F3D_USE_EXTERNAL_CLIP
• F3D_USE_EXTERNAL_DMON（依赖F3D_MODULE_DMON）
• F3D_USE_EXTERNAL_IMGUI（依赖F3D_MODULE_UI）

对应的find_package逻辑位于根 CMakeLists.txt。

面向贡献者的高级构建选项

根 CMakeLists.txt 还提供了面向开发的选项：

• F3D_STRICT_BUILD：启用严格告警并视告警为错误（MSVC 下/W4 /WX，GCC/Clang 下-Wall -Wextra -Werror等）
• F3D_COVERAGE：生成覆盖率文件（--coverage等标志）
• F3D_SANITIZER：可选择none/address/thread/leak/memory/undefined，为构建注入对应的 sanitizer 编译与链接参数

面向贡献的构建：dev 预设

如果你计划为 F3D 贡献代码，可以直接使用仓库提供的dev配置预设（定义于 CMakePresets.json），一条命令完成「Debug + 测试 + 严格编译」的配置：

cmake --preset=dev /path/to/source

该预设会设置BUILD_TESTING=ON、CMAKE_BUILD_TYPE=Debug、F3D_STRICT_BUILD=ON、F3D_TESTING_DISABLE_CATCH_ALL=ON、F3D_TESTING_ENABLE_LONG_TIMEOUT_TESTS=ON。注意：可选依赖需要在此之上按需手动开启（如通过-DF3D_PLUGIN_BUILD_ASSIMP=ON追加）。

使用 VCPKG 自动构建依赖

仓库提供了 vcpkg.json 清单文件，可以借助 VCPKG 自动编译依赖。基本用法是安装 VCPKG 后，配置时指定工具链文件：

cmake -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake /path/to/source

更简单的方式是直接使用vcpkg预设：

cmake --preset=vcpkg /path/to/source

需要说明的两点：

1. 清单文件目前只声明了 VTK（关闭默认特性、开启opengl与seacas特性）；Alembic、Assimp、OCCT、Draco、OpenUSD 等依赖以清单 feature 形式提供（alembic、assimp、occt、draco、usd），需要时在 vcpkg.json 中手动补充；
2. 除 vcpkg 基础预设外，仓库还提供了vcpkg_alembic、vcpkg_assimp、vcpkg_occt、vcpkg_draco、vcpkg_usd等组合预设（见 CMakePresets.json），它们通过继承vcpkg预设并同时设置VCPKG_MANIFEST_FEATURES与对应插件开关，例如：

cmake --preset=vcpkg_assimp /path/to/source

Python 绑定：构建与测试

环境准备

构建 Python 绑定只需系统中有pybind11；若还需运行测试，则额外需要pytest与numpy。这些依赖可用pip安装，官方建议（非强制）使用虚拟环境隔离：

python -m venv .venv source .venv/bin/activate pip install --group dev

注意：pip install --group需要 pip 25.1 或更高版本，可用python -m pip install --upgrade pip升级。

构建

开启 Python 绑定选项并配置（python/CMakeLists.txt 中会find_package(Python 3.10 ...)与find_package(pybind11 3.0.0 REQUIRED)）：

cmake -DF3D_BINDINGS_PYTHON=ON [...]

然后单独构建pyf3d目标：

cmake --build . --target pyf3d

测试

构建完成后，可通过 CTest 的标签机制只运行 Python 绑定测试：

ctest -L python

若需要生成类型存根（.pyi），配置时额外开启F3D_BINDINGS_PYTHON_GENERATE_STUBS，构建后会调用 generate_stubs.py 在构建目录生成 stubs（见 python/CMakeLists.txt）。

提示：构建测试需要 git LFS 数据。根 CMakeLists.txt 会检查testing/data/dragon.vtu是否为真实文件（LFS 拉取），若未执行git lfs pull且开启了BUILD_TESTING会直接中止配置。

安装：组件化安装

安装通过 CMake 完成：

cmake --install ${your_build_dir}

也可以按组件名单独安装：

cmake --install ${your_build_dir} --component ${component_name}

安装组件一览

组件化的安装逻辑在 library/CMakeLists.txt 中有完整体现：sdk组件安装头文件、f3dConfig.cmake与f3d.pc；plugin_sdk组件安装 f3dPlugin.cmake 等插件开发宏文件；dependencies组件通过 CMake 的RUNTIME_DEPENDENCY_SET收集并排除系统库路径（如system32、/usr/lib）。

安装完成后，下游项目即可通过find_package(f3d COMPONENTS library)或find_package(f3d COMPONENTS pluginsdk)引用 libf3d 或开发第三方插件，具体可参考 library-config.cmake 与 pluginsdk-config.cmake。

从配置到发布：构建要点小结

1. 先备依赖：至少准备 CMake、C++20 编译器与 VTK >= 9.4.0；按需安装上表中的可选依赖，并在 VTK 配置时开启对应模块（IOExodus、IOHDF、IONetCDF、IOPDAL、IOOpenVDB、RenderingRayTracing等）。
2. 配置：使用cmake --preset=dev（贡献开发）或cmake --preset=vcpkg（自动依赖），或用cmake -DF3D_*手动组合模块、插件与绑定选项。
3. 构建：cmake --build .，Python 绑定可用--target pyf3d单独构建。
4. 测试：ctest（可配合-R按名称、-L按标签筛选），详见 测试指南。
5. 安装：cmake --install，按需指定--component打包出应用、SDK、插件 SDK 或自包含运行时等不同形态的产物。

【免费下载链接】f3dFast and minimalist 3D viewer.项目地址: https://gitcode.com/GitHub_Trending/f3/f3d