Tool to create bootable disk images from a Rust OS kernel.
Creates a bootable disk image from a Rust OS kernel.
> cargo install bootimage
First you need to add a dependency on the
bootloadercrate:
# in your Cargo.toml[dependencies] bootloader = "0.6.4"
Note: At least bootloader version
0.5.1is 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 runneras a custom runner in a
.cargo/configfile:
[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
bootimagehas built-in support for running unit and integration tests of your kernel. For this, you need to use the
custom_tests_frameworkfeature of Rust as described here.
Configuration is done through a through a
[package.metadata.bootimage]table in the
Cargo.tomlof 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
andbootimage 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
orbootimage runner
(in seconds)test-timeout = 300
Whether the
-no-reboot
flag should be passed to test executablestest-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.