blog:pcdevtools [Target-Earth]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== DOS - Modern Development Tools ======

This is my page which collects links/information on various modern development tools and languages for writing new code on old PC/IBM/DOS systems.
===== 16bit & 32bit Tools =====

=== OpenWatcom ===

   * Homepage: https://github.com/open-watcom
   * Documentation: https://github.com/open-watcom/open-watcom-v2/wiki
   * Sample makefiles
     * 286 / Real mode target
     * 386 / Protected mode target

OpenWatcom is a very useful suite of development tools (C and C++, Fortran, etc) that can target both the traditional, early 16bit DOS environment, as well as the later 32bit protected mode environment taking advantage of the 386 and later processors. It is a continuation of the earlier commercial Watcom product now turned over to the community and available for free.

The syntax of the OpenWatcom compilers and make utilities are a little 'off' compared to many of the GNU tools, but once you've worked out the various incantations to use, it works quite nicely.

==== 32bit Only Tools ====


=== DJGPP / GCC ===

   * Homepage
   * Downloads
   * Sample makefile



===== DOS SDK's & Libraries =====

==== Audio & Video ====

=== Allegro 4 ===

   * [[https://liballeg.org/|Homepage]]
   * Documentation
     * [[https://liballeg.org/api.html|Official documentation at liballeg.org]] - downloadable versions only
     * [[https://www.allegro.cc/manual/4/|Alternative documentation at allegro.cc]]
   * Downloads
     * {{:blog:pcdev:allegro-4.2.3.1.djgpp.bin.tar.bz2 |}} - Compiled for DJGPP (using gcc 12.x)
     * The above includes Allegro 4.2.3.1 built and patched for DJGPP, with all example code, normal, debug and profile library versions and html docs. This unpacks to **/opt/toolchains/x86/allegro-djgpp**.
     * CWSDPMI.EXE (at the [[http://sandmann.dotster.com/cwsdpmi/|official homepage]] or the [[https://en.wikipedia.org/wiki/CWSDPMI|information on Wikipedia]])
     * You need cwsdpmi.exe, above, (or an equivalent DPMI server) in order for DJGPP binaries to run on DOS.

Allegro was basically [[https://www.libsdl.org/|SDL]] for DOS, before SDL was even a thing (SDL is great, by the way and I use it a lot!). It's a full featured graphics and audio game library for DOS and a number of other platforms - it's still around and being developed, but dropped support for DOS many years ago. It's probably the most full featured, freely available graphics/audio SDK for DOS. There are versions of it floating around the net pre-packaged with ancient versions of the DOS DJGPP toolchain, but by far the best way of using it these days is via a cross-compiler toolchain such as DJGPP on Linux/Mac/Windows.

How to build on modern compilers? Well, first of all **don't use Open Watcom**; I started off via this route and everything appears to work just fine, but later on I got to the point of needing to set up the Allegro timer/interrupt functions and I started getting unexplained program termination at the point (or just after) the Allegro timers were initialised. I eventually relented and rebuilt Allegro using djgpp and switch to that, with the exact same lines of code the application stopped exiting at the point the Allegro timer was initialised.

I can only guess that Watcom/Open Watcom was not fully tested at the point the last release of Allegro for DOS was released in 2009. My experience tells me that it is not a fully working combination. Stick with **DJGPP**.

The outline process is simple:

  - Download 4.2.3.1 source
  - Unpack
  - Configure for DJGPP cross-compilation (run '**fix.sh djgpp**')

But as always, the devil is in the details. If you want to use a modern version of GCC/DJGPP (and you *really* do), you have to make a few changes. First you have to edit **xmake.sh** to pick up your DJGPP install. In my case it was setting the two variables **XC_PATH** and **XPREFIX** to the following:

**xmake.sh**
<code>
XC_PATH=/opt/toolchains/x86/djgpp/bin
XPREFIX=i586-pc-msdosdjgpp-
</code>

Next edit **makefile.dj** to set a compatibility option for the modern GCC compiler (the '**-fgnu89-inline**' directive). If you don't, things look like they work until you try to link against Allegro and your code will fail to compile due to duplicate symbol errors (there are a lot of inline defines in the Allegro headers, which are deprecated on C99 syntax):

**makefile.dj**
<code>
TARGET_OPTS = -fgnu89-inline -O2 -funroll-loops -ffast-math
</code>

Finally, there is a bug in one of the graphics drivers that comes with the 4.2.3.1 release, and it results in two missing symbols when compiled with GCC. You need to edit **src/misc/vbeaf.c** and add them.
Just before the following lines:

**src/misc/vbeaf.c**
<code>
* the video driver structure */
GFX_DRIVER gfx_vbeaf =
{
</code>

Change it to show the following:

**src/misc/vbeaf.c**
<code>
int int_ds;
int saved_ds;

/* the video driver structure */
GFX_DRIVER gfx_vbeaf =
{
</code>

Now you are ready to compile Allegro from source:

<code>
./xmake.sh lib
cp -a include /to/where/you/want/the/allegro/headers
cp lib/djgpp/lib*.a /to/where/you/want/the/allegro/libs
</code>

You can optionally build the demo application as well:

<code>
./xmake.sh demo
</code>

However, the examples and many other bits of the DOS runtime (such as the keyboard/sound setup utilities) don't get built via the cross compile process, so they need to be built manually:

<code>
cd allegro-4.2.3.1
cd examples
for src in *.c; do
  i586-pc-msdosdjgpp-gcc -I/to/where/you/want/the/allegro/headers -g -O2 -o ${src%.c} $src /to/where/you/want/the/allegro/libs/liballeg.a -lm
done
cd ..
cd setup
i586-pc-msdosdjgpp-gcc -I/to/where/you/want/the/allegro/headers -O2 -o setup.exe setup.c /to/where/you/want/the/allegro/libs/liballeg.a -lm
i586-pc-msdosdjgpp-gcc -I/to/where/you/want/the/allegro/headers -O2 -o keyconf.exe keyconf.c /to/where/you/want/the/allegro/libs/liballeg.a -lm
</code>

.. you'll want to copy the following to the application/game you are writing, since these are used to allow users to configure their sound/video options:

   * //setup/setup.exe//
   * //setup/setup.dat//
   * //setup/keyboard.dat//
   * //language.dat// & //allegro.cfg// (both found in the main allegro-4.2.3.1 folder)

There are some more hoops to jump through in order to build documentation, but if you want to skip all of this and just use a pre-compiled library, with the headers, examples, setup/keyboard utilities, the main demo and documentation all built and configured, just grab the archive I uploaded, above: {{ :blog:pcdev:allegro-4.2.3.1.djgpp.bin.tar.bz2 |}}

Most of the DOS binaries (.exe files) in my archive have been compressed with **upx**, if you build from source you will want to install and use upx, as otherwise you'll find that even the tiniest Allegro tool will be 700-800KBytes in size (you pretty much end up with an entire copy of the Allegro library embedded in each one due to the limitations of the linker/runtime on DOS).

==== Audio Only ====

=== Apogee Sound System ===

   *[[https://github.com/jimdose/Apogee_Sound_System|Homepage]] at Github

The historic Apogee Sound System, as used on many Apogee software titles in the early 1990's. This only builds on Watcom/OpenWatcom, so there may be additional effort in using this with a more modern toolchain like DJGPP.

No specific documentation other than what is in the source code itself.

---

=== Judas Sound Library ===

   * [[https://github.com/volkertb/JUDAS|Homepage]] at Github
   * [[https://github.com/volkertb/JUDAS|Documentation]] at Github
   * Downloads 
     * {{ :blog:pcdev:judas.watcom.bin.tar.bz2 |}} - Compiled for OpenWatcom 2.0+
     * {{ :blog:pcdev:judas.djgpp.bin.tar.bz2 |}} - Compiled for DJGPP (using gcc 12.x)
     * Both archives unpack to **/opt/toolchains/x86** - the former to **/opt/toolchains/x86/judas-watcom**, the latter to **/opt/toolchains/x86/judas-djgpp**. 

The Judas audio library is a small lightweight sound library capable of playing back multi-channel tracker modules (.mod, .xm, .s3m formats) as well as digital samples on DOS. It supports a small number of soundcards, including the following common models (and compatibles):

   * SoundBlaster (original mono, non-Pro models)
   * SoundBlaster Pro
   * SoundBlaster 16
   * Gravis Ultrasound

Judas will compile and build on both Open Watcom as well as DJGPP. I've provided pre-built archives above, for both toolchains, ready to link in and use. Full documentation on including Judas in your DOS application is in the [[https://raw.githubusercontent.com/volkertb/JUDAS/master/README.TXT|README]] file. 

As an example of the performance, on Dosbox with the 386 core and 5000 fixed cycles (which in most estimates is equivalent to something like a 386 25-33MHz), the basic player with Judas will play an 8 channel module without issue in 8bit stereo. Depending on the complexity it can handle up to around 16 channels. Obviously with higher specification DOS environments (486 and Pentium settings) you can turn on higher quality output, play more channels etc.

---

=== Miles Sound System ===

   * [[http://www.ke5fx.com/|Homepage]] at Jon Miles' personal site
   * [[http://www.thegleam.com/ke5fx/misc/AIL2.ZIP|Download]] the source code

Used in [[https://en.wikipedia.org/wiki/Miles_Sound_System|many commercial titles]] back in the days of DOS, the author (John Miles) has opened up the sound system for anyone to use.

Do note that there were many, many updates to the drivers used in the Miles Sound System over the years, and some games/manufacturers distributed updated drivers with their games, so the driver/sdk source linked above probably isn't an exhaustive list of all the supported sound cards.