[openvrml-develop] How to compile OpenVRML under Windows Vista or XP.

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

How to compile OpenVRML under Windows Vista or XP.
Copyright (C) Zack Smith 2008
This document is covered by the GNU Free Documentation License.

Updated June 28th 2008.

1. Obtain OpenVRML. You can either download the latest tarball from here:
	http://openvrml.org/download
   and then extract the files, or perhaps it would be better to obtain 
   the latest code using Subversion as follows:
	svn co http://svn.openvrml.org/svnroot/openvrml/trunk openvrml

2. Download & install the precompiled Boost C++. 
	http://www.boost-consulting.com/products/free
   The installer will itself download the boost DLLs.
   Install everything that's multithreaded.

3. Download Visual C++ Express. 
	http://www.microsoft.com/express/vc/
   Installing it will take some time.
   You should probably register as well.
	-> They also allow you to download a handy installation ISO.

4. Start Visual Studio and open the OpenVRML solution file, which is in:
	openvrml/ide-projects/Windows/VisualC9_0/OpenVRML/

== Nota bene:
== OpenVRML relies on several libraries, each of which
== must be downloaded, and each of whose include and library
== directories must be added to Visual C++ path lists.
== The following step explains how to add to the path lists.

5. We now need to add Boost header and library directories to 
   the compiler's path lists.
   - Select the Tools->Options pulldown menu.
   - In Projects and Solutions, select VC++ Directories,
     then Include Files.
   - Click on the folder icon and add the path for the boost directory
     with the version number. It should be similar to this:
       C:\Program Files\boost\boost_1_35_0
   - Now select Library Files.
   - Click on the folder icon to add the path. It looks like this:
       C:\Program Files\boost\boost_1_35_0\lib

6. Download and install Freetype2 2.3.6 from here:
	http://sourceforge.net/project/showfiles.php?group_id=3157
   There's a solution file in the builds/win32/visualc subdirectory
   that you can create the .lib file with.
   Once that's done, move it to your morelibs directory.

7. Add the include and library directories for Freetype.
   There are two include directories to add for Freetype,
   namely "include" and "include\freetype". The library
   directory is "objs".

8. You will need to build libpng. This requires that zlib be in the
   same directory as the libpng directory.
   Download the source code for BOTH Libpng and zlib.
   On your desktop, create a directory called zlib.
   Extract Libpng to your desktop as well, producing a directory like lpng1229.
   Extract zlib source code (e.g. tar zxfv zlib-1.2.3.tar.gz) and
   rename that directory to just "zlib". 
   Open the project file in lpng1229/projects/visualc71 (or newer if exists).
   Right-click on the solution (at top) in the list of projects.
   Click on Configuation Manager.
   Set the Configuation to LIB Debug for all three.

9. Add the include directory for libpng to the VC++ include path list.
   This is just the lpng directory itself.
   Add the libpng's library directory to VC++'s library path list
   since we will use this later when compiling OpenVRML.
   It is this:
	lpng1229/projects/visualc71/Win32_LIB_Debug/libpng13d.lib
   Build libpng.

10. Download and install Libiconv from here:
	http://www.zlatkovic.com/pub/libxml/
   Add its library directory to the libraries path list and
   its include directory to the include files path list.

11. Download and install Libxml from here:
	http://www.zlatkovic.com/pub/libxml/
   Add its library directory to the libraries path list and
   its include directory to the include files path list.

12. You will need to install SDL. 
   You have two options: To download precompiled DLLs
   plus include files, or to build it yourself.
   For precompiled go here:
	http://www.libsdl.org/download-1.2.php
   (I found that the precompiled SDL 1.2.13 works.)
   The included DLLs that will have to be installed in
   the binary directory of OpenVRML or in c:\windows\system32.
   Alternatively I describe how to build it yourself
   in the "Building SDL" section below.

13. Add SDL's header and library directories to the VC++'s path lists.

14. Install DirectX SDK. SDL requires DirectX however
   the SDK version is more complete and may be useful.
   The size is about 450 megs.
	http://msdn.microsoft.com/en-us/directx/default.aspx

15. You will need zlib (separate from libpng).
   You have two options: precompiled or build it yourself.
   Note that for libpng you already downloaded the source code.

   To get the precompiled zlib go here:
	http://www.zlatkovic.com/pub/libxml/

   If you want to try to compile those sources, it's easy. 
   The VC++ project file is in zlib-1.2.3/projects/visualc6. 
   I suggest going into Configuration Manager (right click on 
   Solution 'zlib') and setting the Configuation to LIB Debug 
   for all three targets. The library file will be here: 
	zlib-1.2.3/projects/visualc6/Win32_LIB_Debug/zlibd.lib

   Add the zlib library directory to the libraries path list
	->  zlib-1.2.3/projects/visualc6/Win32_LIB_Debug
   its include files directory to the include files path list.
	->  zlib-1.2.3/

16. Now we need JSAPI (which Mozilla Foundation has renamed SpiderMonkey).
   It is easiest to download the precompiled code from Mozilla, 
   in the form of XULRunner:
	http://ftp.mozilla.org/pub/mozilla.org/xulrunner/nightly/latest-trunk/
   Get the SDK version and extract it.
   Add its library directory to the libraries path list
	-> xulrunner-sdk/lib
   and its include directory to the include files path list.
	-> xulrunner-sdk/include/js
   Note the "js".

17. We need to add a command-line argument for a file to view, i.e.
   to test the executable.
   Right click on the sdl-viewer project, click Properties, Debugging,
   Command Arguments. Add something like:
	file:///c:/users/YOURNAME/desktop/openvrml/models/snoman.wrl

	-> Notice that 3 forward slashes are required
	   and that are the software doesn't seem to understand two,
	   nor does it understand the C| notation.

18. Build the solution. The only executable with be sdl-viewer.exe.

19. Set the environment variable for OPENVRML_DATA to the
    full path of the openvrml/data directory, something like this under Vista:
	c:/users/YOURNAME/desktop/openvrml/data
    or under XP:
	c:/docume~1/YOURNAME/desktop/openvrml/data

20. Set the sdl-viewer as the default application to debug.
   You do this by right-clicking on the sdl-viewer project
   and clicking on "Set as Startup Project".

21. If you wish to run VRML/X3D that has Javascript, you will need to
   do two things:
   First, set the OPENVRML_SCRIPT_PATH environment variable.
   Second, copy JSAPI's js2350.dll and nspr4.dll to the OpenVRML
   binary directory.

22. Press F5 to run the program in debug mode.

-----------------

Troubleshooting:

* If you get an error during the loading of DLLs, and
  the error code is hexadecimal, such as:
	"The application failed to initialize property (0xE06D7363)"
  then this may indicate that your OPENVRML_DATADIR environment variable
  is unset or incorrectly set. In an ideal world, this problem would result 
  in a MessageBox() call, but presently it doesn't. 

* To do a proper "clean solution", you may not want to rely on
  VC++. It's not as deterministic as 'make' under Unix. Use Cygwin 
  carefully thus:
	rm `find . -name "*.obj"`
	rm `find . -name "*.lib"`
	rm `find . -name "*.dll"`
	rm `find . -name "*.exe"`
  -> Don't forget the "-name" part! Forgetting it will remove everything.

* If there is a problem with manifest files not being produced, 
  note that VC++ normally produces them itself. To repair a manifest file
  problem, you may need to do a proper clean (above). It may help if
  you have /NODEFAULTLIB:MSVCRT.LIB in your linker command-line
  arguments for all projects.

-----------------

Building SDL (optional):

If you desire to compile SDL yourself, here are the instructions:

1. Use Subversion (in Cygwin) to download the latest sources.
	svn checkout http://svn.libsdl.org/branches/SDL-1.2

2. Download the latest DirectX SDK. It's about 440 megs.
	http://msdn.microsoft.com/en-us/directx/default.aspx
   Install it.

	-> Do NOT get the smaller end-user runtime.

3. Unzip the VisualC.zip file that is inside SDL-1.2/.

4. Open the Visual C++ solution file in the VisualC directory.

5. Using the pulldown Tools->Options, edit in Project/Solutions
   the VC++ Directories, Include files: add a link to the
   DirectX include directory, which will perhaps be here:
	c:\progra~1\microsoft directx*\lib\x86

6. Go into the project properties for SDL, and select
   Configuration Properties, General, Project Defaults,
   and set set Configuration Type to STATIC LIBRARY.

7. You will need to add tell LINK to include some libraries 
   in order to create the SDL DLLs. Right click on the
   SDL project, then Properties, Configuration Properties, Linker,
   Input and locate Addition Dependencies.  Now add: 
	winmm.lib dxguid.lib

8. Build.

9. Switch to the OpenVRML solution. Make sure that sdl-viewer
   has linker inputs of 
	SDL.lib SDLmain.lib 

-end-