{"id":51918031,"url":"https://github.com/zfl9/zmake","last_synced_at":"2026-07-27T14:00:58.778Z","repository":{"id":369241930,"uuid":"1288826617","full_name":"zfl9/zmake","owner":"zfl9","description":"Integrate C/C++ build system into Zig build system","archived":false,"fork":false,"pushed_at":"2026-07-19T13:15:44.000Z","size":47,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-19T14:09:39.093Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zfl9.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-04T02:40:59.000Z","updated_at":"2026-07-19T13:15:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zfl9/zmake","commit_stats":null,"previous_names":["zfl9/zmake"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/zfl9/zmake","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zfl9%2Fzmake","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zfl9%2Fzmake/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zfl9%2Fzmake/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zfl9%2Fzmake/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zfl9","download_url":"https://codeload.github.com/zfl9/zmake/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zfl9%2Fzmake/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35953520,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-27T02:00:06.776Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-27T14:00:58.191Z","updated_at":"2026-07-27T14:00:58.751Z","avatar_url":"https://github.com/zfl9.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ZMake\n\nZMake 是 Zig 构建系统的一个适配层工具，它可以将现有 C/C++ 构建系统无缝融入 Zig 生态。\n\n## 背景\n\nC/C++ 开发者长期缺乏集**包管理**与**构建**于一体的现代工具链。Autotools 与 CMake 仅聚焦于构建本身，并无内置的包管理能力；包管理长期依赖于手动下载、git submodule 或系统包管理器，体验割裂。\n\nZig 提供了完整的解决方案：\n\n- **`build.zig.zon`** — 去中心化的包管理器。任何 tarball（`.tar.gz`、`.zip` 等）均可作为 Zig 包纳入依赖管理，tarball 内无需包含 Zig 构建元数据。\n- **`zig build`** — 内置构建系统，用强类型 \u0026 通用的 Zig 编程语言（而非 Autotools/CMake 等领域特定语言）来描述构建过程，与包管理器深度集成。\n- **`zig cc` / `zig c++`** — 基于 Clang/LLVM 的全功能编译工具链。内置各目标平台的 libc/libc++ 源码，提供一流的、开箱即用的交叉编译支持。\n\n```bash\n# 引入 C 库依赖，自动写入 build.zig.zon\nzig fetch --save=wolfssl https://github.com/wolfSSL/wolfssl/archive/refs/tags/v5.9.2-stable.tar.gz\n\n# 一键编译\nzig build\n\n# 一键交叉编译\nzig build -Dtarget=aarch64-linux-musl\nzig build -Dtarget=x86_64-linux-musl -Dcpu=x86_64_v3\n```\n\n包管理、构建系统、编译 \u0026 交叉编译，三者合一，这正是 C/C++ 生态长久以来缺失的关键拼图。\n\n## 问题\n\n若上游 C/C++ 项目已原生支持 `build.zig` 且被积极维护，这无疑是最理想的情况（此时亦不需要 ZMake）。然而，绝大多数现有 C/C++ 库并不原生支持 `build.zig`。\n\n面对这些库，社区的常见做法是由第三方为它们编写一份 `build.zig`。但复杂 C/C++ 项目的构建系统并非小工程——老牌库的构建脚本通常积累了数十年的环境探测、平台特定标志与条件编译逻辑，要将其完整、准确地复刻到 `build.zig` 中极其困难。这导致此类第三方的 `build.zig` 往往存在特性缺失，或停留在玩具级别，难以用于生产。此外，一旦上游源码重构或新增文件，这份 `build.zig` 就会迅速失效，引入高昂的二次维护成本。\n\n## 解法\n\nZMake 的核心思想是**驱动而非重写**。你无需修改上游的任何构建脚本，只需在你的 `build.zig.zon` 中将 C/C++ 源码（tarball、git 仓库等）作为标准 Zig 包引入，然后在你的 `build.zig` 中调用 ZMake。ZMake 会在 Zig 的隔离沙盒中驱动上游原生的构建系统，同时将 Zig 的完整工具链与交叉编译能力透明注入其中。\n\n\u003e `build.zig.zon` 中的依赖包只需是一个标准 tarball（`.tar.gz`、`.zip` 等常见打包格式均可），**并不要求** tarball 内包含 `build.zig`、`build.zig.zon` 等 Zig 构建元数据。这正是 Zig 可以无缝承接 C/C++ 项目的基础能力。\n\n### 核心特性\n\n- **非侵入式 \u0026 无需额外维护**：不修改上游源码，无需向上游项目引入或维护 `build.zig`。\n- **工具链自动注入**：自动将 `zig cc` / `zig c++` 以及 Target、Optimize、LTO 等信息注入至上游构建系统。\n- **缓存系统集成**：将所有的构建上下文序列化为一个描述文件，与 Zig 缓存系统优雅集成，确保并发构建的正确性。\n\n## 快速开始\n\n以 wolfssl 为例，将其原生 tarball 接入 Zig 构建系统。\n\n\u003e 这里仅作演示用途，[wolfssl-zig](https://github.com/zfl9/wolfssl-zig) 在本文基础上提供了更完善的集成。\n\n使用 `zig fetch --save` 获取依赖（具体版本见 [Tags](https://github.com/zfl9/zmake/tags) 页面）：\n\n```bash\n# 引入 zmake 本身\nzig fetch --save=zmake https://github.com/zfl9/zmake/archive/refs/tags/v1.3.0.tar.gz\n\n# 引入 wolfssl 源码 tarball\nzig fetch --save=wolfssl https://github.com/wolfSSL/wolfssl/archive/refs/tags/v5.9.2-stable.tar.gz\n```\n\n执行后 `build.zig.zon` 将包含：\n\n```zig\n.{\n    .name = \"my-project\",\n    .version = \"0.1.0\",\n    .dependencies = .{\n        .zmake = .{\n            .url = \"https://github.com/zfl9/zmake/archive/refs/tags/v1.3.0.tar.gz\",\n            .hash = \"...\",\n        },\n        .wolfssl = .{\n            .url = \"https://github.com/wolfSSL/wolfssl/archive/refs/tags/v5.9.2-stable.tar.gz\",\n            .hash = \"...\",\n        },\n    },\n}\n```\n\n**build.zig** — 配置并构建：\n\n```zig\nconst std = @import(\"std\");\nconst ZMake = @import(\"zmake\").ZMake;\n\npub fn build(b: *std.Build) !void {\n    const target = b.standardTargetOptions(.{});\n    const optimize = b.standardOptimizeOption(.{});\n\n    const wolfssl = ZMake.create(b, \"wolfssl\", .{\n        .build_system_type = .autotools,\n        .source_dir = b.dependency(\"wolfssl\", .{}).path(\"\"),\n        .target = target,\n        .optimize = optimize,\n        .run_autogen = true,\n    });\n    wolfssl.add_configure_arg(\"--enable-tls13\");\n    wolfssl.add_configure_arg(\"--disable-oldtls\");\n    const build_out = wolfssl.build();\n\n    // 导出命名路径，供下游 dependency 使用者引用\n    b.addNamedLazyPath(\"include\", build_out.path(b, \"include\"));\n    b.addNamedLazyPath(\"lib\", build_out.path(b, \"lib\"));\n\n    // 安装头文件与库文件（zig build 时触发）\n    b.installDirectory(.{\n        .source_dir = build_out.path(b, \"include\"),\n        .install_dir = .header,\n        .install_subdir = \"\",\n    });\n    const install_lib = b.addInstallLibFile(build_out.path(b, \"lib/libwolfssl.a\"), \"libwolfssl.a\");\n    b.getInstallStep().dependOn(\u0026install_lib.step);\n}\n```\n\n- ZMake 自动完成 wolfssl 的配置与构建，并与 Zig 的缓存系统紧密集成。\n- 执行 `zig build`，编译产出在 `./zig-out/` 下，可见 include、lib 等文件。\n- 执行 `zig build -Dtarget=...` 进行交叉编译，与原生的 Zig 使用方式一致。\n\n## 支持的构建系统\n\n| 类型 | 状态 |\n|------|------|\n| Autotools | ✅ 已完成 |\n| CMake | 🚧 计划中 |\n| Makefile | 🚧 计划中 |\n\n## API 参考\n\n### `ZMake`\n\n#### `ZMake.create(b, name, options) → *ZMake`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `build_system_type` | `.autotools` / `.cmake` / `.makefile` | 上游构建系统类型 |\n| `source_dir` | `LazyPath` | 源码目录路径 |\n| `target` | `ResolvedTarget` | 编译目标（默认 host） |\n| `optimize` | `OptimizeMode` | 优化模式（默认 ReleaseFast） |\n| `lto` | `LtoMode` | LTO 模式（默认 none） |\n| `separate_sections` | `bool` | `-ffunction-sections -fdata-sections`（默认 true） |\n| `gc_sections` | `bool` | `-Wl,--gc-sections`（默认 true） |\n| `strip` | `bool` | 是否剥离符号（默认根据 optimize 自动选择） |\n| `run_autogen` | `bool` | 是否在 configure 前执行 autogen.sh（默认 false） |\n| `install_prefix` | `[]const u8` | 逻辑安装前缀（默认 \"/usr\"） |\n| `nproc` | `usize` | `make -j\u003cN\u003e` 并行数（默认使用当前的 CPU 核心数） |\n| `use_bear` | `bool` | 使用 `bear` 以生成 **编译数据库**（默认 false） |\n| `build_dir_symlink` | `[]const u8` | 创建指向 `build_dir` 的符号链接（默认不创建） |\n\n\u003e `use_bear=false` 时，build_dir 下也会创建 `compile_commands.json`，内容是 `[]` 空列表。\n\n#### `zmake.add_configure_arg(arg: []const u8)`\n\n添加额外的 `./configure` 参数（仅 Autotools）。\n\n#### `zmake.build() → LazyPath`\n\n执行构建，返回 **构建产出目录**（即 `{include, lib, ...}`）的 `LazyPath`。\n\n#### `zmake.get_build_dir() → LazyPath`\n\n获取指向 **构建目录** 的 `LazyPath`。只允许在 `build()` 之后调用。\n\n#### `zmake.get_build_out() → LazyPath`\n\n获取指向 **构建产出目录** 的 `LazyPath`。只允许在 `build()` 之后调用。\n\n---\n\n### `Pipeline`\n\n依次执行多个系统命令或自定义 Step，Step 之间自动建立先后依赖关系。\n\n#### `Pipeline.init(b, options) → Pipeline`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `cwd` | `LazyPath` | 系统命令执行时的工作目录（可选） |\n\n#### `pipeline.add_command(program, options) → *Step.Run`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `name` | `[]const u8` | 步骤名称（可选） |\n| `ignore_stdout` | `bool` | 捕获并忽略 stdout（默认 true） |\n\n#### `pipeline.add_step(step: *std.Build.Step)`\n\n将一个自定义 Step 追加到 Pipeline 末尾，自动依赖前一个步骤。\n\n#### `pipeline.get_last_step() → *std.Build.Step`\n\n返回 Pipeline 中最后一个 Step。\n\n---\n\n### `Symlink`\n\n一个自定义的 `std.Build.Step`，用于在项目目录（build_root）下创建 **符号链接**。\n\n#### `Symlink.create(b, symlink_filename, point_to_path) → *Symlink`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `symlink_filename` | `[]const u8` | 符号链接的文件名 |\n| `point_to_path` | `LazyPath` | 符号链接指向的目标路径 |\n\n\u003e 注：`symlink_filename` 可以包含相对路径，程序将自动创建其目录。\n\n---\n\n### `PatchCDB`\n\n一个自定义的 `std.Build.Step`，用于修复 `bear` 生成的 `compile_commands.json`。\n\n- `argv[0]` 替换为 `clang`\n- 过滤 `-mcpu=*` 等不兼容参数\n\n#### `PatchCDB.create(b, cdb_path) → *PatchCDB`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `cdb_path` | `LazyPath` | `compile_commands.json` 的路径 |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzfl9%2Fzmake","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzfl9%2Fzmake","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzfl9%2Fzmake/lists"}