Skip to content

Conversation

@peppergrayxyz
Copy link

@peppergrayxyz peppergrayxyz commented Nov 1, 2025

Currently, it is difficult to figure out how all parts play together. There is documentation available, but it needs to be pieced together. To make things easier, it would be great to have a basic kernel that is compiled into a basic OS and booted.

Addition in this PR:

  • showcase an OS that boots a minimal kernel using bootloader
  • update usage guides
  • describe the setup of basic-os with basic-kernel in tutorial.md
  • use bashtestmd to create a shell script from the tutorial
  • run the shell script to generate the basic example
  • boot the basic example using qemu and show that it starts and prints a message
  • add generation of basic example from tutorial to CI

This gives newcomers a starting point and can serve as a template for new projects. By generating the basic example from the tutorial and adding this to CI the tutorial and basic example stay consistent and recent.

@peppergrayxyz peppergrayxyz force-pushed the basic_example branch 5 times, most recently from eaf59ab to 7fb97c3 Compare November 1, 2025 02:12
@Freax13
Copy link
Member

Freax13 commented Nov 1, 2025

Thank you for your contribution!

I welcome improvements for our documentation, but I'm not sure that this is going in the right direction. While it's impressive that you can create a full kernel from a bash script generated from a Markdown file, a lot of the sections just contain some commands without much of an explanation of what's going on. In part that's because the tutorial is generating each and every file and sometimes there just isn't much to say. Given this, I'm not sure how the Markdown file adds much value over just providing the files for the user to look at and adding inline comments to add more explanations.
Markdown aside, I like your example. It's cleaner than our tests and looks like a solid base for kernel. I'd welcome keeping that and linking it from our existing usage guide.
I'd prefer improving our existing usage guides instead of replacing it with a new one.

@peppergrayxyz peppergrayxyz force-pushed the basic_example branch 2 times, most recently from 6b4b8c3 to d232672 Compare November 1, 2025 13:52
@peppergrayxyz peppergrayxyz changed the title Add tutorial and basic example Add basic example Nov 1, 2025
@peppergrayxyz peppergrayxyz force-pushed the basic_example branch 2 times, most recently from 63f4bf7 to 73e4e3f Compare November 1, 2025 14:04
@peppergrayxyz
Copy link
Author

Thanks for your Feedback!

I removed the tutorial and updated usage guides. Please take a look if this is going in the right direction now. Happy to make further adjustments!

@peppergrayxyz peppergrayxyz force-pushed the basic_example branch 2 times, most recently from 3f0fded to 1b6b5c7 Compare November 3, 2025 06:14
- showcase an OS that boots a minimal kernel using bootloader
- update usage guides

Signed-off-by: Pepper Gray <hello@peppergray.xyz>
Co-authored-by: Tom Dohrmann <Erbse.13@gmx.de>
Copy link
Member

@Freax13 Freax13 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great work so far! This is almost ready.

Comment on lines +47 to +51
```toml
# .cargo/config.toml
[build]
target = "x86_64-unknown-none"
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
```toml
# .cargo/config.toml
[build]
target = "x86_64-unknown-none"
```

Let's also remove this.

```sh
$ cargo init --bin
```
- Define a [workspace](https://doc.rust-lang.org/cargo/reference/workspaces.html) and add your kernel as a workspace member.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we're specifying the command used to create the top-level crate (cargo init --bin we should do the same for the kernel). We could remove the kernel from the members (and just use members = []) and then use cargo new kernel --bin in the workspace root.

```
Run:
```sh
$ cargo run -- bios
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
$ cargo run -- bios
$ cargo run bios

Let's be consistent with the documentation in create-disk-image.md.

(Also applies to the command below for UEFI)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants