Table of Contents
List of Tables
Table of Contents
Do you want to contribute to a cool project? Or do you want to learn more about VR, cross-platform techniques, and system abstractions? Then this is your guide. This book is for those people who wish to go further with their VR Juggler work by contributing to the project and even becoming full-fledged developers with commit access.
For those people interested in joining the VR Juggler developer team, you should read Part I, “Introduction” and Part II, “Compiling and Installing”. Once you have read those and decide you would like to get commit access, refer to the section called “How to Become a VR Juggler Committer”.
This document is different from the VR Juggler 1.0 Team Guide. That document relates only to VR Juggler whereas this covers the Juggler Suite of Tools as a (unified) whole.
By now you should have read the Getting Started Guide so that you know about environment variables and about compiling VR Juggler applications. It is expected that you already know about compilers and linkers and shells and most everything else developers of UNIX and Windows software deal with on a regular basis.
As a member of the VR Juggler Development Team, you will work on extremely scalable and extensible VR system software, use modern software engineering techniques such as UML and Design Patterns, and gain exposure within the VR development community. Your contributions will run on some of the world's most powerful VR configurations, as well as smaller single-user PC workstations.
We don't require much, but in order to coexist happily, we ask that you please refer the section called “Required Reading” which lists required background information. We appreciate your effort on the team.
Sincerely, The Juggler Development Team
Table of Contents
Table of Contents
Before diving into development tasks, we present some background information. This is to help newcomers understand the project and its goals, and it serves to keep existing developers on track and up to speed.
Our coding standard.
Design Patterns (Book: ISBN 0-201-63361-2) and Design Patterns in general
Autoconf documentation. (Try doing info autoconf).
Automake documentation. (Try doing info automake).
GNU make documentation. (Try doing a man or info on make or gmake. There is a good book on using make by O'Reilly and Associates).
Perl documentation. (Try doing a man on perl. There are several good books on Perl by O'Reilly and Associates).
Doxygen documentation (used in the various modules comprising VR Juggler to auto-generate documentation for C++ classes).
CVS documentation (used for revision control).
VR technology as a whole is stagnating with its closed source solutions. This means that anyone new to VR may need to develop a new solution, often inferior than others. Releasing an open VR software system is vital to the development of VR. Instead of reimplementing VR software, people need to focus on implementing new VR ideas and methods so that VR technology can mature. Now, because of VR Juggler, people can focus on implementing these new VR ideas and methods for the future because this technology is readily available to all, free from cost or legal ties.
VR Juggler is a platform for virtual reality applications. The name comes from the delicate balance that must be struck between flexibility, performance, and ease of use. You develop your application once for VR Juggler, then anywhere that VR Juggler is supported, your application is also supported.
VR Juggler's design addresses several key requirements for a virtual reality development system:
Performance
Flexibility
Rapid application development
Ease of use
Extensibility
Portability
Flexibility is achieved by placing common abstractions over I/O devices. New devices can be added easily, and existing devices can be reconfigured or replaced, even while an application is running. To allow optimal performance, applications are given direct access to graphics APIs (currently including OpenGL, OpenGL Performer, OpenSceneGraph, and OpenSG). VR Juggler includes built-in support for performance monitoring of applications and graphics subsystems. It supports multiple-processor machines and will support distributing applications across multiple machines.
Using VR Juggler to develop applications is kept as simple as possible. Small base classes provide a skeleton for application development, while the abstractions of I/O devices simplify programming. During run-time, any VR Juggler application can be controlled or reconfigured by a Java-based graphical interface.
VR Juggler is designed to support a wide array of VR hardware on a variety of architectures. Several tracking systems, gloves, and input devices are already supported. VR Juggler supports projection- based displays such as the CAVE™, and includes support for head-mounted devices. VR Juggler 2.0 is known to run on IRIX, Linux, Windows, Solaris, FreeBSD, HP-UX, and Mac OS X.
Table of Contents
Table of Contents
There are a few different ways to build the modules related to the VR Juggler project. This chapter explains all the ins and outs of getting the VR Juggler source code and compiling everything, including the documentation you are reading right now.
In general, readers should refer to the file INSTALL.html found in the top-level VR Juggler source directory and to the build-from-CVS public Wiki page. These have the most up-to-date information. In this part of the book, we cover more general topics that are not likely to change frequently. All developers of VR Juggler should nonetheless read this and the following chapters carefully to understand the build process as a whole.
This section lists the comprehensive set of software tools that we require when compiling VR Juggler from its source. If you are reading a printed version of this file, please check the website to ensure that you have the latest information. There have been several instances where bugs in third party software caused problems with compiling VR Juggler and running VR Juggler applications. For the most current system setup instructions, visit the system setup Wiki page.
Table 2.1. All Platforms
| CVS | 1.11 (or newer) |
| GNU make | 3.78 (or newer) |
| GNU Autoconf | 2.53 (or newer) |
| GNU Automake | 1.5 (or newer) |
| Perl | 5.6.0 (or newer) |
| Boost | 1.31.0 |
| CppDOM | 0.3.1 (or newer) |
| Java 2 Platform (for Tweek and VRJConfig) | 1.3.1 or newer (1.4.2 is recommended) |
Table 2.5. Win32
| Operating System | Windows 2000/XP[a] |
| Microsoft Visual Studio | 7.0 (.NET 2002) or 7.1 (.NET 2003) |
| Juggler Tools | Latest |
| Cygwin | 1.3 (including Perl 5.6.1 or newer) |
| NSPR | 4.1 (or newer) |
[a] Windows 2000 (or XP) is needed only for compiling the VR Juggler libraries. Applications can be compiled against the libraries on Windows 95/98/ME. | |
Table of Contents
As an open source product, the VR Juggler source code is freely available to anyone who wants to use it. In this chapter, we explain how to get the source. There are two ways to get the VR Juggler source code:
Get the source directly from the CVS repository.
Download a snapshot of the source code as a TAR file from the “Download” page.
Both methods are described in this section, though the second is mostly self-explanatory.
Before you can use CVS to get the source code, you must be sure that CVS itself is set up properly on your system. Depending on your platform, CVS may be available in several different forms. The most common version is the original command-line interface. If CVS is not available on your system, you can get the source from CVShome.org. This version is available for all platforms including Win32. For graphical interfaces, you can choose from the following:
MacCVS/WinCVS: A freely available front-end for CVS available from WinCvs.org
jCVS: A CVS client written in Java available from jCVS.org
tkCVS: A Tcl/Tk-based interface to CVS available from Two BarleyCorns
Once you have CVS running in some form, you are ready to download the source from the VR Juggler repository, hosted at SourceForge. The instructions given here are from the CVS section VR Juggler project page and are subject to change if the SourceForge policies change. Note that there are two sets of directions on that page: one for anonymous access and one for developers with commit access. Each of those is discussed in the following subsections.
Anonymous CVS access is for those who want the latest source code but do not have commit access. This would include developers who are working on patches they wish to submit for addition to the source base. As of this writing, the following are the basic instructions for anonymous CVS access:
“Log in” to the SourceForge CVS server. This step only has to be done the first time you access the repository. Afterward, the login setting is saved in your $HOME/.cvspass file.
% cvs -d:pserver:anonymous@cvs.vrjuggler.sourceforge.net:/cvsroot/vrjuggler login
Check out a copy of the current VR Juggler source tree:
% cvs -d:pserver:anonymous@cvs.vrjuggler.sourceforge.net:/cvsroot/vrjuggler checkout juggler
If what you really want is the VR Juggler 1.0 release branch instead of the developmental main branch, use the following command:
% cvs -d:pserver:anonymous@cvs.vrjuggler.sourceforge.net:/cvsroot/vrjuggler checkout -rRELENG_1_0 juggler_1.0
(The string RELENG_1_0 is the name of the branch in the CVS repository containing the VR Juggler 1.0 release code. “RELENG” means “release engineering”.)
Two different CVS modules are used in the above examples: juggler and juggler_1.0. This arises from the restructuring of the repository that occurred as part of the VR Juggler 1.1 evolution. In the juggler_1.0 module, only the RELENG_1_0 branch is still used. For more information about the branches, please refer to the information on the public Wiki site.
Once you have the source checked out, you can use CVS as you normally would keeping in mind that you have read-only access to the repository when using anonymous access.
You may find it useful to retain the CVSROOT value rather than always giving the -d option on the command line. Setting the $CVSROOT environment variable does just that. Defining a shell alias such as cvsjuggler that sets the environment variable is the recommended method.
For those developers with commit access, the steps are slightly different. You must have some version of SSH installed to access the repository as a developer. This is required by SourceForge, and we (the VR Juggler Team) have no control over this. The steps then to get a read/write copy of the VR Juggler source tree are as follows:
Set the environment variable $CVS_RSH to use ssh(1).
% CVS_RSH = ssh
(Note that this is using the shell-independent environment variable syntax defined in the Getting Started Guide.) It is recommended that you set this environment variable in your shell's configuration appropriate configuration file or as part of an alias that configures your environment to work with the VR Juggler CVS repository.
Check out the source using your SourceForge login name.
% cvs -dlogin_name@cvs.vrjuggler.sourceforge.net:/cvsroot/vrjuggler checkout juggler
Be sure to use the appropriate branch name.
Note that there is no login step in this case. Your SourceForge password is required for all CVS commands.
After this point, you can access the CVS repository as though it is a normal, local repository. As with the anonymous CVS access, you can set the $CVSROOT environment variable to the value given with the -d option above. For further information about using SSH with SourceForge, please refer to the appropriate SSH documentation and to SourceForge's documentation.
As a developer, you will probably need access to the latest VR Juggler source and therefore should be getting it from the CVS repository. In some cases, however, it may be helpful to get a snapshot of the code in an archived format. The download page on the VR Juggler website has a section listing source code snapshots. Here, you can get a compressed tar file containing the official source code for a particular release of VR Juggler. These snapshots are not for developmental purposes and will not give you access to the CVS repository.
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.
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.
Table of Contents
The VR Juggler project uses the Autoconf utility to stay portable across platforms. This means you will have to “configure” the project before compiling 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.
In this chapter, the following conventions are used for text formatting and naming:
Program, file, and directory names are represented this way.
Commands that are intended to be run by the user are written in this style.
References to system and library calls are written as call_name(##) where “##” is the manual section where that call's documentation can be found.
Makefile targets are named as 'target', and makefile variables are named as $(VAR_NAME).
Environment variables are named as defined in the “Enviroment Variables” chapter in the Getting Started Guide.
When first downloading the Juggler source to compile it, users must generate the configure script and vjDefines.h.in template using autoconf and autoheader. This files are not part of the repository because they are generated using third-party tools from files in the repository (i.e., configure.in and acconfig.h). The usual way to generate the files is:
% ./autogen.sh
This must be executed in the top-level Juggler source directory.
Once the configure script is generated, it can be invoked by typing:
% ./configure.pl
To get a list of all available options for configure.pl, do:
% ./configure.pl --help
To get a list of all available options for the multitude of Autoconf-generated configure scripts, run:
% ./configure.pl --all-help
VR Juggler uses tools from the GNU Autoconf package for automatically generating its configure script and its template configuration header file (vrjDefines.h). The command autoconf is used to “compile” the file configure.in in the top-level directory into the configure script, aptly named configure. autoheader reads both configure.in and acconfig.h to generate the template file vrjDefines.h.in which the configure script later uses to generate vrjDefines.h.
It is important that the generated files remain synchronized with their templates for proper compiling of the library. To facilitate this, revision numbers of configure.in and acconfig.h are available at the tops of the files, and these can be compared against the revision number of configure and vrjDefines.h.in. If the numbers do not match, it is best to run autoconf and/or autoheader to get everything up to date. Typically, autoconf needs to be used far more frequently than autoheader, but there are times when changes made only to configure.in require that both be run. It hurts nothing to run both whenever configure.in is updated.
Note that it is possible to use a configure script generated on a UNIX platform in a Win32 environment. The version of sh.exe distributed in juggler-tools.zip handles the UNIX newline characters. It is, however, not possible to use a configure script generated in a Win32 environment on a UNIX platform. The ^M characters confuse the shell and cause the script to fail immediately.
In a UNIX environment, no environment variables have to be set for configure to work properly. The PATH should be reasonable and must include tools such as C and C++ compilers, a working GNU make and standard UNIX utilities such as cat, sh, test, etc. The configuration process can of course uses environment variables such as $CC, $CXX, $CFLAGS, etc. as it runs. Users can define values for these variables to force the configuration process to use user-defined settings. This is common in configure script use.
In a Win32 environment, some variables have to be defined for the Microsoft Visual C++ compiler to work properly. These are mentioned on the Download page. Refer to that document to ensure that the environment is set up right for building and installing.
The script configure.pl is the glue that holds all the individual module build systems together. Given a configuration file (juggler.cfg) and a collection of build systems that follow some simple rules, configure.pl is capable of running all the component Autoconf-generated configure scripts in the correct order such that dependencies are satisfied. It completes the configuration process by generating a makefile that builds the individual modules.
The easiest way to configure VR Juggler is to run configure.pl with no options in the top-level source directory. Doing so will root compiling in that directory. This will use all the default values for the host platform with the script doing its best to make the right choices. In some cases, however, this may not be sufficient.
Possible situations that may cause configure to report a fatal error or a warning about a feature being disabled include the following:
The version of sh available does not support the features being used in configure. In this case, the configure script will exit with an error status. To get around this, invoke ksh, bash, or zsh on configure (in that order as available). These shells have newer features and fully support sh syntax. (In particular, this is known to be a problem with /bin/sh on Solaris 7 and possibly Solaris 8.)
A “modern” C++ compiler was not found. This is a fatal error. VR Juggler uses many features of the latest C++ standard, and a C++ compiler supporting these features is absolutely required. To use an alternate C++ compiler, specify a value for the environment variable CXX. Refer to the section called “Required Tools and Utilities for Building VR Juggler from Source” for compiler requirements.
The OpenGL libraries and/or header files were not found. This is a fatal error. To remedy this problem, use the --with-opengl option to configure to specify the root directory containing the OpenGL installation.
The OpenGL Performer libraries and/or header files were not found. This is not a fatal error and simply causes the Performer API to be disabled for that build. If Performer is available, use the --with-performer option to configure to specify the root directory containing the Performer installation. It may also be necessary to use the --with-pfver option if OpenGL Performer 2.4 is not the version installed.
A version of Perl greater than or equal to 5.004 was not found. This will cause installations to fail. To provide a valid Perl binary for use by the makefiles, use the --with-perl option to configure. The path given should be the full path up to but not including the perl binary itself. For example, if a perl5 binary were in /usr/unsupported/bin, give this directory as the argument to --with-perl. In a Win32 environment, use /'s as the path separator rather than \'s.
No Java compiler was found. This disables the compilation of VrjConfig. There are three ways to fix this, with all giving the same results:
Set the environment variable JDK_HOME to the Java installation directory (e.g., /usr/local/java which contains a bin subdirectory with all the JDK utilities).
Set the environment variable JAVA_HOME to the Java installation directory. This serves the same purpose as the previous option but offers users a different environment variable name to allow for varying configurations between sites and platforms.
Give configure a path to the Java installation through the --with-jdkhome option.
In a Win32 environment, the path separator character should be a `/' rather than a `\'. This is consistent with other uses of paths in a Win32 environment.
In this section, we present a description of the arguments that affect the execution of configure.pl. For the most up-to-date documentation, run the script as follows on the command line:
% ./configure.pl --manual
We now present a description of the options recognized by configure.pl. (Note that unrecognized options are passed through to the Autoconf-generated configure scripts which is what makes the whole thing work.)
Print usage information of this script and exit.
Print usage information for all the known Autoconf-generated configure scripts. The knowledge of configure scripts scripts comes from the configuration file. The output may be restricted using the --module argument, described below.
Print usage information of this script in UNIX manpage format and exit.
Print a list of the available modules that may be configured
Name the configuration file to be used by this script. If not specified, it defaults to juggler.cfg. This file is discovered based on the run-time path to this script, and thus the script and the default configuration file must be in the same directory. For example, if this script is run as:
../configure.pl
then juggler.cfg will be searched for as ../juggler.cfg.
Limit the work done by this script to what is required by the named module. The given name must correspond to one listed in the aforementioned configuration file. This can be specified in conjunction with --all-help to limit the output to only what is appropriate for the named module.
Just regenerate the files previously generated without running the Autoconf-generated configure script(s) again.
Name the file containing arguments to pass to the Autoconf-generated configure script(s) that will be executed. If not specified, it defaults to acdefaults.cfg, found using the same technique as is used for juggler.cfg (see --cfg above).
Name a .pl file (what could be a Perl script) that will be “imported” into this script. This imported code allows users to write Perl code that will extend the argument list passed to the Autoconf-generated configure scripts. If not specified, it defaults to acdefaults.pl, found using the same technique as is used for juggler.cfg and acdefaults.cfg (see --cfg above).
If both acdefaults.cfg and acdefaults.pl exist, acdefaults.pl is used, an acdefaults.cfg is ignored.
Define the host operating system. This can be any string. It will be used to recognize which platform-specific block to load from the Autoconf default arguments file. Use of this argument forcibly overrides automatic detection of the host operating system. Use with caution!
This section has not been updated for VR Juggler 1.1/2.0. Some of the options described below are accurate, but many are not. Until such time as this section is updated, it is best to read the output of running configure.pl with the --all-help option.
The following is a list of the current VR Juggler-specific options that can be invoked at configuration time as of Revision 1.273.2.3 of configure.in (the revision number can be found at the top of the configure.in file and at the top of the configure script). The output for all options is generated by doing configure --help.
Force the use of a C compiler other than what would be detected automatically.
Force the use of a C++ compiler other than what would be detected automatically.
Force the use of GCC as the compiler. Currently as of Revision 1.273.2.3 of configure.in), use of this option is not fully implemented. Its current state is for use only in a Win32 environment so that the Cygnus-Win32 version of GCC can be used to compile Juggler instead of the Microsoft Visual C++ command-line compiler.
Define the application binary interface (ABI) for which Juggler is compiled. In some cases, the instruction set architecture (ISA) can also be defined in combination with the ABI. The possible values for this are:
N32_M3 (IRIX): Use the new 32-bit ABI and the mips3 ISA (using MIPSpro compiler options -n32 -mips3. This is the default for building on IRIX.
N32_M4 (IRIX): Use the new 32-bit ABI and the mips4 ISA (using MIPSpro compiler options -n32 -mips4.
64_M3 (IRIX): Use the 64-bit ABI and the mips3 ISA (using MIPSpro compiler options -64 -mips4.
64_M4 (IRIX): Use the 64-bit ABI and the mips4 ISA (using MIPSpro compiler options -n32 -mips4.
ELF_i386 (Linux, Solaris, FreeBSD, NetBSD): Use the ELF ABI on x86 hardware. This uses the default ABI and ISA when compiling on the i386 versions of the named operating systems. Other ISA's may work but have not been tested. For other architectures, let the configure script figure out the ISA based on what it determines the target platform to be. This is the default option for the named operating systems.
WIN32_i386 (Windows NT, Windows 9x): Use the standard Win32 ABI on x86 hardware. This uses the default settings for compiling in these environments. No support is planned for other architectures. This is the default option for the named operating systems.
HP (HP-UX): Use the HP PA-RISC ABI. This will be supported in the future when the HP-UX port is functional. This is the default for building on HP-UX.
ALPHA (Digital UNIX): Use the standard Digital UNIX COFF ABI. This will be supported in the future if a port to Digital UNIX is made.
Give the JDK installation directory. This is the base directory containing a bin subdirectory with all the JDK utilities (such as javac and jar). The default is the value in $JDK_HOME or /usr/java if $JDK_HOME has no value. In a Win32 environment, this option must be give using /'s as the path separator rather than \'s.
Give the OpenGL Performer installation directory. This is the base directory containing an include subdirectory that in turn has a Performer subdirectory and at least a lib directory with the Performer libraries. On IRIX, there may also be a lib32 subdirectory and a lib64 subdirectory. They will be used appropriately depending on the ABI chosen (see above). The default path is /usr.
Give the IRIS/OpenGL Performer version installed. Between Performer 2.2 and 2.4, the names of the libraries were changed. In 2.2, they had an _ogl extension, but in 2.4, that extension was dropped. Specifying the version number defines which libraries will be linked in the Performer sample applications. The default version is 2.4.
Give the OpenGL installation directory. This is the base directory containing an include subdirectory that in turn has a GL subdirectory and at least a lib directory with the OpenGL libraries. On IRIX, there may also be a lib32 subdirectory and a lib64 subdirectory. They will be used appropriately depending on the ABI chosen (see above). This option is particularly useful (i.e., necessary) on platforms such as Linux, FreeBSD and HP-UX where OpenGL is not distributed as part of the base operating system. Common values are /usr/local, /usr/X11R6 and /opt/graphics/OpenGL (HP-UX 10.20). In VR Juggler 1.0, this option is not supported in a Win32 environment. The default path is /usr.
Tell the VR Juggler build system that the target system is using the Mesa OpenGL implementation. This will look for libMesaGL and friends rather than libGL, and it will use the libMesa* libraries when linking sample applications.
Give the Audiere installation directory. This is the base directory containing an include/audiere subdirectory and at least a lib subdirectory with the Audiere libraries. The default path is /usr/local.
Give the AudioWorks installation directory. This is the base directory containing an include/PSI subdirectory and at least a lib/PSI subdirectory with the AudioWorks libraries. If AudioWorks is found, the Juggler AudioWorks sound wrapper will be compiled and installed. The default path is /usr.
Give the OpenAL installation directory. This is the base directory containing an include/AL subdirectory and at least a lib subdirectory with the OpenAL libraries. OpenAL cannot be used with SPROC threads, and its use will be disabled when VPR is compiled to use SPROC threads on IRIX The default path is /usr/local.
Name the directory containing a Perl 5.004 or newer binary. A working Perl 5.004 or newer binary is necessary for a complete build and install of Juggler. The version of the binary can be determined by executing (perl -v). This path is the full path leading up to the binary (e.g., /usr/local/bin). There is no default, but common values are hard-coded into the configure script. They are /usr/bin, /usr/local/bin and C:/Perl/bin. Note that in a Win32 environment, paths must be given using /'s as the path separator rather than \'s.
Name the group used for ownership of installed files. This allows installation of Juggler under a group name controlled by the site administrator. If the group name is not found, no group is specified during installation which is typically fine. The default is “vrjuggler”.
Provide permissions for installed (normal) files. This will be used for header files, source code, config files, etc. The format must be UNIX octal-style (e.g., 0644). The default is 0644.
Provide permissions for installed executables. This will be used for scripts, executables, and shared libraries. The format must be UNIX octal-style (e.g., 0644). The default is 0755.
Provide permissions for directories created in the installation tree. The default is 0755.
Set the version number for this build. If not specified, it will be determined automatically from the contents of the VERSION file.
Define the threading implementation. The options are SPROC (use IRIX sproc(2) threads), POSIX (use pthreads), and NSPR (use NSPR threads). The default on IRIX is SPROC, though configure knows what other platforms should use. For example, POSIX threads are used on Linux and FreeBSD without specifying this option. NSPR is required on Mac OS X, Windows, and Solaris.
Enable the OpenGL API in the library. This option cannot be disabled and is on by default.
Enable the Performer API in the library. This turns on (or turns off) compiling of the Performer code in VR Juggler. Disabling is done using the standard method for Autoconf-generated scripts. On platforms that do not have Performer, a warning is issued and the API is disabled. This option is enabled by default.
Enable (or disable) the performance-testing code. This defines which method of performance testing should be used or disables it altogether. The possible options are as follows:
SGI: Use SGI-specific methods for doing performance testing.
POSIX: Use portable POSIX-specified code for performance testing.
NONE: Disable performance code
Disabling this code can be done using the NONE option or by using the standard disable option for Autoconf-generated scripts.
Another commonly used option is --prefix which is used to set the base directory for the installation. In a Win32 environment, be sure to use /'s as the path separator rather than \'s to be consistent with all other paths used by configure and the makefiles it generates.
The configure.pl script provides a method for regenerating files without running the individual configure scripts again. Simply execute the following:
% ./configure.pl --regen
This can be used to regenerate all the output files from their respective .in files without going through the entire configuration process again. This is useful, for example, when only a Makefile.in file changes without an update in the configure script. In general, when any .in file (other than configure.in) changes, the above method can be used to quickly incorporate the template file changes into the generated files.
Users who want to do a fresh configuration can run the script reconfig. It removes all cached data from any previous configuration processes and runs configure.pl with the same arguments it was given originally.
The VR Juggler configure script has been designed to work in a multi-platform environment. It allows VR Juggler to be built for multiple platforms using the same source tree (distributed with NFS for example) with all versions co-existing safely.
To take advantage of this feature, make a directory somewhere for building the library. This directory can go anywhere, but the typical location is a subdirectory of the top-level Juggler source tree. (Note that on a Win32 platform, this directory MUST be a subdirectory of the Juggler source tree.) It can also be called whatever seems appropriate. A common name is build, and alternate options are build-PLATFORM where PLATFORM is the name of the platform on which VR Juggler is being built. Multiple build directories can exist side by side. They fully separate all parts of the compile process and can be removed safely at the root. After making the directory, cd into it and run the configure script from it. For example, if a directory called build has been created as a subdirectory of juggler, do the following:
% cd build % ../configure.pl [options]
This will run the configure script as normal but will create a full, unique build environment as a subdirectory of build.
So the question becomes “To build or not to build?” There are advantages to running configure.pl from the top-level directory, and there are disadvantages to that method. A benefit of the simpler method is that it provides a quick start to building with no in-depth knowledge of the Juggler build system necessary. It has a “familiar feel” compared to other projects that use Autoconf-generated scripts for configuration. The main disadvantage of this method is that the generated files are “next to” the template files. As a developer, this can and has caused confusion about which file to modify. For example, it is very easy to forget that a quick modification to a Makefile will be destroyed when configure.pl is run again if that change is not also made in the corresponding Makefile.in. It is also easy to want to check in a generated file when only the templates should be in the CVS repository.
Similarly, there are advantages and disadvantages to creating a separate build environment. As mentioned above, building can be done for multiple operating systems using the same source tree. (This is how the NSPR API is currently built using their configure script.) In addition to building for multiple operating systems, it is possible to easily build multiple configurations from the same source tree. This is extremely useful for building different threading models and different ABI/ISA combinations to test changes in a single source tree. Also mentioned above, the entire build environment can be removed from the root. This is because all aspects of the build are separated from the source tree so that object files, makefiles, dependency files, etc. do not pollute the source tree. On the other hand, this is not a typical use of a configure script (though it is a documented method of configuration in the Autoconf documentation) and is thus not familiar to users. It can also result in complicated paths depending on where the build environment is rooted and how the path to configure.pl is specified.
When Autoconf-generated configure scripts run, a file called config.log is constantly updated in the working directory. When something goes wrong with the configuration process, the first thing to do is refer to the bottom of this file to see what was happening at the time of the error and why that step failed. Debugging the actual script is more difficult. Interested readers should refer to Chapter 8, Maintaining and Extending the Build System for more information on this particular topic.
This file is the template for vrjDefines.h (the equivalent of config.h) which is generated by configure. It provides definitions for various system-specific features that are available. vrjDefines.h is included by vrjConfig.h and should not be included by any source file directly. This file is generated by autoheader from configure.in and acconfig.h (the section called “Autoconf and Autoheader”) and is the only .in file that does not use the configure substitution strings (@VAR_NAME@). If modifications are necessary, they should be made to acconfig.h.
There are many Makefile.in's in the Juggler source tree. All are used by configure to generate the actual makefiles that are used for compiling and installing Juggler. They make extensive use of the configure substitution strings. Modifications should always be made to the Makefile.in file. The full list of available substitutions is available near the bottom of configure.in. The file Makefile.base.in provides most of these values as makefile variables (macros) and can be included by other makefiles to maximize sharing.
Besides the previous examples, configure can be used to generate any kind of file from a .in template file. The substitution strings are expanded just as they are in makefiles. An example of a generated file that takes advantage of this is VARS.pl.in, found in the top-level directory. It is used by the Perl script makefiles-gen.pl to do substitution in makefiles at installation time in the same manner as the configure script by storing the expanded strings in a Perl hash.
Table of Contents
To improve portability and consistency across platforms, VR Juggler uses GNU make for building the library (installation is covered Chapter 7, Installing VR Juggler). The makefiles used employ many features that are unique to GNU make thus requiring that people who wish to compile Juggler from its source are required to have it installed. The Juggler makefiles are known to to work with GNU make versions 3.78 and newer. 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.
In this chapter, the following conventions are used for text formatting and naming:
Program, file and directory names are represented this way.
Commands that are intended to be run by the user are written in this style.
References to system and library calls are written as call_name(##) where “##” is the manual section where that call's documentation can be found.
Makefile targets are named as 'target', and makefile variables are named as $(VAR_NAME).
Environment variables are named as defined in the “Enviroment Variables” chapter in the Getting Started Guide.
As mentioned in the introduction, Juggler requires the use of GNU make for compiling. This section provides a very short introduction to the use of make in general. It is assumed that the GNU make command is “gmake”. To verify that the version of GNU available is one of the known working versions, do:
% gmake -v
It will return something similar to the following output:
GNU Make version 3.79.1, by Richard Stallman and Roland McGrath.
Copyright (C) 1988, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 2000
Free Software Foundation, Inc.
...The emphasized text is the version information. For best results, this should be one of the version numbers listed in the section called “Required Tools and Utilities for Building VR Juggler from Source”.
Most, if not all, versions of make (not just GNU make) use the following syntax for execution:
make [[VARIABLE=value...] | [target...]]
The options in square brackets are not required. The [...] strings mean that any number of the previous option can be given. If executed with no arguments, the default target will be built. This is either the first target defined in the corresponding makefile or one explicitly denoted as 'default' in the makefile. Typically, the default target is 'all'. Any target(s) can be built by simply naming them on the command line.
Variables used in the makefile can be overridden by command-line arguments. Simply name the variable (e.g., CC, the C compiler command) and give it a value (e.g., CC=/usr/local/bin/gcc). This forces all references to the variable in the makefile to use what is on the command line.
Other useful options for GNU make are the following:
-k: Keep going even when errors are encountered
-f filename: Explicitly name the makefile to use instead of the default (either Makefile or makefile found in the current directory)
-j [count]: Do a parallel build of the target(s), optionally limiting the number of processes spawned to count
-l float-value: Limit the load on the machine to the specified value when doing a parallel build
This section describes all the targets related to building VR Juggler from its source code. The targets are grouped together depending upon how they are related. For information on what is actually done as part of the compiling process, see the section called “Process of Building (Individual Steps)”. A current list of all the targets (with descriptions) can be found at the top of Makefile.in in the top-level VR Juggler source directory.
Clean up the build environment and then build and install everything using the default ABI and ISA. This is a simple target for those who just want to build and install VR Juggler as simply as possible. “Everything” in this case is the following:
Debugging, optimized, and profiled versions of the library binaries
Shared and static versions of the library binaries (if both are supported on the target platform)
Header files
Sample applications, test code, and user tools
Data files (sample config files, model files, etc.)
VRJConfig (if it was built)
This is the same as the 'world' target except that it builds and installs all possible ABI and ISA combinations for the target platform. On IRIX, for example, this means that all combinations of N32, 64, mips3, and mips4 (debugging and optimized versions) are built and installed. Most platforms currently support only one ABI/ISA combination thus making this target the same as 'world'.
This target is similar to 'world' except that the installation tree is suitable for redistribution. Extra files such as the change logs, the release notes, and the license files are installed. In addition, the tree is stamped with a build time to help track possible differences between two releases of the same version. (This has only occurred for one VR Juggler beta release, but it seems like a good idea to have the build time included with a distribution.)
This is the same as the 'release' target except that it builds and installs all possible ABI and ISA combinations for the target platform. On IRIX, for example, this means that all combinations of N32, 64, mips3, and mips4 (debugging and optimized versions) are built and installed. Most platforms currently support only one ABI/ISA combination thus making this target the same as 'release'.
This target is the same as 'all'. In other words, it builds everything. It executes the first phase of the 'world' target (i.e., only the build phase, not the install phase). Since it builds both debugging and optimized versions of VR Juggler without installing, it is useful for testing changes to the library code to ensure that it works in both the debugging and optimized cases.
In the same manner as 'world-all-abi', this target builds, but does not install, all possible ABI/ISA combinations for the target platform. Thus, it provides functionality that could also be called 'buildworld-all-abi', but the length of such a target's name is unwieldy.
Build only the debugging version of the library binaries (both static and dynamic). In other words, the libraries are built so that debugging symbols are turned on. It is the combination of 'dbg' and 'dbg-dso' (see below). This is the default target and is what gets built if running make(1) with no arguments.
Build only the optimized version of the library binaries (both static and dynamic). This is built with no debugging symbols at all. It is the combination of 'opt' and 'opt-dso'.
Build only the profiled version of the library binaries (both static and dynamic). This capability is dependent on the compiler being used. Not all compilers support the process of generating profiled code, so this target may have no effect. Profiled libares are built with debugging symbols. This target is the combination of 'prof' and 'prof-dso'.
Build only the static debugging version of the libraries. This does the same thing as 'debug' but does not compile the dynamic libraries.
Build only the dynamic debugging version of the libraries. This does the same thing as 'debug' but does not compile the static libraries.
Build only the static optimized version of the libraries. This does the same thing as 'optim' but does not compile the dynamic libraries.
Build only the dynamic optimized version of the libraries. This does the same thing as 'optim' but does not compile the static libraries.
Build only the static profiled version of the libraries. This does the same thing as 'profiled' but does not compile the dynamic libraries.
Build only the dynamic profiled version of the libraries. This does the same thing as 'profiled' but does not compile the static libraries.
Compile the VRJConfig Java files and collect them into VRJConfig.jar. This is only done if the configure script found a working Java compiler during its phase of the compile process.
Set up the developer pseudo-installation environment. More detail is given on this subject below in the section called “Developer Installation”.
Clean up everything in the build environment. This uses the 'clean' target defined by Doozer++ that is automatically included by all makefiles. The cleaning process is recursive just as the build process is. Each makefile may define which files are safe for cleaning, but generally core files, compiler-generated files, and object files are the only things removed during this process.
Clean up the automatically generated dependency files (the .d files in each directory). This method for cleaning up deletes only these files and nothing else--ever.
Remove the developer pseudo-installation environment. More detail is given on this subject in the section called “Developer Installation”.
Clean up (clobber) the entire build environment except what was generated by configure. This runs the above clean-up targets and removes the object directory(ies) and lib directory(ies). Its purpose is to reset the build environment to its state just prior to running configure.
Print out all the targets with short descriptions as well as default values for some variables that may be overridden by the user. For more information about variables in the Juggler makefiles, see the section called “Useful Variables”.
Build targets executed from the top-level directory generate the object files in a directory tree created during compilation named as obj/platform/ABI/ISA/opt|debug. It is always a subdirectory of the top-level directory in the build environment. The path to this directory is passed as an argument to the recursive make process overriding the $(OBJDIR) variable.
Similarly, a subtree is made for the library binaries. It is named as lib/ISA/opt|debug (or lib32/... or lib64/... depending on the platform and the ABI). Since the library binaries are built only by the Makefile in the top-level directory, it is only used by builds from that directory.
Targets such as 'dbg', 'opt' and 'clean' are available for use in the individual subdirectories. Building a target from within a subdirectory is localized to that subdirectory. Thus, all object files would be generated in the directory where the target was run rather than in the obj subdirectory. For example, the following process would build only the object files in the Config directory:
% cd Config % gmake opt
Those object files can be removed by running the 'clean' target in that directory.
As with all make-based build systems, variables used in the makefiles can be overridden by the user. This section describes variables that developers may find useful to override while compiling. The variables are listed alphabetically.
Provide an alternate installation prefix than what was set at configuration time. Refer to Chapter 7, Installing VR Juggler for more information about installing VR Juggler.
Define an alternate ABI/ISA combination than the default set by configure. This accepts exactly the same values as the --with-abi argument to the configure script. Results of its use can be seen near the bottom of Makefile.base.
Do not clobber the build environment (via the 'clobber' target) before running the 'world' target. Set this variable to 1 to enable it.
Disable compiling and installing of VRJConfig by setting this variable to 1 when building. This is very handy when VRJConfig is not building properly or is not needed for whatever reason.
Set an alternate directory in which object files are created. The default method is to use the platform- and ABI-specific directory when compiling from the top-level directory or to use the current directory when compiling in a subdirectory.
Choose an alternate suffix for object files that are compiled. When compiling with MS Visual C++, “obj” is the default. In all other cases, “o” is the default. Only specify the suffix, not the '.' as that is always present.
Provide a different version of a Perl 5.004 or newer binary than what configure found.
Two options can be used with GNU make when compiling VR Juggler. They provide the capability to build the library in parallel to take advantage of hardware that can do this effectively. To enable parallel building, specify the -j argument on the command line. With no argument, there is no limit to the number of jobs that are spawned by the build process. An integer argument limits the number of jobs to that value.
The second argument enforces load balancing on the machine while doing a parallel build. To do this, use the -l option with a floating-point value as the load limit. Note that to be allowed to do this, GNU make must be installed setgid on many platforms. When used in combination with the -j option, parallel compiling can be done while not loading the machine down too heavily.
This section describes the steps taken by the 'world' target as it builds VR Juggler. All other build targets are subsets of 'world', and this information can be applied accordingly. Note that 'world' can only be run from the top-level directory of the build environment. The steps are: