Personal notes building zig 0.14.0-dev.xxxx on Macbook M3 Max
This probably works on all current Apple Silicon Macs, but you must check other models yourself. Newer Intel Macs are also likely to work, with one significant difference: homebrew has a different default path.
20240319 Now on M3 Max. Sonoma 14.4.1, latest XCode Commandline Tools, homebrew-installed LLVM 17.0.6
20240420 Sonoma 14.4.1. latest XCode Commandline Tools, homebrew-installed LLVM 17.0.6
20240423 Sonoma 14.4.1. latest XCode Commandline Tools, homebrew-installed LLVM 17.0.6
20240508 Sonoma 14.4.1. latest XCode Commandline Tools, homebrew-installed LLVM LLVM 18.1.5 (formula 'llvm')
20240514 Sonoma 14.5 latest XCode Commandline Tools, homebrew-installed LLVM 18.1.5 (formula 'llvm')
20240531 Sonoma 14.5 latest XCode Commandline Tools, homebrew-installed LLVM 18.1.6 (formula 'llvm')
20240607 Sonoma 14.5 latest XCode Commandline Tools, homebrew-installed LLVM 18.1.6 (formula 'llvm@18')
20240726 Sonoma 14.5 latest XCode Commandline Tools, homebrew-installed LLVM 18.1.8 (formula 'llvm@18')
20240802 Sonoma 14.6 latest XCode Commandline Tools, homebrew-installed LLVM 18.1.8 (formula 'llvm@18')
20240819 Sonoma 14.6.1 latest XCode Commandline Tools, homebrew-installed LLVM 18.1.8 (formula 'llvm@18')
20240917 Sequoia 15.0 latest XCode Commandline Tools, homebrew-installed LLVM 18.1.8 (formula 'llvm@18')
20240926 Sequoia 15.0 latest XCode Commandline Tools, homebrew-installed LLVM 19.1.0 (formula 'llvm@19')
20241019 Sequoia 15.0.1 latest XCode Commandline Tools, homebrew-installed LLVM 19.1.2 (formula 'llvm')
20241028 Sequoia 15.1 latest XCode Commandline Tools, homebrew-installed LLVM 19.1.2 (formula 'llvm@19')
20241102 Sequoia 15.1 latest XCode Commandline Tools, homebrew-installed LLVM 19.1.3 (formula 'llvm@19')
DO YOU REALLY NEED TO BUILD FROM SOURCE?
Perhaps all you need is a particular version of zig? Many apps require a slightly older zig version, read more about why here. In that case, simply download the right binary yourself or use https://github.com/marler8997/zigup.
Ziglang.org wiki:
"... if your goal is to install a specific version of Zig, you can find pre-built tarballs on the download page. You could also try installing Zig from a package manager. Finally, there is zig-bootstrap to cross-compile an installation of Zig from source for any target. When using zig-bootstrap, be sure to check out the git tag corresponding to the version you want to build, as master branch is not kept in any coherent state."
https://github.com/ziglang/zig/wiki/Building-Zig-From-Source
https://github.com/ziglang/zig/wiki/Troubleshooting-Build-Issues.
BUILDING FROM SOURCE ON A MAC
Below, I describe how to build zig master using the Homebrew package manager + cmake with a few Mac-specific tweaks. There may be better and less common methods that work. But Mac developers are more likely to be familiar with this way.
I used a few things from https://github.com/ziglang/zig/wiki/Contributing. Note that on macOS cmake actually seems to be slightly faster than ninja.
MY CURRENT TEST MACHINE
➜ system_profiler SPHardwareDataType | grep "Chip:" | cut -c 13-30; sw_vers; clang --version
Apple M3 Max
ProductName: macOS
ProductVersion: 15.1
BuildVersion: 24B83
Homebrew clang version 19.1.3
Target: arm64-apple-darwin24.1.0
Thread model: posix
InstalledDir: /opt/homebrew/Cellar/llvm/19.1.3/bin
Configuration file: /opt/homebrew/etc/clang/arm64-apple-darwin24.cfg
BUILD ENVIRONMENT
I use the latest major version of macOS (unless I have specific reasons not to). In general, I try to keep up with the latest minor version + security updates. For zig, the two previous major versions of macOS are supposed to work.
Below, I assume that the latest version of XCode Command Line Tools is installed. It is included with Apple XCode and can also be installed separately. Building zig without this might be possible. But I prefer to test the most common configuration.
Use Homebrew to install LLVM, cmake + some Mac-specific dependencies: 'zlib', 'zstd' and 'lld'. If you need it, homebrew allows multiple LLVM versions to be installed side-by-side: 'llvm@17', 'llvm@18' etc.
Zig master currently expects LLVM 19 to be installed. Using the wrong major LLVM version will break your build!
Unfortunately, Homebrew LLVM currently has issues with the 'zstd' library (see ziglang/zig#20806). To build zig, use the fix below to link it directly. Until there is a proper upstream solution, this fix should be applied every time there has been a minor version update of Homebrew LLVM.
ln "/opt/homebrew/opt/zstd/lib/libzstd.a" "/opt/homebrew/opt/llvm/lib/libzstd.a"
brew install cmake; brew install zlib; brew install zstd; brew install llvm@19; brew install lld
Put Homebrew-installed LLVM first in your path by adding the line below to your shell profile (probably '~/.zshrc'). Remember to restart your shell or source the profile to make LLVM available!
export PATH=/opt/homebrew/opt/llvm/bin:$PATH
Note! The homebrew path for Intel Macs is "/usr/local/opt", NOT "/opt/homebrew/opt/".
Finally restart your terminal and check that you don't have any configuration issues with homebrew
➜ ~ brew doctor
Your system is ready to brew.
GET THE LATEST ZIG SOURCE CODE AND PREPARE YOUR REPO
Get the latest source code from the zig Github repo. If you plan on contributing to zig itself, create your own fork.
> git clone [email protected]:ziglang/zig.git
> cd zig
BUILD A RELEASE MODE ZIG BINARY
Make sure you are in the folder where you cloned Zig. Pull the latest code. Clean both global and local zig cache. Create an empty build folder. Note that zig master has changed the default local cache: it's now '.zig-cache', NOT 'zig-cache'.
git pull
rm -rf ~/.cache/zig; rm -rf .zig-cache; rm -rf zig-out; rm -rf build; mkdir build
Setting the build flag -DZIG_STATIC_LLVM=on specifies that you want a statically linked homebrew-installed LLVM. This is currently necessary to build on macOS.
Using -DZIG_NO_LIB=ON is optional but I find it convenient (it prevents creating an extra copy of the library source). Adding the make '-j' parameter is also optional but makes builds faster (use the number of performance CPU cores on your machine).
Now build and install a release mode zig binary. This takes several minutes, even on a fast machine.
cd build; cmake .. -DCMAKE_PREFIX_PATH="$(brew --prefix llvm)" -DZIG_STATIC_LLVM=on -DZIG_NO_LIB=ON -DCMAKE_BUILD_TYPE=Release; make -j12; make install
Note that the build process is under active development. Using macOS and cmake, you can expect linker warnings + 58 build warnings. A successful build ends similar to this:
... lots of output omitted
/Users/jonas/src/zig/zig/build/zig2.c:3679508:25: warning: incompatible pointer types passing 'uintptr_t *' (aka 'unsigned long *') to parameter of type 'uint64_t *' (aka 'unsigned long long *') [-Wincompatible-pointer-types]
3679508 | t15.f1 = zig_addo_u64(&t15.f0, t3, t2, UINT8_C(64));
| ^~~~~~~
/Users/jonas/src/zig/zig/stage1/zig.h:631:43: note: passing argument to parameter 'res' here
631 | static inline bool zig_addo_u64(uint64_t *res, uint64_t lhs, uint64_t rhs, uint8_t bits) {
| ^
58 warnings generated.
[ 94%] Linking CXX executable zig2
ld: warning: ignoring duplicate libraries: '/opt/homebrew/opt/llvm/lib/libclangAPINotes.a', '/opt/homebrew/opt/llvm/lib/libclangARCMigrate.a', '/opt/homebrew/opt/llvm/lib/libclangAST.a', '/opt/homebrew/opt/llvm/lib/libclangASTMatchers.a', '/opt/homebrew/opt/llvm/lib/libclangAnalysis.a', '/opt/homebrew/opt/llvm/lib/libclangBasic.a', '/opt/homebrew/opt/llvm/lib/libclangCrossTU.a', '/opt/homebrew/opt/llvm/lib/libclangEdit.a', '/opt/homebrew/opt/llvm/lib/libclangExtractAPI.a', '/opt/homebrew/opt/llvm/lib/libclangIndex.a', '/opt/homebrew/opt/llvm/lib/libclangInstallAPI.a', '/opt/homebrew/opt/llvm/lib/libclangLex.a', '/opt/homebrew/opt/llvm/lib/libclangParse.a', '/opt/homebrew/opt/llvm/lib/libclangRewrite.a', '/opt/homebrew/opt/llvm/lib/libclangRewriteFrontend.a', '/opt/homebrew/opt/llvm/lib/libclangSema.a', '/opt/homebrew/opt/llvm/lib/libclangStaticAnalyzerCheckers.a', '/opt/homebrew/opt/llvm/lib/libclangStaticAnalyzerCore.a', '/opt/homebrew/opt/llvm/lib/libclangStaticAnalyzerFrontend.a', '/opt/homebrew/opt/llvm/lib/libclangSupport.a', '/opt/homebrew/opt/llvm/lib/libclangToolingCore.a'
[ 94%] Built target zig2
[100%] Building stage3
[100%] Built target stage3
[ 36%] Built target zigcpp
[ 47%] Built target zig-wasm2c
[ 68%] Built target zig1
[ 94%] Built target zig2
[100%] Built target stage3
Install the project...
-- Install configuration: "Release"
BUILD A DEBUG MODE ZIG BINARY
Use your release mode zig to build a debug mode version of itself. This is useful for working on zig itself and/or digging deeper when debugging.
➜ stage3/bin/zig build -p stage4 -Dno-lib
➜
ADD ALIASES (optional but convenient)
Some zig developers use https://github.com/marler8997/zigup to deal with multiple zig versions. Personally, I find it simpler to keep a handful of aliases in my profile for projects pinned to older zig versions.
Change the lines below to point at your build folder and put them in '.zshrc'. Absolute path is required, last part must be 'build/stage3/bin/zig' or 'build/stage4/bin/zig'. Feel free to use whatever aliases you want.
alias zig=/Users/jonas/src/zig/zig/build/stage3/bin/zig
alias dzig=/Users/jonas/src/zig/zig/build/stage4/bin/zig
Remember to restart your shell (or source the profile) to make aliases available.
CHECK THAT EVERYTHING WORKS
Open a new terminal and verify that your aliases work.
➜ ~ zig version
0.14.0-dev.2126+e27b4647d
➜ ~ which zig
zig: aliased to /Users/jonas/src/zig/zig/build/stage3/bin/zig
➜ ~ zig env
{
"zig_exe": "/Users/jonas/src/zig/zig/build/stage3/bin/zig",
"lib_dir": "src/zig/zig/lib",
"std_dir": "src/zig/zig/lib/std",
"global_cache_dir": "/Users/jonas/.cache/zig",
"version": "0.14.0-dev.2126+e27b4647d",
"target": "aarch64-macos.15.1...15.1-none",
"env": {
"ZIG_GLOBAL_CACHE_DIR": null,
"ZIG_LOCAL_CACHE_DIR": null,
"ZIG_LIB_DIR": null,
"ZIG_LIBC": null,
"ZIG_BUILD_RUNNER": null,
"ZIG_VERBOSE_LINK": null,
"ZIG_VERBOSE_CC": null,
"ZIG_BTRFS_WORKAROUND": null,
"ZIG_DEBUG_CMD": null,
"CC": null,
"NO_COLOR": null,
"CLICOLOR_FORCE": null,
"XDG_CACHE_HOME": null,
"HOME": "/Users/jonas"
}
}
➜ ~ dzig version
0.14.0-dev.2126+e27b4647d
➜ ~ which dzig
dzig: aliased to /Users/jonas/src/zig/zig/build/stage4/bin/zig
You can read more about testing here: https://github.com/ziglang/zig/wiki/Contributing#testing Try running native behavior tests as a simple sanity check. There should be no errors.
Note! You should run these tests from your build folder.
➜ build git:(master) zig build test-behavior -Dskip-non-native --summary all
Build Summary: 25/25 steps succeeded; 14950/15768 tests passed; 818 skipped
test-behavior success
... detailed output omitted
Run this to see which native tests were skipped.
➜ ~ cd src/zig/zig/build
➜ build git:(master) zig test ../test/behavior.zig -I../test
... details of skipped tests omitted
1869 passed; 102 skipped; 0 failed.
If you feel ambitious, check behavior tests for all platforms. This takes much longer. There are currently no expected errors.
➜ build git:(master) zig build test-behavior
➜ build git:(master)
Update: I currently build both release and debug versions. My default for normal use is the release version.