Skip to content

Commit 3f9571f

Browse files
adamperkowskiadamperkowski
committed
some more docs
1 parent 0a1240c commit 3f9571f

File tree

9 files changed

+705
-5
lines changed

9 files changed

+705
-5
lines changed

‎book/book.toml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,11 @@ title = "HighlightOS"
77

88
[output.html]
99
cname = "os.adamperkowski.dev"
10-
#default-theme = "colibri"
11-
#preferred-dark-theme = "colibri"
10+
default-theme = "highlight"
11+
preferred-dark-theme = "highlight"
1212
git-repository-url = "https://github.com/adamperkowski/highlightos"
1313
edit-url-template = "https://github.com/adamperkowski/highlightos/edit/master/book/{path}"
14-
#additional-css = ["custom.css"]
14+
additional-css = ["./theme/custom.css"]
1515

1616
[output.html.search]
1717
use-boolean-and = true

‎book/src/SUMMARY.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
11
# Summary
22

3-
- [HighlightOS](./highlightos.md)
3+
[HighlightOS](./highlightos.md)
4+
5+
- [Usage](./usage.md)
6+
- [Building from source](./building.md)
7+
- [Core](./core.md)
8+
- [Commands](./commands.md)

‎book/src/building.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Building from source
2+
## Main kernel (on x86_64 Linux)
3+
**Requirements:**
4+
- [Git](https://git-scm.com) version control system
5+
- [Rust toolchain](https://www.rust-lang.org/tools/install)
6+
7+
**Steps:**
8+
1. Install the nightly toolchain:
9+
```bash
10+
rustup toolchain install nightly
11+
```
12+
2. Install required components:
13+
```bash
14+
rustup component add rust-src --toolchain nightly-x86_64-unknown-linux-gnu && rustup component add llvm-tools-preview --toolchain nightly-x86_64-unknown-linux-gnu && cargo install bootimage
15+
```
16+
3. Create a local clone of the repository:
17+
```bash
18+
git clone [email protected]:adamperkowski/highlightos.git && cd highlightos
19+
```
20+
4. `cd` into the `kernel/` directory:
21+
```bash
22+
cd kernel
23+
```
24+
5. Build the bootable binary:
25+
```bash
26+
cargo bootimage --release
27+
```
28+
This command will create a `target/target/release` directory in which you'll find the `bootimage-hlkernel.bin` binary file.

‎book/src/commands.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Built-in commands
2+
* `clrs` > clears the screen
3+
* `help` > shows the list of built-in commands
4+
* `test` > this one always returns `2` (see [return codes](https://github.com/adamperkowski/highlightos/wiki/core#return-codes))
5+
* `cc` > displays copyright info (see [license](https://github.com/adamperkowski/highlightos/blob/main/LICENSE))
6+
* `getdoc [cmd]` > displays a short summary of provided command
7+
* `chcolor [fg] [bg]` > changes console text colors (see [available colors](https://github.com/adamperkowski/highlightos/wiki/Core#currently-available-colors-user))
8+
9+
## DEBUG commands:
10+
* `crash_kernel` > `panic!`s the system

‎book/src/core.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Core structure
2+
## Prompt input
3+
Current buffer can be interrupted by pressing <kbd>F1</kbd>.
4+
5+
The shell keeps a history of all commands executed.<br>History can be browsed with the `history` command or <kbd>&#8593;</kbd> and <kbd>&#8595;</kbd> keys.
6+
## Command return codes
7+
* `0` > executed successfully
8+
* `1` > "silent" return code - doesn't show the message
9+
* `2` > returned general error (minor)
10+
* `3` > returned critical error (could not recover)
11+
* `4` > returned user error (ex. incorrect input)
12+
13+
## Colors
14+
**Currently available colors (user):**
15+
* `black`
16+
* `blue`
17+
* `green`
18+
* `cyan`
19+
* `red`
20+
* `magenta`
21+
* `brown`
22+
* `lightgray`
23+
* `lightgreen`
24+
* `lightcyan`
25+
* `lightred`
26+
* `yellow`
27+
* `white`

‎book/src/highlightos.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# HighlightOS
2-
32
x86_64 OS (kernel) made completely from scratch in Assembly & Rust
43

4+
This documentation includes only the "main kernel" (inside the `/kernel` directory).
5+
56
Documentation for bleeding-edge main can be found at [https://os.adamperkowski.dev/main](https://os.adamperkowski.dev/main).
7+
8+
Keep in mind that this website is still a WIP.

‎book/src/usage.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Usage
2+
## Running in QEMU on Linux
3+
**Requirements:**
4+
- [QEMU](https://www.qemu.org/download/#linux) (full package)
5+
- A bootable binary of HighlightOS<br>You can download one from [releases](https://github.com/adamperkowski/highlightos/releases) or you can [build it yourself](./building.html).
6+
7+
**Steps:**
8+
1. `cd` into directory that contains the binary.
9+
2. Run the following command:
10+
```
11+
qemu-system-x86_64 -drive format=raw,file=<your_binary_filename>.bin
12+
```
13+
Replace `<your_binary_filename>` with the actual name of the HighlightOS binary.
14+
15+
## Running on real hardware
16+
You can also flash the binary image onto a USB stick and boot it on a real machine.
17+
18+
You can flash it by running the following command:
19+
```
20+
dd if=<your_binary_filename>.bin of=/dev/sdX && sync
21+
```
22+
23+
Make sure to replace `<your_binary_filename>.bin` with your downloaded/compiled binary name and make sure to replace `/dev/sdX` with your USB's actual partition number.<br>**Any data on it will be lost!**
24+
25+
You can choose the device to boot off of from your BIOS boot menu (accessible by pressing <kbd>F2</kbd>, <kbd>F8</kbd> or <kbd>F12</kbd> - depending on your motherboard).
26+
27+
**<ins>Double-check that your motherboard is capable of booting legacy media(s)</ins>, as HighlightOS is not UEFI-compatible yet.**

0 commit comments

Comments
 (0)