{"id":13472401,"url":"https://github.com/rust-osdev/bootloader","last_synced_at":"2026-01-16T07:39:33.308Z","repository":{"id":29014750,"uuid":"117340127","full_name":"rust-osdev/bootloader","owner":"rust-osdev","description":"An experimental pure-Rust x86 bootloader","archived":false,"fork":false,"pushed_at":"2025-04-02T10:08:10.000Z","size":1573,"stargazers_count":1474,"open_issues_count":81,"forks_count":215,"subscribers_count":29,"default_branch":"main","last_synced_at":"2025-04-23T18:58:52.243Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rust-osdev.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-01-13T12:01:37.000Z","updated_at":"2025-04-22T14:57:53.000Z","dependencies_parsed_at":"2024-01-13T18:08:35.855Z","dependency_job_id":"f9d613a4-53b9-4b85-a810-9900fbcbfa59","html_url":"https://github.com/rust-osdev/bootloader","commit_stats":{"total_commits":1077,"total_committers":54,"mean_commits":"19.944444444444443","dds":0.1494893221912721,"last_synced_commit":"df388915f669aeb52a279d908cef1cb9a2974c69"},"previous_names":[],"tags_count":112,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-osdev%2Fbootloader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-osdev%2Fbootloader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-osdev%2Fbootloader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-osdev%2Fbootloader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rust-osdev","download_url":"https://codeload.github.com/rust-osdev/bootloader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250496977,"owners_count":21440231,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T16:00:54.391Z","updated_at":"2026-01-16T07:39:33.297Z","avatar_url":"https://github.com/rust-osdev.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# bootloader\n\n[![Docs](https://docs.rs/bootloader/badge.svg)](https://docs.rs/bootloader)\n[![Build Status](https://github.com/rust-osdev/bootloader/actions/workflows/build.yml/badge.svg)](https://github.com/rust-osdev/bootloader/actions/workflows/build.yml)\n[![Join the chat at https://rust-osdev.zulipchat.com](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://rust-osdev.zulipchat.com)\n\nAn experimental x86_64 bootloader that works on both BIOS and UEFI systems. Written in Rust and some inline assembly, buildable on all platforms without additional build-time dependencies (just some `rustup` components).\n\n## Requirements\n\nYou need a nightly [Rust](https://www.rust-lang.org) compiler with the `llvm-tools-preview` component, which can be installed through `rustup component add llvm-tools-preview`.\n\n## Usage\n\nTo use this crate, you need to adjust your kernel to be bootable first. Then you can create a bootable disk image from your compiled kernel. These steps are explained in detail below.\n\n### Migrating from older bootloader version\n\nIf you're already using an older version of the `bootloader` crate, follow our [migration guides](docs/migration).\n\n### Starting from scratch\n\nOur [basic example](examples/basic/basic-os.md) showcases an OS that boots a minimal kernel using `bootloader`.\n\n### Using an existing kernel\n\nTo combine your kernel with `bootloader` and create a bootable disk image, follow these steps:\n\n#### Make your kernel compatible with `bootloader`\n\n- Add a dependency on the `bootloader_api` crate in your kernel's `Cargo.toml`.\n- Your kernel binary should be `#![no_std]` and `#![no_main]`.\n- Define an entry point function with the signature `fn kernel_main(boot_info: \u0026'static mut bootloader_api::BootInfo) -\u003e !`. The function name can be arbitrary.\n  - The `boot_info` argument provides information about available memory, the framebuffer, and more. See the API docs for `bootloader_api` crate for details.\n- Use the `entry_point` macro to register the entry point function: `bootloader_api::entry_point!(kernel_main);`\n  - The macro checks the signature of your entry point function and generates a `_start` entry point symbol for it. (If you use a linker script, make sure that you don't change the entry point name to something else.)\n  - To use non-standard configuration, you can pass a second argument of type `\u0026'static bootloader_api::BootloaderConfig` to the `entry_point` macro. For example, you can require a specific stack size for your kernel:\n    ```rust\n    const CONFIG: bootloader_api::BootloaderConfig = {\n        let mut config = bootloader_api::BootloaderConfig::new_default();\n        config.kernel_stack_size = 100 * 1024; // 100 KiB\n        config\n    };\n    bootloader_api::entry_point!(kernel_main, config = \u0026CONFIG);\n    ```\n- Compile your kernel to an ELF executable by running **`cargo build --target x86_64-unknown-none`**. You might need to run `rustup target add x86_64-unknown-none` before to download precompiled versions of the `core` and `alloc` crates.\n- Thanks to the `entry_point` macro, the compiled executable contains a special section with metadata and the serialized config, which will enable the `bootloader` crate to load it.\n\n#### Creating a bootable image\n\n- Move your full kernel code into a `kernel` subdirectory.\n- Create a new `os` crate at the top level\n    ```sh\n    $ cargo init --bin\n    ```\n- Define a [workspace](https://doc.rust-lang.org/cargo/reference/workspaces.html).\n    ```toml\n    # in Cargo.toml\n    [workspace]\n    resolver = \"3\"\n    members = []\n    ```\n- Add your kernel as a workspace member.\n    ```sh\n    $ cargo new kernel --bin\n    ```\n- Enable the workspace to build your kernel:\n  - Set up an [artifact dependency](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#artifact-dependencies) to add your `kernel` crate as a `build-dependency`:\n      ```toml\n      # in Cargo.toml\n      [build-dependencies]\n      kernel = { path = \"kernel\", artifact = \"bin\", target = \"x86_64-unknown-none\" }\n      ```\n      Enable the unstable artifact-dependencies feature:\n      ```toml\n      # .cargo/config.toml\n      [unstable]\n      bindeps = true\n      ```\n      Experimental features are only available on the nightly channel:\n      ```toml\n      # rust-toolchain.toml\n      [toolchain]\n      channel = \"nightly\"\n      targets = [\"x86_64-unknown-none\"]\n      ```\n  - Alternatively, you can use [`std::process::Command`](https://doc.rust-lang.org/stable/std/process/struct.Command.html) to invoke the build command of your kernel in the `build.rs` script.\n- Create a [`build.rs`](https://doc.rust-lang.org/cargo/reference/build-scripts.html) build script in the `os` crate. See our [disk image creation template](docs/create-disk-image.md) for a more detailed example.\n  - Obtain the path to the kernel executable. When using an artifact dependency, you can retrieve this path using `std::env::var_os(\"CARGO_BIN_FILE_MY_KERNEL_my-kernel\")`\n  - Use `bootloader::UefiBoot` and/or `bootloader::BiosBoot` to create a bootable disk image with your kernel.\n- Do something with the bootable disk images in your `main.rs` function. For example, run them with QEMU.\n\nSee our [disk image creation template](docs/create-disk-image.md) for a more detailed example.\n\n## Architecture\n\nThis project is split into three separate entities:\n\n- A [`bootloader_api`](./api) library with the entry point, configuration, and boot info definitions.\n  - Kernels should include this library as a normal cargo dependency.\n  - The provided `entry_point` macro will encode the configuration settings into a separate ELF section of the compiled kernel executable.\n- [BIOS](./bios) and [UEFI](./uefi) binaries that contain the actual bootloader implementation.\n  - The implementations share a higher-level [common library](./common).\n  - Both implementations load the kernel at runtime from a FAT partition. This FAT partition is created\n  - The configuration is read from a special section of the kernel's ELF file, which is created by the `entry_point` macro of the `bootloader_api` library.\n- A `bootloader` library to create bootable disk images that run a given kernel. This library is the top-level crate in this project.\n  - The library builds the BIOS and UEFI implementations in the [`build.rs`](./build.rs).\n  - It provides functions to create FAT-formatted bootable disk images, based on the compiled BIOS and UEFI bootloaders.\n\n## License\n\nLicensed under either of\n\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or\n  http://www.apache.org/licenses/LICENSE-2.0)\n- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\nUnless 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frust-osdev%2Fbootloader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frust-osdev%2Fbootloader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frust-osdev%2Fbootloader/lists"}