From 86410dc077357ce08285eff54ce0bb1ee634fe8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=B1=9F=E8=8A=B7=E9=85=B1=E7=B4=AB?= Date: Fri, 18 Sep 2026 16:01:49 +0800 Subject: [PATCH] Add multilingual README documentation --- README.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++ README.zh-CN.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++ README.zh-TW.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 295 insertions(+) create mode 100644 README.md create mode 100644 README.zh-CN.md create mode 100644 README.zh-TW.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..1cc7f49 --- /dev/null +++ b/README.md @@ -0,0 +1,101 @@ +# ZBinary2CArray + +[简体中文](README.zh-CN.md) · [繁體中文](README.zh-TW.md) · **English** + +`ZBinary2CArray` converts a binary file into a C/C++ array. It provides a +header-only C++20 library and a command-line program (`zbtca-cli`) for +generating ready-to-include source files. + +## Features + +- Export binary data as `unsigned char`, `unsigned short`, `unsigned int`, or + `unsigned long long` arrays. +- Generate either a self-contained header or a source file with an `extern` + declaration header. +- Configure storage and const specifiers, include guards, line wrapping, and + generated-file annotations. +- Automatically creates missing output directories. + +## Requirements + +- A C++20-compatible compiler. +- CMake 3.31.6 or newer to build the command-line program. + +## Build + +```sh +cmake -S . -B build +cmake --build build +``` + +The executable is written to `build/zbtca-cli` (or `build/Debug/zbtca-cli.exe` +for common multi-configuration generators). + +## Command-line usage + +```text +zbtca-cli [options] +``` + +Convert `assets/logo.bin` to an includeable header: + +```sh +zbtca-cli assets/logo.bin --output generated/logo.hpp --type u8 \ + --storage inline --const constexpr +``` + +By default, header-only output is generated beside the input file using the +name `.hpp`; for example, `assets/logo.bin.hpp`. Use `--source` to +generate a `.cpp` file and a companion `extern` header: + +```sh +zbtca-cli assets/logo.bin --source --output generated/logo.cpp --type u32 +``` + +### Options + +| Option | Description | +| --- | --- | +| `-o`, `--output ` | Output path. Defaults to a name derived from the input. | +| `-t`, `--type ` | Element type: `u8`, `u16`, `u32`, or `u64`; defaults to `u8`. | +| `--header-only` | Generate a header-only output file (default). | +| `--source` | Generate a source file and an `extern` declaration header. | +| `--no-inc-guard` | Do not emit an include guard. | +| `--storage ` | Storage specifier: `none`, `static`, or `inline`. | +| `--const ` | Const specifier: `none`, `const`, or `constexpr`. | +| `-n`, `--nums-per-line ` | Elements per line; `0` selects the type-specific default. | +| `--no-tidy` | Disable formatted hexadecimal output. | +| `--no-anno-tool`, `--no-anno-runner`, `--no-anno-file`, `--no-anno-size`, `--no-anno-time` | Disable the corresponding generated-file annotation. | +| `--tool-name ` | Override the tool name in annotations. | +| `--runner-name ` | Override the runner name in annotations. | +| `-h`, `--help` | Print command help. | + +## Library usage + +Include `ZBinary2CArray/zbtca.h`, load a binary file with `ZBTCA_Bin`, and +write it through `ZBTCA_Output`: + +```cpp +#include "ZBinary2CArray/zbtca.h" + +int main() { + ZBTCA_Bin binary("assets/logo.bin"); + ZBTCA_Output output(binary); + + auto& config = output.Config(); + config.ExportTypeFlags = ZBTCA_Types::TypeFlags::u8; + config.HeaderOnly = true; + config.StorageSpecifier = ZBTCA_Types::OutputCfg::StorageSpecifier_inline; + config.ConstSpecifier = ZBTCA_Types::OutputCfg::ConstSpecifier_constexpr; + + const ZBTCA_Response response = output("generated/logo.hpp"); + return response.status() ? 0 : 1; +} +``` + +The generated identifier is derived from the input filename; characters that +are invalid in C/C++ identifiers are replaced with underscores. + +## License + +This project is released under the [MIT License](LICENSE). diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..70287ab --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,97 @@ +# ZBinary2CArray + +**简体中文** · [繁體中文](README.zh-TW.md) · [English](README.md) + +`ZBinary2CArray` 用于将二进制文件转换为 C/C++ 数组。项目提供仅头文件的 +C++20 库，以及可生成可直接包含源码文件的命令行程序 `zbtca-cli`。 + +## 特性 + +- 支持导出为 `unsigned char`、`unsigned short`、`unsigned int` 或 + `unsigned long long` 数组。 +- 可生成独立头文件，或生成源文件及带有 `extern` 声明的配套头文件。 +- 可配置存储说明符、常量说明符、包含保护、换行数量和生成文件注释。 +- 自动创建不存在的输出目录。 + +## 环境要求 + +- 支持 C++20 的编译器。 +- 构建命令行程序需要 CMake 3.31.6 或更高版本。 + +## 构建 + +```sh +cmake -S . -B build +cmake --build build +``` + +可执行文件位于 `build/zbtca-cli`；使用常见多配置生成器时，通常位于 +`build/Debug/zbtca-cli.exe`。 + +## 命令行用法 + +```text +zbtca-cli [options] +``` + +将 `assets/logo.bin` 转换为可包含的头文件： + +```sh +zbtca-cli assets/logo.bin --output generated/logo.hpp --type u8 \ + --storage inline --const constexpr +``` + +默认会在输入文件旁生成仅头文件输出，文件名为 `.hpp`，例如 +`assets/logo.bin.hpp`。使用 `--source` 可生成 `.cpp` 文件及配套的 `extern` +声明头文件： + +```sh +zbtca-cli assets/logo.bin --source --output generated/logo.cpp --type u32 +``` + +### 选项 + +| 选项 | 说明 | +| --- | --- | +| `-o`, `--output ` | 输出路径；默认根据输入路径生成。 | +| `-t`, `--type ` | 元素类型：`u8`、`u16`、`u32` 或 `u64`；默认 `u8`。 | +| `--header-only` | 生成仅头文件输出（默认）。 | +| `--source` | 生成源文件及含 `extern` 声明的头文件。 | +| `--no-inc-guard` | 不生成包含保护。 | +| `--storage ` | 存储说明符：`none`、`static` 或 `inline`。 | +| `--const ` | 常量说明符：`none`、`const` 或 `constexpr`。 | +| `-n`, `--nums-per-line ` | 每行元素数；`0` 使用按类型设定的默认值。 | +| `--no-tidy` | 禁用格式化的十六进制输出。 | +| `--no-anno-tool`、`--no-anno-runner`、`--no-anno-file`、`--no-anno-size`、`--no-anno-time` | 禁用对应的生成文件注释。 | +| `--tool-name ` | 覆盖注释中的工具名称。 | +| `--runner-name ` | 覆盖注释中的运行者名称。 | +| `-h`, `--help` | 显示命令帮助。 | + +## 库用法 + +包含 `ZBinary2CArray/zbtca.h`，使用 `ZBTCA_Bin` 读取二进制文件，再通过 +`ZBTCA_Output` 写出： + +```cpp +#include "ZBinary2CArray/zbtca.h" + +int main() { + ZBTCA_Bin binary("assets/logo.bin"); + ZBTCA_Output output(binary); + + auto& config = output.Config(); + config.ExportTypeFlags = ZBTCA_Types::TypeFlags::u8; + config.HeaderOnly = true; + config.StorageSpecifier = ZBTCA_Types::OutputCfg::StorageSpecifier_inline; + config.ConstSpecifier = ZBTCA_Types::OutputCfg::ConstSpecifier_constexpr; + + const ZBTCA_Response response = output("generated/logo.hpp"); + return response.status() ? 0 : 1; +} +``` + +生成的标识符由输入文件名派生；不符合 C/C++ 标识符规则的字符会被替换为下划线。 + +## 许可证 + +本项目采用 [MIT 许可证](LICENSE)。 diff --git a/README.zh-TW.md b/README.zh-TW.md new file mode 100644 index 0000000..2cee639 --- /dev/null +++ b/README.zh-TW.md @@ -0,0 +1,97 @@ +# ZBinary2CArray + +[简体中文](README.zh-CN.md) · **繁體中文** · [English](README.md) + +`ZBinary2CArray` 可將二進位檔案轉換為 C/C++ 陣列。專案提供僅標頭檔的 +C++20 函式庫，以及能產生可直接包含之原始碼檔案的命令列程式 `zbtca-cli`。 + +## 功能 + +- 支援匯出為 `unsigned char`、`unsigned short`、`unsigned int` 或 + `unsigned long long` 陣列。 +- 可產生獨立標頭檔，或產生原始碼檔及附帶 `extern` 宣告的標頭檔。 +- 可設定儲存說明符、常數說明符、包含保護、每行元素數量與產生檔案註解。 +- 自動建立不存在的輸出目錄。 + +## 環境需求 + +- 支援 C++20 的編譯器。 +- 建置命令列程式需要 CMake 3.31.6 或更新版本。 + +## 建置 + +```sh +cmake -S . -B build +cmake --build build +``` + +執行檔位於 `build/zbtca-cli`；使用常見多組態產生器時，通常位於 +`build/Debug/zbtca-cli.exe`。 + +## 命令列用法 + +```text +zbtca-cli [options] +``` + +將 `assets/logo.bin` 轉換為可包含的標頭檔： + +```sh +zbtca-cli assets/logo.bin --output generated/logo.hpp --type u8 \ + --storage inline --const constexpr +``` + +預設會在輸入檔案旁產生僅標頭檔輸出，檔名為 `.hpp`，例如 +`assets/logo.bin.hpp`。使用 `--source` 可產生 `.cpp` 檔案與附帶的 `extern` +宣告標頭檔： + +```sh +zbtca-cli assets/logo.bin --source --output generated/logo.cpp --type u32 +``` + +### 選項 + +| 選項 | 說明 | +| --- | --- | +| `-o`, `--output ` | 輸出路徑；預設依輸入路徑產生。 | +| `-t`, `--type ` | 元素類型：`u8`、`u16`、`u32` 或 `u64`；預設為 `u8`。 | +| `--header-only` | 產生僅標頭檔輸出（預設）。 | +| `--source` | 產生原始碼檔及含 `extern` 宣告的標頭檔。 | +| `--no-inc-guard` | 不產生包含保護。 | +| `--storage ` | 儲存說明符：`none`、`static` 或 `inline`。 | +| `--const ` | 常數說明符：`none`、`const` 或 `constexpr`。 | +| `-n`, `--nums-per-line ` | 每行元素數；`0` 使用依類型設定的預設值。 | +| `--no-tidy` | 停用格式化的十六進位輸出。 | +| `--no-anno-tool`、`--no-anno-runner`、`--no-anno-file`、`--no-anno-size`、`--no-anno-time` | 停用對應的產生檔案註解。 | +| `--tool-name ` | 覆寫註解中的工具名稱。 | +| `--runner-name ` | 覆寫註解中的執行者名稱。 | +| `-h`, `--help` | 顯示命令說明。 | + +## 函式庫用法 + +包含 `ZBinary2CArray/zbtca.h`，使用 `ZBTCA_Bin` 讀取二進位檔案，再透過 +`ZBTCA_Output` 寫出： + +```cpp +#include "ZBinary2CArray/zbtca.h" + +int main() { + ZBTCA_Bin binary("assets/logo.bin"); + ZBTCA_Output output(binary); + + auto& config = output.Config(); + config.ExportTypeFlags = ZBTCA_Types::TypeFlags::u8; + config.HeaderOnly = true; + config.StorageSpecifier = ZBTCA_Types::OutputCfg::StorageSpecifier_inline; + config.ConstSpecifier = ZBTCA_Types::OutputCfg::ConstSpecifier_constexpr; + + const ZBTCA_Response response = output("generated/logo.hpp"); + return response.status() ? 0 : 1; +} +``` + +產生的識別字由輸入檔名衍生；不符合 C/C++ 識別字規則的字元會替換為底線。 + +## 授權條款 + +本專案採用 [MIT 授權條款](LICENSE)。