System Layout Overview

ravynOS in general looks like macOS (opens in a new tab), with a few aspects of FreeBSD (opens in a new tab). It uses a custom EFI bootloader (opens in a new tab).

The core system is Darwin 19.6, equivalent to MacOS X 10.15.6 (Catalina). This consists of the XNU kernel, a set of kernel extensions (kexts) implementing kernel components and IOKit drivers, libSystem, and dyld.

Kernel Extensions are the primary way to add hardware support, file systems, and kernel capabilities in ravynOS, and should be written for IOKit. See the AHCI driver in /Kernel/Extensions/RavynAHCIPort (opens in a new tab) for an example. Critical extensions are pre-linked with the kernel to create a kernelcache file, which is loaded by the EFI loader. The kernelcache may be compressed with LZVN, although it currently isn't when produced by plktool. After the system is up and a root filesystem is available, additional kexts can be loaded from disk.

We can currently boot in a QEMU Q.35 VM with OVMF EFI. More drivers are needed for real hardware.

Most core OS functionality for user processes is provided by libSystem, which is automatically linked to every executable by the compiler (clang). It includes the C runtime, libdispatch, liblaunch, libxpc, blocks runtime, name resolution, system info and notifications, malloc, math, threads, logging, and more. It does NOT include C++, which is LLVM's in /usr/lib/libc++, or Objective-C, which is Apple's objc4 at /usr/lib/libobjc.A.dylib.

Layer Cake

         [           User Applications            ]
         [                Magma DE                ]
         [    WindowServer    ][    daemons       ]
         [ CoreFoundation, Foundation, Cocoa, etc ]
         [            --- launchd ---             ]
         [ libSystem ][ libc++ ][ libobjc ][ dyld ]
          ----------------------------------------
         [ Kernel extensions: IOACPIFamily,       ]
         [ IOPCIFamily, IOStorageFamily,          ]
         [ IOGraphics, hfs, msdosfs, pthread,     ]
         [ corecrypto, etc                        ]
          ----------------------------------------
         [ XNU - BSDKernel, Mach, IOKit           ]

We have this stack working up to CoreFoundation, with the exception of launchd currently being a simple stub.

System Files

Darwin lives in:

• /usr/lib - dyld, libSystem.B.dylib, /usr/lib/system/*, libc++, libobjc.A, etc
• /System/Library/CoreServices
• /System/Library/Kernels
• /System/Library/Extensions
• /System/Library/Frameworks - System, Kernel, IOKit and DriverKit frameworks (with headers)

Some special directories are also used:

• /dev (device files)
• /tmp (temporary files)

You can (and should) safely ignore these OS directories unless you are working on the base system.

Most of the system files provided by ravynOS live under /System/Library.

• Frameworks contains our CoreFoundation, CFNetwork, Foundation, CoreData, CoreText, CoreVideo, CoreGraphics, QuartzCore, LaunchServices, IOKit, and AppKit frameworks. Most of these have many stub functions that need to be implemented.
• Fonts
• Desktop Pictures
• CoreServices

The command line BSD environment lives mainly in /bin, /sbin, /usr/bin, /etc, and /var. Certain macOS/ravynOS specific tools like open, plutil, etc are also here.

Applications

Applications in ravynOS should be packaged as AppBundles with the directory name ending in .app and stored in either /Applications or ~/Applications (although they can technically be stored or moved anywhere). Some Applications here are provided with ravynOS and others may be installed by users. As on macOS, this is the primary place to find installed software.

Library

/Library is used for system-level or shared files that are not strictly "system" files, such as application-installed fonts and Java SDKs. Think of it roughly like a combination of /usr/lib and /usr/share. Each user has a personal Library folder in their home directory which is used to store per-user configuration, application support data, individual fonts, cached data, etc.

On ravynOS, each user has a LaunchServices database in ~/Library/db/launchservices.db. This database controls which applications are known, what types they can open, and which is used to open files.

This MIT knowledge base article (opens in a new tab) has a good explanation of the multiple Library folders on macOS.

Users

As on macOS, ravynOS users have a home folder under /Users. The traditional Unix folders /usr/home and /home are not used.

Volumes

Any media detected by ravynOS will be mounted under /Volumes in a folder with the filesystem name or label, if it can be determined, and a generic name if not. Other mount points such as /media and /mnt should not be used by applications, but can be used for temporary mounts by developers or users.