Skip to content

Latest commit

 

History

History
129 lines (115 loc) · 4.09 KB

BUILDING.md

File metadata and controls

129 lines (115 loc) · 4.09 KB
Raw

Build and Test Instructions

Prerequisite software

  • On all platforms:

    • git
    • VSCode (for class exercises)
    • The rust-analyzer VSCode extension

  • On macOS

    • Homebrew
    • Xcode Command Line Tools

  • On Ubuntu

    • build-essential 
      sudo apt install build-essential

  • On Windows

    • WSL + build-essential
    • The Remote Development VSCode extension
    • Note: all commands below should be executed within WSL unless otherwise stated. This includes VSCode. It must be started from the WSL shell, not from the Windows native command prompt. Workflow on native Windows is possible but not documented since WSL is still required.

  • On Arch Linux

    • Run the command below to get all the dependencies and follow the build and test process for Ubuntu
    • sudo pacman -S seabios edk2-ovmf readline base-devel ; sudo cp /usr/share/ovmf/x64/OVMF.fd /usr/share/ovmf

Building

  1. Install Rust, UEFI target support as well as other dependencies required for Rust. 
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
rustup +nightly target add x86_64-unknown-uefi
  2. (macOS-only) Change the default toolchain to stable-x86_64-apple-darwin. 
    rustup default stable-x86_64-apple-darwin
  3. Clone the repo. It can be any location. This document uses ~ as an example. 
    cd ~
git clone git@github.com:tandasat/Hypervisor-101-in-Rust.git
  4. Build the whole workspace. 
    cd Hypervisor-101-in-Rust
cargo build

On VSCode, the cargo build task is also available.

Testing with Bochs

  1. Clone Bochs. It can be any location. This document uses ~ as an example. 
    cd ~
git clone -b gcc git@github.com:tandasat/Bochs.git
  2. Configure, build and install Bochs.
    • On macOS 
      cd Bochs/bochs
sh .conf.macosx
make
sudo make install
    • On Ubuntu and Windows 
      sudo apt install ovmf vgabios
cd Bochs/bochs
sh .conf.linux
make
sudo make install
  3. Build and run the hypervisor on Bochs
    • On macOS 
      brew install p7zip
brew install mtools
cd ~/Hypervisor-101-in-Rust/
cargo xtask bochs-intel
# or
cargo xtask bochs-amd
    • On Ubuntu and Windows 
      sudo apt install p7zip-full mtools
cd ~/Hypervisor-101-in-Rust/
cargo xtask bochs-intel
# or
cargo xtask bochs-amd

On VSCode, the cargo xtask bochs-intel and cargo xtask bochs-amd tasks are also available.

Testing with VMware (optional for the course)

Prerequisite software:

  • On macOS
    • VMware Fusion Pro
  • On Windows and Ubuntu
    • VMware Workstation Pro
  1. (Windows-only) Hyper-V needs to be disabled to run the VMware VM. See #7 for the details.
  2. Install dependencies.
    • On macOS 
      brew install cdrtools
    • On Ubuntu and Windows 
      sudo apt install genisoimage
  3. Build and run the hypervisor on VMware. 
    cd ~/Hypervisor-101-in-Rust/
cargo xtask vmware
  4. When VMware starts and shows a boot option, select "EFI Internal Shell (Unsupported option)".

On VSCode, the cargo xtask vmware task is also available.

Testing with bare metal (optional for the course)

To test on bare metal, have a device with serial output. Copy rhv.efi, the snapshot, patch, and corpus files into a FAT32 formatted USB thumb drive. Then, boot the test device, start the UEFI shell, and start the rhv.efi.