Allegro Watcom-specific information

         ______   ___    ___
        /\  _  \ /\_ \  /\_ \
        \ \ \L\ \\//\ \ \//\ \      __     __   _ __   ___
         \ \  __ \ \ \ \  \ \ \   /'__`\ /'_ `\/\`'__\/ __`\
          \ \ \/\ \ \_\ \_ \_\ \_/\  __//\ \L\ \ \ \//\ \L\ \
           \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
            \/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
                                           /\____/
                                           \_/__/

                    Watcom-specific information.

             See readme.txt for a more general overview.

# Watcom notes

Status: complete and fully functional, but not so widely used and tested as the djgpp code. This version is heavily based on the djgpp version, basically just emulating whatever parts of the djgpp libc aren't provided by Watcom. See `docs/build/djgpp.txt` for information about the available hardware drivers: the djgpp and Watcom versions are 100% identical in this respect.

This library works with version 10.6 and the various 11.0 versions of the Watcom C compiler, as well as with Open Watcom 1.0 or later.

# Required software

- Watcom C version 10.6 or 11.0x, or Open Watcom 1.0 or later.
- djgpp compiler (`djdev*.zip`, `gcc*b.zip`, and `bnu*b.zip`).
- GNU make (`mak*b.zip`).
- GNU sed (`sed*b.zip`): Required for 10.6: Used to build asm sources. Optional for other versions: Used by "`make depend`".

Except for the Watcom compiler itself, all of the above packages can be downloaded from your nearest SimTel mirror site, in the `/pub/simtelnet/gnu/djgpp/` directory, or you can use the zip picker on http://www.delorie.com/djgpp/. See the djgpp `readme.1st` file for information about how to install djgpp.

# Installing Allegro

This is a source-only distribution, so you will have to compile Allegro before you can use it. To do this you should:

Type "`cd allegro`", followed by "`fix.bat watcom`", followed by "`make`". Then go do something interesting while everything compiles. When it finishes compiling, type "`make install`" to set the library up ready for use.

The makefile will try to guess whether you are using Watcom 10.6 or 11.0 by checking for the presence of `wdisasm.exe`. If it gets this wrong, you may need to override it by passing `WATCOM_VERSION=10.6` or `WATCOM_VERSION=11` as arguments to make, or setting the `WATCOM_VERSION` environment variable.

If you also want to install a debugging version of the library (highly recommended), now type "`make install DEBUGMODE=1`". Case is important, so it must be `DEBUGMODE`, not debugmode!

If you also want to install a profiling version of the library, now type "`make install PROFILEMODE=1`".

If your copy of Allegro doesn't include the `makefile.dep` dependency files (unlikely, unless you have run "`make veryclean`" at some point), you can regenerate them by running "`make depend`".

# Using Allegro

All the Allegro functions, variables, and data structures are defined in `allegro.h`. You should include this in your programs, and link with either the optimised library `alleg.lib`, the debugging library `alld.lib`, or the profiling library `allp.lib`. Programs that use Allegro must be compiled to use the stack based calling convention (wcl386 option '`-5s`'), and with stack overflow checks disabled (wcl386 option '`-s`'). You will also have to increase the stack size from the miserly Watcom default, using a wcl386 option like '`-k128k`', or a linker command like '`option stack=128k`'.