75 lines
4.7 KiB
Markdown
75 lines
4.7 KiB
Markdown
# Luna
|
|
A simple kernel and userspace for the x86_64 platform, written mostly in C++.
|
|
|
|
## Features
|
|
Not so much at the moment.
|
|
|
|
- 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 load files from a [virtual file system](kernel/src/fs/) supporting an initial ramdisk, device pseudo-filesystems... but no hard disks yet.
|
|
- Basic preemptive multitasking, round-robin [scheduler](kernel/src/thread/) that can switch between tasks.
|
|
- Can [load userspace ELF programs](kernel/src/sys/elf/) from the file system as user tasks.
|
|
- [System call](kernel/src/sys/) interface and simple [C Library](libs/libc/), aiming to be POSIX-compatible.
|
|
- Some very simple [example programs](apps/), written in C, that then can get loaded and executed by the kernel.
|
|
- UNIX-like [multitasking primitives](kernel/src/sys/exec.cpp), which allow user tasks to spawn other tasks.
|
|
|
|
## 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)).
|
|
|
|
You should start by installing the [required dependencies](https://wiki.osdev.org/GCC_Cross_Compiler#Installing_Dependencies).
|
|
|
|
Then, run `tools/setup.sh` to build the toolchain.
|
|
|
|
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.)
|
|
|
|
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.
|
|
|
|
`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`.
|
|
|
|
## 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`.
|
|
|
|
## Prebuilt images
|
|
|
|
Prebuilt ISO images for every version can be found at [pub.cloudapio.eu](https://pub.cloudapio.eu/luna).
|
|
|
|
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.
|
|
|
|
## License
|
|
Luna is open-source and free software under the [BSD-2 License](LICENSE). |