Luna/README.md

# Luna
A simple kernel and userspace for the x86_64 platform, currently being rewritten in Rust.

## 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.
- 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).

## Setup
Start by installing [rustup](https://rustup.rs/) and install the Rust toolchain by running:

`rustup default stable` or `rustup default nightly`

You also need to add the `rust-src` component:

`rustup component add rust-src`

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
There are a variety of build scripts, but in most cases, you should just use `build-iso.sh` or `rebuild-iso.sh`.

Or for release builds, `build-stable-iso.sh`.

## Running

`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 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?

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).
Finally, add a README. It's perhaps too long, but that's better than it being too short. 2022-10-07 18:16:44 +00:00			`# Luna`
Update README.md 2022-10-31 13:48:35 +00:00			`A simple kernel and userspace for the x86_64 platform, currently being rewritten in Rust.`
Finally, add a README. It's perhaps too long, but that's better than it being too short. 2022-10-07 18:16:44 +00:00
Update README.md 2022-10-31 13:48:35 +00:00			`## Past features (before rewrite)`
Finally, add a README. It's perhaps too long, but that's better than it being too short. 2022-10-07 18:16:44 +00:00			`- 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).`
Update README.md 2022-10-29 08:13:36 +00:00			`- 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.`
Update README.md with new features 2022-10-17 17:39:34 +00:00			`- UNIX-like [multitasking primitives](kernel/src/sys/exec.cpp), which allow user tasks to spawn other tasks.`
Update README.md 2022-10-29 08:13:36 +00:00			`- 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).`

Finally, add a README. It's perhaps too long, but that's better than it being too short. 2022-10-07 18:16:44 +00:00			`## Setup`
Update README.md 2022-10-31 13:48:35 +00:00			`Start by installing [rustup](https://rustup.rs/) and install the Rust toolchain by running:`
Finally, add a README. It's perhaps too long, but that's better than it being too short. 2022-10-07 18:16:44 +00:00
Update README.md 2022-10-31 13:48:35 +00:00			`rustup default stable` or `rustup default nightly`
Finally, add a README. It's perhaps too long, but that's better than it being too short. 2022-10-07 18:16:44 +00:00
Update README.md 2022-10-31 13:48:35 +00:00			You also need to add the `rust-src` component:
Finally, add a README. It's perhaps too long, but that's better than it being too short. 2022-10-07 18:16:44 +00:00
Update README.md 2022-10-31 13:48:35 +00:00			`rustup component add rust-src`
Finally, add a README. It's perhaps too long, but that's better than it being too short. 2022-10-07 18:16:44 +00:00
Update README.md 2022-10-31 13:48:35 +00:00			`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.`
Finally, add a README. It's perhaps too long, but that's better than it being too short. 2022-10-07 18:16:44 +00:00
Update README.md 2022-10-31 13:48:35 +00:00			A script is provided to do so: `tools/setup-bootloader.sh`. It requires GNU Make and git.
Separate building a debug image and running it, and provide a script for GDB. 2022-10-08 13:32:48 +00:00
Update README.md 2022-10-31 13:48:35 +00:00			`To run Luna, you should install [QEMU](https://qemu.org). You can use another virtual machine, but the run scripts use it by default.`
Finally, add a README. It's perhaps too long, but that's better than it being too short. 2022-10-07 18:16:44 +00:00
Update README.md 2022-10-31 13:48:35 +00:00			`## Building`
			There are a variety of build scripts, but in most cases, you should just use `build-iso.sh` or `rebuild-iso.sh`.
Finally, add a README. It's perhaps too long, but that's better than it being too short. 2022-10-07 18:16:44 +00:00
Update README.md 2022-10-31 13:48:35 +00:00			Or for release builds, `build-stable-iso.sh`.
Finally, add a README. It's perhaps too long, but that's better than it being too short. 2022-10-07 18:16:44 +00:00
			`## Running`

Update README.md 2022-10-31 13:48:35 +00:00			`tools/run.sh`, which will invoke `build-iso.sh` to build any modified files, or `tools/fast-run.sh` that just runs Luna.
Finally, add a README. It's perhaps too long, but that's better than it being too short. 2022-10-07 18:16:44 +00:00
			`## Prebuilt images`

Update README.md 2022-10-31 13:48:35 +00:00			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.
Update README.md with information about hourly builds 2022-10-24 19:12:22 +00:00
600th commit! 1. Update the bc patch to remove an unnecessary line. 2. Update README.md to mention the port system. 3. Improve the port system!! 2022-10-23 15:15:38 +00:00			`## Is there third-party software I can use on Luna?`

Update README.md 2022-10-31 13:48:35 +00:00			No, you're on the wrong branch right now. Switch to `main` for a system capable of running some third-party programs.
600th commit! 1. Update the bc patch to remove an unnecessary line. 2. Update README.md to mention the port system. 3. Improve the port system!! 2022-10-23 15:15:38 +00:00
Finally, add a README. It's perhaps too long, but that's better than it being too short. 2022-10-07 18:16:44 +00:00			`## License`
			`Luna is open-source and free software under the [BSD-2 License](LICENSE).`