{"id":50614905,"url":"https://github.com/deevus/mise-zig-build","last_synced_at":"2026-06-06T07:04:10.547Z","repository":{"id":355748831,"uuid":"1229356755","full_name":"deevus/mise-zig-build","owner":"deevus","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-05T06:26:22.000Z","size":72,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-05T06:26:54.507Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deevus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-05-05T00:50:01.000Z","updated_at":"2026-05-05T06:26:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/deevus/mise-zig-build","commit_stats":null,"previous_names":["deevus/mise-backend-zig","deevus/mise-zig"],"tags_count":null,"template":false,"template_full_name":"jdx/mise-backend-plugin-template","purl":"pkg:github/deevus/mise-zig-build","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deevus%2Fmise-zig-build","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deevus%2Fmise-zig-build/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deevus%2Fmise-zig-build/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deevus%2Fmise-zig-build/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deevus","download_url":"https://codeload.github.com/deevus/mise-zig-build/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deevus%2Fmise-zig-build/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33972420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"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-06-06T07:04:09.724Z","updated_at":"2026-06-06T07:04:10.542Z","avatar_url":"https://github.com/deevus.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mise-zig-build\n\nA [mise](https://mise.jdx.dev) backend plugin for building and installing Zig projects from git or tarballs.\n\nGiven a `build.zig` + `build.zig.zon` project, this backend:\n1. Fetches source from a git URL or tarball\n2. Resolves which Zig compiler version to use\n3. Runs `zig build install --prefix \u003cinstall_path\u003e`\n4. Exposes the built executables on `PATH`\n\n## Prerequisites\n\n- **mise** with experimental backends enabled: `mise settings set experimental true` or `MISE_EXPERIMENTAL=1`\n- **Zig is auto-installed** when the project supplies a version. Specifically, the backend installs zig for you if any of these are present:\n  - `minimum_zig_version` in the project's `build.zig.zon`\n  - `zig_version` opt (in `mise.toml` or `MISE_ZIG_BACKEND_ZIG_VERSION`)\n  - the project's own `mise.toml` pinning zig, when `trust_mise_toml = true`\n- **You only need to pre-install zig yourself** if none of the above apply — i.e. the project doesn't declare a version anywhere. In that case the backend falls back to your active zig (anything installed via `mise install zig@\u003cver\u003e` is sufficient — it doesn't need to be globally activated, just installed).\n\n## Install\n\n```bash\nmise plugin install zig-build https://github.com/deevus/mise-zig-build\n```\n\n## Usage\n\n### From a git repository\n\n```bash\n# Use a tagged release\nmise install zig-build:git+https://github.com/zigzap/zap@v0.1.0\n\n# Run a tool from the project\nmise exec zig-build:git+https://github.com/zigzap/zap@v0.1.0 -- myapp --help\n```\n\nOmitting the `git+` prefix also works for non-tarball URLs:\n\n```bash\nmise install zig-build:https://github.com/zigzap/zap@v0.1.0\n```\n\n### From a tarball (with TOFU hash verification)\n\n```bash\n# Install without hash verification\nmise install zig-build:tar+https://example.com/myapp-1.0.0.tar.gz@0.1.0\n\n# Install with Zig multibase hash verification\nmise install zig-build:tar+https://example.com/myapp-1.0.0.tar.gz@1220abc123...def\n```\n\nWhen a Zig multibase hash (`1220` + 64 hex chars) is provided as the version, the downloaded tarball's SHA-256 is verified against it. Without a hash, the download is accepted on first use (TOFU).\n\n### In mise.toml\n\n```toml\n[tools]\n\"zig-build:git+https://github.com/zigzap/zap\" = \"v0.1.0\"\n```\n\n## Options\n\nOptions can be set via `mise.toml` tool-specific config or environment variables. Precedence: `ctx.options` \u003e env var \u003e default.\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `zig_version` | string | `nil` (auto-detect) | Zig compiler version to use. Overrides `minimum_zig_version` from `build.zig.zon`. |\n| `optimize` | string | `nil` | Build optimization mode (e.g. `ReleaseSafe`, `ReleaseFast`, `ReleaseSmall`). Passed as `-Doptimize=\u003cvalue\u003e`. |\n| `build_args` | array | `[]` | Additional arguments passed to `zig build install`. Use array syntax in mise.toml. |\n| `auto_install_zig` | bool | `true` | Automatically install the resolved Zig version if not already present. |\n| `bin_path` | string | `\"bin\"` | Directory under install path containing executables. |\n| `filter_bins` | array | `[]` | When set, only symlink these specific executables into `\u003cinstall_path\u003e/.mise-bins/` instead of exposing the entire `bin_path`. |\n\n### mise.toml example\n\n```toml\n[tools]\n\"zig-build:git+https://github.com/user/project\" = \"v1.0.0\"\n\n[tools.\"zig-build:git+https://github.com/user/project\".options]\nzig_version = \"0.14.0\"\noptimize = \"ReleaseFast\"\nbuild_args = [\"-Dstrip=true\"]\nbin_path = \"bin\"\nfilter_bins = [\"myapp\"]\n```\n\n### Environment variable equivalents\n\n```\nMISE_ZIG_BACKEND_ZIG_VERSION=0.14.0\nMISE_ZIG_BACKEND_OPTIMIZE=ReleaseFast\nMISE_ZIG_BACKEND_BUILD_ARGS=\"-Dstrip=true -Dcpu=native\"\nMISE_ZIG_BACKEND_AUTO_INSTALL_ZIG=false\nMISE_ZIG_BACKEND_BIN_PATH=bin\nMISE_ZIG_BACKEND_FILTER_BINS=\"myapp helper\"\n```\n\nNote: array env vars are whitespace-split, which means elements cannot contain spaces.\n\n## How it works\n\nThe backend implements three hooks:\n\n- **`BackendListVersions`**: For git sources, lists tags matching semver (`v?X.Y.Z`) via `git ls-remote --tags`. For tarballs, returns `[\"latest\"]`.\n- **`BackendInstall`**: Fetches source, resolves Zig version, builds and installs. Zig version resolution follows a tiered approach (first match wins):\n  1. `zig_version` opt (`ctx.options` or `MISE_ZIG_BACKEND_ZIG_VERSION`)\n  2. The project's own `mise.toml` zig pin — only when `trust_mise_toml = true` (default `false`). Otherwise the project's `mise.toml` is removed before building.\n  3. `minimum_zig_version` from `build.zig.zon`\n  4. Your active zig (resolved via `mise current zig` from a neutral cwd)\n\n  Tiers 1–3 trigger auto-install of the named zig version (unless `auto_install_zig = false`). Tier 4 uses whatever you already have configured.\n- **`BackendExecEnv`**: Exposes the binary directory on `PATH`, respecting `bin_path` and `filter_bins`.\n\n### Ref resolution\n\nGit refs try `--branch \u003cref\u003e` first, falling back to `--branch v\u003cref\u003e` for projects that tag as `vX.Y.Z` but are referenced without the `v` prefix. SHA-shaped refs use plain clone + checkout. `HEAD` clones the default branch.\n\n## Development\n\n```bash\n# Bootstrap test dependencies\nmise run test:setup\n\n# Run unit tests\nmise run test:unit\n\n# Run integration test (links plugin, builds vendored fixture)\nmise run test\n\n# Format code\nmise run format\n\n# Run all CI checks\nmise run ci\n```\n\n### Debugging\n\n```bash\nmise --debug install zig-build:tar+file://./test/fixtures/hello.tar.gz@0.1.0\n```\n\n### Troubleshooting\n\n- **\"no minimum_zig_version declared\"**: The backend will use your active zig. Pin a specific version with the `zig_version` opt, add `minimum_zig_version` to your `build.zig.zon`, or set `trust_mise_toml = true` if the project's `mise.toml` already pins zig.\n- **\"Hash mismatch\"**: The tarball content changed since the hash was recorded (TOFU pin changed). Update the version hash or remove the hash pin.\n- **\"No binaries found\"**: The build succeeded but no files were installed to `bin_path`. Set `bin_path` if your project installs to a different location, or check that your `build.zig` calls `b.installArtifact()`.\n- **Installation fails on macOS/Linux**: Ensure the Zig compiler version you need is available via mise: `mise install zig@\u003cversion\u003e`.\n\n## Status\n\nThis is a **work-in-progress** custom backend for mise. Custom backends are experimental in mise — enable them with `mise settings set experimental true` or `MISE_EXPERIMENTAL=1`.\n\nSee [docs/plans/2026-05-05-zig-project-backend-design.md](docs/plans/2026-05-05-zig-project-backend-design.md) for the design document.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeevus%2Fmise-zig-build","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeevus%2Fmise-zig-build","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeevus%2Fmise-zig-build/lists"}