MD-Modules

Various debugging modules and utilities for Sega Mega-Drive / Genesis ROMs.

Repository structure

This repository includes modules for Mega-Drive projects (modules/ directory) and various utilities (utils/ directory) in one place, since most of them are tightly integrated or depend on each other. See below for the lists of modules and utilities.

Modules

• MD Debugger and Error Handler - also known as The Advanced Error Handler and Debugger, handles exceptions and helps to debug your Mega-Drive ROMs in any emulators and on the real hardware;
• MD-Shell - a stand-alone easy to use "assembly header" to run small programs as Mega-Drive ROMs, includes MD Debugger.

Utilities

• ConvSym (C++20) - a symbol extraction and conversion utility;
• CBundle (C++20) - a custom pre-processor used to build debugger's bundles from the shared "cross-assembler" source files;
• BlobToAsm (Python 3.8+) - a utility to render binary files in M68K assembly with additional tricks (e.g. offset-based expression injection);

Building from source code

This repository aims to be cross-platform, designed with Linux, Windows, MacOS (and other BSD systems) in mind. It makes extensive use of GNU-flavored Makefiles for both *nix and Windows systems (see Makefile for *nix and Makefile.win for Windows). Please read notes below to make sure you have all the prerequisites and your platform is fully supported.

Dependencies

• GNU Make is required to build pretty much everything.

• Utilities require a GCC or Clang compiler with C++20 support and Python 3.8 or newer.

• Modules fully depend on utilities, so they require all the dependencies listed above. Non-Windows systems also require Wine to run assemblers (they're 32-bit Windows executables).

Windows

Please install WSL2 with Ubuntu (see How to install Linux on Windows with WSL), then follow Linux instructions.

Warning

Make sure to install this repository on Linux-side file system, otherwise a lot of executables may not run!

Linux

Make sure you have the necessary dependencies using your package manager (this following example uses apt under Debian/Ubuntu):

apt install g++ make python3 wine

To build everything, use one of the following commands:

make
# or separately:
make utils
make modules

FreeBSD

Make sure you have the necessary dependencies:

pkg install gmake python3 wine

Note

If you're running a 64-bit system, you'll likely also need a 32-bit installation of Wine. As of FreeBSD 13, the following script may automate the process:

/usr/local/share/wine/pkg32.sh install wine

Consult your distribution's manuals for more information.

Please note that you specifically need to use GNU-Make instead of BSD-flavoured Make everywhere:

gmake
# or separately:
gmake utils
gmake modules

MacOS

Warning

Since MacOS Catalina 10.15, 32-bit software is no longer supported. You may not be able to build Modules which require 32-bit Wine. The only proper workaround (at the time of writing) is to use a VM.

Make sure you have Wine:

brew tap homebrew/cask-versions
brew install --cask --no-quarantine wine-stable

To build everything, use one of the following commands:

make
# or separately:
make utils
make modules