forked from AbleOS/ableos
69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
|
### 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)
|