Luna/README.md

# Luna
A simple 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/binfmt/ELF.cpp), [shebang scripts](kernel/src/binfmt/Script.cpp) or [arbitrary binary formats](kernel/src/binfmt/BinaryFormat.h) (registered through kernel modules, which are not supported yet =D).
- 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 almost POSIX-compatible.
- Support for [several third-party programs](ports/), including the [GNU binutils](ports/binutils/PACKAGE) suite of utilities.
- POSIX [signal](libc/src/signal.cpp) support.
- Designed to be [portable](kernel/src/arch), no need to be restricted to x86_64.
- Everything is [UTF-8](libluna/include/luna/Utf8.h).
- [UNIX local domain sockets](kernel/src/net/UnixSocket.cpp), allowing for local IPC.
- [POSIX shared memory](libc/include/sys/mman.h) support.
- 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. No exceptions here :).
- An extensive set of [standard Unix utilities](apps/), from [ls](apps/ls.cpp) to [uname](apps/uname.cpp) to [base64](apps/base64.cpp). Written in modern C++ and very small amounts of code, using Luna's practical [OS library](libos/).

## Setup

To build and run Luna, you will need to build a [cross-compiler](https://wiki.osdev.org/Why_do_I_need_a_Cross_Compiler) and cross-binutils for `x86_64-luna`.

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

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

## Running

To run Luna in a virtual machine, you should have [QEMU](https://www.qemu.org/) installed.

Additionally, the build process needs some extra dependencies to run: `cmake`, `ninja`, `nasm` and `genext2fs`.

`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 a new release is created, 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?

Yes! A ports system is in place, and you can use the build scripts to add some ports to your image. More information in the [Ports](ports/README.md) page.

## License
Luna is open-source and free software under the [BSD-2-Clause 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 2023-08-08 14:04:10 +00:00			`A simple 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: More features 2023-08-08 14:19:38 +00:00			`- Can [load ELF programs](kernel/src/binfmt/ELF.cpp), [shebang scripts](kernel/src/binfmt/Script.cpp) or [arbitrary binary formats](kernel/src/binfmt/BinaryFormat.h) (registered through kernel modules, which are not supported yet =D).`
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).`
README: More features 2023-08-08 14:19:38 +00:00			`- [System call](kernel/src/sys/) interface and [C Library](libc/), aiming to be almost POSIX-compatible.`
			`- Support for [several third-party programs](ports/), including the [GNU binutils](ports/binutils/PACKAGE) suite of utilities.`
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.`
README: More features 2023-08-08 14:19:38 +00:00			`- Everything is [UTF-8](libluna/include/luna/Utf8.h).`
Update README.md 2023-07-30 09:55:08 +00:00			`- [UNIX local domain sockets](kernel/src/net/UnixSocket.cpp), allowing for local IPC.`
README: More features 2023-08-08 14:19:38 +00:00			`- [POSIX shared memory](libc/include/sys/mman.h) support.`
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.`
README: More features 2023-08-08 14:19:38 +00:00			`- Return-oriented [error propagation](libluna/include/luna/Result.h), inspired by Rust and SerenityOS. No exceptions here :).`
			`- An extensive set of [standard Unix utilities](apps/), from [ls](apps/ls.cpp) to [uname](apps/uname.cpp) to [base64](apps/base64.cpp). Written in modern C++ and very small amounts of code, using Luna's practical [OS library](libos/).`
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 2023-07-22 09:45:35 +00:00			To build and run Luna, you will need to build a [cross-compiler](https://wiki.osdev.org/Why_do_I_need_a_Cross_Compiler) and cross-binutils for `x86_64-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
Update README.md 2023-07-22 09:45:35 +00:00			`For this, you should start by installing the [required dependencies](https://wiki.osdev.org/GCC_Cross_Compiler#Installing_Dependencies).`
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`

Update README.md 2023-07-22 09:45:35 +00:00			`To run Luna in a virtual machine, you should have [QEMU](https://www.qemu.org/) installed.`

			Additionally, the build process needs some extra dependencies to run: `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			`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
Update README.md 2023-07-22 09:45:35 +00:00			These images are built manually whenever a new release is created, and thus don't reflect the latest changes on the `main` branch.
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			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?`

ports: Add initial documentation to the port system 2023-07-24 16:29:44 +00:00			`Yes! A ports system is in place, and you can use the build scripts to add some ports to your image. More information in the [Ports](ports/README.md) page.`
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`
Update README.md 2023-07-30 09:55:08 +00:00			`Luna is open-source and free software under the [BSD-2-Clause License](LICENSE).`