From 7f4a040505da64fbe640e6d3d4a22fb0e502fa57 Mon Sep 17 00:00:00 2001 From: koniifer Date: Sat, 12 Oct 2024 15:53:32 +0100 Subject: [PATCH] WIP help doc --- HELP.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 12 ++-------- 2 files changed, 71 insertions(+), 10 deletions(-) create mode 100644 HELP.md diff --git a/HELP.md b/HELP.md new file mode 100644 index 0000000..47a0f17 --- /dev/null +++ b/HELP.md @@ -0,0 +1,69 @@ +### What are the requirements? +- A machine with [Rustc Tier 1 platform support](https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-1-with-host-tools) +- Rustup +- QEMU (for executing) +- GIT CLI + +### How do I run ableos? +- It is recommended to run ableos under QEMU. Here is how: + - Install QEMU + - Clone ableos + - Go to ableos directory + - Pull the limine submodule with `git submodule update --init` + - Run `cargo repbuild help` + +### How can I contribute? +- [Contribute code](#how-do-i-contribute-code) +- [Run ableos on your machine](#how-do-i-run-ableos) +- Find bugs +- Create media showing ableos + +### How do I contribute code? +- Start by forking ableos +- Write something that runs in the userspace, for example: + - System drivers + - Programs + - Libraries +- Patch bugs and improve code in the kernel +- Ensure that the code is OK to be maintained by asking in the [discord](https://discord.gg/t5Wt3K4YNA) +- When you have finished your changes, you can submit a pull request for review [here](https://git.ablecorp.us/ableos/ableos) + +### repbuild and kernel compile, but QEMU isn't starting +- Ensure you have the `qemu-desktop-{arch}` for your OS and target architecture installed +- Try running again with `--noaccel` if you have QEMU already + +### I have run using repbuild but it's slow +- Ensure release mode is enabled with the `-r` flag +- Remove the `--noaccel` flag if you can +- If both of these are already done, there may be a problem with thee VM, kernel, your program, or the hblang compiler + +### Compiler is complaining about "reg id leaked" +- [Submit](#how-do-i-report-a-compiler-bug) an issue, reg id leaked is a bug + +### My program isn't running +- Refer to [here](#i-have-run-using-repbuild-but-its-slow), it may be that your program is simply starting slowly +- Ensure that your program has a properly written meta.toml file +- Ensure that your program is enabled in [system_config.toml](sysdata/system_config.toml) +- Try running again with `--noaccel`, there is a known bug with some systems that prevents programs from starting. + +### Kernel panic??? Huh??? +- Kernel panics can be caused by improperly using memory (e.g, writing out of bounds) +- Kernel panics are most likely to be caused when accessing memory or using `@eca` for kernel ecalls +- [Report](#how-do-i-report-an-ableos-bug) a kernel panic + +### I am running in release mode but I have no debug info +- Add the `-d` flag for debug info + +### What is `@eca`? How do I use it? +- Eca is an ecall. They are similar to syscalls +- The `@eca` directive takes the following arguments: + - `@eca(ecall_number, reg_1, ..., reg_n)` +- The various ecalls have different arguments that are given by register values +- Most ecalls are wrapped by `stn`, for example, `random`, `buffer`, and `memory` all make use of ecalls +- All ecalls can be found [ecah.rs](kernel/src/holeybytes/ecah.rs) + +### How do I report an ableos bug? +- Submit an issue [here](https://git.ablecorp.us/ableos/ableos/issues) or report it in the [discord](https://discord.gg/t5Wt3K4YNA) + +### How do I report a compiler bug? +- Submit an issue [here](https://git.ablecorp.us/ableos/holeybytes/issues) or report it in the [discord](https://discord.gg/t5Wt3K4YNA) \ No newline at end of file diff --git a/README.md b/README.md index 181fbb1..64217e0 100644 --- a/README.md +++ b/README.md @@ -10,15 +10,7 @@ Donations can be made [here on Liberapay](https://liberapay.com/AbleTheAbove) or # Compiling -AbleOS should be able to be built on any platform which is supported by -[Rustc Tier 1 platform support](https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-1-with-host-tools). - -For running AbleOS, `repbuild` uses QEMU. - -## Steps -1. Ensure you have qemu installed -2. `git submodule update --init` -3. `cargo repbuild run` +See [HELP.md](HELP.md) # Developing -There is a new work in progress developer tool for hblang. \ No newline at end of file +There is a new work in progress developer tool for hblang. (see: dev folder) \ No newline at end of file