Allegro DMC-specific information

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

                     DMC-specific information.

             See readme.txt for a more general overview.

# DMC notes

Status: complete.

Caveats: The DMC port does not support assembly, so ALLEGRO_USE_C must be set when compiling. The DMC runtime library does not support unicode paths.

DMC is the only Windows compiler that can build a static library that can be used with DAllegro.

The instructions at http://wiki.allegro.cc/Build/DMC might be more up to date.

# Required software

- Digital Mars C/C++ Compiler - http://www.digitalmars.com/d/1.0/download.html
- Digital Mars Basic Utilities - http://ftp.digitalmars.com/bup.zip
- GNU Make - http://sourceforge.net/project/showfiles.php?group_id=9328
- Recent set of DirectX and other Windows SDK headers. - http://alleg.sourceforge.net/files/dx70_dmc.zip

# Setting up DMC

1. Unzip the Digital Mars compiler (dmc.zip) and place the files in c:\dmc.
2. Unzip the Basic Utilities (bup.zip) and place them in the same folder. (The exe files should all be in the c:\dmc\bin folder.)
3. Unzip the DirectX 7 package (dx70_dmc.zip) and place the include files in c:\dmc\include and the library files in c:\dmc\lib. (This will overwrite some of DMC's default DX files.)
4. Extract only the usr/local/wbin/make.exe file from UnxUtils.zip to your desktop, rename it to gmake.exe, and copy it to c:\dmc\bin.
5. Add c:\dmc\bin to your PATH environment variable.
6. Create the DMCDIR environment variable and set it to c:\dmc

# Building Allegro

## Step by Step Instructions

- Extract the Allegro source zip file to c:\allegro
- Open up a MS-DOS prompt and type the following commands.

>        cd\allegro
>        fix dmc
>        gmake obj\dmc\plugins.h
>        gmake all ALLEGRO_USE_C=1 STATICLINK=1
>        gmake installall ALLEGRO_USE_C=1 STATICLINK=1
>        gmake all ALLEGRO_USE_C=1
>        gmake installall ALLEGRO_USE_C=1

## Advanced Build Options

The above instructions build six versions of Allegro, the Demo, tools, examples, and the documentation. If you don't need all of that, you can customize what gets built. Obviously, if you don't need both the static or dynamic libraries, simply don't run the associated commands. If you don't care about the Debugging or Profiling versions, you can remove the word all from the command line. For example:

>        gmake ALLEGRO_USE_C=1
>        gmake install ALLEGRO_USE_C=1

builds and installs the optimized, dynamic Allegro library along with all of the examples, documents, etc. Or if you want to specifically build and install the debug and profiling versions:

>        gmake ALLEGRO_USE_C=1 DEBUGMODE=1
>        gmake install ALLEGRO_USE_C=1 DEBUGMODE=1
>        gmake ALLEGRO_USE_C=1 PROFILEMODE=1
>        gmake install ALLEGRO_USE_C=1 PROFILEMODE=1

If you only want to build the library (without the extra stuff), specifically request to make the lib target:

>        gmake lib ALLEGRO_USE_C=1

That would only build the optimized, dynamic Allegro library. Other targets besides lib exist; refer to Makefile.all and Makefile.dmc for more information. All of the options can be mixed and matched where it makes sense.

Note that DMC can only build the C version of Allegro (as opposed to using some assembly), so the ALLEGRO_USE_C=1 option is mandatory.

# Using Allegro

## Hello World

For a simple example, consider hello.c:

>        #include <allegro.h>

>        int main(void)
>        {
>                allegro_init();
>                set_gfx_mode(GFX_AUTODETECT_WINDOWED, 640, 480, 0,0);
>                allegro_message("Hello, World!");
>                return 0;
>        }
>        END_OF_MAIN()

First, you must include the Allegro header file. Inside the main function, you should call allegro_init() to set up Allegro. You must do that before calling (almost) any of the other Allegro functions. (This program will create a 640x480 window and then pop-up the message "Hello, World!".) At the end of the main function, you must include the END_OF_MAIN() macro (no semicolon is needed).

## Dynamic Version (DLL)

To compile this program, type:

>        dmc -c test.c

This will create the object file. It will then need to be linked to Allegro when you create the executable:

>        dmc test.obj alleg.lib -otest.exe

That will build test.exe, which will require the Allegro DLL (eg: alleg42.dll) to run. Alternatively you could use allp.lib for profiling or alld.lib for debugging.

## Static Version

If you wanted to statically link this program so that the Allegro DLL is not required, you must first compile it like:

>        dmc -c test.c -DALLEGRO_STATICLINK=1

Then you can link it against any of the static versions of Allegro:

>        dmc test.obj alleg_s.lib kernel32.lib user32.lib gdi32.lib comdlg32.lib
>           ole32.lib dinput.lib ddraw.lib winmm.lib dsound.lib dxguid.lib

(All of that should be entered on one line.) Note that you have to include a bunch of Windows libraries when you statically link! As before, you can also use allp_s.lib for profiling and alld_s.lib for debugging.