Table of Contents
List of Tables
Table of Contents
Table of Contents
Do you want to contribute to a cool project? Want to learn more about VR, cross platform techniques, and system abstractions? 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.
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.
To become a developer with commit access on the Juggler opensource project, refer to the section called “How to Become a VR Juggler Committer”.
As a member of the Juggler Development Team, you will work on extremely scalable and extensible VR system software, use modern software engineering techiniques such as UML and Design Patterns, and gain exposure within the VR development community. It is your contributions that will run on some of the worlds most powerful VR configurations, as well as smaller single-user PC workstations.
We don't require much, but in order to happily coexist, 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
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 VR Juggler to autogenerate 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 need to completely develop a new solution, often inferior than others. Releasing an open VR system is vital to the development of VR. Instead of reinplementing VR systems, 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 now this standard technology is readily available to all, free from cost or legal ties.
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 Juggler, then anywhere that 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 and Iris Performer).
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 and developing applications are 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. Juggler supports projection- based displays such as the CAVE or C2, and includes support for head-mounted devices. Development work is being done on IRIX, Linux, Windows NT, Solaris, and FreeBSD systems, with reports of success on HP/UX.
Table of Contents
Table of Contents
There are a few different ways to build the projects related to the VR Juggler project. This chapter explains all the ins and outs of compiling VR Juggler and related projects including the documentation you are reading right now.
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.
Table 3.1. Requirements by Platform
| Platform | Minimum Software Versions |
| All | |
| IRIX | |
| RedHat Linux | |
| Win32 | |
| Platforms not Officially Supported | |
| HP-UX | |
| Solaris™[b] | |
| Solaris™ | |
| FreeBSD | |
[a] Windows NT 4.0 is needed only for compiling the VR Juggler libraries. Applications can be compiled against the libraries on Windows 95/98/Me. [b] Support for the Forte™ C++ (WorkShop™ C++) development package on Solaris™ has not been tested, so only freely available GNU utilities are listed. | |
Table of Contents
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: Afreely 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. Afterwards, 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: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 juggler
(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”.)
% cvs -d:pserver:anonymous@cvs.vrjuggler.sourceforge.net:/cvsroot/vrjuggler checkout -r RELENG_1_0 juggler_1.0
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 an 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 SSH1 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 ocumentation 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 make 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.
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.
Choose a directory to put Juggler. From this point on, we will refer to that directory as SRC_DIR.
Go to that directory and checkout juggler using CVS. Make sure CVS is set up and pointing to the VR Juggler repository. Refer to the SourceForge instructions for getting VR Juggler with CVS.
% cd SRC_DIR % cvs checkout juggler
Enter the newly checked-out VR Juggler source directory.
% cd SRC_DIR/juggler
Set the environment variable VJ_BASE_DIR
The directory instlinks is semi-important. What does the word “instlinks” mean? It is a working distribution of the Juggler library. After gmake is done, you'll be able to use this directory as though it were an installed version of VR Juggler.
This directory also determines where juggler files will be created. Juggler files will be created in some-directory/instlinks/.. (in other words, files are created one directory back from instlinks).
Make sure the following environment variable assignment line is in your shell's startup file:
VJ_BASE_DIR=SRC_DIR/juggler/instlinks
Compile juggler (using the Autoconf system and GNU make):
Auto-generate the configuration script configure:
% autoconf
Auto-generate the vjDefine.h.in header template:
% autoheader
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 --help for options.
% ./configure
Build (make) the distribution using GNU make. This compiles, links, and creates the final distribution tree (in the form of symbolic links).
% gmake
Advanced Topics
Send compiler output to a different directory than the source tree. Run this in the directory you want compiler output to go. This is typically done with a subdirectory in the juggler source tree. We will call it <BUILD_DIR>.
% mkdir <BUILD_DIR> % cd <BUILD_DIR> % <SRC_DIR>/configure
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.
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:
% autoconf ; autoheader
This must be executed in the top-level Juggler source directory.
Once the configure script is generated, it can be invoked by typing:
% ./configure
To get a list of all the available options, do:
% ./configure --help
VR Juggler uses tools from the GNU Autoconf package for automatically generating its configure script and its template configuration header file (vjDefines.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 vjDefines.h.in which the configure script later uses to generate vjDefines.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 vjDefines.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 easiest way to configure Juggler is to run configure with no options in the top-level source directory. Doing this will root compiling in this 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.
The OpenGL libraries and/or header files were not found. This is a fatal error. To remedy this problem, use the --with-oglroot 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-pfroot 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 compiling of vjcontrol and installation of the library 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 vjcontrol. 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.
The following is a list of the current 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.
Define the threading implementation. The options are IRIX_SPROC (use IRIX sproc(2) threads), POSIX (use pthreads) and WIN32 (use Win32 threads). The default is IRIX_SPROC, though configure knows what other platforms should use. For example, POSIX threads are used on Linux, Solaris and FreeBSD without specifying this option.
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 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 SL installation directory. This is the base directory containing an include/sl subdirectory and at least a lib subdirectory with the SL libraries. Before testing for SL, a test will be performed checking for the SGI Audio library if compiling on IRIX. If it is found, then the test for SL is performed. If SL is found, the VR Juggler SL sound wrapper will be compiled and installed. The default path is /usr.
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.
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.
After running configure, one of the generated files is a shell script called config.status. This script 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, config.status can be used to quickly incorporate the template file changes into the generated files.
The configure script should always be run after it is regenerated from configure.in. Thus, whenever autoconf is run (see the section called “Autoconf and Autoheader” for more information), the script itself should be run again to ensure that the latest build environment is available.
The VR Juggler configure script has been designed to work in a multi-platform environment. It allows 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 [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 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 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 is specified.
When configure runs, 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 9 for more information on this particular topic.
This file is the template for vjDefines.h (the equivalent of config.h) which is generated by configure. It provides definitions for various system-specific features that are available. vjDefines.h is included by vjConfig.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 8). 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 and optimized 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.)
VjControl (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 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 'ddso' (see below). This is the default target and is what gets built if running make 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 '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.
Compile the VjControl Java files and collect them into VjControl.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 a 'clean' target defined in Makefile.base that is automatically shared by all makefiles that include that file. The cleaning process is recursive just as the build process is. Each makefile defines 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 previous clean-up targets and removes the object directory(ies) and lib directory(ies). Its purpose is to totally 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 8 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 VjControl by setting this variable to 1 when building. This is very handy when VjControl 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:
Clobber the build environment so that it is as it would be after running configure in a clean directory tree.
Build the object files for the optimized version of the library binaries. Part of this process is to generate dependencies for each .c and .cpp file on the fly. These dependencies are listed in corresponding .d files and are updated automatically whenever a change in a source or header file is detected. All targets, except 'cleandepend', run in the subdirectories of the source tree (not just the one that builds optimized object files) ensure that dependencies are up to date all the time. Compiling from the top-level directory of the build environment puts the optimized object files in a platform- and ABI-specific subdirectory named as obj/platform/ABI/ISA/opt.
Create the static and dynamic versions of the library binaries from the optimized object files. The binaries are built in the subdirectory named as lib/ISA/opt and are linked to from the lib directory. Note that lib may be named differently on some platforms. On IRIX, for example, depending on the default ABI, it may be named lib32 or lib64. It is referred to as lib for simplicity.
Repeat steps 2 and 3 for the debugging version of the object files and library binaries.
Once all libraries are built, links are set up in the lib directory and its ISA subdirectory (if there is one) that point to the default library version. This is currently the debugging version since that is what developers are likely to use most frequently. These links overwrite those made in step 3 (and repeated in step 4).
Compile VjControl if the Java compiler is available and compiling of it has not been disabled by the user (refer to the section called “Useful Variables” for more information).
The remainder of the work done is installation. More information on installing is available in Chapter 8.
To facilitate development of VR Juggler applications, an environment is created after compiling that simulates a fully installed version of the library and its components. This is done entirely within the build environment and is rooted in a directory called instlinks (a subdirectory of the top-level build directory).
When the build process completes, a message is printed telling the developer the value to which s/he should set the environment variable $VJ_BASE_DIR. By doing this simple step, the developer is given a pseudo-installation where Juggler applications (that are part of the source tree) can be compiled and executed. These applications are linked statically on IRIX, but on all other UNIX-based platforms, they are linked dynamically. In those cases, $LD_LIBRARY_PATH should be set to the value $VJ_BASE_DIR/lib which is a normal step in the setup process for using an actual installation.
As of this writing, this environment is not available on a Win32 platform. This is because the creation of it relies heavily on symbolic links. Because of this, Juggler must be fully installed for application development. Suggestions for enabling an equivalent development environment for Win32 are welcomed. It is possible, after installing Juggler, to continue working within the build environment. Set $VJ_BASE_DIR to the installation directory and continue working as on any other platform. All library binaries and headers will be referenced from the installed version, but source code (for applications as an example) comes from the Juggler source tree.
Table of Contents
To improve portability and consistency across platforms, VR Juggler uses GNU make for installing the library (compiling is covered in Chapter 7). 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.1 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.
Please refer to the section called “General Quick Start”. The information there provides everything needed to get started with installing Juggler after building it.
This section describes all the targets related to installing 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 full installation process, refer to the section called “Process of Full Install (Individual Steps)”. A current list of all the targets (with descriptions) can be found at the top of Makefile.in in the top-level Juggler source directory.
This target is the same as 'install-all'. It performas a full installation of library binaries (both debugging and optimized for the default ABI/ISA combination) and all associated files. The steps taken for this installation are as described in the section called “Process of Full Install (Individual Steps)”. This is the essentially second phase of the 'world' target described in Chapter 7. It requires that 'buildworld' be successfully completed beforehand.
This is the same as the 'installworld' target except that it 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) are installed. Most platforms currently support only one ABI/ISA combination thus making this target exactly the same as 'installworld'. The steps taken for this installation follow those described in the section called “Process of Full Install (Individual Steps)”.
This target is the same as 'install'. It installs only the debugging version of the library binaries (both static and dynamic) and all associated files. It includes the combination of 'install-dbg' and 'install-ddso' (see below). The steps taken for this installation follow those described below. This is the target that is run when using the traditional make install command.
Install only the static debugging version of the library binaries. Nothing besides the libraries is installed.
Install only the dynamic debugging version of the library binaries. Nothing besides the libraries is installed.
Install only the optimized version of the library binaries (both static and dynamic) and all associated files. It includes the combination of 'install-opt' and 'install-dso' (see below). The steps taken for this installation follow those described in the section called “Process of Full Install (Individual Steps)”.
Install only the static optimized version of the library binaries. Nothing besides the libraries is installed.
Install only the dynamic optimized version of the library binaries. Nothing besides the libraries is installed.
Install all the header files from the VR Juggler source tree.
Install the sample applications and generate all the application makefiles from the Makefile.in templates. This makes a copy of the samples directory tree found in the VR Juggler source.
Install the test code and generate all the application makefiles from the Makefile.in templates. This makes a copy of the test directory tree found in the VR Juggler source.
Install the user tools and generate all the necessary makefiles from the Makefile.in templates. This makes a copy of the tools directory tree found in the VR Juggler source.
Install the standard VR Juggler data files. This makes a copy of the Data directory tree found in the VR Juggler source.
Install the VjControl JAR file and its runnable files. In a UNIX environment, the vjcontrol scripts are installed. On a Win32 platform, the vjcontrol.bat batch file is installed. This is done only if the configure script found a working Java compiler and the target is not being disabled via the $(NO_JAVA_GUI) variable.
Build the directory hierarchy for the installation. This is done before any of the “full” install targets ('installworld', 'install-all-abi', 'install-debug' and 'install-optim') is run. This is useful for testing parts of the installation or doing partial installations. Run it before doing any testing to create the full install hierarchy and then run the selected install targets. For example, to install only the static debugging libraries with nothing else, do:
make hier install-dbg
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 installing. The variables are listed alphabetically.
Provide an alternate installation prefix than what was set at configuration time. This is handy if testing the installation process or if no prefix was given at configuration time. Specifying a value for this variable is all that is necessary to change the entire installation path of 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. If this was used as part of compiling, it must also be used for installing to ensure that everything is installed properly.
Disable ths installation of VjControl by setting this variable to 1 when building. This is very handy when VjControl is not building properly or is not needed for whatever reason.
Provide a different version of a Perl 5.004 or newer binary than what configure found. Perl is crucial to the installation process because several Perl scripts are used (see the section called “Custom Scripts”). If it necessary to use a different perl binary than the one that configure found, it can be named with this variable. All Perl scripts will use it.
This section describes the steps taken by the “full” installation targets 'installworld', 'install-all-abi', 'install-debug', and 'install-optim' when they are run by the user. These four targets install library binaries and all associated VR Juggler files (data files, VjControl, headers, sample apps, etc.). The steps are:
Do any pre-installation steps necessary. This includes creating the entire installation directory hierarchy.
Install the library binaries (those that are appropriate for the target being run). Refer to the section called “Targets” for information on which binaries are installed by which targets. In particular, the 'installworld' target sets up links in the installed lib directory pointing to the default library version (currently the debugging version).
Install all the header files needed for compiling applications.
Install all the sample code provided as examples of working VR Juggler applications.
Install the test code provided for testing various aspects of VR Juggler (threads, math, input devices, etc.) to ensure that it is in good working order.
Install the various user tools included as helper applications in using VR Juggler.
Install all the data files (config files, gesture files, calibration tables, etc.).
Install VjControl (if it was built).
Do any post-installation steps necessary. Currently, nothing is done at this stage except informing the user that installation is complete.
The installation process heavily depends on scripts written for VR Juggler. Most of the scripts themselves are generalized such that they are not specific to Juggler, and in the case of mtree.pl, the script is written to fill in if the mtree(1) application is not found by configure. The use of each script is described in detail here.
mtree(1) is a utility for mapping directory hierarchies. It dates back to 4.3BSD-Reno, and development of it has continued in FreeBSD and in NetBSD. mtree.pl is a Perl script written to mimic the behavior of mtree(1) (the version distributed with FreeBSD 3.0) so that Juggler's installation can take advantage of its features on platforms without mtree(1). The two are not completely functionally equivalent at this time, but the basic features needed by VR Juggler are present.
The key aspect of mtree(1) that the Juggler installation uses is the creation of directory hierarchies from specification files (named with the extension .dist). These specifications can be used to create the full installation tree with all directories guaranteed to have the same permissions and ownership. The actual specification files are generated by configure from template files to allow maximum flexibility. One key file, VJ.lib.dist, is generated by configure from scratch (i.e., without a template) so that it can take advantage of configure's internal knowledge about the target platform.
The options that are used during installation are the following:
If any of the owner, group or permissions for a directory do not match the specification, update them accordingly. All three must be specified for a missing directory to be created. (Note that this extra stipulation is not yet implemented in mtree.pl.) On a Win32 platform, the owner and group are essentially meaningless because the Perl 5 port does not implement the functions that can read and modify ownership.
Ignore everything except directory file types. This is used only for ensuring the integrity of the directory hierarchy.
Ignore files in the hierarchy that are not in the specification. This is especially important since the VR Juggler specification files only contain directory information.
Read from the named specification file rather than from the standard input.
Start at the name directory rather than the current directory.
mtree(1) provides a wide range of features but unfortunately not all are implemented in mtree.pl. For example, besides being used to build a hierarchy, it can be used to generate a specification file for an existing hierarchy. For more information about what can be done with this utility, refer to the manual page if mtree(1) is distributed with the operating system. More work on bringing the two closer together in functional equivalence is anticipated.
This Perl 5 script is used to install an entire directory tree without any of the CVS directories. Its use is very simple. In general, the base of the tree to be installed and the destination directory are all that is necessary. The basic usage is:
install-dir.pl [-i source directory | -o destination directory | -u user name | -g group name | -m mode]
Options for the script are as follows:
Name the directory to be installed. Required.
Name the directory to which source directory is installed. Required.
Name the user that will own the installed files and directories. This has no meaning on a Win32 platform.
Name the group that will own the installed files and directories. This has no meaning on a Win32 platform.
Provide the permission bits (UNIX octal style) of the installed files. Note that this sets the same permissions for all files. If used in combination with mtree(1), permissions can be set on a per-file basis after this script is run.
Currently, this script is used to install the Data directory since it contains no source files (see install-src.pl below), and it is used in the process of creating VjControl.jar. Thus, it is versatile enough to be used during both the compile and install phases.
Similar to install-dir.pl, this script installs the contents of a directory tree to a specified location. It is, however, more selective in what it installs. Only source files of recognized types (.txt, .TXT, .C, .c, .h, .cxx, .CXX, .cpp, .CPP and makefiles) are copied from the source to the destination. Any CVS directories are not copied over. The options for this script are exactly the same as those for install-dir.pl.
This script is used to perform the same functions as configure when it expands the “@...@” strings in .in template files. Its use is reserved for the installation phase rather than the configuration phase. The installation process copies over many Makefile.in's that configure would normally generate for use by developers. To simplify maintenance, the same template files are used for installations that users can access. Since the templates still contain the “@...@” strings, they must be expanded again. Thus, makefiles-gen.pl steps in for this purpose.
Options for makefiles-gen.pl are slightly different from any of the other scripts. It uses GNU-style options for the sake of clarity since some of the options correspond directly to a “@...@” string to be expanded. The options described here are required unless otherwise noted.
The name of the file given for this option is a Perl file containing “@...@” substitution values. These are used when replacing the “@...@” strings in the template files. For more information about this file, see the paragraph following this list. Note that the file name given should be the one generated by configure and not the .in template version. The generated file has the expanded strings that this script needs for its job.
This option is typically a simple value providing a path to the source code relative to the makefile. In almost all cases, it will be `.' since the source code and the Makefile being generated are in the same directory. This replaces @srcdir@.
Use this option to name the base directory where the Makefile's will go. For example, to generate the makefiles in the samples installed subtree, the path given is $(datadir)/samples.
This option names the base of the directory tree containing the Makefile.in templates. In other words, it is a subdirectory in the Juggler source tree in which the recursive search for Makefile.in's starts.
In conjunction with the previous option, name the directories to be searched for Makefile.in templates. Only the directories here will be searched and used in the generation process.
Give the name of the user who will own the installed files. This option has no meaning on a Win32 platform. This option is not required.
Give the name of the group that will own the installed files. This option has no meaning on a Win32 platform. This option is not required.
Give the permissions (UNIX octal style) to be set for the installed files. This defaults to the running user's umask. This option is not required.
The key to this script is VARS.pl.in, located in the top-level VR Juggler source directory. It is a Perl file that can be evaluated at run time by the script to set values used for substitution. The format used in the file is:
$VARS{'VAR_NAME'} = '@VAR_NAME@';Note that VAR_NAME should be the same in both places for ease of understanding. The %VARS hash is used in the substitution process. Occurrences of its keys found in a Makefile.in are replaced with the value associated with that key (the expanded “@...@” string). Also note the use of apostrophes to prevent expansion of variables by the Perl interpreter. Be careful to use the right string delimiters when adding new values.
Many of these Perl scripts use the InstallOps module (found in InstallOps.pm with the other scripts). This module provides subroutines implementing commonly used techniques in working with directory trees and files during installation. Ideally, it is general enough to be used in writing new scripts that can be added to the installation process. A short description of the available subroutines and their use is provided here.
recurseDir();
($start_dir, $base_inst_dir);
Recurse through the given directory tree beginning at $start_dir. The second argument, $base_inst_dir, names the base directory to which the files will be installed. This routine requires that the calling package define a subroutine called recurseAction() that defines what actions to take when a normal file is encountered during the recursion process. It is only called when non-directory type files are found in the current directory of the recursion process. Since this is specialized for installation, it ensures that the destination directories (rooted at $base_inst_dir) exist.
newDir();
($base_dir, $newdir);
Create a new directory ($newdir) in a given directory tree ($base_dir). If it already exists, it is not created.
installFile();
($filename, $uid, $gid, $mode, $dest_dir);
Install a given file ($filename) with specified permissions ($mode) in UNIX octal style to a destination directory ($dest_dir). Ownership is set based on the provided values for $uid and $gid (which has no effect on a Win32 platform).
replaceTags();
(Replace tags of the form @...@ in the given file ($infile) with known replacement values (found in %VARS). The tags are the keys of %VARS, and the replacement values are the values associated with those keys.);
Table of Contents
Table of Contents
Part of being an open source project includes accepting contributions from the user community. When members of the user community contribute code to a project, everyone benefits. In this chapter, we explain why contributions are helpful, and we expalin how to make contributions.
People who have limited experience with open source projects may not be familiar with the ideas surrounding user contributions. Because users have direct access to the source code, they have the opportunity to fix bugs, add new features, and otherwise improve the project. When users make such changes, they send them to the development team for inclusion in the next release.
VR technology as a whole is stagnating with its closed source solutions. This means that anyone new to VR need to completely develop a new solution, often inferior than others. Releasing an open VR system is vital to the development of VR. Now instead of reimplementing VR systems, people can focus on implementing new VR ideas and methods all relying on this standard technology to be there, and free from cost or legal ties.
Because VR Juggler will benefit from your efforts, that's why! As an OpenSource project, we want your help, your input, your ideas, and most of all, your code contributions. You don't have to be a hot-shot, fast CPUs, fast downloads programmer to contribute. VR Juggler is a big project, and it is still growing. Whether your background is in UNIX-based systems or Win32, you can help. We want motivated, creative people to help us make VR Juggler the world's best virtual reality platform. If you're still not convinced, take a look at the rest of this page for some more motivation.
Only the most trivial software is bug free, and VR Juggler is certainly non-trivial. We do our best to track down and fix bugs, but our fly swatter is only so big. If you find a bug, then by all means, submit a bug report and give us a patch! Don't worry, we won't be too embarrassed.
As with most projects, the features present in VR Juggler are those deemed necessary by the developers and users. New features are added, but the developers with commit access only have so much time each day to devote to the advancement of the source. With a growing user base and advances in the field of virtual reality, new features help everyone. If you have an idea or some earth-shattering code, we want to see it!
Everyone in the field of virtual reality has differing ideas, goals and equipment. If VR Juggler is to prove usable as the basis for advanced (and not-so-advanced) virtual reality applications, it will need to provide support for the needs of as many users as possible. Getting to this point means that missing features need to be added by someone. Eventually, the current developers could find the time to meet everyone's needs, but those needs can be met faster with the help of contributors.
The most obvious case of a missing features is a driver for Device X. VR Juggler provides a highly flexible mechanism for adding a device driver to the source. If you have driver source code for a currently unsupported device, chances are that driver can be added to VR Juggler easily.
Other examples of missing features can include a wide variety of extensions. To save yourself time, it would be best to discuss your ideas in a public VR Juggler forum (insert vrjuggler-devel link) first so that you can get feedback on whether your ideas are applicable to the VR Juggler core or would be better suited to a higher-level tool.
The VR Juggler team loves what it does and is excited about VR Juggler and its continued development. We are, however, a small group with big ideas and busy schedules. We want your help because, with support from many bright, creative developers, we think that VR Juggler can achieve these big goals and more.