SafaOS/SafaOS: an opensource operating system made for fun · GitHub

An open-source non-Unix-like OS, written from scratch in Rust for fun.

You can use the safa-helper to build and run SafaOS. Running it is either through ./helper.sh [ARGS] or just:

cd safa-helper
cargo run -- [ARGS]

If your platform doesn't support running shell scripts this could work, one if the build system goals is to be portable so If it doesn't work on your platform natively please open an issue (I didn't actually test it on anything other then linux because of lack of motivation).

you need:

• git
• xorriso (TODO: Replace with a more portable tool, perhaps write the ISO packaging code myself?)
• a working rust toolchain with cargo
• libcurl (should be bundled by default in most operating systems including windows)

First you have to run (or the cd safa-helper trick above...)

./helper.sh init

once every rust libstd update (or if you are not actively working on the project just once every git pull would work).

If you want to cross compile SafaOS for an architecture other then your host's run

./helper.sh init -a [arch]

currently arch can either be x86_64 or aarch64.

Then to build run

./helper.sh build

(the -a|--arch flag works for build too) This should make an iso with the path: out/safaos.iso if successful, You can also find pre-built artifact isos built using github actions, check the latest successful build for the main branch.

You'll need:

• qemu-system-[arch]: where arch is either x86_64 or aarch64.
• all the build dependencies for the target architecture.

./helper.sh run --no-kvm

(the -a|--arch flag is also available for running, if you want to use it you must likely want to provide the --no-kvm flag too)

or run with kvm (faster but kvm might not be available or broken)

./helper.sh run

otherwise you have the iso out/safaos.iso feel free to do whatever you want with it.

You can also use the safa-helper to debug:

./helper.sh run --debugger --no-kvm

(doesn't work with kvm) and then connect to port 1234 with a gdb client i recommend using rust-lldb.

❯ ./helper.sh --help
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.12s
     Running `/home/aler/Documents/SafaOS/safa-helper/target/debug/safa-helper --help`
The SafaOS's build system and helper tools

Usage: safa-helper [OPTIONS] [COMMAND]

Commands:
  init               Initializes the submodules and installs the SafaOS's toolchain (rustc target)
  install-toolchain  Installs the SafaOS prebuilt toolchain for the current host platform. (for a given SafaOS specific target)
  get-fonts          Retrieves all the font files
  init-fonts         Initializes the Font List
  reset              `cargo clean`s all crates in the userspace directory. (eg. safa-userspace)
  build              Builds a SafaOS iso
  run                Builds and Runs a normal SafaOS iso, requires qemu (default)
  test               Builds and runs a test SafaOS iso, requires qemu
  help               Print this message or the help of the given subcommand(s)

Options:
      --no-kvm                 runs with kvm disabled
      --no-gui                 runs with gui disabled
      --debugger               runs with debugger enabled on port 1234
      --qemu-args <QEMU_ARGS>  [default: ]
  -o, --output <OUTPUT>        The final output of the built iso the default is out/safaos.iso for normal isos and out/safaos-tests.iso for test isos
  -v, --verbose
  -a, --arch <ARCH>            [default: x86_64] [possible values: aarch64, x86_64]
  -h, --help                   Print help
  -V, --version                Print version

You'll need:

• qemu-system-[arch]: where arch is either x86_64 or aarch64.

To test SafaOS for the current host, run:

./helper.sh test --no-kvm

or

cd safa-helper
cargo run test --no-kvm

You can use the -a|--arch flag to test a specific arch, you can also omit --no-kvm if kvm is available.

or to test all architectures (requires all qemu-system-[arch] variants) run:

./test-all.sh

then the tests will be ran for all architectures with no kvm and no gui.

safa-userspace/: contains userspace programs written in rust, they are compiled and then copied to the ramdisk as sys:/bin/, any rust binary crate added to this directory would be automatically detected, compiled and bundled to the ramdisk by the safa-helper.

safa-core/: contains the kernel and other kernel-related crates (only the kernel crate is detected by the safa-helper).

ramdisk-include: anything put in this directory will be included in the ramdisk at sys:/ by the safa-helper.

common: some constants and files that are used by the build system.

safa-helper/: The SafaOS build system and helper utils.

Check FEATURES.md. you can also check safa-userspace/ for examples of programs written in rust.

Aside from the rust stdandard library another method to interact with the kernel is through the safa-api which provides low-level wrapper functions around the syscalls, and also some high-level wrappers (such as a userspace allocator which is a very high-level wrapper around the sbrk syscall, ofc the raw sbrk syscall is still exposed).

check out CONTRIBUTING.md

currently uses the limine bootloader. Thanks to the developers of:

• MinOS, TacOS, and BananaOS for helping develop this.
• StelluxOS for their awesome OS and XHCI tutorial, which helped me implemented USB support.