Table of Contents
Of particular interest, the VR Juggler project uses the autoconf and automake utilities to stay portable across platforms. This means you will have to “configure” the project before you compile it. To make sense of this documentation, please understand the concepts listed in the section called “Required Reading”. Posting about these subjects to the mailing list will probably be ignored.
Please note that this chapter is maintained separately from the build documentation distributed with the VR Juggler source code. As such, it may have incorrect or out-of-date information. For the most accurate documentation on compiling, please refer to the file juggler/INSTALL.html (or juggler/INSTALL.txt) that comes with the source code.
The following is a brief description of each section within this chapter:
Quick Start: A quick overview of how to build Juggler.
Win32-Specific Considerations: Getting set up for Juggler use and development in a Win32 environment.
Using the Configure Script: How to use configure to set up a build environment before compiling.
Compiling VR Juggler: How to use the Juggler build system in detail.
Installing VR Juggler: How to install Juggler after compiling it.
For the impatient, we begin with this section, a quick start for compiling VR Juggler. Ideally, these steps will just work, but there may be unexpected problems. If you are compiling source code checked out from CVS, the code may be broken and thus not compile at all.
Choose a directory to put the VR Juggler source code. From this point on, we will refer to that directory as SRC_DIR.
Go to SRC_DIR and checkout the source code using CVS. Make sure CVS is set up and pointing to the VR Juggler repository. (Refer to the section called “Getting the Source Code from the CVS Repository” and to the SourceForge instructions for getting VR Juggler using CVS.)
% cd SRC_DIR % cvs checkout juggler
Enter the newly checked-out VR Juggler source directory, a subdirectory of SRC_DIR.
% cd juggler
Auto-generate the configuration scripts configure and template headers (vrjDefines.h.in, for example):
% ./autogen.sh
Configure the build. This probes the system for capabilities, generate Makefiles, etc. It “configures” the source tree for the current system. The configure script will let you change how VR Juggler compiles. For example, you could build VR Juggler without the Performer API using an option passed to the configure script.
You can type configure.pl --help for options.
% ./configure.pl
Build (make) the distribution using GNU make. This compiles, links, and creates the final distribution tree (in the form of symbolic links).
% gmake
Set the environment variable VJ_BASE_DIR based on the output when the build completes. You must also extend your PATH environment variable as directed.This is required by VR Juggler application makefiles.
The directory instlinks is important for developers. What does the word “instlinks” mean? It is a working distribution of the VR Juggler library for developer use. After gmake is done, you will be able to use this directory as though it were a fully installed version of VR Juggler. This directory also determines where VR Juggler files can be found.
The VR Juggler build system (and the build systems for the individual modules) supports the concept of a build directory. This directory is usually created as a subdirectory within the source tree. All the C++ object files, Java class files, and compiled libraries go into it thereby leaving the source tree as a read-only store for the code. Use of a build directory allows easy clean-up because the entire build directory can be removed. It also allows multiple variations of the same source code to be compiled in different, parallel build directories. Variations could be based on operating system, threading subsystem, module subset, and/or compiler version.
To make use of a build directory, the instructions from above vary only slightly. Before running configure.pl in step 5, do the following:
% mkdir BUILD_DIR % cd BUILD_DIR
Then for step 5, run configure.pl as follows:
% ../configure.pl
If you prefer to use the absolute path to configure.pl rather than the relative path shown above, that will work too.