Files
oak-editor/docs/zh/plans/riir/M1-oakcommon.md
T
Mike-Solar 9b25772267 docs: module-split execution manuals for RIIR stage 1 (plans/riir/)
13 files: 00 overview, 01 two-layer adapter spec (init/free/func +
opaque handles + same-name adapter classes, frozen naming/ownership/
error/event rules), 02 dependency matrix + split order M1-M9 (from a
490-file include scan), 03 Google Test spec (per-C-API coverage,
roundtrip tests, leak counters), M1-M9 per-module manuals with frozen
C APIs (common/undo/node/timeline/codec/audio/render/task/plugin) and
the facade assembly-layer verdict.
2026-07-27 00:06:33 +08:00

4.5 KiB
Raw Blame History

M1 · oakcommon 拆分手册

内容:engine/common/(41 文件通用工具集)+ engine/config/。 依赖:oakcore(2)。被依赖:几乎全员(node 31、render 24、 codec 12、plugin 6、audio 5、task 4、timeline 4、undo 2)。 拆分顺序第 1 位(叶子)。

1. 目标形态

oakcommon/
  include/oakcommon/   # 公共头(C ABI + 允许直引的纯头工具)
  src/                 # 现有 .cpp 原样迁入
  tests/               # oakcommon_gtest
  • 纯头工具(lerp.h、define.h、decibel.h、tohex.h、digit.h、 memorypool.h、threadsafemap.h、range.h 等无 .cpp 的):作为 oakcommon 公共头直接提供给其他模块 include——拆分阶段允许 (不产生链接依赖)。RIIR 阶段这些会改写成各语言自有实现。
  • config/config.h:单头配置存取,被全模块引用(10+)。 它是 Qt 依赖(QSettings 包装),按 §2 冻结 C ABI。

2. 冻结 C API(有 .cpp 实现的函数族)

命名前缀 oakcommon_。以下按头分组(签名机械规则见 01 §3, 此处冻结函数清单与特殊约定):

2.1 oakcommon/config.h(对应 config/config.h)

void oakcommon_config_set(const char *group, const char *key,
                          const char *value_utf8);
int  oakcommon_config_get(const char *group, const char *key,
                          char *buf, int buf_size);          /* 两段式 */
int  oakcommon_config_get_int(const char *group, const char *key,
                              int fallback);
double oakcommon_config_get_double(const char *group, const char *key,
                                   double fallback);
void oakcommon_config_set_int(const char *group, const char *key, int v);

2.2 oakcommon/xml.h(对应 common/xmlutils.h,8 次被引)

/* XMLAttributeLoop/xml_read_next_start_element 的 C 化:
 * 以迭代器句柄包装 QXmlStreamReader */
typedef struct OakCommonXmlReader OakCommonXmlReader;
OakCommonXmlReader *oakcommon_xml_reader_init(const char *utf8, int len);
void oakcommon_xml_reader_free(OakCommonXmlReader *r);
int  oakcommon_xml_read_next_start_element(OakCommonXmlReader *r);
int  oakcommon_xml_reader_name(OakCommonXmlReader *r, char *buf, int n);
int  oakcommon_xml_reader_attr(OakCommonXmlReader *r, const char *attr,
                               char *buf, int n);
int  oakcommon_xml_reader_read_element_text(OakCommonXmlReader *r,
                                            char *buf, int n);
void oakcommon_xml_reader_skip_current(OakCommonXmlReader *r);

写出侧 oakcommon_xml_writer_*(init_to_string/write_attribute/ write_text_element/free 得字符串,两段式)。

2.3 oakcommon/files.h(common/filefunctions.h,render 7 次)

int  oakcommon_file_exists(const char *path);                 /* 1/0 */
int  oakcommon_file_size(const char *path);                   /* -1 失败 */
int  oakcommon_file_read_all(const char *path, char *buf, int n); /* 两段式 */
int  oakcommon_file_write_all(const char *path, const char *data, int n);
int  oakcommon_dir_mkpath(const char *path);
int  oakcommon_get_config_path(char *buf, int n);
int  oakcommon_get_temp_path(char *buf, int n);

2.4 oakcommon/ocio.h、oakcommon/oii.h、oakcommon/ffmpeg.h

(ocioutils/oiioutils/ffmpegutils,按 01 §3 机械 POD 化; OAK/OIIO/FFmpeg 类型全部句柄化或拍平字段。)

2.5 oakcommon/misc.h

jobtime(double oakcommon_jobtime_now(void))、current (oakcommon_current_get/set 线程局部当前对象句柄)。

3. 切割点(common 的 12 次反向 include,逐条)

现状 处理
common → render/ 7 次(播放钟/自动滚动等引 render 类型) 涉及文件(playbackaudioclock/autoscroll 等)上移出 oakcommon:它们不是底层工具,归 oakrender(M7)
common → node/ 3 次 同上,归 oaknode(M3)
common → undo/ 1 次 同上,归 oakundo(M2)
common → codec/ 1 次 同上,归 oakcodec(M5)
common → pluginSupport/ 1 次 同上,归 oakplugin(M9)

判据:切完后 grep -rn '#include "' oakcommon/src | grep -vE '"(oakcommon|olive/core)' 为空(只剩 oakcore 与 Qt/系统头)。

4. 测试(映射 03 §2)

  • config:set/get 往返、int/double fallback、两段式 buf。
  • xml:reader 解析样例串、attr/text 读取、skip、writer 产出解析回读。
  • files:临时目录建/写/读/尺寸/删除。
  • 每函数 1 正常 + 1 错误路径;oakcommon_debug_alive_count() 泄漏断言。