Skip to main content

​
Prerequisites

This guide assumes you have:
  • Homebrew installed
  • Xcode or Xcode Command Line Tools installed
The Command Line Tools alone are sufficient - you don’t need the full Xcode application.

​
Setup with Homebrew

1

Configure Xcode Command Line Tools

If you have the full Xcode application installed, set your command line tools to use Xcode’s tools:
sudo xcode-select --switch /Applications/Xcode.app
Skip this step if you only have the Command Line Tools installed.
2

Install core dependencies

brew install coreutils e2fsprogs qemu bash imagemagick ninja \
  cmake ccache rsync zstd
3

Install filesystem support

Choose one of the following options:
brew install m4 autoconf automake libtool
brew install --cask macfuse
Toolchain/BuildFuseExt2.sh
Installing macfuse for the first time requires:
  1. Enabling its system extension in System Settings
  2. Restarting your machine
4

Install debugging tools (Apple Silicon only)

For kernel debugging on Apple Silicon Macs:
brew install x86_64-elf-gdb
This provides a native build of GDB that can cross-debug x86-64 code.
5

Install newer compiler (Xcode 14.2 or older)

If you have Xcode 14.2 or older, install a newer host compiler:
brew install llvm@18
Xcode 14.3 or later is known to work without additional compilers.

​
Setup with Nix

If you have Nix installed, you can enter a devshell with all dependencies: 
nix --extra-experimental-features "nix-command flakes" develop

​
Build and Run

Once all dependencies are installed: 
Meta/serenity.sh run
Refer to the main Build System Overview for detailed build instructions.

​
Platform Notes

​
Apple Silicon vs Intel

  • Both native aarch64 and x86_64 builds are supported
  • Rosetta 2 should be disabled to build native aarch64 version
  • Use x86_64-elf-gdb for debugging x86-64 kernel

​
macfuse Installation

After installing macfuse via Homebrew:
  1. Open System Settings (or System Preferences on older macOS)
  2. Enable the macfuse system extension
  3. Restart your Mac
This is easy to miss but required for macfuse to work.

​
CMake Version Notes

Homebrew ships bleeding-edge CMake versions, which should work fine. However:
Building CMake from source with Homebrew GCC or LLVM may not work on all platforms.
If Homebrew doesn’t offer CMake 3.25.x+ on your platform: 
# Manually build CMake with Apple clang
Toolchain/BuildCMake.sh
Make sure Apple clang from Xcode is first in your $PATH.

​
Xcode Compatibility

If you have the full Xcode installed, keep it updated to avoid CMake compatibility issues with GCC.

​
Troubleshooting

​
macfuse Not Working

If you get permission errors:
  1. Check System Settings for enabled kernel extensions
  2. Ensure you’ve restarted after installation
  3. Try reinstalling: 
    brew reinstall --cask macfuse

​
CMake Build Issues

If you encounter CMake errors: 
# Remove old cache files
rm Build/*/CMakeCache.txt

# Ensure Xcode tools are configured
sudo xcode-select --switch /Applications/Xcode.app

# Or for Command Line Tools only:
sudo xcode-select --switch /Library/Developer/CommandLineTools

​
Compiler Version Issues

Verify your compiler versions: 
gcc --version

​
QEMU Launch Failures

If QEMU fails to start: 
# Ensure QEMU is properly installed
brew reinstall qemu

# Check QEMU version (6.2+ required)
qemu-system-x86_64 --version

​
Architecture-Specific Builds

To build for a specific architecture: 
SERENITY_ARCH=x86_64 Meta/serenity.sh run

​
Next Steps

Advanced Options

Explore build customization and CMake options

Build System Overview

Learn more about the SuperBuild system

Build docs developers (and LLMs) love

Get started for freeTalk to us