📚 课程目录第3章动态链接库加载与版本管理

3. 动态链接库加载与版本管理：跨平台 dlopen/LoadLibrary、版本号解析与兼容性检查

在相机二次开发中，SDK 通常以动态链接库（Windows .dll、Linux .so、macOS .dylib）形式提供。运行时动态加载技术允许主程序在不重新编译的情况下适配不同版本或不同厂商的相机库，是实现插件化架构和兼容性适配的核心基础。本章将深入讲解跨平台动态库加载原理、版本号解析策略以及稳健的兼容性检查实现。

3.1 核心概念与原理

动态库加载方式主要分为两类：

隐式链接（静态导入）： 编译时由链接器处理，程序启动时由操作系统加载器自动加载。缺点是库不存在或版本不匹配时程序直接崩溃，缺乏灵活性。
显式链接（动态加载）： 程序运行时主动调用操作系统 API 加载库、解析符号，并处理加载失败的情况。这是相机适配中推荐的做法，能实现优雅降级和版本检测。

3.2 跨平台动态库加载 API 对比

功能	Windows (Win32)	Linux / macOS (POSIX)
加载库	`LoadLibrary` / `LoadLibraryEx`	`dlopen`
获取符号地址	`GetProcAddress`	`dlsym`
卸载库	`FreeLibrary`	`dlclose`
错误信息	`GetLastError`	`dlerror`
头文件	`<windows.h>`	`<dlfcn.h>`
链接选项	无需额外链接（隐式需要 .lib）	`-ldl`

最佳实践： macOS 虽然也使用 dlopen，但推荐使用 @rpath 或 @executable_path 来指定库搜索路径，避免使用全局路径导致冲突。此外，对于系统框架，可以使用 NSBundle 或 NSModule 实现更原生的加载方式。

3.3 版本号解析与兼容性策略

大多数相机 SDK 遵循语义化版本规范（Semantic Versioning）：主版本.次版本.修订版（例如 2.5.1）。兼容性检查逻辑如下：

主版本： 必须精确匹配。主版本不同代表 ABI 不兼容，链接会导致未定义行为。
次版本： 实际版本必须大于等于需求版本。次版本高代表功能超集，向后兼容。
修订版： 通常不影响兼容性判断，但可用于获取精确的构建信息。

// version_compat.h
#include <string>
#include <vector>
#include <sstream>

struct Version {
    int major = 0;
    int minor = 0;
    int patch = 0;

    static Version parse(const std::string& ver_str) {
        Version v;
        std::vector<int> parts;
        std::stringstream ss(ver_str);
        std::string item;
        while (std::getline(ss, item, '.')) {
            parts.push_back(std::stoi(item));
        }
        if (parts.size() > 0) v.major = parts[0];
        if (parts.size() > 1) v.minor = parts[1];
        if (parts.size() > 2) v.patch = parts[2];
        return v;
    }

    static bool isCompatible(const Version& required, const Version& actual) {
        if (actual.major != required.major) {
            return false; // ABI 不兼容
        }
        if (actual.minor < required.minor) {
            return false; // 功能缺失
        }
        return true;
    }
};

3.4 实现流程：跨平台动态加载器

以下代码展示了如何封装一个跨平台的动态库加载类，并集成版本检查和错误处理。

// library_loader.h
#pragma once
#include <memory>
#include <string>
#include <functional>

class DynamicLibrary {
public:
    virtual ~DynamicLibrary() = default;
    virtual bool load(const std::string& path) = 0;
    virtual void* getSymbol(const std::string& name) = 0;
    virtual std::string getLastError() = 0;
    virtual void unload() = 0;
};

std::unique_ptr<DynamicLibrary> createLibraryLoader();

// library_loader_win.cpp (Windows 实现)
#ifdef _WIN32
#include <windows.h>
class WinLibrary : public DynamicLibrary {
    HMODULE handle = nullptr;
    std::string last_error;
public:
    bool load(const std::string& path) override {
        handle = LoadLibraryA(path.c_str());
        if (!handle) {
            last_error = "LoadLibrary failed: " + std::to_string(GetLastError());
            return false;
        }
        return true;
    }
    void* getSymbol(const std::string& name) override {
        auto ptr = GetProcAddress(handle, name.c_str());
        if (!ptr) {
            last_error = "GetProcAddress failed: " + std::to_string(GetLastError());
        }
        return (void*)ptr;
    }
    std::string getLastError() override { return last_error; }
    void unload() override { if (handle) FreeLibrary(handle); handle = nullptr; }
};
#endif

// library_loader_posix.cpp (Linux/macOS 实现)
#ifdef __linux__ || __APPLE__
#include <dlfcn.h>
#include <cstring>
class PosixLibrary : public DynamicLibrary {
    void* handle = nullptr;
    std::string last_error;
public:
    bool load(const std::string& path) override {
        handle = dlopen(path.c_str(), RTLD_NOW | RTLD_LOCAL);
        if (!handle) {
            last_error = dlerror();
            return false;
        }
        return true;
    }
    void* getSymbol(const std::string& name) override {
        dlerror(); // 清除旧错误
        auto ptr = dlsym(handle, name.c_str());
        const char* err = dlerror();
        if (err) {
            last_error = err;
            return nullptr;
        }
        return ptr;
    }
    std::string getLastError() override { return last_error; }
    void unload() override { if (handle) dlclose(handle); handle = nullptr; }
};
#endif

3.5 调试与部署

常见错误排查：

ERROR_MOD_NOT_FOUND (Windows) / file not found (Linux)： 库路径错误或依赖的运行时库缺失。使用 dumpbin /dependents (Windows) 或 ldd (Linux) 检查依赖。
symbol lookup error： 导出的符号与头文件声明不一致，或者编译时使用的头文件与运行时库版本不匹配。
位宽冲突： 尝试在 64 位进程中加载 32 位库，反之亦然。

重要： 在生产环境中部署时，务必在安装包中包含正确的 Visual C++ Redistributable (Windows) 或指定 rpath (Linux/macOS)，确保动态库的依赖项能够被正确解析。对于相机 SDK，经常需要将相机厂商提供的 .dll / .so 放置在与主程序相同的目录下，或添加到系统路径中。

3.6 性能与稳定性优化

延迟加载（Lazy Loading）： 只在真正需要访问相机时才加载对应的动态库，减少程序启动时间。对于多相机系统，可以按需加载不同厂商的库。
缓存符号地址： 在加载完成后，立即查询并缓存所有需要用到的函数指针，避免在实时采集路径中频繁调用 dlsym / GetProcAddress。
线程安全： 动态库的加载和卸载通常不是线程安全的，建议在单线程初始化阶段完成所有加载操作，并使用互斥锁保护全局库列表。

3.7 流程全景图：运行时兼容性决策

下图总结了从加载动态库到完成兼容性检查的完整决策路径：