Prerequisites

The most common package manager on Mac is brew (Homebrew), so install it first—this makes installing what macOS calls “Command Line Tools” much easier later on.

But installing brew also requires access to GitHub as a prerequisite, and on macOS it’s hard to use my favorite tool, Steam++. There are two easy methods. The first is the most common VPN method—Clash; the second is even simpler and more beginner-friendly: just use UU Accelerator. Search for “学术” (“Academic”) in it and you get free acceleration.

Once you’ve confirmed that GitHub is accessible, run the following command in the terminal. Note: at the end, the command tells you what to do about PATH.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After the installation finishes, use the following command to confirm it succeeded.

brew -v

Installing the Toolchain and Build Tools

First install the build tools, cmake and ninja.

brew install cmake ninja

Then install the toolchain. There’s a catch: arm-gcc cannot be installed directly via brew under its original package name; that package may be a without-headers variant and lacks many standard libraries and headers. Managing with MSYS2 on Windows has a similar issue.

First, try uninstalling the packages and tools under their original names; this step is important if you have a leftover old environment.

brew uninstall arm-none-eabi-gcc arm-none-eabi-binutils

Then install the full package.

brew install --cask gcc-arm-embedded

PKG="$(find "$(brew --caskroom)/gcc-arm-embedded" -name '*.pkg' | head -n 1)"
[ -n "$PKG" ] || { echo "未找到 gcc-arm-embedded 的 pkg"; exit 1; }
installer -pkg "$PKG" -target CurrentUserHomeDirectory

TOOLBIN="$(find "$HOME/Applications/ArmGNUToolchain" -type d -path '*/arm-none-eabi/bin' | sort | tail -n 1)"
[ -n "$TOOLBIN" ] || { echo "未找到 ArmGNUToolchain bin 目录"; exit 1; }
for t in gcc g++ as ar objcopy size gdb nm objdump ranlib readelf strip addr2line gcc-ar gcc-nm gcc-ranlib; do
    ln -sf "$TOOLBIN/arm-none-eabi-$t" "/opt/homebrew/bin/arm-none-eabi-$t"
done

Finally, verify the complete toolchain; the output should include the correct header file paths and header names such as stdint.h.

arm-none-eabi-gcc -v -E -x c - < /dev/null

After that, you can compile your project as usual.