《OGRE 3D 渲染引擎原理与架构》1.3 CMake 构建系统与版本宏

OGRE 用 CMake 构建,最低版本 3.13,project 声明版本 14.6.3 与代号 Tsathoggua。构建选项区分 WorkQueue 线程化、资源线程安全与资源管理器严格度。版本三元组在 CMake 与头文件里双向存在,靠宏压缩成 32 位整数互相衔接。lab 用 C++ 解析 project 行并断言版本字段。

1.3 CMake 构建系统与版本宏

OGRE 的构建系统只有一个入口:根目录 CMakeLists.txt。cmake_minimum_required(VERSION 3.13.0) 定了地基,紧接着用 project(OGRE VERSION 14.6.3) 声明工程名与版本。这一节的三个数字——工程名、版本、代号——是全书的锚点:

# CMakeLists.txt:v14.6.3 版本声明(源码摘录)
cmake_minimum_required(VERSION 3.13.0)
...
project(OGRE VERSION 14.6.3)
set(OGRE_VERSION_SUFFIX "")
set(OGRE_VERSION_NAME "Tsathoggua")
set(OGRE_SOVERSION ${OGRE_VERSION_MAJOR}.${OGRE_VERSION_MINOR})

project(OGRE VERSION 14.6.3) 会让 CMake 自动生成 OGRE_VERSION_MAJOR、OGRE_VERSION_MINOR、OGRE_VERSION_PATCH 三个变量,OGRE_SOVERSION 就基于它们拼出 14.6 作为动态库 soname。版本代号 Tsathoggua 是克苏鲁神话里的沉睡之神——OGRE 每个主版本都配一个这类代号。

版本宏:CMake 与头文件的双向衔接

上一节讲过 OgrePrerequisites.h 里的 OGRE_VERSION 宏把三元组压成 32 位整数。注意这里有个关键衔接:字符串版本的权威来源是 CMakeLists,整数版本的权威来源是头文件宏。两者必须一致,靠 OgreBuildSettings.h 在配置期生成时把 CMake 的版本号带入 C++ 侧。实际上 OGRE_VERSION_MAJOR/MINOR/PATCH 宏在编译期由 CMake 配置写入,OgrePrerequisites.h 再用它们计算 OGRE_VERSION。

为什么不用字符串比较版本?因为整数版本号可以进 #if 编译期判断:

// OgreMain/include/OgrePrerequisites.h:版本门槛(v14.6.3 源码摘录)
    #define OGRE_VERSION    ((OGRE_VERSION_MAJOR << 16) | (OGRE_VERSION_MINOR << 8) | OGRE_VERSION_PATCH)

    #define OGRE_MIN_VERSION(MAJOR, MINOR, PATCH) OGRE_VERSION >= ((MAJOR << 16) | (MINOR << 8) | PATCH)

#if OGRE_MIN_VERSION(14, 6, 0) 这类写法在源码里随处可见,用来给不同版本编译不同的代码路径。补丁版本占 8 位意味着单个数字上限 255,对一年几个补丁的节奏绰绰有余。

关键构建选项:线程模式与提供者

OGRE 的线程抽象可以接四套后端,这是 CMakeLists.txt 里 OGRE_CONFIG_THREAD_PROVIDER 选项的取值:

# CMakeLists.txt:线程相关选项(v14.6.3 源码摘录)
set_property(CACHE OGRE_RESOURCEMANAGER_STRICT PROPERTY STRINGS 0 1 2)
set_property(CACHE OGRE_CONFIG_THREADS PROPERTY STRINGS 0 1 2 3)
set_property(CACHE OGRE_CONFIG_THREAD_PROVIDER PROPERTY STRINGS boost poco tbb std)
  • OGRE_CONFIG_THREAD_PROVIDER:缓存菜单列出 boost、poco、tbb、std。固定版本的 ConfigureBuild 仅实现 boost、poco、std 三个分支,默认 std。
  • OGRE_CONFIG_THREADS:0 关闭线程化队列;1 支持后台准备和加载;2 只允许后台准备;默认 3 开启工作线程,资源操作由调用方遵守线程约束。1 和 2 已弃用。worker 数量由 Root 另外设置。
  • OGRE_RESOURCEMANAGER_STRICT:0~2,资源管理器严格模式强度。

这些选项最终通过 OgreBuildSettings.h(CMake 生成)进入 C++ 宏。理解「CMake 配置 → 生成头文件 → 源码宏」这条链路,是之后读 OgreResourceManager.h、OgreThreads.h 时判断「这个宏哪来的」的基础。

构建后的产物布局

一次典型的 cmake .. && make 会产出:

  • libOgreMain.so(或 .dll/.dylib)——核心库;
  • RenderSystem_Vulkan、RenderSystem_GL3Plus 等——每个后端一个动态库;
  • Plugin_OctreeSceneManager、Plugin_ParticleFX 等——每个插件一个动态库;
  • OgreMeshUpgrader、OgreXMLConverter 等——命令行工具。

动态库成百上千个的插件化加载方式,靠的是 OgreDynLib 在运行期 dlopen——这是第 3 章的主线。构建产物与运行期加载之间的桥梁,就是插件的 dllStartPlugin/dllStopPlugin 导出符号。

由构建选项确定可读的运行路径

CMake 配置经模板生成构建目录中的头文件,再进入预处理条件。阅读 ResourceBackgroundQueue 之前,先从该次构建的 OgreBuildSettings.h 查 OGRE_THREAD_SUPPORT。否则,源码中两个编译分支都像运行时选项。

对照模式 0 和 3 时观察任务是否在提交线程直接执行。两次构建使用同一场景和资产,分别保存生成头和任务线程日志。

源码定位

上游引用固定到 OGRE v14.6.3 源码 。

可运行产物:C++ 最小验证

下面复现 project(OGRE VERSION 14.6.3) 这行的解析,把工程名与三元组拆出来,并推导 OGRE_SOVERSION。它与 src/01-3-cmake-version-parse.cpp 逐字节一致:

// file: src/01-3-cmake-version-parse.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/01-3-cmake-version-parse.cpp -o bin/01-3-cmake-version-parse && ./bin/01-3-cmake-version-parse
//
// 复现 CMakeLists.txt 的版本声明解析:
//   project(OGRE VERSION 14.6.3)
//   set(OGRE_VERSION_NAME "Tsathoggua")
//   set(OGRE_SOVERSION ${OGRE_VERSION_MAJOR}.${OGRE_VERSION_MINOR})
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cstdio>
#include <string>

namespace ogre_repro {

struct Version {
  int major, minor, patch;
};

// 解析形如 "project(NAME VERSION M.m.p)" 的一行
bool parseProjectLine(const std::string& line, std::string& name, Version& v) {
  const std::string kw = "project(";
  if (line.compare(0, kw.size(), kw) != 0) return false;
  const std::string rest = line.substr(kw.size(), line.find(')') - kw.size());
  size_t verPos = rest.find("VERSION");
  if (verPos == std::string::npos) return false;
  name = rest.substr(0, verPos);
  while (!name.empty() && (name.back() == ' ' || name.back() == '\t'))
    name.pop_back();
  const std::string verStr = rest.substr(verPos + 7);
  return std::sscanf(verStr.c_str(), "%d.%d.%d", &v.major, &v.minor, &v.patch) == 3;
}

std::string soversion(const Version& v) {
  return std::to_string(v.major) + "." + std::to_string(v.minor);
}

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  Version v;
  std::string name;
  const std::string line = "project(OGRE VERSION 14.6.3)";
  CHECK(parseProjectLine(line, name, v));
  CHECK_EQ(name, "OGRE");
  CHECK_EQ(v.major, 14);
  CHECK_EQ(v.minor, 6);
  CHECK_EQ(v.patch, 3);
  CHECK_EQ(soversion(v), "14.6");

  CHECK(!parseProjectLine("set(OGRE_VERSION_NAME \"Tsathoggua\")", name, v));

  std::printf("project: %s VERSION %d.%d.%d  SOVERSION %s\n", name.c_str(),
              v.major, v.minor, v.patch, soversion(v).c_str());
  return lab::report("01-3 构建系统:CMake 版本声明");
}

本机实测(Apple clang 16,clang++ -std=c++20):编译通过,断言 7/7 通过。

小结

  • OGRE 用 CMake 构建,project(OGRE VERSION 14.6.3) 是版本字符串的权威来源。
  • 版本号在 CMake 与头文件里双向存在,头文件用 32 位宏压缩做编译期判断。
  • 默认 provider 为 std。资源线程安全和 WorkQueue 是否线程化由模式值控制。
  • 构建产物是「核心库 + 每后端一个动态库 + 每插件一个动态库」的模块化布局。

阅读导航:上一节:1.2 v14.6.3 源码目录地图 · 下一节:2.1 Root 单例与构造顺序 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图