System Architecture

System Layout Overview

ravynOS combines certain aspects of FreeBSD (opens in a new tab), XDG (opens in a new tab), and macOS (opens in a new tab). In general, it tries to follow the layout of macOS.

System Files

FreeBSD's kernel and base runtime is used to provide better hardware compatibility than something based on Apple's XNU (opens in a new tab) kernel like PureDarwin (opens in a new tab). Using FreeBSD as the base also gives us Linux app compatibility to help fill gaps in application support until Mac apps are fully working.

FreeBSD lives in:

  • /boot
  • /bin
  • /etc
  • /lib
  • /libexec
  • /sbin
  • /usr
  • /var

Some special directories are also used:

  • /dev (device files)
  • /tmp (temporary files)
  • /proc (running process information)
  • /media
  • /mnt
  • /net (special mount points - mostly unused in ravynOS).

There is also a small rescue system in /rescue which can be used for system recovery and user root's files in /root. The source code for this base system can be found in the ravynOS (opens in a new tab) repository. For more information on FreeBSD itself, please see the FreeBSD Handbook (opens in a new tab) - but be careful! ravynOS is not FreeBSD; it is ''based'' on FreeBSD. There are significant differences.

This ravynOS repository includes our modified compiler and linker (clang and lld) which understand how to build and link ELF Framework bundles.

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

Most of the system files provided by Ravyn live under /System/Library. Notably, the Cocoa compatibility APIs live in the Frameworks folder here. System fonts exist in the Fonts folder and desktop wallpapers can be found under Desktop Pictures. Important system services like Filer and startup code are found in CoreServices (not to be confused with the CoreServices.framework). Source code for most things here can be found in the main ravynOS (opens in a new tab) repository. Some items (like Fonts and Desktop Pictures) are fetched as part of building the Live CD ISO and are then copied into the installed system by the installer. Source code for the CD build can be found in the ravynOS (opens in a new tab) GitHub repository.


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). Applications may also be packaged in the AppDir (opens in a new tab) format. Linux applications can also use AppImage (opens in a new tab) format. Bundles are the preferred format.

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.

Traditional Unix applications and tools generally live in /usr/bin or /usr/local/bin and various other directories such as /usr/share, /var/lib, /etc. Other the ones provided by the system, this type of application should be avoided. (A future package system such as Homebrew will allow sane management of user-installed Unix tools in /usr/local.) If you really need something not provided by the system and not available as an Application, you can build it from the FreeBSD Ports collection.

Each user also has a Applications folder in their home directory.


/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. It is maintained by Filer and the open through the LaunchServices.framework.

The XDG folders used by many X11 applications have also been relocated into ~/Library.

  • XDG_CONFIG_HOME, normally ~/.config, is ~/Library/FreeDesktop/config
  • XDG_DATA_HOME, normally ~/.local/share, is ~/Library/FreeDesktop/share

This means many standard X11 & KDE app config files will be found there instead. (Note: XDG_CACHE_HOME still points to ~/.cache but will likely move in the future.)

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


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


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.