○ Building on Windows (Docker)

On Windows you can build and run Neutron using neutron.ps1 (PowerShell). The script runs Make inside a Docker container (Ubuntu 24.04, AArch64 toolchain, parted, mtools, dosfstools) and can run QEMU on the host or inside the container. You do not need a native cross-compiler or SD tools on the host.

Prerequisites: Docker Desktop, QEMU for windows (For running bootloader on host machine instead of docker) and PowerShell.

Do not run the script from a directory other than the Neutron project root. The script binds the current directory as /Neutron in the container; if you run it from elsewhere, the wrong folder will be used and artefacts may not appear where you expect.

Usage: .\neutron.ps1 <command> [options]. The Docker image is built automatically when needed (e.g. on first build or run).

Quick Start

The docker container has Qemu installed and thus can be used for testing the bootloader using the following command

.\neutron.ps1 build # detect latest version and compile the bootloader
.\neutron.ps1 emu # to run the compiled bootloader inside the docker container QEMU

Build

The default target is all:

.\neutron.ps1 build              # same as: make all
.\neutron.ps1 build all          # bootloader + kernel (+ sd.img unless embed-kernel=true)
.\neutron.ps1 build bootloader   # only kernel8.img
.\neutron.ps1 build kernel       # build packed test kernel (outputs bin/atom.bin)
.\neutron.ps1 build sd-image     # only sd.img
.\neutron.ps1 build debug        # build the debug artefacts of the binaries
.\neutron.ps1 build clean        # remove build and debug artefacts
.\neutron.ps1 build clean-debug  # remove only debug artefacts
.\neutron.ps1 build size         # section sizes

Using a prebuilt kernel

Pass --kernel <path> to skip the test kernel build and use your own packed NKRN image:

# Prebuilt packed NKRN image (already has the NKRN header)
.\neutron.ps1 build all --kernel C:\path\to\prebuilt.bin
 
# Raw binary (no NKRN header yet) — add --pack to run pack_kernel.py first
.\neutron.ps1 build all --kernel C:\path\to\raw.bin --pack

The script copies the file to bin/custom_kernel.bin (accessible inside the container via the existing bind-mount) and passes K_BIN=bin/custom_kernel.bin to Make automatically. Both sd-image and the embedded-kernel path pick it up from there.

Run QEMU on host

Requires qemu-system-aarch64 on PATH. Builds artefacts if missing; use --build to force rebuild:

.\neutron.ps1 run # run the compiled bootloader in host machine QEMU
.\neutron.ps1 run --build # force build the bootloader and run in host machine QEMU

Run QEMU inside Docker

No host QEMU needed. Builds artefacts if missing; use --build to force rebuild:

.\neutron.ps1 emu # run the compiled bootloader in docker container QEMU
.\neutron.ps1 emu --build # force build the bootloader and run in docker container QEMU

Interactive shell

Open a bash shell in the build container:

.\neutron.ps1 shell # access the docker container root shell

Docker image and custom commands

.\neutron.ps1 docker build        # build image only
.\neutron.ps1 docker tag         # tag image as latest
.\neutron.ps1 docker bash        # same as shell
.\neutron.ps1 docker "make clean"   # run arbitrary command in container

Help

.\neutron.ps1 help

Summary of neutron.ps1 commands

Command	Description
.\neutron.ps1 build [target] [—kernel path] [—pack]	Build in Docker (default target: all). Stages external kernel if --kernel is given; packs it first if --pack is also given.
.\neutron.ps1 run [—build]	Run QEMU on host; build first if artefacts missing.
.\neutron.ps1 emu [—build]	Run QEMU inside Docker; build first if artefacts missing.
.\neutron.ps1 shell	Open interactive bash in container.
.\neutron.ps1 docker build, tag, bash, or command	Image build/tag, shell, or run a command in container.
.\neutron.ps1 help	Show usage and all commands.