From b01878cd3ca1ad710c970d1ab19897091332f78a Mon Sep 17 00:00:00 2001 From: apio Date: Sun, 18 Dec 2022 14:55:04 +0100 Subject: [PATCH] Update README.md --- README.md | 43 ++++++++++++++++++++++++++++--------------- 1 file changed, 28 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 2def0b6c..6c4f7b82 100644 --- a/README.md +++ b/README.md @@ -2,16 +2,25 @@ A simple kernel and userspace for the x86_64 platform, written mostly in C++ and C. [![Build Status](https://drone.cloudapio.eu/api/badges/apio/Luna/status.svg?ref=refs/heads/restart)](https://drone.cloudapio.eu/apio/Luna) (rewrite, listed features are currently mostly from the old version) ## Features -- x86_64-compatible [kernel](kernel/). -- Keeps track of which [memory](kernel/src/memory/) is used and which memory is free, and can allocate memory for itself and [user programs](kernel/src/sys/mem.cpp). -- Can read, write and execute files from a [virtual file system](kernel/src/fs/) supporting an initial ramdisk, device pseudo-filesystems... but no hard disks yet. -- Preemptive multitasking, with a round-robin [scheduler](kernel/src/thread/) that can switch between tasks. -- Can [load ELF programs](kernel/src/sys/elf/) from the file system as userspace tasks. -- [System call](kernel/src/sys/) interface and [C Library](libs/libc/), aiming to be mostly POSIX-compatible. -- UNIX-like [multitasking primitives](kernel/src/sys/exec.cpp), which allow user tasks to spawn other tasks. -- Some simple [userspace programs](apps/src/), written in C. -- Simple [command-line shell](apps/src/sh.c), allowing for interactive use of the system. -- Basic multi-user system with [a password file](initrd/etc/passwd) and utilities for [logging in](apps/src/session.c) and [switching users](apps/src/su.c). +- x86_64-compatible [kernel](kernel/). (Rewritten) +- Keeps track of [memory](kernel/src/memory/). (Rewritten) +- Can read, write and execute files from a [virtual file system](kernel/src/fs/) supporting an initial ramdisk, device pseudo-filesystems... but no hard disks yet. (Not there yet) +- Preemptive multitasking, with a round-robin [scheduler](kernel/src/thread/) that can switch between tasks. (Rewritten) +- Can [load ELF programs](kernel/src/sys/elf/) from the file system as userspace tasks. (Not there yet) +- [System call](kernel/src/sys/) interface and [C Library](libs/libc/), aiming to be mostly POSIX-compatible. (Not there yet) +- UNIX-like [multitasking primitives](kernel/src/sys/exec.cpp), which allow user tasks to spawn other tasks. (Not there yet) +- Some simple [userspace programs](apps/src/), written in C. (Not there yet) +- Simple [command-line shell](apps/src/sh.c), allowing for interactive use of the system. (Not there yet) +- Basic multi-user system with [a password file](initrd/etc/passwd) and utilities for [logging in](apps/src/session.c) and [switching users](apps/src/su.c). (Not there yet) + +## New features (in the rewrite) +- Easier [portability](kernel/src/arch), no need to be restricted to x86_64. +- Fully [UTF-8 aware](luna/include/luna/Utf8.h), **everywhere**. +- More [thread](luna/include/luna/Atomic.h) [safety](kernel/src/thread/Spinlock.h). +- Environment-agnostic [utility library](luna/), which can be used in both kernel and userspace. +- Improved [error propagation](luna/include/luna/Result.h), inspired by Rust and SerenityOS. +- Better code quality and readability. +- Build system now uses [CMake](CMakeLists.txt), which makes everything a lot easier. ## Notes - The default user is named 'selene' and you can log into it with the password 'moon'. @@ -34,8 +43,6 @@ This script will check whether you have the required versions of the toolchain a Please beware that building GCC and Binutils can take some time, depending on your machine. ## Building -Yes, there is a Makefile sitting on the top level of the repository. It's tempting. But do not use it directly, since it depends on environment variables set by the build scripts. - There are a variety of scripts for building Luna. `tools/build.sh` will build the kernel, libc and binaries. @@ -52,7 +59,7 @@ There are a variety of scripts for building Luna. `tools/rebuild-iso.sh` will do a clean rebuild, install, and make an ISO disk image. -In most cases, you should just use `build-iso.sh`. +In most cases, you should just use `run.sh`, but if you want to build without running, `build-iso.sh`. ## Running @@ -60,13 +67,13 @@ You should have [QEMU](https://www.qemu.org/) installed. You can choose between 3 run scripts: -`tools/run.sh` is the one you should use in most cases. It will build (only files that have changed since last build), install, make an ISO image, and run Luna in QEMU. +`tools/run.sh` is the one you should use in most cases. It will build changed files, install, make an ISO image, and run Luna in QEMU. `tools/rebuild-and-run.sh` will rebuild, install, make an ISO, and run Luna in QEMU. `tools/debug.sh` will run Luna in QEMU with a port open for GDB to connect to. (run `tools/build-debug.sh`, `tools/gdb.sh`, and then `tools/debug.sh` in a separate terminal for an optimal debugging experience) -Beware that running with optimizations disabled may cause the kernel to behave differently, which is why I don't use it that often. +Beware that running without hardware acceleration does some weird stuff with the memory map, which is why I don't use it that often. Essentially, since `run.sh` builds the toolchain if it hasn't been built, builds Luna if it hasn't been built, and runs it, you could just checkout this repo, run `run.sh`, and you're done. No need for the other scripts. Those are included for more fine-grained control/building step-by-step. @@ -82,8 +89,14 @@ Every hour, my server pulls the latest commits on `main` and builds an hourly IS These images do reflect the latest changes on the `main` branch, but are obviously less stable. Additionally, an hourly image will be skipped if building the latest commit of the project fails. +Until the `restart` branch gets merged, you'll have to build an ISO yourself. + ## Is there third-party software I can use on Luna? +No, not on this branch. + +**ORIGINAL ANSWER** + Yes, actually! Check out the [ports](ports/) directory. Right now, there are very few ports, because our C Library is a bit primitive and doesn't support complex projects.