Z88DK MSX build template with sample game

This repository contains sample games made with Z88DK, MAME and C-BIOS.

@see Z88DK を使って MSX のゲームをつくるための環境構築メモ

Playable by WebMSX

License

MIT License

Special Thanks

• Z88DK - The Development Kit for Z80 Computers - Compiler and toolchain
• Lovely Composer - Music Sequencer
• @aburi6800 - MSX Sound Driver and Convertor
• MAME - Emulator
• openMSX - Emulator
• C-BIOS - MSX Open Source BIOS
• Native Debug - Native debugging for VSCode
• DeZog - Visual Studio Code Debugger for Z80/ZX Spectrum.

Build Require

• Ubuntu 20.04|22.04 LTS or Windows WSL2
• Setup Z88DK
• cmake (sudo apt install cmake)

Set enviroments on ~/.bashrc

# z88dk
export Z88DK_HOME=/home/hiromasa/devel/msx/z88dk
export ZCCCFG=${Z88DK_HOME}/lib/config
export PATH=${Z88DK_HOME}/bin:${PATH}

Verifiy

$ which zcc
/home/hiromasa/devel/msx/z88dk/bin/zcc
$ ls -laF ${ZCCCFG}/msx.cfg
-rw-rw-r-- 1 hiromasa hiromasa 1035  9月  1 12:10 /home/hiromasa/devel/msx/z88dk/lib/config/msx.cfg
$ zcc 2>&1 | head -5
zcc - Frontend for the z88dk Cross-C Compiler - v18586-be7c8763a-20210901

Usage: zcc +[target] {options} {files}
   -v -verbose                  Output all commands that are run (-vn suppresses)
   -h -help                     Display this text

Build

Compile

mkdir build && cd build
cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/z88dk.cmake ..
make

Verifiy

ls -laF ../dist/*.rom
-rw-rw-r-- 1 hiromasa hiromasa  16384  9月  3 18:13 example.rom

Run with openMSX

Setup openMSX

openMSX

Run

$ ls -laF dist/*.rom
-rw-rw-r-- 1 hiromasa hiromasa 16384  9月  3 18:13 dist/example.rom
$ openmsx dist/example.rom

Debug (openmsx-debugger)

Apply patch

• openmsx-debugger で z88dk の -m 形式の .map symbol を読ませる hack + Ubuntu 20.04 LTS Qt 5.14 Obsolete fix

• Ubuntu 22.04 LTS 版の openmsx-debugger で z88dk の -m 形式の .map symbol を読ませる hack

Run with MAME (z88dk-gdb)

Setup MAME

@see DeZog + Z88DK + MAME で MSX アセンブリーをデバッグする手順

Enable -debug flag

CMakefiles.txt

add_compile_flags(C
    +msx
    -vn
    -llib3d
    -lm
    -lndos
    -lmsxbios
    -m
    -debug # Enable
    # https://github.com/z88dk/z88dk/wiki/Classic-allocation#automatic-heap-configuration
    -DAMALLOC
)

Build with debug

rm -Rf build/
mkdir build && cd build
cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/z88dk.cmake ..
make

Verify

Deploy debug ROM for MAME

$ ls -laF dist/*.rom
-rw-rw-r-- 1 hiromasa hiromasa 16384  9月  3 18:13 dist/example.rom
$ cd dist
$ zip -j ../mics/mame/roms/msx1_cart/example.zip example.rom

Run MAME with gdbstub

$ cd mics/mame
$ ./mame cbiosm1jp example -debugger gdbstub -debug
gdbstub: listening on port 23946

Connect z88dk-gdb to MAME

$ z88dk-gdb -h 127.0.0.1 -p 23946 -x dist/example.map
Reading debug symbols...OK
Connected to the server.

VSCode Attach (Native Debug)

• The breakpoint rows may shift, so try setting breakpoints after startup.
• As of 2022-7, "Step Over" does not seem to return the operation. "Continue" and "Step into" work well, so please use them interchangeably.

.vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
          "name": "Attach to MAME gdbserver",
          "type": "gdb",
          "request": "attach",
          "target": "127.0.0.1:23946",
          "remote": true,
          "cwd": "${workspaceRoot}",
          "gdbpath": "${env:Z88DK_HOME}/bin/z88dk-gdb",
          "debugger_args": [
            "-x",
            "${workspaceRoot}/dist/example.map" // or appropriate .map of your project (-m -debug needed!)
          ],
          "autorun": [
          ]
      }
    ]
}