ableos/HELP.md

What are the requirements?

• A machine with Rustc Tier 1 platform support
• 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
• Run ableos on your machine
• 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
• When you have finished your changes, you can submit a pull request for review here

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 an issue, reg id leaked is a bug

My program isn't running

• Refer to here, 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
• 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 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

How do I report an ableos bug?

• Submit an issue here or report it in the discord

How do I report a compiler bug?

• Submit an issue here or report it in the discord