.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.  Information
in this section applies to both KHOROS_HOME and Khoros toolboxes.
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
or in {toolbox}/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 particular 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 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.
This is followed by creating symbolic links from the srcmach tree to 
each of the files in the Khoros source tree.  
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
architecture.  \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
The concepts described above were applied to KHOROS_HOME. These
same concepts can be applied to Khoros toolboxes.
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 the top level directory of KHOROS_USER, 
for access to the machine names and login IDs.
.PP
Note that a mach file must be setup even if you are not going to 
support multiple architectures. That is you need a mach file
even if you are working with a single architectures.
.PP
The five entries in the mach file are described below:
.sp
.IP KHOROS_USER 24
specifies the name of the user.  This is used to ensure proper 
ownership and permissions of files, required for rsh's, and will
mail to the user the results of compilations and installations.
NOTE, This is a required field.
.sp
.IP LOCAL_SRC_TOP 24
specifies the complete path to the top of source for the machine that 
is used in the development of the Khoros system. (See explanation below).
NOTE, this is a required field.
.sp
.IP KHOROS_MACHINES 24
specifies the name of the machines that source will be compiled on. This
field only needs to be specified if multiple architectures are to be 
supported.
.sp
.IP KHOROS_MACH_DIR 24
specifies the complete paths to the srcmach directories for each machine 
named in the KHOROS_MACHINES entry. This
field only needs to be specified if multiple architectures are to be
supported.
.sp
.IP KHOROS_SRC_TOP 24
specifies the complete paths to the top of source for each machine named 
in the KHOROS_MACHINES entry. This
field only needs to be specified if multiple architectures are to be
supported.
.sp
.PP
\f(CW$KHOROS_HOME/repos/config/src_conf\fP is the location 
for KHOROS_HOME 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 
toolboxes.  Each toolbox will contain its own mach file(s), located in 
\f(CW{toolbox}/repos/config/src_conf\fP. Consult Volume 2, Chapter 1 for
information on creating and managing toolboxes using \fBkraftsman\fP.
Several examples of different mach files are presented in the examples 
that follow.
.PP
The paths for $KHOROS_HOME and and the top level of toolboxes 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 verify 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 field 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 repos/config/src_conf directory for a mach file named
"default_mach.sun.xyz.edu" for KHOROS_HOME and 
"{toolbox}_mf.sun.xyz.edu" for a toolbox.  If the mach file is not found,
then the search will continue in the repos/config/src_conf directory 
for "default_mach" for KHOROS_HOME and "{toolbox}_mf for a toolbox.
If a mach file is not found, the program will terminate 
and a mach file will have to be created.
.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. Note, this example
applies to the mach files in KHOROS_HOME, however this concept
can be applied to the mach files in a Khoros Toolbox. 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 a
Khoros toolbox 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. We will call the Khoros toolbox "CONTRIB_TOOLBOX."
An example of a mach file for a Khoros toolbox is presented below:
.nf

#  contrib_toolbox_mf

set KHOROS_USER = (spanky)
set KHOROS_MACHINES = (dec.xyz.edu  sun.xyz.edu)
set KHOROS_MACH_DIR = ($CONTRIB_TOOLBOX/srcmach/srcdecmips  $CONTRIB_TOOLBOX
RIB/srcmach/srcsun4)
set KHOROS_SRC_TOP = ($CONTRIB_TOOLBOX/src $CONTRIB_TOOLBOX/src)
set LOCAL_SRC_TOP = (/usr/users/spanky/contrib_toolbox/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 referred to as a srcmach tree.  The user may retrieve 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 srcmach directory,
it is the preferred 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 srcmach.  In the 
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
srcmach directory are specified in the \fImach file\fP.
.LP
The usage for \fBksrcconf\fP is as follows:
.nf
\f(CW
 % ksrcconf [-source xxxx] [-toolbox yyyy]\fP

 where,
         xxxx  is the source directory

         yyyy  is the name of the toolbox you are working in. If you
               you are working in KHOROS_HOME, do not specify the
               the -toolbox option.
 
.fi
A complete description and program usage may be obtained by retrieving 
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
a Khoros toolbox. We will call the toolbox "contrib_toolbox".
.sp
.nf
cd to the source directory in the "contrib_toolbox" toolbox. Execute:
.br
\f(CW% ksrcconf -toolbox contrib_toolbox\fP
.fi
.sp
ksrcconf will look in $CONTRIB_TOOLBOX/repos/config/src_conf for
the mach file.
.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 [-toolbox] [-f full_path | -r relative_path]
                [make options]\fP

where,
        [-toolbox]  the Toolbox name
        [-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 the src directory.  A complete 
description and usage of \fBkmakeall\fP can be obtained at any time
by retrieving 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 the $KHOROS_USER/.rhosts.bk to
$KHOROS_USER/.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 $KHOROS_HOME 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 the source
in a Khoros toolbox. We will call the toolbox CONTRIB_TOOLBOX
.sp
.nf
\f(CW% cd CONTRIB_TOOLBOX/src
% kmakeall install -toolbox contrib_toolbox\fP

.fi
.sp

