jcs.org
Serenity Operating System
1# Setting up a development environment on macOS
2
3# Prerequisites
4
5This installation guide assumes that you have [Homebrew](https://brew.sh) and Xcode installed. You need to open Xcode at least once for it to install the required tools.
6
7Before you build, you must set your command line tools to Xcode's tools instead of the ones installed via Homebrew:
8```console
9sudo xcode-select --switch /Applications/Xcode.app
10```
11
12Make sure you also have all the following dependencies installed:
13
14```console
15# core
16brew install coreutils e2fsprogs qemu bash imagemagick ninja cmake ccache rsync zstd
17
18# (option 1) fuse + ext2
19brew install m4 autoconf automake libtool
20brew install --cask macfuse
21Toolchain/BuildFuseExt2.sh
22
23# (option 2) genext2fs
24brew install genext2fs
25
26# for kernel debugging, on Apple Silicon
27brew install x86_64-elf-gdb
28```
29
30If you have Xcode version 13 or older, also install a newer host compiler from homebrew. Xcode 14 is known to work.
31
32```console
33brew install llvm@15
34# OR
35brew install gcc@12
36```
37
38# Notes
39
40You can use both Intel and Apple Silicon Macs to run the x86-64 version of SerenityOS. You do not
41need to install Rosetta for this. An emulator is used when running on an Apple Silicon, so Serenity
42will be slower compared to running natively with hardware-assisted virtualization on an Intel machine.
43
44If you're building on M1 Mac and have Homebrew installed in both Rosetta and native environments,
45you have to make sure that required packages are installed only in one of the environments. Otherwise,
46these installations can conflict during the build process, which is manifested in hard to diagnose issues.
47Building on M1 natively without Rosetta is recommended, as the build process should be faster without Rosetta
48overhead.
49
50Installing macfuse for the first time requires enabling its system extension in System Preferences and then restarting your machine. The output from installing macfuse with brew says this, but it's easy to miss.
51
52It's important to make sure that Xcode is not only installed but also accordingly updated, otherwise CMake will run into incompatibilities with GCC.
53
54Homebrew is known to ship bleeding edge CMake versions, but building CMake from source with homebrew
55gcc or llvm may not work. If homebrew does not offer cmake 3.25.x+ on your platform, it may be necessary
56to manually run Toolchain/BuildCMake.sh with Apple clang from Xcode as the first compiler in your $PATH.
57
58If you want to debug the x86-64 kernel on an Apple Silicon machine, you can install the `x86_64-elf-gdb`
59package to get a native build of GDB that can cross-debug x86-64 code.