Neutron v1.0.1

Building on Linux and macOS

3 min read

On Linux and macOS you build Neutron using GNU Make and an AArch64 cross-compiler. SD image creation requires additional host tools.

Prerequisites

Cross-compiler. The Makefile expects the prefix aarch64-linux-gnu- by default. Install the corresponding package:

  • Arch: sudo pacman -S aarch64-linux-gnu-gcc aarch64-linux-gnu-binutils
  • Fedora: sudo dnf install gcc-aarch64-linux-gnu binutils-aarch64-linux-gnu
  • Ubuntu / Debian: sudo apt install gcc-aarch64-linux-gnu binutils-aarch64-linux-gnu
  • macOS: Use Homebrew or another source for aarch64-linux-gnu-gcc and aarch64-linux-gnu-ld, or set CROSS=aarch64-none-elf- and install the bare-metal toolchain.

Make. GNU Make is required. On macOS, ensure you use the version from Xcode Command Line Tools or Homebrew, not an outdated system make if present.

SD image tools. Building the SD image (and thus make all) needs:

  • parted (partitioning)
  • mtools (mformat, mcopy, mdir)
  • dosfstools (optional; mtools is sufficient for the current image creation)

On Debian/Ubuntu: sudo apt install parted mtools. On Arch: sudo pacman -S parted mtools.

QEMU (optional). To run the built image in QEMU, install qemu-system-aarch64. Package names: qemu-system-arm (Debian/Ubuntu), qemu-full or qemu-system-aarch64 (Arch), qemu (Homebrew).

Build Commands

From the Neutron project root:

make clean
make all

make all builds the bootloader (bin/kernel8.img), the test kernel (bin/atom.bin), and the SD image (bin/sd.img). To build only specific parts, use the targets described in Make Targets.

Toolchain Override

To use a different compiler prefix (for example the bare-metal toolchain):

make CROSS=aarch64-none-elf- all

The variable CROSS must end with a hyphen and must be set for every make invocation unless you export it.

Running in QEMU

After a successful build:

make qemu-rpi

This starts QEMU with -machine raspi3b, the bootloader as kernel, and the SD image as the SD card. Serial I/O is sent to the terminal. Exit with the QEMU monitor shortcut (typically Ctrl-A X or Ctrl-A C then quit).

make qemu-rpi depends on the all target, so it will build bootloader, kernel, and SD image if they are out of date.

Troubleshooting

“No rule to make target” or missing assembler: Ensure the cross-compiler and binutils are installed and that CROSS (if set) matches the prefix of the tools (e.g. aarch64-linux-gnu-gcc, aarch64-linux-gnu-as).

SD image creation fails (mformat, mcopy, mdir not found): Install mtools. On some systems the FAT image is created with a different tool; the Makefile uses mformat -i $@@@1M -F -v NEUTRON :: and mcopy -i $@@@1M ....

QEMU not found: Install the QEMU package that provides qemu-system-aarch64 and ensure it is on your PATH.

For a list of all targets and variables, see Make Targets.

Graph View

Backlinks