Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
101 lines (65 sloc) 3.23 KB


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:

bootimage build --target your_custom_target.json [other_args]

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

If you prefer a cargo subcommand, you can use the equivalent cargo bootimage command:

cargo bootimage --target your_custom_target.json [other_args]


To run your kernel in QEMU, you can use bootimage run:

bootimage run --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.

If you prefer working directly with cargo, you can use bootimage runner as a custom runner in your .cargo/config:

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

Now you can run your kernel through cargo xrun --target […].


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

    # This target is used if no `--target` is passed
    default-target = ""

    # 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


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.

You can’t perform that action at this time.