# setup-zig

Install the Zig compiler for use in an Actions workflow, and preserve the Zig cache across workflow runs.

## Usage

```yaml
jobs:
  test:
    runs-on: ubuntu-latest
    name: Build and Test
    steps:
      - uses: actions/checkout@v3
      - uses: mlugg/setup-zig@v1
      - run: zig build test
```

This will automatically download Zig and install it to `PATH`.

You can use `version` to set a Zig version to download. This may be a release (`0.13.0`), a specific nightly
build (`0.14.0-dev.2+0884a4341`), the string `master` for the latest nightly build, or the string `latest`
for the latest full release. It can also refer to a [Mach nominated version][mach-nominated], such as
`2024.5.0-mach`. The default is `latest`.

```yaml
  - uses: mlugg/setup-zig@v1
    with:
      version: 0.13.0
```

> [!WARNING]
> Mirrors, including the official Zig website, may purge old nightly builds at their leisure. This means
> that if you target an out-of-date nightly build, such as a `0.11.0-dev` build, the download may fail.

If you want to use one specific mirror, you can set it using the `mirror` option:

```yaml
  - uses: mlugg/setup-zig@v1
    with:
      mirror: 'https://pkg.machengine.org/zig'
```

Please don't do this unnecessarily; it's not nice to hammer one mirror. This mirror is not permitted to
be https://ziglang.org/download to avoid the official website being hit with large amounts of requests.
If you've experienced issues with a default mirror, please open an issue, and I will communicate with the
mirror's owner or remove it from the list.

If necessary, the caching of the global Zig cache directory can be disabled by setting the option
`use-cache: false`. Don't do this without reason: preserving the Zig cache will typically speed things up
and decrease the load on GitHub's runners.

[mach-nominated]: https://machengine.org/about/nominated-zig/

## Details

This action attempts to download the requested Zig tarball from a set of mirrors, in a random order. As
a last resort, the official Zig website is used. The tarball's minisign signature is also downloaded and
verified to ensure binaries have not been tampered with. The tarball is cached between runs and workflows.

The global Zig cache directory (`~/.cache/zig` on Linux) is automatically cached between runs, and all
local caches are redirected to the global cache directory to make optimal use of this cross-run caching.

## Adding a mirror

Anyone is welcome to host a Zig download mirror; thanks to the tarball signatures, the mirror provider need
not be trusted. Naturally, if a mirror is found to be a bad actor, it will be removed, and likewise if a
mirror repeatedly encounters reliability problems.

The rules for adding a mirror are listed below. Note that I (@mlugg) reserve the right to, for any or no
reason, exclude mirrors which obey these rules, or include mirrors which violate them.

> [!NOTE]
> While there are a lot of rules listed here, most of them should be obvious. They are stated explicitly here
> to ensure complete clarity on what is expected of a mirror. Please do read these requirements through before
> attempting to add a mirror.

* A mirror provides a single base URL, which we will call `X`.
* `X` **may** include a path component, but is not required to. For instance, `https://foo.bar/zig/` is okay,
  as is `https://zig.baz.qux/`.
* The mirror **must** have working HTTPS support. `X` **must** start with `https://`.
* The mirror **must** cache tarballs locally. For instance, it may not simply forward all requests to another
  mirror.
* The mirror **may** routinely evict its local tarball caches based on any reasonable factor, such as age,
  access frequency, or the existence of newer versions. This does not affect whether the mirror may return 404
  for requests to these files (see below).
* The mirror **must** download its tarballs from either `https://ziglang.org/`, or another mirror which
  follows these rules.
* Tarballs **must** be accessible by sending GET requests for files under `X`, where the filename matches that
  of the files provided by `https://ziglang.org/`, not including the directory part. For instance,
  `X/zig-linux-x86_64-0.13.0.tar.xz` is a valid access, and should return the same file as
  `https://ziglang.org/download/0.13.0/zig-linux-x86_64-0.13.0.tar.xz`.
* Files provided by the mirror **must** be bit-for-bit identical to their `https://ziglang.org/` counterparts.
* If a file is accessed whose Zig version is a master branch build (i.e. a `-dev` version), and the version is
  ordered before the latest major release of Zig, the mirror **may** respond with 404 Not Found, but is not
  required to. For instance, at the time of writing, `0.13.0` is the latest major release of Zig, so a mirror
  may respond with 404 for `0.13.0-dev...` builds, but *not* for `0.14.0-dev...` builds.
* If a file is accessed whose Zig version is `0.5.0` or below, the mirror **may** respond with 404 Not Found,
  but is not required to.
* If a file is acccessed which represents a *source* tarball, such as `X/zig-0.13.0.tar.xz`, the mirror
  **may** respond with 404 Not Found, but is not required to. The same applies to "bootstrap source tarballs",
  such as `X/zig-bootstrap-0.13.0.tar.xz`.
* For all other accesses of valid Zig tarballs, the mirror **must** respond with status code 200 OK and the
  file in question. If the mirror has not yet cached the file locally, it should immediately download it from
  a permitted source (as covered above), and respond with the downloaded file.
* If a tarball `X/foo.ext` is available by the above rules, requesting the minisign signature file
  `X/foo.ext.minisig` **must** also respond with status code 200 OK and the signature file in question, like
  the tarball itself.
* The mirror **may** rate-limit accesses. If an access failed due to rate-limiting, the mirror **should**
  return HTTP status code 429 Too Many Requests.
* The mirror **may** undergo maintenance, upgrades, and other scheduled downtime. If an access fails for this
  reason, where possible, the mirror **should** return HTTP status code 503 Unavailable. The mirror **should**
  try to minimize such downtime.
* The mirror **may** undergo occasional unintended and unscheduled downtime. The mirror **must** go to all
  efforts to minimize such outages, and **must** resolve such outages within a reasonable time upon being
  notified of them.
* The mirror **may** observe the `?source=github-actions` query parameter to track how many requests originate
  from this Action. This Action will provide this query parameter to all mirror requests.

The easiest way to set up a mirror right now is using Mach's [Wrench][wrench]. For instructions, please see
[the relevant section of their README][setup-wrench].

[wrench]: https://github.com/hexops/wrench
[setup-wrench]: https://github.com/hexops/wrench?tab=readme-ov-file#run-your-own-ziglangorgdownload-mirror

After setting up a mirror, you can add it to this GitHub Action by opening a PR which adds it to the list in
[mirrors.json](https://github.com/mlugg/setup-zig/blob/main/mirrors.json).