Building from Source - FarelRA/CSMWrap GitHub Wiki

Building CSMWrap from Source

This guide provides instructions for building CSMWrap on a Linux-based system.

Prerequisites

  1. Operating System: A Linux distribution (e.g., Ubuntu, Fedora).

  2. Build Tools:

    • build-essential (or equivalent package group providing gcc, make, etc.)
    • nasm (Netwide Assembler)
    • git
    • curl (for downloading OVMF for testing, optional)
    • xxd (typically part of vim-common or similar)

    On Ubuntu/Debian, you can install these with:

    sudo apt-get update
sudo apt-get install -y build-essential nasm git curl xxd

Cloning the Repository

Clone the CSMWrap repository and its submodules:

git clone https://github.com/FlyGoat/CSMWrap.git --recursive
cd csmwrap

If you've already cloned without --recursive, you can initialize submodules with:

git submodule update --init --recursive

Building SeaBIOS CSM and VBIOS

CSMWrap relies on specific binaries from a customized SeaBIOS build. These are Csm16.bin (the CSM itself) and vgabios.bin (the VESA VBIOS). The build system automates this.

  1. Configure SeaBIOS: The project includes a seabios-config file which is copied to seabios/.config. This configuration enables CSM and Coreboot VGA support, among other things.
  2. Build SeaBIOS components: 
    make seabios
    This command will:
    • Clean the SeaBIOS build directory.
    • Copy seabios-config to seabios/.config.
    • Run make olddefconfig and make within the seabios subdirectory.
    • Use xxd to convert the resulting Csm16.bin and vgabios.bin into C header files (src/bins/Csm16.h and src/bins/vgabios.h) which are then compiled into CSMWrap.

Building CSMWrap

CSMWrap can be built for ia32 (32-bit UEFI) or x86_64 (64-bit UEFI).

For x86_64 (Default)

make ARCH=x86_64

Or simply:

make

The output will be bin-x86_64/csmwrap.efi. The GitHub Actions workflow renames this to csmwrapx64.efi.

For IA32

make ARCH=ia32

The output will be bin-ia32/csmwrap.efi. The GitHub Actions workflow renames this to csmwrapia32.efi.

Output Files

After a successful build, you will find the EFI application in the bin-<ARCH> directory (e.g., bin-x86_64/csmwrap.efi).

Cleaning

  • To clean CSMWrap object files and binaries for a specific architecture: 
    make clean ARCH=x86_64  # or ARCH=ia32
  • To clean only the SeaBIOS build products (leaves CSMWrap builds intact): 
    make -C seabios distclean
  • To clean everything including downloaded dependencies for testing: 
    make distclean

Testing with QEMU (Optional)

The Makefile includes rules to run CSMWrap in QEMU using OVMF firmware.

  1. Download OVMF: The first time you run, it will download the necessary OVMF files if they are not present in an ovmf subdirectory.
  2. Run for x86_64: 
    make run ARCH=x86_64 QEMUFLAGS="-m 2G -hda your_boot_disk.img"
  3. Run for IA32: 
    make run ARCH=ia32 QEMUFLAGS="-m 1G -hda your_boot_disk.img"
    Replace your_boot_disk.img with a path to a disk image containing a legacy OS. The QEMUFLAGS variable can be used to pass additional options to QEMU. The application will be copied to a temporary FAT-formatted boot drive for QEMU.
⚠️ **GitHub.com Fallback** ⚠️