HOW_TO_COMPILE_WIN32.txt

*******************************************************************************
HOW TO COMPILE DAPHNE UNDER WIN32
*******************************************************************************

The following document explains how to compile Daphne under Windows.
Start by reading "The Short Version" to get an general idea of what
you need to do. From there proceed to read the rest of the document
for more specific details that may help you solve or avoid potential
problems.


Contents:

	A. The Short Version
	B. Tested development enviroments
	C. Compiler Quirks
	D. Library Quirks
	E. Libraries to Get
	F. Organizing your libraries
	G. Opening and compiling the Daphne project
	H. Troubleshooting Compiler and Linking Errors
	I. Installing your generated daphne file


*******************************************************************************
A. The Short Version 
*******************************************************************************

	1. Check part E for what libraries you need to get. If you need
	to generate your own libraries then go ahead and do so.
	2. On the very same folder where you found this text file double click 
	on the solution file "daphne_vs2003.sln".
	3. Select the type of build you wish to create (debug or release).
	4. Take a minute to add the necessary paths to your project's directory 
	lists for "include" and "library" settings.
	5. Check daphne's C++ pre-processor settings and if needed modify
	it to meet your needs (eg, add/remove ZLIB_WINAPI or BUILD_SINGE).
	6. Check daphne's Linker Input Settings so all libraries
	are correctly spelled.
	7. Build your solution.	


*******************************************************************************
B. Tested Development Environments
*******************************************************************************


Daphne has been tested to compile under the following Microsoft products:
 
	Visual C++ 6
	Visual C++ .NET 2003 (a.k.a. Visual C++ 7.1)
	Visual C++ 2005 (a.k.a. Visual C++ 8.0)
	Visual C++ 2008 (a.k.a. Visual C++ 9.0)
	Visual C++ 2010 (a.k.a. Visual C++ 10.0)
 
 
*******************************************************************************
C. Compiler Quirks:
*******************************************************************************
 
If you are using Visual C++ 6:
 
	- Make sure you have MASM installed.  VS7.1 automatically comes with this
	installed.  If you are using VS6, you may need to upgrade to
	service pack 5 and then install the Processor Pack in order to get MASM.
	There are other ways to get it installed, but this way requires the 
	shortest explanation :).

	- Get SDL-devel-1.x.xx-VC6.zip.


If you are using Visual C++ 2003:
 
	- If compiling your own libogg and libvorbis libraries then get 
	version 1.2.0 for both. That's the last version that supported this 
	compiler. You can find it by browsing older release versions
	at the xiph.org address below:
 
	http://downloads.xiph.org/releases/ogg/
 

If you are using Visual C++ 2005:

	- Make sure you apply Service Pack 1. Some newer libraries (eg, libSDL) 
	may generate errors if you don't.


If you are using Visual Studio 2010 Express Edition:
 
	- Be aware this edition may not compile libogg nor libvorbis
	right out of the box. Visual Studio 2008 Express Edition does
	not have this problem.


The following may apply to any Visual Studio version:
 
	- It is very likely you will have to update your project's linker 
	properties so that it correctly spells the right filenames for the 
	libraries you want to compile against. For example depending on what you 
	use you	may have to rename vorbis.lib to libvorbis.lib or 
	zlib.lib to zlibwapi.lib. This is usually done at the property pages for 
	your Daphne project:
		
		+ For VS2003: At the Solution Explorer right click on "daphne"
			and select "Properties". From there choose "Linker"-->"Input"
			
		+ For VS2005/2008/2010:
 
			(Alt+F7)-->Configuration Properties-->Linker-->Input
			Check the field "Additional Dependencies".
			
	- Visual Studio VC++ 2005 and newer need an additional package called
	  "VC Redistributable Package" (eg, vcredist_x86.exe) installed for 
	  any compiled program to work outside the developing environment. 
	  
	  Some computers have this installed by other programs or Windows updates.
	  This will solve error messages like "the application configuration is 
	  incorrect". Keep this in mind when installing your custom created 
	  Daphne on a target machine.
	
 
*******************************************************************************
D. Library Quirks (applies to all compilers):
*******************************************************************************
 
 
 
	+++++++++ SDL Libraries +++++++++
 
	- When dealing with SDL libraries make sure
	to choose the correct one for the version of Visual C you
	are using. Usually there is a separate zip file with the suffix
	"VC6", "VC8" or "VC". 
 
	+++++++++ OGG and VORBIS +++++++++
	
	- When working with libogg and libvorbis you will have to
	compile the libraries on  your own. Take a look inside
	the directory structure libogg and libvorbis. Be sure to select
	the right folder pointing the project or solution file
	corresponding to the compiler version you are using.
	These folders are usually named "vs2003", "vs2005" or "vs2008".
	Failure to match these with the correct compiler may result
	in compiler errors.
	
	- libvorbis uses libogg, so compile libogg first and later add the
	library path to your compiler "VC++ directories" configuration
	for libvorbis.
 
	- libvorbis has four main projects, but the ones you need
	are libvorbis and libvorbisfile.
 
 
	+++++++++ ZLIB +++++++++
	
	- Save some time by downloading pre-compiled zlib libraries.
	You can find them at http://www.winimage.com/zLibDll/index.html
	Be aware you will still need to get the header files as well.
	- Latest ZLIB versions require the word "ZLIB_WINAPI"
	  declared in the project's pre-processor project settings.
	- Library naming conventions changed too.
	  Use "zlibwapi.lib" instead of "zlib.lib"
 
 
 
*******************************************************************************
E. Libraries to Get:
*******************************************************************************
 
 
	To compile Daphne you need to have the following libraries:
		
		+ libSDL	-	http://www.libsdl.org
		+ libGLEW	-	http://glew.sourceforge.net
		+ libOgg	-	http://xiph.org/downloads/
		+ libVorbis 	-	http://xiph.org/downloads/
		+ zlib		- 	http://www.zlib.net/
	
 
	+++++++++ Optional: Compiling SINGE with Daphne +++++++++
 
	To compile the SINGE add-on for Daphne you also need to add:
 
		+ libSDL_image	-	http://www.libsdl.org/projects/SDL_image/		
		+ libSDL_ttf	-	http://www.libsdl.org/projects/SDL_ttf/		
 
 
	SINGE add-on is built by default. If you wish to disable it then
	remove the words "BUILD_SINGE" on daphne's pre-processor project settings.
 
 
 
 
*******************************************************************************
F. Organizing your libraries:
*******************************************************************************
 
 
	It's recommended you create a folder where to extract
	all the downloaded librares. You will need to add new directories to the
	Include category to point to the include files for the packages you
	just downloaded.  For example, you might add an entries like these:
	
		c:\mylibs\sdl-1.2\include		
		c:\mylibs\libogg-1.2.0\include
		c:\mylibs\zlib-1.14
		c:\mylibs\glew\include
		
		
	To access the Directories tab of your compiler:
	
		+ VS6, go to Tools->Options then click on 
                Projects->Directories tab.
		+ VS7.1 go to Tools->Options->Projects then click on the 
		  Directories tab.
		+ VS2005/2008 go to:
			Tools->Options->Projects and Solutions->VC++ Directories.
		
 
	You will also need to add entries to the "Library" category (as opposed 
	to the "Include" category you just added entries for). 
	Your library entries might look like this:
 
	    c:\mylibs\sdl-1.2\lib
		c:\mylibs\sdl_mixer-1.2.0\lib
		C:\mylibs\libogg-1.2.0\win32\VS2005\Win32\Release
		c:\mylibs\zlib-1.14\dll32
		c:\mylibs\glew\lib
		
		
	
	- How to set Global VC++ Directories in Visual Studio 2010:	
	
	VS2010 does things a little bit differently. Use the following
	instructions to set a group of directories globally to all
	projects inside a solution:
	
	1. Select Tools->Settings->Expert Settings.
	2. Open up the daphne_vs2010.sln solution file.
	3. Select View->Property Manager and expand the node for 'daphne'.
	4. Expand the node for either "Debug" or "Release".
	5. Right click on "Microsoft.Corp.<Platform>.user" 
	   and select "Properties".	
	6. At the "Daphne Property Pages" window, select
		Configuration Properties->VC++ Directories
	
	7. Add the additional directories for include and library.
	   Hit OK when you are done.
	8. Save your project and exit Visual Studio altogether.
	9. Relaunch Visual studio and open your daphne solution.
		Your directories changes should now apply globally
		to all the projects in the solution.
 
 
 
 
*******************************************************************************
G. Opening and Compiling the Daphne project:
*******************************************************************************
 
 
	+ Go to File->Open Solution and open the daphne_vs2003.sln (or double click
	on the solution in the src folder).
	
	+ If using a newer Visual C++ compiler versions then you will see the 
	Conversion Wizard pop up. Let it convert your project to your Visual C++ 
	version. Take a moment to read "Troubleshooting Compiler/Linker Errors" and 
	fix the problem with ".\daphne.rc(10) fatal error RC1015".
		
	+ Select the kind of build you want (Debug or Release). 	
	
	+ Make sure your C++ pre-processor settings have all the right values!
	  Make sure your Linker "Input" settings have all the libraries
	  correctly spelled!
	
	+ On the menu toolbar select "Build->Build Solution".
	
	
At this point you should be ready to compile. Good Luck!
 
 
	
*******************************************************************************
H. Troubleshooting Compiler and Linking Errors:
*******************************************************************************
 
 
+ .\daphne.rc(10) : fatal error RC1015: cannot open include file 'afxres.h'
 
	Happens when converting the VS2003 project solution to a newer
	Visual Studio version. Open up daphne.rc and change the
	following line:
 
	#include "afxres.h"
 
 
	to this:
 
	#include "windows.h"
 
+ LINK : fatal error LNK????: cannot open input file '*******.lib'
 
	Visual Studio can't find the specified library.
	Probably the file is misspelled in the linker properties.
	Usually happens with zlib, libogg or libvorbis libraries.
 
	Check that the library files declared in the project linker 
        "INPUT" properties are correctly spelled and that your library 
        directories are pointing to the right places.
	
+ error PRJ0019: A tool returned an error code from 
  "Performing Custom Build Step"
 
	Happens when compiling SINGE. Fix it by moving your "src" folder
	to a path that does not use spaces in its name.
	
+ error LNK2001: unresolved external symbol __imp___CrtDbgReportW        

	Happens when trying to generate a multi-threaded release build
	on a debug build.

	Fix it by going to daphne's Property Pages (right click
	on the project name in the Solution Explorer pane then choose
	"Properties"). Once you are there select 

		Configuration Properties->C/C++->Code Generation

	Change the value in the "Runtime Library" option
	to "Multi-threaded Debug DLL".

+ error	LNK2005: <some function> already defined in LIBCMTD.lib
 
	You'll get this error when using VS2005 without
	the Service Pack 1 installed against the libraries in the SDL package 
	"SDL-devel-1.?.??-VC8.zip". Fix it by updating your compiler
	to SP1 or by using "SDL-devel-1.?.??-VC6.zip" instead.
	
+ vorbisfile.h(59): error C3861: '_fseeki64': identifier not found, even with 
  argument-dependent lookup
  
	Happens when tryping to compile a newer libvorbis library 
	with the older Visual Studio 2003. Quick fix is to
	use an older libvorbis version (or a newer VS compiler).

	Long fix: Open up vorbisfile.h and go to line 59. Change the
	following:

		return _fseeki64(f,off,whence);

	to this:

		return fseek(f,off,whence);
	

+ LINK: ... unresolved external symbol _crc32 ....
 
	Happens when trying to compile with the latest
	zlib versions. Add the word "ZLIB_WINAPI" (without the quotes)
	to the preprocessor compile settings for the "daphne" project.
 


+ "This application has failed to start because <SOME.DLL> was not found.
	Re-installing the application may fix this problem"

	Project "daphne_test" expects to find SDL.dll and inpout32.dll 
	after it's done compiling. When it doesn't it complains with this 
	message, but the project will finish successfully. You can happily 
	hit OK and ignore this message.

	...Or you can copy SDL.dll and inpout32.dll to the place
	where Visual Studio dumps all the generated programs (one directory
	above the "src" folder).
 
 
*******************************************************************************
I. Installing your generated daphne file
*******************************************************************************
	
You got through all the hurdles and got daphne to compile. Congrats.
Now what next? At this point you might be tempted to simply copy
the generated daphne.exe to the folder where your official daphne release
is located.
 
While this may work, the official daphne distribution may have
DLL files that are incompatible with your custom created daphne.
If you get DLL related errors then you need to copy the appropriate
DLL files as well. Those binary files can be found at each of the
library directories you setup previously. In order to save you some time
here is a list of what you need to look for. Copy these files in the same 
location where you place your generated daphne.exe file:

 
	+ vldp2.dll and singe.dll from the same folder you
	  got daphne.exe.
 
	+ SDL.dll from the SDL-1.x.xx folder
 
	+ glew32.dll from the libglew folder
 
	+ zlib.dll (if using version 1.14) or
	  zlibwapi.dll (if using a newer zlib version like 1.2.5)
 
	+ SDL_image.dll, zlib1.dll, libpng12-0.dll from
	  the SDL_image folder.	
 
	+ SDL_ttf.dll and libfreetype-6.dll from the SDL_ttf folder.
 
	+ libogg.dll from somewhere inside the libogg folder.
 
	+ libvorbis.dll and libvorbisfile.dll from within the libvorbis folder.
	
	+ inpout32.dll is found in the official daphne build.
	  If you don't see it then run Daphne Loader and
	  update to the latest version. 

	+ msvcp71.dll and msvcr71.dll if using VS2003.
	
	+ For VS2005 and newer you need to install the Visual C++
	Redistibutable package (vcredist_x86.exe) on the target machine. 
	Simply copying the DLLs over won't work.

 
*******************************************************************************
 
"The magic of myth and legend has come true in our time. One types the correct
incantation on a keyboard, and a display screen comes to life, showing things
that never were nor could be."
 
	- Frederick Brooks. "The Mythical Man-Month".
 
*******************************************************************************