Appendix A. Troubleshooting Guide

Solving Technical Difficulties

If you encounter technical difficulties, please follow these steps:

  1. Read through this Installation Guide completely.
  2. Read the FAQs on KRI's web site at http://www.khoral.com/ or on KRI's anonymous FTP site at ftp.khoral.com in the file /pub/khoros/FAQ/k2_compile_FAQ
  3. Read and post messages on the Khoros Usenet Newsgroup, comp.soft-sys.khoros or access this newsgroup using email by sending your questions to khoros@khoral.com.
  4. Email KRI's technical support services at support@khoral.com,
    fax us at (505)881-3842, or telephone us at (505)837-6500.

Other specific problems are dealt with in the following sections.

Common problems with Running kbuild

The most common problem is running out of disk space or NFS timing out during the compile. If this happens, correct the problems, and follow the steps below:


> cd <Khoros Installation Directory>/bootstrap/objects
> make clean
> cd <Khoros Installation Directory>
> ./bin/kbuild


Note: bootstrap in these examples should be replaced by all toolbox names, or at least the name of the last toolbox where compiles failed.

The reason that you need to clean the system is because of the possibility of corrupted object and library files.

It is not unusual to have a system failure (NFS dies, machine crashes, etc) during the compile. If this happens, follow the same instructions as above.

If kbuild fails due to compile errors, please verify that you have configured the kgenmake system files located in <Khoros Installation Directory>/bootstrap/config correctly.

The Khoros Compile FAQ

This collection of commonly encountered problems is available on the Khoros Web site at: http://www.khoral.com/ and on KRI's FTP site at ftp.khoral.com, in the file: /pub/khoros/FAQ/k2-compile-FAQ

System Requirements

Checking Hardware Requirements

If the commands listed below do not work for you, please consult your system documentation, your vendor, or your system administrator.

Checking Computer System Hardware

The requirements below refer to the disk(s) on which you install and the computer(s) on which you run Advanced Khoros software.


     Checking Computer System Hardware Requirements for Advanced Khoros        

Hardware Resource                    Command to Check Hardware Resource   

CPU                                  uname -m, uname -p, or uname -a      

RAM                                                                       

Sun (Solaris 2.x/SunOS 5.x)          /etc/dmesg | grep -i mem             

Sun (Solaris 1.x/SunOS 4.x)          /bin/dmesg | grep -i mem             

SGI (IRIX)                           /sbin/hinv | grep -i mem             

DEC Alpha (Digital UNIX/OSF1)        restart computer; watch startup      
                                     messages                             

PC (Linux)                           /bin/dmesg | grep -i mem             

IBM RS/6000 (AIX)                    /usr/sbin/lscfg | grep -i mem        

Swap Space                                                                

Sun (Solaris 2.x/SunOS 5.x           /etc/swap -l                         

Sun (Solaris 1.x/SunOS 4.x)          /etc/pstat -s                        

SGI (IRIX)                           /sbin/swap -l                        

DEC Alpha (Digital UNIX/OSF1)        /usr/sbin/swapon -s                  

PC (Linux):                          /usr/bin/vmstat                      

IBM RS/6000 (AIX):                   /usr/bin/vmstat                      

Temp. Space (e.g. /usr/tmp)          /bin/df /usr                         

Disk Space to Install Application    /bin/df                              
Environment                                                               

Disk Space to Install Development    /bin/df                              
Environment                                                               

Disk Space per Application User      /bin/df                              

Disk Space per Developer             /bin/df                              



Checking Display System Hardware

The requirements below refer to the computer running your X Window System server (or to your X terminal) on which you display Advanced Khoros software. In the case of workstations, this may often be the same computer that you use to run Advanced Khoros. Note: <display name> can be the empty string if you are displaying and running on the same computer; otherwise it is the system (host) name or the IP number of the machine whose display you wish to check. Also note: if you are checking a remote display, the computer you are running the xdpyinfo command on must be authorized to connect to that display (often by using the xhost command on the remote display). See your system documentation for further details.


      Checking Display System Hardware Requirements for Advanced Khoros        

Hardware Resource                    Command to Check Hardware Resource   

Color Graphics                       xdpyinfo -display <display name>:0   

Display Size                         xdpyinfo -display <display name>:0   

Display Resolution                   xdpyinfo -display <display name>:0   



Checking Software Requirements

Checking Computer Runtime System Software

The requirements below refer to the computer(s) on which you run Advanced Khoros software. These requirements refer to both Advanced Khoros application and development environments.


 Checking Computer Runtime System Software Requirements for Advanced Khoros    

Software Resource           Command to Check Software Resource            

Operating System            uname -m, uname -p, and uname -a              

Window System & Graphics                                                  
System                                                                    
Client Runtime Environment                                                

Sun (Solaris 2.x/SunOS      /usr/sbin/pkgchk -l | grep -i libx11          
5.x)                                                                      

Sun (Solaris 1.x/SunOS      ls -al $OPENWINHOME/lib/libX                 
4.x)                                                                      

SGI (IRIX)                  /usr/sbin/versions | grep -i x_eoe  and       
                            /usr/sbin/versions | grep -i gl               

DEC Alpha (Digital          /usr/sbin/setld -i | grep -i xdev             
UNIX/OSF1)                                                                

PC (Yggdrasil Linux)        ls -al /usr/lib/ygg/comp | grep -i x11      

IBM RS/6000 (AIX)           /usr/bin/lslpp -La | grep -i x11  and         
                            lppchk                                        

FORTRAN System              (Not needed if using f2c or on KRI's          
Runtime Environment         supported platforms)                          

Sun (Solaris 2.x/SunOS      /usr/sbin/pkgchk -l | grep -i f77             
5.x)                                                                      

Sun (Solaris 1.x/SunOS      ls -al /usr/lang/SC/77                     
4.x)                                                                      

SGI (IRIX)                  /usr/sbin/versions | grep -i ftn_eoe          

DEC Alpha (Digital          /usr/sbin/setld -i | grep -i fortran          
UNIX/OSF1)                                                                

PC (Yggdrasil Linux)        ls -al /usr/lib/ygg/comp | grep -i f2c      

IBM RS/6000 (AIX)           /usr/bin/lslpp -La | grep -i fortran and      
                            lppchk                                        



Checking Display Runtime System Software

The requirements below refer to the computer running your X Window System server (or to your X terminal) on which you display Advanced Khoros software. In the case of workstations, this often may be the same computer that you use to run Advanced Khoros.

Note: <display name> can be the empty string if you are displaying and running on the same computer; otherwise it can be the system (host) name or the IP number of the machine whose display you wish to check.

Also note: if you are checking a remote display, the computer you are running the xdpyinfo command on must be authorized to connect to that display (often by using the xhost command on the remote display). See your system documentation for further details.

Further Note: <wm name> is one of mwm, dtwm, 4Dwm, twm, olwm, etc.


  Checking Display System Runtime Software Requirements for Advanced Khoros    

Software Resource        Command to Check Software Resource               

X Window Server (X       xdpyinfo -display <display name>:0               
Terminal)                                                                 

Graphics Server          xdpyinfo -display <display name>:0               

Window Manager           For C Shell (csh) users:                         

                          strings -a `which <wm name>` | grep -i release  
                          or                                              
                          strings -a `which <wm name>` | grep -i version  

                         For Korn Shell (ksh) users:                      

                          strings -a `whence <wm name>` | grep -i         
                         release or                                       
                          strings -a `whence <wm name>` | grep -i         
                         version                                          



Checking Computer System Software for Installing on a Development or Ported Platform

Please refer to the following section on checking requirements for the Advanced Khoros development environment. The installation requirements in these cases are the same as for the development environment, except that you do not need the Perl interpreter. Remember, though, that these requirements are for the machine(s) on which you are installing Advanced Khoros, whereas the development environment requirements are for the computers(s) where you run the development environment.

Checking Computer System Software for Advanced Khoros Development Environment

The requirements below refer to the computer(s) on which you run Advanced Khoros software. These requirements apply only to the Advanced Khoros development environment.


           Checking Computer System Software Requirements for            
                   Advanced Khoros  Development Environment                    

Software Resource           Command to Check Software Resource            

ANSI C Compiler             For C Shell (csh) users:                      

                              which cc  and `which cc` -v  and  man cc    

                            For Korn Shell (ksh) users:                   

                              whence cc  and `whence cc` -v  and  man cc  

                            (Note:  cc may be  acc,  gcc, or  xlc  ;  -v  
                            may be -V)                                    

FORTRAN Compiler            For C Shell (csh) users:                      

                              which f77  and `which f77` -v  and  man     
                            f77                                           

                            For Korn Shell (ksh) users:                   

                              whence f77  and `whence f77` -v  and  man   
                            f77                                           

                            (Note:  f77 may be  f2c,  g77, or  xlf  ;     
                            -v may be -V)                                 




ANSI C Development                                                        
Environment                                                               

Sun (Solaris 2.x/SunOS      /usr/sbin/pkgchk -l | grep cc                 
5.x)                                                                      

Sun (Solaris 1.x/SunOS      ls /usr/lang/SC                              
4.x)                                                                      

 SGI (IRIX)                 /usr/sbin/versions | grep -i c_dev            

DEC Alpha (Digital          /usr/sbin/setld -i | grep -i devel            
UNIX/OSF/1)                                                               

PC (Yggdrasil Linux)        ls -al /usr/lib/ygg/comp | grep -i gcc      

IBM RS/6000 (AIX)           /usr/bin/lslpp -La | grep -i xlc  and         
                            lppchk                                        

FORTRAN Development                                                       
Environment                                                               

Sun (Solaris 2.x/SunOS      /usr/sbin/pkgchk -l | grep f77                
5.x)                                                                      

Sun (Solaris 1.x/SunOS      ls /usr/lang/SC                              
4.x)                                                                      

 SGI (IRIX)                 /usr/sbin/versions | grep -i ftn_dev          

DEC Alpha (Digital          /usr/sbin/setld -i | grep -i fortran          
UNIX/OSF/1)                                                               

PC (Yggdrasil Linux)        ls -al /usr/lib/ygg/comp | grep -i f2c      

IBM RS/6000 (AIX)           /usr/bin/lslpp -La | grep -i xlf  and         
                            lppchk                                        

Window System & Graphics                                                  
System                                                                    
Client Development                                                        
Environment                                                               

Sun (Solaris 2.x/SunOS      /usr/sbin/pkgchk -l | grep -i x11             
5.x)                                                                      

Sun (Solaris 1.x/SunOS      ls -al $OPENWINHOME/lib/libX     and         
4.x)                        ls -al $OPENWINHOME/include/X11               

SGI (IRIX)                  /usr/sbin/versions | grep -i x11  and         
                            /usr/sbin/versions | grep -i gl               

DEC Alpha (Digital          /usr/sbin/setld -i | grep -i xdev             
UNIX/OSF/1)                                                               

PC (Yggdrasil Linux)        ls -al /usr/lib/ygg/comp | grep -i x11      

IBM RS/6000 (AIX)           /usr/bin/lslpp -La | grep -i x11  and         
                            lppchk                                        

Perl Interpreter            For C Shell (csh) users:                      

                             which perl  and  `which perl` -v             

                            For Korn Shell (ksh) users:                   

                             whence perl  and  `whence perl` -v           



Checking 3rd-Party System Software for Installing and Running Advanced Khoros

Remember, all this software is freely included at the ftp site, so if you are installing on a supported platform, you may still proceed with the installation without these 3rd-party tools installed. If you are installing on a development or ported platform, you must first install these 3rd-party tools before continuing with the installation. To assist you with this, the source code for all of these 3rd-party tools has been included at the KRI ftp site. See Appendix B for instructions.

Note that all of this software is bundled with the Linux OS for PC's. Also note that perl is bundled with IRIX 5.3 OS for SGIs. Finally, note that GNU's tar is not required, but highly recommended.

The requirements below refer to the computer(s) on which you install and run Advanced Khoros software. Remember that perl is only required for the software development environment and the Support Toolbox.


          Checking 3rd-Party System Software Requirements for            
                   Installing and Running Advanced Khoros                      

Software Resource              Command to Check Software Resource         

GNU file                       For C Shell (csh) users:                   
compression/decompression:                                                

 gzip/gunzip 1.2.4+              which gzip  and  `which gzip` -V         

                               For Korn Shell (ksh) users:                

                                 whence gzip  and  `whence gzip` -V       

GNU file                       For C Shell (csh) users:                   
archiving/de-archiving:                                                   

 tar 1.11.8 +                    which tar  and  `which tar` --version    

                               For Korn Shell (ksh) users:                

                                 whence tar  and  `whence tar` --version  

                               Also:  ls /usr/local/gnu/bin/tar           

GNU runoff tools for           For C Shell (csh) users:                   
formatting/printing:                                                      

 groff, gtbl, & geqn 1.10+       which groff  and  `which groff` -v       

                               For Korn Shell (ksh) users:                

                                 whence groff  and  `whence groff` -v     

Perl Interpreter:              For C Shell (csh) users:                   

 perl 4.036 (preferred and       which perl  and  `which perl` -v         
tested) or 5.02                                                           

                               For Korn Shell (ksh) users:                

                                 whence perl  and  `whence perl` -v       



What If I'm Missing Some Requirements?

Where to Get Hardware

You may be able to increase disk space, swap space, and temp. space by removing unneeded files from your system and/or reconfiguring your system's disk usage.

Where to Get Third-Party Software

Go to ftp.khoral.com:/pub/dist.


Computer Runtime System Software

Freeware X11R5+ client runtime environments are provided by X Consortium, Inc. and by KRI via FTP. You will then have to compile them, which requires a C compiler.

Otherwise, please contact your system administrator.

Display Runtime System Software

Freeware versions of the necessary X11R5+ display servers and window managers are provided by X Consortium, Inc. and by KRI via FTP. You will then have to compile them, which requires a C compiler.

Otherwise, please contact your system administrator.

Computer Development System Software

Freeware versions of the required compilers and development environments are available via Internet FTP access. ANSI C, C++, f2c, and Perl are available from GNU and/or the Free Software Foundation and from KRI via FTP. (Note: you need a native C compiler to compile the freeware ANSI C compiler.)

Freeware X11R5+ client development environments are provided by X Consortium, Inc. and by KRI via FTP access. You will then have to compile them, which requires an ANSI C compiler.

Otherwise, please contact your system adminstrator.

3rd-Party System Software

The required 3rd-party system software may be obtained in "ready-to-run" form for the Advanced Khoros supported platforms from the ftp site. When you run the kinstall script, you will have an option to install any missing 3rd-party system software automatically.

If you are not installing Advanced Khoros on a supported platform, the source code is also included at the ftp site. However, you will then have to compile them, which requires ANSI C and C++ compilers.

Descriptions of Supported and Non-Supported Platforms

Supported Platforms

Advanced Khoros has been developed and extensively tested on the platforms listed in the table below. Because of the extra level of testing, KRI designates these as supported platforms. Additionally, a Advanced Khoros supported platform has the following characteristics:


                   Supported Platforms for Advanced Khoros                      

Vendor  CPU          Operating        ANSI C         FORTRAN         
                     System          Compiler     Compiler       

DEC     Alpha AXP    OSF/1  3.2       cc 3.11        f77 3.4-041    
                     (Digital UNIX)   (native)       (DEC AXP FORTRAN              
                                                     77)                       

(PC)    486,         Linux 2.0.18     gcc 2.7.2      f2c 19951025   
        Pentium      (Red Hat)        (GNU C)       (AT&T Bell Labs)                   
                                       

SGI     MIPS I-IV    IRIX 5.3         cc 3.18        f77 4.0.1   
       (R2000-R10000)                (SGI Devel.    (SGI FORTRAN              
                                      Option 5.3)    77)                       

Sun     SPARC        Solaris 2.4,2.5  gcc 2.7.2      f2c 19951025   
                     (SunOS 5.4)      (GNU C)        (AT&T Bell Labs                      
                                                      

Sun     SPARC        Solaris 2.4,2.5  cc 3.0.1       f77 3.0.1   
                     (SunOS 5.4)     (Sun SPARCworks)(Sun SPARCworks)                      




Non-Supported Platforms

For a variety of reasons, KRI refers to two major types of platforms: supported and non-supported. However, for internal purposes KRI distinguishes between two types of non-supported platforms: development and ported. For purposes of installing Advanced Khoros there is no difference in the steps taken to install either non-supported platform, which is why we have chosen to refer to them with a single term throughout the installation guide. If you are interested in knowing what the difference between development and ported platforms is, the two following sections provide an explanation.

Development Platforms

Khoros has been developed and partially tested on the platforms listed in the table below. Due to this partial level of testing, KRI designates these as development platforms. An Advanced Khoros development platform has the following characteristics:

             Development Platforms for Advanced Khoros

Vendor   CPU        Operating System   ANSI C Compiler     FORTRAN Compiler

IBM      RS/6000,   AIX  4.1            xlc 3.0               xlf 3.0
         PowerPC                        (AIX ANSI C)          (AIX FORTRAN 77)

Sun      SPARC      Solaris 2.3         cc 2.0.1              f77 2.0.1
                    (SunOS 5.3)         (Sun SPARCworks)      (Sun SPARCworks)

Sun      SPARC      Solaris 2.4+        gcc 2.7.2+            f2c 19951025+
                    (SunOS 5.5+)        (GNU C - freeware)    (AT&T - freeware)

Sun      SPARC      Solaris 1.1.3+      cc 2.0.1              f77 2.0.1
                    (SunOS 4.1.3+)      (Sun ANSI C)          (Sun FORTRAN 77)


Ported Platforms

Advanced Khoros has been ported to the platforms listed in the table below. Only very limited testing has been performed on these platforms. Because of this low level of testing, KRI designates these as ported platforms. A ported platform has the following characteristics:


                   Ported Platforms for Advanced Khoros

Vendor   CPU         Operating Sys.    ANSI C Compiler    FORTRAN Compiler

HP       9000/700+   HP-UX 9.0.1        cc (native)          f77 (native)

(PC)     486,        FreeBSD            gcc 2.7.0            f2c 19951025
         Pentium                        (GNU C - bundled)    (AT&T - bundled)

(PC)     486,        BSD/OS             gcc 2.7.0            f2c 19951025
         Pentium     (BSDI)             (GNU C - bundled)    (AT&T - bundled)

Cray     Y-MP        UNICOS 9.0.0       cc (native)          f77 (native)

Data     Aviion      DG/UX              cc (native)          f77 (native)
General



Copyright Khoral Research, Inc. 1997; All Rights Reserved