Macos on Charlie Chiang's blog

Bundling macOS Dynamic Libraries

Mon, 08 Jun 2026 12:25:00 +0800

I recently tried to build QEMU on macOS and make the result portable enough that it could still run after uninstalling the Homebrew packages used during the build, or I can move the whole QEMU directory to another machine. I don’t want the Homebrew build because it installs too many dependencies on the system, and I want a more self-contained bundle, not a system-wide installation.

The short version: fully static linking on macOS is not really the right target. macOS binaries still dynamically link against Apple system libraries such as libSystem. But for tools like QEMU, what I really wanted was not a “pure static binary”; I wanted a self-contained directory like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


_qemu-11.0.1/
├── bin/
│ ├── qemu-img
│ ├── qemu-system-x86_64
│ └── ...
└── lib/
 ├── libglib-2.0.0.dylib
 ├── libgobject-2.0.0.dylib
 ├── libintl.8.dylib
 ├── libpcre2-8.0.dylib
 └── ...

The binaries in bin/ should load their non-system dependencies from ../lib (note that it’s relative, not absolute, so it will work even if the whole directory is moved), instead of from /opt/homebrew.

This post records the process, using QEMU as the example.

The original problem

I built QEMU roughly like this:

1
2
3
4
5
6


# You should refer to https://wiki.qemu.org/Hosts/Mac for the latest build instructions. This is just an example.
brew install libffi gettext glib pkg-config zstd # may not be the exact set of dependencies you need

./configure --prefix="$HOME/bin/_qemu-11.0.1"
make -j"$(sysctl -n hw.ncpu)"
make install

The build worked. But after uninstalling some Homebrew dependencies, running qemu-img failed:

1
2
3
4


dyld[82783]: Library not loaded: /opt/homebrew/opt/glib/lib/libglib-2.0.0.dylib
 Referenced from: /Users/charlie/bin/_qemu-11.0.1/bin/qemu-img
 Reason: tried: '/opt/homebrew/opt/glib/lib/libglib-2.0.0.dylib' (no such file)
zsh: abort qemu-img

This means the installed QEMU binary still contains an absolute dependency path:

1

/opt/homebrew/opt/glib/lib/libglib-2.0.0.dylib

We can confirm that with:

1

otool -L "$PREFIX/bin/qemu-img"

Example output:

1
2
3
4
5


qemu-img:
 /opt/homebrew/opt/glib/lib/libglib-2.0.0.dylib (compatibility version 8801.0.0, current version 8801.0.0)
 /opt/homebrew/opt/zstd/lib/libzstd.1.dylib (compatibility version 1.0.0, current version 1.5.7)
 /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1351.0.0)
 ...

The /usr/lib and /System/Library entries are fine. They are macOS system libraries. The /opt/homebrew/... entries are the ones that make the binary depend on my local Homebrew installation.

Why not just build QEMU fully static?

On Linux, the natural thought is “just build a static binary”.

On macOS, that is not usually how things work. macOS does not support the same style of fully static userland binary that Linux users often expect. You can try to statically link some third-party libraries, but the final program will still dynamically link to Apple system libraries.

So the practical goal is:

Bundle third-party .dylib dependencies next to the program, and rewrite Mach-O load commands so the binary loads those local copies.

This is similar in spirit to what many .app bundles do, but here I wanted a plain CLI directory layout.

The tools involved

macOS Mach-O binaries can be inspected and patched with these tools:

1
2
3
4


otool -L <file>
install_name_tool -change <old> <new> <file>
install_name_tool -id <new-id> <dylib>
install_name_tool -add_rpath <rpath> <file>

otool -L shows dynamic library load commands.

For example:

1

otool -L "$PREFIX/bin/qemu-img"

might show:

1
2
3
4
5


qemu-img:
 /opt/homebrew/opt/glib/lib/libglib-2.0.0.dylib (compatibility version 8801.0.0, current version 8801.0.0)
 /opt/homebrew/opt/zstd/lib/libzstd.1.dylib (compatibility version 1.0.0, current version 1.5.7)
 /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1351.0.0)
 ...

Those can be rewritten with:

1
2
3
4


install_name_tool -change \
 /opt/homebrew/opt/glib/lib/libglib-2.0.0.dylib \
 '@executable_path/../lib/libglib-2.0.0.dylib' \
 "$PREFIX/bin/qemu-img"

@executable_path means “the directory containing the executable being launched”.

So it will try to find libglib-2.0.0.dylib in ../lib/ relative to the executable, no longer looking in /opt/homebrew.

First attempt: patch direct dependencies only

My first attempt was simple:

1
2
3
4
5


otool -L "$PREFIX"/bin/* \
 | grep /opt/homebrew \
 | sort \
 | uniq \
 | awk '{print $1}'

This found direct Homebrew dependencies used by QEMU binaries, such as:

1
2
3
4
5


/opt/homebrew/opt/glib/lib/libgio-2.0.0.dylib
/opt/homebrew/opt/glib/lib/libglib-2.0.0.dylib
/opt/homebrew/opt/glib/lib/libgmodule-2.0.0.dylib
/opt/homebrew/opt/glib/lib/libgobject-2.0.0.dylib
/opt/homebrew/opt/zstd/lib/libzstd.1.dylib

Then I copied those libraries into $PREFIX/lib and patched the binaries.

This fixed some errors, but not all of them.

Running qemu-img then failed with a different error:

1
2


dyld[97126]: Library not loaded: /opt/homebrew/opt/gettext/lib/libintl.8.dylib
 Referenced from: /Users/charlie/bin/_qemu-11.0.1/lib/libglib-2.0.0.dylib

So I realized that it is not enough to patch only the binaries. The copied .dylib files have their own dependencies too.

In this case:

1
2
3


qemu-img
 -> libglib-2.0.0.dylib
 -> libintl.8.dylib

libintl.8.dylib was not directly referenced by qemu-img. It was a transitive dependency of libglib.

The correct model

The dependency graph looks like this:

1
2
3
4
5
6
7


bin/qemu-img
 -> /opt/homebrew/opt/glib/lib/libglib-2.0.0.dylib
 -> /opt/homebrew/opt/zstd/lib/libzstd.1.dylib

lib/libglib-2.0.0.dylib
 -> /opt/homebrew/opt/gettext/lib/libintl.8.dylib
 -> /opt/homebrew/opt/pcre2/lib/libpcre2-8.0.dylib

So the bundling process must be recursive:

Scan Mach-O files in bin/.
Find its /opt/homebrew dependencies.
Copy those .dylib files into lib/.
Patch the binaries to refer to the bundled copies (../lib).
Scan the copied .dylib files.
Copy and patch their dependencies too.
Repeat until no /opt/homebrew dependencies remain.

Which paths should be used?

For executables in bin/, I use:

1

@executable_path/../lib/libfoo.dylib

For dylibs inside lib/, I use:

1

@loader_path/libfoo.dylib

@executable_path is relative to the main executable being launched.
@loader_path is relative to the Mach-O file that is doing the loading. For dependencies between dylibs, this is what we want:
1 2

lib/libglib-2.0.0.dylib -> @loader_path/libintl.8.dylib

Since both files are in the same lib/ directory, this resolves correctly.

The final bundling script

I ended up writing a small Python script called macho-bundle-deps. You can find it here: https://github.com/charlie0129/dotfiles/blob/f15791054e517f6b5afc892312f1db73f331d475/bin/darwin/macho-bundle-deps. This is a permanent link to a specific commit, so you may want to check the latest version in the repository.

Usage:

1
2
3
4
5
6


PREFIX="$HOME/bin/_qemu-11.0.1"

macho-bundle-deps \
 --lib-dir "$PREFIX/lib" \
 --prefix /opt/homebrew \
 "$PREFIX"/bin

Or, from inside the QEMU prefix:

1
2
3


cd "$HOME/bin/_qemu-11.0.1"

macho-bundle-deps --lib-dir lib bin

The script does the following:

finds Mach-O files from the input paths
scans their dependencies with otool -L
copies matching dependencies into --lib-dir
patches executable dependencies to @executable_path/../lib/...
patches bundled dylib dependencies to @loader_path/...
patches copied dylib IDs with install_name_tool -id
recursively processes newly copied dylibs
reports an error if matching absolute dependency paths remain

Verifying the result

After running the bundler, I verify that no Homebrew paths remain:

1

otool -L "$PREFIX"/bin/* "$PREFIX"/lib/*.dylib | grep /opt/homebrew

Now I can uninstall the dependencies from Homebrew, and the bundled QEMU still works:

1
2


brew uninstall libffi gettext glib
qemu-img --help

Notes and limitations

This is not the same as producing a fully static binary.

The result still depends on macOS system libraries, which is normal:

1
2


/usr/lib/libSystem.B.dylib
/System/Library/Frameworks/...

It also does not magically make a binary portable across all macOS versions or CPU architectures. A binary built on Apple Silicon is still an arm64 Mach-O binary unless built otherwise.

This approach is mainly useful for making a local CLI tool directory self-contained with respect to Homebrew dependencies.

Why copying symlinks should be avoided

Homebrew often has dylib symlinks like:

1

libintl.dylib -> libintl.8.dylib

When bundling, prefer copying the symlink target, not the symlink itself.

In shell, that means:

1

cp -L source.dylib "$PREFIX/lib/"

In Python, shutil.copy2(..., follow_symlinks=True) does the same thing.

This avoids ending up with a bundled symlink pointing to a non-existent file.

Final layout

After bundling, the QEMU directory looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


_qemu-11.0.1/
├── bin/
│ ├── qemu-img
│ ├── qemu-io
│ ├── qemu-nbd
│ ├── qemu-system-aarch64
│ ├── qemu-system-x86_64
│ └── ...
└── lib/
 ├── libffi.8.dylib
 ├── libgio-2.0.0.dylib
 ├── libglib-2.0.0.dylib
 ├── libgmodule-2.0.0.dylib
 ├── libgobject-2.0.0.dylib
 ├── libintl.8.dylib
 ├── libpcre2-8.0.dylib
 └── libzstd.1.dylib

Now qemu-img no longer cares whether Homebrew’s glib, gettext, pcre2, or zstd packages are installed.

Conclusion

The main lesson is that macOS dependency bundling is graph traversal, not a one-shot patch.

Patching only the top-level binaries is not enough. You also need to patch the dylibs that you copied, and then patch the dylibs that those dylibs depend on.

The final strategy is:

1

scan -> copy -> patch -> scan copied dylibs -> repeat

For executables:

1
2


/opt/homebrew/.../libfoo.dylib
 -> @executable_path/../lib/libfoo.dylib

For bundled dylibs:

1
2


/opt/homebrew/.../libbar.dylib
 -> @loader_path/libbar.dylib

And for the dylib’s own install name:

1
2


/opt/homebrew/.../libfoo.dylib
 -> @loader_path/libfoo.dylib

Fake macOS Version Detected by Homebrew

Tue, 08 Oct 2024 22:08:00 +0800

Background

One particular issue that I encountered when I tried to install some software using Homebrew on my Mac is that Homebrew deprecates support for older macOS versions just like Apple do. Once a macOS version is deprecated, Homebrew will not provide bottles (precompiled binaries) for that version. This means that you have to compile the software from source, which is extremely time-consuming and sometimes error-prone. Imagine installing shell-check will require to build ghc from source, which takes hours, and then use ghc to build shell-check from source. This is not a good experience.

Solution

Pin homebrew/core to an older version

One way to work around this issue is to use a older version of the homebrew/core tap, such that the bottles are still available for the macOS version you are using because they are built when your macOS version is supported. The downside is that you will be using outdated software. If this is not an issue for you then congratulations. You can achieve this by running the following command:

1
2
3


$ brew tap homebrew/core
$ cd $(brew --repo homebrew/core)
$ git reset --hard <commit-hash>

Make sure you disable the auto-update of Homebrew so that it does not update the homebrew/core tap to the latest version. You can do this by running the following command:

1

$ echo 'export HOMEBREW_NO_AUTO_UPDATE=1' >> ~/.zshrc

Fake macOS version

Another way is to fake the macOS version that Homebrew detects. This way, Homebrew will provide bottles for the macOS version you are faking. Most software will work and you will be using the latest software. However, this may not work for all software as some software may have dependencies that are not available for the macOS version you are faking. You can achieve this by running the following command:

1
2


$ export HOMEBREW_FAKE_MACOS=13.0 # Choose a macOS version that is supported by Homebrew and close to your macOS version
$ brew install xxx

Explanation

Homebrew actually has an private undocumented API that allows you to fake the macOS version. https://github.com/Homebrew/brew/blob/a3d8f4e0e4a22da9990d59cca70bec1e7be726cf/Library/Homebrew/os/mac.rb#L41

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# This can be compared to numerics, strings, or symbols
# using the standard Ruby Comparable methods.
#
# @api internal
sig { returns(MacOSVersion) }
def self.full_version
 @full_version ||= if (fake_macos = ENV.fetch("HOMEBREW_FAKE_MACOS", nil)) # for Portable Ruby building
 MacOSVersion.new(fake_macos)
 else
 MacOSVersion.new(VERSION)
 end
end

Example

I have macOS Monterey (12.0) running, which is just deprecated by Homebrew. I want to install batt which is not available as a bottle for macOS Monterey.

If I run brew install batt, I will get the following error:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


$ brew install batt
Warning: You are using macOS 12.
We (and Apple) do not provide support for this old version.
It is expected behaviour that some formulae will fail to build in this old version.
It is expected behaviour that Homebrew will be buggy and slow.
Do not create any issues about this on Homebrew's GitHub repositories.
Do not create any issues even if you think this message is unrelated.
Any opened issues will be immediately closed without response.
Do not ask for help from Homebrew or its maintainers on social media.
You may ask for help in Homebrew's discussions but are unlikely to receive a response.
Try to figure out the problem yourself and submit a fix as a pull request.
We will review it but may or may not accept it.

It’s Oct 8, 2024 and the latest macOS version is macOS Sequoia (15.0). So the last 3 supported macOS versions are:

macOS Sequoia (15.0)
macOS Sonoma (14.0)
macOS Ventura (13.0)

You can confirm that by checking out batt’s formula:

1
2
3
4
5
6


$ brew edit batt
...
sha256 cellar: :any_skip_relocation, arm64_sequoia: "61bd7790a82f2269b9a0ce1585c57564d03be4e4ac89b8f0d8843c0073a688e6"
sha256 cellar: :any_skip_relocation, arm64_sonoma: "198bd7bb9a808f0a9e4cb1a31b7e9c2a72d690ba1d07ebddf78b6d0ce0b6dd03"
sha256 cellar: :any_skip_relocation, arm64_ventura: "6eff598159b263327b8b562ab32f5e5e7157c20f25cbecfa08b48eda794c4c43"
...

Showing only the bottles for macOS Sequoia (15.0), macOS Sonoma (14.0), and macOS Ventura (13.0) are available.

Sadly my macOS version (Monterey 12.0) is not in the list, but macOS Ventura (13.0) is the closest to macOS Monterey (12.0). So I can fake the macOS version to macOS Ventura (13.0) by running the following command:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


$ export HOMEBREW_FAKE_MACOS=13.0
$ brew config
...
macOS: 13.0-arm64 # YES! I'm now faking macOS Ventura (13.0)
...
$ brew install batt
==> Downloading https://ghcr.io/v2/homebrew/core/batt/manifests/0.3.1
Already downloaded: /Users/charlie/Library/Caches/Homebrew/downloads/86da7d77f0bacb44475e0280eef162148e3b51df8ea44ff9bc16a5a7bba6d39f--batt-0.3.1.bottle_manifest.json
==> Fetching batt
==> Downloading https://ghcr.io/v2/homebrew/core/batt/blobs/sha256:6eff598159b263327b8b562ab32f5e5e7157c20f25cbecfa08b48eda794c4c43
Already downloaded: /Users/charlie/Library/Caches/Homebrew/downloads/24fc002de2ee11096a544dd84ff1033262a5cb627c2b824c915a552bb6a588dd--batt--0.3.1.arm64_ventura.bottle.tar.gz

As you can see, Homebrew is downloading the bottle for macOS Ventura (13.0) successfully! (Of course, the log is showing that I have already downloaded earlier, but you get the idea.)

batt itself does not rely on any APIs that are not available in my current macOS version, so it works perfectly fine.

macOS Nix First Taste

Thu, 27 Jun 2024 15:13:00 +0800

Note

Note that this blog currently acts as a reference for me. It is not a comprehensive guide on why and how to use Nix on macOS.

I chose nix because I am tired of Homebrew’s slowness and NOT PROVIDING BOTTLES (BINARY) FOR OLD MACOS VERSIONS.

Install

I am not using the official installer because it cannot survive macOS updates. Instead, I am using the Determinate System’s Nix Installer.

1
2
3
4
5
6
7


ARCH=$(uname -m | sed 's/arm64/aarch64/')
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
curl -L -o nix-installer https://github.com/DeterminateSystems/nix-installer/releases/latest/download/nix-installer-$ARCH-$OS
chmod +x nix-installer
# Optionally, move nix-installer to your PATH
# sudo install nix-installer /usr/local/bin
./nix-installer install --explain

Pin Nixpkgs

I don’t want to download a tarball and extract it every now and then. I know you can set tarball-ttl to a higher value, but I don’t want to do that either. Just pin nixpkgs.

1

nix registry pin nixpkgs

If you are like me in China, you may want to use a mirror.

1

echo "substituters = https://mirrors.sjtug.sjtu.edu.cn/nix-channels/store/ https://cache.nixos.org/" | sudo tee -a /etc/nix/nix.conf

Using

I wrote some scripts just to make my life easier.

Later Steps

There is nix-darwin to make declarative configuration easier. I don’t have time to try it yet but I will definitely give it a try when I have time.