DOCSEARCHbyAlgolia
Submit Docs

ToaruOS Documentation

repository·master·Indexed 27 days ago

https://github.com/klange/toaruos

An independent, complete operating system for x86-64 PCs and ARMv8 VM environments. It features the Misaka modular kernel, a C standard library, and Kuroko, a custom dynamic bytecode-compiled language. The documentation covers system usage (shell, bim editor, msk package manager), window management, bootloader configurations for BIOS and EFI, and a suite of system libraries including toaru_graphics, toaru_yutani for GUI applications, and toaru_pex for IPC.

Tokens
42.6K
Snippets
29
Records
391
Agent score
92%

What's inside ToaruOS

  1. Overview of the ToaruOS Bootloader

    master

    The ToaruOS Bootloader (version 4.0) is designed for the ToaruOS Live CD. It supports both BIOS and EFI boot modes and provides a menu for selecting boot options, a simple editor for customizing kernel command line arguments, and a 32-bit ELF loader for multiboot-compatible builds of Misaka.

    Key features include:

    • Boot Menu: Select between different boot options.
    • Command Line Editor: Customize kernel parameters before booting.
    • ELF Loader: Specifically tailored to load Misaka kernels via multiboot compatibility.

  2. Overview of ToaruOS System Libraries

    master
    The ToaruOS system libraries provide core functionality that is not present in the standard C library. These libraries are shared across multiple ToaruOS applications to ensure consistent behavior for features like graphics, configuration parsing, and data structures.

  3. Build ToaruOS using Docker

    master

    If you are on a Linux host with Docker installed, you can build ToaruOS locally using a provided build container. The repository must be bind-mounted to /root/misaka inside the container.

    Follow these steps to clone the repository, initialize submodules, and run the build script via Docker:

    git clone https://github.com/klange/toaruos
cd toaruos
git submodule update --init kuroko
git submodule update --init bim
docker pull toaruos/build-tools:1.99.x
docker run -v `pwd`:/root/misaka -w /root/misaka -e LANG=C.UTF-8 -t toaruos/build-tools:1.99.x util/build-in-docker.sh

    After the build completes, you can use make targets such as make run or make shell (which runs a ToaruOS shell using a serial port with QEMU).

    git clone https://github.com/klange/toaruos
cd toaruos
git submodule update --init kuroko
git submodule update --init bim
docker pull toaruos/build-tools:1.99.x
docker run -v `pwd`:/root/misaka -w /root/misaka -e LANG=C.UTF-8 -t toaruos/build-tools:1.99.x util/build-in-docker.sh

  4. Run ToaruOS in VirtualBox or VMware Workstation

    master

    For the best end-user experience, use VirtualBox or VMware Workstation, as ToaruOS supports automatic display sizing and absolute mouse positioning in these environments.

    Recommended VM Configuration:

    • Type: "Other" 64-bit guest
    • RAM: At least 1GiB
    • Network: Intel Gigabit NIC
    • CPU: Two or more CPUs recommended
    • Storage: Attach the CD image; hard disks can be removed or ignored.

    Bootloader Options:

    • Seamless Mode: By default, Seamless support is disabled for performance. To enable it, select "VirtualBox Seamless" in the bootloader menu before booting.
    • Display Sizing: If you encounter issues with automatic display sizing, you can disable it via the bootloader menu.

  5. Use the ToaruOS shell and command line

    master

    The ToaruOS shell provides a Unix-like environment but is incomplete.

    • To view syntax and built-in functions, run the help command.
    • To see a list of available commands, press Tab twice.
    • Tab completion is supported for both commands and filenames.

  7. Run ToaruOS in QEMU

    master

    QEMU is recommended for development due to its hardware flexibility and debugging capabilities.

    A recommended command line for an Ubuntu 20.04 host is:

    qemu-system-x86_64 -enable-kvm -m 1G -device AC97 -cdrom image.iso -smp 2

    Notes:

    • If not using KVM, replace -enable-kvm with -accel hvm or -accel haxm (depending on your host), or remove it entirely for TCG software emulation.
    • Using the -M q35 flag replaces the PIIX chipset with a newer one. This switches the IDE controller to SATA, which may result in faster boot times, but ToaruOS may not be able to read its own CD at runtime until the AHCI driver is implemented.
    qemu-system-x86_64 -enable-kvm -m 1G -device AC97 -cdrom image.iso -smp 2

  8. Initialize the ToaruOS build toolchain using Docker

    master

    Follow these steps to clone the repository, build the toolchain inside a Docker container, and move the resulting local toolchain to the appropriate directory.

    1. Build the base image using docker build ..
    2. Run the container interactively with a bash shell: docker run -it <image_name> bash.
    3. Inside the container, execute the following sequence to clone the repository, build the toolchain, and relocate the binaries:
    cd
git clone --recurse-submodules https://github.com/toaruos/misaka
cd misaka
util/build-toolchain.sh
cd util/build/binutils
while [[ -e confdir3/confdir3 ]]; do mv confdir3/confdir3 confdir3a; rmdir confdir3; mv confdir3a confdir3; done; rmdir confdir3
cd ../../..
mv local /root/gcc_local
cd /root
rm -rf misaka

  10. Boot ToaruOS using Multiboot2

    master

    ToaruOS complies with the Multiboot and Multiboot 2 specifications. If the native BIOS or EFI loaders fail, you can boot using the multiboot or multiboot2 commands (e.g., in GRUB):

    multiboot2 /path/to/misaka-kernel root=/dev/ram0 migrate vid=auto start=live-session
module2 /path/to/ramdisk.igz
set gfxpayload=keep
    multiboot2 /path/to/misaka-kernel root=/dev/ram0 migrate vid=auto start=live-session
module2 /path/to/ramdisk.igz
set gfxpayload=keep