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


   Notes on building the MingW32/Cygwin version of Allegro.

   Written by Henrik Stokseth.

   Robert J Ohannessian added some updates to the installation instructions
   and added an example on how to use Dev-C++ with Allegro.

   Elias Pschernig and Hein Zelle revamped the cross-compilation section.

   See readme.txt for a more general overview.



=======================================
============ MingW32 notes ============
=======================================

   This is a complete MingW32 port of Allegro. This build doesn't rely
   on the DLL files produced by MSVC but can make them itself.
   I'm proud to say Allegro can now make Win32 programs entirely using
   free professional tools. On that note I'd like to thank Peter Puck for
   making this a reality and for finishing off what I started. Enjoy!

   The screensaver example is built, but you must copy scrsave.scr to your
   windows directory if you want to test it.
   
   If you have both GNU Bash and GNU fileutils installed then set the
   environment variable UNIX_TOOLS (set UNIX_TOOLS=1) so that compilation
   will work. This is because GNU make will automatically use sh.exe instead
   of command.com if it finds it somewhere in the path.

   "make depend" and "fixdll.bat" requires that you have GNU sed installed.
   "fixdll.bat" requires that you have GNU sort (not DOS !) installed.
   The clean targets require that you have GNU fileutils installed.
   You can download some extra utilities for MingW32 from:
      http://sourceforge.net/projects/gnuwin32/

   If you at any stage in the installation process get an
   'Out of Environment space' message, then please see the Allegro F.A.Q.
   for how to fix this.



=====================================================
=== Obtaining and installing the compiler & tools ===
=====================================================

   You have four choices when it comes to installing MingW32 and Allegro
   on your computer.

   - The section 'Setting up MingW32 to build Allegro' describes how to set
     up the MingW32 command line tools which is the prefered choice for
     those who like to work on the command line.

   - The section 'Setting up Dev-C++ to build Allegro' describes how to set
     up the MingW32 command line tools in addition to the Dev-C++ IDE. This
     is the prefered choice for those who like to work in a graphical
     development environment.

   - The section 'Setting up Cygwin to build Allegro' describes how to set
     up your Cygwin compiler to build Allegro. Cygwin offers a mature
     UNIX-like environment for you to work in.

   - The last section 'Cross compilation' describes how to set up the
     MingW32 command line tools to compile Win32 programs from your Linux
     box.

   Note: You will need a program to decompress .zip, .tar.gz and optionally
   .tar.bz2 files. I recommend PowerArchiver (shareware) which can be
   downloaded from: 'http://www.powerarchiver.com'.



=============================================
==== Setting up MingW32 to build Allegro ====
=============================================

   For the MingW32 part, you will need to obtain the following 
   distributions from the internet. Please don't unzip/install until step 3.

   1) Download the complete MingW32 distribution from 'http://www.mingw.org'
      or 'http://sourceforge.net/projects/mingw/'. You should download the
      complete package instead of the many small ones unless you want to
      move files manually. :-) Note that gcc 2.95.3 at least is required.

   2) Get the minimal DirectX 7 SDK for MingW32. (dx70_mgw.zip) Download it
      from 'http://alleg.sourceforge.net/wip.html'. Please don't confuse it
      with dx70_min.zip.

   3) Install the MingW32 distribution from step 1. I recommend you unzip it
      to 'c:\mingw32' (the following steps assume this is what you used).
      Do NOT install it in a directory name with spaces, plus signs, minus
      signs, slashes, or anything else that's fancy enough to break the
      compiler. That goes double for people installing in C:\Program Files.

   4) Unzip the file from step 2 to 'c:\mingw32'. Overwrite any existing
      files. Note: If you use an older copy of MingW32 where the Include and
      Lib subdirectories doesn't exist, then unzip the file to
      'c:\mingw32\i386-mingw32msvc' instead.

   5) You now need to add 'c:\mingw32\bin' to the *beginning* of your PATH.

      If you use Windows 9x you can add the line
      'path c:\mingw32\bin;%PATH%' to the end of your 'c:\autoexec.bat'
      file. You can use 'edit', 'msconfig', 'sysedit', 'notepad' or any
      other editor capable of editing ASCII text.

      If you use Windows NT (which includes 2000 and XP) then open
      Control Panel, and click the 'System' applet, then the 'Advanced' tab,
      and finally the 'Environment' button. Select the PATH= entry, and add
      'c:\mingw32\bin' to it.

   6) Likewise add the line 'set MINGDIR=c:\mingw32' to your
      'c:\autoexec.bat'.

   7) Now reboot!

   Test the installation by typing the following on the command line:
   'gcc -v'. The answer should be similar to:
   
   Reading specs from C:\MINGW32\BIN\..\lib\gcc-lib\i386-mingw32msvc\2.95.3\specs
   gcc version 2.95.3 20010726 (release)

   (If you don't know how, you can click on Start -> Run then type "command".
   Under Windows 2000 and XP, you should type "cmd" instead.)



=============================================
==== Setting up Dev-C++ to build Allegro ====
=============================================

   Some people prefer to use the Dev-C++ distribution to make Allegro
   programs. Dev-C++ is a neat development IDE and includes an updated
   MingW32 compiler. Please do not unzip or install anything until step 4.

   Getting what you need:

   1) Download the complete MingW32 distribution from 'http://www.mingw.org'
      You should download the complete package instead the many small ones
      unless you want to move files manually. :-) At the time of writing
      (November, 2001) version 1.1 is the newest. A direct link is here:
      'http://prdownloads.sourceforge.net/mingw/MinGW-1.1.tar.gz'

   2) Download the Dev-C++ 4 IDE (without MingW32 compiler and libraries)
      from 'http://www.bloodshed.net/dev/download.html'.
      Once again, make sure you do not install it until you get to step 4.

   3) Get the minimal DirectX 7 SDK for MingW32. (dx70_mgw.zip) Download it
      from 'http://alleg.sourceforge.net/wip.html'. Please don't confuse it
      with dx70_min.zip.


   Installation process:

   4) Install the package from step 1. I recommend you unzip it
      to 'C:\Dev-Cpp' (the following steps assume this is what you used).
      Do NOT install it in a directory name with spaces, plus signs, slashes, 
      or anything else that's fancy enough to break the compiler. 
      That goes double for people installing in C:\Program Files.

   5) Install the package from step 2 to 'C:\Dev-Cpp'. Overwrite any existing
      files.

   6) Unzip the file from step 3 to 'C:\Dev-Cpp' Overwrite any existing
      files.

   7) You now need to add 'C:\Dev-Cpp\bin' to the *beginning* of your PATH.

      If you use Windows 9x you can add the line
      'path c:\Dev-Cpp\bin;%PATH%' to the end of your 'c:\autoexec.bat'
      file. You can use 'edit', 'msconfig', 'sysedit', 'notepad' or any
      other editor capable of editing ASCII text.

      If you use Windows ME, you'll need to run 'msconfig', then select the
      'Environment' tab, and add 'c:\Dev-Cpp\bin' to PATH.

      If you use Windows NT (which includes 2000 and XP) then open
      Control Panel, and click the 'System' applet, then the 'Advanced' tab,
      and finally the 'Environment' button. Select the PATH= entry, and add
      'c:\Dev-Cpp\bin' to it.

   8) Likewise add the line 'set MINGDIR=C:\Dev-Cpp' to your
      'c:\autoexec.bat'.

   9) Now reboot!

   Test the installation by typing the following on the command line:
   'gcc -v'. The answer should be simmilar to:
   
   Using builtin specs.
   gcc version 2.95.2 19991024 (release)

   (click on Start -> Run then type "command" or "cmd" to get a command
   prompt.)


   10) Now scroll down a bit for instructions on how to install Allegro
       and an example program.



============================================
==== Setting up Cygwin to build Allegro ====
============================================

   1) Obtain the Cygwin packages. Get setup.exe from
      'http://sources.redhat.com/cygwin/'. Start the Cygwin setup program
      and download these packages: bash, binutils, cygwin, cygutils,
      fileutils, gcc, gdb, login, make, man, mingw-runtime, sed, sh-utils,
      texinfo, textutils and w32api.

      Install these packages (run setup.exe once more). The rest of these
      instructions assumes you installed to 'c:\cygwin'. When setup asks
      you which line endings you want, select unix-style instead of DOS.
      
   2) Get the minimal DirectX 7 SDK for MingW32. (dx70_mgw.zip) Download it
      from 'http://alleg.sourceforge.net/wip.html' and unzip it to a
      temporary directory, for instance 'C:\Temp'. Then move the contents of
      'C:\Temp\lib' to 'C:\cygwin\lib\w32api', and the contents of
      'C:\Temp\include' to 'c:\cygwin\usr\include\w32api'.

   3) put the following text in '/etc/profile' (c:\cygwin\etc\profile)
      export ALLEGRO_USE_CYGWIN=1
      export MINGDIR=/usr/local

   4) Start your cygwin BASH shell which you can find either on your desktop
      and/or on your Windows start menu. Make sure /bin/sh exists, if not
      just run: 'ln -s /bin/bash.exe /bin/sh.exe'.

   5) Then run './fix.sh mingw32 --dtou'. This will take a while...

   Test the installation by typing the following in the BASH shell:
   'gcc -v'. The answer should be similar to:
   
   Reading specs from /usr/lib/gcc-lib/i686-pc-cygwin/2.95.3-5/specs
   gcc version 2.95.3-5 (cygwin special)

   Note! If you have problems installing the profiling version of the Allegro
   library, you will probably need to copy a file called libgmon.a from the
   MingW32 distribution to your /lib/mingw directory (c:\cygwin\lib\mingw) in
   cygwin. This is expected to be fixed in a later release of the
   mingw-runtime package (I'm currently using mingw-runtime-1.2-1).



=======================================
========== Cross compilation ==========
=======================================

   Brief example of how to set up a MingW32 cross-compiler system:

   1) Download and install the MingW32 cross-compiler. You can get the
      software:
      - directly from the MingW site:
          http://sourceforge.net/projects/mingw/
        You need the following packages (as of February 2003):
          - gcc (gcc-3.2.2-20030208-1-src.tar.gz)
          - binutils (binutils-2.13.90-20030111-1-src.tar.gz)
          - mingw runtime (mingw-runtime-2.4.tar.gz)
          - w32api (w32api-2.2.tar.gz)
        Optionally, you can get from the SDL site,
         http://www.libsdl.org/extras/win32/common:
          - opengl-devel (opengl-devel.tar.gz)
      - using a more convenient script with instructions for downloading:
         http://www.libsdl.org/extras/win32/cross/README.txt
        Follow the instructions, and make sure to edit the build-crosh.sh
        script so it downloads the most recent version of gcc and binutils.
      - as a premade Debian package called 'mingw32', which you can install
        with 'apt-get install mingw32'.

   2) Get the minimal DirectX 7 SDK for MingW32 (dx70_mgw.zip).
      Download it from 'http://alleg.sourceforge.net/wip.html' and unzip it
      in the cross-compiler base directory. Make sure you convert all text
      files to unix style (unzip -a) or the preprocessor will croak. The
      DirectX package downloaded and installed by the SDL script is not up
      to date: replace it with the package from the Allegro site.

   3) Edit the file 'xmake.sh' in the root of your Allegro directory,
      replacing XC_PATH, XPREFIX and INSTALL_BASE with the right names.
      For example, if your compiler's base dir (the one with bin, lib and
      include sub-folders) is /usr/i586-mingw32msvc, and you have prefix-less
      binaries in /usr/i586-mingw32msvc/bin, you would use:

      XC_PATH=/usr/i586-mingw32msvc/bin
      XPREFIX=
      INSTALL_BASE=/usr/i586-mingw32msvc

      Note that the build-cross.sh script from SDL installs binaries both
      with and without prefix, but some binaries (windres specifically)
      are installed only with prefix. If you installed the crosscompiler
      in /opt/cross-tools using this script, you would use:

      XC_PATH=/opt/cross-tools/i386-mingw32msvc/bin:/opt/cross-tools/bin
      XPREFIX=i386-mingw32msvc-
      INSTALL_BASE=/opt/cross-tools/i386-mingw32msvc

   4) Run './fix.sh mingw32 --dtou' (--dtou is only needed if your Allegro
      directory has text files in DOS format, otherwise you can use --quick).
      If you are using a CVS version of Allegro, run 'make depend' to
      generate the build dependencies, then run 'misc/fixdll.sh' to generate
      the allegro.def file. You are now finished with all the preparations.
   
   5) You can now run './xmake.sh' to build the Allegro library and then run
      './xmake.sh install' as root to install it. Afterwards, you can use
      'xmake.sh' as you would use 'make' to compile your Allegro programs, or
      you can use the 'cross-make.sh' and 'cross-configure.sh' scripts from
      the SDL site. You must use 'xmake.sh' to compile Allegro itself though.



============================================
============ Installing Allegro ============
============================================

   Step-by-step instructions on how to build the MingW32 version of Allegro.
   This assumes you have unzipped allegro to c:\allegro

   First configure Allegro by entering the following on the commandline:
   (click on Start -> Run then type "command" or "cmd" to get a command
   prompt)

   cd c:\allegro
   fix.bat mingw32

   The dynamically linked version of Allegro gets built by default but if
   you want to build the statically linked version of Allegro write the
   following on the command line:

   SET STATICLINK=1

   If you want to build either the debug or the profiling version of
   the library enter one of the following. Skip them to build the
   release (default) version.

   SET DEBUGMODE=1
   SET PROFILEMODE=1

   Now we're ready to make the Allegro library. 

   make

   If your copy of Allegro does not include the linker .def file (unlikely,
   unless you have run "make veryclean" at some point, or are using the CVS
   version of Allegro), you can regenerate it by running "misc\fixdll.bat".
   You will need to have GNU sed and sort installed for this operation to
   work. The version of sed that is linked from the MingW32 site does not
   work properly; it has issues with end-of-line characters. You should get
   sed and sort from the link at the top of this document.

   Once the build is finished you can recover some disk space by running
   "make compress", which uses the UPX program to compress the executable
   files and the optimized dll. Before running "make compress", you must set
   the environment variable UPX_BIN to point to upx.exe. You will have to
   do run "make compress" before "make install" if you want the compressed
   dll to be copied to the windows directory. To recover even more disk
   space, you can run "make clean" to get rid of all the temporary files and
   HTML format documentation.

   And then the last thing; Installing the Allegro library.

   make install
  
   You have now installed MingW32 and allegro! See the rest of the
   documentation and examples to learn more about it.



=======================================
============ 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 liballeg.a, the debugging library 
   liballd.a, or the profiling library liballp.a. You should include the
   Allegro DLLs in any software you release to the public.

   When using a statically linked library, you must define the preprocessor
   symbol ALLEGRO_STATICLINK before including any of the Allegro headers and
   link your program against Allegro and the main Win32/DirectX libraries
   in that order (see the variable LIBRARIES in makefile.mgw).

   Don't forget that you need to use the END_OF_MAIN() macro right after 
   your main() function.

=======================================

   A simple example of a command line to compile an allegro program
   with MingW32:

   gcc foo.c -mwindows -O2 -Wall -o foo.exe -lalleg

=======================================

   A simple example on how to create a little program with Dev-C++:

   Launch Dev-C++ and create a new project (File/New Project). Select
   "Windows Application", then click on the "Ok" button. Name your
   project and give associate it to a new file. You should now see a
   sample code in a window. Close that window since you won't be
   needing it (Allegro is much simpler to use than this). Create a
   new file (File/New Source File), then write a small Allegro
   program. You can inspire yourself by the Allegro examples if you
   wish. Here's a small program you can type to see if everything
   worked until now:

      #include <allegro.h>

      int main() {
         allegro_init();
         allegro_message("Hello World!");
         return 0;
      }
      END_OF_MAIN();

   You now need to tell Dev-C++ that you'd like to make a program that
   uses Allegro. For that, go in the Project Options screen
   (Project/Project Options menu), then enter -lalleg (or -lalld for
   the debug mode) in the box under 'Further object file or linker
   options'.

   Compile your project! Simply click on the green check mark on
   your Dev-C++ toolbar. Correct any syntax errors in your code,
   then click on "Execute" to run the program. If all worked
   you will see a message box pop up with "Hello World" inside of it.



   Happy coding!
