A Minimal Rust Kernel (zh-CN)

[utterances-bot]

This is a general purpose comment thread for the “A Minimal Rust Kernel (zh-CN)” post.

Please note that I (@phil-opp) do not speak Chinese, so please comment in English if possible.

[GCYYfun]

抱歉有一个疑问、文章中"设置默认目标"的一节、最后直接使用的命令是否应该是、

cargo xbuild

[phil-opp]

cc @Rustin-Liu @luojia65 Maybe you can help here? (I don't speak Chinese)

[12101111]

是的，应该cargo xbuild 而不是cargo build
https://os.phil-opp.com/minimal-rust-kernel/#set-a-default-target

[luojia65]

GCYYfun commented 6 hours ago
I'm sorry but I have a question, in the section Setting Default Target section of this article, should the command used directly at last be:
cargo xbuild?

12101111 commented 4 hours ago
Yes this should be cargo xbuild instead of cargo build. (link)

[phil-opp]

@luojia65 Thanks a lot for translating! Seems like this was fixed in #794.

[luojia65]

似乎已经修好了，感谢。我的repo里也得改改（回头验证一下
Thank you! @phil-opp

[Qcalgos]

使用cargo bootimage 命令时候，需要在Cargo.toml中配置使用xbuild进行编译。如下：
[package.metadata.bootimage]
build-command = ["xbuild"]
因为cargo bootimage默认使用build，而不是xbuild。

[Selenium39]

good

[fuchk]

我用了然后变成这样了
Error: Failed to read bootimage configuration: unexpected package.metadata.bootimage key build-command with value ["xbuild"]

[curtainp]

when i use cargo bootimage to build bootable image, i see this error,
Compiling bootloader v0.9.16
error[E0463]: can't find crate for std
how can i resolve this, thanks

[phil-opp]

@curtainp Looks like you somehow depend on the standard library. Did you set the #![no_std] attribute?

[curtainp]

yes, and all step follow the blog,

// no_std attribute disable automatic include std
#![no_std]
// disable runtime entry
#![no_main]

with nightly version rust installed
rustc 1.53.0-nightly (5d04957a4 2021-03-22)
from where the error occur(i use cargo bootimage --verbose), when compiling bootloader, maybe not the kernel code problem?

[phil-opp]

Do you have your code online somewhere so that I can take a look?

[curtainp]

https://gitee.com/keleidoscope/blog_os.git

[phil-opp]

You need to compile your code for the custom target. The command cargo bootimage --target x86_64_blog_os.json works without problems with your project.

[curtainp]

yeah，i get it， thanks a lot

[Calvin-he]

failed to run "cargo bootimage"

WARNING: `CARGO_MANIFEST_DIR` env variable not set
Building kernel
   Compiling bootloader v0.9.16
error[E0463]: can't find crate for `core`
  |
  = note: the `x86_64-blog_os-9927342838811049115` target may not be installed

error: aborting due to previous error

For more information about this error, try `rustc --explain E0463`.
error: could not compile `bootloader`

To learn more, run the command again with --verbose.
Error: Kernel build failed.

[hai1222]

cargo install bootimage
安装失败，报一堆错

help: consider importing this tuple variant
    |
638 |     use core::option::Option::Some;
    |

error[E0433]: failed to resolve: use of undeclared type `Vec`
  --> /home/work/.cargo/registry/src/github.com-1ecc6299db9ec823/anyhow-1.0.66/src/chain.rs:61:32
   |
61 |                 let mut rest = Vec::new();
   |                                ^^^ use of undeclared type `Vec`

error[E0433]: failed to resolve: use of undeclared type `Vec`
  --> /home/work/.cargo/registry/src/github.com-1ecc6299db9ec823/anyhow-1.0.66/src/chain.rs:98:23
   |
98 |                 rest: Vec::new().into_iter(),
   |                       ^^^ use of undeclared type `Vec`

Some errors have detailed explanations: E0405, E0412, E0425, E0432, E0433, E0463, E0531.
error: could not compile `anyhow` due to 246 previous errors

[phil-opp]

Please try to run the cargo install bootimage command from a different directory, e.g. your home directory.

[hai1222]

谢谢，可以了

[QineGeYu]

我无论在主目录还是项目中运行cargo install bootimage都报错
error[E0773]: attempted to define built-in macro more than once
--> /home/mrxie/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/macros/mod.rs:1470:5
|
1470 | macro_rules! cfg {
| ^^^^^^^^^^^^^^^^
|
note: previously defined here
--> /home/mrxie/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/macros/mod.rs:1470:5
|
1470 | macro_rules! cfg {
| ^^^^^^^^^^^^^^^^

error[E0152]: duplicate lang item in crate core (which std depends on): sized
|
= note: the lang item is first defined in crate core (which memchr depends on)
= note: first definition in core loaded from /tmp/cargo-installkjt27M/release/deps/libcore-de7b5b6595e1bc1e.rmeta
= note: second definition in core loaded from /home/mrxie/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/lib/libcore-d453bab70303062c.rlib

Some errors have detailed explanations: E0152, E0773.

[QineGeYu]

重装rust，然后在主目录运行cargo install bootimage成功了

[Natane0808]

This error occurs when I run with the cargo bootimage

WARNING: You're currently building for the host system. This is likely an error and will cause build scripts of dependencies to break.

To build for the target system either pass a `--target` argument or set the build.target configuration key in a `.cargo/config` file.

   Compiling core v0.0.0 (D:\software\Rust\rustup\toolchains\nightly-x86_64-pc-windows-msvc\lib\rustlib\src\rust\library\core)
   Compiling compiler_builtins v0.1.85
   Compiling rustc-std-workspace-core v1.99.0 (D:\software\Rust\rustup\toolchains\nightly-x86_64-pc-windows-msvc\lib\rustlib\src\rust\library\rustc-std-workspace-core)
error[E0464]: multiple candidates for `rmeta` dependency `core` found
 --> D:\software\Rust\rustup\toolchains\nightly-x86_64-pc-windows-msvc\lib\rustlib\src\rust\library\rustc-std-workspace-core\lib.rs:4:9
  |
4 | pub use core::*;
  |         ^^^^
  |
  = note: candidate #1: \\?\C:\Users\Natane\AppData\Local\Temp\cargo-xbuildyO6xyB\target\x86_64-pc-windows-msvc\release\deps\libcore-2e6fd6313c7cdeab.rmeta
  = note: candidate #2: \\?\C:\Users\Natane\AppData\Local\Temp\cargo-xbuildyO6xyB\target\x86_64-pc-windows-msvc\release\deps\libcore-a7f88337d798d6c7.rmeta

For more information about this error, try `rustc --explain E0464`.
error: could not compile `rustc-std-workspace-core` due to previous error
warning: build failed, waiting for other jobs to finish...
error: `"\\\\?\\D:\\software\\Rust\\rustup\\toolchains\\nightly-x86_64-pc-windows-msvc\\bin\\cargo.exe" "rustc" "-p" "alloc" "--release" "--manifest-path" "C:\\Users\\Natane\\AppData\\Local\\Temp\\cargo-xbuildyO6xyB\\Cargo.toml" "--target" "x86_64-pc-windows-msvc" "--" "-Z" "force-unstable-if-unmarked"` failed with exit code: Some(101)

[linkypi]

@phil-opp I have tried cargo clean to clean, but can not fixed the problem. Could you help me find the problem when you have time ? My project link is my_os, Thanks a lot.

It does not have any warnings now when I try export CARGO_MANIFEST_DIR=~/Desktop/rust/my_os first ,
and then run cargo bootimage --target x86_64-my_os.json

> cargo clean
     Removed 3 files, 2.9KiB total
> export CARGO_MANIFEST_DIR=~/Desktop/rust/my_os
> cargo bootimage --target x86_64-my_os.json 
Building kernel
   Compiling compiler_builtins v0.1.108
   Compiling core v0.0.0 (/home/lynch/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core)
   Compiling rustc-std-workspace-core v1.99.0 (/home/lynch/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/rustc-std-workspace-core)
   Compiling alloc v0.0.0 (/home/lynch/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/alloc)
error[E0464]: multiple candidates for `rmeta` dependency `core` found
 --> /home/lynch/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/rustc-std-workspace-core/lib.rs:4:9
  |
4 | pub use core::*;
  |         ^^^^
  |
  = note: candidate #1: /tmp/cargo-xbuildOPZAyN/target/x86_64-my_os/release/deps/libcore-5f13781266999769.rmeta
  = note: candidate #2: /tmp/cargo-xbuildOPZAyN/target/x86_64-my_os/release/deps/libcore-4697982036cf9e0d.rmeta

For more information about this error, try `rustc --explain E0464`.
error: could not compile `rustc-std-workspace-core` (lib) due to 1 previous error
warning: build failed, waiting for other jobs to finish...
error: `CARGO_TARGET_DIR="/tmp/cargo-xbuildOPZAyN/target" RUSTFLAGS="-Cembed-bitcode=yes" RUST_TARGET_PATH="" __CARGO_DEFAULT_LIB_METADATA="XARGO" "/home/lynch/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/bin/cargo" "rustc" "-p" "alloc" "--release" "--manifest-path" "/tmp/cargo-xbuildOPZAyN/Cargo.toml" "--target" "x86_64-my_os.json" "--" "-Z" "force-unstable-if-unmarked"` failed with exit code: Some(101)
Error: Kernel build failed.
Stderr: 

[linkypi]

I think I have found the reason, but I don't know why.

1. use bootloader version 0.9.8 instead of the lastest version 0.11.7 in Cargo.toml.
2. comment the build-std in .cargo/config.toml
3. run cargo bootimage... and booting in qemu

It work well both in Windows and Ubuntu.

[dependencies]
bootloader = "0.9.8"

[unstable]
build-std-features = ["compiler-builtins-mem"]
# build-std = ["compiler_builtins","alloc"]

> cargo bootimage --target .\x86_64-my_os.json
WARNING: `CARGO_MANIFEST_DIR` env variable not set
Building kernel
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.01s
Building bootloader
   Compiling compiler_builtins v0.1.108
   Compiling core v0.0.0 (C:\Users\troub\.rustup\toolchains\nightly-x86_64-pc-windows-msvc\lib\rustlib\src\rust\library\core)
   Compiling serde v1.0.116
   Compiling bitflags v1.2.1
   Compiling llvm-tools v0.1.1
   Compiling x86_64 v0.14.7
   Compiling toml v0.5.6
   Compiling bootloader v0.9.28 (C:\Users\troub\.cargo\registry\src\index.crates.io-6f17d22bba15001f\bootloader-0.9.28)
   Compiling rustc-std-workspace-core v1.99.0 (C:\Users\troub\.rustup\toolchains\nightly-x86_64-pc-windows-msvc\lib\rustlib\src\rust\library\rustc-std-workspace-core)
   Compiling bit_field v0.10.1
   Compiling volatile v0.4.4
   Compiling zero v0.1.2
   Compiling rlibc v1.0.0
   Compiling usize_conversions v0.2.0
   Compiling fixedvec v0.2.4
   Compiling xmas-elf v0.6.2
warning: field `0` is never read
  --> src\page_table.rs:20:13
   |
20 |     Mapping(MapToError<Size4KiB>),
   |     ------- ^^^^^^^^^^^^^^^^^^^^
   |     |
   |     field in this variant
   |
   = note: `#[warn(dead_code)]` on by default
help: consider changing the field to be of unit type to suppress this warning while preserving the field numbering, or remove the field   
   |
20 |     Mapping(()),
   |             ~~

warning: `bootloader` (bin "bootloader") generated 1 warning
    Finished `release` profile [optimized + debuginfo] target(s) in 11.72s
Created bootimage for `myos` at `D:\rust\my_os\target\x86_64-my_os\debug\bootimage-myos.bin`

[phil-opp]

Ah yes, the current version of the guide only works with bootloader v0.9, not with newer versions. I opened a PR to clarify this at #1309. It would be great if someone could translate this note and add it to the Chinese version.

[linkypi]

@phil-opp I can translate this note to Chinese version, it's a piece of cake for a Chinese guy. But I can't fork your main branch. Anyway, I can translate it here for you :

** 注意：** 当前环境仅兼容 bootloader v0.9 版本。较新的版本需考虑使用其他的构建工具，否则会导致构建出现未知错误。

[phil-opp]

Thanks! I added it in 9b0a0a3.

[storytellerF]

在mac上无法运行，也没有任何报错，同一个bin文件，Windows 10没有问题。
Can't run on Mac. No problem on Windows 10.

[bjorn3]

What exactly is the problem on macOS?

[luojia65]

可以说得具体一点吗

[storytellerF]

没有反应，没有任何输出。

QEMU emulator version 7.2.0
Copyright (c) 2003-2022 Fabrice Bellard and the QEMU Project developers

[TachikakaMin]

因为会弹出一个窗口，这个窗口默认是在最下层会被盖住，你可能没看见

Because there will be a window under your terminal window and you didn't see it. So qemu looks like stopped.

[storytellerF]

@TachikakaMin Your are right. No problem now.
你是对的，现在没有问题了

[XGY4n]

请问怎么使用纯命令行执行qemu-system-x86_64 -drive format=raw,file=target/x86_64-blog_os/debug/bootimage-blog_os.bin里面的helloworld打印? 我使用nohup 和 -nographic , nohup.out 只会有bootstage，如何把qenu的东西定向出来？

[luoxi2934562231]

I got an error when I run with ^cargo xbuild --target x86.....json$，I can't complie rust-std-workspace-core v1.99.0，and the error message said "multiple candidate for tmeta depandency core found".

[Itsusinn]

Same error

[Itsusinn]

You might need https://github.com/rust-osdev/bootloader/blob/7c8e2ca63449f92cd1f7494b9cdc9fcf58b7375d/docs/migration/v0.9.md

[phil-opp]

Have you tried cargo clean and recompiling? This sounds like a cleanup bug in cargo xbuild.

[phil-opp]

Also, if you're using -Zbuild-std you should use a normal cargo build instead of cargo xbuild. Otherwise core is compiled and linked twice.

[foxxcn]

My friends made too many mistakes. I guarantee that I didn’t miss any step. Even the previous step json was still successful until

cargo install bootimage

and I stalled erro:

% cargo bootimage --target x86_64-blog_os.json
error: data-layout for target `x86_64-bootloader-15639772412341111525`, `e-m:e-p270:32:32-p271:32:32-p272:64:64-i64:64-f80:128-n8:16:32:64-S128`, differs from LLVM target's `x86_64-unknown-none-gnu` default layout, `e-m:e-p270:32:32-p271:32:32-p272:64:64-i64:64-i128:128-f80:128-n8:16:32:64-S128`

error: could not compile `rustc-std-workspace-core` (lib) due to 1 previous error
warning: build failed, waiting for other jobs to finish...
error: could not compile `core` (lib) due to 1 previous error
error: could not compile `compiler_builtins` (lib) due to 1 previous error
Error: Bootloader build failed.
Stderr: 

[tsatke]

Check out rust-osdev/bootloader#420 and #1292

[foxxcn]

Oh my gosh, it seems like this tutorial is no longer available, or has become unavailable to me as a beginner in this field.

[foxxcn]

After browsing the comment area, I solved this json problem and found out whether it is like this or cargo bootimage:

error[E0464]: multiple candidates for `rmeta` dependency `core` found
/rustc-std-workspace-core/lib.rs:4:9
  |
4 | pub use core::*;
  |         ^^^^
  |
  = note: candidate #1: /private/var/folders/4c/04fphxgd27160gqj6rlb669c0000gn/T/cargo-xbuildoYUtex/target/x86_64-blog_os/release/deps/libcore-8719925a388c81ad.rmeta
  = note: candidate #2: /private/var/folders/4c/04fphxgd27160gqj6rlb669c0000gn/T/cargo-xbuildoYUtex/target/x86_64-blog_os/release/deps/libcore-ca5616d8e9cbcf49.rmeta

For more information about this error, try `rustc --explain E0464`.
error: could not compile `rustc-std-workspace-core` (lib) due to 1 previous error

[phil-opp]

Could you try cargo clean and rebuilding? Looks like there is still a compiled core version of a previous build in the target folder that wasn't properly cleaned up.

[phil-opp]

Also, if you're using -Zbuild-std you should use a normal cargo build instead of cargo xbuild. Otherwise core is compiled and linked twice.

[zzdrake]

qemu-system-x86_64 -drive format=raw,file=target/x86_64-blog_os/debug
why runing so slow

[matveitolochko]

because you are using the debug one, compile in release, and use the release bin

[wangxiaoyan369]

cargo bootimage build error

PS C:\Code\Rust\os-guide\blog_os> cargo bootimage
output:

Building kernel
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.10s
Building bootloader
error: failed to parse manifest at `C:\Develop\rust\.cargo\Cargo.toml`

Caused by:
  manifest is missing either a `[package]` or a `[workspace]`
Error: Bootloader build failed.
Stderr:

"C:\Develop\rust.cargo" is my CARGO_HOME
rustc 1.83.0-nightly (7042c269c 2024-09-23)
cargo 1.83.0-nightly (eaee77dc1 2024-09-19)
bootimage 0.10.3

[bjorn3]

You should create .cargo/config.toml, not .cargo/Cargo.toml.

[fuchk]

This error occurs when I run with the cargo bootimage，I didn't find a similar one in previous review, can you help me see what the reason is？
Building kernel
WARNING: You're currently building for the host system. This is likely an error and will cause build scripts of dependencies to break.

To build for the target system either pass a --target argument or set the build.target configuration key in a .cargo/config file.

error: failed to copy Cargo.lock from C:\Users\28902\.rustup\toolchains\nightly-x86_64-pc-windows-msvc\lib\rustlib\src\rust/library\..\Cargo.lock to C:\Users\28902\AppData\Local\Temp\cargo-xbuildRzCDN2\Cargo.lock
caused by: 系统找不到指定的文件。 (os error 2)
Error: Kernel build failed

[QineGeYu]

请参考 https://os.phil-opp.com/zh-CN/minimal-rust-kernel/ 清歌与 ***@***.***

…

---Original--- From: ***@***.***> Date: Thu, Mar 6, 2025 17:30 PM To: ***@***.***>; Cc: ***@***.******@***.***>; Subject: Re: [phil-opp/blog_os] A Minimal Rust Kernel (zh-CN) (Discussion#1019) 我用了然后变成这样了 Error: Failed to read bootimage configuration: unexpected package.metadata.bootimage key build-command with value ["xbuild"] — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you commented.Message ID: ***@***.***>

[220303]

Windows平台上项目目录不要太长，否则编译过程中链接器(rust-lld)会报错：

error: linking with `rust-lld` failed: exit code: 0xc0000374
  |
  = note: "rust-lld" "-flavor" "gnu" "C:\\Users\\ADMINI~1\\AppData\\Local\\Temp\\rustci2Ef3q\\symbols.o" "<1 object files omitted>" "--as-needed" "-Bstatic" "T:\\ELCO\\Computer Science\\Operating System\\220303\'s Kernel R\\kernel\\target\\x86_64-kernel\\debug\\deps/{librustc_std_workspace_core-e5e018c30b9b1f48.rlib,libcore-8c663417353e0152.rlib,libcompiler_builtins-918324d46c04c70b.rlib}.rlib" "-L" "C:\\Users\\ADMINI~1\\AppData\\Local\\Temp\\rustci2Ef3q\\raw-dylibs" "-Bdynamic" "--eh-frame-hdr" "-z" "noexecstack" "-o" "T:\\ELCO\\Computer Science\\Operating System\\220303\'s Kernel R\\kernel\\target\\x86_64-kernel\\debug\\deps\\kernel-c8d1dc174c6d25a5" "--gc-sections"        
  = note: some arguments are omitted. use `--verbose` to show all linker arguments
  = note:

我原来的目录就是因为太长所以报错，直接把项目目录剪切桌面上就好了，文件目录里有空格和特殊字符(我用了英文 ’ 字符)，目前没有什么问题。

用VS code可能会在main.rs中 #![no_std] 那一行提示 can't find crate for test ，但只要你自己确定创建包的时候时bin而不是lib (默认不加参数是bin)，就不用管这个报错，不影响编译。

[Eltotsira]

在windows中运行cargo install bootimage 时发生错误：

Some errors have detailed explanations: E0405, E0412, E0425, E0432, E0433, E0463, E0531.
error: could not compile serde (lib) due to 6713 previous errors.

在项目的Cargo.toml里添加

[dependencies]
bootloader = "0.9"
serde = { version = "1.0", default-features = false, features = ["derive"] }

仍无助于解决问题。

[Eltotsira]

我知道了，删除之前建立的./cargo/config.toml，就能成功安装bootimage了

[wangmj]

Has anyone encountered the following errors when run command: cargo bootimage

Building kernel
   Compiling bootloader v0.9.31
   Compiling rs-os v0.1.0 (/home/$user/develop/rs-os)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.54s
Building bootloader
error: failed to run `rustc` to learn about target-specific information

Caused by:
  process didn't exit successfully: `/home/$user/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/bin/rustc - --crate-name ___ --print=file-names --target /home/$user/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/bootloader-0.9.31/x86_64-bootloader.json --crate-type bin --crate-type rlib --crate-type dylib --crate-type cdylib --crate-type staticlib --crate-type proc-macro --print=sysroot --print=split-debuginfo --print=crate-name --print=cfg -Wwarnings` (exit status: 1)
  --- stderr
  error: error loading target specification: target-c-int-width: invalid type: string "32", expected u16 at line 14 column 30
    |
    = help: run `rustc --print target-list` for a list of built-in targets

Error: Bootloader build failed.
Stderr:

I resolved by modify the file of ~/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/bootloader-0.9.31/x86_64-bootloader.json.
However, I don't think this method is not good. are there any better approaches?

My rustc version: rustc 1.90.0-nightly (498ae9fed 2025-07-28)

[wangkaijavaee]

Cargo.toml 中的 “bootloader = "0.9"” 要改成 bootloader = "=0.9.32"（固定版本）或者选择不高于0.9.33的版本，但也要固定版本，因为0.9.33不兼容本程序了；

[AzureZee]

分享一下我的环境配置,希望能帮到你们.

系统: win10 ,

msys2环境配置

将路径C:\msys64\ucrt64\bin添加到系统环境变量(Windows环境推荐使用ucrt64模式), 这样可以直接在pwsh运行qemu.
国内下载需要配置镜像, 在msys2的ucrt64模式执行以下命令设置pacman镜像:

sed -i "s#https\?://mirror.msys2.org/#https://mirrors.tuna.tsinghua.edu.cn/msys2/#g" /etc/pacman.d/mirrorlist*
pacman -Syu

安装qemu

pacman -S mingw-w64-ucrt-x86_64-qemu

---

rust 环境配置

安装llvm-tools

rustup component add llvm-tools-x86_64-pc-windows-msvc 

推荐使用cargo-binstall安装bootimage, 直接安装预编译的二进制文件.

cargo binstall bootimage