# raw.resBuilder.coff32

`raw.resBuilder.coff32` 将标准 Windows `.res` 或规范化资源数组转换为 **32 位 i386 PE/COFF resource object**。它面向 TinyCC 的 PE 链接器，亦可用于 MinGW/GNU ld、现代 Microsoft LINK，以及需要标准 Windows 资源对象的其他工具链。

## 导入

```aardio
import raw.resBuilder.coff32;
```

本库不是通用 COFF writer，不生成代码对象、静态库或 x64/ARM 对象。

## 从资源数组生成对象

```aardio
import raw.resBuilder.coff32;

var result,err,code = raw.resBuilder.coff32.write(
    "/build/app-resource.obj",
    [
        {type=10;name=1;language=0x0409;data="embedded data"};
        {type=10;name="MY_DATA";language=0x0409;data='A\0B'}
    ]
);

if(!result) return null,err,code;
print(result.bytes,result.relocations,result.sectionName);
```

资源数组元素字段：

- `type`：数字 ID `0..65535`，或非空 UTF-8 字符串。
- `name`：数字 ID `0..65535`，或非空 UTF-8 字符串。
- `language`：LANGID `0..65535`，省略时默认 `0x0409`。
- `data`：`string` 或 `buffer`，按原始字节保留。

同一个 `(type,name,language)` 只能出现一次。字符串 type/name 会编码为 UTF-16，资源目录按 Windows 资源查找所需的 UTF-16 code unit 顺序排序。

## 转换标准 `.res`

```aardio
import raw.resBuilder.coff32;

var result,err = raw.resBuilder.coff32.convert(
    "/build/app.res",
    "/build/app-resource.obj"
);
if(!result) return null,err;
```

输入支持当前 `raw.resBuilder` 生成的标准 `.res`，也支持已验证的 `rc.exe`、GNU `windres` 等工具生成的标准 `.res`。损坏记录、越界数据、非法 UTF-16 标识符、重复资源和不符合首个空记录约定的输入会被拒绝。

`.res` 的 `DataVersion`、`MemoryFlags`、`Version`、`Characteristics` 是构建记录元数据；PE resource directory 不提供完全对应的字段。本库承诺资源类型、名称、语言和数据语义等价，不承诺这些 `.res` 元数据逐字节映射到最终 PE。

## dryRun 与结果

```aardio
var result,err,code = raw.resBuilder.coff32.write(
    "/build/not-created.obj",
    [{type=10;name=1;data="test"}],
    {dryRun=true}
);

// result.data 是待写入的完整 COFF 字节串；不会创建目标文件。
```

成功结果至少包含：

- `ok=true`
- `path`：规范化后的目标路径
- `bytes`：对象总字节数
- `resources`：资源数量
- `machine=0x014C`：i386 machine
- `sectionBytes`：`.rsrc` 节数据大小
- `relocations`：资源数据 RVA relocation 数量
- `sectionName`：输出节名
- `data`：仅在 `dryRun=true` 时返回

失败返回 `null, error[, errorCode]`，错误信息包含处理阶段，例如 `coff32.res.read`、`coff32.normalize` 或 `coff32.object.write`。

## 输出节名

默认输出节名为 `.rsrc`，这是 TinyCC `pe_load_res()` 所需的格式。可通过 `options.sectionName` 指定 1 到 8 个 ASCII 字节的节名，例如某些旧版 VC6 LINK 环境可使用：

```aardio
var result,err = raw.resBuilder.coff32.write(
    "/build/vc6-resource.obj",
    [{type=10;name=1;data="test"}],
    {sectionName=".rsrc$01"}
);
```

`.rsrc$01` 只是兼容变体；默认 `.rsrc` 是本库面向 TinyCC 的主要输出。

## 确定性与兼容范围

- 输入资源顺序不影响输出字节布局。
- 输出固定为 i386 PE/COFF 单资源节对象，使用 `IMAGE_REL_I386_DIR32NB` relocation。
- TinyCC、MinGW-w64 i686 GCC/GNU ld 和 Microsoft LINK 已完成真实资源链接与 Win32 API 回读验证。
- VC6.0 的 `cvtres -> LINK` 控制链路已验证；其旧版 LINK 对 plain `.rsrc` 输入节名存在兼容性问题时，可尝试显式使用 `.rsrc$01`。
- 不支持 x64、ARM/ARM64、ELF、Mach-O、代码 COFF、静态库归档或调试信息。
