678 lines
20 KiB
Markdown
678 lines
20 KiB
Markdown
# C API 设计规范总纲
|
||
|
||
> **必读**：本文件定义了所有 Olive/Oak 动态库的 C API 设计约定。`01-` 到 `07-` 各模块的 API 均遵循此规范。
|
||
|
||
---
|
||
|
||
## 1. 设计原则
|
||
|
||
### 1.1 不透明指针（Opaque Pointer）
|
||
|
||
所有 C++ 对象在 C 接口中均隐藏实现，仅暴露为 `struct` 的前向声明：
|
||
|
||
```c
|
||
// 公共头文件（.h）中
|
||
typedef struct OliveNodeGraph OliveNodeGraph; // 只有声明，无定义
|
||
|
||
// 实现文件（.cpp）中
|
||
struct OliveNodeGraph {
|
||
olive::NodeGraph* impl; // 实际的 C++ 对象
|
||
};
|
||
```
|
||
|
||
外部代码只能操作指针，无法解引用或 sizeof。
|
||
|
||
### 1.2 纯 C 接口
|
||
|
||
- 函数名使用 `snake_case`，前缀为 `olive_<module>_`。
|
||
- 参数和返回值仅使用 C 基础类型、结构体、不透明指针。
|
||
- 禁止使用 C++ 特性：类、引用、重载、模板、异常、`std::string`、`QString`。
|
||
- 字符串使用 `const char*`（UTF-8 编码）。
|
||
- 布尔值使用 `int`（0 = false，非 0 = true）。
|
||
|
||
### 1.3 动态库自身可以用 C++
|
||
|
||
动态库的实现文件（`.cpp`）内部可以继续使用：
|
||
- Qt（`QObject`, `QString`, `QList`, 信号槽等）
|
||
- C++ STL
|
||
- 虚函数、模板、Lambda
|
||
- 异常（但不得穿透 C 接口边界）
|
||
|
||
C 接口层只是薄薄的封装胶合层。
|
||
|
||
---
|
||
|
||
## 2. 命名规范
|
||
|
||
| 元素 | 规范 | 示例 |
|
||
|---|---|---|
|
||
| 类型名 | `Olive` + `PascalCase` | `OliveNodeGraph`, `OliveFrame` |
|
||
| 函数名 | `olive_<module>_<snake_case>` | `olive_node_graph_create`, `olive_codec_decoder_open` |
|
||
| 枚举名 | `Olive<Module><PascalCase>` | `OliveCodecResultOk`, `OliveRenderModeOffline` |
|
||
| 常量宏 | `OLIVE_<MODULE>_UPPER_SNAKE` | `OLIVE_NODE_OK`, `OLIVE_CODEC_ERROR_NOT_FOUND` |
|
||
| 版本宏 | `OLIVE_<MODULE>_API_VERSION` | `OLIVE_NODE_API_VERSION 1` |
|
||
|
||
---
|
||
|
||
## 3. 内存管理约定
|
||
|
||
### 3.1 谁创建，谁释放
|
||
|
||
- **库创建的对象**，必须由库的对应 `destroy`/`free` 函数释放。
|
||
- **主进程分配并传入的缓冲区**（如 `char*` 参数），由主进程管理，库内部只读或复制。
|
||
- **库返回的字符串/缓冲区**，必须使用库提供的 `free` 函数释放，不能用 C 标准 `free()`（因为库的堆和主进程的堆可能是分离的，尤其是在 Windows 上）。
|
||
|
||
```c
|
||
// 正确：库分配，库释放
|
||
char* xml = olive_node_graph_save_xml(graph, &len);
|
||
// ... 使用 xml ...
|
||
olive_core_free(xml); // 使用库提供的释放函数
|
||
|
||
// 错误：
|
||
free(xml); // 危险！堆可能不一致
|
||
```
|
||
|
||
### 3.2 通用释放函数
|
||
|
||
每个模块提供一个通用释放函数：
|
||
|
||
```c
|
||
void olive_core_free(void* ptr); // 释放字符串/二进制缓冲区
|
||
void olive_core_mem_free(void* ptr, size_t size); // 带大小的释放（用于安全擦除）
|
||
```
|
||
|
||
### 3.3 对象生命周期模式
|
||
|
||
```c
|
||
// 模式 A：Create/Destroy（堆分配）
|
||
OliveNodeGraph* olive_node_graph_create(void);
|
||
void olive_node_graph_destroy(OliveNodeGraph* obj);
|
||
|
||
// 模式 B：Init/Cleanup（栈分配或外部缓冲区）
|
||
int olive_frame_init(OliveFrame* frame, int w, int h, OlivePixelFormat fmt);
|
||
void olive_frame_cleanup(OliveFrame* frame);
|
||
|
||
// 模式 C：Ref/Unref（引用计数）
|
||
void olive_frame_ref(OliveFrame* frame);
|
||
void olive_frame_unref(OliveFrame* frame);
|
||
```
|
||
|
||
优先使用 **模式 A（Create/Destroy）**，因为不透明指针天然适合堆分配。
|
||
|
||
---
|
||
|
||
## 4. 错误处理
|
||
|
||
### 4.1 返回码约定
|
||
|
||
所有可能失败的函数返回 `int`：
|
||
|
||
```c
|
||
#define OLIVE_OK 0 // 成功
|
||
#define OLIVE_ERROR_GENERIC -1 // 通用错误
|
||
#define OLIVE_ERROR_INVALID -2 // 无效参数
|
||
#define OLIVE_ERROR_NOMEM -3 // 内存不足
|
||
#define OLIVE_ERROR_NOT_FOUND -4 // 找不到对象/文件
|
||
#define OLIVE_ERROR_IO -5 // IO 错误
|
||
#define OLIVE_ERROR_CANCELLED -6 // 操作被取消
|
||
#define OLIVE_ERROR_UNSUPPORTED -7 // 不支持的操作
|
||
```
|
||
|
||
### 4.2 详细错误信息
|
||
|
||
提供线程局部的错误信息获取函数：
|
||
|
||
```c
|
||
int olive_core_last_error_code(void);
|
||
const char* olive_core_last_error_string(void); // 线程安全，返回静态缓冲区或 TLS
|
||
```
|
||
|
||
实现方式：
|
||
|
||
```cpp
|
||
// .cpp 中
|
||
thread_local int g_last_error_code = OLIVE_OK;
|
||
thread_local char g_last_error_string[1024];
|
||
|
||
static void SetError(int code, const char* fmt, ...) {
|
||
g_last_error_code = code;
|
||
va_list args;
|
||
va_start(args, fmt);
|
||
vsnprintf(g_last_error_string, sizeof(g_last_error_string), fmt, args);
|
||
va_end(args);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 字符串处理
|
||
|
||
### 5.1 输入字符串
|
||
|
||
- 所有 `const char*` 参数均视为 **UTF-8 编码**。
|
||
- 库内部在边界处转换为 `QString`：
|
||
|
||
```cpp
|
||
// 封装层内部
|
||
QString qstr = QString::fromUtf8(cstr);
|
||
```
|
||
|
||
### 5.2 输出字符串
|
||
|
||
- 返回 `char*` 的函数，使用 `olive_core_free()` 释放。
|
||
- 如果只需读取而不持有，提供 `const char*` 返回版本：
|
||
|
||
```c
|
||
const char* olive_node_get_type_name(OliveNode* node); // 生命周期与 node 绑定
|
||
char* olive_node_graph_save_xml(OliveNodeGraph* graph, size_t* out_len); // 需释放
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 显式加载器（ModuleLoader）
|
||
|
||
### 6.1 设计目标
|
||
|
||
主进程通过一个统一的 `ModuleLoader` 类显式加载所有动态库，将 `dlopen`/`dlsym` 的细节隐藏。
|
||
|
||
### 6.2 C++ 封装类
|
||
|
||
```cpp
|
||
// app/moduleloader.h
|
||
#pragma once
|
||
|
||
#include <QString>
|
||
#include <QHash>
|
||
#include <functional>
|
||
|
||
namespace olive {
|
||
|
||
class ModuleLoader {
|
||
public:
|
||
ModuleLoader();
|
||
~ModuleLoader();
|
||
|
||
// 加载指定路径的动态库
|
||
bool Load(const QString& module_name, const QString& library_path);
|
||
|
||
// 卸载
|
||
void Unload(const QString& module_name);
|
||
|
||
// 获取函数指针（模板封装，内部调用 dlsym）
|
||
template<typename FuncPtr>
|
||
FuncPtr GetFunction(const QString& module_name, const char* func_name) {
|
||
return reinterpret_cast<FuncPtr>(GetFunctionRaw(module_name, func_name));
|
||
}
|
||
|
||
// 检查是否已加载
|
||
bool IsLoaded(const QString& module_name) const;
|
||
|
||
// 获取加载错误信息
|
||
QString LastError() const;
|
||
|
||
private:
|
||
void* GetFunctionRaw(const QString& module_name, const char* func_name);
|
||
|
||
struct ModuleHandle {
|
||
void* handle; // dlopen handle
|
||
QString path;
|
||
};
|
||
QHash<QString, ModuleHandle> modules_;
|
||
QString last_error_;
|
||
};
|
||
|
||
// 便捷宏：从指定模块获取函数并调用
|
||
#define OLIVE_LOAD_FUNC(loader, module, name, type) \
|
||
auto name = (loader).GetFunction<type>(module, #name); \
|
||
if (!name) { qFatal("Failed to load function: " #name " from module: " #module); }
|
||
|
||
} // namespace olive
|
||
```
|
||
|
||
### 6.3 实现（POSIX）
|
||
|
||
```cpp
|
||
// app/moduleloader.cpp
|
||
#include "moduleloader.h"
|
||
#include <dlfcn.h>
|
||
#include <QDebug>
|
||
|
||
namespace olive {
|
||
|
||
bool ModuleLoader::Load(const QString& module_name, const QString& library_path) {
|
||
if (modules_.contains(module_name)) return true;
|
||
|
||
void* handle = dlopen(library_path.toUtf8().constData(), RTLD_NOW | RTLD_LOCAL);
|
||
if (!handle) {
|
||
last_error_ = QString::fromUtf8(dlerror());
|
||
qWarning() << "Failed to load" << library_path << ":" << last_error_;
|
||
return false;
|
||
}
|
||
|
||
modules_.insert(module_name, {handle, library_path});
|
||
qInfo() << "Loaded module:" << module_name << "from" << library_path;
|
||
return true;
|
||
}
|
||
|
||
void ModuleLoader::Unload(const QString& module_name) {
|
||
auto it = modules_.find(module_name);
|
||
if (it != modules_.end()) {
|
||
dlclose(it->handle);
|
||
modules_.erase(it);
|
||
}
|
||
}
|
||
|
||
void* ModuleLoader::GetFunctionRaw(const QString& module_name, const char* func_name) {
|
||
auto it = modules_.find(module_name);
|
||
if (it == modules_.end()) return nullptr;
|
||
dlerror(); // 清除之前的错误
|
||
void* func = dlsym(it->handle, func_name);
|
||
return func;
|
||
}
|
||
|
||
} // namespace olive
|
||
```
|
||
|
||
### 6.4 实现（Windows）
|
||
|
||
```cpp
|
||
#include <windows.h>
|
||
|
||
bool ModuleLoader::Load(const QString& module_name, const QString& library_path) {
|
||
HMODULE handle = LoadLibraryW(library_path.toStdWString().c_str());
|
||
if (!handle) {
|
||
last_error_ = QString::number(GetLastError());
|
||
return false;
|
||
}
|
||
modules_.insert(module_name, {handle, library_path});
|
||
return true;
|
||
}
|
||
|
||
void* ModuleLoader::GetFunctionRaw(const QString& module_name, const char* func_name) {
|
||
auto it = modules_.find(module_name);
|
||
if (it == modules_.end()) return nullptr;
|
||
return GetProcAddress(static_cast<HMODULE>(it->handle), func_name);
|
||
}
|
||
```
|
||
|
||
### 6.5 使用示例
|
||
|
||
```cpp
|
||
// core.cpp 中初始化
|
||
module_loader_ = new ModuleLoader();
|
||
module_loader_->Load("core", FindLibraryPath("libolivecore.so"));
|
||
module_loader_->Load("codec", FindLibraryPath("libolivecodec.so"));
|
||
module_loader_->Load("node", FindLibraryPath("libolivenode.so"));
|
||
|
||
// 获取函数
|
||
OLIVE_LOAD_FUNC(*module_loader_, "core", olive_rational_make, OliveRational(*)(int64_t, int64_t));
|
||
|
||
OliveRational r = olive_rational_make(1001, 30000);
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 类型映射表
|
||
|
||
| C++ 类型（内部） | C 接口类型（公共） | 说明 |
|
||
|---|---|---|
|
||
| `olive::Rational` | `OliveRational` | `struct { int64_t num, den; }` |
|
||
| `olive::Color` | `OliveColor` | `struct { double r, g, b, a; }` |
|
||
| `olive::TimeRange` | `OliveTimeRange*` | 不透明指针 |
|
||
| `olive::Frame` | `OliveFrame*` | 不透明指针 |
|
||
| `olive::SampleBuffer` | `OliveSampleBuffer*` | 不透明指针 |
|
||
| `olive::PixelFormat` | `OlivePixelFormat` | `enum` |
|
||
| `olive::VideoParams` | `OliveVideoParams` | 公开结构体（POD） |
|
||
| `olive::AudioParams` | `OliveAudioParams` | 公开结构体（POD） |
|
||
| `olive::Node*` | `OliveNode*` | 不透明指针 |
|
||
| `olive::NodeGraph*` | `OliveNodeGraph*` | 不透明指针 |
|
||
| `olive::RenderTicketPtr` | `OliveRenderTicket*` | 不透明指针（引用计数内部管理） |
|
||
| `QString` | `const char*` | UTF-8 编码 |
|
||
| `QSize` | `struct { int width; int height; }` | `OliveSize` |
|
||
| `QMatrix4x4` | `float[16]` | 列优先 |
|
||
|
||
### 7.1 POD 结构体定义示例
|
||
|
||
```c
|
||
// olivecore_api.h
|
||
|
||
typedef struct {
|
||
int64_t num;
|
||
int64_t den;
|
||
} OliveRational;
|
||
|
||
typedef struct {
|
||
double r;
|
||
double g;
|
||
double b;
|
||
double a;
|
||
} OliveColor;
|
||
|
||
typedef struct {
|
||
int width;
|
||
int height;
|
||
int depth;
|
||
int channel_count;
|
||
OlivePixelFormat format;
|
||
double pixel_aspect_num;
|
||
double pixel_aspect_den;
|
||
} OliveVideoParams;
|
||
|
||
typedef struct {
|
||
int sample_rate;
|
||
int64_t channel_layout; // FFmpeg AV_CH_LAYOUT_* 值
|
||
OliveSampleFormat format;
|
||
} OliveAudioParams;
|
||
|
||
typedef struct {
|
||
int width;
|
||
int height;
|
||
} OliveSize;
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 线程安全
|
||
|
||
### 8.1 API 层面
|
||
|
||
- **默认不保证线程安全**。除非文档明确标注 `thread-safe`，否则每个 `OliveXxx*` 对象只能在创建它的线程中使用。
|
||
- 这是刻意的设计：由于渲染进程是"用完即弃"的，不存在多线程共享渲染状态的问题。
|
||
|
||
### 8.2 主进程中的线程使用
|
||
|
||
- `ModuleLoader` 本身是线程安全的（只读查找，加载/卸载在初始化/退出时串行执行）。
|
||
- UI 对象在主线程操作。
|
||
- IO/解码可以在工作线程中通过 C API 操作独立的 `OliveDecoder*` 实例。
|
||
|
||
---
|
||
|
||
## 9. 版本与 ABI 兼容性
|
||
|
||
### 9.1 API 版本号
|
||
|
||
每个模块的 C API 有一个主版本号：
|
||
|
||
```c
|
||
#define OLIVE_NODE_API_VERSION 1
|
||
|
||
int olive_node_api_version(void); // 返回 OLIVE_NODE_API_VERSION
|
||
```
|
||
|
||
### 9.2 加载时版本检查
|
||
|
||
```cpp
|
||
bool LoadNodeModule(ModuleLoader* loader, const QString& path) {
|
||
if (!loader->Load("node", path)) return false;
|
||
auto version_fn = loader->GetFunction<int(*)()>("node", "olive_node_api_version");
|
||
if (!version_fn || version_fn() != EXPECTED_NODE_API_VERSION) {
|
||
qFatal("Incompatible libolivenode.so version");
|
||
return false;
|
||
}
|
||
return true;
|
||
}
|
||
```
|
||
|
||
### 9.3 ABI 兼容性规则
|
||
|
||
- **允许**：新增函数、新增枚举值（在末尾）、新增结构体字段（在末尾，且文档标注"v2 起可用"）。
|
||
- **不允许**：删除函数、修改函数签名、修改已有字段含义、改变枚举值顺序。
|
||
- **结构体扩展**：POD 结构体新增字段时，提供初始化宏确保旧代码不会未初始化新字段：
|
||
|
||
```c
|
||
#define OLIVE_VIDEO_PARAMS_DEFAULT { \
|
||
.width = 1920, .height = 1080, .depth = 1, \
|
||
.channel_count = 4, .format = OLIVE_PIXEL_FMT_RGBA32F, \
|
||
.pixel_aspect_num = 1.0, .pixel_aspect_den = 1.0 \
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 头文件组织
|
||
|
||
### 10.1 目录结构
|
||
|
||
```
|
||
c_api/
|
||
├── include/
|
||
│ ├── olive/ # 公共 C API 头文件（安装时发布）
|
||
│ │ ├── core_api.h
|
||
│ │ ├── codec_api.h
|
||
│ │ ├── node_api.h
|
||
│ │ ├── render_api.h
|
||
│ │ ├── audio_api.h
|
||
│ │ ├── plugin_api.h
|
||
│ │ ├── ui_api.h
|
||
│ │ └── olive_api.h # 总入口，包含所有模块
|
||
│ └── olivecpp/ # 主进程内部使用的 C++ 辅助封装
|
||
│ ├── module_loader.h
|
||
│ ├── core_wrapper.h // RAII 包装类
|
||
│ ├── node_wrapper.h
|
||
│ └── ...
|
||
└── src/
|
||
├── core_api.cpp // 对应各模块的 C 封装实现
|
||
├── codec_api.cpp
|
||
├── node_api.cpp
|
||
├── render_api.cpp
|
||
├── audio_api.cpp
|
||
├── plugin_api.cpp
|
||
└── ui_api.cpp
|
||
```
|
||
|
||
### 10.2 C API 头文件示例
|
||
|
||
```c
|
||
// c_api/include/olive/node_api.h
|
||
#ifndef OLIVE_NODE_API_H
|
||
#define OLIVE_NODE_API_H
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
#include "core_api.h"
|
||
|
||
#define OLIVE_NODE_API_VERSION 1
|
||
|
||
/* ========== 类型前向声明 ========== */
|
||
typedef struct OliveNodeGraph OliveNodeGraph;
|
||
typedef struct OliveNode OliveNode;
|
||
typedef struct OliveParam OliveParam;
|
||
|
||
/* ========== 函数导出宏 ========== */
|
||
#ifdef OLIVE_BUILDING_NODE
|
||
# define OLIVE_NODE_API __attribute__((visibility("default")))
|
||
#else
|
||
# define OLIVE_NODE_API
|
||
#endif
|
||
|
||
/* ========== API 版本 ========== */
|
||
OLIVE_NODE_API int olive_node_api_version(void);
|
||
|
||
/* ========== NodeGraph ========== */
|
||
OLIVE_NODE_API OliveNodeGraph* olive_node_graph_create(void);
|
||
OLIVE_NODE_API void olive_node_graph_destroy(OliveNodeGraph* g);
|
||
|
||
OLIVE_NODE_API int olive_node_graph_load_xml(OliveNodeGraph* g,
|
||
const char* xml_data,
|
||
size_t xml_len);
|
||
OLIVE_NODE_API char* olive_node_graph_save_xml(OliveNodeGraph* g,
|
||
size_t* out_len);
|
||
|
||
OLIVE_NODE_API OliveNode* olive_node_graph_find_node(OliveNodeGraph* g,
|
||
const char* node_id);
|
||
OLIVE_NODE_API int olive_node_graph_add_node(OliveNodeGraph* g,
|
||
const char* node_type,
|
||
const char* node_id);
|
||
|
||
/* ========== Node ========== */
|
||
OLIVE_NODE_API const char* olive_node_get_id(OliveNode* node);
|
||
OLIVE_NODE_API const char* olive_node_get_type_name(OliveNode* node);
|
||
|
||
OLIVE_NODE_API int olive_node_connect(OliveNode* from_node,
|
||
int from_output_index,
|
||
OliveNode* to_node,
|
||
int to_input_index);
|
||
|
||
/* ========== Param ========== */
|
||
OLIVE_NODE_API int olive_node_set_param_int(OliveNode* node,
|
||
const char* param_name,
|
||
int64_t value);
|
||
OLIVE_NODE_API int olive_node_set_param_double(OliveNode* node,
|
||
const char* param_name,
|
||
double value);
|
||
OLIVE_NODE_API int olive_node_set_param_rational(OliveNode* node,
|
||
const char* param_name,
|
||
OliveRational value);
|
||
OLIVE_NODE_API int olive_node_set_param_string(OliveNode* node,
|
||
const char* param_name,
|
||
const char* value);
|
||
|
||
/* ========== Project ========== */
|
||
OLIVE_NODE_API OliveNodeGraph* olive_project_create(const char* name);
|
||
OLIVE_NODE_API int olive_project_load_file(OliveNodeGraph* project,
|
||
const char* filename);
|
||
OLIVE_NODE_API int olive_project_save_file(OliveNodeGraph* project,
|
||
const char* filename);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif // OLIVE_NODE_API_H
|
||
```
|
||
|
||
---
|
||
|
||
## 11. CMake 中的 C API 编译
|
||
|
||
### 11.1 为模块添加 C API 目标
|
||
|
||
```cmake
|
||
# app/node/CMakeLists.txt
|
||
|
||
# 原有 C++ 源码（内部实现，不暴露头文件）
|
||
set(NODE_INTERNAL_SOURCES
|
||
node.cpp node.h
|
||
traverser.cpp traverser.h
|
||
project/project.cpp project/project.h
|
||
# ... 其他内部文件
|
||
)
|
||
|
||
# C API 封装层源码
|
||
set(NODE_API_SOURCES
|
||
${CMAKE_SOURCE_DIR}/c_api/src/node_api.cpp
|
||
)
|
||
|
||
# 模块对外头文件（安装时发布）
|
||
set(NODE_API_HEADERS
|
||
${CMAKE_SOURCE_DIR}/c_api/include/olive/node_api.h
|
||
)
|
||
|
||
# 创建动态库
|
||
add_library(olivenode SHARED
|
||
${NODE_INTERNAL_SOURCES}
|
||
${NODE_API_SOURCES}
|
||
)
|
||
|
||
target_compile_definitions(olivenode PRIVATE OLIVE_BUILDING_NODE)
|
||
target_include_directories(olivenode
|
||
PRIVATE
|
||
${CMAKE_SOURCE_DIR}/app
|
||
${CMAKE_SOURCE_DIR}/c_api/include
|
||
PUBLIC
|
||
$<INSTALL_INTERFACE:include>
|
||
)
|
||
|
||
target_link_libraries(olivenode
|
||
PRIVATE
|
||
olivecore
|
||
olivecodec
|
||
Qt${QT_VERSION_MAJOR}::Core
|
||
)
|
||
|
||
# 设置符号可见性：默认隐藏，只有标记 OLIVE_NODE_API 的才导出
|
||
set_target_properties(olivenode PROPERTIES
|
||
CXX_VISIBILITY_PRESET hidden
|
||
VISIBILITY_INLINES_HIDDEN YES
|
||
)
|
||
|
||
# 安装 C API 头文件
|
||
install(FILES ${NODE_API_HEADERS} DESTINATION include/olive)
|
||
install(TARGETS olivenode DESTINATION lib)
|
||
```
|
||
|
||
### 11.2 主可执行文件不链接业务库
|
||
|
||
```cmake
|
||
# app/CMakeLists.txt（改造后）
|
||
|
||
add_executable(olive-editor
|
||
main.cpp
|
||
core.cpp
|
||
core.h
|
||
${CMAKE_SOURCE_DIR}/c_api/src/module_loader.cpp # 显式加载器实现
|
||
)
|
||
|
||
# 主程序只链接 Qt 和系统库，不链接 olivecore/olivecodec 等业务库！
|
||
target_link_libraries(olive-editor PRIVATE
|
||
Qt${QT_VERSION_MAJOR}::Core
|
||
Qt${QT_VERSION_MAJOR}::Gui
|
||
Qt${QT_VERSION_MAJOR}::Widgets
|
||
# ... 其他 UI 依赖
|
||
)
|
||
|
||
target_include_directories(olive-editor PRIVATE
|
||
${CMAKE_SOURCE_DIR}/c_api/include
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 测试策略
|
||
|
||
### 12.1 C API 单元测试
|
||
|
||
为每个 C API 函数编写独立测试：
|
||
|
||
```cpp
|
||
// tests/c_api/test_node_api.cpp
|
||
#include <gtest/gtest.h>
|
||
#include "olive/node_api.h"
|
||
|
||
TEST(NodeAPITest, CreateDestroy) {
|
||
OliveNodeGraph* g = olive_node_graph_create();
|
||
ASSERT_NE(g, nullptr);
|
||
olive_node_graph_destroy(g);
|
||
}
|
||
|
||
TEST(NodeAPITest, AddNodeAndParam) {
|
||
OliveNodeGraph* g = olive_node_graph_create();
|
||
ASSERT_EQ(OLIVE_OK, olive_node_graph_add_node(g, "Transform", "T1"));
|
||
OliveNode* n = olive_node_graph_find_node(g, "T1");
|
||
ASSERT_NE(n, nullptr);
|
||
ASSERT_EQ(OLIVE_OK, olive_node_set_param_double(n, "position_x", 100.0));
|
||
olive_node_graph_destroy(g);
|
||
}
|
||
```
|
||
|
||
### 12.2 ABI 稳定性测试
|
||
|
||
在 CI 中：
|
||
1. 编译当前版本的动态库。
|
||
2. 用上一个发布版本的测试可执行文件加载当前动态库运行。
|
||
3. 验证所有测试通过（确保未破坏 ABI）。
|
||
|
||
---
|
||
|
||
## 13. 常见陷阱
|
||
|
||
| 陷阱 | 说明 | 对策 |
|
||
|---|---|---|
|
||
| **异常穿透 C 边界** | C++ 异常抛出到 C 调用方是 UB。 | 所有 C API 函数用 `try/catch(...)` 包裹，捕获所有异常并转换为错误码。 |
|
||
| **RTTI 跨边界** | `dynamic_cast` 在不同动态库间可能失败。 | C 接口不使用 RTTI，内部若必须 `dynamic_cast`，确保类型定义在同一个库内。 |
|
||
| **Qt 元对象跨库** | `qobject_cast` 依赖 moc 生成的静态元对象数据，跨库时可能失效。 | 不在 C API 中暴露 Qt 对象，所有 Qt 对象封装在库内部。 |
|
||
| **全局静态变量** | 多个动态库各有一份全局静态变量。 | 避免在 C API 头文件中定义全局静态变量，使用函数内 static + 首次调用初始化。 |
|
||
| **堆不一致（Windows）** | A 库 `malloc`，B 库 `free` 导致崩溃。 | 严格遵循"谁分配谁释放"，使用库提供的 `olive_core_free()`。 |
|