zig_macos_m2_max_install

zig_macos_m2_max_install · GitHub

Personal notes building zig 0.12.0-dev.xxxx on an Macbook M2 Max

This probably works on all current Apple Silicon Macs, but you must check other models yourself. It should also work for newer Intel Macs, with one small but significant difference: Homebrew has a different default path.

20230926: Updated for macOS Sonoma, Homebrew-installed LLVM 17.01 and latest XCode Commandline Tools

20231001: Build zig binaries for both release and debug mode (with release mode as default)

20231212: Updated for Sonoma 14.2, Homebrew-installed LLVM 17.0.6 and latest XCode Commandline Tools

DO YOU REALLY NEED TO BUILD FROM SOURCE?

"First of all, 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 using the Homebrew package manager + cmake with a few Mac-specific flags. There may be better and less common methods, but this is what most Mac developers are likely to use.

MY TEST MACHINE

➜  ~ system_profiler SPHardwareDataType | grep "Chip:" | cut -c 13-30
system_profiler SPHardwareDataType | grep "Memory:" | cut -c 15-19
system_profiler SPHardwareDataType | grep " Total Number of Cores:" | cut -c 7-66

Apple M2 Max
96 GB
Total Number of Cores: 12 (8 performance and 4 efficiency)

➜  ~ sw_vers; clang --version
ProductName:		macOS
ProductVersion:		14.2
BuildVersion:		23C64
Homebrew clang version 17.0.6
Target: arm64-apple-darwin23.2.0
Thread model: posix
InstalledDir: /opt/homebrew/opt/llvm/bin

BUILD ENVIRONMENT

I use the latest major version of macOS (unless there is a specific reason not to). In general, I also use the latest minor version + any security update. The two previous major versions of macOS should work (but I don't test that).

The latest version of XCode Command Line Tools must be installed. They are part of the Apple XCode IDE, but can also be installed separately. Note! It should be possible to install zig without these tools. But I don't cover how to do that here.

Use Homebrew to install Mac-specific dependencies 'zlib' and 'zstd'. Then install LLVM 17.0.6 or later. Note! Don't allow brew to update to a new major LLVM version before zig is ready for that - your zig build will break! Tip: prevent brew from automatically updating llvm with the command 'brew pin llvm'.

> brew install zlib; brew install zstd; brew install llvm;

Put Homebrew-installed LLVM first in your path by adding this line 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! On Intel Macs, it should be "/usr/local/opt" instead of "/opt/homebrew/opt/".

GET THE LATEST ZIG SOURCE CODE AND PREPARE YOUR REPO

Get the latest source code from the zig Github repo. If you want to contribute to zig, consider creating 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. Then pull the latest code, create an empty build folder and clean both global and local zig cache.

> git pull
> rm -rf build; mkdir build; rm -rf ~/.cache/zig; rm -rf zig-cache

Some Mac-specific build flags are currently necessary: specify that you want a statically linked homebrew-installed LLVM and also add a special flag for the 'zstd' dependency. The make '-j9' parameter is optional but makes builds faster if you have enough CPU cores.

Zig itself can be built in different build modes, see https://github.com/ziglang/zig/wiki/Contributing#editing-source-code. To build a release mode version, add these flags:

'-DCMAKE_BUILD_TYPE=Release' build the zig binary in release mode.

'-DZIG_NO_LIB=ON' use existing 'lib' folder in the source tree (don't create a copy for the new binary)

Now build and install your release mode zig binary. This will take several minutes.

cd build; cmake .. -DCMAKE_PREFIX_PATH="$(brew --prefix llvm);$(brew --prefix zstd)" -DZIG_STATIC_LLVM=on -DZIG_NO_LIB=ON -DCMAKE_BUILD_TYPE=Release; make -j9; make install

Note that the build process is under active development. Using macOS and cmake, you can expect 46 build warnings + some linker warnings. A successful build should end similar to this:

... lots of details omitted

/Users/jonas/src/zig/zig/build/zig2.c:3072417:23: warning: incompatible pointer types passing 'uintptr_t *' (aka 'unsigned long *') to parameter of type 'uint64_t *' (aka 'unsigned long long *') [-Wincompatible-pointer-types]
 t5.f1 = zig_subo_u64(&t5.f0, t4, t0, UINT8_C(64));
                      ^~~~~~
/Users/jonas/src/zig/zig/stage1/zig.h:679:43: note: passing argument to parameter 'res' here
static inline bool zig_subo_u64(uint64_t *res, uint64_t lhs, uint64_t rhs, uint8_t bits) {
                                          ^
/Users/jonas/src/zig/zig/build/zig2.c:3370322:8: warning: incompatible pointer types assigning to 'const uint16_t (*)[16]' (aka 'const unsigned short (*)[16]') from 'const uint16_t *' (aka 'const unsigned short *') [-Wincompatible-pointer-types]
   t26 = t25.ptr;
       ^ ~~~~~~~
46 warnings generated.
[ 94%] Linking CXX executable zig2
ld: warning: ignoring duplicate libraries: '/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/libclangParse.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'
[ 94%] Built target zig2
[100%] Building stage3
Install the project...
-- Install configuration: "Release"

BUILD A DEBUG MODE ZIG BINARY

Now use your release mode zig to build a debug mode version of itself. This is useful for working on zig itself and digging deeper when debugging.

➜  build git:(master) stage3/bin/zig build -p stage4 -Dno-lib
➜ 

ADD ALIASES (optional but very convenient)

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.12.0-dev.1820+37458cc88
➜  ~ 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": "/Users/jonas/src/zig/zig/lib",
 "std_dir": "/Users/jonas/src/zig/zig/lib/std",
 "global_cache_dir": "/Users/jonas/.cache/zig",
 "version": "0.12.0-dev.1820+37458cc88",
 "target": "aarch64-macos.14.2...14.2-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,
  "CC": null,
  "NO_COLOR": null,
  "XDG_CACHE_HOME": null,
  "HOME": "/Users/jonas"
 }
}
➜  ~ dzig version
0.12.0-dev.1820+37458cc88
➜  ~ dzig env
{
 "zig_exe": "/Users/jonas/src/zig/zig/build/stage4/bin/zig",
 "lib_dir": "/Users/jonas/src/zig/zig/lib",
 "std_dir": "/Users/jonas/src/zig/zig/lib/std",
 "global_cache_dir": "/Users/jonas/.cache/zig",
 "version": "0.12.0-dev.1820+37458cc88",
 "target": "aarch64-macos.14.2...14.2-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,
  "CC": null,
  "NO_COLOR": null,
  "XDG_CACHE_HOME": null,
  "HOME": "/Users/jonas"
 }
}

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.

➜  build git:(master) zig build test-behavior -Dskip-non-native --summary all
Build Summary: 30/30 steps succeeded; 17995/19069 tests passed; 1074 skipped
test-behavior success

... detailed output omitted

Run this to see which native tests were skipped. Note! You should run these tests from your build folder.

➜  ~ cd src/zig/zig/build
➜  build git:(master) zig test ../test/behavior.zig -I../test

... details of skipped tests omitted

1804 passed; 103 skipped; 0 failed.

If you feel ambitious, check behavior tests for all platforms. This takes much longer. There is only one expected test failure. It has been present for a long time and may be a test artifact.

➜  build git:(master) zig build test-behavior

run test behavior-x86_64-macos-none-x86_64-Debug-selfhosted-no-lld: error: the following command terminated with signal 10 (expected exited with code 0):
/Users/jonas/src/zig/zig/zig-cache/o/af44f95a21214a10be85c8aa357eb9f2/test --listen=-
Build Summary: 63/96 steps succeeded; 31 skipped; 1 failed; 1809/1907 tests passed; 98 skipped
... detailed output omitted