• Stars
    star
    752
  • Rank 60,353 (Top 2 %)
  • Language
    Rust
  • License
    Apache License 2.0
  • Created almost 7 years ago
  • Updated 9 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Tool to create bootable disk images from a Rust OS kernel.

bootimage

Creates a bootable disk image from a Rust OS kernel.

Installation

> cargo install bootimage

Usage

First you need to add a dependency on the bootloader crate:

# in your Cargo.toml

[dependencies]
bootloader = "0.9.8"

Note: At least bootloader version 0.5.1 is required since bootimage 0.7.0. For earlier bootloader versions, use bootimage 0.6.6.

If you want to use a custom bootloader with a different name, you can use Cargo's rename functionality.

Building

Now you can build the kernel project and create a bootable disk image from it by running:

cargo bootimage --target your_custom_target.json [other_args]

The command will invoke cargo build, forwarding all passed options. Then it will build the specified bootloader together with the kernel to create a bootable disk image.

Running

To run your kernel in QEMU, you can set a bootimage runner as a custom runner in a .cargo/config file:

[target.'cfg(target_os = "none")']
runner = "bootimage runner"

Then you can run your kernel through:

cargo xrun --target your_custom_target.json [other_args] -- [qemu args]

All arguments after -- are passed to QEMU. If you want to use a custom run command, see the Configuration section below.

Testing

The bootimage has built-in support for running unit and integration tests of your kernel. For this, you need to use the custom_tests_framework feature of Rust as described here.

Configuration

Configuration is done through a [package.metadata.bootimage] table in the Cargo.toml of your kernel. The following options are available:

[package.metadata.bootimage]
# The cargo subcommand that will be used for building the kernel.
#
# For building using the `cargo-xbuild` crate, set this to `xbuild`.
build-command = ["build"]
# The command invoked with the created bootimage (the "{}" will be replaced
# with the path to the bootable disk image)
# Applies to `bootimage run` and `bootimage runner`
run-command = ["qemu-system-x86_64", "-drive", "format=raw,file={}"]

# Additional arguments passed to the run command for non-test executables
# Applies to `bootimage run` and `bootimage runner`
run-args = []

# Additional arguments passed to the run command for test executables
# Applies to `bootimage runner`
test-args = []

# An exit code that should be considered as success for test executables
test-success-exit-code = {integer}

# The timeout for running a test through `bootimage test` or `bootimage runner` (in seconds)
test-timeout = 300

# Whether the `-no-reboot` flag should be passed to test executables
test-no-reboot = true

License

Licensed under either of

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

More Repositories

1

bootloader

An experimental pure-Rust x86 bootloader
Rust
1,368
star
2

uefi-rs

Rusty wrapper for the Unified Extensible Firmware Interface (UEFI). This crate makes it easy to develop Rust software that leverages safe, convenient, and performant abstractions for UEFI functionality.
Rust
1,297
star
3

x86_64

Library to program x86_64 hardware.
Rust
787
star
4

linked-list-allocator

Rust
220
star
5

acpi

Rust library for parsing ACPI tables and interpreting AML
Rust
200
star
6

.github

About this organization
133
star
7

homepage

CSS
119
star
8

multiboot2

Rusty wrappers for Multiboot2.
Rust
110
star
9

volatile

Rust
70
star
10

vga

Library to program vga hardware.
Rust
55
star
11

xhci

A Rust library which is useful to handle xHCI
Rust
41
star
12

spinning_top

A simple spinlock crate based on the abstractions provided by the `lock_api` crate.
Rust
36
star
13

uart_16550

Minimal support for uart_16550 serial output.
Rust
33
star
14

pci_types

Useful types for dealing with PCI
Rust
31
star
15

ovmf-prebuilt

Rust
24
star
16

apic

Rust
15
star
17

ansi_rgb

Colorful terminal text using ANSI escape sequences
Rust
14
star
18

virtio-spec-rs

Definitions from the Virtual I/O Device (VIRTIO) specification.
Rust
12
star
19

endian-num

Byte-order-aware numeric types.
Rust
11
star
20

pic8259

Rust
10
star
21

x86_64_types

Rust
7
star
22

ps2-mouse

Library to manage a PS2 mouse
Rust
7
star
23

ucs2-rs

UCS-2 conversion utilities for Rust.
Rust
6
star
24

usb

Utilities for working with USB devices
Rust
6
star
25

os_bootinfo

Rust
6
star
26

ieee1275-rs

Rudimentary ieee1275/OpenFirmware Rust environment similar to uefi-rs.
Rust
4
star
27

fuse-abi

FUSE device bindings.
Rust
3
star