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.