When VR Juggler was first ported to the Win32 environment in late 1997, a Microsoft Visual C++ project file was used for compiling the libraries. Development on the GNU Autoconf-based build system on UNIX platforms began in mid-1998, and it was quickly realized that having two separate methods for compiling would complicate matters. To simplify our work, the build system used for compiling VR Juggler is thus the same on UNIX and Win32 platforms. Only the Autoconf-based system is supported, thus providing the same build environment on all platforms.
Because the UNIX and Win32 environments have many striking differences, special information must be provided for using the VR 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 VR Juggler for developmental use. This is intended primarily for developers who wish to work with the VR Juggler source and (hopefully) submit work to the VR 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 VR Juggler (aside from Visual C++, of course) including some modified versions of programs. Of note, the bundled version of 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.3 or newer. With Cygwin version 1.1 and newer, the tools work better in the Win32 environment than older releases, 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 vrjDefines.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.
Recent releases of Cygwin include both Autoconf 2.13 and 2.5x as well as Automake 1.4 and 1.5. There have been problems observed with the aclocal distributed with Automake 1.5, and as of this writing, the Automake 1.4 version is required to run autogen.sh. This can be accomplished as follows:
% ACLOCAL=/usr/autotool/stable/bin/aclocal ./autogen.sh
The above temporarily assigns a value to the $ACLOCAL environment variable that is then used by autogen.sh.
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. 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 VSVARS32.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 Variables” 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 5, Using the VR Juggler Configure Scripts 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.3 and to the latest juggler-tools package.
The “developer installation” is not fully functional on any Win32 file system. Because of this, VR Juggler must be fully installed after it has been compiled (refer to Chapter 7, Installing VR Juggler for more information on this process). Once that is done, $VJ_BASE_DIR can be set to point to the installation directory and applications can be compiled in that tree.
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 VR 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 report parse errors 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.