GoKawiilThis page contains a curated list of recent changes to main branch Zig.
Also available as an RSS feed.
This page contains entries for the year 2026. Other years are available in the Devlog archive page.
June 25, 2026 New @bitCast Semantics and LLVM Backend Improvements Author: Matthew Lugg (Quite long devlog coming up, apologies—I got a little carried away with this one!) A few weeks ago, I began working on a branch implementing an improvement to the LLVM backend which had been planned for a long time. This ended up snowballing into a bigger change which implemented a few language proposals you might be interested to hear about. LLVM Backend Integer Lowering Zig has always lowered arbitrary bit-width integer types (e.g. u4 , i13 , u40 ) directly to LLVM IR’s bit-int types ( i4 , i13 , i40 ). However, we’ve known for a long time that this lowering is not optimal, because LLVM’s documented semantics for representing these types in memory are unnecessarily restrictive to the optimizer. Perhaps more importantly, because Clang never emits LLVM IR like this, these code paths in LLVM have never been properly tested, and so are poorly supported in practice—over the past few years, we have observed many instances of trivial optimizations being missed and even straight-up miscompilations. So, the original goal of the PR was to only use these bit-int types when manipulating values in SSA form, and to zero- or sign-extend them to ABI-sized types ( i8 , i16 , i32 , etc) when storing them in memory. This should be well-supported, not least because it matches how Clang lowers C’s _BitInt(N) ! That change was actually fairly straightforward, but I hit one issue which led me down a bit of a rabbit-hole. The Problem with @bitCast @bitCast is an interesting builtin. In the past, it was defined as being equivalent to the following sequence of operations: Take a pointer to the operand value
Cast it to a pointer to the destination type
Load from that pointer In other words, it was essentially syntax sugar for reinterpreting bytes of memory. However, over time, we diverged from this definition—for instance, it became allowed to use @bitCast to reinterpret a [3]u8 as a u24 , even though on most targets @sizeOf(u24) is greater than @sizeOf([3]u8) so the above definition would invoke Illegal Behavior. Up to now, the LLVM backend had implemented these underspecified semantics for the @bitCast builtin. However, because that definition involved reinterpreting memory, changing how we store integer types in memory ended up impacting the implementation of @bitCast , and introducing Illegal Behavior which led to crashes in the compiler test suite. The easiest solution to this would probably have been to implement logic in the LLVM backend to approximately match the old behavior. I instead opted for a better solution—implement a new definition of @bitCast . Redefining @bitCast In 2024, Jacob Young wrote up language proposal #19755 which aimed to solve the problems with @bitCast by precisely specifying a new set of semantics for it. This proposal was accepted shortly after it was submitted, and in fact, the semantics it details are already implemented by the self-hosted x86_64 backend! So to solve the LLVM backend’s problems, I didn’t necessarily need to match the old @bitCast semantics—instead, this seemed like a good time to finally get the new semantics implemented everywhere. As an aside, another advantage to doing this is that we could take advantage of the compiler’s Legalize pass, which takes difficult-to-lower operations and rewrites them in terms of simpler operations, so that compiler backends only need to support those simple operations. Legalize already had functionality, used by the self-hosted x86_64 backend, which converted complex @bitCast operations into simpler ones, and it could be easily adapted to aid the other compiler backends too (mainly the LLVM and C backends)—but only if they implemented the new semantics. Regardless, the point is, I set out on a side quest (which ended up being harder than the original quest) to implement these new semantics throughout the compiler. This includes not only the LLVM and C backends, but also comptime execution—after all, Zig allows you to do almost any operation at comptime, @bitCast included! Because the new semantics are meaningfully different from the old (more on this later), I also had to audit a lot of uses of @bitCast across the standard library, compiler, and supporting libraries (e.g. compiler_rt ). But after a few mostly-painless fixes for CI failures, I was able to finally get my PR green, and landed it in master yesterday (closing a good few issues in the process!). The New @bitCast Semantics Now that we’ve gotten through all of the background, it’s finally time for me to actually explain new @bitCast behavior. Instead of being based on reinterpreting bytes in memory like before, the builtin is now defined in terms of the bits which logically represent a type. Every type which supports @bitCast has a “logical bit layout”—a representation of that type as an ordered sequence of bits. For instance, u5 is composed of 5 logical bits, which we order from least-significant to most-significant. [2]u5 is composed of 10 logical bits—the 5 from the first element, followed by the 5 from the second element. The new definition of @bitCast is that it reinterprets the logical bits of one type as the logical bits of a different type. The simplest example is to take an unsigned integer, say a u8 , and convert it to a signed integer of the same size, in this case i8 . This operation does exactly what you’d expect—the bits are unchanged, and we just reinterpret the most-significant bit as a sign bit. Also unchanged are the semantics of @bitCast between an integer type and a packed struct / packed union type. The place where the new semantics differ from the old is when you get aggregate types (arrays and vectors) involved. Consider, for instance, bitcasting a [2]u8 to a u16 . Under the old semantics, the result of this operation depends on the target endian: on big-endian targets, the first array element became the 8 most significant bits, whereas on little-endian targets, the first array element became the 8 least significant bits. Under the new semantics, because we only care about logical bit representation (which is endian-agnostic), the operation behaves identically on every target: the first array element becomes the 8 least significant bits. As a general rule, the new semantics tend to match the behavior of the old semantics on little-endian targets. This definition also allows for some weirder operations, such as converting [2]u3 to @Vector(3, u2) : test "bitcast [2]u3 to @Vector(3, u2)" { const arr : [ 2 ] u3 = . { 0b001 , 0b011 } ; const vec : @Vector ( 3 , u2 ) = @bitCast ( arr ) ; try expect ( vec [ 0 ] == 0b01 ) ; try expect ( vec [ 1 ] == 0b10 ) ; try expect ( vec [ 2 ] == 0b01 ) ; } const expect = @import ( "std" ) . testing . expect ; This kind of operation isn’t very useful most of the time, but it’s there if you need it! For instance, perhaps you want to deconstruct an integer into a vector of individual bits to operate on—that can now be done by a @bitCast to @Vector(n, u1) . While doing all of this stuff, I also implemented a couple of smaller accepted proposals—I won’t detail them here, but you can take a look at the issues if you’re interested: Disallow @bitCast to/from vectors of pointers (#18936)
to/from vectors of pointers (#18936) Allow @bitCast on enums (part of #35602) Of course, all of these changed semantics will be explained in the 0.17.0 release notes (hopefully a bit more concisely than what I managed here!), and suggested migration steps outlined. LLVM Backend Performance On a final note, I just wanted to mention that the original motivation for this branch—changing how the LLVM backend lowers non-ABI integer types—was demonstrably successful at restoring missed optimizations. In fact, the Zig compiler itself—despite not making heavy use of arbitrary bit width integers internally!—saw around 5% performance improvements from the better optimization. This means you might have some minor runtime performance gains to look forward to in 0.17.0! Thanks for reading, I hope this was interesting to some of you. Happy hacking!
May 30, 2026 ELF Linker Improvements Author: Matthew Lugg I’ve spent the past few weeks working on our new ELF linker which debuted in Zig 0.16.0. At the time of the 0.16.0 release, this linker implementation was in its fairly early stages, and only really supported linking Zig-only code without any external libraries (even libc)—hence why it was (and still is) disabled by default (it can be enabled with -fnew-linker ). However, quite a lot of progress has been made since that initial release! Here’s a nice milestone—as of my latest PR, the new ELF linker is capable of building the self-hosted Zig compiler with LLVM and LLD libraries enabled, a task which requires quite a few features under the hood. [ mlugg @nebula master] $ [mlugg@nebula master] $ zig build -Dno-lib -Dnew-linker -Denable-llvm [mlugg@nebula master] $ [mlugg@nebula master] $ ./zig-out/bin/zig build-exe ~/hello.zig -fllvm -flld [mlugg@nebula master] $ ./hello Hello, World! [mlugg@nebula master] $ Of course, an ELF linker isn’t necessarily the most exciting thing in the world, which is why the headline feature of this new linker is its support for fast incremental compilation. After the recent enhancements, it is now possible (on x86_64 Linux) to perform incremental rebuilds while linking external libraries, C sources, etc—without any additional performance overhead! Here’s a clip of me trying it out on Andrew’s Tetris clone: A few silly changes to Andrew’s Tetris clone being built in around 30ms each. Oh, and fast incremental rebuilds also work nicely on the Zig compiler itself: [mlugg@nebula master]$ zig build -Dno-lib -Denable-llvm -fincremental --watch Build Summary: 4/4 steps succeeded install success └─ install zig success └─ compile exe zig Debug native success 36s Build Summary: 4/4 steps succeeded install success └─ install zig success └─ compile exe zig Debug native success 244ms Build Summary: 4/4 steps succeeded install success └─ install zig success └─ compile exe zig Debug native success 228ms Build Summary: 4/4 steps succeeded install success └─ install zig success └─ compile exe zig Debug native success 288ms Build Summary: 4/4 steps succeeded install success └─ install zig success └─ compile exe zig Debug native success 283ms The biggest missing feature of this linker implementation right now is that it still does not yet support generating DWARF debug information for Zig code—that’s definitely my next priority. But even without that support, it’s amazing just how useful instant rebuilds can be, for example in any situation where you’re doing a lot of print debugging. If you’re using the master branch of Zig and you’re on x86_64 Linux, consider trying out incremental compilation with the new ELF linker if it previously wasn’t working with your project! I expect many codebases to already work great with it, unlocking the ability to rebuild your project in milliseconds. Of course, if you come across any bugs, please do open an issue. And if you’re currently sticking to tagged releases of Zig, don’t worry—as Andrew mentioned in his last devlog, Zig 0.17.0 is just around the corner, so it won’t be long before you can try this too!
May 26, 2026 Build System Reworked Author: Andrew Kelley Big branch just landed: separate the maker process from the configurer process This devlog entry is essentially a preview of the upcoming release notes, but serves as an advanced notice to those who want to help test out the new features and provide feedback that will guide the Zig project moving forward. Before, build.zig files plus the build system implementation were all compiled into one bloated process, in Debug mode. After build.zig logic finished constructing a build graph in memory, the “build runner” code executed it. Now, build.zig files are compiled into a small process (the “configurer”) in debug mode. After this logic finishes constructing a build graph in memory, it is serialized to a binary configuration file. The parent zig build process is aware of this file and caches it for next time. While waiting for all that, it asynchronously compiles the build graph execution process (the “maker”) in release mode. Once the configuration file is available and the maker process is finished compiling, the maker process is executed, passing it the configuration file. The maker process only needs to be compiled once per zig version thanks to the global cache. The maker process then executes the build graph, which is contained within the serialized configuration file. The primary motivation of this change was to make zig build faster, in three ways: Only the user’s build.zig logic will be compiled with each change, rather than the entire build system along with it. This is starting to become more valuable now that we have introduced --watch , --fuzz and --webui . The build system can grow more features without making zig build take longer. Now the build system can skip rerunning the build.zig logic entirely when it knows nothing will change, for example if you add -freference-trace to your zig build command line, it now avoids re-running your build.zig logic redundantly, using the same configuration as last time. Now the process that actually executes the build graph is compiled with optimizations enabled. To demonstrate points 2 and 3, here is the difference between running zig build --help before and after: Benchmark 1 (34 runs): master/zig build -h measurement mean ± σ min … max outliers delta wall_time 150ms ± 5.52ms 145ms … 165ms 4 (12%) 0% peak_rss 84.8MB ± 275KB 84.2MB … 85.1MB 0 ( 0%) 0% cpu_cycles 593M ± 4.01M 588M … 608M 2 ( 6%) 0% instructions 995M ± 52.5K 995M … 995M 0 ( 0%) 0% cache_references 25.8M ± 165K 25.4M … 26.1M 0 ( 0%) 0% cache_misses 651K ± 20.1K 619K … 697K 0 ( 0%) 0% branch_misses 918K ± 7.44K 906K … 935K 0 ( 0%) 0% Benchmark 2 (348 runs): branch/zig build -h measurement mean ± σ min … max outliers delta wall_time 14.3ms ± 744us 13.2ms … 23.3ms 8 ( 2%) ⚡- 90.4% ± 0.4% peak_rss 78.5MB ± 562KB 77.1MB … 81.4MB 7 ( 2%) ⚡- 7.4% ± 0.2% cpu_cycles 24.1M ± 821K 22.8M … 27.1M 3 ( 1%) ⚡- 95.9% ± 0.1% instructions 43.7M ± 23.8K 43.7M … 43.8M 56 (16%) ⚡- 95.6% ± 0.0% cache_references 1.46M ± 14.6K 1.40M … 1.50M 19 ( 5%) ⚡- 94.3% ± 0.1% cache_misses 142K ± 4.87K 127K … 157K 2 ( 1%) ⚡- 78.1% ± 0.4% branch_misses 126K ± 1.37K 120K … 129K 12 ( 3%) ⚡- 86.3% ± 0.1% It’s dramatic because before, build.zig logic was being executed with each zig build command, but now, the build system uses the cached, serialized configuration instead. Aside from performance, I expect third-party tooling such as ZLS to benefit from consuming the serialized configuration file rather than maintaining a fork of the build runner. This changeset heavily reworks the internal mechanism of the zig build system, however, it is mostly non-breaking from an API perspective, with the exceptions noted in the PR linked above. For most people I’m guessing this is the main breaking change they’ll hit: if ( b . args ) | args | { run_cmd . addArgs ( args ) ; } ⬇️ run_cmd . addPassthruArgs ( ) ; This removes a capability from build scripts since they can no longer observe those arguments. In exchange, it means that when changing those arguments, build scripts no longer must be rebuilt from source. If you’re someone who wants to influence the direction of Zig, this is a good time to upgrade your projects to the development version and try out these changes. We’ll be releasing 0.17.0 within a couple weeks from now. However, if you don’t have time, and you find out that 0.17.0 broke your build, don’t worry, there will be plenty of opportunity to get fixes in for the 0.17.1 tag as well.
April 08, 2026 Incremental compilation with LLVM Author: Matthew Lugg I’ve been spending a bit of time working on personal projects after merging my type resolution changes last month, but I did find the time recently to make some improvements to the LLVM codegen backend. This involved a few different enhancements with various goals, but one nice user-facing change was that I managed to get incremental compilation working with the LLVM backend. Sadly this can’t do anything to speed up the dreaded LLVM Emit Object: that time is entirely down to LLVM. However, what incremental compilation does help with is minimizing the time spent in the actual Zig compiler code, which means that if your code has compile errors (so “LLVM Emit Object” will be skipped), you’ll usually get those errors very quickly. (Of course, it does still give you a slight speed-up in successful builds too.) This support is available in master branch builds right now, and will be in the 0.16.0 release (which we’ll be tagging very soon). For anyone who still hasn’t tried it, especially if you’re using Zig’s master branch, please do try out incremental compilation by passing -fincremental --watch to zig build ! The Zig core team have benefited from incremental compilation in our workflows for a good year now, and we’re also hearing good things from users. The feature is relatively stable at this point, and people are often surprised how much time they can save just by getting up-to-date compile errors in milliseconds rather than seconds. I haven’t really personally used incremental compilation with the LLVM backend, but all of the incremental test coverage in CI is now enabled for the LLVM backend, and I’ve had positive feedback from users, so it’s definitely worth giving a shot. As always, if you encounter bugs in incremental compilation, please report them if you can! Thank you, and I hope you find this useful :)
... continue reading