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 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).

Build

The default target is all:

.\neutron.ps1 build              # same as: make all
.\neutron.ps1 build all          # bootloader + kernel + sd.img
.\neutron.ps1 build bootloader   # only kernel8.img
.\neutron.ps1 build kernel       # only atom.bin
.\neutron.ps1 build sd-image    # only sd.img
.\neutron.ps1 build clean        # remove build artefacts
.\neutron.ps1 build size         # section sizes

Run QEMU on host

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

.\neutron.ps1 run
.\neutron.ps1 run --build

Run QEMU inside Docker

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

.\neutron.ps1 emu
.\neutron.ps1 emu --build

Interactive shell

Open a bash shell in the build container:

.\neutron.ps1 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]	Build in Docker (default target: all). Builds image if missing.
.\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.