@html_text_substitution=readme.txt|readme.txt
@external-css=../allegro.css
@document_title=Notes on building the MinGW/Cygwin version of Allegro.
@
______ ___ ___
/\ _ \ /\_ \ /\_ \
\ \ \L\ \\//\ \ \//\ \ __ __ _ __ ___
\ \ __ \ \ \ \ \ \ \ /'__`\ /'_ `\/\`'__\/ __`\
\ \ \/\ \ \_\ \_ \_\ \_/\ __//\ \L\ \ \ \//\ \L\ \
\ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
\/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
/\____/
\_/__/
Notes on building the MinGW/Cygwin version of Allegro.
Written by Henrik Stokseth.
Robert J Ohannessian added some updates to the installation instructions
and an example on how to use Dev-C++ with Allegro.
Elias Pschernig and Hein Zelle revamped the cross-compilation section.
Andrei Ellman updated the Cygwin section.
Michal Molhanec simplified the Dev-C++ instructions.
See readme.txt for a more general overview.
@
@heading
MinGW notes
This is a complete MinGW port of Allegro. This build doesn't rely
on the DLL files produced by MSVC any longer 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/system directory (or winnt/system32 directory
under Windows NT/2k/XP) if you want to test it.
If you have both GNU bash and GNU fileutils installed on your system, then
set the environment variable UNIX_TOOLS (set UNIX_TOOLS=1). This is needed
because GNU make will automatically use sh.exe instead of command.com if
it finds it somewhere in the PATH. This step is not necessary when using
MSYS or Cygwin as the makefile automatically sets UNIX_TOOLS for you.
"make depend" and "fixdll.bat" require that you have GNU sed installed.
"fixdll.bat" requires that you have GNU sort (not DOS sort!) installed.
You can download some extra utilities for MinGW from:
'http://sourceforge.net/projects/gnuwin32/'
@heading
Obtaining and installing the compiler & tools
You have four choices when it comes to installing MinGW and Allegro
on your computer:
The section 'Setting up MinGW to build Allegro' describes how to set
up the MinGW command line tools which is the preferred 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 Dev-C++ environment to work with Allegro. This is the preferred
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
MinGW 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'.
@heading
Setting up MinGW to build Allegro
The procedure is as follows:
1. Make sure you have a working MinGW installation. You can download the
complete distribution or individual packages from 'http://www.mingw.org'
or 'http://sourceforge.net/projects/mingw/'. You can also use
the Minimal SYStem (MSYS) environment with Allegro.
2. Get the minimal DirectX 7 SDK for MinGW (dx70_mgw.zip). You
download it from 'http://alleg.sourceforge.net/wip.html'. Note
that this is *not* the same package as 'dx70_min.zip'. Unzip it
to the compiler directory, overwriting any existing files.
3. Set the environment variable MINGDIR to the compiler directory. If you
use Windows 9x, you can add the line
set MINGDIR=c:\MinGW
to your 'c:\autoexec.bat' file, assuming 'c:\MinGW' is the compiler
directory, and reboot. If you use Windows ME, you can run 'msconfig',
select the 'Environment' tab and then add MINGDIR. If you use
Windows NT/2k/XP, you can open the Control Panel, click the 'System'
applet, the 'Advanced' tab and finally the 'Environment' button, and
then add MINGDIR. If you use MSYS, add instead the line
export MINGDIR=/mingw
to your 'c:\msys\etc\profile' file.
Test the installation by typing the following on the command line:
'gcc -v'. The answer should be similar to:
Reading specs from ../lib/gcc-lib/mingw32/3.2/specs
Configured with: ../gcc/configure --with-gcc --with-gnu-ld
--with-gnu-as --host=mingw32 --target=mingw32 --prefix=/mingw
--enable-threads --disable-nls --enable-languages=f77,c++,objc,ada
--disable-win32-registry --disable-shared
Thread model: win32
gcc version 3.2 (mingw special 20020817-1)
If you don't know how to open a terminal, you can click on 'Start -> Run'
then type "command". Under Windows 2k/XP, you should type "cmd" instead.
@heading
Setting up Dev-C++ to build Allegro
Note: we assume that the complete version of the Dev-C++ environment (i.e
with the bundled MinGW compiler) is used. If you use instead Dev-C++ as
a mere IDE on top of an already installed MinGW compiler, follow the
instructions given in the previous section.
The procedure is as follows:
1. Make sure you have a working Dev-C++ installation. You can download the
complete version from 'http://bloodshed.net/dev/devcpp.html'.
2. Get the DirectX SDK: go to Tools\Check for Updates/Packages... and
install the DirectX package. Close Dev-C++.
3. Add 'c:\DevCpp\bin' to the beginning of your PATH environment variable
and set the environment variable MINGDIR to 'c:\DevCpp'. If you use
Windows 9x, you can add the lines
PATH=c:\DevCpp\bin;%PATH%
set MINGDIR=c:\DevCpp
to your 'c:\autoexec.bat' file and reboot. If you use Windows ME, you
can run 'msconfig', select the 'Environment' tab, then modify PATH and
add MINGDIR. If you use Windows NT/2k/XP, you can open the Control
Panel, click the 'System' applet, the 'Advanced' tab and finally the
'Environment' button, then modify PATH and add MINGDIR.
Test the installation by typing the following on the command line:
'gcc -v'. The answer should be similar to:
Reading specs from ../lib/gcc-lib/mingw32/3.2/specs
Configured with: ../gcc/configure --with-gcc --with-gnu-ld
--with-gnu-as --host=mingw32 --target=mingw32 --prefix=/mingw
--enable-threads --disable-nls --enable-languages=f77,c++,objc,ada
--disable-win32-registry --disable-shared
Thread model: win32
gcc version 3.2 (mingw special 20020817-1)
If you don't know how to open a terminal, you can click on 'Start -> Run'
then type "command". Under Windows 2k/XP, you should type "cmd" instead.
@heading
Setting up Cygwin to build Allegro
The procedure is as follows:
1. Make sure you have a working Cygwin installation. You can download the
setup.exe program from 'http://sources.redhat.com/cygwin/'.
You will need the followin packages: bash, binutils, cygwin, cygutils,
fileutils, gcc, gdb, login, make, man, mingw-runtime, sed, sh-utils,
texinfo, textutils and w32api.
2. Get the minimal DirectX 7 SDK for MinGW. (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'. If you are asked
if you want to overwrite any existing files, choose to overwrite them.
3. Put the following text in '/etc/profile' (c:\cygwin\etc\profile)
export ALLEGRO_USE_CYGWIN=1
export MINGDIR=/usr/local
export CPATH=/usr/local/include
export LIBRARY_PATH=/usr/local/lib
Note: if the CPATH or LIBRARY_PATH variables are already set, you will
have to append the new path to the existing one by using a colon (":")
as the separator.
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/3.2/specs
gcc version 3.2 20020927 (prerelease)
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
MinGW 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).
@heading
Cross compilation
The procedure is as follows:
1. Download and install the MinGW 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 MinGW (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.
6. To build the documentation, use the native build process. This
limitation will eventually be removed.
@heading
Installing Allegro
This assumes you have unzipped allegro to c:\allegro or, if you are using
MSYS, you have unzipped it to c:\msys\allegro (which is equivalent to
/allegro from within the MSYS environment) or, if you are using Cygwin,
you have unzipped it to c:\cygwin\allegro (which is equivalent to
/allegro from within the Cygwin environment).
First configure Allegro for MinGW. Unless you are using MSYS or Cygwin,
enter 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
If you are using MSYS or Cygwin, start your environment, which you can
find either on your desktop and/or on your Windows start menu. The
following commands should then be used instead of the ones above:
cd /allegro
./fix.sh mingw32 --dtou (--dtou can be replaced by --quick for MSYS).
Now you're ready to build the Allegro library with:
make (or mingw32-make if you are using a recent version of MinGW)
The dynamically linked version of Allegro gets built by default. If you
want to build the statically linked version of Allegro, use:
make STATICLINK=1
If you want to build either the debug or the profile version of the
library, enter one of the following commands:
make DEBUGMODE=1 (dynamically linked)
make DEBUGMODE=1 STATICLINK=1 (statically linked)
make PROFILEMODE=1 (dynamically linked)
make PROFILEMODE=1 STATICLINK=1 (statically linked)
A list of all the available options:
CROSSCOMPILE
Set this if you are crosscompiling; it implies UNIX_TOOLS.
WARNMODE
Set this if you want Allegro to display and stop on nearly all
warnings issued by the compiler. Allegro should compile fine with
this set.
TARGET_ARCH_COMPAT
or
TARGET_ARCH_EXCL
These affect the level of processor dependant optimisation that
Allegro uses. You can set either of these to the processor type you
want to optimize for. The difference between these two is that
TARGET_ARCH_COMPAT optimise for the given processor so that the code
will still run on older processors, while TARGET_ARCH_EXCL will
generate code that will run exclusively on the given processor and of
course newer ones. Example: set TARGET_ARCH_COMPAT=i686
TARGET_OPTS
Affects the general optimisations that Allegro uses.
UNIX_TOOLS
If your system does not have the usual DOS tools available (`md',
`rd', `copy', etc., and commands which understand the \ character),
then set this to 1 to use the Unix equivalents. This is set
implicitly when you set CROSSCOMPILE, and is also set automatically
when you are running under bash.
To activate any of these, type (for example) "make WARNMODE=1".
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 MinGW 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 library. Run:
make install
with the same options you passed to 'make' in order to build the library.
You have now installed Allegro! See the rest of the documentation and
examples to learn more about it.
@heading
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). The names of
the statically linked Allegro libraries are post-fixed with '_s' so that
you will link with either liballeg_s.a, liballd_s.a or liballp_s.a.
Don't forget that you need to use the END_OF_MAIN() macro right after
your main() function.
@heading
Compiling manually with MinGW
A simple example of a command line to compile an Allegro program with
MinGW looks like:
gcc foo.c -Wl,--subsystem,windows -O2 -Wall -o foo.exe -lalleg
If you are compiling with Cygwin, the compiler option '-mno-cygwin' must
be added, both at compile-time and at link-time:
gcc foo.c -Wl,--subsystem,windows -mno-cygwin -O2 -Wall -o foo.exe -lalleg
Note that, if you want to make a console application, you must use
'-Wl,--subsystem,console' instead of '-Wl,--subsystem,windows'.
@heading
Creating a program with Dev-C++
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' or select 'Parameters tab' and enter -lalleg (or -lalld for
the debug mode) in the box under 'Linker'.
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!