Volume II ------ -- Khoros Programmer's Manual ------ ---------- - ------ Chapter 10 INSTALLATION GUIDE Installation Guide for the Khoros System Primary Author(s): John Rasure ---- ------ c Copyright 1992 University of New Mexico. All rights reserved. Printed: March 16, 1992 Volume II - Programmer's Manualr 10 - Installation Guide ------ -- - ------------ ------ CONTENTS Chapter 10 - INSTALLATION GUIDE A. INTRODUCTION ...................................... 1 A.1 PREREQUISITES .............................. 1 A.2 OTHER DOCUMENTATION ........................ 2 A.3 SUPPORT AND MAINTENANCE .................... 3 A.4 COMMON PROBLEMS ............................ 3 B. KHOROS VIA FTP DISTRIBUTION ....................... 4 B.1 ACQUIRE TAR FILES .......................... 4 B.2 COMMON PROBLEMS IN ACQUIRING THE SYSTEM .... 5 B.3 UNTAR THE FILES ............................ 6 B.4 COMMON PROBLEMS IN UNTARRING FILES ......... 7 C. KHOROS VIA TAPE DISTRIBUTION ...................... 7 C.1 EXTRACTING KHOROS FROM TAPE ................ 7 D. CONFIGURING YOUR ENVIRONMENT ...................... 7 E. COMPILING KHOROS ............................ 8 E.1 CONFIGURING THE IMAKE SYSTEM .......... 9 E.1.1 Commonly Asked Questions About Configuring Imake ..................................... 9 E.2 STARTING THE COMPILE ....................... 11 E.3 COMMON PROBLEMS WITH COMPILING ............. 12 F. INSTALLING TOOLBOXES .............................. 12 G. GETTING STARTED ................................... 13 KHOROS Release: 1.0 10 - i Volume II - Programmer's Manualr 10 - Installation Guide ------ -- - ------------ ------ INSTALLATION GUIDE A. INTRODUCTION - ------------ Welcome to Khoros 1.0 (Patch 5)! This document con- tains the information that you need to load and install the Khoros software onto your system. Both source and binaries are available via anonymous ftp or by ordering a tape and printed documentation. The installation procedure outline follows: Step 1) ftp from pprg.eece.unm.edu or order and receive a tape Step 2) untar the source and/or binary files in KHOROS HOME - Step 3) set up your user environment Step 4) if you did NOT install binaries and want to compile, run installit Step 5) read Volume 1, Chapter 1 of the Khoros manual and try Khoros out! A.1 PREREQUISITES If you are going to use the binaries provided (sun4, sgi, or dec mips), then the prerequisite is to have some version of the the X windows system and about 40 Megabytes of disk space plus the amount of space needed for binaries (see table below). The following list of prerequisites is for those that plan on compiling the system. + X11R4 or X11R5 from MIT with current patches. You need X11R4 or X11R5 libraries (client libraries, X11, Xaw, --- --- Xt, Xmu and Xext) to compile Khoros; however once -- --- ---- Khoros is compiled, it will run with an X11R3 server. Both X11R4 and X11R5 are available via Anonymous FTP from "export.lcs.mit.edu". + A C compiler + A Fortran compiler is recommended (not all of Khoros will be available without a Fortran compiler) KHOROS Release: 1.0 10 - 1 Volume II - Programmer's Manualr 10 - Installation Guide ------ -- - ------------ ------ + The compress program (available via Anonymous FTP from "pprg.eece.unm.edu"). + About 65 Megabytes of disk space plus room for objects, libraries and binaries (see table below) ------------------------------------------------------------ |Khoros 1.0 Binaries Are Available for These Architectures || ++----------------------------------------------------------|| Vendor |Name OS |.o's and lib|Binaries (Meg) || || -------+----------+-------------+------------+-------------- DEC 5000/3100 Ultrix 4.1 37 66|| | | | | SUN sparc SUN OS 4.1.1 21 63|| | | | | SGI Indigo OS 4.0 36 70|| || | | | | || ------------------------------------------------------------ A.2 OTHER DOCUMENTATION If you are unsure about the installation of Khoros and need additional information, the following documents may be of help: khoros This is a four page overview of Khoros. If you are not sure what Khoros is and what it can do, read this document to get a better overview than the one provided in the announcement. This file is located in $KHOROS HOME/release. - chapter1 Volume I, Chapter 1 of the Khoros User's manual provides general information for the Khoros user. This should be considered required reading. chapter9 Volume II, Chapter 9 of the Khoros Programmer's Manual provides a detailed description of the source configuration and imake system used by Khoros. This will be helpful to those who are porting the software to other architectures or are having trouble with compiling. appendixB Volume II, Appendix C of the Khoros Programmer's Manual provides a detailed description of the imake system symbols and rules. This document is helpful when modifying the Khoros imake system. announce This is the announcement of the Khoros 1.0 release. It provides a brief overview of Khoros and ordering information. This file is located in $KHOROS HOME/release. - This document, install, and the documents listed above are available in both postscript and plain text form on pprg.eece.unm.edu in the directory pub/khoros/release or in your copy of Khoros in $KHOROS HOME/release. A *.ftp - indicates that it is a plain text file, a *.ps indicates KHOROS Release: 1.0 10 - 2 Volume II - Programmer's Manualr 10 - Installation Guide ------ -- - ------------ ------ postscript (ready to print), and a *.ms indicates that it is the source "roff" file. Instructions on how to obtain these files is provided below. A.3 SUPPORT AND MAINTENANCE Even though many users of Khoros have said that it is quality software, Khoros 1.0 is not a commercial product. Support is provided via an e-mail users group (khoros@chama.eece.unm.edu), a USENET news group comp.soft- sys.khoros, and periodic updates. To join the Khoros mailing list, mail to khoros-request@chama.eece.unm.edu. To report bugs, mail to khoros-bugs@chama.eece.unm.edu. Please use the bug report form found in $KHOROS HOME/repos/BugReport as - a template for reporting bugs. There are several companies that are likely to be selling Khoros support in the near future. Please inquire if you are interested. A.4 COMMON PROBLEMS Khoros 1.0 is a large system, and often an end user only wants part of its functionality. This often leads to complaints about the system requirements. The only solution to this problem now is to obtain Khoros as it is, install it, and then delete the components of the system that you do not want. The minimum set of directories that you need to run Khoros are: bin contains executables repos User Interface Specification files, architecture- specific configuration files You may also want to keep: doc Online help man man pages used by vman manual contents of printed manual release starter documentation data example data You do not need the following for only a "runable" Khoros system: src needed for compiling lib needed for compiling include needed for compiling KHOROS Release: 1.0 10 - 3 Volume II - Programmer's Manualr 10 - Installation Guide ------ -- - ------------ ------ B. KHOROS VIA FTP DISTRIBUTION - ------ --- --- ------------ First you must determine where on your system that you want to install Khoros and then create a directory (any name is fine). This can be done by creating a user named "khoros", or simply by creating a home directory such as /usr/local/khoros or /usr/khoros. B.1 ACQUIRE TAR FILES Move to the directory that you just created and then execute the following commands to acquire the Khoros compressed TAR files. a. Use ftp to connect to pprg.eece.unm.edu. % ftp pprg.eece.unm.edu -or- % ftp 129.24.24.10 b. Use "anonymous" or "ftp" as the user name. Name (pprg.eece.unm.edu:login): anonymous -or- Name (pprg.eece.unm.edu:login): ftp c. Use your e-mail address as the password; please use a valid e-mail address, as this ftp site logs all anonymous ftp's. Password (pprg.eece.unm.edu:user): {your valid e- mail address} 331 Anonymous login ok, use your E-MAIL address as the password. 230 Guest login ok, access restrictions apply. d. Get the installation guide (this file, called install.ftp) for acquiring Khoros via anonymous ftp. (note that "install.ftp" is the plain text file - both ".ms" and ".ps" files are available for those who would like them). ftp> cd /pub/khoros/release ftp> get install.ftp e. Set the ftp program to binary mode. ftp> bin f. The next step is to actually get the Khoros TAR files. The compressed TAR files are located in KHOROS Release: 1.0 10 - 4 Volume II - Programmer's Manualr 10 - Installation Guide ------ -- - ------------ ------ four separate directories: bins (sun4, sgi, decmips), system, source and data. Within each of these directories, you will find both the compressed TAR file and a set of "split" files created from that TAR file. You can have a functional Khoros system without the data and system directories, in other words, a minimal system can be installed with only system and bins. To get the system directory: ftp> cd system ftp> get system.tar.Z The system.tar.Z has been split into many different files; if you have trouble getting the system.tar.Z file, you may try getting each of the split files individually. To use this method, substitute the previous commands with: ftp> prompt ftp> mget system.[0-9]* g. In the above steps, you acquired the "foundation" (doc, dotfiles, repos, man, manual, release) of the Khoros system. In order to get bins, source (src and include) and data, go to that directory on pprg.eece.unm.edu and follow the same basic steps as above. A minimal system can be created by only obtaining the system and bins directories. B.2 COMMON PROBLEMS IN ACQUIRING THE SYSTEM It is not uncommon for the files to be corrupted during ftp transfer. To verify that you have good files, use the *.listing file found in each directory of pprg along with the TAR files. Check to see that the calculated checksums match. For example, if you got the system.tar.Z file, this procedure will be simple. First, get the "system.listing" file from pprg.eece.unm.edu, in /pub/khoros/system, if you have not already done so. Then, run: % sum system.tar.Z The output of the sum program should match the statistic --- given for system.tar.Z, at the top of the system.listing file. If it does not match, this indicates that the TAR file has been corrupted. If the TAR file has been corrupted, you may want to re-acquire the system as detailed in the previous section. Or, you can find out which files are bad by executing: KHOROS Release: 1.0 10 - 5 Volume II - Programmer's Manualr 10 - Installation Guide ------ -- - ------------ ------ % zcat system.tar.z | tar tvf - > my system.listing - Now, execute: % diff system.listing my system.listing - This will list the differences between the two files. Of course, the first ~30 lines will differ, as our system.listing file has additional checksum information at the beginning; however, if any other lines in the listing differ, look at the filenames listed on the lines that differ. This will indicate which files were corrupted. If you got the split files, it is best to write a small "foreach" script to perform the checking procedure for you. B.3 UNTAR THE FILES You have already created a "home" directory for the TAR files, now you must set the environment variable KHOROS HOME. It should be set to the home directory that - you created above. For instance, if you created a home directory /usr/khoros, % setenv KHOROS HOME /usr/khoros - or % setenv KHOROS HOME ~khoros - if you set up a user name for Khoros. All of the TAR files should be untarred in the KHOROS HOME - directory. (In the case of untarring binaries for more than one architecture, you may want to create a binmach directory and untar the bins into different subdirectories.) To untar the system.tar.Z file, use the following commands: % cd $KHOROS HOME - % zcat system.tar.Z | tar -xfoB - -OR- % uncompress -c system.tar.Z | tar -xfoB - If you transferred the split files instead of the system.tar.Z file, you will need to do: % cd $KHOROS HOME - % cat system.[0-9]* | uncompress > system.tar % tar -xf system.tar Alternatively, you may use (WARNING: this is not as reliable and doesn't seem to work on bindecmips): KHOROS Release: 1.0 10 - 6 Volume II - Programmer's Manualr 10 - Installation Guide ------ -- - ------------ ------ % zcat system.[0-9]* | tar -xfoB - -OR- % uncompress -c system.[0-9]* | tar -xfoB - You should follow the same basic procedure for the data, source and bins TAR files. After you untar the compressed TAR file, you may want to remove the TAR file to save space. B.4 COMMON PROBLEMS IN UNTARRING FILES Be sure that you have not run out of disk space by using the %df . command. If you run out of disk space during the untarring procedure, the untarred Khoros system will be corrupted. Delete the untarred Khoros system, and free up some extra space before starting the untarring procedure again. Often, an uncompressed TAR file gets left around after it is successfully untarred; delete it to free up additional space. C. KHOROS VIA TAPE DISTRIBUTION - ------ --- ---- ------------ First you must determine where on your system that you want to install Khoros and then create a directory (any name is fine). This can be done by creating a user named "khoros", or simply by creating a home directory such as /usr/local/khoros or /usr/khoros. The tape distribution includes tape(s) with Khoros source and binaries (if ordered), Volume one and two of the Khoros manual and installation instructions for extracting Khoros from the tape(s). C.1 EXTRACTING KHOROS FROM TAPE Your tape distribution should include instructions on how to extract Khoros from the tape(s). If you have problems with extracting Khoros off the tape(s), please contact us. Note, make sure you move to the directory that you just created before extracting Khoros from tape. If you did not receive binaries or want to compile Khoros on another architecture, follow the instructions below for compiling Khoros. D. CONFIGURING YOUR ENVIRONMENT - ----------- ---- ----------- You will need to set up your user environment so that Khoros applications will run properly. The files of concern are: .cshrc or .login, .khoros env and .Xdefaults. If you - KHOROS Release: 1.0 10 - 7 Volume II - Programmer's Manualr 10 - Installation Guide ------ -- - ------------ ------ need more details than what is provided below, please read Chapter 1, Volume 1 on "Getting Started" with Khoros. Provided with the release is a directory called "dotfiles" that provides templates or examples for the files mentioned below. .cshrc Modify your ".cshrc" or ".login" file to include a path to $KHOROS HOME/bin. The ".cshrc" or - ".login" file should source .khoros env. - .khoros env The environment variables used by Khoros are set - in the .khoros env file. Use the file - $KHOROS HOME/dotfiles/khoros env as a template. - - % cp dotfiles/khoros env .khoros env - - .Xdefaults Use the one provided to start with; it is in $KHOROS HOME/dotfiles/Xdefaults. - % cp dotfiles/Xdefaults .Xdefaults As a note, Khoros was developed using primarily the twm window manager which is distributed with X11R4. To test out your new environment, execute the following commands: % source .cshrc % xrdb .Xdefaults If you have obtained and untarred binaries, you can skip the following section on compiling Khoros. However, it is very important that you execute the following program to configure the man pages for your site: % $KHOROS HOME/man/utils/tmac/customize - If you forget to run the customize program, the vman command --------- will not work, and you will not have access to the Khoros man pages. E. COMPILING KHOROS - --------- ------ If you have all of the prerequisites as stated above, and you are compiling for one of the platforms listed above, the configuration should be quite simple. However, if you are compiling for a new (unsupported) architecture or want to support multiple architectures, you should read $KHOROS HOME/release/chapter9 and use - $KHOROS HOME/release/appendixB as a reference for imake - KHOROS Release: 1.0 10 - 8 Volume II - Programmer's Manualr 10 - Installation Guide ------ -- - ------------ ------ changes. You should be most concerned with configuring the Khoros imake system correctly. If you received a printed manual consult Volume II, Chapter 9 and Appendix B. E.1 CONFIGURING THE IMAKE SYSTEM Before starting the compile, the imake configuration files in $KHOROS HOME/repos/config/imake conf must be - - modified. The files that need special attention are: platform.cf, where platform is the name of the architecture -------- -- -------- (i.e. for a Sun use sun.cf, for a DecMips use ultrix.cf, etc) and Site.def. The symbol defines in these files need to be set according to how you want to compile Khoros. For example, if your system does not have a Fortran compiler, the symbol "HasFortran" in the platform.cf file must be set -------- -- to "NO". We have tried to tailor the imake configuration files so that very little effort is needed to compile Khoros, however, it is important that you check these files for correctness. While the imake configuration files such as platform.cf and Site.def are fairly well commented, more -------- -- ---- --- information can be found in Chapter 9 and Appendix B. Once the imake configuration files have been modified, you are ready to compile Khoros. E.1.1 Commonly Asked Questions About Configuring Imake Below are a few commonly asked questions about the imake configuration files. If you need to use any of the following symbols or any other imake symbol, we suggest that the symbol defines are put in the platform.cf file. -------- -- Q: X11 directories are not in the "standard" place on my machine, how do I specify where the X11 directories exist? A: define the symbol "XLibDir" to the directory where the X11 libraries exist #define XLibDir /usr/local/lib/X11 define the symbol "XIncludes" to the directory where the X11 include directory exists. #define XIncludes -I/usr/local/include Q: Fortran libraries are in /usr/lang rather than in /usr/lib, how do I change where to look for Fortran libraries? A: define the symbol "FortranLibDir" to the directory KHOROS Release: 1.0 10 - 9 Volume II - Programmer's Manualr 10 - Installation Guide ------ -- - ------------ ------ where the Fortran libraries exist #define FortranLibDir /usr/lang Q: I need to add some other libraries to compile against, how do I add these extra libraries? A: define the symbol "ExtraLibs" to the directory where the libraries exist #define ExtraLibs /myhome/foobar Q: How do I make the libraries load with a different option than the C programs load with? A: define the symbol "LibraryLdCmd" to the command that you want the libraries to load with and the "LdCmd" to the command that you want the C programs to load with. #define LibraryLdCmd ld #define LdCmd cc Q: How do I specify different compile options for libraries and C programs. A: define the symbol "LibraryCCOptions" to the options that you want the libraries to compile with and the "DefaultCCOptions" to the options that you want the C programs to compile with. #define LibraryCCOptions -q -P #define DefaultCCOptions -float Q: How do I specify different compile options for Fortran libraries and Fortran object files. A: define the symbol "LibraryFCOptions" to the options that you want the libraries or other Fortran object files to compile with. #define LibraryFCOptions -O Q: I can not regenerate the Khoros manual on a Sun Workstation because soelim for .so lines in the roff files, limits the file length to 64 characters. A: This is a bug and has been reported to Sun, but not expected to be fixed until the release after 4.1.2 (maybe). We are distributing a public domain version of the soelim program. If you think or know that your OS has this problem, then make sure you have the following symbol set to YES. KHOROS Release: 1.0 10 - 10 Volume II - Programmer's Manualr 10 - Installation Guide ------ -- - ------------ ------ #define SoeLim YES Q: Can I compile Khoros and utilize shared libraries. A: As of Patch 5 we are only supporting Sun shared libraries. We have the mechanisms in place for other architectures, but have not verified the shared rules. If you want to compile the Sun with Shared Libraries then set the symbol "HasSharedLibraries" to YES. #define HasSharedLibraries YES If you want to port Khoros to use shared libraries on your architecture, you should model it after the the Sun version. You will have to either modify or create a library rules file in the $KHOROS HOME/repos/config/imake conf/Lib. - - Although many more questions about configuring the imake system have been asked, this set of questions and answers should give one the feel of how to make changes to the imake configuration files. It is strongly suggested that the document Volume 2, Appendix B, "Imake Symbols and Variables" be consulted when making changes to the imake symbols. E.2 STARTING THE COMPILE The installit program in $KHOROS HOME/src will prompt - you for some default directories and startup flags. The installit program will modify the imake Site.def file to ---- --- include the correct location for Khoros binary, library and include directories. To compile Khoros, execute the following commands: % cd $KHOROS HOME/src - % ./installit If you would like to watch the compile, you can execute: % tail -f make.World Note that if you use the "tail" command to watch the Khoros system compile, you will have to "^C" out of it when the compile has been completed. The compile will take several hours. Some typical times are listed below. SparcStation 1 5 hours (src mounted on NFS partition) Sun3/260 4.6 hours (using gcc on NFS partition) Vax 3500 4.4 hours (using cc on NFS partition) KHOROS Release: 1.0 10 - 11 Volume II - Programmer's Manualr 10 - Installation Guide ------ -- - ------------ ------ DecStation 5000 3.33 hours (local disk) SGI Indigo 2.00 hours (local disk) E.3 COMMON PROBLEMS WITH COMPILING Again, the most common problems is that you run out of disk space or NFS will time out during the compile. If this happens, you should: % cd $KHOROS HOME/src - % make allclean; installit The reason that you need to "clean" the system is because of the possibility of corrupted .o's and libs. It is not unusual to have a system failure (NFS dies, machine crashes, etc) during the compile. Follow the same instructions as above. If the "installit" fails due to compile errors, please verify that you have configured the imake system files located in $KHOROS HOME/repos/config/imake conf correctly. - - Consult Volume II, Chapter 9 for assistance. F. INSTALLING TOOLBOXES - ---------- --------- This section discusses how to install a toolbox that was created by another person or was developed on another machine, and is being set up on a new machine. Note, It is assumed that Khoros is already installed at this point. The following steps must be followed in order to update the configuration files for the new directory and machine. 1. Set the environment variable KHOROS TOOLBOX to your - toolbox file. To do this type the following command. % setenv KHOROS TOOLBOX {Pathname to Toolbox file} - 2. Find a location for your toolbox, and create the directory. If you received Khoros via tape distribution, then follow the installation instructions you received with your order. Otherwise, If you aquired the toolbox via ftp, the file will be in tar format. To untar the toolbox, use the following command: % tar -xf {toolbox tar filename} Make sure you cd to the directory you want to unpack it to, before typing the untar command. KHOROS Release: 1.0 10 - 12 Volume II - Programmer's Manualr 10 - Installation Guide ------ -- - ------------ ------ 3. For the rest of this discussion, {top dir} will refer to the directory that contains the top level of your toolbox. Modify the {top dir}/repos/config/src conf/{toolbox} mf file. Look for - - the KHOROS USER tag inside the file, and substitute - your user name for one that is already there. Use \pwd in the toolbox/src directory to get the absolute path, and replace the path assigned to the LOCAL SRC TOP tag - - with this new path. 4. Run kraftsman to add the toolbox entry to your toolbox file. (See the help page on "ADD TOOLBOX" option on the "Creation" pane in kraftsman, or check in Volume 2, Chapter 11 for information on how to add a toolbox to your toolbox file.) 5. After adding the toolbox entry to your toolbox file, go to the "Configuration" pane, and make sure that both the Binary Path and Library Path are correct. (See the configure toolbox documentation in Volume 2, Chapter 11.) Once you have set these paths correctly, you may exit kraftsman. The rest of the instructions explain how to build and install all the routines in the newly installed toolbox. 6. execute: % cd {top dir}/src 7. execute: % make Makefile Makefiles 8. execute: % make install Finally, you will need to add {top dir}/bin to your path so that you will be able to execute the routines. You may want to do this in your ".cshrc" file, so that you will not have to remember to set the path every time you log in. G. GETTING STARTED - ------- ------- Now that you have Khoros installed, you will want to use the manual printing utility, prnmanual, to print out Volume 1, Chapter 1, "Getting Started", and other documents. If you received a printed copy of the manual, there is no need to reprint any of the manual. Questions, comments, constructive criticism can be mailed to the Khoros E-Mail Users Group, KHOROS Release: 1.0 10 - 13 Volume II - Programmer's Manualr 10 - Installation Guide ------ -- - ------------ ------ khoros@chama.eece.unm.edu, or the Khoros USENET news group, comp.soft-sys.khoros. To join the e-mail group, mail to khoros-request@chama.eece.unm.edu. PLEASE: only requests to ------ get on or off the Khoros mailing list should go to this address. Other mail is very likely to get lost or be deleted. Once you are a member of the Khoros Users Group, you may mail any questions that are not addressed in the Khoros Manuals to khoros@chama.eece.unm.edu. If a member of the Khoros group itself cannot answer your question immediately, it is likely that another Khoros user may be able to. As with any system approaching the size of the Khoros system, you can expect to find some bugs. We already are aware of several bugs; these can be found in $KHOROS HOME/repos/BugList. If you find a bug in the Khoros - system, please look through this file first to see if it is one of the bugs that we already have on our list. We strongly encourage you to report any bugs that you may find -------- that are not listed in the BugList. All bugs are to be reported via email, to khoros-bugs@chama.eece.unm.edu. When ----- ---- reporting bugs, please include the version of Khoros --------- ---- ------ ------- --- ------- -- ------ (located in the file $KHOROS HOME/src/Patchlevel), the ------- -- --- ---- ----------- --- ---------- --- machine type (execute: uname -a), and how the bug can be ------- ---- ------- ----- - --- --- --- --- --- -- duplicated. You can send us Cantata Workspaces and/or ---------- --- --- ---- -- ------- ---------- --- -- Journal Playback files. ------- -------- ----- We hope that you like the Khoros system! KHOROS Release: 1.0 10 - 14