1.2 动态库加载
1.1 讲了插件要实现的接口,但插件通常编译成 DLL / Shared Object,Root::loadPlugin 拿到的是一个库文件名。OGRE 用 DynLib 这一层薄薄的封装把「在不同操作系统上打开一个动态库」收敛成三个宏加三个方法。这一节看 OgreDynLib 的真实实现:跨平台宏、按平台补后缀、load/unload/getSymbol。
本章与站内既有内容的分工
卷一 3.x 提到 DynLibManager 负责缓存与销毁 DynLib;这里剖析 DynLib 本身——OgreDynLib.h 的类契约与 OgreDynLib.cpp 的跨平台实现,是 1.3 写自定义插件骨架的前置。
DynLib:一个名字 + 一个句柄
头文件里的类很小,成员只有两个:名字 mName 和句柄 mInst。句柄类型也按平台定义:
// OgreMain/include/OgreDynLib.h:DynLib(v14.6.3 源码摘录,已删减)
#if OGRE_PLATFORM == OGRE_PLATFORM_WIN32 || OGRE_PLATFORM == OGRE_PLATFORM_WINRT
typedef struct HINSTANCE__* DYNLIB_HANDLE;
#else
typedef void* DYNLIB_HANDLE;
#endif
...
class _OgreExport DynLib : public DynLibAlloc
{
private:
String mName;
/// Gets the last loading error
String dynlibError(void);
public:
DynLib( const String& name );
~DynLib();
/** Load the library
*/
void load();
/** Unload the library
*/
void unload();
/// Get the name of the library
const String& getName(void) const { return mName; }
void* getSymbol( const String& strName ) const throw();
private:
/// Handle to the loaded library.
DYNLIB_HANDLE mInst;
};
Windows 上句柄是 HINSTANCE__*(LoadLibrary 返回的库句柄),POSIX 上是裸 void*(dlopen 的句柄)。类把平台差异藏起来,外部只看到 load/unload/getSymbol。
跨平台宏:三个宏收敛所有差异
OgreDynLib.cpp 开头用条件编译把四个平台家族的加载原语收敛成三个宏:
// OgreMain/src/OgreDynLib.cpp:DYNLIB 宏(v14.6.3 源码摘录,已删减)
#if OGRE_PLATFORM == OGRE_PLATFORM_WIN32
# define DYNLIB_LOAD( a ) dynLibLoad( a ) // we can not use LOAD_WITH_ALTERED_SEARCH_PATH with relative paths
# define DYNLIB_GETSYM( a, b ) GetProcAddress( a, b )
# define DYNLIB_UNLOAD( a ) !FreeLibrary( a )
#elif OGRE_PLATFORM == OGRE_PLATFORM_WINRT
# define DYNLIB_LOAD( a ) LoadPackagedLibrary( stringToWstring(a).c_str(), 0 )
# define DYNLIB_GETSYM( a, b ) GetProcAddress( a, b )
# define DYNLIB_UNLOAD( a ) !FreeLibrary( a )
#elif OGRE_PLATFORM == OGRE_PLATFORM_LINUX || OGRE_PLATFORM == OGRE_PLATFORM_ANDROID || OGRE_PLATFORM == OGRE_PLATFORM_EMSCRIPTEN
# define DYNLIB_LOAD( a ) dlopen( a, RTLD_LAZY | RTLD_GLOBAL)
# define DYNLIB_GETSYM( a, b ) dlsym( a, b )
# define DYNLIB_UNLOAD( a ) dlclose( a )
#elif OGRE_PLATFORM == OGRE_PLATFORM_APPLE || OGRE_PLATFORM == OGRE_PLATFORM_APPLE_IOS
# define DYNLIB_LOAD( a ) mac_loadDylib( a )
# define FRAMEWORK_LOAD( a ) mac_loadFramework( a )
# define DYNLIB_GETSYM( a, b ) dlsym( a, b )
# define DYNLIB_UNLOAD( a ) dlclose( a )
#endif
每个平台只改这三个宏,DynLib 的实现体就完全统一。注意 Linux 系 dlopen(a, RTLD_LAZY | RTLD_GLOBAL)——惰性解析符号、全局符号可见;Apple 系额外有 FRAMEWORK_LOAD(.framework 包)。
load():先补后缀,再加载
load() 的实现分两步:先把平台专属后缀补到文件名上,再调用 DYNLIB_LOAD:
// OgreMain/src/OgreDynLib.cpp:DynLib::load(v14.6.3 源码摘录,已删减)
void DynLib::load()
{
String name = mName;
#if OGRE_PLATFORM == OGRE_PLATFORM_EMSCRIPTEN
if (name.find(".js") == String::npos)
name += ".js";
#elif OGRE_PLATFORM == OGRE_PLATFORM_LINUX
// dlopen() does not add .so to the filename, like windows does for .dll
if (name.find(".so") == String::npos)
{
name += StringUtil::format(".so.%d.%d", OGRE_VERSION_MAJOR, OGRE_VERSION_MINOR);
}
#elif OGRE_PLATFORM == OGRE_PLATFORM_APPLE
// dlopen() does not add .dylib to the filename, like windows does for .dll
if(name.substr(name.find_last_of(".") + 1) != "dylib")
name += ".dylib";
#elif OGRE_PLATFORM == OGRE_PLATFORM_WIN32 || OGRE_PLATFORM == OGRE_PLATFORM_WINRT
// Although LoadLibraryEx will add .dll itself when you only specify the library name,
// if you include a relative path then it does not. So, add it to be sure.
if(name.substr(name.find_last_of(".") + 1) != "dll")
name += OGRE_BUILD_SUFFIX ".dll";
#endif
// Log library load
LogManager::getSingleton().logMessage("Loading library " + name);
mInst = (DYNLIB_HANDLE)DYNLIB_LOAD( name.c_str() );
#if OGRE_PLATFORM == OGRE_PLATFORM_APPLE
if(!mInst)
{
name = mName;
if(name.substr(name.find_last_of(".") + 1) != "framework")
name += ".framework";
// Try again as a framework
mInst = (DYNLIB_HANDLE)FRAMEWORK_LOAD( name );
}
#endif
if( !mInst )
OGRE_EXCEPT(
Exception::ERR_INTERNAL_ERROR,
"Could not load dynamic library " + mName +
". System Error: " + dynlibError(),
"DynLib::load" );
}
后缀决策表:
| 平台 | 补上的后缀 | 说明 |
|---|---|---|
| Emscripten | .js | WebAssembly 模块 |
| Linux/Android | .so.<MAJOR>.<MINOR> | dlopen 不会像 Windows 那样自动加后缀,还要带上版本号(14.6) |
| Apple | .dylib,失败再试 .framework | dlopen 不自动加后缀 |
| Windows | <OGRE_BUILD_SUFFIX>.dll | LoadLibraryEx 对相对路径不加 .dll |
规则统一是「先判断后缀是否已在,没有才补」。加载失败抛出 ERR_INTERNAL_ERROR 异常,消息里带上 dynlibError()(dlerror() / GetLastError() 的系统错误文本)。
unload 对称地调用 DYNLIB_UNLOAD,失败同样抛异常;getSymbol 用 DYNLIB_GETSYM(mInst, strName) 取符号地址,找不到返回 NULL:
// OgreMain/src/OgreDynLib.cpp:DynLib::unload / getSymbol(v14.6.3 教学示意,参照上游同名实现,已删减)
void DynLib::unload()
{
// Log library unload
LogManager::getSingleton().logMessage("Unloading library " + mName);
if( DYNLIB_UNLOAD( mInst ) )
{
OGRE_EXCEPT(...);
}
}
...
void* DynLib::getSymbol( const String& strName ) const throw()
{
return (void*)DYNLIB_GETSYM( mInst, strName.c_str() );
}
源码定位
OgreMain/include/OgreDynLib.h:DYNLIB_HANDLE(46-50)、DynLib类(59-102)、getName(83)、getSymbol(96)OgreMain/src/OgreDynLib.cpp:DYNLIB 宏(32-49)、DynLib::load(107-150)、DynLib::unload(153-167)、getSymbol(170-173)、dynlibError(175-227)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面用纯 C++ 复现后缀补全决策与加载/取符号/卸载的调用语义。它与 src/01-2-dynlib-loading.cpp 逐字节一致:
// file: src/01-2-dynlib-loading.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/01-2-dynlib-loading.cpp -o bin/01-2-dynlib-loading && ./bin/01-2-dynlib-loading
//
// 复现动态库加载的后缀补全与 load/unload/getSymbol 语义
// (对应 OgreMain/src/OgreDynLib.cpp 107-173 的 DynLib::load/unload/getSymbol,
// 32-49 的 DYNLIB 平台宏):
// 各平台先补后缀再加载:Emscripten .js / Linux .so.MAJ.MIN / Apple .dylib / Windows .dll;
// 已有后缀不补;加载失败抛异常;getSymbol 找不到返回空。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <cstdint>
#include <stdexcept>
#include <string>
namespace ogre_repro {
enum class Platform { Windows, Linux, Apple, Emscripten };
// 对应 OgreDynLib.cpp 107-129:按平台补全后缀,已有则不补
std::string addLibrarySuffix(const std::string& name, Platform plat, uint32_t major,
uint32_t minor) {
std::string out = name;
switch (plat) {
case Platform::Emscripten:
if (out.find(".js") == std::string::npos) out += ".js";
break;
case Platform::Linux:
if (out.find(".so") == std::string::npos) {
out += ".so." + std::to_string(major) + "." + std::to_string(minor);
}
break;
case Platform::Apple:
if (out.substr(out.find_last_of(".") + 1) != "dylib") out += ".dylib";
break;
case Platform::Windows:
if (out.substr(out.find_last_of(".") + 1) != "dll") out += ".dll";
break;
}
return out;
}
// 对应 OgreDynLib.h 59-:模拟动态库(记录调用,模拟失败)
class SimDynLib {
public:
explicit SimDynLib(std::string name) : mName(std::move(name)) {}
void load() {
if (mLoadFails) throw std::runtime_error("could not load: " + mName);
mLoaded = true;
mLoadCount++;
}
void unload() {
mLoaded = false;
mUnloadCount++;
}
// 对应 getSymbol:已知符号返回非空,未知返回空
void* getSymbol(const std::string& sym) const {
if (!mLoaded || sym != "dllStartPlugin") return nullptr;
return reinterpret_cast<void*>(1);
}
const std::string& getName() const { return mName; }
bool mLoaded = false;
int mLoadCount = 0;
int mUnloadCount = 0;
bool mLoadFails = false;
std::string mName;
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
// 后缀补全:Windows 补 .dll
CHECK_EQ(addLibrarySuffix("RenderSystem_GL", Platform::Windows, 14, 6),
"RenderSystem_GL.dll");
// 已有 .dll 不重复补
CHECK_EQ(addLibrarySuffix("Ogre.dll", Platform::Windows, 14, 6), "Ogre.dll");
// Linux 补 .so.14.6
CHECK_EQ(addLibrarySuffix("Plugin_Assimp", Platform::Linux, 14, 6),
"Plugin_Assimp.so.14.6");
// 已有 .so 不补
CHECK_EQ(addLibrarySuffix("Plugin.so", Platform::Linux, 14, 6), "Plugin.so");
// Apple 补 .dylib
CHECK_EQ(addLibrarySuffix("Sample", Platform::Apple, 14, 6), "Sample.dylib");
// 已有 .dylib 不补
CHECK_EQ(addLibrarySuffix("libOgre.dylib", Platform::Apple, 14, 6), "libOgre.dylib");
// Emscripten 补 .js
CHECK_EQ(addLibrarySuffix("Ogre", Platform::Emscripten, 14, 6), "Ogre.js");
// load/unload/getSymbol 语义
SimDynLib lib("Plugin_Assimp");
CHECK(!lib.mLoaded);
lib.load();
CHECK(lib.mLoaded);
CHECK_EQ(lib.mLoadCount, 1);
// 取到符号(模拟 dllStartPlugin)
CHECK(lib.getSymbol("dllStartPlugin") != nullptr);
// 未知符号返回空
CHECK(lib.getSymbol("nope") == nullptr);
lib.unload();
CHECK(!lib.mLoaded);
CHECK_EQ(lib.mUnloadCount, 1);
// 卸载后符号不可取
CHECK(lib.getSymbol("dllStartPlugin") == nullptr);
// 加载失败抛异常(对应 OGRE_EXCEPT)
SimDynLib bad("Missing.so");
bad.mLoadFails = true;
bool threw = false;
try {
bad.load();
} catch (const std::runtime_error&) {
threw = true;
}
CHECK(threw);
CHECK(!bad.mLoaded);
return lab::report("1.2 动态库加载");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 17/17 通过。
小结
DynLib用mName+mInst(DYNLIB_HANDLE)两个成员封装一个动态库。- 三个
DYNLIB_*宏把dlopen/LoadLibrary等平台原语收敛成统一接口。 load()先按平台补后缀(.js/.so.MAJ.MIN/.dylib/.dll)再加载,已有后缀不补。- 加载失败抛
ERR_INTERNAL_ERROR,消息带系统错误文本;getSymbol找不到返回NULL。 - Apple 系加载失败会回退尝试
.framework。
阅读导航:上一节:1.1 插件接口 · 下一节:1.3 自定义插件骨架 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。