Update build instructions in the Readme

Author: phil-opp

README.md

@@ -10,28 +10,50 @@ Written for the [second edition](https://github.com/phil-opp/blog_os/issues/360)
 
 TODO
 
-## Build and Run
-You need a nightly [Rust](https://www.rust-lang.org) compiler and [cargo xbuild](https://github.com/rust-osdev/cargo-xbuild).
+## Requirements
 
-Then you can run the `builder` executable with your kernel as argument:
+You need a nightly [Rust](https://www.rust-lang.org) compiler and [cargo xbuild](https://github.com/rust-osdev/cargo-xbuild). You also need the `llvm-tools-preview` component, which can be installed through `rustup component add llvm-tools-preview`.
+
+## Build
+
+The simplest way to use the bootloader is in combination with the [bootimage](https://github.com/rust-osdev/bootimage) tool. With the tool installed, you can add a normal cargo dependency on the `bootloader` crate to your kernel and then run `bootimage build` to create a bootable disk image. You can also execute `bootimage run` to run your kernel in [QEMU](https://www.qemu.org/) (needs to be installed).
+
+To compile the bootloader manually, you need to invoke `cargo xbuild` with a `KERNEL` environment variable that points to your kernel executable (in the ELF format):
+
+```
+KERNEL=/path/to/your/kernel/target/debug/your_kernel cargo xbuild
+```
+
+As an example, you can build the bootloader with example kernel from the `example-kernel` directory with the following commands:
 
 ```
-cd builder
-cargo run -- --kernel path/to/your/kernel/elf/file
+cd example-kernel
+cargo xbuild
+cd ..
+KERNEL=example-kernel/target/x86_64-example-kernel/debug/example-kernel cargo xbuild --release
 ```
 
-This will output a file named `bootimage.bin` in the `../target/x86_64-bootloader/release` folder.
+This results in a bootloader executable at `target/x86_64-bootloader.json/release/bootloader`. This executable is still an ELF file, which can't be run directly.
+
+## Run
+
+To run the compiled bootloader executable, you need to convert it to a binary file. You can use the `llvm-objcopy` tools that ships with the `llvm-tools-preview` rustup component. The easiest way to use this tool is using [`cargo-binutils`](https://github.com/rust-embedded/cargo-binutils), which can be installed through `cargo install cargo-binutils`. Then you can perform the conversion with the following command:
+
+```
+cargo objcopy -- -I elf64-x86-64 -O binary --binary-architecture=i386:x86-64 \
+  target/x86_64-bootloader/release/bootloader target/x86_64-bootloader/release/bootloader.bin
+```
 
-You can run this file using [QEMU](https://www.qemu.org/):
+You can run the `bootloader.bin` file using [QEMU](https://www.qemu.org/):
 
 ```
-qemu-system-x86_64 -drive format=raw,file=target/x86_64-bootloader/release/bootimage.bin
+qemu-system-x86_64 -drive format=raw,file=target/x86_64-bootloader/release/bootloader.bin
 ```
 
-Or burn it to an USB drive:
+Or burn it to an USB drive to boot it on real hardware:
 
 ```
-dd if=target/x86_64-blog_os/debug/bootimage-blog_os.bin of=/dev/sdX && sync
+dd if=target/x86_64-bootloader/release/bootloader.bin of=/dev/sdX && sync
 ```
 
 Where sdX is the device name of your USB stick. **Be careful** to choose the correct device name, because everything on that device is overwritten.