Build, Run and Debug

The compiler's default artifact is NOBJ: a transactional stream of image bytes, patches and a final memory map. A target profile supplies the memory layout and service destinations for one machine.

Build an object

The basic command remains:

nucleus build -o build/program.nobj source.nu

A successful build commits one NOBJ generation. A failed build does not publish a partial replacement. NOBJ keeps target image records and late patches separate, allowing the Z80 compiler to emit a stream without retaining a whole program image.

For a flat target, the host can materialize that object as Intel HEX. A banked target remains one NOBJ program with physical-bank identity on its records; it is not several unrelated flat compilations. ROM materialization and burning are host-tool jobs rather than source-language operations.

One command can request all three flat artifacts:

nucleus build --target-profile target.json \
  --hex-output build/debugging.hex \
  --d8-output build/debugging.d8.json \
  -o build/debugging.nobj examples/15-debugging.nu

The book gate runs this command and compares each artifact with the equivalent Host API result.

Add a source map

Requesting D8 produces a sidecar map without changing NOBJ or generated bytes. The map connects executable address ranges with the original source part, line and column, and gives source-defined routine symbols such as main and addOne.

Compiler startup, runtime helpers, padding and static data receive no invented source line. Patches retain the attribution of the image byte they change. Banked output uses one bank-scoped map identity so equal visible addresses in different physical banks do not collide.

Debug80 loads the launchable artifact and its D8 map. Source breakpoints resolve through executable mapped ranges, and the current program counter can be shown against the same source. At present, the documented launch workflow is flat; banked NOBJ and per-bank D8 are validated as artifacts and materialized by the appropriate host tooling.

The companion provides two calls and a final assignment, giving the debugger a small but useful stepping sequence. It leaves observed equal to 2.

var counter as u16 = 0
var observed as u16 = 0

sub addOne()
    counter = counter + 1
end

sub main()
    addOne()
    addOne()
    observed = counter
end

What to keep

Source files describe declarations and behavior. A project file or resolver orders source parts. A target profile describes memory and services. NOBJ carries the tentative target object, and D8 carries optional debugging metadata. Keeping those roles separate is what lets the same compiler run behind Node, CP/M or a smaller machine host.

Summary

• nucleus build emits a committed NOBJ object after successful compilation.
• Target profiles supply placement and service addresses outside source.
• Flat objects may be materialized as Intel HEX.
• D8 is a sidecar and does not change generated program bytes.
• Debug80 uses D8 ranges and symbols for source-level debugging.

See the standalone Host API, target system specification and D8 source maps. The checked companion is 15-debugging.nu.