Home

MAME source-debugging preview
Quick-Start Guide

How to install

You will need a special build of MAME and a special build of an assembler or compiler that generates the debugging information MAME needs. For the latter, this preview currently includes lwtools.

This preview currently only works with the special build of lwtools, but I may expand the preview to CMOC and ugBasic for the CoCo if there is sufficient interest.

If you prefer to build your own, see Build Instructions.

MAME

  • Go to the Releases page, and click on the latest release.

  • You will find unofficial builds there for Windows, Mac (ARM64), and Linux. Go to your existing MAME installation and overwrite your official MAME binary with the unofficial version. (Rename the official build first, so you can revert back to it if you need to!)

lwtools

  • From the same releases page above, you will find unofficial builds of lwasm and lwlink for Windows, Mac (ARM64), and Linux. Go to your existing lwtools installation and overwrite your official lwtools binaries with the unofficial ones. (Rename the official lwasm / lwlink first, so you can revert back to them if you need to!)
    • Note: I cannot verify macos builds, but I am told this build does at least run and properly print usage. Hopefully the rest works, too.

Getting started

lwtools

When it's time to assemble your code, add -ito the lwasm command-line. Example:

lwasm -9bl -omy-code.bin my-code.asm -lmy-code.lst -i

In addition to the usual lwasm output, the above will also generate my-code.bin.mdi, which contains the debugging information. If, instead, you are assembling and linking use command-lines like these:

lwasm --obj -9 -l -omy-code1.obj my-code1.asm -lmy-code1.lst -i
lwasm --obj -9 -l -omy-code2.obj my-code2.asm -lmy-code2.lst -i
lwasm --obj -9 -l -omy-code3.obj my-code3.asm -lmy-code3.lst -i
lwlink -b -omy-code.bin -imy-code.mdi --map=my-code.map my-code1.obj my-code2.obj my-code3.obj

the first three lines will generate an MDI file for each section appearing in each assembled source file. For example, if my-code1.asm contained two sections, and the other .asm files contained one, you'd get files named something like my-code1.obj_sectiona.mdi, my-code1.obj_sectionb.mdi, my-code2.obj_section.mdi, my-code3.obj_section.mdi. lwlink looks for mdi files of these names and combines them together into a single MDI file, much as it combines the .obj files into a single .bin file. The -i option passed to lwlink allows you to specify the name for the final MDI file that lwlink generates (in this case, my-code.mdi).

MAME

Once you have your MDI file, you're ready to begin debugging. Launch MAME with the usual command-line options (including -debug), and add on -src_debug_info path/to/MDI/file. Note that you only pass a single MDI file. In the lwlink example above, you would specify the final MDI generated by lwlink (e.g., -src_debug_info path/to/my-code.mdi)

You will then be able to bring up the source file window via Options menu, Show Source command from the main debugger window. You can then use the source file window to set breakpoints and step, or use the dedicated source-level debugging commands in the console window.

For fun, try executing symlist 0 from the debugger console window to view the source-level symbols available to you.

There is a lot more functionality not summarized here. For full documentation, go to Full source-level debugging docs for MAME

More features

For information on source debugging from NitrOS-9, or while the CoCo 3's Memory Management Unit is paging in and out physical RAM blocks containing your code, see More Features.

What if I have feedback?

Bugs? Comments? Ideas? Questions? Please use the discussion section on GitHub. I will do my best to respond to all posts.

Other Pages