@html_text_substitution=readme.txt|readme.txt @external-css=../allegro.css @document_title=Allegro MSVC-specific information @
     ______   ___    ___
    /\  _  \ /\_ \  /\_ \
    \ \ \L\ \\//\ \ \//\ \      __     __   _ __   ___ 
     \ \  __ \ \ \ \  \ \ \   /'__`\ /'_ `\/\`'__\/ __`\
      \ \ \/\ \ \_\ \_ \_\ \_/\  __//\ \L\ \ \ \//\ \L\ \
       \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
	\/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
				       /\____/
				       \_/__/


		 MSVC-specific information.

	 See readme.txt for a more general overview.
@
@heading MSVC notes Status: complete. 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. @heading Required software 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. 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 INCLUDE and LIB environment variables to put the DirectX SDK files in front of the standard MSVC locations. 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 /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 informations about how to install DJGPP. If you choose MinGW, download the MinGW compiler and associated tools from 'http://www.mingw.org' or 'http://sourceforge.net/projects/mingw/'. You can download the complete distribution instead of the individual packages if you don't want to install each package manually. If you choose Cygwin, get setup.exe from 'http://sources.redhat.com/cygwin/'. Start the Cygwin setup program and download the required packages. Then install the packages (run setup.exe once more). When setup asks you which line endings you want, select unix-style instead of DOS. Remember that the chosen set of tools have to be on your PATH during the building of Allegro. @heading 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: Set up your environment so that MSVC can be used from the commandline. You probably have a vcvars32.bat file that will do this for you (usually located in the VC98\BIN folder where you have MSVC installed, for example C:\Program Files\Microsoft Visual Studio\). Under either Windows NT or Windows 2000, you will have to run this file every time you open a DOS box or configure the environment variables in Control Panel/System/Environment. The make process needs all the path variables to be in DOS 8.3 format, and since MSVC is usually installed in something like "C:\Program Files\Microsoft\Microsoft Visual Studio .NET 2003", this will cause a problem. Run "echo %MSVCDir%" (%VCINSTALLDIR% under MSVC 8) from the command line to see if you have this problem. 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. There are two solutions for this. If you have chosen MinGW and have installed it with the w32api package you can solve this problem simply by passing the --msvcpaths parameter to fix.bat (see below). Otherwise if you are using vcvars32.bat, you will have to edit it so that it sets the 8.3 paths, not the long versions. To get 8.3 path names, you can use the command prompt (cmd.exe). Type in "dir /x" to get a listing of the 8.3 file and directory names alongside of their full names. You can also use the DOS prompt (command.exe) and "dir", but this will only show you the 8.3 names. 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 vcvars32.bat then you must start Cygwin in the same command-prompt window you used to run vcvars32.bat unless you configured the environment variables in Control Panel/System/Environment). This is usually done via "C:\cygwin\cygwin.bat". Go to the directory where you have installed Allegro by using 'cd'. If you are using Cygwin, type "./fix.sh msvc --utod". Otherwise (i.e if you are using DJGPP or MinGW), type "fix.bat msvc". If you are using MinGW and want the fix.bat to solve problems with long paths, type "fix.bat msvc --msvcpaths". If you are using MSVC 7 you can specify "msvc7" instead of "msvc" to enable better optimizations. Likewise, you can specify "icl" to use the Intel commandline compiler. If you are using MSVC 8 you should specify "msvc8" otherwise you will get a lot of deprecation warnings. For MSVC 6 and older you can use also "msvc6". If you are compiling from CVS, before continuing you must run both "make depend" and "misc/fixdll.sh" as explained below, or the build will fail asking for some .inc file. Type "make". Then go do something interesting while everything compiles. When it finishes compiling, type "make install" to set the library up ready for use. 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 you want statically linked libraries as well as the default DLLs, pass additionally "STATICLINK=1" to the make commands above. If your copy of Allegro doesn't include the makefile.dep dependency files (unlikely, unless you have run "make veryclean" at some point or are building the CVS version), you can regenerate them by running "make depend". If your copy of Allegro doesn't include the linker .def file (unlikely, unless you have run "make veryclean" at some point or are building the CVS version), you can regenerate it by running "misc\fixdll.bat". Cygwin users can run "misc/fixdll.sh" instead. 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. @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 one of the libraries: 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 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.vc). 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. Don't forget that you need to use the END_OF_MAIN() macro right after your main() function! 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 allegro/lib/msvc/ directory.