When VR Juggler was first ported to the Win32 environment, a Microsoft Visual C++ project file was used for compiling the library. Development on the GNU Autoconf-based build system on UNIX platforms had been going strong for a long time prior to this, and it was quickly realized that having two separate methods for compiling would complicate matters. The build system used for compiling VR Juggler is now the same on UNIX and Win32 platforms. Only the Autoconf-based system is supported which provides the same build environment on all platforms.
Since the UNIX and Win32 environments have many striking differences, special information must be provided for using the Juggler build system on Windows-based platforms. This document provides all the information necessary for getting set up in a Win32 environment prior to compiling and installing Juggler for developmental use. This is intended primarily for developers who wish to work with the Juggler source and (hopefully) submit work to the Juggler team. Users who are doing application development on a Win32 platform may want to read it too so that they may get a better understanding of what is available as part of the Win32 support.
Developers should refer to the Win32 section of the download page for the list of packages that must be installed. The juggler-tools package is especially important. It contains exactly the utilities used for compiling Juggler (aside from Visual C++ of course) including some modified versions of programs. Of note, the version of make included is what comes with the Bamboo Win32 tools. It is a modified version of GNU make that will run in a DOS shell and can handle DOS-style paths. Also, makedepend has been modified to output UNIX-safe paths and to know about the INCLUDE environment variable used by Visual C++.
In addition to what is listed on the download page, the following packages are needed for Win32 development of Juggler (but not for application development):
Cygwin 1.1.8 or newer. With the newer versions of Cygwin, the tools work better in the Win32 environment, and many pre-compiled packages are available including CVS, Perl, Autoconf, and Automake. It is strongly recommended that the Cygwin versions of all these utilities be used.
GNU Autoconf version 2.13 and GNU Automake version 1.4. Versions beyond these are not currently supported on any platform. This is needed to compile a new configure script after modifying configure.in and to update vjDefines.h.in when necessary. Note that these tools can only be run from a BASH shell (included with the Cygwin package). Autoconf and Automake can be compiled and installed on a Win32 platform without modification using the Cygwin tools.
There are several environment variables that need to be set properly when compiling and installing Juggler and when running Juggler applications. These variables apply to all users, both those who are compiling and running applications as well as those who are compiling VR Juggler itself.
All users must have the juggler-tools directory in their path. If the Cygwin utilities are installed, it is especially important that juggler-tools be listed before the Cygwin bin directory so that the supported utilities are found first. Unfortunately, when running a BASH shell, the Cygwin path is always first, but in the BASH environment, this is acceptable. The ordering is far more important for DOS shells. Besides juggler-tools, the directory containing the Visual C++ executables must also be in the path. The configure script needs this so that it can find CL.EXE when it is setting up the C and C++ compilers.
This should also be set for all users. It provides paths to the Visual C++ include directories that CL.EXE needs when compiling. On Windows NT, it is set only for the user who installed Visual C++. Be sure to change this to be included in all users' environments. Alternatively, it can be set using the VCVARS32.BAT batch file on a per-shell basis, but users will see much better results if it is set in the general environment. In particular, a BASH shell does not get the environment changes made by the batch file. The batch file also uses “8.3” names which may confuse the Cygwin tools.
This is another Visual C++ environment variable that needs to be set in the same manner as %INCLUDE%. Again, this is initially set only for the user who installed Visual C++ and should be changed so that it is set for all users.
The value for this should be set using the DOS path with /'s as the path separator rather than \'s as would normally be the case with DOS/Win32 paths. For example, if VR Juggler is installed in C:\software\vrjuggler, %VJ_BASE_DIR% would be set to C:/software/vrjuggler. Never use //c/software/vrjuggler or /cygdrive/c/software/vrjuggler. The Visual C++ I/O libraries will not be able to handle these special Cygwin paths.
For more information, refer to the section titled “Environment Varibles” in the Getting Started Guide.
Finally, the actual process of compiling (and installing) VR Juggler can begin. After taking the steps in the preceding sections, this will be an easy task (assuming that the source is stable of course). This section focuses primarily on the process when done within a DOS shell. In a BASH shell, the environment is almost identical to that on a UNIX platform, so there are no special considerations to be made.
The first step, as usual, is to configure the build environment with the configure script. (This assumes that configure and vjDefines.h.in have already been generated.) If running in a DOS shell, configure must be invoked using the sh utility. The following will not work:
> ./configure [options]
Instead, it must be run as:
> sh ./configure [options]
As with the UNIX environment, it can be run from a separate build directory. Refer to Chapter 6 for more information (specifically, the section called “Usage”). Options with paths should use /'s for the path separator rather than \'s. They should also be enclosed in double quotes (“path/to/something”) in case the path includes one or more spaces.
Once configuration has completed, compiling can be done in either a DOS shell or a BASH shell using the version of GNU make in juggler-tools. The Cygwin B20.1 version will not work in a DOS shell. This is when it is especially important to have the juggler-tools directory before the Cygwin directory in the user's path.
Beyond this, everything (aside from the problems listed in the next section) will be the same as in a UNIX environment.
Listed here are things to keep in mind when working in a Win32 environment. It is not as stable as its UNIX counterpart due, for the most part, to reasons beyond the control of this project. Please read this in full before reporting problems with the Win32 build.
In versions of Cygwin prior to 1.1, the UNIX utilities will appear to become blocked or may die with an error saying that they cannot fork. This may have been due to a race condition in the old Cygwin code. Typically, it happens when one or more BASH shells are open while a build is happening in a DOS shell. Closing one or more (sometimes all) of the BASH shells usually fixes the problem. It is strongly recommended that developers update to Cygwin 1.1.8 and to the latest juggler-tools package.
The “developer installation” does not work in any Win32 file system. It relies heavily on symbolic links which, while common on UNIX file systems, have no meaning in a Win32 environment. Because of this, VR Juggler must be fully installed after it has been compiled (refer to Chapter 8 for more information on this process). Once that is done, $VJ_BASE_DIR can be set to point to the installation directory and development can continue in the build tree.
The configure script assumes that the compiler knows how to find the OpenGL libraries and headers. In VR Juggler 1.0, no check is made to verify that the OpenGL libraries are available. This has been corrected in VR Juggler 1.1 and beyond.
Dependencies must be generated differently than on UNIX-based platforms. The Visual C++ compiler does not output the dependencies of a given source file in the same manner as all UNIX C and C++ compilers supported by the Juggler build system. Because of this, makedepend is used. It may not handle all the #ifdef's properly and report non-fatal warnings. These can be ignored typically, especially if it is trying to find some file that is clearly UNIX-specific (e.g., pthread.h). The version of makedepend in juggler-tools has been modified to output UNIX-style (and UNIX-safe) paths, but it is possible that not all situations have been considered. If it is clear that makedepend is not handling a path properly, please report the problem.
A configure script generated in a Win32 environment will not work in a UNIX environment. The “^M problem” causes the shell to fail when trying to run the script. A configure script generated in a UNIX environment will however work in a Win32 environment because sh can handle both UNIX- and DOS-style newlines.
The application makefiles (not the library makefiles) all use the $(VAR_NAME) syntax for referencing variables. This is so that the makefiles will work with nmake. These are intended to be usable with all version of make (or as many as is feasibly possible), so they deviate from the style used in other makefiles to accommodate this particular version of make.