Skip to content

Commit

Permalink
chore: move dev docs to CONTRIBUTING.md (#289)
Browse files Browse the repository at this point in the history
this commit moves the developer docs to `CONTRIBUTING.md` and adds new
README.md text explaining what Mycelium actually *is*.
  • Loading branch information
hawkw authored Aug 2, 2022
1 parent 42249a3 commit c0bf72e
Show file tree
Hide file tree
Showing 2 changed files with 167 additions and 83 deletions.
107 changes: 107 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
# contributing to mycelium

thanks for your interest in contributing to Mycelium, an alleged "operating
system"! please bear in mind that this is a hobby project that i work on in my
spare time, so pull requests may not always be reviewed in a timely manner.

## building & running

mycelium is built using [`inoculate`], the horrible mycelium build tool.

`inoculate` automates the process of compiling the kernel and bootloader and
producing a bootable mycelium disk image. it also provides a test runner for
running kernel-mode tests in [QEMU], running the release kernel in [QEMU], and
launching a [`gdb`] debugging session.

```text
inoculate 0.1.0
the horrible mycelium build tool (because that's a thing we have to have now apparently!)
USAGE:
inoculate [OPTIONS] <kernel-bin> [SUBCOMMAND]
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
--bootloader-manifest <bootloader-manifest>
The path to the `bootloader` crate's Cargo manifest. If this is not provided, it will be located
automatically
--color <color>
Whether to emit colors in output [env: CARGO_TERM_COLORS=] [default: auto] [possible values: auto, always,
never]
--kernel-manifest <kernel-manifest>
The path to the kernel's Cargo manifest. If this is not provided, it will be located automatically
-l, --log <log> Configures build logging [env: RUST_LOG=] [default: warn]
-o, --out-dir <out-dir> Overrides the directory in which to build the output image
-t, --target-dir <target-dir> Overrides the target directory for the kernel build
ARGS:
<kernel-bin> The path to the kernel binary
SUBCOMMANDS:
help Prints this message or the help of the given subcommand(s)
run Builds a bootable disk image and runs it in QEMU (implies: `build`)
test Builds a bootable disk image with tests enabled, and runs the tests in QEMU
```

[`inoculate`]: https://github.com/hawkw/mycelium/tree/main/inoculate

### cargo aliases

the following [cargo aliases] are provided for development:

- `cargo inoculate` runs any `inoculate` subcommand
- `cargo run-x64` runs the x86_64 kernel in QEMU
- `cargo test-x64` runs the x86_64 kernel's kernel-mode test suite in QEMU
- `cargo build-x64` builds the x86_64 bootable disk image
- `cargo clippy-x64` runs the [clippy] linter with the kernel x86_64 target
enabled (rather than the build host's target triple).

[cargo aliases]: https://github.com/hawkw/mycelium/blob/main/.cargo/config
[clippy]: https://github.com/rust-lang/rust-clippy

### build dependencies

to build mycelium for x86_64, you need the following:

- a nightly rust compiler
- the `rust-src` and `llvm-tools-preview` Rust toolchain components

the `rust-src` and `llvm-tools-preview` toolchain components are required in the
[`rust-toolchain.toml`] file, so in most cases, rustup will install them
automatically. if, for whatever reason, they are not present, you can install
them manually with:

```shell
rustup component add rust-src llvm-tools-preview
```

[`rust-toolchain.toml`]: https://github.com/hawkw/mycelium/blob/main/rust-toolchain.toml

### runtime dependencies & tools

to run the mycelium kernel-mode tests, or to run an interactive mycelium session
using `inoculate`, you need the [QEMU] emulator; in particular,
`qemu-system-x86_64` to run the x86_64 mycelium kernel. you can install QEMU
using your favorite package manager.

similarly, to use `inoculate`'s support for [`gdb`] (the GNU debugger), you need
`gdb` installed on your system. it's probably also possible to debug mycelium with
`lldb` somehow, but i haven't tried that.

for NixOS users, there's an included [`shell.nix`] which can be used with
[`nix-shell`] or [`direnv`]. this should ensure all required runtime
dependencies and tools are present.

for users of other package managers, you're on your own...but if there's a
similar mechanism for installing the required dev tooling for a project from a
config file, i'd welcome a PR to add support for your preferred package manager.

[QEMU]: https://www.qemu.org/
[`gdb`]: https://www.gnu.org/software/gdb/
[`shell.nix`]: https://github.com/hawkw/mycelium/blob/main/shell.nix
[`nix-shell`]: https://nixos.wiki/wiki/Development_environment_with_nix-shell
[`direnv`]: https://direnv.net/
143 changes: 60 additions & 83 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,104 +15,81 @@ someday this will do stuff
[tests-url]: https://github.com/hawkw/mycelium/actions/workflows/ci.yml
[sponsor-badge]: https://img.shields.io/badge/sponsor-%F0%9F%A4%8D-ff69b4
[sponsor-url]: https://github.com/sponsors/hawkw
## building & running

mycelium is built using [`inoculate`], the horrible mycelium build tool.

`inoculate` automates the process of compiling the kernel and bootloader and
producing a bootable mycelium disk image. it also provides a test runner for
running kernel-mode tests in QEMU, running the release kernel in QEMU, and
launching a [`gdb`] debugging session.

```text
inoculate 0.1.0
the horrible mycelium build tool (because that's a thing we have to have now apparently!)
USAGE:
inoculate [OPTIONS] <kernel-bin> [SUBCOMMAND]
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
--bootloader-manifest <bootloader-manifest>
The path to the `bootloader` crate's Cargo manifest. If this is not provided, it will be located
automatically
--color <color>
Whether to emit colors in output [env: CARGO_TERM_COLORS=] [default: auto] [possible values: auto, always,
never]
--kernel-manifest <kernel-manifest>
The path to the kernel's Cargo manifest. If this is not provided, it will be located automatically
-l, --log <log> Configures build logging [env: RUST_LOG=] [default: warn]
-o, --out-dir <out-dir> Overrides the directory in which to build the output image
-t, --target-dir <target-dir> Overrides the target directory for the kernel build
ARGS:
<kernel-bin> The path to the kernel binary
SUBCOMMANDS:
help Prints this message or the help of the given subcommand(s)
run Builds a bootable disk image and runs it in QEMU (implies: `build`)
test Builds a bootable disk image with tests enabled, and runs the tests in QEMU
```

[`inoculate`]: https://github.com/hawkw/mycelium/tree/main/inoculate
## what is it?

### cargo aliases
this repository contains Mycelium, an alleged "operating system", and a
collection of Rust libraries written as part of its development. eventually,
Mycelium will be a microkernel-ish operating system that runs on commodity
desktop hardware, executes [WebAssembly] modules in both kernel- and user-space,
and implements the [WebAssembly System Interface][wasi] (or _WASI_) as its syscall layer.

the following [cargo aliases] are provided for development:
right now, though, it runs...[_one_ webassembly module][helloworld], which
prints "hello world" and immediately exits. so that's coming along great,
thanks for asking.

- `cargo inoculate` runs any `inoculate` subcommand
- `cargo run-x64` runs the x86_64 kernel in QEMU
- `cargo test-x64` runs the x86_64 kernel's kernel-mode test suite in QEMU
- `cargo build-x64` builds the x86_64 bootable disk image
- `cargo clippy-x64` runs the [clippy] linter with the kernel x86_64 target
enabled (rather than the build host's target triple).
## crates

[cargo aliases]: https://github.com/hawkw/mycelium/blob/main/.cargo/config
[clippy]: https://github.com/rust-lang/rust-clippy
> "what if the real operating system was the libraries we wrote along the way?"
### build dependencies
in the process of implementing Mycelium itself, we've written a whole bunch of
Rust libraries, which also live in this repository. some of these libraries may
be generally useful for other projects, and have been or will be published to
[crates.io].

to build mycelium for x86_64, you need the following:
the general-purpose crates in this repository include:

- a nightly rust compiler
- the `rust-src` and `llvm-tools-preview` Rust toolchain components
- [`cordyceps`]: a library of [intrusive data structures][intrusive], including
linked lists and lock-free MPSC queues,
- [`maitake`]: an "async runtime construction kit" for using Rust's async/await
in bare metal applications such as operating systems,
- [`mycelium-alloc`]: an implementation of a [buddy-block memory allocator][buddy],
- [`mycelium-bitfield`]: a bitfield library based on const eval and declarative
macros,
- [`mycelium-util`]: a "standard library" of reusable components for bare-metal
`no_std` Rust projects, such as `no_std` synchronization primitives.

the `rust-src` and `llvm-tools-preview` toolchain components are required in the
[`rust-toolchain.toml`] file, so in most cases, rustup will install them
automatically. if, for whatever reason, they are not present, you can install
them manually with:
in addition, beyond the kernel itself, this repository also contains the
following Mycelium components:

```shell
rustup component add rust-src llvm-tools-preview
```
- [`hal-core`]: the core interface definitions of Mycelium's (admittedly
somewhat half-baked) hardware abstraction layer,
- [`hal-x86_64`]: implementations of the Mycelium HAL for 64-bit x86 (amd64)
CPUs,
- [`mycotest`]: testing utilities for Mycelium's in-kernel tests,
- [`inoculate`]: Mycelium's Horrible Build Tool™

[`rust-toolchain.toml`]: https://github.com/hawkw/mycelium/blob/main/rust-toolchain.toml
## how do i run it?

### runtime dependencies & tools
so...how do i actually build and run Mycelium?

to run the mycelium kernel-mode tests, or to run an interactive mycelium session
using `inoculate`, you need the [QEMU] emulator; in particular,
`qemu-system-x86_64` to run the x86_64 mycelium kernel. you can install QEMU
using your favorite package manager.
the easiest way to run the Mycelium kernel (using the [QEMU] emulator) is to use
[`inoculate`], Mycelium's Horrible Build Tool™. to launch Mycelium in [QEMU], run

similarly, to use `inoculate`'s support for [`gdb`] (the GNU debugger), you need
`gdb` installed on your system. it's probably also possible to debug mycelium with
`lldb` somehow, but i haven't tried that.
```console
cargo run-x64
```

for NixOS users, there's an included [`shell.nix`] which can be used with
[`nix-shell`] or [`direnv`]. this should ensure all required runtime
dependencies and tools are present.
see [CONTRIBUTING.md] for details on development environment setup and tools.

[WebAssembly]: https://webassembly.org/
[wasi]: https://github.com/WebAssembly/WASI
[helloworld]: https://github.com/hawkw/mycelium/blob/main/src/helloworld.wast
[crates.io]: https://crates.io

[`cordyceps`]: https://github.com/hawkw/mycelium/tree/main/cordyceps
[`maitake`]: https://github.com/hawkw/mycelium/tree/main/maitake
[`mycelium-alloc`]: https://github.com/hawkw/mycelium/tree/main/alloc
[`mycelium-bitfield`]: https://github.com/hawkw/mycelium/tree/main/bitfield
[`mycelium-util`]: https://github.com/hawkw/mycelium/tree/main/util
[`hal-core`]: https://github.com/hawkw/mycelium/tree/main/hal-core
[`hal-x86_64`]: https://github.com/hawkw/mycelium/tree/main/hal-x86_64
[`mycotest`]: https://github.com/hawkw/mycelium/tree/main/mycotest
[`inoculate`]: https://github.com/hawkw/mycelium/tree/main/inoculate

for users of other package managers, you're on your own...but if there's a
similar mechanism for installing the required dev tooling for a project from a
config file, i'd welcome a PR to add support for your preferred package manager.
[intrusive]:
https://www.boost.org/doc/libs/1_45_0/doc/html/intrusive/intrusive_vs_nontrusive.html
[buddy]: https://en.wikipedia.org/wiki/Buddy_memory_allocation

[QEMU]: https://www.qemu.org/
[`gdb`]: https://www.gnu.org/software/gdb/
[`shell.nix`]: https://github.com/hawkw/mycelium/blob/main/shell.nix
[`nix-shell`]: https://nixos.wiki/wiki/Development_environment_with_nix-shell
[`direnv`]: https://direnv.net/
[CONTRIBUTING.md]: https://github.com/hawkw/mycelium/blob/main/CONTRIBUTING.md

0 comments on commit c0bf72e

Please sign in to comment.