- Details
- Category: Setup
Preparing the build environment
This should be required only once. We will use a GNU environment in Windows for building. You can also try Visual Studio, but since I do not have it, I cannot give further help here. See https://docs.mamedev.org/initialsetup/compilingmame.html for further information.
Most of the following information can be found on the MAME Documentation Wiki: Compiling MAME in Windows
1. Download MSYS2 and install it
For Windows x64, please download the installer from the MSYS2 website. This is free software.
Start the executable package by double-click. The installer allows you to choose an installation directory; if you do not pick the default (C:\msys64), make a note of it and replace the default path whenever it appears in the following setup. You can run MSYS2 Setup directly from the installer.
Should Windows Defender warn you about a possible security hazard, please ignore that and insist on installing (More info, Install anyway).
2. Set up MSYS2
When you run the setup, you should see something similar to the Windows command prompt, but with colored text, and a cursor blinking after a $ sign. This is the Unix-like build environment that we will use. In the following text, the commands you have to type in are shown in blue after the $ sign (which you do not type). Please make sure you type these command exactly as shown, including uppercase or lowercase. You can also copy the text and paste it behind the $ sign.
Whenever you are asked whether to proceed with the installation, enter Y or hit Return.
$ pacman -Syu
This updates the current installation.
$ pacman -S git make unzip
Installs the git, make, and unzip commands. Git is used to manage the source code, for example, allowing you to download the latest changes.
$ pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-libc++ mingw-w64-x86_64-python
Installs the compiler, libraries, and the Python interpreter.
$ cd ~$ curl -O "https://repo.mamedev.org/x86_64/mame-essentials-1.0.6-1-x86_64.pkg.tar.xz"$ pacman -U mame-essentials-1.0.6-1-x86_64.pkg.tar.xz$ echo -e '\n[mame]\nInclude = /etc/pacman.d/mirrorlist.mame\nSigLevel = Never' >> /etc/pacman.conf$ pacman -Syu$ echo "export MINGW64=/mingw64 MINGW32=" >> .bashrc$ exit
These are some final settings before building MAME.
Get the sources
Open the command window again (search for MINGW64 in the Start menu), type the following:
$ git clone https://github.com/mamedev/mame.git
This will download all MAME sources from Github. This may take some minutes; the source tree contains nearly 30000 files. You should see a new "mame" directory in the folder.
3. Compile MAME
If you are not already in the mame directory, enter it with the cd command.
$ cd mame$ make -j4 SOURCES=ti/ti99_4x.cpp,ti/ti99_4p.cpp,ti/ti99_8.cpp,ti/geneve.cpp,ti/ti99_2.cpp REGENIE=1
If your PC has sufficient CPUs/cores, you can choose a higher job count (for example, -j12). You should copy this line in a file and store it in the mame folder (like "maketi"). You can then start compilation with
$ ./maketi
After compiling has finished, you should have a freshly built mame executable file. Copy this file into your MAME working directory.
4. Update MAME
$ git pull$ make clean
With pull, your local installation is updated with all changes on Github. You should do a make clean, as shown, to avoid trouble during compiling. Then continue as described below "Compile MAME". For more information about git, please check the online documentation.
5. Forget about steps 2-4 and use my tools
I prepared some small scripts to make the preparation, building, and installation easier. You can, of course, adapt these files to your personal needs.
- prepare: Set up MSYS2 as described above.
- clean: Clean the build directory from a previous build
- maketi: Build MAME.
- mameinst: Install the newly built MAME in the target directory
- mameprep_msys2: Fetch all ROMs and create suitable starter batch files.
This will lead you quickly through the installation and configuration process:
Download MSYS2 and install it
As described above, download the executable package and start it. Run MSYS2 from the installer as proposed at the end.
Download the prepare script
Put the prepare script in your home directory. This is the directory where you find yourself when opening MSYS2. Typically, it should be C:\msys64\home\yourname. The other three scripts are automatically retrieved.
Configure MSYS2
Run the prepare script in your home directory. Watch the output. Ideally, it should do everything mentioned above in tasks 1 and 2.
Build MAME
Run the maketi script in the mamegit subdirectory that has been created by the prepare script.
Install MAME
Run the mameinst script in the mamegit subdirectory that has been created by the prepare script. MAME will be installed in the directory C:\prg\mame.
Get all ROMs
On the first installation, the mameinst script will remind you to fetch the necessary ROMs. Go into the target installation directory (by default /c/prg/mame) and run the mameprep_msys2 script. When it is done, you will find a new folder on your desktop, containing batch files to run various TI and Geneve systems. This is done only once.
6. Troubleshooting
Sometimes, things don't work as expected, even though you swear that you did everything as you were told.
Python not found
When you start building MAME, you get the message after some time that Python was not found.
Check: Did you install Python as described above? In the command shell, enter this:
$ /mingw64/bin/python
Does this work? That is, do you get a "No such file or directory" error, or is there a Python command prompt (">>>") ? If so, exit Python with quit(). Obviously, Python is not in your path.
Check exactly what prompt you see: Is there a MINGW64 or MSYS? If you see MSYS, you opened the wrong command window. Close it and search for "MINGW64" in the Windows start menu. You might want to create a shortcut on your desktop.
Scripts are not found
Although you verified that you are in the correct directory, you see this:
$ maketi
-bash: maketi: command not found
Note that in Unix systems, the current directory is not contained in the command search path. To execute a file outside of the search path, you must provide the directory in which it is located. This is done easily by using the period as the current directory:
$ ./maketi
And now you notice that I actually wrote that in the explanation above.
- Details
- Category: Setup
The TI-99/4A emulation offers two kinds of cartridge formats:
- the common ZIP format for ROM packages in MAME
- the RPK format
The first format is used throughout MAME for bundling ROM dumps that belong to some collection, for example, all ROMs for a computer system. In the same way, all ROMs of a cartridge are stored in a single ZIP file, which must be added to the software list, a XML file in the hash subdirectory. For the TI, this would be the file ti99_cart.xml.
The second format was the result of an earlier attempt to find a format for cartridges. Later, the ZIP format became the recommended format for cartridges, but it has a shortcoming: It depends on an update of the mentioned XML file. The RPK format, on the other hand, allows the user to set up a self-contained cartridge package that can be used right away. For this reason, the RPK format was kept in MAME.
I will elaborate on the details of both cartridge formats in a separate document.
Creating a ZIP cartridge
to be added
Creating a RPK cartridge
There are some points to follow, but this is not really difficult.
- You have to collect all dumps that shall be part of the cartridge. These are the dumps of memory in ROM space and in GROM space. Also, you need to check whether the cartridge offers RAM space or NVRAM space (which is saved on shutting down).
- You have to determine the type of the cartridge. The type is relevant for the function of the cartridge board where the ROMs are located.
- Now you have to set up the defining XML file called layout.xml. It must be part of the cartridge package. This is an example for a "gromemu" type:
<?xml version="1.0" encoding="utf-8"?>
<romset version="1.0">
<resources>
<rom id="gromimage" file="TETRISg.bin"/>
</resources>
<configuration>
<pcb type="gromemu">
<socket id="grom_socket" uses="gromimage"/>
</pcb>
</configuration>
</romset>
The most important parts are marked up in magenta. The PCB type is gromemu, and the ROM dump file is called TETRISg.bin. It is referenced by the "gromimage" tag, and the "socket" element declares it to be a GROM image by using the ID "grom_socket". You can use any other tag for "gromimage", and the file may also have any name.
Note that there is no format for the dump file name; the "g.bin" at the end of the file name has no special meaning for MAME. This is different to other emulators where the file name also determines its type; in the RPK format, the meaning of the dump file is determined by the socket element.
- Create a ZIP file from the dump files and the layout.xml. All these files must be part of the package.
- Change the suffix of the ZIP file to "rpk".
- Details
- Category: Setup
Actually, all Linuxes are alike. Almost. In the end, you run into problems because one system is by default installed with some library that another does not use. Since these libraries are installed only once, the challenge is to find out which libraries need to be installed and which are already there, and this is again different from system to system.
Thus, not the Linuxes are different, but their installation evolves over time. I will give some hints for installing MAME on different systems on this page.
Running MAME
MAME is dynamically linked against some libraries which may not be installed on your machine.
But fixing this is a simple job which you have to do only once. The following commands have been tested on a fresh installation. After installing, you should be able to run MAME. (Please report if you find a different situation.)
Unfortunately, different Linux flavors come with different package installers. And to make things worse, they use different package names for the same libraries.
If your system does not have the required libraries, you will see an error message like this:
$ ./mame ti99_4a
./mame: error while loading shared libraries: xxxx: cannot open shared object file: No such file or directory
The xxxx is the file name of the missing library file. The package name is usually slightly different.
openSUSE Tumbleweed
(July 2023)
sudo zypper install libSDL2_ttf-2_0-0
Ubuntu 22.04 LTS
sudo apt-get install libsdl2-2.0-0
sudo apt-get install libsdl2-ttf-2.0-0
sudo apt-get install libqt5widgets5
Installing the TTF lib will also install the SDL2 base lib, so you may skip the first command.
Linux Mint 19.3
sudo apt install libsdl2-ttf-2.0-0
sudo apt install libqt5widgets5
Configure it once
Open a bash shell and type
user@host:~$ cd mame
user@host:~/mame$ ./mame -createconfig
This creates a file ~/mame/mame.ini. Open it in some text editor.
In the second section ("CORE SEARCH PATH OPTIONS") you will find a setting rompath. This is relative to your base directory ~/mame; typically, you will find the value roms (i.e. it will be ~/mame/roms). This subdirectory is already created by unpacking the zip file (or after the build process). If you like, you can append ;cartridges or similar in order to separate between modules and system roms. You must make sure that there is a directory ~/mame/cartridges; if needed, create a new folder of that name in your explorer.
Scroll down to "OSD VIDEO OPTION"; change window to 1 to get a windowed output, otherwise it is fullscreen. In the next section "OSD PER-WINDOW VIDEO OPTION" you should set the first resolution property to 1280x960 or bigger, as you find suitable.
Note that this configuration is only done once, when you install MAME, as we show it here.
Install system ROMs and cartridges
Go to our WHTech repository and download ti99_complete.zip from the directory /System ROMs/MAME. Unzip its contents into the roms subdir. Do not unzip the zip files inside.
Also from WHTech, download all_carts.zip from /Cartridges/MAME. It contains a collection of zip files, each one for a cartridge; do not unpack these cartridge zips.
Store the cartridge zips into the cartridges subdir if you added that location to the rompath, otherwise move all cartridge zip files to the roms subdir.
Create starter script files
The following examples will only work if the specified disk or cassette image files are actually present at the indicated paths (or in the working directory if no path is specified). The backslashes are used to continue the command line on the next line; do not forget them.
Example 1
Plain console, cassette file inserted
#!/bin/bash
cd ~/mame
./mame ti99_4a -cass1 cassette.wavExample 2
External 32K memory expansion, TI floppy controller, myfloppyimage.dsk inserted in DSK1
#!/bin/bash
cd ~/mame
./mame ti99_4a -ioport peb -ioport:peb:slot2 32kmem -ioport:peb:slot8 tifdc -flop1 myfloppyimage.dskExample 3
Cartridge Extended Basic, external 32K memory expansion, RS232 card, HFDC controller, one drive, myfloppyimage.dsk inserted
#!/bin/bash
cd ~/mame
./mame ti99_4a -cart exbasic -ioport peb -ioport:peb:slot2 32kmem \
-ioport:peb:slot7 tirs232 -ioport:peb:slot8 hfdc \
-flop1 myfloppyimage.dsk Example 4
Cartridge Editor/Assembler, external 32K memory expansion, Speech synthesizer, Horizon RAMDisk, HFDC, hard disk, one floppy image inserted
#!/bin/bash
cd ~/mame
./mame ti99_4a -cart editass -ioport peb -ioport:peb:slot2 32kmem \
-ioport:peb:slot3 spchsyn -ioport:peb:slot4 horizon -ioport:peb:slot8 hfdc \
-ioport:peb:slot8:hfdc:h1 generic -hard1 myharddisk.hd -flop1 myfloppyimage.dsk Example 5
P-Code system, external 32K memory expansion, TI floppy controller, one drive, Editor/Filer inserted from folder C:\prg\mame\disks\UCSD
#!/bin/bash
cd ~/mame
-ioport:peb:slot3 pcode -ioport:peb:slot8 tifdc \
-flop1 disks\UCSD\ucsd_pascal_editor_filer_1.dsk Note: You must turn on the P-Code card in the DIP switches menu of the On-screen display (OSD). The card is turned off by default because it immediately takes over control on start.
Example 6
Geneve, Horizon RAMDisk, Speech, RS232, HFDC, one hard disk
#!/bin/bash
cd ~/mame
-peb:slot6 tirs232 -peb:slot8 hfdc \
-ioport:peb:slot8:hfdc:h1 generic -hard1 myharddisk.hd - Details
- Category: Setup
I will give some hints for installing MAME on a Raspberry Pi 4.
Keep in mind that MAME requires a lot of performance from the CPU. As shown in the Requirements section, you will need at least a Raspberry Pi 4.
Running MAME
MAME is dynamically linked against some libraries which may not be installed on your machine.
The following commands have been tested on a fresh installation. After installing, you should be able to run MAME. (Please report if you find a different situation.)
Raspberry Pi OS
Debian version 11 (bullseye)
sudo apt install libsdl2-ttf-2.0-0
more to follow
- Details
- Category: Setup
We're going to describe a fast way to install MAME on your Windows computer. If you follow these steps closely, there should not be any problem getting it running.
Check your Windows release
You should run a post-XP version (Vista, 7, 8, 10, 11). Do not try any older release like Windows 98, ME, or 2000. Windows XP is not recommended for security reasons, and MAME is not tested to run on it.
Get the MAME package
Download the most recent MAME release from the MAMEdev website from the section Official Binaries. You should use the 64 bit version (unless you know that your computer is 32 bit only).
Please do not attempt to install an older release, particularly not if its release number is much smaller than the current one. There have been changes in the meantime concerning the ROM formats, and this may make it impossible to run MAME.
Install the files
Run the exe file; this is just a self-extracting archive file. Choose your target directory; for easier configuration, a simple path like C:\prg\mame is recommended. The extracted files will be located in that directory.
Note that MAME does not alter your registry file. This means you can at any time simply remove the MAME installation, install another one in a separate directory, or reinstall it if desired. Uninstalling means that you just remove the MAME directory.
Configure it once
Open a command shell and type (in black)
C:\Users\Whoever> cd \prg\mame
C:\prg\mame> mame -createconfig
C:\prg\mame> exitThis creates a file C:\prg\mame\mame.ini. Open it in some text editor.
In the second section ("CORE SEARCH PATH OPTIONS") you will find a setting rompath. This is relative to your base directory C:\prg\mame; typically, you will find the value roms (i.e. it will be C:\prg\mame\roms). This subdirectory is already created by unpacking the zip file. If you like, you can append ;cartridges or similar in order to separate between modules and system roms. You must make sure that there is a directory C:\prg\mame\cartridges; if needed, create a new folder of that name in your explorer.
Scroll down to "OSD VIDEO OPTION"; change window to 1 to get a windowed output, otherwise it is fullscreen. In the next section "OSD PER-WINDOW VIDEO OPTION" you should set the first resolution property to 640x480 or bigger, as you find suitable.
Note that this configuration is only done once, when you install MAME, as we show it here.
Install system ROMs and cartridges
Go to our WHTech repository and download ti99_complete.zip from the directory /System ROMs/MAME. Unzip its contents into the roms subdir. Do not unzip the zip files inside.
Also from WHTech, download all_carts.zip from /Cartridges/MAME. It contains a collection of zip files, each one for a cartridge; do not unpack these cartridge zips.
Store the cartridge zips into the cartridges subdir if you added that location to the rompath, otherwise move all cartridge zip files to the roms subdir.
Create a starter batch
Create a small batch file to launch MAME. You may drop that on your desktop. For that, open some text editor and type
c:
cd \prg\mame
mame ti99_4a
Save it as ti99.bat to your desktop, or anywhere else as desired.
You can now edit this starter batch or create copies. You can change the system name (e.g. geneve, ti99_8), add cartridges (-cart exbasic) or peripheral devices (-ioport peb -ioport:peb:slot8 hfdc), and add floppy disks (-flop1 mydisk.dsk).
If you prefer the 32 KiB internal 16-bit RAM expansion, you can turn it on in the "System configuration" menu of the on-screen display (OSD). You then have to remove the 32kmem configuration below in all examples, however.
Example 1
Plain console, cassette file inserted
Important: This and the following examples will only work if the specified disk or cassette image files are actually present at the indicated paths (or in the working directory if no path is specified).
c:
cd \prg\mame
mame ti99_4a -cass1 cassette.wavExample 2
External 32K memory expansion, TI floppy controller, myfloppyimage.dsk inserted in DSK1
c:
cd \prg\mame
mame ti99_4a -ioport peb -ioport:peb:slot2 32kmem -ioport:peb:slot8 tifdc -flop1 myfloppyimage.dskExample 3
Cartridge Extended Basic, external 32K memory expansion, RS232 card, HFDC controller, one drive, myfloppyimage.dsk inserted
c:
cd \prg\mame
mame ti99_4a -cart exbasic -ioport peb -ioport:peb:slot2 32kmem -ioport:peb:slot7 tirs232 -ioport:peb:slot8 hfdc -flop1 myfloppyimage.dsk
Example 4
Cartridge Editor/Assembler, external 32K memory expansion, Speech synthesizer, Horizon RAMDisk, HFDC, hard disk, one floppy image inserted
c:
cd \prg\mame
mame ti99_4a -cart editass -ioport peb -ioport:peb:slot2 32kmem -ioport:peb:slot3 spchsyn -ioport:peb:slot4 horizon -ioport:peb:slot8 hfdc -ioport:peb:slot8:hfdc:h1 generic -hard1 myharddisk.hd -flop1 myfloppyimage.dsk
Example 5
P-Code system, external 32K memory expansion, TI floppy controller, one drive, Editor/Filer inserted from folder C:\prg\mame\disks\UCSD
c:
cd \prg\mame
mame ti99_4a -ioport peb -ioport:peb:slot2 32kmem -ioport:peb:slot3 pcode -ioport:peb:slot8 tifdc -flop1 disks\UCSD\ucsd_pascal_editor_filer_1.dsk
Note: You must turn on the P-Code card in the DIP switches menu of the On-screen display (OSD). The card is turned off by default because it immediately takes over control on start.
Example 6
Geneve, Horizon RAMDisk, Speech, RS232, HFDC, one hard disk
c:
cd \prg\mame
mame geneve -peb:slot4 horizon -peb:slot5 spchsyn -peb:slot6 tirs232 -peb:slot8 hfdc -ioport:peb:slot8:hfdc:h1 generic -hard1 myharddisk.hd
Reconfiguration
If you do not plan to change your configuration too often, you may want to set it inside MAME using the OSD. You can use the menu selection Slot devices to change the peripheral box contents, for example. Note that this change is only temporary until you leave MAME.
If you want to keep changes after stopping MAME, you must set readconfig and writeconfig to 1 in mame.ini.
When you use this setting, be aware that your command-line arguments may be overridden by what you had set in the OSD menu before you exited MAME the last time.
- Details
- Category: Setup
Many users may prefer to install the ready-to-use MAME package. If you are interested how MAME works, if you want to contribute to its development, try to fix a bug, or suggest a useful extension, you should consider installing the MAME sources and building MAME.
If you are not so familiar with building, this may sound rather complicated, and you probably doubt that you can safely get to the desired end. Or you do have some experience in building software from sources, but all you remember was that at some time compilation stopped with a long error text that you could not make sense of from the second line.
However, MAME sources show a very high quality, that is, they actually compile to completion, and there are only very few compiler warnings (mostly from the imported 3rd-party libraries). With the following instructions, you should be able to successfully build MAME and to run it on your computer. Even if you do not plan to write own code, you will enjoy building MAME, because you always have access to the latest changes, so you do not have to wait for the next release.