Notes about SerenityOS

SerenityOS.md

File structure

• Libraries: Userland/Libraries/{LibC, LibGUI...}
• Games: Userland/Games/{Snake, Solitaire...}
• Applications: Userland/Applications/{Calculator, Calendar...}

Ninja

SerenityOS is built using CMake and Ninja.

• Target: output files of the build process (executables, libraries).

• Use Ninja with CMake: cmake -G Ninja (generates a build.ninja file)

• Build target: ninja <target>

• Build default: ninja ("default" target is built. In CMake, default="all" for all the targets in the project)

• List targets: ninja -t targets

• Installation: ninja install The install target is generated in cmake by install(...) command.

• Targets specific to SerenityOS:

$ ninja image # Generate image to run
$ ninja run   # Run image on qemu

CMake custom functions

The following CMake functions are defined in: Meta/CMake/utils.cmake

serenity_component(...)
serenity_app(...)
serenity_lib(...)

System calls

Functions

• Kernel-level implementations in Kernel/Syscalls/*.cpp
• User-level functions to call in Userland/Libraries/LibCore/System.cpp

Pledge

• Notion inspired by OpenBSD.
• Specifies a set of promises, each allowing certain syscalls:
  • stdio: Basic I/O (read, write, close...)
  • rpath: Read filesystem access (open, stat, getcwd...)
  • unix: Unix domain sockets (socket, bind, listen...)

C++ program

Entry point

• Actual main() entry point defined in Userland/Libraries/LibMain/Main.cpp.
• Does some initialization, and calls serenity_main().
• serenity_main() returns an ErrorOr<ResultType, ErrorType> (defined in AK/Error.h and without ErrorType in AK/Forward.h).

Syscalls

• The following two system calls are placed at beginning of serenity_main() for security purposes (to sandbox apps).
  • pledge(): Limit system calls a process can make.
  • unveil(): Allow access only to specific files and directories.

TRY macro

• Defined in AK/Try.h
• Executes the passed expression (function) that returns an ErrorOr.
• On error, serenity_main() returns with the error in ErrorOr.
• On success, the ErrorOr value is assigned to a variable.
• Implemented using a compound statement (valid in GNU C), that evaluates to its last subexpression.