@chapter(Installing Galatea)

@section(Customizing the compilation process)

The Galatea distribution is set up to compile on a 4.3 BSD derived
system.  Without any changes, Galatea should compile on Ultrix, Sun OS,
Athena UNIX, and 4.3 BSD.  With minimal changes to the compile
configuration file, it is possible to compile Galatea for HP-UX or
Interactive 386/ix.

To change the configuration to work on various systems, copy the file
conf/generic to a new file whose name describes your system, ie.
cmuvax.  This file should then be modified to reflect your
configuration.  This file contains a set of make(1) macro definitions
that will be substituted into makefiles with the gconfig program,
which is also in the conf directory.  Follow the instructions supplied
as comments within each conf file to set the options you require. The
conf/dirs file directs gconfig to the directories in which it should
modify makefiles.  If you want to create a new flag or macro, you can
simply add it to the config file.  Gconfig will place a copy of every
macro in the config into every makefile it touches, whether or not
there was a previous definition.  If there was a previous definition,
gconfig removes it.

To run gconfig, change working directories to conf 'cd conf', type
'make', then type 'gconfig'.  When used without arguments, gconfig uses
the 'config' file to reconfigure the Galatea programs.  If an alternate
configuration file, ie. cmuvax, is required, type the name of the file
as the first argument to gconfig, ie. 'gconfig cmuvax'.  That
invocation will use the cmuvax file as the template to configure
Galatea for use on Carnegie Mellon VAX hosts.

If your system and options are already described in one of the
predefined conf files (athena, hpux, inter386, or sparc), you can
simply change the line "CONFIG = generic" to the name of your conf
file in the top-level Makefile. Then type "make all" to automatically
configure and build Galatea.  Or, you can type "make all
CONFIG=athena", and the build will be performed, preceeded by a
configuration.

@section(Tuning server parameters)

There are several aspects of the server operation, mainly timing
parameters, that can be adjusted for a particular site.  All of these
parameters are adjustable in the include file GALATEA/server/tunables.h
The documentation for these parameters is in the include file.

@section(Compiling the system)

The Makefiles for Galatea are designed to compile the complete system
without intervention.  In the top level Galatea directory, typing 'make'
should create the entire system.  'make install' will create the entire
system, if necessary, and then install the executables, libraries and
include files in common locations.  This is normally
/usr/local/{lib,include,bin} and /etc.  If you wish to make these
directories, 'make directories' will create any necessary directories
that do not already exist.  Typing 'make clean' will erase all of the
object files and executables and typing 'make uninstall' will remove any
installed files.

@section(The configuration file)

The Galatea server uses a configuration file to determine what the
devices are connected to the local machine, what remote servers are
available, and the video connectivity of the site.  Each line in the
file specifies a directly connected device or a remote server.  Fields
which are meaningless for a given device type should be filled with
@b[?].  This configuration file is usually called /etc/galatead.conf

@subsection(Representing a local videodisk player)

A directly connected videodisk player has a line with the following form:
@begin(example)
@flushleft[Type  VolumeName  Model  TtyPort  Baud  Parity  Chan]
@end(example)

The fields are separated by whitespace.  The values for the fields are:
@begin(description)
Type@\This field should contain RPD, for Record/Play Device.

VolumeName@\This field specifies the name of disk contained in the player.

Model@\This field specifies the type of videodisk player.

TtyPort@\This field specifies the port to which the videodisk player is
connected.  For a disk player connected to the serial port identified
with /dev/ttyS0, this field would be @b[ttyS0].

Baud@\This field specifies the baud rate for communication with the
videodisk player.  

Parity@\This field specifies the parity for communication with the
videodisk player.  This field can be @b[even], @b[odd], @b[any], or
@b[none].

Chan@\This field specifies the switch and input to which the disk player
connects.  This field is comma separated list of items of the form x:n-m
where n is the switcher number and m is the input number on the switch.
@b[1-3] would represent switch 1, input 3.  A special case for the
switcher number is @b[0], which indicates that the disk player does not
feed a switch, but is a direct server output.  In this case, m is the
server virtual output number.  The x component of the item is optional
and is either a @b[o] or @b[i], standing for output or input.  Note that
if all the items in a single list must either all contain the x
component, or they all must not contain that component.  A device that
is capable of recording can have a single item with an @b[i] for the x
component.  @b[i:0-3] would indicate that the recording input of the RPD
is fed from server virtual output number 3.

@end(description)

@subsection(Representing a local video routing switch)

The line of configuration for a local video switch has the following form:
@begin(example)
@flushleft[Type  SWTR-n  Model  TtyPort  Baud  Parity  Chan]
@end(exampe)

Aside from a few differences, the representation of a switch is
identical to that of a videodisk player.  If the field is not noted
specifically below, use the description given for local videodisk
player.

@begin(description)
Type@\For a local video switch, this field should be @b[SWTR].

SWTR-n@\This field specifies the switch number.  @b[n] should be the
number assigned to the switch, which is used in referencing the switch
in all other device representations.  For configuration with a single
switch, there could be one switch line with @b[SWTR-1] as the SWTR-n
field, although the number chosen for the switch is arbitrary.

Model@\This field specifies which type of switcher is connected.

TtyPort@\Normally this field is the same as for an RPD, but certain
switches can be chained together on a single serial port.  For these
switches, the TtyPort can be of the from x:m, where x is the device
number in the chain and m is the port filename as for an RPD.

Chan@\The channel description is a field made of a comma separated list
of items of the form x:y;n-m The x component specifies which of possibly
several physical switch outputs this item describes.  This is used when
you are configuring a multiple output switcher, such as the Akai 16x16
Digital Patch Panel.  The y component indicates the default input which
will be patched to the specified output.  The output will be set to this
input whenever the switcher is reset.  Switchers are reset when the
players are spun down, and when the volume table is rebuilt.  The n and
m components are as for an RPD where n indicates the switch to which the
specified output is connected and m indicates to which channel on the
next switcher the specified output is connected.  A value of @b[0] for n
indicates that the specified feeds a server virtual output and does not
feed another switcher.
@end(description)

@subsection(Representing a remote server)

Any Galatea server can be configured to use the resources of another
Galatea server.  The local server incorporates the resources of the
remote server as if they were located on the local host.  Clients do not
have any indication of differences between local and remote devices.  To
represent a remote server to the local server, use the following form of
configuration file line:
@begin(example)
@flushleft[Type  Hostname  ?  RemOut  ?  ?  Chan]
@end(example)
@begin(description)
Type@\For a remote server, the Type should be @b[FORW].

Hostname@\This field specifies the hostname for the server to which the
local server should connect.

Remout@\This field specifies which of the outputs on the remote machine
the local server should utilize.

Chan@\This Chan field is almost identical to the Chan field for local
video switches.  The differences are that there is no default input for
each output and that the output number specification is not important,
except that each output number must be unique.  So, the form of this
field is a comma separated list of items of the form x:n-m.  (A later
version of Galatea will permit the ommision of the output number.)  Of
course, if you only have the forwarding device feeding one local input,
you need not specify an output number.  Again, if n is @b[0], then the
forwarding device feeds a server virtual output.
@end(description)

@subsection(Representing an uncontrolled input)

A Galatea server can also make use of uncontrolled input sources, such
as a camera.  Such a device can be represented in the configuration file
with a line of the form:
@begin(example)
@flushleft[Type  InputName ?  ?  ?  ?  Chan]
@end(example)
@begin(description)
Type@\The Type should be @b[INPUT] for an uncontrolled input device.

InputName@\This field specifies the name of the uncontrolled input.

Chan@\The Chan field is a comma separated list of items of the form n-m,
where n is number of switcher to which the input is connected and m is
the input channel number on the specified switch.  If n is @b[0], then
the uncontrolled input feeds a server virtual output.
@end(description)

@subsection(Sample configuration files)

For a single disk player configuration:
@begin(verbatim)
RPD   BostonDisc SONY_LDP1000A ttyS0   4800  none 0-0
@end(verbatime)

For a fairly complex configuration, with multiple switchers, multiple disk
players, and a forwarding entry:
@begin(verbatim)
# A line beginning with a # is a comment line.
# This first group feeds the little switcher (SWTR-1)
RPD   BostonDisc SONY_LDP1000A  ttyS1   4800   none o:1-1
# The following two feed both another switch, and their own
# virtual output.  This would be ok if the cable system
# output were split and fed to both places.
INPUT MIT-CABLE  ?              ?       ?      ?    1-2,0-3
FORW  flotsam    ?              0       ?      ?    1-2,0-3
INPUT ColorBars  ?              ?       ?      ?    1-3
# This device feeds the AKAI directly, and takes as its input 
# the 2nd output of the AKAI.
RPD   RECORDABLE PANA_3031F     ttyS4   9600   none o:3-1,i:0-1
# The little switch feeds the AKAI, and the default input is 
# ColorBars
SWTR  SWTR-1     ATHENA_4x1     ttyS0   9600   none 1:3;3-2
# The big switch feeds virtual output 0 and 1, and has a 
# default input of SWTR-1, note the way the line is continued
# on multiple lines.
SWTR  SWTR-2     AKAI16x16      0:ttyS3 19200  none 1:2;0-0,\
2:2;0-1

@end(verbatim)