# zigbin

**Repository Path**: graviton/zigbin

## Basic Information

- **Project Name**: zigbin
- **Description**: zig 程序嵌入二进制示例
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Zig 二进制资源嵌入演示

本项目演示如何在 Zig 编译产物中嵌入二进制资源（图片、音频等）。

## 项目结构

```
zigbin/
├── build.zig          # 构建配置
├── src/
│   └── main.zig       # 主程序
└── assets/            # 资源文件
    ├── sample.txt     # 文本资源
    └── music.dat      # 音频资源
```

## 核心技术

### 1. @embedFile 编译时嵌入

```zig
const data = @embedFile("path/to/file");
```

- 在编译时将文件内容嵌入到二进制中
- 数据存储在 `.rodata` 段（只读数据段）
- 零运行时开销，直接访问内存

### 2. 常量数组嵌入

```zig
const image_data: [1024]u8 = .{ 0x89, 0x50, ... };
```

- 手动定义二进制数据
- 同样存储在 `.rodata` 段
- 适合小型资源或生成的数据

### 3. 自定义段嵌入（linksection）

```zig
// 嵌入到自定义段
export const custom_data: [32]u8 linksection(".mydata") = .{ ... };

// 嵌入到 .text 段（代码段）
export const text_data: [16]u8 linksection(".text") = .{ ... };

// 嵌入到 .data 段（可写数据段）
export var data_section: [8]u8 linksection(".data") = .{ ... };
```

- 使用 `linksection` 指定目标段
- 可以是标准段（.text, .data, .rodata）或自定义段
- `export` 关键字确保符号不被优化掉
- `.text` 段通常用于代码，但也可以放数据
- `.data` 段的数据可以在运行时修改

## 构建和运行

```bash
# 构建项目
zig build

# 运行程序
zig build run

# 查看编译产物的段信息（Linux/Mac）
objdump -h zig-out/bin/embed_demo

# Windows 使用
dumpbin /HEADERS zig-out\bin\embed_demo.exe
```

## 输出说明

程序会：

1. 显示嵌入的文本文件内容
2. 显示嵌入的二进制数据信息
3. 显示资源在内存中的地址
4. 将嵌入的 PNG 数据写入 `output.png` 文件
5. 演示自定义段：
   - `.mydata` 自定义段的数据
   - `.text` 代码段中的数据
   - `.data` 可写数据段的数据及修改

## 技术要点

- **编译时嵌入**：资源在编译时就被打包进可执行文件
- **零拷贝访问**：直接通过指针访问嵌入的数据
- **跨平台**：Zig 的 `@embedFile` 在所有平台上工作一致
- **类型安全**：编译时检查文件是否存在