.ds f. srcmach.sec
.bp
.NH 1 "MAINTAINING THE KHOROS SRCMACH TREE FOR MULTIPLE ARCHITECTURES"
.XS
\s12\*(SN  MAINTAINING THE KHOROS SRCMACH TREE FOR MULTIPLE ARCHITECTURES
.XE
.sp
.PP
This section of the manual provides information for setting up and
maintaining Khoros for multiple architectures.  
Briefly, the steps necessary for configuring Khoros for multiple
architectures includes the following:
.sp
.IP "(1) - "
Create the libmach directories for each architecture to be supported.
.sp
.IP "(2) - "
Create the binmach directories for each architecture to be supported.
.sp
.IP "(3) - "
Modify or create the mach file(s) in KHOROS_HOME/repos/config/src_conf
for the appropriate paths and machine names for each architecture.
.sp
.IP "(4) - "
Create the srcmach tree for each architecture.  This consists of 
creating a directory structure that mimics that of the Khoros source
tree, and making symbolic links from the srcmach tree to the Khoros
source tree.
.sp
.IP "(5) - "
Compile the system for each architecture.
.sp 
.PP
The remainder of this document provides more detailed information 
on each step outlined above.  Several tool programs are provided, which help 
in creating directories and making links to files in source.  The use
of these programs is explained in the sections that follow.
.PP
Khoros should be installed for a single architecture prior to establishing
a multiple architecture system.  This will ensure that all programs
compile clean and that there are no configuration problems.
The \fIInstallation Guide\fP provides the user with the necessary information
for setting up Khoros for a single architecture.
.PP
Before proceeding to set up a system for multiple architectures,
the user should be aware of some of the possible configurations that
may arise on a networked system of machines.
As described in Section A of this chapter, the directory structure of Khoros
includes src, repos, lib, include, bin, and data.  To support multiple
architectures, you would also have srcmach, libmach, and binmach
directories which would contain subdirectories for each architecture.
Because disk storage is a precious commodity, you might choose to
store the Khoros source directories on a different disk from that
of the binaries and libraries.  Note that the environment variable,
\fIKHOROS_HOME\fP, points to the top level of the Khoros src directory.
.PP
There are three common scenarios for setting up Khoros for multiple
architectures on a networked system.  One scenario is to have the srcmach, 
bins, and libs on a local partition and the src directory on another 
machine that is mounted on the local partition.  Another scenario is to 
have the binaries and libraries on a local partition, and the src and 
srcmach on a remote disk that is mounted on the local partition.  
The last scenario is to have the src, srcmach, binaries, and 
libraries on a remote disk that is mounted locally.  
The following diagram depicts these three scenarios:
.sp
.DS
.ps 9
.vs 11
\f(CW
Scenario 1 - src located on a remote disk

     Machine A                 Machine B
      (local)                   (remote)
     ----------     mounted    ----------
     |        |<---------------| khoros |
     |--------|                |        |
     | srcmach|                |        |
     |  bins  |                |        |
     |  libs  |                |        |
     ----------                ----------

Scenario 2 - src and srcmach located on a remote disk

     Machine A                 Machine B
      (local)                   (remote)
     ----------     mounted    ----------
     |        |<---------------| khoros |
     |        |<---------------| srcmach|
     |--------|                |        |
     |  bins  |                |        |
     |  libs  |                |        |
     ----------                ----------

Scenario 3 - src, srcmach, bins, and libs located on a remote disk

     Machine A                 Machine B
      (local)                   (remote)
     ----------     mounted    ----------
     |        |<---------------| khoros |
     |        |<---------------| srcmach|
     |        |<---------------|  bins  |
     |        |<---------------|  libs  |
     |        |                |        |
     ----------                ----------

* khoros - includes the directories of src, include, repos, and data.

\fP
.DE
.PP
After it is determined which scenario best fits a paricular site,
the next step is to create the directories for the \fIlibmach\fP 
and \fIbinmach\fP.  We will now provide a procedure for doing this.
.PP
The first step in setting up Khoros for multiple architectures is to
create a \fIlibmach\fP directory that will have a separate subdirectory for
each architecture to be supported.  For example, if both dec
and sun architectures are supported, then \fIlibdecmips\fP and 
\fIlibsun4\fP directories are created beneath the \fIlibmach\fP
directory.  Each of these directories will contain the compiled libraries
for each supported architecture.  
The directory \fIlib\fP is just a symbolic link to the libmach directory 
for the local host machine architecture.  This is accomplished by
creating a \fI/localhost/khoros\fP directory and creating a link between
the \fIlib\fP directory and the libmach directory on each machine.
Thus, accessing the directory \fIlib\fP on a sun4 machine will actually get
you the libmach directory for the sun4 architecture, \fIlibsun4\fP.
This step must be performed for each machine architecture to be supported.
.LP
This step can best be illustrated by an example: (on a sun4 machine)
.sp
.nf
\f(CW% mkdir /localhost/khoros
% ln -s ~khoros/libmach/libsun4 lib
% cd khoros
% ln -s /localhost/khoros/lib lib
\fP
.fi
.PP
The next step is to create a \fIbinmach\fP directory that will contain
the compiled libraries for each architecture.  Similar to the \fIlibmach\fP
directory discussed above, a \fIbinmach\fP directory is created with
a separate subdirectory for each architecture.  Using the same example as
above, separate subdirectories will be created for \fIbindecmips\fP and
\fIbinsun4\fP.  Each of these directories will contain the compiled
binaries for each supported architecture.  Similar to the \fIlib\fP
directory discussed above, the \fIbin\fP directory is just a symbolic
link to the local host libmach for that machine architecture.
This step must be performed for each machine architecture to be supported.
A symbolic link can be set up for the local host in the following manner:
.sp
.nf
\f(CW% mkdir /localhost/khoros
% ln -s ~khoros/binmach/binsun4 bin
% cd khoros
% ln -s /localhost/khoros/bin bin
\fP
.fi
.PP
The following diagram shows a portion of the Khoros directory structure
for support of multiple architectures.  It illustrates how the organization 
of the \fIlibmach\fP and \fIbinmach\fP directories as described above would 
appear if the local host machine is a decmips.
.sp
.DS
.ps 9
.vs 11
\f(CW

 /localhost/khoros/bin@ -> binmach/bindecmips

 /localhost/khoros/lib@ -> libmach/libdecmips


             |--bin@ -> /localhost/khoros/bin
             |
             |                  |-bindecmips----
             |--binmach---------|
             |                  |-binsun4-------
             |    
 ../khoros---|
             |
             |                  |-libdecmips----
             |--libmach---------|
             |                  |-libsun4-------
             |
             |--lib@ -> /localhost/khoros/lib

\fP
.DE
.PP
This is followed by creating a srcmach tree for each architecture, 
creating symbolic links to the
files in the Khoros source tree, and compiling for each architecture.  
Creating a srcmach tree consists of creating a directory structure 
that mimics the directory structure of the Khoros source tree.
If you are including Khoros contrib, then you will also want to set
up a srcmach tree that mimics the Khoros contrib source tree.  
This is followed by creating symbolic links from the srcmach tree to 
each of the files in the Khoros and Khoros contrib source trees.  
The final step is to compile the system for each of the architectures.
.PP
There are several programs that can be used to help create symbolically 
linked source trees when your site supports multiple machine 
architectures.  Two programs that can be used to create a symbolically 
linked source tree are \fBklndir\fP and \fBksrcconf\fP.  
\fBKlndir\fP is a low level tool used to create a symbolically linked 
source tree for a particular architecture, whereas \fBksrcconf\fP 
can be used to create multiple source trees at once.  \fBKsrcconf\fP will 
take care of creating the source tree directories for each architecture 
and make the links to the source files.  \fBKmakeall\fP
is a tool to ease the process of compiling the source for each
architecuture.  \fBKsrcconf\fP and \fBkmakeall\fP both depend on
\fImach\fP files, whereas \fBklndir\fP does not.  Each of these tools 
will be discussed in the sections that follow.
.PP
Since many of the tool programs in Khoros make use of \fImach\fP files,
we will begin by discussing the creation and use of mach files.
.sp 2
.NH 2 "MACH FILES AND MULTIPLE ARCHITECTURES"
.XS
     \*(SN  MACH FILES AND MULTIPLE ARCHITECTURES
.XE
.sp
.PP
\fBKsrcconf\fP and \fBkmakeall\fP use a \fImach\fP file to sort out
the correct paths to the top level of source for each machine.
A mach file contains information specific for a particular 
installation site.  It contains the name of the Khoros user, the
names of the machines, and the proper paths to the source and
srcmach directories for each of the machine architectures that
source will be compiled on.  These routines also require that an
".rhosts.bk" file be located in $KHOROS_HOME, for access to the machine 
names and login IDs.
.PP
The five entries in the mach file are described below:
.sp
.IP KHOROS_USER 24
specifies the name of the Khoros user.  This is used to ensure proper 
ownership and permissions of files, and required for rsh's.
.sp
.IP KHOROS_MACHINES 24
specifies the name of the machines that source will be compiled on.
.sp
.IP KHOROS_MACH_DIR 24
specifies the complete paths to the srcmach directories for each machine 
named in the KHOROS_MACHINES entry.
.sp
.IP KHOROS_SRC_TOP 24
specifies the complete paths to the top of source for each machine named 
in the KHOROS_MACHINES entry. 
.sp
.IP LOCAL_SRC_TOP 24
specifies the complete path to the top of source for the each machine that 
is used in the development of the Khoros system. (See explanation below)
.sp
.PP
\f(CW$KHOROS_HOME/repos/config/src_conf\fP is the default location 
for Khoros mach files.  If your site has one or more machines with
the same paths to the Khoros source tree, then one mach file may be
used to specify the machine information for Khoros home.  
A mach file must also be
created for those sites supporting Khoros contrib.  Several examples
of different mach files are presented in the examples that follow.
These examples assume that $KHOROS_HOME and $KHOROS_CONTRIB have
been set to their respective paths for a particular site.
That is, $KHOROS_HOME may be set to the path /local/khoros, and 
$KHOROS_CONTRIB to /local/khoros_contrib.
.PP
The paths for $KHOROS_HOME and $KHOROS_CONTRIB must be correct for your
site.  The user should be aware of aliases for "pwd".  For example, if
you have "pwd" aliased to "cwd", then you may get an incomplete path 
if your site is using \fIautomount\fP or if your partitions are
symbolically linked so that Khoros is available in a different location
on your disk.  To avoid this problem, the user may want to unalias
the "pwd" command, or use "\pwd" to get the correct path to the top 
of source.
.PP
One other problem that may occur, is that the hostnames for the machines
at your site may not be qualified with an extension.  For example, if
your site has a machine name of "mymachine", it may be qualified with
an extension, such as "mymachine.xyz.edu".  You should verifiy the
correct hostname of all machines at your site by logging on to the 
machine and entering the command, \f(CWhostname\fP.  This will return
the correct hostname for that machine, and this is what should be
entered in KHOROS_MACHINES field of the mach file. 
.PP
The following is an example of a mach file for Khoros that supports
two different machine architectures:
.nf

set KHOROS_USER = (khoros)
set KHOROS_MACHINES = (dec.xyz.edu  sun.xyz.edu)
set KHOROS_MACH_DIR = ($KHOROS_HOME/srcmach/srcdecmips  $KHOROS_HOME/src
mach/srcsun4)
set KHOROS_SRC_TOP = ($KHOROS_HOME/src $KHOROS_HOME/src)
set LOCAL_SRC_TOP = (/local/khoros/src)

.fi
.sp
.PP
If the full paths to the top of the Khoros source tree are different 
for each of the machines at a site, then a mach file must be created
for each of the machines.  To create a mach file for a particular site, 
one needs to list the machine names for each of the architectures 
that are supported.  The path to the srcmach directories for each 
machine must also be provided in the KHOROS_MACH_DIR field.  
In addition, the path to the top of the source for each of the machines 
must also be provided.  Note that there is a one-to-one correspondence 
for each entry in the fields, KHOROS_MACHINES, KHOROS_MACH_DIR, 
and KHOROS_SRC_TOP.
.PP
The last field in the mach file, LOCAL_SRC_TOP, specifies the path to 
the top of source.  For some sites, this path may be different for
each of the machines that source will be compiled on.  If the paths
to source are different for each machine, then it is necessary to
create a mach file for each machine.  For example, if your site
supports two machine architectures with different paths to the
top of source, then a mach file should be created for each
architecture.  In addition, the paths to the top of the Khoros source
tree must be checked for any networked machine that is used
for developing or managing Khoros.  If the path to the top
of the Khoros source tree is different, then a separate mach file 
must also be created for use with that particular machine.
.PP
The programs that use mach files check the current machine name and
will use the appropriate mach file, if one exists for that machine.
For example, if your current machine name is sun.xyz.edu, a 
search is made in the specified directory for a mach file named
"default_mach.sun.xyz.edu".  If the mach file is not found,
then the search will continue in the default directory 
"$KHOROS_HOME/repos/config/src_conf/" for "default_mach.sun.xyz.edu".
If the mach file is still not found, then the default mach file,
"default_mach" will be used.  If the correct paths cannot be resolved,
then the program will terminate, and a mach file will have to be
created for that particular machine.
.PP
The next example illustrates a site supporting two architectures 
when the paths to the top of Khoros source are different for each of
the machines.  In this case two mach files are required.  The two mach
files are named using the machine name as the extension. If the 
machine names are dec.xyz.edu and sun.xyz.edu, then the mach 
files would be named, default_mach.dec.xyz.edu and 
default_mach.sun.xyz.edu. Examples of these two files are presented
below:
.nf

#  default_mach.dec.xyz.edu

set KHOROS_USER = (khoros)
set KHOROS_MACHINES = (dec.xyz.edu  sun.xyz.edu)
set KHOROS_MACH_DIR = ($KHOROS_HOME/srcmach/srcdecmips  $KHOROS_HOME/src
mach/srcsun4)
set KHOROS_SRC_TOP = ($KHOROS_HOME/src $KHOROS_HOME/src)
set LOCAL_SRC_TOP = (/local/khoros/src)

.fi
.nf

#  default_mach.sun.xyz.edu

set KHOROS_USER = (khoros)
set KHOROS_MACHINES = (dec.xyz.edu  sun.xyz.edu)
set KHOROS_MACH_DIR = ($KHOROS_HOME/srcmach/srcdecmips  $KHOROS_HOME/src
mach/srcsun4)
set KHOROS_SRC_TOP = ($KHOROS_HOME/src $KHOROS_HOME/src)
set LOCAL_SRC_TOP = (/foo/local/khoros/src)

.fi
.PP
Notice that the paths for the two machines are different for 
LOCAL_SRC_TOP.  Since the tools make use of these paths to install
and configure srcmach trees, it is important to recognize these
differences for successful maintenance of the Khoros source tree.
.PP
The next example shows how a mach file may be set up for support of the
Khoros contrib srcmach for two different architectures.  In this example,
let's assume that the paths to the top of Khoros source are the same.
This enables the use of one mach file to define the paths for both
architectures.   To keep the definitions in this mach file separate from
those in the mach file, the names of the mach files should be different.
For example the mach file for Khoros could be "default_mach" and the
mach file for Khoros contrib could be "contrib_mach".  An example of
a mach file for Khoros contrib is presented below:
.nf

set KHOROS_USER = (khoros)
set KHOROS_MACHINES = (dec.xyz.edu  sun.xyz.edu)
set KHOROS_MACH_DIR = ($KHOROS_CONTRIB/srcmach/srcdecmips  $KHOROS_CONT
RIB/srcmach/srcsun4)
set KHOROS_SRC_TOP = ($KHOROS_CONTRIB/src $KHOROS_CONTRIB/src)
set LOCAL_SRC_TOP = (/local/khoros_contrib/src)

.fi
.PP
The following sections discuss each of the tool programs involved in 
building and maintaining the Khoros srcmach tree for multiple architectures.
.sp 2
.NH 2 "CREATE A SYMBOLIC LINKED SOURCE TREE - KLNDIR"
.XS
     \*(SN  CREATE A SYMBOLIC LINKED SOURCE TREE - KLNDIR
.XE
.sp
.PP
\fBKlndir\fP is a program for creating directories in
a srcmach tree and creating symbolic links to the files in the 
corresponding directories in the Khoros source tree.
\fBKlndir\fP first checks to see if the destination directories in
the srcmach tree exist.  If they do not exist, then it creates the 
directories and makes the symbolic links to the *.c, *.h, *.f source files.
It copies over the source Makefiles, and makes symbolic links to the 
Imakefiles. 
.sp
.PP
The usage for \fBklndir\fP is as follows: 
.nf
\f(CW

 % klndir -source xxxx -dest yyyy\fP

 where,
         xxxx  is the absolute path to a directory in source from /.

         yyyy  is the absolute path to a directory in the srcmach from /.

.fi
The user specifies the FULL directory path to the Khoros source tree
and the destination srcmach tree.  The Khoros source tree is the location
of the source files for Khoros.  The destination source tree is a new 
source tree containing symbolic links to the source (*.c, *.h, and *.f files),
and is refered to as a srcmach tree.  The user may retreive the man page
for \fBklndir\fP for a complete description and usage information.
.PP
The following example demonstrates the usage for \fBklndir\fP:
.sp
.nf
\f(CW% klndir -source /foo/khoros/src -dest /foo/khoros/srcmach/foomach\fP
.fi
.sp
This will make links from the khoros source tree to the
foomachine source tree.
.sp 2
.NH 2 "CREATE MULTIPLE SYMBOLIC LINKED SOURCE TREES - KSRCCONF"
.XS
     \*(SN  CREATE MULTIPLE SYMBOLIC LINKED SOURCE TREES - KSRCCONF
.XE
.sp
.PP
\fBKsrcconf\fP is a more powerful and higher level tool than \fBklndir\fP,
since it can create multiple srcmach trees at once.  Since \fBKsrcconf\fP
calls \fBklndir\fP for each directory in the $KHOROS_HOME/srcmach directory,
it is the prefered tool to use when creating srcmach trees for multiple
machine architectures.  By default, \fBksrcconf\fP will attempt to create
symbolic links relative to the present working directory.  \fBKsrcconf\fP
assumes that there is a directory called KHOROS_HOME/srcmach.  In the 
KHOROS_HOME/srcmach directory are subdirectories for each machine 
architecture, and for each of these subdirectories it will update and
create the symbolic links.  The paths to each subdirectory of the
KHOROS_HOME/srcmach directory are specified in the \fImach file\fP.
.LP
The usage for \fBksrcconf\fP is as follows:
.nf
\f(CW
 % ksrcconf [-source xxxx] [-mach yyyy]\fP

 where,
         xxxx  is the source directory

         yyyy  is the path and filename of the mach file that is
                being used for the current install.
 
.fi
A complete description and program usage may be obtained by retreiving 
the man page for \fBksrcconf\fP.
.LP
The following examples may be helpful:
.sp
.nf
\f(CW% cd $KHOROS_HOME/src/vipl/arith_binary
% ksrcconf\fP
.fi
.sp
\fBOR\fP
.sp
\f(CW% ksrcconf -source $KHOROS_HOME/src/vipl/arith_binary\fP
.sp
Here is an example of setting up the symbolic links for all of
$KHOROS_HOME/src:
.sp
.nf
\f(CW% cd $KHOROS_HOME/src
% ksrcconf\fP
.fi
.sp
The next example shows how to configure the srcmach directory for
khoros_contrib:
.sp
.nf
\f(CW% cd $KHOROS_CONTRIB/src
% ksrcconf -mach contrib_mach\fP
.fi
.sp
Note that you must specify the correct mach file for khoros contrib, 
since the tool programs will use the default mach file for khoros home.
.sp 2
.NH 2 "COMPILING MULTIPLE ARCHITECTURES - KMAKEALL"
.XS
     \*(SN  COMPILING MULTIPLE ARCHITECTURES - KMAKEALL
.XE
.sp
.PP
Once the srcmach trees are in place and the
bin and lib directories for the multiple architectures have been created, 
\fBkmakeall\fP can be used to compile all of the architectures at once.
\fBKmakeall\fP is a shell script to assist in the use of \fBmake\fP on a
distributed computer system.  By default, \fBkmakeall\fP will attempt
to make source relative to the present working directory.
.PP
The usage for \fBkmakeall\fP is as follows:
.sp
.nf
\f(CW% kmakeall [-mach] [-f full_path | -r relative_path]
                [make options]\fP

where,
        [-mach]  is the path to a specified mach file
        [-f]     is the full path
        [-r]     is relative path to the top level src directory

.fi
The user can specify the FULL directory path name (-f) to the source, 
or the relative path name (-r) to $KHOROS_HOME/src.  A complete 
description and usage of \fBkmakeall\fP can be obtained at any time
by retreiving the man page for \fBkmakeall\fP. 
.PP
After getting the defined make objects and options, \fBkmakeall\fP
attempts to call \fIrsh\fP to each machine and call \fBmake\fP in the
appropriate $KHOROS_HOME/srcmach/ directory. 
\fBKmakeall\fP uses \fIrsh\fP, and since ".rhosts" files should not be left
lying around, \fBkmakeall\fP copies $KHOROS_HOME/.rhosts.bk to
$KHOROS_HOME/.rhosts before calling \fIrsh\fP and then removes the ".rhosts" 
file before exiting.  Since the \fIrsh\fP's are put in the
background, \fBkmakeall\fP needs to sleep for about a minute
to allow \fIrsh\fP's to be connected before removing the ".rhosts" file.
.PP
Here is an example of making and installing \fBvadd\fP on all machines:
.sp
.nf
\f(CW% cd $KHOROS_HOME/src/vipl/arith_binary/vadd
% kmakeall install\fP

.fi
.PP
Here is an example of making and installing all of 
$KHOROS_HOME/src/file_formats on all machines:
.sp
.nf
\f(CW% cd $KHOROS_HOME/src/file_formats
% ksrcconf
% kmakeall install\fP

.fi
.PP
Note that on a busy network and/or a slow server, you may experience 
timeout problems.  Therefore one should be cognizant of the network load
when compiling.
.PP
The following example illustrates how to compile all of khoros contrib:
.sp
.nf
\f(CW% cd $KHOROS_CONTRIB/src
% kmakeall install -mach contrib_mach\fP

.fi
.sp

