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.);