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.