{"id":31923875,"url":"https://github.com/chainsafe/zbuild","last_synced_at":"2025-10-13T23:58:28.739Z","repository":{"id":282070721,"uuid":"946957689","full_name":"ChainSafe/zbuild","owner":"ChainSafe","description":"An opinionated zig build tool","archived":false,"fork":false,"pushed_at":"2025-08-22T13:03:57.000Z","size":143,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-10-02T02:53:35.385Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/ChainSafe.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}},"created_at":"2025-03-12T00:02:48.000Z","updated_at":"2025-08-22T13:04:00.000Z","dependencies_parsed_at":"2025-03-12T17:22:56.534Z","dependency_job_id":"b0b69fdb-026a-4cd3-ace0-802006ebbf29","html_url":"https://github.com/ChainSafe/zbuild","commit_stats":null,"previous_names":["chainsafe/zbuild"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ChainSafe/zbuild","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChainSafe%2Fzbuild","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChainSafe%2Fzbuild/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChainSafe%2Fzbuild/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChainSafe%2Fzbuild/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChainSafe","download_url":"https://codeload.github.com/ChainSafe/zbuild/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChainSafe%2Fzbuild/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279017175,"owners_count":26086019,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"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":"2025-10-13T23:58:19.624Z","updated_at":"2025-10-13T23:58:28.731Z","avatar_url":"https://github.com/ChainSafe.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zbuild\n\nAn opinionated build tool for Zig projects.\n\n## Introduction\n\n`zbuild` is a command-line build tool designed to simplify and enhance the build process for Zig projects. It leverages a ZON-based configuration file (`zbuild.zon`) to define project builds declaratively, generating a corresponding `build.zig` and `build.zig.zon` file that integrates seamlessly with Zig’s native build system. This approach reduces the complexity of writing and maintaining Zig build scripts manually, offering a structured alternative for managing dependencies, modules, executables, libraries, tests, and more.\n\nNote: `zbuild` is under active development. Some features are incomplete or subject to change. Check the `docs/TODO.md` file for planned enhancements.\n\n## Features\n\n- **ZON-based Configuration**: Define your build in a `zbuild.zon` file instead of writing Zig code directly.\n- **Automatic build.zig Generation**: Create a `build.zig` and `build.zig.zon` file from your configuration.\n- **Comprehensive Build Support**: Manage dependencies, modules, executables, libraries, objects, tests, formatting, and run commands.\n- **Command-Line Interface**: Execute common build tasks like compiling executables, running tests, and formatting code.\n\n## Installation\n\nCurrently, zbuild must be built from source:\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/chainsafe/zbuild.git\ncd zbuild\n```\n\n2. Build the executable:\n```bash\nzig build -Doptimize=ReleaseFast\n```\n\n3. (Optional) Install it globally:\n```bash\nzig build install --prefix ~/.local\n```\n\nA pre-built binary distribution is planned for future releases once sufficient feature-completeness is achieved.\n\n## Usage\n\n`zbuild` provides a command-line interface with various commands to manage your Zig projects. Below is the general syntax and a list of available commands:\n\n```\nUsage: zbuild [global_options] [command] [options]\n```\n\n### Commands\n\n- `init`: Initialize a new Zig project with a basic `zbuild.zon`, `build.zig`, `build.zig.zon`, and `src/main.zig` in the current directory.\n- `fetch`: Copy a package into the global cache  and optionally add it to `zbuild.zon` and `build.zig.zon`\n- `install`: Install all artifacts defined in `zbuild.zon`.\n- `uninstall`: Uninstall all artifacts.\n- `sync`: Synchronize `build.zig` and `build.zig.zon` with `zbuild.zon`.\n- `build`: Run `zig build` with the generated `build.zig`.\n- `build-exe \u003cname\u003e`: Build a specific executable defined in `zbuild.zon`.\n- `build-lib \u003cname\u003e`: Build a specific library.\n- `build-obj \u003cname\u003e`: Build a specific object file.\n- `build-test \u003cname\u003e`: Build a specific test into an executable.\n- `run \u003cname\u003e`: Run an executable or a custom run script.\n- `test [name]`: Run all tests or a specific test.\n- `fmt [name]`: Format code for all or a specific formatting target.\n- `help`: Print the help message and exit.\n- `version`: Print the version number and exit.\n\n### Global Options\n\n- `--project-dir \u003cpath\u003e`: Set the project directory (default: `.`).\n- `--zbuild-file \u003cpath\u003e`: Specify the configuration file (default: `zbuild.zon`).\n- `--no-sync`: Skip automatic synchronization of `build.zig` and `build.zig.zon`.\n\n### General Options\n\n- `-h, --help`: Print command-specific usage.\n\nFor command-specific options (e.g., `fetch`), use zbuild \u003ccommand\u003e --help.\n\n## Configuration\n\nThe `zbuild.zon` file is the heart of the zbuild system. It defines your project’s structure and build settings. Below is an example configuration:\n\n```zon\n.{\n    .name = .example_project,\n    .version = \"1.2.3\",\n    .description = \"A comprehensive example\",\n    .fingerprint = 0x90797553773ca567,\n    .minimum_zig_version = \"0.14.0\",\n    .paths = .{ \"build.zig\", \"build.zig.zon\", \"src\" },\n    .keywords = .{\"example\"},\n    .dependencies = .{\n        .mathlib = .{\n            .path = \"deps/mathlib\",\n        },\n        .network = .{\n            .url = \"https://github.com/example/network/archive/v1.0.0.tar.gz\",\n        },\n    },\n    .options_modules = .{\n        .build_options = .{\n            .max_depth = .{\n                .type = \"usize\",\n                .default = 100,\n            },\n        },\n    },\n    .modules = .{\n        .utils = .{\n            .root_source_file = \"src/utils/main.zig\",\n            .imports = .{.mathlib, .build_options},\n            .link_libc = true,\n        },\n        .core = .{\n            .root_source_file = \"src/core/core.zig\",\n            .imports = .{.utils},\n        },\n    },\n    .executables = .{\n        .main_app = .{\n            .root_module = .{\n                .root_source_file = \"src/main.zig\",\n                .imports = .{.core, .network},\n            },\n        },\n    },\n    .libraries = .{\n        .libmath = .{\n            .version = \"0.1.0\",\n            .root_module = .utils,\n            .linkage = .static,\n        },\n    },\n    .tests = .{\n        .unit_tests = .{\n            .root_module = .{\n                .root_source_file = \"tests/unit.zig\",\n                .imports = .{.core, .utils},\n            },\n        },\n    },\n    .fmts = .{\n        .source = .{\n            .paths = .{\"src\", \"tests\"},\n            .exclude_paths = .{\"src/generated\"},\n            .check = true,\n        },\n    },\n    .runs = .{\n        .start_server = \"zig run src/server.zig\",\n        .build_docs = \"scripts/build_docs.sh\",\n    },\n}\n```\n\n### Key Sections\n\n- `name`, `version`, `fingerprint`, `minimum_zig_version`, `paths`: Project metadata (required).\n- `dependencies`: External packages (path or URL).\n- `options_modules`: Configurable build options bundled into modules.\n- `modules`: Reusable code units with optional imports and build settings.\n- `executables`, `libraries`, `objects`: Build targets with root modules.\n- `tests`: Test targets with optional filters.\n- `fmts`: Code formatting rules.\n- `runs`: Custom shell commands.\n\n## Hello World Example\n\nHere’s a step-by-step example to create and build a simple Zig project with zbuild:\n\n1. Initialize the project:\n\n```bash\nmkdir myproject\ncd myproject\nzbuild init\n```\n\n2. (Optional) Inspect `zbuild.zon`\n\n```zon\n.{\n    .name = .myproject,\n    .version = \"0.1.0\",\n    .fingerprint = 0x\u003cgenerated\u003e,\n    .minimum_zig_version = \"0.14.0\",\n    .paths = .{ \"build.zig\", \"build.zig.zon\", \"src\" },\n    .executables = .{\n        .myproject = .{\n            .root_module = .{\n                .root_source_file = \"src/main.zig\",\n            },\n        },\n    },\n}\n```\n\n3. Update `src/main.zig`\n```zig\nconst std = @import(\"std\");\npub fn main() !void {\n    const allocator = std.heap.page_allocator;\n    const args = try std.process.argsAlloc(allocator);\n    defer std.process.argsFree(allocator, args);\n\n    const arg = if (args.len \u003e= 2) args[1] else \"zbuild\";\n    std.debug.print(\"Hello {s}!\\n\", .{arg});\n}\n```\n\n4. (Optional) Build the Executable:\n\n```bash\nzbuild build-exe myproject\n```\nThis builds the `myproject` executable into `zig-out/bin`.\n\n5. Run the Executable:\n\n```bash\nzbuild run myproject -- world\n```\n\nOutputs: `Hello, world!`\n\n## Fetching Dependencies\n\nAdd a dependency to your project:\n```bash\nzbuild fetch --save=example https://github.com/example/repo/archive/v1.0.0.tar.gz\n```\n\nThis updates `zbuild.zon` with:\n```zon\n.dependencies = .{\n    .example = {\n        .url = \"https://github.com/example/repo/archive/v1.0.0.tar.gz,\n    }\n}\n```\n\nAnd synchronizes `build.zig.zon` with the fetched hash.\n\n\n## Contributing\n\nContributions are welcome! To contribute:\n\n1. Fork the repository on GitHub: https://github.com/chainsafe/zbuild.\n2. Create a branch for your changes.\n3. Submit a pull request with a clear description of your improvements.\n\nPlease open an issue first to discuss significant changes or report bugs.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchainsafe%2Fzbuild","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchainsafe%2Fzbuild","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchainsafe%2Fzbuild/lists"}