Repository files navigation

Creates a bootable disk image from a Rust OS kernel.

> cargo install bootimage

First you need to add a dependency on thebootloader crate:

# in your Cargo.toml[dependencies]bootloader ="0.9.8"

Note: At least bootloader version0.5.1 is required sincebootimage 0.7.0. For earlier bootloader versions, usebootimage 0.6.6.

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

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 invokecargo build, forwarding all passed options. Then it will build the specified bootloader together with the kernel to create a bootable disk image.

To run your kernel in QEMU, you can set abootimage 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 theConfiguration section below.

Thebootimage has built-in support for running unit and integration tests of your kernel. For this, you need to use thecustom_tests_framework feature of Rust as describedhere.

Configuration is done through a[package.metadata.bootimage] table in theCargo.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 executablestest-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 executablestest-no-reboot =true

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE orhttp://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT orhttp://opensource.org/licenses/MIT)

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.