Luna/README.md

# Luna
A very basic POSIX-based operating system for personal computers, written in C++. [![Build Status](https://drone.cloudapio.eu/api/badges/apio/Luna/status.svg)](https://drone.cloudapio.eu/apio/Luna)

## Another UNIX clone?
[Yes, another UNIX clone](https://wiki.osdev.org/User:Sortie/Yes_Another_Unix_Clone).

## Features
- x86_64-compatible lightweight [kernel](kernel/).
- Preemptive multitasking, with a round-robin [scheduler](kernel/src/thread/).
- [Virtual file system](kernel/src/fs/) with a simple [tmpfs](kernel/src/fs/tmpfs/) and read-only [ext2](kernel/src/fs/ext2/) support.
- Can [load ELF programs](kernel/src/thread/ELF.cpp) from the file system as userspace tasks.
- Boots from an [ext2](apps/preinit.cpp) root filesystem (a bit slow for now).
- [System call](kernel/src/sys/) interface and [C Library](libc/), aiming to be mostly POSIX-compatible.
- POSIX [signal](libc/src/signal.cpp) support.
- Designed to be [portable](kernel/src/arch), no need to be restricted to x86_64.
- Designed around [UTF-8](libluna/include/luna/Utf8.h).
- Environment-agnostic [utility library](libluna/), which can be used in both kernel and userspace.
- Return-oriented [error propagation](libluna/include/luna/Result.h), inspired by Rust and SerenityOS.
- Build system uses [CMake](CMakeLists.txt).

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

Additionally, some extra Luna-specific dependencies you should install are: cmake, ninja, nasm and genext2fs.

Then, run `tools/setup.sh` to build the toolchain.

Please beware that building GCC and Binutils can take some time, depending on your machine.

## Running

You should have [QEMU](https://www.qemu.org/) installed.

`tools/run.sh` is the script you should use in most cases. It will build changed files, install, make an ISO image, and run Luna in QEMU.

If you have no toolchain set up, `run.sh` will build it automatically, which means that you don't necessarily have to run `setup.sh` since `run.sh` does it for you.

## 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, this 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.

## Is there third-party software I can use on Luna?

Not right now, but hopefully we can start porting some software soon!

## 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 to match repository description 2023-05-20 20:00:52 +00:00			`A very basic POSIX-based operating system for personal computers, written in C++. [![Build Status](https://drone.cloudapio.eu/api/badges/apio/Luna/status.svg)](https://drone.cloudapio.eu/apio/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
Add clause about Unix to README.md 2023-04-04 20:57:55 +00:00			`## Another UNIX clone?`
			`[Yes, another UNIX clone](https://wiki.osdev.org/User:Sortie/Yes_Another_Unix_Clone).`

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			`## Features`
Rewrite README.md now that restart is gone 2023-01-08 14:55:01 +00:00			`- x86_64-compatible lightweight [kernel](kernel/).`
kernel+apps+base+tools: Use Ext2 for the root partition file system init is now split into two parts: preinit, which lives in the initrd and prepares the root file system for init, and the actual /usr/bin/init, which lives in the root partition and starts services and reaps zombies. The kernel now looks for /bin/preinit instead of /bin/init as the executable for the init process. All configuration files in initrd/etc have been moved to base/etc. (The plan is to have only moon and preinit in the initrd.) Since the current Ext2 implementation is read-only (and it's on a CDROM so it would be read-only anyways), /home/selene is a tmpfs (as well as /tmp), to allow for a writable home directory. The system is slower now, but that's to expect since the Ext2 code doesn't use caching and the ATA code still uses PIO. 2023-07-10 11:05:06 +00:00			`- Preemptive multitasking, with a round-robin [scheduler](kernel/src/thread/).`
Update README.md 2023-07-01 15:40:29 +00:00			`- [Virtual file system](kernel/src/fs/) with a simple [tmpfs](kernel/src/fs/tmpfs/) and read-only [ext2](kernel/src/fs/ext2/) support.`
README: Update broken link to ELF loader The ELF loader was moved into the thread/ subdirectory in 0c1d33f2ec. 2023-05-10 20:58:37 +00:00			`- Can [load ELF programs](kernel/src/thread/ELF.cpp) from the file system as userspace tasks.`
kernel+apps+base+tools: Use Ext2 for the root partition file system init is now split into two parts: preinit, which lives in the initrd and prepares the root file system for init, and the actual /usr/bin/init, which lives in the root partition and starts services and reaps zombies. The kernel now looks for /bin/preinit instead of /bin/init as the executable for the init process. All configuration files in initrd/etc have been moved to base/etc. (The plan is to have only moon and preinit in the initrd.) Since the current Ext2 implementation is read-only (and it's on a CDROM so it would be read-only anyways), /home/selene is a tmpfs (as well as /tmp), to allow for a writable home directory. The system is slower now, but that's to expect since the Ext2 code doesn't use caching and the ATA code still uses PIO. 2023-07-10 11:05:06 +00:00			`- Boots from an [ext2](apps/preinit.cpp) root filesystem (a bit slow for now).`
Rewrite README.md now that restart is gone 2023-01-08 14:55:01 +00:00			`- [System call](kernel/src/sys/) interface and [C Library](libc/), aiming to be mostly POSIX-compatible.`
Update README.md 2023-07-11 09:50:57 +00:00			`- POSIX [signal](libc/src/signal.cpp) support.`
Rewrite README.md now that restart is gone 2023-01-08 14:55:01 +00:00			`- Designed to be [portable](kernel/src/arch), no need to be restricted to x86_64.`
Update README.md 2023-07-01 15:40:29 +00:00			`- Designed around [UTF-8](libluna/include/luna/Utf8.h).`
README: Update luna/ links to point to libluna/ 2023-03-11 09:37:38 +00:00			`- Environment-agnostic [utility library](libluna/), which can be used in both kernel and userspace.`
			`- Return-oriented [error propagation](libluna/include/luna/Result.h), inspired by Rust and SerenityOS.`
Rewrite README.md now that restart is gone 2023-01-08 14:55:01 +00:00			`- Build system uses [CMake](CMakeLists.txt).`
Update README.md 2022-10-29 08:13:36 +00:00
Rewrite README.md now that restart is gone 2023-01-08 14:55:01 +00:00			`## Setup`
Update README.md 2022-12-07 10:13:16 +00:00
Update README.md 2022-12-04 09:07:56 +00:00			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) 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)).
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
			`You should start by installing the [required dependencies](https://wiki.osdev.org/GCC_Cross_Compiler#Installing_Dependencies).`

Update README.md 2023-07-11 09:50:57 +00:00			`Additionally, some extra Luna-specific dependencies you should install are: cmake, ninja, nasm and genext2fs.`
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 2023-07-11 09:50:57 +00:00			Then, run `tools/setup.sh` to build the toolchain.
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
			`Please beware that building GCC and Binutils can take some time, depending on your machine.`

			`## Running`

			`You should have [QEMU](https://www.qemu.org/) installed.`

Update README.md 2023-07-11 09:50:57 +00:00			`tools/run.sh` is the script you should use in most cases. It will build changed files, install, make an ISO image, and run Luna in QEMU.
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 2023-07-11 09:50:57 +00:00			If you have no toolchain set up, `run.sh` will build it automatically, which means that you don't necessarily have to run `setup.sh` since `run.sh` does it for you.
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-24 19:15:22 +00:00			`Prebuilt ISO images (numbered) for every version can be found at [pub.cloudapio.eu](https://pub.cloudapio.eu/luna/releases).`
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
			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.

Update README.md 2023-07-11 09:50:57 +00:00			Every hour, this 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.
Update README.md with information about hourly builds 2022-10-24 19:12:22 +00:00
			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.

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

Remove old note from README 2023-04-26 20:49:43 +00:00			`Not right now, but hopefully we can start porting some software soon!`
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`
Bring back the OS-Specific Toolchain on restart :^) 2023-01-06 16:35:07 +00:00			`Luna is open-source and free software under the [BSD-2 License](LICENSE).`