#image #kernel #disk #binary #bootimage

bin+lib bootimage

Tool to create a bootable OS image from a kernel binary

60 releases

0.10.3 Apr 1, 2021
0.10.2 Dec 10, 2020
0.10.1 Aug 3, 2020
0.9.0 Jul 17, 2020
0.2.1 Mar 31, 2018

#98 in Filesystem

Download history 534/week @ 2020-12-29 484/week @ 2021-01-05 495/week @ 2021-01-12 561/week @ 2021-01-19 582/week @ 2021-01-26 686/week @ 2021-02-02 633/week @ 2021-02-09 781/week @ 2021-02-16 494/week @ 2021-02-23 571/week @ 2021-03-02 605/week @ 2021-03-09 562/week @ 2021-03-16 767/week @ 2021-03-23 692/week @ 2021-03-30 673/week @ 2021-04-06 732/week @ 2021-04-13

2,574 downloads per month




Creates a bootable disk image from a Rust OS kernel.


> cargo install bootimage


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

# in your Cargo.toml

bootloader = "0.6.4"

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.


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.


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.


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 is done through a through a [package.metadata.bootimage] table in the Cargo.toml of your kernel. The following options are available:

# 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


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.


~50K SLoC