Building on macOS

Build SerenityOS on macOS with Homebrew or Nix

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:

   Option 1: fuse + ext2

   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

   Option 2: genext2fs

   brew install genext2fs
   
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:

   LLVM 18

   brew install llvm@18
   

   GCC 13

   brew install gcc@13
   

   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

Apple Silicon

• 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

Intel

• Builds x86_64 natively
• No special configuration required

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:

Check GCC

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:

x86_64

SERENITY_ARCH=x86_64 Meta/serenity.sh run

aarch64

SERENITY_ARCH=aarch64 Meta/serenity.sh run

Disable Rosetta 2 before building aarch64.

Next Steps

Advanced Options

Explore build customization and CMake options

Build System Overview

Learn more about the SuperBuild system