How to compile OpenVRML under Windows Vista or XP

Original version copyright (C) Zack Smith 2008
This document is covered by the GNU Free Documentation License.

1. Obtain OpenVRML

Get the OpenVRML distribution (either a release tarball or the latest sources from Subversion) as per http://openvrml.org/download.

2. Download Visual C++ Express

If you don't already have the Microsoft compiler, you can use the free version, Visual C++ Express.

3. Install the precompiled Boost C++ libraries

Use BoostPro Computing's freely available installer for the Windows build of Boost.

Install at least the "Multithread" and "Multithread Debug" variants of the libraries for the most recent version of the Microsoft Visual C++ compiler (9.0, as of this writing).

The installers for versions 1.37.0 and 1.38.0 appear to have a glitch such that checking the boxes to install the variants globally for all libraries may not actually result in that selection propagating to the individual libraries. Make sure that you expand the tree of available variants to install and specifically check the "Multithread" and "Multithread Debug" variants.

4. Open the solution file

The solution file for Visual C++ 9.0 can be found at the path

ide-projects\Windows\VisualC9_0\OpenVRML\OpenVRML.sln

in the OpenVRML distribution.

5. Add the Boost header and library directories to the compiler's path lists

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.

1. Select the Tools->Options pulldown menu.
2. In Projects and Solutions, select VC++ Directories, then Include Files.
3. 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_38_0
   

4. Now select Library Files.
5. Click on the folder icon to add the path. It looks like this:

   C:\Program Files\boost\boost_1_38_0\lib
   

6. Build FreeType

1. Download the zip file distribution of FreeType from the FreeType SourceForge project's file releases.
2. Open the solution file in Visual C++. It can be found in builds\win32\vc2008 (for the Visual Studio 2008 compiler) in the FreeType distribution.
3. Build the "LIB Release" and "LIB Debug" configurations of the freetype project.
4. The FreeType solution outputs both libraries to the same directory, objs\win32\vc2008. (Again, the particular path is likely to vary depending on the compiler version in use.) Add this directory to Visual Studio's list of library directories. This will be of the form:

   C:\Users\Joe\freetype-2.3.9\objs\win32\vc2008
   

5. Add the FreeType distribution's include subdirectory to Visual Studio's list of include directories. This will be of the form:

   C:\Users\Joe\freetype-2.3.9\include
   

7. Build libpng

1. Download the zip file distributions of both the latest libpng release as well as zlib from the libpng SourceForge project's file releases.
2. After unzipping the libpng distribution, unzip the contents of the zlib distribution to a directory named "zlib" at the same level as the libpng distribution's top-level directory. For example, if your libpng distribution lives at C:\Users\Joe\lpng1235, your zlib distribution should be in C:\Users\Joe\zlib. Note that while the libpng zip file contains a top-level directory, the zlib one does not (as of zlib release 1.2.3).
3. Open the libpng solution file in Visual C++. It can be found at projects\visualc71\libpng.sln in the libpng distribution.
4. Build both the "LIB Debug" and "LIB Release" configurations of the libpng project. zlib will get built automatically as a dependency.
5. Add libpng's output directories to Visual C++'s list of library directories. These will be of the form:

   C:\Users\Joe\lpng1235\projects\visualc71\Win32_LIB_Debug
   C:\Users\Joe\lpng1235\projects\visualc71\Win32_LIB_Release
   

6. Add zlib's and libpng's source directories to Visual C++'s list of include directories. These will be of the form:

   C:\Users\Joe\zlib
   C:\Users\Joe\lpng1235
   

8. Get SpiderMonkey (the Mozilla JavaScript runtime)

It is easiest to download the precompiled code from Mozilla in the form of XULRunner: ftp://ftp.mozilla.org/pub/xulrunner/releases/

Get the SDK version and extract it. Add its library directory to Visual C++'s list of library directories. This will be of the form:

C:\Users\Joe\xulrunner-sdk\lib

Add the SpiderMonkey? include directory to Visual C++'s list of include directories. This will be of the form:

C:\Users\Joe\xulrunner-sdk\include\js

9. Install SDL

You have two options: download precompiled DLLs plus include files, or build it yourself. For precompiled go to http://www.libsdl.org/download-1.2.php The included DLLs that will have to be installed in the binary directory of OpenVRML.

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

11. Run sdl-viewer in the debugger

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

12. Build the solution

The only executable with be sdl-viewer.exe.

13. Set environment variables

Set the environment variable 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

14. 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".

15. Running scripts

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.

16. 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)
  

  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.