Nominated Zig versions

Periodically we nominate a new Zig nightly version which all Mach projects target and use.

We encourage others to adopt the same Zig version Mach uses, since Zig packages which target latest nightly (or the latest stable release) will very often be incompatible otherwise.

Why nominated Zig versions, instead of nightly or stable?

TL;DR: it’s a sweetspot between stable and nightly.

Stable releases occur just once or twice per year, nominated Zig versions occur several times per year - but not every day like nightly.

Stable releases of Zig are few and far between, perhaps once or twice per year, making it challenging to provide feedback on the latest-and-greatest APIs or benefit from the wins that are being made in main because Zig development happens so rapidly.

Nightly Zig is the opposite, but is an always moving target. When only you work with your code, you depend on nobody, and nobody depends on you, then you can update at your leisure and nightly is managable. But with many projects depending on one another, it’s very challenging to ensure your code is compatible with others’ because everyone is working on their own personal update schedule.

Mach’s nominated Zig versions provide a different set of tradeoffs, a middleground between the two extremes above: benefit from the changes in nightly Zig 2-3x faster than you would using stable, and suffer less from the incompatibility consequences of using nightly.

Schedule

All events target the 4th day of the month, but may slip if we’re unable to complete the event by then.

Over time, we may adjust this schedule somewhat as we learn more (it is not set in stone.)

Process

During months where a Zig version is nominated, we:

• Begin the nomination process (ideally on the 1st-4th of the month)
• Update the Nomination history section below with the new nightly Zig version we’re nominating.
• Begin the time-consuming process of following this GitHub checklist
  • Updating 40+ repositories Zig code, CI pipelines, build.zig.zon files, testing using the new Zig version, etc.
  • Doing updates in a specific order, so that dependencies are also updated to use the new Zig version
• Typically, a show-stopping bug does not occur. But if it does..
  • We may have to fix the issue e.g. upstream in Zig if we can’t workaround it
  • We’ll need to wait for it to be merged, and for Zig nightly builds to contain the fix
  • We’ll update the existing Nomination history entry to point to the new version (days may have passed, so this could include other breaking changes)
  • Re-roll! Effectively begin this whole process from the beginning.
• Once everything looks good, the new Zig version is working with Mach, we declare success - the GitHub issue is closed, and an announcement is made in the #progress channel of Discord.
• If after we declare success you find a show-stopping bug in your own projects that needs to be fixed upstream in Zig, you’ll have to use the older version until the next scheduled nominated version update.

Machine-readable version history

https://machengine.org/zig/index.json provides a machine-readable version history. It is a strict superset of https://ziglang.org/download/index.json - but updated less frequently, and with Mach versions added. A few types of Mach versions are added:

• mach-latest -> always the latest nominated Zig version.
• 2024.1.0-mach-wip -> -wip signifies that we are in the process of nominating this version, it has not been confirmed working with Mach yet.
• 2024.1.0-mach -> specific nominated versions.
• 0.3.0-mach -> an alias for the nominated Zig version that was used at the time of Mach v0.3 release.

What if we had used stable zig in the past?

Periodically, the question comes up: why not just use stable Zig versions? The best way to answer this, and our own gauge for answering this, is to look at how this would’ve affected us in the past.

• Between Zig 0.13 and 0.14 (not yet released):
  • We were able to identify a linker regression which prevented Mach from building/linking at all on macOS. This regression likely only affected Mach, as most projects do not use Zig ObjC bindings. If we hadn’t been able to identify this regression and give feedback to the Zig core team (who thankfully was able to fix it quickly!) then we may not have been able to upgrade to Zig 0.14 while keeping macOS support.
• Between Zig 0.12 and 0.13 (1.5 months):
  • We were able to identify a linker regression which prevented using prebuilt WebGPU binaries on macOS, exactly one day after the 0.12 release. Again, this regression likely primarily affected Mach - so if we had been using stable Zig, we’d need to hope it got fixed in 0.13 which was a short development cycle - or wait ~10 months for 0.14 / regress our macOS support.
• Between Zig 0.11 and 0.12 (8.5 months)
  • We were able to provide early feedback on the package manager and get various bugs/issues with it fixed for our use cases, being probably the earliest / most serious adopter of it. If we had not done this, we would’ve had no choice but to maintain our pre-package-manager dependency management system until Zig 0.13 was released ~10 months later.
• Between Zig 0.10 and 0.11 (9 months)
  • Early package manager feedback.

Nominated Zig history

2024.10.0-mach

Zig 2024.10.0-mach and 0.14.0-dev.1911+3bf89f55c are identical.

Install it using zigup:

zigup 0.14.0-dev.1911+3bf89f55c

Or download it using our pkg.machengine.org mirror:

Installation: Download, extract, and place on your system $PATH. Ensure zig version reports the right version.

Signatures: .minisig Download signatures can be retrieved from ziglang.org for all downloads.

Tips on upgrading your code

2024.5.0-mach

Zig 2024.5.0-mach and 0.13.0-dev.351+64ef45eb0 are identical.

Install it using zigup:

zigup 0.13.0-dev.351+64ef45eb0

Or download it using our pkg.machengine.org mirror:

Installation: Download, extract, and place on your system $PATH. Ensure zig version reports the right version.

Signatures: .minisig Download signatures can be retrieved from ziglang.org for all downloads.

Tips on upgrading your code

2024.3.0-mach

Zig 2024.3.0-mach and 0.12.0-dev.3180+83e578a18 are identical.

Install it using zigup:

zigup 0.12.0-dev.3180+83e578a18

Or download it using our pkg.machengine.org mirror:

Installation: Download, extract, and place on your system $PATH. Ensure zig version reports the right version.

Signatures: .minisig Download signatures can be retrieved from ziglang.org for all downloads.

Tips on upgrading your code

2024.1.0-mach

Zig 2024.1.0-mach and 0.12.0-dev.2063+804cee3b9 are identical.

Note: The first nominated version ever, this was out-of-band with the schedule due to it.

Install it using zigup:

zigup 0.12.0-dev.2063+804cee3b9

Or download it using our pkg.machengine.org mirror:

Installation: Download, extract, and place on your system $PATH. Ensure zig version reports the right version.

Signatures: .minisig Download signatures can be retrieved from ziglang.org for all downloads.

Tips on upgrading your code