What is XNU?

XNU kernel is part of the Darwin operating system for use in macOS and iOS operating systems. XNU is an acronym for X is Not Unix. XNU is a hybrid kernel combining the Mach kernel developed at Carnegie Mellon University with components from FreeBSD and a C++ API for writing drivers called IOKit. XNU runs on x86_64 and ARM64 for both single processor and multi-processor configurations.

The XNU Source Tree

• config - configurations for exported apis for supported architecture and platform
• SETUP - Basic set of tools used for configuring the kernel, versioning and kextsymbol management.
• EXTERNAL_HEADERS - Headers sourced from other projects to avoid dependency cycles when building. These headers should be regularly synced when source is updated.
• libkern - C++ IOKit library code for handling of drivers and kexts.
• libsa - kernel bootstrap code for startup
• libsyscall - syscall library interface for userspace programs
• libkdd - source for user library for parsing kernel data like kernel chunked data.
• makedefs - top level rules and defines for kernel build.
• osfmk - Mach kernel based subsystems
• pexpert - Platform specific code like interrupt handling, atomics etc.
• security - Mandatory Access Check policy interfaces and related implementation.
• bsd - BSD subsystems code
• tools - A set of utilities for testing, debugging and profiling kernel.

How to Build XNU

Prerequisites for External Developers

If you are building XNU outside of Apple's internal development environment, you will need to set up additional dependencies first.

Download and Install Xcode

Ensure you have the Xcode installed that is aligned with the OS version you want to build (for example, Xcode 15.4 for MacOS 15.4). Download from: * App Store, or * https://developer.apple.com/download/all/ (requires Apple Developer account)

To select a specific version of Xcode:

sudo xcode-select -s path/to/Xcode.app/Contents/Developer
xcrun -sdk macosx -show-sdk-path

Download and Install the Kernel Debug Kit (KDK)

This step is required for building on Apple silicon. If you are building only for Intel, you can skip this step.

1. Download the KDK from https://developer.apple.com/download/all/ (requires Apple Developer account)
2. Search for "Kernel Debug Kit" and download the package matching your exact macOS version (you can find this in Settings > General > About)
3. Install the package. It will be installed to /Library/Developer/KDKs/KDK_{ver}_{build}.kdk
4. Save the path for later use:

export KDK=/Library/Developer/KDKs/KDK_{ver}_{build}.kdk

Download and Build XNU Dependencies

The following dependencies must be built and installed before building XNU:

• DTrace (this is optional)
• AvailabilityVersions
• libdispatch
• xnu headers

The versions you need can be downloaded from https://opensource.apple.com/releases/

Build CTF Tools from dtrace

tar zxf dtrace-{version}.tar.gz
cd dtrace-{version}
xcodebuild install -sdk macosx -target ctfconvert \
  -target ctfdump -target ctfmerge \
  ARCHS='x86_64 arm64' VALID_ARCHS='x86_64 arm64' DSTROOT=$PWD/dst
export TOOLCHAIN=$(cd $(xcrun -sdk macosx -show-sdk-platform-path)/../../Toolchains/XcodeDefault.xctoolchain && pwd)
sudo ditto "$PWD/dst/$TOOLCHAIN" "$TOOLCHAIN"
cd ..

Install AvailabilityVersions

tar zxf AvailabilityVersions-{version}.tar.gz
cd AvailabilityVersions-{version}
make install
sudo ditto "$PWD/dst/usr/local/libexec" \
  "$(xcrun -sdk macosx -show-sdk-path)/usr/local/libexec"
cd ..

Install XNU Headers

tar zxf xnu-{version}.tar.gz
cd xnu-{version}
make SDKROOT=macosx ARCH_CONFIGS="X86_64 ARM64" installhdrs
sudo ditto "$PWD/BUILD/dst" "$(xcrun -sdk macosx -show-sdk-path)"
cd ..

Build libfirehose from libdispatch

tar zxf libdispatch-{version}.tar.gz
cd libdispatch-{version}
xcodebuild install -sdk macosx ARCHS='x86_64 arm64e' \
  VALID_ARCHS='x86_64 arm64e' -target libfirehose_kernel \
  PRODUCT_NAME=firehose_kernel DSTROOT=$PWD/dst
sudo ditto "$PWD/dst/usr/local" \
  "$(xcrun -sdk macosx -show-sdk-path)/usr/local"
cd ..

Building a DEVELOPMENT Kernel

The xnu make system can build kernel based on KERNEL_CONFIGS & ARCH_CONFIGS variables as arguments. Here is the syntax:

make SDKROOT=<sdkroot> ARCH_CONFIGS=<arch> KERNEL_CONFIGS=<variant>

Where:

• <sdkroot>: path to macOS SDK on disk. (defaults to /)
• <variant>: can be debug, development, release, profile and configures compilation flags and asserts throughout kernel code.
• <arch>: can be valid arch to build for. (E.g. X86_64)

For Internal Developers

To build a kernel for the same architecture as running OS, just type

make SDKROOT=macosx.internal

Additionally, there is support for configuring architectures through ARCH_CONFIGS and kernel configurations with KERNEL_CONFIGS.

make SDKROOT=macosx.internal ARCH_CONFIGS=X86_64 KERNEL_CONFIGS=DEVELOPMENT
make SDKROOT=macosx.internal ARCH_CONFIGS=X86_64 KERNEL_CONFIGS="RELEASE DEVELOPMENT DEBUG"

For External Developers

Building for Intel Macs

cd xnu-{version}
make SDKROOT=macosx ARCH_CONFIGS=X86_64 KERNEL_CONFIGS=RELEASE

Building for Apple Silicon Macs

cd xnu-{version}
make SDKROOT=macosx KDKROOT=${KDK} \
  TARGET_CONFIGS="RELEASE ARM64 {PLATFORM}"

The {PLATFORM} should be set based on your machine. A table of platform and associated Mac Models can be found at the end of this document.

Example for MacBookAir10,1:

make SDKROOT=macosx KDKROOT=${KDK} TARGET_CONFIGS="RELEASE ARM64 T8101"

Build Options

• Speed up link: add BUILD_LTO=0
• Build development kernel: replace RELEASE with DEVELOPMENT
• Colorful output: add LOGCOLORS=y
• Concise output: add CONCISE=1

Note: By default, the architecture is set to the build machine's architecture, and the default kernel config is set to build for DEVELOPMENT.

This will also create a bootable image, kernel.[config], and a kernel binary with symbols, kernel.[config].unstripped.

To install the kernel into a DSTROOT, use the install_kernels target:

make install_kernels DSTROOT=/tmp/xnu-dst

For a more satisfying kernel debugging experience, with access to all local variables and arguments, but without all the extra check of the DEBUG kernel, add something like the following to your make command:

CFLAGS_DEVELOPMENTARM64="-O0 -g -DKERNEL_STACK_MULTIPLIER=2"
CXXFLAGS_DEVELOPMENTARM64="-O0 -g -DKERNEL_STACK_MULTIPLIER=2"

Remember to replace DEVELOPMENT and ARM64 with the appropriate build and platform.

Extra Flags: You can pass additional flags to the C compiler at the command line with the EXTRA_CFLAGS build setting. These flags are appended to the base CFLAGS, and the default value for the setting is an empty string.

This setting allows you to e.g. selectively turn on debugging code that is guarded by a preprocessor macro. Example usage...

text make SDKROOT=macosx.internal PRODUCT_CONFIGS=j314s EXTRA_CFLAGS='-DKERNEL_STACK_MULTIPLIER=2'

• To build with RELEASE kernel configuration

  text make KERNEL_CONFIGS=RELEASE SDKROOT=/path/to/SDK

Building FAT Kernel Binary

Define architectures in your environment or when running a make command.

make ARCH_CONFIGS="X86_64" exporthdrs all

Other Makefile Options

• $ make MAKEJOBS=-j8 # this will use 8 processes during the build. The default is 2x the number of active CPUS.
• $ make -j8 # the standard command-line option is also accepted
• $ make -w # trace recursive make invocations. Useful in combination with VERBOSE=YES
• $ make BUILD_LTO=0 # build without LLVM Link Time Optimization
• $ make BOUND_CHECKS=0 # disable -fbound-attributes for this build
• $ make REMOTEBUILD=user@remotehost # perform build on remote host
• $ make BUILD_CODE_COVERAGE=1 # build with support for collecting code coverage information
• $ make SAVE_OPT_RECORD=".*" # save compiler (linker if BUILD_LTO) optimization record, for analysis by a tool like optview

The XNU build system can optionally output color-formatted build output. To enable this, you can either set the XNU_LOGCOLORS environment variable to y, or you can pass LOGCOLORS=y to the make command.

Customize the XNU Version

The xnu version is derived from the SDK or KDK by reading the CFBundleVersion of their System/Library/Extensions/System.kext/Info.plist file. This can be customized by setting the RC_DARWIN_KERNEL_VERSION variable in the environment or on the make command line.

See doc/building/xnu_version.md for more details.

Debug Information Formats

By default, a DWARF debug information repository is created during the install phase; this is a "bundle" named kernel.development.\.dSYM To select the older STABS debug information format (where debug information is embedded in the kernel.development.unstripped image), set the BUILD_STABS environment variable.

export BUILD_STABS=1
make

Building KernelCaches

To test the xnu kernel, you need to build a kernelcache that links the kexts and kernel together into a single bootable image. To build a kernelcache you can use the following mechanisms:

• Using automatic kernelcache generation with kextd. The kextd daemon keeps watching for changing in /System/Library/Extensions directory. So you can setup new kernel as

  text cp BUILD/obj/DEVELOPMENT/X86_64/kernel.development /System/Library/Kernels/ touch /System/Library/Extensions ps -e | grep kextd

• Manually invoking kextcache to build new kernelcache.

  text kextcache -q -z -a x86_64 -l -n -c /var/tmp/kernelcache.test -K /var/tmp/kernel.test /System/Library/Extensions

Booting a KernelCache on a Target machine

For Internal Developers

The development kernel and iBoot supports configuring boot arguments so that we can safely boot into test kernel and, if things go wrong, safely fall back to previously used kernelcache. Following are the steps to get such a setup:

1. Create kernel cache using the kextcache command as /kernelcache.test

2. Copy exiting boot configurations to alternate file

   sh cp /Library/Preferences/SystemConfiguration/com.apple.Boot.plist /next_boot.plist

3. Update the kernelcache and boot-args for your setup

   sh plutil -insert "Kernel Cache" -string "kernelcache.test" /next_boot.plist plutil -replace "Kernel Flags" -string "debug=0x144 -v kernelsuffix=test " /next_boot.plist

4. Copy the new config to /Library/Preferences/SystemConfiguration/

   sh cp /next_boot.plist /Library/Preferences/SystemConfiguration/boot.plist

5. Bless the volume with new configs.

   text sudo -n bless --mount / --setBoot --nextonly --options "config=boot"

The --nextonly flag specifies that use the boot.plist configs only for one boot. So if the kernel panic's you can easily power reboot and recover back to original kernel.

For External Developers

SECURITY WARNING: Installing a custom kernel requires lowering the system security settings. On Intel Macs, you must disable System Integrity Protection (SIP), set Secure Boot to "No Security," and disable the authenticated root volume. On Apple Silicon Macs, you must set the security policy to "Reduced Security" and further downgrade to "Permissive" via Recovery Mode. Failure to do this will result in a system that fails to boot.

Note: Building a kernel cache MUST be done on the device where you will boot the custom kernel.

Note: Installing a kernel could potentially render your system un-bootable, so testing in a VM is highly recommended.

Intel Mac: Install and Run

After building, you should have a new kernel at {xnu}/BUILD/obj/kernel[.development].

1. Build the Kernel Cache

cd xnu-{version}
kmutil create -a x86_64 -Z -n boot sys \
  -B BUILD/BootKernelExtensions.kc \
  -S BUILD/SystemKernelExtensions.kc \
  -k BUILD/obj/kernel \
  --elide-identifier com.apple.driver.AppleIntelTGLGraphicsFramebuffer

Note: The AppleIntelTGLGraphicsFramebuffer driver will not link against the open source XNU kernel.

2. Mount a live view of the filesystem

mkdir BUILD/mnt
sudo mount -o nobrowse -t apfs /dev/diskMsN $PWD/BUILD/mnt

Note: diskMsN can be found by running mount, looking for the root mount's device, and removing the last "s" segment. For example, if root is /dev/disk1s2s3, mount /dev/disk1s2.

3. Install the kernel and KCs

sudo ditto BUILD/BootKernelExtensions.kc "$PWD/BUILD/mnt/System/Library/KernelCollections/BootKernelExtensions.kc.development"
sudo ditto BUILD/SystemKernelExtensions.kc "$PWD/BUILD/mnt/System/Library/KernelCollections/SystemKernelExtensions.kc.development"
sudo ditto BUILD/obj/kernel "$PWD/BUILD/mnt/System/Library/Kernels/kernel.development"

Note: "development" can be replaced with any short string (e.g., "usr"). Using a suffix allows maintaining a fallback for system recovery.

4. Bless the new KCs

sudo bless --folder $PWD/BUILD/mnt/System/Library/CoreServices \
  --bootefi --create-snapshot

5. Set boot-args to select the new KC

sudo nvram boot-args="kcsuffix=development wlan.skywalk.enable=0"

Note: The wlan.skywalk.enable=0 boot-arg is necessary to disable Skywalk in the WLAN driver, as Skywalk is not part of the open source kernel. If you encounter Skywalk-related panics, you may also need to add dk=0 to disable DriverKit drivers.

6. Reboot!

Important Notes: * Due to missing network (Skywalk) and power management (XCPM) functionality, some features like sleep/wake will not work * If your machine becomes un-bootable, boot into Recovery Mode (h