📄 nanochess/bootOS/getting-started/building

File: building.md | Updated: 11/18/2025

Building from Source

Learn how to build bootOS from the assembly source code.

Prerequisites

  • NASM (Netwide Assembler) version 2.0 or later
  • Make (optional, for using Makefile)

Build Process

Using NASM Directly

The simplest way to build bootOS:

nasm -f bin os.asm -l os.lst -o os.img

Parameters:

  • -f bin - Output raw binary format
  • -l os.lst - Generate listing file
  • -o os.img - Output filename

This produces:

  • os.img - Bootable disk image (512 bytes)
  • os.lst - Assembly listing with addresses

Using Makefile

The included Makefile provides convenient targets:

# Build os.img
make

# Build and run in QEMU
make runqemu

# Clean build artifacts
make clean

Build Artifacts

After building, you'll have:

| File | Description | Size | |------|-------------|------| | os.img | Bootable OS image | 512 bytes | | os.lst | Assembly listing | Variable |

Understanding the Listing File

The .lst file shows the assembled code with addresses:

00000000 31C0            xor ax,ax
00000002 8ED8            mov ds,ax
00000004 8EC0            mov es,ax

This is useful for:

  • Debugging
  • Understanding memory layout
  • Verifying code size
  • Locating specific routines

Assembly Options

CPU Target

The code specifies cpu 8086 for compatibility with the original IBM PC:

cpu 8086

This ensures no instructions newer than 8086 are used.

Memory Locations

Key addresses defined in the source:

stack:  equ 0x7700      ; Stack pointer
line:   equ 0x7780      ; Buffer for line input
sector: equ 0x7800      ; Sector data for directory
osbase: equ 0x7a00      ; bootOS location
boot:   equ 0x7c00      ; Boot sector location

Size Constraints

bootOS must fit in exactly 512 bytes:

times 510-($-$$) db 0x4f
db 0x55,0xaa            ; Boot sector signature

The last two bytes (0x55, 0xAA) are the boot sector signature required by the BIOS.

Verifying the Build

Check File Size

ls -l os.img

Should show exactly 512 bytes.

Check Boot Signature

hexdump -C os.img | tail -1

Should end with 55 aa.

Check with objdump

objdump -D -b binary -m i8086 os.img | head -20

Shows the disassembled machine code.

Building Other Examples

The repository includes counter.asm:

nasm -f bin counter.asm -l counter.lst -o counter.img

This is an example program that can run under bootOS.

Advanced: Custom Builds

Modifying Memory Layout

To change where bootOS loads:

  1. Edit the osbase constant
  2. Update interrupt vector addresses
  3. Ensure no conflicts with BIOS data area

Adding Commands

To add new commands:

  1. Create command handler routine
  2. Add entry to commands table
  3. Verify total size stays under 510 bytes

Size Optimization

Tips for keeping code small:

  • Share code between routines
  • Use compact instructions (xor vs mov)
  • Reuse registers
  • Leverage BIOS interrupts

Troubleshooting

Build Fails

Error: instruction not supported

  • Check for post-8086 instructions
  • Verify cpu 8086 directive is present

Error: phase error

  • Label address changed between passes
  • Usually from forward references with sized operands

Build Succeeds but Won't Boot

Check image size:

stat -f%z os.img  # macOS
stat -c%s os.img  # Linux

Check boot signature:

tail -c 2 os.img | xxd

Should show: 55 aa

Next Steps