From ed298701725f2450674b3e5059f7fecfec8c1651 Mon Sep 17 00:00:00 2001 From: apio Date: Mon, 31 Oct 2022 14:48:35 +0100 Subject: [PATCH] Update README.md --- README.md | 84 +++++++++++-------------------------------------------- 1 file changed, 17 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index c7879e0f..25631fa6 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Luna -A simple kernel and userspace for the x86_64 platform, written mostly in C++ and C. +A simple kernel and userspace for the x86_64 platform, currently being rewritten in Rust. -## Features +## Past features (before rewrite) - 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. @@ -13,88 +13,38 @@ A simple kernel and userspace for the x86_64 platform, written mostly in C++ and - 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). -## Notes -- The default user is named 'selene' and you can log into it with the password 'moon'. - ## Setup -To build and run Luna, you will need to build a [GCC Cross-Compiler](https://wiki.osdev.org/Why_do_I_need_a_Cross_Compiler%3F) and cross-binutils for `x86_64-luna`. (Yes, Luna is advanced enough that it can use its own [OS-Specific Toolchain](https://wiki.osdev.org/OS_Specific_Toolchain), instead of a bare metal target like `x86_64-elf`. It is the first of my OS projects to be able to do so. The patches for Binutils and GCC are [binutils.patch](tools/binutils.patch) and [gcc.patch](tools/gcc.patch)). +Start by installing [rustup](https://rustup.rs/) and install the Rust toolchain by running: -You should start by installing the [required dependencies](https://wiki.osdev.org/GCC_Cross_Compiler#Installing_Dependencies). +`rustup default stable` or `rustup default nightly` -Then, run `tools/setup.sh` to build the toolchain. +You also need to add the `rust-src` component: -This script will check whether you have the required versions of the toolchain already setup, and will skip building them if so. (This means that it is used by the build scripts to install the toolchain if it is missing before building, so you could skip running it manually.) +`rustup component add rust-src` -Please beware that building GCC and Binutils can take some time, depending on your machine. +Luna uses the [BOOTBOOT](https://gitlab.com/bztsrc/bootboot) bootloader, so you'll need to build its mkbootimg tool to create disk images with it. + +A script is provided to do so: `tools/setup-bootloader.sh`. It requires GNU Make and git. + +To run Luna, you should install [QEMU](https://qemu.org). You can use another virtual machine, but the run scripts use it by default. ## 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 build scripts, but in most cases, you should just use `build-iso.sh` or `rebuild-iso.sh`. -There are a variety of scripts for building Luna. - -`tools/build.sh` will build the kernel, libc and binaries. - -`tools/rebuild.sh` will do a full rebuild of the kernel, libc and binaries. - -`tools/install.sh` will install those to the system root and initial ramdisk. - -`tools/sync-libc.sh` will install the libc headers to the system root, build libc and install it. - -`tools/build-iso.sh` will build, install, and make an ISO disk image named Luna.iso. - -`tools/build-debug.sh` will rebuild the kernel with debug symbols and optimizations disabled, install, and make an ISO image. This script should only be used when you are going to be running the system with a debugger (such as GDB). - -`tools/build-stable-iso.sh` does the same thing as build-iso.sh, but configures the kernel so that the version does not show the commit hash (used for stable versions). - -`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`. +Or for release builds, `build-stable-iso.sh`. ## Running -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/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 without hardware virtualization/with optimizations disabled may cause the kernel to behave differently, 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. - -You can pass any arguments you want to the run scripts, and those will be forwarded to QEMU. Example: `tools/run.sh -m 512M -net none -machine q35`. +`tools/run.sh`, which will invoke `build-iso.sh` to build any modified files, or `tools/fast-run.sh` that just runs Luna. ## Prebuilt images -Prebuilt ISO images (numbered) for every version can be found at [pub.cloudapio.eu](https://pub.cloudapio.eu/luna/releases). - -These images are built manually whenever I decide to make a new version, and thus don't reflect the latest changes on the `main` branch. - -Every hour, my server pulls the latest commits on `main` and builds an hourly ISO image. The ten most recent ones can be found in the [hourly](https://pub.cloudapio.eu/luna/hourly) directory, and [Luna-latest.iso](https://pub.cloudapio.eu/luna/Luna-latest.iso) should always be symlinked to the newest one. - -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. +Prebuilt ISO images are right now only available for the `main` branch, which contains the Luna repository before the rewrite. +When this rewrite is stable enough/has progressed enough, it will be merged into `main` and prebuilt images will be available. ## Is there third-party software I can use on Luna? -Yes, actually! Check out the [ports](ports/) directory. -Right now, there are very few ports, because our C Library is quite primitive and doesn't support complex projects. -I'm in the process of trying to port the [GNU binutils](https://www.gnu.org/software/binutils/), though. - -You should also keep in mind that it is not possible to compile software written in any language other than C for Luna right now. - -But feel free to try to port some program yourself and add it to the ports directory! - -Port usage: - -`ports/add-port.sh ` will build and add a port to the list of installed ports, and the built port will automatically get installed into the system root every time you run Luna. - -`ports/remove-port.sh ` will remove the port from the list of installed ports, remove built files from the system root, as well as the build directory. - -`ports/make-package.sh ` will compile the port and make a package archive from it, which may be used in the future with a package manager :) +No, you're on the wrong branch right now. Switch to `main` for a system capable of running some third-party programs. ## License Luna is open-source and free software under the [BSD-2 License](LICENSE). \ No newline at end of file