<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><head><title>
Allegro MSVC-specific information
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" title="Default" type="text/css" href="../allegro.css"></head><body bgcolor=white text=black link="#0000ee" alink="#ff0000" vlink="#551a8b">
<pre>
______ ___ ___
/\ _ \ /\_ \ /\_ \
\ \ \L\ \\//\ \ \//\ \ __ __ _ __ ___
\ \ __ \ \ \ \ \ \ \ /'__`\ /'_ <tt>`\/\`'</tt>__\/ __`\
\ \ \/\ \ \_\ \_ \_\ \_/\ __//\ \L\ \ \ \//\ \L\ \
\ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
\/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
/\____/
\_/__/
MSVC-specific information.
See <a href="../readme.html">readme.txt</a> for a more general overview.
</pre>
<p><br>
<h1><a name="MSVC notes">MSVC notes</a></h1>
<p>
Status: complete.
<p>
The screensaver example is built, but you must copy <tt>scrsave.scr</tt> to
your <tt>windows/system</tt> directory (or <tt>winnt/system32</tt> directory
under Windows NT/2k/XP) if you want to test it.
<p>
You may also want to refer to one of the following, as they may include
more up to date information:
<p>
<ul><li><a href="http://wiki.allegro.cc/Build/MSVC_6">http://wiki.allegro.cc/Build/MSVC_6</a>
<li><a href="http://wiki.allegro.cc/Build/MSVC_7">http://wiki.allegro.cc/Build/MSVC_7</a>
<li><a href="http://wiki.allegro.cc/Build/MSVC_8">http://wiki.allegro.cc/Build/MSVC_8</a>
</ul>
<p>
<h1><a name="Project Files">Project Files</a></h1>
<p>
Project files for MSVC 6, 7, and 8 are included in the /build/msvc directory.
If you choose to use them, you can ignore the other sections of this
document. (The "Using Allegro" section would still apply.)
<p>
You do need to make sure you have recent versions of the DirectX and
Windows Platform headers, as described in the "Required software section."
<p>
Before you can use the project files, you must first double-click on the
/build/msvc/pre-build-msvc.bat file. Then open the Allegro project file
and select Build / Batch Build from the menu. Select the versions you want to
build and then press the Build button.
<p>
(Note that under MSVC 6 you may need to repeat the build process several times
due to compiler bugs.)
<p>
If everything builds successfully, you'll need to copy some files to finish
the installation:
<p>
<ul><li>Copy the contents of C:\allegro\include to "Visual Studio\VC\include"
<li>Copy the .lib files from C:\allegro\lib\msvc to "Visual Studio\VC\lib"
<li>Copy the .dll files from C:\allegro\lib\msvc to C:\Windows\System32
</ul>
<p>
The most common location of Visual Studio is "C:\Program Files\Microsoft
Visual Studio."
<p>
Then you can build the rest of the examples, demos, tests, and tools by
opening up their respective project files and selectiong Batch Build from
the menu.
<p><br>
<h1><a name="Required software">Required software</a></h1>
<p>
<ul><li>Microsoft Visual C++.
<li>Recent set of DirectX and other Windows SDK headers.
<li>A GNU environment to run GNU tools with, such as DJGPP, MinGW or Cygwin.
Depending on which one you choose, you will need the following packages:
<ul><li>DJGPP: compiler (<tt>djdev*.zip</tt>, <tt>gcc*b.zip</tt>, <tt>bnu*b.zip</tt>).<br>
GNU make (<tt>mak*b.zip</tt>).<br>
Optional: GNU sed (<tt>sed*b.zip</tt>). Used by "<tt>make depend</tt>" and
"<tt>fixdll.bat</tt>".<br>
Optional: GNU sort (<tt>txt*b.zip</tt>). Used by "<tt>fixdll.bat</tt>".<br><br>
<li>MinGW: compiler (mingw-runtime, gcc, binutils).<br>
GNU make.<br>
Optional: GNU sed. Used by "<tt>make depend</tt>" and "<tt>fixdll.bat</tt>".<br>
Optional: GNU sort (textutils). Used by "<tt>fixdll.bat</tt>".<br>
Optional: w32api. See next section about details.<br><br>
<li>Cygwin: compiler (cygwin, gcc, binutils).<br>
GNU make.<br>
Optional: GNU sed. Used by "<tt>make depend</tt>" and "<tt>fixdll.sh</tt>"<br>
Optional: GNU sort (textutils). Used by "<tt>fixdll.sh</tt>".<br><br>
</ul></ul>
Allegro should work ok with MSVC versions 4, 5, 6, 7.0 (.NET),
7.1 (.NET 2003) and 8.0 (.NET 2005). However note that the lowest tested
version is 6.
<p>
The DirectX SDK can be obtained directly from Microsoft. An old version
of the headers is included with MSVC 6, but Allegro requires more recent
files. You should either copy the current headers into your MSVC include
and lib directories, or alter your <tt>INCLUDE</tt> and <tt>LIB</tt> environment variables
to put the DirectX SDK files in front of the standard MSVC locations.
<p>
If you choose to use DJGPP as your GNU environment, the DJGPP compiler and
associated tools can be downloaded from your nearest SimTel mirror site,
in the <tt>/pub/simtelnet/gnu/djgpp/</tt> directory, or you can use the zip picker
on <a href="http://www.delorie.com/djgpp/">http://www.delorie.com/djgpp/</a>. See the djgpp <tt>readme.1st</tt> file for
informations about how to install DJGPP.
<p>
If you choose MinGW, download the MinGW compiler and associated tools from
'<a href="http://www.mingw.org">http://www.mingw.org</a>' or '<a href="http://sourceforge.net/projects/mingw/">http://sourceforge.net/projects/mingw/</a>'. You
can download the complete distribution instead of the individual packages
if you don't want to install each package manually.
<p>
If you choose Cygwin, get <tt>setup.exe</tt> from '<a href="http://sources.redhat.com/cygwin/">http://sources.redhat.com/cygwin/</a>'.
Start the Cygwin setup program and download the required packages. Then
install the packages (run <tt>setup.exe</tt> once more). When setup asks you which
line endings you want, select unix-style instead of DOS.
<p>
Remember that the chosen set of tools have to be on your PATH during the
building of Allegro.
<p><br>
<h1><a name="Installing Allegro">Installing Allegro</a></h1>
<p>
This is a source-only distribution, so you will have to compile Allegro
before you can use it. To do this you should:
<p>
<br><center><h2><a name="Setting up the environment">Setting up the environment</a></h2></center><p>
<p>
Set up your environment so that MSVC can be used from the commandline.
You probably have a <tt>vcvars32.bat</tt> file that will do this for you
(the exact location of this file depends on your MSVC version and folder
where you have MSVC installed, e.g. for MSVC 6 it is usually
<tt>C:\Program Files\Microsoft Visual Studio\VC98\Bin</tt>, for MSVC 8
<tt>C:\Program Files\Microsoft Visual Studio 8\VC\Bin</tt> etc.).
You will have to run this file every time you open a DOS box or configure
the environment variables in Control Panel/System/Environment (autoexec.bat
for Win 9x/ME).
<p>
<br><center><h2><a name="Configuring Allegro">Configuring Allegro</a></h2></center><p>
<p>
To configure Allegro for your compiler please run in the command prompt:
<blockquote class="text"><pre>
fix.bat msvc6 - for MSVC 6 and older
fix.bat msvc7 - for MSVC 7 (.NET) and 7.1 (.NET 2003)
fix.bat msvc8 - for MSVC 8 (.NET 2005)
fix.bat icl - for Intel compiler
</pre></blockquote>
<p>
<br><center><h2><a name="Long paths handling">Long paths handling</a></h2></center><p>
<p>
Normally you can skip this section, unless you have some problem with
building Allegro.
<p>
The make process needs all the path variables to be in DOS 8.3 format, and
since MSVC is usually installed in something like
"<tt>C:\Program Files\Microsoft\Microsoft Visual Studio .NET 2003</tt>",
this may cause a problem. This should normally be handled by
<tt>fix.bat</tt>, so you probably don't need to worry about this. However you
can run "<tt>echo %MSVCDir%</tt>" (<tt>%VCINSTALLDIR%</tt> under MSVC 8)
from the command line to see if it contain spaces.
If you are using MSVC 6 or lower the output should already be in DOS 8.3
format so you should not have any troubles. With higher versions of MSVC
it will probably show the long path with spaces. Normally, <tt>fix.bat</tt>
will try to convert it to DOS 8.3 format automatically. You can disable this
conversion by passing the <tt>--nomsvcpaths</tt> parameter to <tt>fix.bat</tt>
(note that this conversion is automatically disabled when using "<tt>msvc6</tt>").
<p>
If you want to handle this yourself manually, you will have to edit
<tt>vcvars32.bat</tt> so that it sets the 8.3 paths, not the long versions.
To get 8.3 path names, you can use the command prompt (<tt>cmd.exe</tt>).
Type in "<tt>dir /x</tt>" to get a listing of the 8.3 file and directory
names alongside of their full names. You can also use the DOS prompt
(<tt>command.exe</tt>) and "<tt>dir</tt>", but this will only show
you the 8.3 names.
<p>
<br><center><h2><a name="Building from SVN">Building from SVN</a></h2></center><p>
<p>
If you are compiling from SVN, you need to run "<tt>make depend</tt>" and
"<tt>misc/fixdll.sh</tt>" before continuing as explained below, or the
library will fail to build because of missing <tt>.inc</tt> files.
<p>
<br><center><h2><a name="Building Allegro">Building Allegro</a></h2></center><p>
<p>
If you are using Cygwin as the GNU environment, start the Cygwin bash shell
from the command prompt (if you used the command prompt to run <tt>vcvars32.bat</tt>
then you must start Cygwin in the same command-prompt window you used to
run <tt>vcvars32.bat</tt> unless you configured the environment variables in Control
Panel/System/Environment). This is usually done via "<tt>C:\cygwin\cygwin.bat</tt>".
<p>
Go to the directory where you have installed Allegro by using '<tt>cd</tt>'.
<p>
Type "<tt>make</tt>". Then go do something interesting while everything compiles.
When it finishes compiling, type "<tt>make install</tt>" to set the library up
ready for use.
<p>
If you are using MSVC 8 and want to embed manifest files to executables
(by default manifests are just embedded in the DLL), run "<tt>misc\embedman.bat all</tt>"
from the command prompt (Cygwin users run "<tt>misc/embedman.bat all</tt>").
<p>
If you also want to install a debugging version of the library (highly
recommended), now type "<tt>make install DEBUGMODE=1</tt>". Case is important, so
it must be <tt>DEBUGMODE</tt>, not <tt>debugmode</tt>!
<p>
If you also want to install a profiling version of the library, now type
"<tt>make install PROFILEMODE=1</tt>".
<p>
If you want statically linked libraries as well as the default DLLs, pass
additionally "<tt>STATICLINK=1</tt>" to the make commands above.
<p>
If your copy of Allegro doesn't include the <tt>makefile.dep</tt> dependency files
(unlikely, unless you have run "<tt>make veryclean</tt>" at some point or are
building the SVN version), you can regenerate them by running
"<tt>make depend</tt>".
<p>
If your copy of Allegro doesn't include the linker .def file (unlikely,
unless you have run "<tt>make veryclean</tt>" at some point or are building the SVN
version), you can regenerate it by running "<tt>misc\fixdll.bat</tt>". Cygwin users
can run "<tt>misc/fixdll.sh</tt>" instead.
<p>
Once the build is finished you can recover some disk space by running
"<tt>make compress</tt>", which uses the UPX program to compress the executable
files and the optimized dll. Before running "<tt>make compress</tt>", you must set
the environment variable UPX_BIN to point to <tt>upx.exe</tt>. You will have to
do run "<tt>make compress</tt>" before "<tt>make install</tt>" if you want the compressed
dll to be copied to the windows directory. To recover even more disk
space, you can run "<tt>make clean</tt>" to get rid of all the temporary files and
HTML format documentation.
<p><br>
<h1><a name="Using Allegro">Using Allegro</a></h1>
<p>
All the Allegro functions, variables, and data structures are defined in
<tt>allegro.h</tt>. You should include this in your programs, and link with one of
the libraries:
<blockquote class="text"><pre>
alleg.lib - optimised DLL import library
alld.lib - debugging DLL import library
allp.lib - profiling DLL import library
alleg_s.lib - statically linked optimised library
alld_s.lib - statically linked debugging library
allp_s.lib - statically linked profiling library
alleg_s_crt.lib - statically linked optimised library
with the static C runtime
</pre></blockquote>
When using a statically linked library, you must define the preprocessor
symbol <tt>ALLEGRO_STATICLINK</tt> 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 <tt>LIBRARIES</tt> in <tt>makefile.vc</tt>). You have also
to make sure that your program is linked against the right C run-time
library, ie. the multi-threaded DLL version of MSVCRT (or the debug
version if you are using the debug library). You can change this option
at Project - Settings - C/C++ - Category: Code Generation - Use run-time
library.
<p>
Don't forget that you need to use the <code>END_OF_MAIN()</code> macro right after
your <code>main()</code> function!
<p>
If you use one of the DLL versions, you will obviously need to distribute
the appropriate DLL along with your program: these can be found in the
<tt>allegro/lib/msvc/</tt> directory.
<p>
The alleg_s_crt.lib is most useful with Visual C++ 8.0. The new C runtime that it
uses can be difficult to distribute. By using alleg_s_crt.lib along with the
multi-threaded runtime (/MT) you can avoid the problem. For more information on
deploying with VC++ 8.0, see <a href="http://wiki.allegro.cc/VisualCExpress2005#Deployment">http://wiki.allegro.cc/VisualCExpress2005#Deployment</a>.
</body>
</html>
