Table of Contents

Vlab Installation

Quick Contents of this Page

Getting the vlab distribution

 This distribution is intended for SGI machines, preferably with full color. Vlab programs rely on X, Motif, OpenGL, awk, ed, shared libraries, a preprocessor for C (cpp or equivalent), and SGI utilities snap, izoom and ipaste. The minimum operating system requirement is Irix 5.3 or higher. See release history for further details.
Note that the sample object-oriented file system of experiments includes some objects that require the use of the rayshade program. (Rayshade is a public domain ray tracer developed by Craig Kolb at Yale University. Cpfg currently supports rayshade version 3.0, which is available for anonymous ftp from princeton.edu in the directory /pub/Graphics.)

Vlab was started as a single-user system but now it is commonly used by many people at the same institution. For the benefit of multi-user sites it is convenient to divide vlab files into 2 classes: global and personal.

The global files are mainly vlab system, simulation and utility programs (see "What is a Virtual Laboratory"), and documentation. It may be also convenient to install the sample database of experiments (oofs) and their hypertext description as a read-only global file accessible as examples by all users (see "Multi-user installation").

These files are all centrally located in the /usr/u/vlab directory (for University of Calgary users). Others need to get the distribution via anonymous ftp.

New users must register before obtaining the distribution via ftp. Registered users may obtain the latest updates to vlab as they become available. Vlab programs for Irix 5.2 are now available as updated binaries, please obtain this update via ftp. (This only includes the binaries for 5.2, new users still need to obtain the rest of the vlab distribution as above, after registration). For installing from the distribution, see the distribution instructions.

Personal files consist of customization files and the individual object hierarchy created by the user. These files must be copied into your account so that you can make changes. To install the personal files, follow the installation instructions.

Installation and startup instructions

Quick startup

 To start using vlab; install it according to the instructions, customize your config.sh file, (see Configuration files and customization ) and type: 

	> cd $VLABPATH
	> GO
This will start a browser using your own oofs file system and starts up the metatext process with a set of simple examples, that use objects from the public oofs filesystem that has been installed. Note: It is important to remember that colour maps have to be loaded in order to display many of the objects.....

Installation for University of Calgary Computer Science users

1) Create a directory under your account to house the personal files and the bin subdirectory for storing the config.sh file. 

   Example:
	
	> mkdir  ~/vlab
	> mkdir  ~/vlab/bin

2) Copy the directories (including contents) from the /home/jungle directories: 

	vlab-local-dist/app-defaults,
	vlab-local-dist/config
into the directory you created in step 1.

Copy the config.sh file from the bin subdirectory. 

  Example:
	
	> cp -r /home/jungle/vlab-local-dist/app-defaults ~/vlab
	> cp -r /home/jungle/vlab-local-dist/config ~/vlab
	> cp  /home/jungle/vlab-local-dist/bin/config.sh  ~/vlab/bin

3) Extract the sample object hierarchy vlab-local-dist/oofs.tar.Z into the directory you created in step 1. 

   Example:
	
	> cd ~/vlab
	> tar xvof  /home/jungle/vlab-local-dist/oofs.tar

4) The file config.sh in your vlab/bin directory needs some minor customization.

Change the first line so that the absolute path name points to your vlab directory (created in step 1). 

   Example:
	
setenv VLABROOT $HOME/vlab
where $HOME contains the pathname of the user's home directory and vlab is the name of the subdirectory created in step 1. (Actually, this is the default line in the config.sh file and needs to be changed only if the user created a subdirectory with a name other than vlab, or placed the directory in a different location.)

Change the second line so that the absolute path name points to the system vlab directory. 

   Example:
	
setenv VLABPATH /home/jungle/vlab-local-dist
(This is the default line in that file currently for local users.)

5) Before your copy of vlab can be used, you must source the config.sh file. In order to do this automatically each time you login, it is best to include an appropriate line in your ~/.cshrc (or similar shell resource file). 

   Example:

source ~/vlab/bin/config.sh
And after including this line, don't forget to type source ~/.cshrc for the change to take effect during the current session.

6) Many aspects of vlab can be customized (see Configuration files and customization ). In particular, the distribution sets the text editors to be vi. If you are unfamiliar with vi, you may want to specify a different editor, such as emacs or jot, before proceeding further. See the documentation on customization of the tools file for the object manager.

7) You can now start up the object browser to experiment with your vlab. Run the program with a command-line argument specifying the location of your object hierarchy (may be a relative path name). 

   Example:

	> browser ~/vlab/oofs

A window will pop up with a hierarchical view of your object hierarchy. See also Quick startup.

Please read the customization section now (see Configuration files and customization).

Single user installation from the ftp distribution

Obtain the distribution via anonymous ftp.

1) Place the file vlab.tar.Z in a temporary directory. 

   Example:

	> mkdir ~/tempvlab
	> cp vlab.tar.Z ~/tempvlab

2) Extract the distribution files into the directory you created in step 1. 

   Example:

        > cd ~/tempvlab
        > zcat vlab.tar.Z | tar xvof -

This will create the vlab file system in this directory. You will also find two additional files in this directory, called readme and makefile.

3) Read the contents of the readme file, for further instructions on how to modify the makefile before completing the installation.

4) Edit the makefile, by changing the appropriate directory names.
Specify VLABDIR: the name of the installation directory where all the vlab files will be located, usually a sub-directory in your home directory for a single user installation (default is $(HOME)/vlab),
specify OOFSDIR: name of the directory for the sample object-oriented file system, this is usually a subdirectory of VLABDIR, but it may be stored someplace else,
specify USERDIR: name of the user directory for private configuration and customization files, (this may be the same as VLABDIR)
specify TARDIR: name of the temporary directory where the vlab.tar.Z file is currently located. 

   Example:
edit the makefile to contain these lines - 
VLABDIR=/home/users/me/vlab
OOFSDIR=$(VLABDIR)/oofs
USERDIR=/home/users/me/vlab
TARDIR=/home/users/me/tempvlab

This means that all vlab files will be stored in /home/users/me/vlab, the private files will be stored in /home/users/me/vlab and the distribution is currently located in /home/users/me/tempvlab.

5) Execute the make process to copy all the files to the specified locations, by typing: 

	> make install

6) Delete the files created in the temporary directory, by typing: 

        > make clean

7) The file config.sh in your vlab/bin directory needs some minor customization.

Change the first line so that the directory path name points to your vlab directory (created in step 5). 

   Example:
	
setenv VLABROOT $HOME/vlab
where $HOME contains the pathname of the user's home directory and vlab is the name of the subdirectory created in step 5. (Actually, this is the default line in the config.sh file and needs to be changed only if the user created a subdirectory with a name other than vlab, or placed the directory in a different location.)

Change the second line so that the directory path name points to the directory where all the vlab system programs are located. 

   Example:
	
setenv VLABPATH $HOME/vlab
(This is the default.)

8) Before your copy of vlab can be used, you must source the config.sh file. In order to do this automatically each time you login, it is best to include an appropriate line in your ~/.cshrc (or similar shell resource file). 

   Example:

source ~/vlab/bin/config.sh
And after including this line, don't forget to type source ~/.cshrc for the change to take effect during the current session.

9) Many aspects of vlab can be customized (see Configuration files and customization ). In particular, the distribution sets the text editors to be vi. If you are unfamiliar with vi, you may want to specify a different editor, such as emacs or jot, before proceeding further. See the documentation on customization of the tools file for the object manager.

10) You can now start up the object browser to experiment with your vlab. Run the program with a command-line argument specifying the location of your object hierarchy (may be a relative path name). 

   Example:

	> browser ~/vlab/oofs

A window will pop up with a hierarchical view of your object hierarchy. See also Quick startup.

Please read the customization section now (see Configuration files and customization).

Multi-user installation from the ftp distribution

If multiple users will access the vlab system programs and documentation, the directories bin, and doc should not be duplicated for each individual, but stored by the System Manager in a central location for all to access.

Obtain the distribution via anonymous ftp.

1) Place the file vlab.tar.Z in a temporary directory. 

   Example:

	> mkdir ~/tempvlab
	> cp vlab.tar.Z ~/tempvlab

2) Extract the distribution files into the directory you created in step 1. 

   Example:

        > cd ~/tempvlab
        > zcat vlab.tar.Z | tar xvof -

This will create the vlab file system in this directory. You will also find two additional files in this directory, called readme and makefile.

3) Read the contents of the readme file, for further instructions on how to modify the makefile before completing the installation.

4) Edit the makefile, by changing the appropriate directory names.
Specify VLABDIR: the name of the installation directory where all the public/shared files will be located for multiple users,
specify OOFSDIR: name of the directory for the sample object-oriented file system, this is usually a subdirectory of VLABDIR, but it may be stored someplace else,
specify USERDIR: name of the user directory for private configuration and customization files,
specify TARDIR: name of the temporary directory where the vlab.tar.Z file is currently located. 

   Example:
edit the makefile to contain these lines - 
VLABDIR=/usr/local/vlab
OOFSDIR=$(VLABDIR)/oofs
USERDIR=/home/users/me/vlab
TARDIR=/home/users/me/tempvlab

This means that shared files will be stored in /usr/local/vlab, the private files will be stored in /home/users/me/vlab and the distribution is currently located in /home/users/me/tempvlab.

5) Execute the make process to copy all the files to the specified locations, by typing: 

	> make install

6) Delete the files created in the temporary directory, by typing: 

        > make clean
7) Create personal directories for each new user. Edit the makefile by changing the directory name of USERDIR and then type 
        > make newuser
This will create the required directories for each user. The process must be repeated for every user.

8) The file config.sh in each user's vlab/bin directory needs some minor customization.

Change the first line so that the directory path name points to the user's vlab directory (created in step 7). 

   Example:
	
setenv VLABROOT $HOME/vlab
where $HOME contains the pathname of the user's home directory and vlab is the name of the subdirectory created in step 7. (Actually, this is the default line in the config.sh file and needs to be changed only if the user created a subdirectory with a name other than vlab, or placed the directory in a different location.)

Change the second line so that the directory path name points to the directory where all the shared vlab system programs are located. 

   Example:
	
setenv VLABPATH /usr/local/vlab

9) Before vlab can be used, the user must source the personal bin/config.sh file. In order to do this automatically each time you login, it is best to include an appropriate line in your ~/.cshrc (or similar shell resource file). 

   Example:

source ~/vlab/bin/config.sh
And after including this line, don't forget to type source ~/.cshrc for the change to take effect during the current session.

10) The vlab configuration files allow individual customization, hence each user will need private copies of files in their own vlab/config and vlab/app-defaults directories. The default files were copied there by the make newuser command. (see Configuration files and customization )

11) We suggest to install the original oofs hierarchy distributed with vlab in a central location where all users can access it in a read-only mode. Individual users should install a personal oofs file system, but make links from their private oofs to the global oofs database. This will make it convenient to access the sample objects and to copy them to the private oofs hierarchy for experimentation.

To install a private oofs directory, follow these steps: (see also the relevant lines in the makefile)

Execute the following commands: 


	setenv VLABROOT $HOME/vlab
	mkdir $VLABROOT/oofs
	cd    $VLABROOT/oofs
	mkdir ext
	cp    $VLABPATH/oofs/* .
	cd    ext
	ln -s $VLABPATH/oofs localoofs
This will create a personal oofs directory and a pointer to the central oofs hierarchy. The pointer is named localoofs in this example.

12) Each user should continue with customization and then start using vlab, see Quick startup.

Configuration files and customization

There are 3 directories which contain configuration files that allow the user to customize the look and feel of the vlab system programs: These files allow the user to change fonts, colors, and various other attributes of the user interface.

The vlab/bin/config.sh file

Vlab system programs rely on certain environment variables for locating configuration files, executables and object files. The config.sh file contains lines which set the required environment variables. A sample config.sh file is listed below (the lines that start with the # symbol are comments, describing the purpose of the variables being set): 
setenv VLABROOT  $HOME/vlab          
##	the root of the personal vlab object hierarchy
##      users may need to create their personal oofs/ directory 
##      see the instructions under "Multi-user installation" 
##      in install.html

setenv VLABPATH  $HOME/vlab          
##      the root of the vlab bin and doc directories, 
##      they may be located in a central location, or they may be 
##      in the user's own vlab directory as in the default case 
##	shown above

setenv VLABBIN   $VLABPATH/bin
##      the directory where all the executable binaries 
##	are located

setenv PATH "$VLABBIN`echo :`$PATH"
##      this adds the bin directory to your search path

setenv VLABDOCDIR $VLABPATH/doc
##	the vlab documentation directory 

setenv VLABOBJECTBIN $VLABBIN/object
##	the location & name of the vlab object manager program

setenv VLABDAEMONBIN $VLABBIN/vlabd
##	the location & name of the vlab daemon program

setenv VLABCONFIGDIR $VLABROOT/config
##	the location of the vlab configuration files

if( "${?XUSERFILESEARCHPATH}" == "0" ) then
  setenv XUSERFILESEARCHPATH "$VLABROOT/app-defaults/%N"
else
  setenv XUSERFILESEARCHPATH \
"$XUSERFILESEARCHPATH`echo :`$VLABROOT/app-defaults/%N"
endif
##	set the directory for the X-windows resource files

The vlab/config directory

This directory contains the following files:

browser
metatext
tools

By convention these file names are in lowercase and are the same as the vlab system program names they relate to, except for tools which is used by the object manager. Each program may have a corresponding configuration file in this directory. Check the documentation of the programs for pertinent information.

Format

Each line contains a keyword, followed by an appropriate value. The keywords are defined by the specific vlab system program they relate to. The parameter names used in configuration files will indicate the function of each parameter.

For example, the browser file contains the line: 

IconSize 50
This means that the icons that will be displayed by the object browser will be 50 pixels in size.

The vlab/app-defaults directory

This directory contains the following files:

Browser
Object
MetaText
XLess

The file names follow the X windows naming convention, hence they are capitalized, and are named the same as the vlab system program they relate to. Each program may have a corresponding X resources file in this directory.

Format

According to the X windows rules for resources files, each line must contain an X resource name, followed by a ":", and then a value for that resource.

For example, the line in browser: 

*background:                          lightGray
defines the background color for all items in the object browser interface (not otherwise set explicitly) to be lightGray.

For further information on X resources, see the online man pages description of editres, and xrdb and the X Toolkit manuals published by the X Consortium.

References

X Window System User's Guide, Volume 3, O'Reilly & Associates, Inc., 1990.

Credits

I. Hernadi, P. Federl - Installation procedures

M. Hammel, I. Hernadi - Installation documentation

Bugs

Contact Information

Please direct all feedback, bug reports, and so on to vlab@cpsc.ucalgary.ca.
Last updated August 30 1996 by Mark Hammel
Table of Contents