RenderMan Toolkit 3.9
Installation Guide

Pixar
January, 2000

Table of Contents

1. Introduction

This document explains how to install the RenderMan Toolkit software for UNIX  and Windows NT based computer systems. The distribution medium is a compact disk containing release files for five supported computer system architectures.

1.1. Hardware supported

This release of the RenderMan Toolkit is supported on the following hardware and operating systems:

This distribution can be installed on any supported workstation with approximately 40 Mbytes of disk space. Also recommended are 32 Mbytes or more of system memory and a full color display.

1.2 Distribution Format

The basic distribution comes as one compact disk (CD). Installation may be performed with a CD that is local to the machine, or which is accessible via a network. Installation varies by distribution.  The SGI distribution can be installed using inst or Software Manager. Windows NT distribution is installed with an InstallShield install script. All other Unix platform distributions are provided in a gzipped tarfile, that can be installed manually, or using a special installation script, rinstall. 

1.3. Format of this Document

The remainder of this document describes the procedure to follow in loading the RenderMan Toolkit software release onto a file system.

Throughout this document, commands you are expected to type are shown in a Bold Courier font, while information that is printed by the system is shown in Courier. Comments are typically shown to the right of a typed command in italics, and surrounded by parentheses. When command line operations are presented, the command interpreter's prompt is shown for reference; e.g.,

2. SGI Installation Procedure

The RenderMan Toolkit CD-ROM includes a distribution in SGI inst format. This distribution can be installed using inst or the SGI Software Manager. The following steps can be used to install from CD-ROM on an SGI computer:
  1. Load the RenderMan Toolkit release CD-ROM into the CD drive.
  2. Log in to the workstation.
  3. Double click on the CD-ROM icon on your desktop.
    The Software manager will automatically start, and load the distribution in /CDROM/dist. If you are not running mediad, you can simply start the Software Manager manually, and then browse the /CDROM/dist directory to locate this distribution.
The distribution scripts will not remove previous RenderMan distributions. If you would like to remove older distributions, please use the Software Manager, or inst program.

This distribution installs into /usr/local/prman.3.9.0.0  and automatically creates a symbolic link /usr/local/prman. If you would like the files to be installed into another location, please create a target directory in this new location, and create a symbolic link from /usr/local/prman.3.9.0.0  to this new directory.

After installing the software, you will still need to install the RenderMan license, and finish other installation details. Please continue with the installation procedure, Installing the License File, below.

3. Windows NT Installation Procedure

The Windows NT distribution is located in the NT folder on the CDROM.  To start installation, run the SETUP.EXE program in this directory. This will bring up a standard InstallShield© installer. The Windows NT default installation will install into the C:\PIXAR\PRMAN directory, although this can be altered by the user. After installation, please take time to view the C:\PIXAR\PRMAN\README.html for specific NT setup instructions.

4. Other Platform Installation Procedure

This section explains the procedure for installing the RenderMan Toolkit release software on your machine. The software is supplied on a single compact disk. The software is configured for installation into the directory /usr/local/prman. If it is placed elsewhere, a symbolic link to the software must be made for /usr/local/prman. (It is possible to set up the renderer to run from another path location. However, we advise that you test it from /usr/local/prman before trying this. See Section 4.6 of this manual and the PhotoRealistic RenderMan User's Manual for details on running the renderer from another path.)

The steps to perform in installing the RenderMan Toolkit release are:

  1. Verify that your machine has the necessary prerequisites for running the PhotoRealistic RenderMan software.
  2. Load the release software onto the machine.
  3. Install the software license and run the license server.
  4. Verify the installation procedure by running the setup confidence tests.

Note that these procedures are needed only when a system is first installed; procedures for normal system operation are described in the PhotoRealistic RenderMan User's Manual.

4.1. Setup Prerequisites

The computer system should be configured with a current version of native Unix operating system. Compatibility between operating system releases is up to the computer system vendor. For reference, the 3.9 distribution has been built under these operating system releases:

The system should be equipped with an appropriate CD-ROM drive or have network access to a system with such a drive.

You should have a copy of the PhotoRealistic RenderMan encrypted license file information. This will be required for the installation of the Flexible License Manager which is used to control access to the renderer. The encrypted license file information maybe provided as a hardcopy document in the RenderMan Toolkit release package, a hardcopy faxed to you by Pixar or a file sent to you via electronic mail from Pixar.

The RenderMan Toolkit release as distributed is configured to support image output to:

See the document PhotoRealistic RenderMan Display Driver Guide for information on how to add other output drivers to the system.

4.2. Loading the Software

Although root (or super-user) permissions may be required in order to create the installation directory, we recommend that the rest of the installation be performed under a user-id other than that of the root. Actually installing the software while logged in as root may leave the files with undesired ownership and permissions.

On a system with a local CD-ROM drive, the software can be loaded onto disk as follows:

  1. Load the RenderMan Toolkit release CD-ROM into the CD drive.
  2. Log in to the workstation.
  3. Make a directory for the release:

        prompt%     mkdir /usr/local/prman (creates the installation directory)
     
  4. Change to the installation directory:

        prompt%     cd CDrom-directory/unix
     
  5. Run the installation script:

        prompt%     ./rinstall
     
  6. Answer the questions.
  7. Install the license information.

Remember that if you extracted the software into a location other than /usr/local/prman, then you must create a symbolic link for /usr/local/prman that points to this location; e.g.

(Note that the symbolic link may have to be made as root depending on the permissions set for the /usr/local directory.)

If the installation target has no CD drive, the best approach is to place the distribution CD-ROM into a CD drive available on the network and use the Network File System (NFS) to enable the installation. One could export the CD-ROM file system to the target machine and run the rinstall script there. Alternately, one could use NFS to mount the target file system onto the computer system with the CD drive and run the rinstall script there.

4.3. Software License Installation

PhotoRealistic RenderMan 3.9 is distributed for use in a network environment. The License Manager Software requires that one (or more) machines in your network operate as a license server. License servers regulate user requests for the software. A license file is provided when you receive PhotoRealistic RenderMan 3.9 that contains encrypted information detailing the machines authorized as license servers, the number of copies of PhotoRealistic RenderMan 3.9 that may be executing simultaneously and the expiration date of the license. The License Manager Software and license file must be properly installed in order for PhotoRealistic RenderMan 3.9 to function properly. The instructions in this section describe how to configure the License Manager Software.

If you are upgrading from a previous release of PhotoRealistic RenderMan, your old license file will not work with PhotoRealistic RenderMan 3.9. You must install the new license file sent to you with PhotoRealistic RenderMan 3.9. The new license for release 3.9 can, however, be used by previous releases of the software. Note also that the License Manager Software that comes with PhotoRealistic RenderMan 3.9 should not be run on a single host simultaneously with the License Manager Software from previous releases.

Globetrotter's on-line documentation provides more complete information regarding the License Manager Software, including installing multiple server configurations, reserving copies of PhotoRealistic RenderMan 3.9 for individuals or machines, and obtaining statistics regarding requested usage patterns of PhotoRealistic RenderMan 3.9.

If you have existing applications installed on your network that employ the Flexible License Manager, you should skip the next two subsections and proceed directly to Section 4.3.3.

4.3.1. Installing the License File

The configuration of the License Manager is provided by a license file, license.dat, that resides in the directory /usr/local/prman/etc. The license file will contain SERVER lines for each host designated as a license server.

Locate the PhotoRealistic RenderMan 3.9 encrypted license file information. You will need to edit the sample license file provided as part of the release (/usr/local/prman/etc/license.dat) replacing the existing information with your site-specific data provided by the encrypted license file information. The license file should normally be protected from write accesses to avoid accidental overwrites. Before editing the license file you must unprotect it by typing:

Be sure to set the protection back when you are done:

The SERVER line should be replaced with the SERVER line(s) from the encrypted license file information, and the FEATURE line replaced with the new FEATURE line.

If you have a copy of the PhotoRealistic RenderMan encrypted license file information in machine-readable form, simply copy the file into /usr/local/prman/etc/license.dat.

4.3.2. Running the License Manager

You should now start a license server daemon. The license server daemon can be started on a host by using the script /usr/local/prman/etc/startlm.sh. The script may be invoked interactively by any user or from the system startup. The license manager needs no special privileges to run.

For most systems a file of the form:

can be placed into the directory: /etc/rc2.d for SGI and SUN, /sbin/rc2.d for DEC, using a file name such as S99startlm.

The license server daemon must be up and running on a majority of the license server hosts in order for the renderer to run.

4.3.3. Systems with No Network

If the machine is not connected to a network, be sure that the hostname from the SERVER line also appears in the /etc/hosts file on the same line with the localhost address of 127.0.0.1

4.3.4. Previously Installed Flexible License Manager Software

It is possible that you have existing, previously installed applications that employ the Flexible License Manager. If so, you should already have a common license.dat file and you are probably already running a license manager daemon. If this is the case you should:
  1. add your site-specific SERVER and FEATURE lines from the PhotoRealistic RenderMan 3.9 encrypted information file to the common license.dat file (usually located in /usr/local/license.dat),
  2. add the Pixar DAEMON line from the sample license file in /usr/local/prman/etc/license.dat to the common license.dat file,
  3. move the sample license file to a safe area

        prompt% cd /usr/local/prman/etc
        prompt% mv license.dat license.dat.save
  4. copy the common license file to the /usr/local/prman/etc directory:

        prompt% cp /usr/local/license.dat license.dat

NOTE: The RenderMan 3.9 distribution MUST use the included pixard daemon.  If you are merging products into a common area, you must either copy the pixard daemon from the 3.9 distribution to your common area, or the DAEMON line must explicitly point to the new pixard in the 3.9 distribution directory.

4.4. Running the Confidence Test

To verify the installation procedure has been performed properly the setup confidence test should be run. This test renders a 128 by 96 image of a blue teapot with a matte surface and a logo texture-mapped onto the front. The calculated image is then compared against a precomputed version of the same image as a consistency test. Note that since floating point calculations vary between hardware environments, this comparison may not be exact. Thus the comparison may be treated as successful even if there are minor differences between the images.

To run the confidence test do the following:

If everything goes well you will see the following printed out: If the comparison failed, the cmptiff program will print the following: In this case, if possible, the generated image should be examined on a display device to judge its correctness.

4.5. Setting up for Use of PhotoRealistic RenderMan

In order to use the PhotoRealistic RenderMan software, users should add /usr/local/prman/bin to their path environment variable.

To start the Network RenderMan server execute the following commands:

The Network RenderMan server may be started interactively by any user. It can also be started automatically at system boot time in the same manner as the license manager startup, see section 4.3.2 above.

4.6 Installing Onto a Different Path

If for some reason it is important to install this software somewhere other than on /usr/local/prman, and a symbolic link is not sufficient, it can be installed on an arbitrary location and referenced using the RMANTREE environment variable. This might occur, for example, in upgrade situations, where both the previous release and this release need to be on-line simultaneously.

In this situation, set the environment variable RMANTREE to be the new location. For example (using the C shell):

Then all references to /usr/local/prman throughout this manual and other manuals may be assumed to refer instead to the value of RMANTREE. All users of the software must similarly set their path variables and the RMANTREE environment variable (usually in their shell startup script, .login for the C shell and .profile for the Bourne shell). Refer to the PhotoRealistic RenderMan User's Manual for details about running the PhotoRealistic RenderMan software.

5. License Manager Software

PhotoRealistic RenderMan uses Globetrotter Software's Flexible License Manager® (FlexLM) to accomplish software protection in the Unix® environment. The software protection system regulates use according to the number of licenses available for simultaneous use and the expiration date of the licenses. Use can be further regulated by the system administrator to reserve licenses for specific users or specific computer systems.

The rendering system consults a license file and communicates with a license server to insure that the site has the proper license to run the software. The license server need not run on the same computer system as the renderer, as long as it can be reached through the network. To protect users from system crashes and downtime on the computer system running the license server, copies of the license server can be running on 3 computer systems. As long as a majority of the license servers remain running, users have access to the licensed software.

The FlexLM End User Manual provided by Globetrotter Software is provided in this package for reference. Some RenderMan Toolkit specific configuration details are:

Further information about FlexLM is available direct from Globetrotter Software.
Copyright © 2000 Pixar. All rights reserved. RenderMan® is a registered trademark of Pixar.
Pixar Animation Studios, 1001 West Cutting Blvd., Richmond, CA 94804
(510) 236-4000 (voice) (510) 236-0388 (fax)