The `ik8b` command¶

The compiler is a single executable that turns one .ik source file into an Intel HEX image of AVR instruction words, and also embeds the cycle-accurate simulator. It is organised as subcommands.

Synopsis¶

./ik8b build <file.ik> [-o <out.hex>] [--emit <hex|ir>] [--report]
./ik8b run   <file.ik> [-o <out.hex>] [--report] [<sim options>]
./ik8b sim   <file.hex> --mcu <device> [<sim options>]
./ik8b devices
./ik8b info
./ik8b version
./ik8b license
./ik8b help

A bare ./ik8b <file.ik> ... (no subcommand) is accepted as a shorthand for build, for convenience and backward compatibility.

Compiling — `build`¶

Give the compiler a source file. The device is taken from the file’s mandatory target declaration, not from a command-line flag:

./ik8b build blink.ik -o blink.hex

-o <out.hex>: Path of the Intel HEX output. Defaults to out.hex if omitted.
--emit <hex|ir>: What to produce: hex (the default) writes the Intel HEX image to -o; ir prints the SSA intermediate representation to standard output and writes no HEX (useful for development and snapshot tests).
--report: Print a build summary covering Program (Flash), SRAM, EEPROM, and register usage. The report also enforces the device’s memory budgets: if the program exceeds the available Flash, SRAM, or EEPROM for the selected target, the build fails. The report prints a machine-readable SRAM_BYTES=<n> line before the normal human-readable summary, which the test harness consumes.

Use --report in CI and whenever you want to know how close you are to a device’s limits.

Simulating — `run` and `sim`¶

The compiler embeds the same AVR virtual machine the test suite uses, so it can run a program without any external tool:

run <file.ik> compiles the source (taking the device from its target) and then simulates the result.
sim <file.hex> simulates an already-assembled Intel HEX image — produced by any toolchain (ik8b, avr-gcc, hand-written assembly) — for the device given by --mcu.

Both share one set of simulation options:

--mcu <device>: Device to simulate (sim only; run takes it from the source target). The device’s real core class drives instruction decoding and per-core timing.
--trace: Print a per-instruction execution trace (PC=... lines).
--dump: Dump the registers, PC, SP, and SREG at exit.
--limit <N>: Stop after N instructions (default: a large bound).
--irq <V> / --irq-at <V:STEP> / --irq-every <V:N>: Inject interrupt vector V — at startup, once at instruction STEP, or every N instructions — to exercise ISR handling.

The standalone ik8bvm simulator binary accepts the same subcommands and options (ik8bvm run <file.hex> --mcu <device> ..., ik8bvm devices).

Informational commands¶

These subcommands print information and exit without compiling.

help (-h, --help): Show usage text.
version (-V, --version): Print the compiler version.
info (--info): Print a summary: version, license, output format, the total number of supported devices, and a per-core-family device count.
license (--license): Print license information (the project is Apache-2.0).
devices (list-devices, --list-devices): Print the full table of supported devices with their core family, SRAM, Flash, EEPROM sizes, and SRAM start address. See Supported devices.

Import resolution¶

import <path> (without the .ik extension) is resolved in this order:

the current working directory — <path>.ik;
the directory named by the IK8B_STD_PATH environment variable, if set;
paths relative to the compiler executable, including the bundled std/ fallback used for std/* imports.

This is why import std/gpio resolves against the shipped standard library regardless of where you run the compiler from.

Output format¶

The output is standard Intel HEX describing AVR-8 instruction words, ready for any programmer (avrdude, a serial bootloader, a hardware ISP, or the bundled AVR virtual machine used by the test suite). The compiler emits no ELF, no map file, and links nothing — the HEX is complete and self-contained.

Build and test targets¶

The repository’s Makefile wraps common workflows (these run inside a container, so no local Rust toolchain is required):

`make build`	Build the native `./ik8b` binary.
`make compile`	Compile the bundled blink example to `out.hex`.
`make test`	Compile + simulate the regression suite (all MCUs).
`make test-interrupts`	Validate interrupt-vector binding, all devices.
`make benchmark`	Compare ik8b vs avr-gcc C/asm via the built-in `sim`.
`make clean`	Remove build artifacts.

The ik8b command¶