Compiling MS-DOS games with Allegro 4 in 2019

I really like Allegro.

Allegro (link) is a library that contains a whole bunch of useful routines for making games. It has graphics commands, keyboard, mouse and joystick reading, sampled sound and music playback, and a fixed-point math library with its own set of 3D projection and calculation routines. It gets you going.

There's a slapdash rough honesty to the whole thing; it contains whatever the heck the contributors felt like putting in. It has things like FLI animation... I have no idea how you'd make a FLI, even now. It supports .BMP, .LBM, .PCX and .TGA images and that's it. It has a MIDI player that routes to Adlib sound card patches on MS-DOS. It supports its own kind of bitmap fonts, but not vector (TrueType/OpenType) ones. It has its own complete GUI library coupled to its internal bitmap structures, all graphically styled to imitate the Atari ST. It has support for a whole bunch of PlayStation and Nintendo controllers... which you can only connect to your computer's parallel port with an adaptor you solder together at home.

Allegro 4 supported MS-DOS (protected mode on a 386 processor and above) and Microsoft Windows 3.1 up to Vista. It supported BeOS, MacOSX and QNX.

Allegro was the first library I ever learned to use when I was learning C for the first time. It's an odd thing, and I love it to bits because it hecking works.

And now, hopefully, with my help, it can hecking work for you too.

Read on for some thoughts about getting Allegro 4.2.3 to work, or skip directly to the downloads with the links above.

--

I want to make some MS-DOS games with Allegro in C, since I've never done that before. My experience with Allegro has been with Windows XP, using MinGW.

For MS-DOS, the most straightforward way is to use DJGPP within a DOS environment. From the DJGPP website (link): 'DJGPP is a complete 32-bit C/C++ development system for Intel 80386 (and higher) PCs running DOS. It includes ports of many GNU development utilities.'. Allegro for DOS was written to be used with DJGPP. It can also be used with other compilers like Watcom/OpenWatcom, but it's developed for DJGPP.

There's a number of ways to prepare a DOS-like environment:

All of these ways are set up and used identically.

There's another alternative which is more involved but can be more convenient:

The latest release version of Allegro 4 available from the developers is 4.2.3. The version of Allegro available through the DJGPP File Picker is 4.2.2.

--

To recompile Allegro 4.2.3, you'll need to use versions of GCC and Binutils from the era. Support stopped for MS-DOS Allegro 4 in 2007, so I've tried to locate the necessary packages from the DJGPP distribution contemporaneous to the version of GCC that was used to compile that version of Allegro: GCC 4.2.1, July 2007.

All of these (except the first) can all be found in the DJGPP ftp and its mirrors, but I'm mirroring them here also if you want them.

All of the DOS-based environments below contain these packages, with a patched version of Allegro 4.2.3 and its source, with the SB 1.0 fix.

It is possible to compile Allegro 4 for DOS with newer versions of DJGPP and its packages, if you're willing to modify some of the Allegro source files and makefiles to reflect changes in GCC and its syntaxes. If you decide to pursue this, make sure to definitely use the Allegro source -not- from DJGPP and include the SB 1.0 fix.

--

Downloadable fully-configured DJGPP + Allegro directory for MS-DOS, FreeDOS or DOSBox

I've prepared a full DJGPP environment with a recompiled and patched Allegro 4.2.3-sb, as a directory compatible with MS-DOS, FreeDOS or DOSBox, ready to be copied to your system of choice and extracted.

DJGPP environment with Allegro 4.2.3-sb (38 MByte)

You'll also need to add some lines to your autoexec.bat: (assuming you've copied the DJGPP directory to your C drive as C:\DJGPP)

set path=%path%;c:\djgpp\bin
set djgpp=c:\djgpp\djgpp.env

These lines add the DJGPP environment tools into PATH, allowing make and gcc to work, etc. The djgpp environment variable is necessary for DJGPP to work. You can alternatively write these lines to a new file such as dj.bat and execute this batch file only when you want the DJGPP environment available to you.

Once you've extracted the directory, you can then test it by attempting to compile Allegro's sound card set up program.

cd c:\djgpp\allegro\setup
gcc setup.c -o setup.exe -lalleg

As well as letting you test whether the compilation process works, the Allegro sound card set up program should let you test keyboard, mouse, joystick, sampled sound and MIDI output on your system.

A test program is included in C:\DJGPP\ALLEGRO\TESTS\ as test.c. There are also lots of example programs in C:\DJGPP\ALLEGRO\EXAMPLES. ex3d is a good graphical demonstration.

--

Standalone FreeDOS virtual machine image with fully-configured DJGPP + Allegro

If you prefer, I've made a VirtualBox .VMDK disk image containing an installed FreeDOS 1.2, with the above directory already extracted and set up. It contains DJGPP and Allegro 4.2.3-sb, and is immediately ready to be used to compile Allegro games (and recompile the library itself if you want).

FreeDOS, DJGPP, Allegro 4.2.3-sb VMDK image and virtual machine (47 MByte)

Once you've booted the VM, you can then test it by attempting to compile Allegro's sound card set up program.

cd c:\djgpp\allegro\setup
gcc setup.c -o setup.exe -lalleg

As well as letting you test whether the compilation process works, the Allegro sound card set up program should let you test keyboard, mouse, joystick, sampled sound and MIDI output on your virtualised system. VirtualBox isn't perfect in this scenario, but a lot of the example programs work.

A test program is included in C:\DJGPP\ALLEGRO\TESTS\ as test.c. There are also lots of example programs in C:\DJGPP\ALLEGRO\EXAMPLES. ex3d is a good graphical demonstration.

To get files in and out of the disk image, I use VirtualBox's VISO tools to import files as if they were stored on a CD-ROM, and I use a second virtual system running Linux with the DJGPP FreeDOS installation mounted as a second hard disk, with shared folders set up within VirtualBox to manage files between guest and host.

--

DJGPP cross-compilation environment with Allegro, for use on Windows

This environment contains DJGPP recompiled for modern 32-bit Windows systems. This environment runs under Windows, but produces MS-DOS compatible executables as if it were DJGPP running under MS-DOS. This means you can more easily use your favourite editors and integrate the compilation stage more easily into your favourite make process. The end result will still need to be executed in a DOS environment though!

DJGPP cross-compilation environment with Allegro 4.2.3-sb, for use on Windows (103 MByte)

This environment was prepared by neozeed of Virtually Fun (link).

Recompiling Allegro in this environment is a little more involved. I've included some instructions for doing so in the zip, as well as usage instructions - please see info.txt.

--

If you just need the SB1.0 support bugfix and would like to recompile Allegro yourself, this is the replacement sb.c you will need.

SoundBlaster 1.0 patched sb.c for Allegro 4.2.2/4.2.3 (Ron Novy)

--

Allegro 4 is giftware, FreeDOS is GPL2. GPL-licensed source code.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Good luck!

Mathew Carr mattcarr at gmail.com 2019-07-20