Sign inSign up

wischner/xcc-z80

By wischner

•Updated 19 days ago

XCC Z80 toolchain with xcc, xas, xld, xgdb, headers, and runtime libraries.

Image
Developer tools
0

8.3K

wischner/xcc-z80 repository overview

⁠XCC Z80 toolchain

Support: wischner.co.uk/support⁠

Ubuntu-based Z80 development image that builds the medium-model toolchain from the pinned retro-vault/xyz Git tag of the X Compiler Suite⁠.

Official project page: https://quinzee.xyz/x⁠

Inside the image you get:

  • xcc for medium-model C23 compilation (float and 32-bit long, without double, long long, or floating-point stdio)
  • xas for assembly
  • xld for linking
  • xopt for post-generation assembly optimization
  • xar for static libraries
  • xobjcopy for object and archive conversion
  • xprog for XL process/service images, ZX Spectrum TAP/TZX packaging, esxDOS FAT16 IDE disk images, and Amstrad CPC CDT/DSK packaging
  • xgdb and xemu for source-level debugging, plus an xgdb-z80 compatibility alias
  • target headers and runtime in /opt/x/z80/include and /opt/x/z80/lib for the cpm3, zx-ram, zx-rom, zx-esxdos, zx-esxdos-rom, yos, cpc-464, cpc-664, and cpc-6128 platforms
  • host-side SDK headers and libraries in /opt/x/include and /opt/x/lib
  • Python 3 for build and project scripting

/opt/x/bin is already on PATH, so the tools are ready to use without extra setup. /opt/xtools is also kept as a compatibility symlink to /opt/x.

⁠Run As Your User

Run the container as your active host user so generated files belong to you and not to root:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xcc --version

All samples below use that same pattern.

⁠xcc

xcc is the main compiler driver. It preprocesses and compiles C, invokes xas to assemble, and invokes xld to link.

Build a relocatable XL image:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xcc hello.c -o hello.xl

Compile only and keep the relocatable object:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xcc -c hello.c -o hello.rel

Build a flat binary at a fixed address:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xcc --oformat=binary -Ttext=0x8000 hello.c -o hello.bin

Build for the staged CP/M 3 runtime:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xcc --platform=cpm3 hello.c -o hello-cpm3.xl

⁠xas

xas assembles hand-written Z80 source. It accepts SDCC-style syntax by default and can also work in GNU mode.

Assemble SDCC-style source into a .rel object:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xas startup.s -o startup.rel

Assemble with debug information:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xas -g main.s -o main.rel

Assemble GNU-style source into ELF:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xas --mode=gnu startup.s -o startup.o

⁠xld

xld links relocatable objects and libraries into final program images. It can emit XL, flat binary, Intel HEX, and ELF outputs.

Link a normal Z80 program into an XL image:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xld main.rel util.rel -o app.xl

Link a fixed-address binary:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xld --oformat=binary -Ttext=0x8000 main.rel -o app.bin

Produce Intel HEX plus a memory map:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xld --oformat=ihx -Map=app.map main.rel -o app.ihx

⁠xopt

xopt optimizes generated or hand-written Z80 assembly. It is useful when you want to inspect and tune assembly outside the normal xcc pipeline.

Optimize one assembly file into a new output:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xopt -O3 input.s -o output.s

Replace a generated assembly file in place:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xopt -Of --in-place generated.s

Print optimization statistics without writing output:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xopt --stats -O3 input.s

⁠xar

xar creates and manages static libraries of relocatable Z80 objects.

Create or update a library:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xar rcs libgame.a sprites.rel sound.rel

List the members of a library:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xar t libgame.a

Extract all members:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xar x libgame.a

⁠xobjcopy

xobjcopy converts objects and archives between supported formats and can strip debug data from them.

Convert an SDCC .rel object to ELF:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xobjcopy -I rel -O elf main.rel main.o

Convert an ELF object back to .rel:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xobjcopy -I elf -O rel main.o main.rel

Strip debug information from an object:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xobjcopy --strip-debug main.rel main-stripped.rel

⁠xgdb and xemu

xgdb is the debugger frontend. Upstream xemu is the bundled remote target and emulator that speaks the GDB remote protocol. For compatibility with older image revisions, xgdb-z80 is also available as an alias to xemu.

Build with debug information:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xcc -g hello.c -o hello.xl

Start the bundled Z80 debug target:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  -p 9000:9000 \
  wischner/xcc-z80:latest \
  xemu --listen 0.0.0.0:9000

Connect the debugger frontend to the running target:

docker run --rm -it \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  wischner/xcc-z80:latest \
  xgdb --exec hello.xl --cdb hello.cdb --remote host.docker.internal:9000

⁠CONTRIBUTE

Contributions are welcome. Please open an issue or pull request: https://github.com/wischner/docker-toolchains⁠

Tag summary

Content type

Image

Digest

sha256:1dede5866…

Size

88.6 MB

Last updated

19 days ago

docker pull wischner/xcc-z80