\begindata{text,756992}
\textdsversion{12}
\template{default}
\define{global

attr:[Justification LeftJustified Point 0]
attr:[FontFamily Andy Int 0]}
\define{note
menu:[Region,NOTE]
attr:[LeftMargin LeftMargin Cm 83230]
attr:[RightMargin RightMargin Cm 83230]
attr:[Justification Centered Point 0]
attr:[FontFace Bold Int Set]
attr:[FontFace Italic Int Set]
attr:[FontSize PreviousFontSize Point 4]}
\define{footnote

attr:[Flags OverBar Int Set]
attr:[FontSize PreviousFontSize Point -2]}










\majorheading{\bigger{\bigger{\bigger{\bigger{The Andrew Distribution \


}}}}
\bigger{Version 6.3.1


(August, 1994)


}



}\flushright{\bold{For more information, please contact: \



Andrew Consortium

School of Computer Science

Carnegie Mellon University

5000 Forbes Avenue

Pittsburgh, PA 15213-3890

U.S.A.

(412) 268-6710


Mailing list: info-andrew@andrew.cmu.edu

(info-andrew-request@andrew.cmu.edu for subscriptions)

Newsgroup: comp.soft-sys.andrew

}}

Copyright Carnegie Mellon University 1991, 1994  - All Rights Reserved

Copyright IBM Corporation 1988, 1991 - All Rights Reserved

Additional copyright information can be found in config/COPYRITE.bls

config/COPYRITE.att, and config/COPYRITE.img in both the source and

destination areas.

This product includes software developed by the

University of California, Berkeley and its contributors.

\begindata{bp,752000}
\enddata{bp,752000}
\view{bpv,752000,0,0,0}

$Disclaimer: \


Permission to use, copy, modify, and distribute this software and its \


documentation for any purpose is hereby granted without fee, \


provided that the above copyright notice appear in all copies and that \


both that copyright notice, this permission notice, and the following \


disclaimer appear in supporting documentation, and that the names of \


IBM, Carnegie Mellon University, and other copyright holders, not be \


used in advertising or publicity pertaining to distribution of the software 

without specific, written prior permission.



IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS \


DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING \


ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT \


SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER \


BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY \


DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, \


WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS \


ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE \


OF THIS SOFTWARE.

 $


The following copyright and permission notice apply to versions of the 
Andrew User Interface System distributed previously.  The above notice 
applies to this release.


Copyright Carnegie Mellon University 1991, 1994  - All Rights Reserved

Copyright IBM Corporation 1988, 1991 - All Rights Reserved


Permission to use, copy, modify, and distribute this software and its 
documentation for any purpose is hereby granted without fee, provided that 
the above copyright notice appear in all copies and that both that 
copyright notice, this permission notice, and the following disclaimer 
appear in supporting documentation, and that the names of IBM, Carnegie 
Mellon University, and other copyright holders, not be used in advertising 
or publicity pertaining to distribution of the software without specific, 
written prior permission.

\bold{
IBM, CARNEGIE MELLON UNIVERSITY, AND OTHER CONTRIBUTORS OF THIS SOFTWARE 
DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED 
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ANY PARTICULAR PURPOSE.  IN 
NO EVENT SHALL IBM, CARNEGIE MELLON UNIVERSITY , OR ANY OTHER CONTRIBUTOR 
BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 
WHATSOEVER RESULTING FROM LOSS OF USE, DATA, OR PROFITS, WHETHER IN AN 
ACTION OF CONTRACT, NEGLIGENCE, OR OTHER TORTIOUS ACTION, ARISING OUT OF OR 
IN CONNECTION WITH THE USE OR PERFORMANCE \


OF THIS SOFTWARE.    \


}

\begindata{bp,751872}
\enddata{bp,751872}
\view{bpv,751872,1,0,0}

\chapter{1	Installation Instructions for the Andrew Distribution

}
This document contains instructions for the installation of the Andrew User 
Interface System software, namely the Andrew Toolkit (ATK), and its 
applications, including the Andrew Message System (AMS).  File name 
references found in this document that start with ./ are relative to the 
top-level of the source tree.  \



This release includes innumerable bug fixes and evolutionary improvements 
to many of Andrew's components. Several new system types are supported, 
 including Sun's Solaris, SVR4, SGI, NetBSD (for i386 machines) and Linux. 
 \



\majorheading{***** Quick-Start Instructions for the Impatient  *****}


Copy the template files./config/site.h.tpl to ./config/site.h and 
./config/site.mcr.tpl to ./config/site.mcr.  You should then edit the 
non-tpl files as follows:   ./config/site.h includes your site's 
adjustments to ./config/allsys.h and ./config/system.h.  You should specify 
the location of the DEFAULT_ANDREWDIR_ENV.  ./config/site.mcr contains your 
site's adjustments to macros in ./config/allsys.mcr and 
./config/system.mcr.  You may want to change XINCDIR, XLIBDIR and XINCDIR 
which define the location of your X libraries and utilities.  You should 
 check the other options available below under section 1.2.1 for the 
./config/site.mcr file and section 1.2.4 for the site.h file. \



If you did not pick up auis3.tar.Z (ams and atkams) then you should add the 
following to the ./config/site.h file:


#undef AMS_ENV


If you picked up contrib.tar.Z and you wish to build and install it, then 
you should add the following:


#define CONTRIB_ENV 1


Then check the "Notes on ..." sections later in this document for 
information possibly relevant to your particular system type, or X server. 
 (There are notes for: Decstation Ultrix 4.2 and 4.3, MIPS,SPARC,Open 
Windows server, IBM RS/6000, Sun Solaris, PS/2 AIXv1.2, SCO Unix , HPUX, 
 NeXT, SGI Iris,  and BSD derivatives for 386 class machines.)


If you are going to use gcc you will need to specify this in your site 
files, e.g.:


In site.mcr:

GCCLIB="the full path to your copy of libgcc.a, typically something like 
 /usr/local/lib/gcc-lib/rs6000-ibm-aix/2.3.3/libgcc.a, it should be in 
quotes to prevent macro substitution by imake."

CC=gcc -traditional

(If you encounter problems using gcc -traditional, try gcc 
-fwritable-strings.)


In site.h:

#define GNU_ENV 1


In the top level (directories ./overhead, ./atk, ./ams, ... exist), run the 
following command: \



\leftindent{imake -I. -I./config -Timake.tmpl -s Makefile -DTOPDIR=.}


This will generate the top level Makefile.  Then run:


\leftindent{make World}


While you're waiting, please read the known problems list.  (PROBLEMS in 
the top level of the source tree.)  And read or at least scan the rest of 
this document.


If you installed the console application you will need to make 
$ANDREWDIR/bin/getstats and possibly $ANDREWDIR/bin/getconsole setuid root, 
or setgid to an appropriate group. (often mem or kmem) Typically these 
programs need access to /dev/mem and /dev/console.


Error reports and request for assistance should be sent to 
info-andrew-bugs@andrew.cmu.edu.  \




\section{1.1	Assumptions and Requirements }\heading{\


}
The Andrew Distribution is portable to a number of system types. Andrew is 
able to run on RS/6000 AIX3\{1,2\}, PS/2 AIX1.2, Sun3\{ 3.5, 4.0, 4.1\}, 
 Sun4 \{4.0, 4.1\}, Vax Ultrix 3.1, Vax Ultrix 4.2, Vax BSD, DEC MIPS, SCO 
I386, SGI IRIX 4.0, Apollo, HP, NeXT (under X11), Linux,  NetBSD (for i386 
machines), BSDI/386 (for i386 machines), and Macintosh II MacMach. We run 
it on RS/6000 AIX3.1 and AIX3.2, Sun 4 Mach, Pmax Mach, Pmax Ultrix 4.2, 
Linux, and HP UX.  \



As shipped, the Andrew distribution is about 50 megabytes of source that 
generates many megabytes of object files, libraries, fonts and applications 
(where the exact amount of object space varies with each machine). The 
default configuration generates about 70 megabytes; changing that 
configuration to include building everything generates about 120 megabytes. 
If you do not have sufficient disk space, the procedures for building a 
partial system are described later in this document.


In addition to space requirements, the distribution assumes that you have 
the X Window System Distribution from MIT, which contains the following 
files and programs:

\leftindent{
\bold{imake} -- part of program construction (makefile) facility

\bold{bdftosnf or bdftopcf} -- font compiler

\bold{makedepend} --part of program construction (makefile) facility

\bold{Xlib} -- X.V11 include files and libraries

}
\section{1.2	Modifying the Configuration Files \


}
The construction and installation of Andrew requires a local site to 
provide a variety of information to the construction process:


\leftindent{a. What kind of machine and operating system are being used

b. Location of various pieces of system software (including the X 
distribution)

c. Location and configuration of services for the installed Andrew system}


This information is conveyed to the build process through various 
configuration files. This section describes each of the major configuration 
files and how an installer should edit them for a local site.


Through the use of various switches ("DEFINE"s), one can control how much 
of the system is built and select the appropriate operating system and 
machine dependent pieces. Because of the large size of the system, many 
options are provided. Definitions that you must provide are described in 
this section. Optional definitions are described later.


Before building Andrew, you should look through the several files that 
configure the system, and change them as necessary so that the Andrew 
software will be built and installed correctly for your environment. Each 
file, and the modifications you might want to make to it, are explained 
below. Looking from the top of the extracted source tree, the files are:


	./config/allsys.mcr

	./config/<machine>/system.mcr

	./config/site.mcr	 (your site's adjustments to allsys.mcr and system.mcr)


	./config/allsys.h

	./config/<machine>/system.h

	./config/site.h	(your site's adjustments to allsys.h and system.h)


	./atk/console/lib/sitevars.h

	./overhead/util/lib/svcconf.c

	./overhead/mail/lib/mailconf.c

	./helpindex/index.tpl


where "<machine>" is the machine type on which you plan to install and 
build Andrew. The (intended) available machine types are:


Machine Type		Operating System		<machine>


\typewriter{IBM RT			AOS December 1988	rt_aos4

IBM RT			AIX 2.2.1			rt_aix221

IBM RS/6000		AIX 3.1, 3.2		rs_aix3

IBM PS/2 M70/80	AIX 1.2			ps_aix12 \


Sun 3			SunOS 3.5			sun3_35

Sun 3			SunOS 4.0			sun3_4

Sun 3			SunOS 4.1			sun3_41

Sun 4			SunOS 4.0			sun4_40

Sun 4			SunOS 4.1			sun4_41

DEC Vax			Ultrix 3.0		vax_3

DEC Vax			BSD (4.3)			vax_43

HP 300			HP UX			hp300

HP 900			HP UX			hp800

386/486			Linux			i386_Linux

386/486			NetBSD			i386_bsd

386/486			BSDI/386		i386_bsdi (new, untested)

Macintosh II		MacMach			mac2_51

Apollo			DomainOS			apollo68k

DEC MIPS			Ultrix 3.0		pmax_3

DEC MIPS			Ultrix 4.1		pmax_41

DEC MIPS			Ultrix 4.2		pmax_ul4

DEC MIPS			Ultrix 4.3		pmax_ul4 (using cc, not gcc)

SGI				IRIX 4.0			sgi_4d

SCO				SCO				sco_i386

NeXT				NeXt Mach 2.0		next_mach20

}

A new document is included in the ./config directory, Porting.doc.  This 
document provides general rules for porting AUIS to a new platform.  \



\subsection{1.2.1	The allsys.mcr, system.mcr, and site.mcr\bold{\{.tpl\}} 
Files}


\bold{./config/allsys.mcr, ./config/\bold{<}}\bold{machine>/system.mcr, 
./config/site.mcr} -- The definitions in these files specify where to find 
various programs, include files, and libraries for building Andrew. The 
definitions that are likely to change are clustered near the top of the 
allsys.mcr file.  \



Definitions in these files are structured so that definitions in allsys.mcr 
come first, then system-dependent overrides in system.mcr, then 
site-specific overrides in site.mcr. \



You should NOT edit either allsys.mcr or your system.mcr. Instead, an empty 
./config/site.mcr.tpl template file is distributed.  Copy 
./config/site.mcr.tpl to ./config/site.mcr then you can make your edits. 
 This overrides the values specified in ./config/allsys.mcr and 
./config/<machines>/system.mcr.  You can override #define'd macros in your 
site.h file by using both #undef and #define, possibly within #fidef/#endif 
pairs.  You can override make variables in your site.mcr file by using 
lines such as ``FOO=bar''.  You may also use #ifdef/#endif pairs to select 
which make variable settings should be used. (Make does lazy evaluation of 
its $(FOO) variables, so it's reasonable to override variables such as 
XUTILDIR in site.mcr.  \



In the simplest case, you would copy ./config/site.mcr.tpl to 
./config/site.mcr,  which results in the following default values:  \



\bold{GCCLIB}			[Default: none]


\indent{GCCLIB specifies where the libgcc.a library is located.  This 
library is needed when compiling with gcc.

}
\bold{BASEDIR}		[Default: DEFAULT_ANDREWDIR_ENV, from ./config/allsys.h - 
can be overridden in ./config/site.h] \


\bold{
}\indent{BASEDIR specifies where you want the root of the installed Andrew 
tree of system software. It is not possible to build Andrew without 
installing it. This directory will have several subdirectories created 
under it during the build process, including: \italic{include}, 
\italic{bin}, \italic{lib}, \italic{dlib}, \italic{etc}, \italic{doc,} and 
\italic{help}. The value for BASEDIR is the path in which the installation 
process should put the Andrew system software, while the value for 
DEFAULT_ANDREWDIR_ENV (cf. section 1.2.5) is the path via which users, by 
default, will execute that software. To override this value, edit your 
site.mcr file, or override DEFAULT_ANDREWDIR_ENV in your site.h file.


BASEDIR must be different from the root of your copy of the source tree. 
That is, in general, when you start, BASEDIR will point to an empty 
directory.

}
\bold{DESTDIR}		[Default: $(BASEDIR)] \


\bold{
}\indent{DESTDIR should always be identical to BASEDIR for system builds. \



DESTDIR may be set to other values \bold{only} in the course of local 
Andrew-based development.  \



For the Andrew build, this value will always be BASEDIR.  But for 
developers of Andrew-based software who want to install their binaries, 
this value may be set to a location specifying a local binary tree.  \



}\bold{AFSBASEDIR}	[Default: /usr/local] \


\leftindent{
AFSBASEDIR denotes the full path to files exported by an AFS (Andrew File 
System) installation. (AFS is a distributed file system available from 
Transarc Corporation. For more information, please send mail to 
afs-sales+@transarc.com.)  It is used only if AFS_ENV is defined; 
otherwise, it is ignored entirely. If it is used, it is presumed that 
AFSBASEDIR/include/afs, AFSBASEDIR/lib/afs, and AFSBASEDIR/bin exist. Other 
specific requirements are listed in the discussion of AFS_ENV and AFS30_ENV 
in the section describing the *.h files.


The default value is /usr/andrew . Override it in your site.mcr file if you 
need to.\indent{

}
}\bold{WMBASEDIR}	[Default: ]


\indent{WMBASEDIR can be used to specify the root location of the old ITC 
window manager (WM) include files and libraries. WM is no longer supported 
by the ITC. If you specify this macro then you should also define WM_ENV in 
your site.h file (see sect. 1.2.4). If WM_ENV is defined and WMBASEDIR is 
specified, it is presumed that $(WMBASEDIR)/lib/libwm.a and 
$(WMBASEDIR)/include/\{font.h,wmclient.h\} exist.


There is no default value for WMBASEDIR. Set WMBASEDIR in your site.mcr 
file if you want to run ATK applications with WM.

}
\bold{CDEBUGFLAGS}	[Default: -O] \


\bold{
}\indent{CDEBUGFLAGS are passed to the C compiler when compiling programs.

}
\bold{XBASEDIR}		[Default: /] \



\leftindent{XBASEDIR should point to the root of your installed X tree. X 
include files are assumed to be in $(XBASEDIR)/usr/include/X11. Xlib and 
bdftosnf are also found in this tree. If your compiler cannot handle paths 
like ``//usr/include/X11'' (with the double slash), you may wish to 
redefine this as the null string.}


\indent{
}\description{\bold{XINCDIR}	[Default: $(XBASEDIR)/usr/include] \



\bold{XLIBDIR}		[Default: $(XBASEDIR)/usr/lib] \


\bold{
XBINDIR	}	[Default: /usr/bin/X11]


}\leftindent{XBINDIR should point to the location of the X bin directory 
under the XBASEDIR.  Do not include XBASEDIR in your definition of 
XBINDIR}\description{


\bold{XUTILDIR}	[Default: /usr/bin/X11]


}\leftindent{As is the case with XBINDIR, XUTILDIR should also point to the 
location of the X bin directory under the XBASEDIR.  Do not include 
XBASEDIR in your definition of XUTILDIR

}\description{
\bold{IMAKE}		[Default: $(XUTILDIR)/imake] \



\bold{XMAKEDEPEND}	[Default: $(XUTILDIR)/makedepend] \


\bold{
}}\indent{IMAKE and XMAKEDEPEND need to be full paths to the X11 imake and 
makedepend programs. These are not normally installed as a part of X11, but 
are found in the X11 source tree in util/imake/imake and 
util/makedepend/makedepend. You can set either IMAKE and XMAKEDEPEND, or 
XUTILDIR, to point to the appropriate place.

}\description{
\bold{XMKFONTDIR}	[Default: $(XBASEDIR)/$(XBINDIR)/mkfontdir] \



\bold{XFC}			[Default:

	RELEASE2_ENV implies $(XSRCDIR)/fonts/compiler/fc,

	FONTS_TO_PCF_ENV implies $(XBASEDIR)/$(XBINDIR)/bdftopcf,

	otherwise $(XBASEDIR)/$(XBINDIR)/bdftosnf] \


	\


\bold{XSRCDIR}		[Default: empty string] \


}
\indent{These are miscellaneous X-related absolute paths. XINCDIR needs to 
point to where your X include files are installed; it is used in the Andrew 
build process. XMKFONTDIR needs to point to the ``mkfontdir'' program from 
the X installation. XLIBDIR needs to point to where libX11.a is installed. 
 XFC should point to the ``bdftosnf'' font processor. Under RELEASE2_ENV, 
XSRCDIR should point to the top of an X11 source tree for the definition of 
XFC, but is otherwise not used.

}
\bold{RESOLVLIB}	[Default: empty string] \


\bold{
}\indent{RESOLVLIB denotes the full path of the domain name resolver 
library.  If RESOLVER_ENV is defined and the resolver functions are not in 
libc.a then RESOLVLIB should be set to the library which contains these 
functions, otherwise RESOLVLIB should be empty.  The default value (the 
empty string) is useful if the resolver code is in your libc.a. If the 
resolver code is in a separate library, such as /usr/lib/libresolv.a, that 
name should be the definition for RESOLVLIB; define it in your site.mcr 
file.


The programmer's interface to the resolver library has changed over time. 
The file ./overhead/mail/lib/valhost.c (which is built into 
DESTDIR/lib/libmail.a) makes calls to different versions of that 
programmer's interface, using the fact that definitions in the resolver's 
exported ``include'' files changed slightly with successive releases. In 
particular, it checks for the definition of NO_DATA in the 4.8 version of 
/usr/include/netdb.h and for the definition of CQUERYM in the pre-4.7.3 
version of /usr/include/arpa/nameser.h. If your versions of these include 
files correspond to the version of the resolver named by RESOLVLIB (or 
libc.a otherwise), you will have no trouble with its interface to Andrew. 
The ./overhead/mail/lib/valhost.c file contains suggestions for what to do 
if this is not the case.}\indent{

}
\bold{INSTALL}		[Default: $(BASEDIR\}/etc/install] \


\bold{
}\indent{INSTALL denotes the name of the install program on your system. If 
you do not have an install program, or if your install program does not 
work, edit the site.h file and:

}
\example{#define BUILDANDREWINSTALL_ENV  1}


\indent{and then re-make your Makefiles (if already made) and continue from 
there. (The setting of INSTALL is based upon the setting of 
BUILDANDREWINSTALL_ENV and will be picked up correctly if set in the 
./config/site.h file.)

}\formatnote{
}Additional definitions are unlikely to change. However, you may want to 
check these values:


\bold{SHELL}		[Default: /bin/sh] \


\bold{
}\indent{SHELL specifies the path to the Bourne shell.

}
\bold{CSHELL}		[Default: /bin/csh] \


\bold{
}\indent{CSHELL specifies the path to the C shell.

}
\bold{CC}			[Default: cc] \


\bold{
}\indent{C compiler to use. On the IBM RT/PC, it is the hc Metaware 
compiler. On other systems, it is the pcc compiler.

}
\bold{ConstructMFLAGS}	[Default: not defined]


\indent{Define ``ConstructMFLAGS'' in your site.mcr if your make program 
accepts MAKEFLAGS but not MFLAGS.}


\subsection{1.2.2	The sitevars.h File}


\bold{./atk/console/lib/sitevars.h} -- contains defines indicating default 
values for the console program. You probably need to be concerned with only 
the following entries:

\description{\bold{
_SITE_NON_ANDREW_MAIL}		[Default: /usr/spool/mail]

\bold{
}\indent{Directory where console should look to see if incoming mail has 
arrived.}


\bold{_SITE_NON_ANDREW_PRINTDIR}	[Default: /usr/spool/lpd]

\bold{
}\indent{Directory where console should look to see if any outstanding 
printing requests are waiting.

}
\bold{_SITE_LOGFILE		}[Default: /tmp/ConsoleLog]

\bold{
}\indent{Default file where console logs should be written when requested 
by the user of console.

}
\bold{_SITE_MTAB		}[Default: /etc/mtab]

\bold{
}\indent{File that console should use for obtaining information about the 
mounted file systems.

}
\bold{_SITE_BIN_SH		}[Default: /bin/sh]

\bold{
}\indent{Default shell to use for exec'ing sub-programs.

}
\bold{_SITE_DEV_TTY		}[Default: /dev/tty]\bold{

}\indent{
}
\bold{_SITE_DEV_PTYP		}[Default: /dev/ptyp]\bold{

}\indent{
}
\bold{_SITE_DEV_CONSOLE	}[Default: /dev/console]

\bold{
}\indent{Stream that console intercepts for its log (actually, its 0th 
log).

}
\bold{_SITE_DEV_KMEM	}[Default: /dev/kmem]

\bold{
}\indent{Device that console should use to obtain memory statistics.

}
\bold{_SITE_VMUNIX		}[Default: /vmunix]

\bold{
}}\indent{\description{File where console should get information about the 
kernel's symbol table.}

}

\subsection{1.2.3	The mailconf.c and svcconf.c Files}


\bold{./overhead/util/lib/svcconf.c and ./overhead/mail/lib/mailconf.c} -- 
These files contain configuration information for the mail system. You will 
not likely have to change anything in this file; instead, once the system 
is built, you will be able to change these options via the AndrewSetup 
mechanism. The details concerning the information in this file can be found 
in the AndrewSetup documentation (./overhead/util/lib/setup.help), the 
Andrew Message System Installation manuals (in ./ams/doc), the Andrew 
Message Delivery System Installation manual (./ams/doc/AMDS.ins), and in 
the White Pages installation manual (./overhead/util/lib/WP.ins).


After making your initial system build, but before expecting the 
mail-related software to work, you should review the AndrewSetup help file 
to check whether the settings for the available options are correct for 
your system.


If you have problems bringing up the mail system and you believe that it is 
a result of information contained in the svcconf.c or mailconf.c files, you 
should send mail to: \



\leftindent{info-andrew-bugs@andrew.cmu.edu

}

\subsection{1.2.4	The allsys.h, system.h, and site.h\bold{\{.tpl\}} Files: 
Defining What Parts of Andrew to Build}


\bold{./config/allsys.h, ./config/\bold{<mach}}\bold{ine>/system.h, 
./config/site.h} -- These files specify several things: what parts of 
Andrew will be built, where the resulting systems should be placed, and 
what flags and facilities are available for that build. This section, 
1.2.4, describes the options in ./config/<machine>/system.h that select 
what parts of Andrew will be built. The next section, 1.2.5, describes the 
options in ./config/<machine>/system.h that specify where the Andrew system 
is to be installed and what facilities are available for its use.


Definitions in these files are structured so that definitions in allsys.h 
come first, then system-dependent overrides in system.h, then site-specific 
overrides in site.h.


You should NOT edit either ./config/allsys.h or ./config/system.h. Instead, 
an empty ./config/site.h.tpl file is distributed.  Copy the template file 
./config/site.h.tpl to ./config/site.h   You should then edit the non-tpl 
files to override what has come before. (You can do this using both #undef 
and #define.)


In the simplest case, you would copy ./config/site.h.tpl to 
./config/site.h,  which results in all facilities being built into 
/usr/andrew. The success of this simplest case, however, depends on the 
assumptions made in ./config/allsys.h and ./config/<machine>/system.h being 
correct for your environment, so you may need to review the options 
described in section 1.2.5. \



The default settings for this first group of options will build only a 
portion of the Andrew system. This includes the basic editor and 
typescript, the help system, a number of objects (including text, c-text, 
raster, spreadsheet/table, drawing, animation and equations), and the 
messages interface programs (messages, cui, vui). The set has been chosen 
to allow you to view most of the messages demonstration folder. You may add 
other parts of the system by defining the appropriate flags in your 
./config/site.h file. You can also choose to build a smaller portion of the 
system by undefining the appropriate flags. A description of the space 
requirements for setting certain switches is presented later in this 
document.


\bold{AMS_ENV}				[Default: defined]

\bold{
}\indent{AMS_ENV is defined if the Andrew Message System should be built. 
This is the messages program and related libraries and programs.  This 
distribution also contains Metamail.  See METAMAIL_ENV.  If you did not 
pick up auis3.tar.Z (ams and atkams) then you must undefine AMS_ENV by 
adding the following line to your ./config/site.h file: \



\indent{\typewriter{#undef AMS_ENV}}


}\bold{AMS_SUBSCRIPTIONMAPFILE}		[Default: ".SubscriptionMap" or 
".SubsMap"]


\leftindent{This is the name of one of the files AMS uses to store 
information about the bboards which exist.  For historical reasons it 
defaults to .SubscriptionMap unless compiling on an HP or a SysV system 
(where M_UNIX is defined).  The reason for the distinction is the 
limitation of these systems to 14 character filenames.   If bboards will be 
stored on filesystems with this limitation all clients which access them 
must be compiled with:


\example{#define  AMS_SUBSCRIPTIONMAPFILE ".SubsMap" }\



in the site.h file.


If HP or SysV systems without the 14 character limit on filenames are used 
all clients should be compiled with:


\example{#define  AMS_SUBSCRIPTIONMAPFILE ".SubscriptionMap"

 }\


If you're not sure and don't have any existing AMS bboard trees the 
".SubsMap" setting is safe for all systems.  If you have an existing AMS 
bboard tree you can check which setting to use with ls -a 
..../.MESSAGES/.Subs*  (Where .... is replaced with the path to the top of 
the bboard tree.) \


}
\bold{METAMAIL_ENV}			[Default: not defined]


\indent{Metamail is an implementation of MIME, the Multipurpose Internet 
Mail Extensions, a proposed standard for multimedia mail on the Internet.


Set MK_METAMAIL to build the version of Metamail that comes with this 
distribution and define METAMAIL_ENV if you are going to use it.  Some AMS 
code takes advantage of Metamail and METAMAIL_ENV is used to communicate 
that metamail is installed on the system.  Metamail is also distributed 
through other channels so, if you've already picked it up from elsewhere 
you would want to #define METAMAIL_ENV while not defining MK_METAMAIL.

}
\bold{AMS_DELIVERY_ENV}		[Default: not defined]

\bold{
}\indent{AMS_DELIVERY_ENV is defined if the Andrew Message Delivery System 
is to be built, regardless of whether it is expected to be used locally. 
Also see RUN_AMDS_ENV in a following section. \



\bold{Note}: The mail and sendmail programs will not automatically be 
replaced with the versions that call AMS. You must install these programs 
by hand after the system has been built successfully. These programs will 
be built and will be located in ./ams/delivery/\{mail,sendmail\}.

}
\bold{WHITEPAGES_ENV}			[Default: not defined]

\bold{
}\indent{WHITEPAGES_ENV is defined if the white pages facility (including 
phonetic name lookup) is to be built and used by the Andrew Message System.

}
\bold{SNAP_ENV}				[Default: not defined]

\bold{
}\indent{SNAP_ENV is defined if the Message Server is to be built.

}
\bold{WM_ENV}				[Default: not defined]

\bold{
}\indent{WM_ENV should be defined if you want to build the Andrew Toolkit 
to run on the unsupported ITC Window Manager (WM) which is not provided in 
this distribution. You can specify the root location of your WM include 
files and libraries by defining WMBASEDIR in your site.mcr file. }\bold{\



X11_ENV}				[Default: defined]

\bold{
}\indent{X11_ENV is defined if the Andrew Toolkit is to be built for the 
X.11 Window System.

}
\bold{PRE_X11R4_ENV}			[Default: not defined]


\indent{PRE_X11R4_ENV should be defined if you will be linking against X11 
header files and libraries that come from versions of X11 prior to the 
fourth release (X11R4). This information is needed because release 4 
defines some new variable types and makes use of ANSI C function 
prototypes.


}\bold{DPS_ENV}				[Default: not defined]


\indent{DPS_ENV should be defined if your systems support the Display 
PostScript extension to X Windows. IBM's X.V11R3 server product, DEC's 
DecWindows product, and Sun's Solaris 2.3 all have this extension, while 
the MIT servers typically do not. Defining this variable will cause some 
code to attempt to link against the DPS libraries. It will also cause some 
code to attempt to contact the DPS extension of an X server at runtime.

}
\bold{ANDREW_MALLOC_ENV}	[Default: defined]

\bold{
}\indent{ANDREW_MALLOC_ENV, if defined, causes the Andrew Toolkit memory 
management package to be used. This memory allocator package not only saves 
VM space but also provides more error detection, when compared to many of 
the memory allocators distributed with Unix systems. On some system 
platforms, use of this allocator has led to multiply defined symbols. If 
this occurs, you can undefine this symbol and rebuild atk/basics and 
atk/apps.

}
\bold{DEBUG_MALLOC_ENV}		[Default: not defined]

\bold{
}\indent{DEBUG_MALLOC_ENV is defined if the debugging version of the Andrew 
Toolkit memory management package should be used. Its definition implies 
the definition of ANDREW_MALLOC_ENV.

}
\bold{SITE_ENV}				[Default: not defined]


\indent{SITE_ENV controls the construction of site specific Andrew 
applications. The source for such applications are meant to be placed in 
the directory ./site. See further documentation in ./site/README.site.

}
\bold{NO_FONTS_ENV}			[Default: not defined]


\indent{NO_FONTS_ENV controls whether or not the Andrew fonts will get 
built. Some sites, that make heavy use of Xterminals or support many 
different display types, may find it convenient to not convert the fonts to 
any specific server format. By default this symbol is not defined and, 
thus, the fonts are created and installed during the build process. Define 
this symbol in your ./config/site.h file if you do not want the Andrew 
fonts to be built.

}
\bold{FONTS_TO_BDF_ENV} 		[Default: not defined]


\indent{FONTS_TO_BDF_ENV controls whether or not the Andrew fonts will be 
converted into their Server Normal Format (.snf) during the build process. 
It may be convenient to leave the fonts in Bitmap Distribution Format 
(.bdf) when it is necessary to convert these to various different Server 
Normal Formats corresponding to the various X servers that may exist at 
your site. If you define this symbol the result will be that all of the 
Andrew fonts will be installed into $\{DESTDIR\}/X11fonts in BDF. You can 
then run self-created font conversion scripts to go to the various final 
formats.}\bold{


FONTS_TO_PCF_ENV}		[Default: defined]


\indent{FONTS_TO_PCF_ENV controls whether the Andrew fonts will be 
converted into the .pcf format during the build process. If this is 
defined, you should ensure that XFC is a valid path to your bdftopcf 
compiler.}\bold{


OPENWINDOWS_ENV}		[Default: not defined]


\indent{If you want to run Andrew applications under Open Windows, define 
this symbol in your site.h file. If you define this symbol, you should set 
your path to include the Open Windows binaries (usually /usr/openwin/bin). 
Open Windows is available only on Sun platforms. As such, all Sun site 
files define a CONVERTFONT macro to be /usr/openwin/bin/convertfont. You 
can override this default value in your ./config/site.mcr file. }\



\bold{OLD_ULTRIX_ENV}		[Default: not defined]


\indent{Some older version of the Ultrix operating system had a bug that 
caused passwords to be echoed in the typescript program. Define this symbol 
in your ./config/site.h file if you are using a version of Ultrix that has 
this bug.

}\bold{
CONTRIB_ENV}			[Default: not defined]

\bold{
}\indent{CONTRIB_ENV controls the construction of the contributed software 
found under source directory ./contrib. At present, this includes a growing 
collection of interesting and valuable utilities and objects, including 
various classes for viewing programming language text files, a slew of 
utilities and classes submitted by MIT (such as header/footer, note, ps), 
an audio inset from Bell Labs, a subclass of textview that recognizes 
gestures (gtextv), and the termulator shell interface (tm).


In order to build the ./contrib section, you need to pick up the 
contrib.tar.Z file from the ftp server.  \


}
\bold{DOC_ENV}				[Default:  not defined]


\indent{DOC_ENV controls the installation of the documents in the ./doc 
directory.  You should define DOC_ENV in your ./config/site.h file if you 
would like to have the documents installed.   \


}
\indent{
}\bold{ISO80_FONTS_ENV}		[Default: defined]


\indent{ISO80_FONTS_ENV controls which text fonts are used by Andrew 
applications. If ISO80_FONTS_ENV is defined, then a font.alias file is 
installed $ANDREWDIR/X11fonts to supply pointers to the X11 fonts that 
comply with the ISO 8859 defined international character set. For sites 
that have these fonts, this is the preferred option, since it will make 
accented characters available to users and programmers in most 
applications, including messages. See the cpchar help file for details on 
how to use them. This option also provides better behavior when used with 
R5's scalable fonts, and with 100dpi fonts, and it also eliminates the need 
for additional fonts to be installed in the destination directory. The only 
known drawback is that these fonts are not as carefully tuned as the their 
Andrew counterparts.}


\bold{MK_BASIC_UTILS}			[Default: not defined]\bold{

MK_BASIC_INSETS}			[Default: defined]\bold{

MK_BLD_BLKS}				[Default: defined]

\bold{MK_HELP	}				[Default: defined]\bold{

MK_TEXT_EXT	}			[Default: defined]\bold{

MK_AUTHORING}			[Default: not defined]\bold{

MK_AUX_UTILS}			[Default: not defined]\bold{

MK_AUX_INSETS}			[Default: not defined]\bold{

MK_EXAMPLES}			[Default: not defined]\bold{

MK_METAMAIL}			[Default: defined]

\bold{MK_CALC				}[Default:\bold{ }not defined] (in contrib)

\bold{MK_CHAMP}				[Default:\bold{ }not defined] (in contrib)

\bold{MK_ZIP}					[Default:\bold{ }not defined] (in contrib)


\indent{These flags control the building of groups of software; the core of 
the ATK is \italic{not} dependent upon these flags, but will be built if 
any part of the ATK is built. Normally, these flags are all defined.


\leftindent{\smaller{MK_BASIC_UTILS 	(= console + ezprint + preview + 
launchapp)

MK_BASIC_INSETS 	(= eq + fad + table + layout)

MK_BLD_BLKS 	(= apt + org + bush + chart + figure)

MK_HELP 		(= rofftext + help)

MK_TEXT_EXT 	(= srctext + lookz)

MK_AUTHORING 	(= controllers + music + ness + createinset + layout)

MK_AUX_UTILS 	(= datacat + toez + prefed )

MK_AUX_INSETS 	(obsolete)

MK_EXAMPLES 	(= examples)}}


If you only want to build part of one (or more) of these groups, a flag 
MK_<SUBDIRECTORY> can be used to specify the ones you want to build; i.e.:

}
\indent{\indent{\smaller{MK_APT

MK_BUSH

MK_CALC		(CONTRIB_ENV must also be set)

MK_CHAMP	(CONTRIB_ENV must also be set)

MK_CHART

MK_CONSOLE

MK_CONTROLLERS

MK_CREATEINSET

MK_SRCTEXT   (includes ctext)

MK_DATACAT

MK_EQ

MK_EXAMPLES

MK_EZPRINT

MK_FAD

MK_FIGURE

MK_HELP

MK_LOOKZ

MK_MUSIC

MK_NESS

MK_ORG

MK_PREFS		(otherwise known as prefed)

MK_PREVIEW

MK_ROFFTEXT

MK_TABLE

MK_TOEZ

MK_ZIP		(CONTRIB_ENVmust also be set)

}}}
\indent{The ATK Imakefile (./atk/Imakefile), that uses these flags, has 
been fairly carefully set up so that it will build parts of the toolkit to 
support the parts that you ask to be built; in other words, it knows about 
the various inter-dependencies. Thus even if you don't have MK_AUTHORING 
set, it will build 'value' if you have AMS_ENV set, because it knows that 
the program 'Messages' uses the 'value' inset.}


The ./contrib/Imakefile uses MK_CALC, MK_CHAMP, MK_ZIP to decide whether to 
build those programs.  It builds tm except on the SGI Iris.  alink is built 
only on Sun Sparcs.  If AMS_DELIVERY_ENV is defined the pobbconf directory 
will be built. (it consists of utilities for running the post office 
machines needded by AMDS.)  If AMS_ENV is defined the eatmail program will 
be built.  (This program incorporates mail from a normal Unix spool mail 
file into the AMS mailbox.)


The programs \bold{\typewriter{rtf2}}, \bold{\typewriter{2rtf}}, and 
\bold{\typewriter{scribetext}} are located in ./contrib/mit.  These 
programs are only built if CONTRIB_ENV is defined as well as RTF_ENV (for 
2rtf & rtf2) or SCRIBETEXT_ENV (for scribetext).  These programs are not 
built by default.


\bold{RTF_ENV}	[Default:  not defined]

\leftindent{2rtf takes an ATK datastream file and produces an RTF file 
capable of being used by Microsoft Word.  Alternately, rtf2 takes an rtf 
compatible file and produces an ATK datastream file capable of being used 
by ATK client programs. }\



\bold{SCRIBETEXT_ENV} 	[Default:  not defined]

\leftindent{Scribetext takes a Scribe compatible manuscript file and 
produces an ATK datastream file capable of being used by ATK client 
programs. \


}
\bold{NEOS_ENV} 	[Default:  not defined]

\leftindent{Neos is a system for the electronic submission and grading of 
papers.  It requires Kerberos.

}
\subsection{1.2.5	The ./config/allsys.h, ./config/<machine>/system.h, and 
./config/site.h Files: Describing Your Environment}


The ./config/allsys.h, ./config/<machine>/system.h, and ./config/site.h 
files also contain a number of flags that need to be set appropriately for 
your environment, describing whether or not various facilities are 
available, where and how the software is to be installed, etc.


\bold{LINKINSTALL_ENV}		[Default: not defined]


\bold{\indent{WARNING:  As of Release 6.0, this installation option has not 
been thoroughly tested and may not compile cleanly.  It should NOT be used, 
we cannot support it.}

}\indent{LINKINSTALL_ENV controls the method by which constructed files are 
installed. The choice is to copy or link the files. If LINKINSTALL_ENV is 
defined, the destination tree is constructed as a symbolic link tree, 
rather than actually installing (copying) the binaries, libraries, etc. 
into $(DESTDIR). \



}\bold{POSIX_ENV}				[Default: system dependent]\indent{ \


}
\leftindent{You will normally not need to modify this symbol.  When defined 
this symbol causes code mostly conformant to POSIX to be used where 
available.  (The code is by no means completely conformant, and some old 
BSD-style code probably still persists.)


}\bold{CLASS_CTRAMPOLINE_ENV}  	[Default: system dependent]


\leftindent{When this preprocessor macro is defined the usual method of 
dispatching class procedures is modified to avoid the need for an assembly 
language "trampoline" routine.  This symbol is defined to 1 in the system.h 
files for hp700_80, hp800_80, and telmat_svr4.  Generally this symbol 
should only be set in the system.h file for an architecture where it is not 
feasible to write the assembly language trampoline code.}

\leftindent{
}\bold{ANSI_COMPILER}			[Default: system/compiler dependent]


\indent{You will normally not need to modify this symbol.  When not defined 
this symbol causes special measures to be taken to compile some code. 
 (Particularly in ./overhead/image.)}


\bold{AFS_ENV}				[Default: not defined]

\indent{(note: if AFS_ENV is defined, then WHITEPAGES_ENV should also be 
defined. Even if you don't intend to actually use the white pages.)}\bold{

}\indent{AFS_ENV is defined if the Andrew File System is being used. This 
is a distributed file system available from Transarc Corporation. For more 
information, please send mail to afs-sales+@transarc.com.   If AFS_ENV is 
defined, it is assumed that the following files will be available under 
AFSBASEDIR :}\indent{

\indent{include/afs/afsint.h include/afs/auth.h include/afs/cellconfig.h 
include/afs/print.h include/afs/prserver.h include/afs/comauth.h 
include/afs/auth.h include/afs/errors.h include/afs/prs_fs.h 
include/afs/venus.h include/afs/vice.h include/rx/xdr.h lib/afs/libauth.a 
lib/afs/libsys.a lib/librx.a lib/liblwp.a

}If SNAP_ENV is also defined, other files needed under AFSBASEDIR are:

\indent{lib/afs/librauth.a lib/afs/libacl.a lib/libr.a lib/libscrypt.a

}If RUN_AMDS_ENV is also defined, so that ./contrib/pobbconf will be built, 
AFSBASEDIR/bin/fs will also be needed.

}
\bold{AFS30_ENV}				[Default: not defined]

\bold{
}\indent{AFS30_ENV is defined if version 3.0 or later of the Andrew File 
System (including the protection server) is being used. If AFS30_ENV is 
defined, so should AFS_ENV be. If this is defined, it is assumed that the 
following files will be available under AFSBASEDIR, in addition to those 
listed in the basic AFS_ENV discussion:

\indent{include/afs/acl.h include/afs/prclient.h include/afs/prerror.h 
lib/afs/libprot.a lib/libubik.a lib/librxkad.a lib/libscrypt.a 
lib/afs/libcom_err.a

}}
\bold{AFS31_ENV}				[Default: not defined]


\indent{AFS31_ENV is defined if version 3.1 or later of the Andrew File 
System (including the protection server) is being used. \bold{If AFS31_ENV 
is defined, so should AFS30_ENV be.} If this is defined, it is assumed that 
the following files will be available under AFSBASEDIR, in addition to 
those listed in the basic AFS_ENV discussion:


\indent{lib/afs/libdes.a

}}
\bold{RUN_AMDS_ENV}			[Default: not defined]

\bold{
}\indent{RUN_AMDS_ENV is defined is the Andrew Message Delivery System is 
to be run at the site. This option affects only the default option values 
in mail system configuration, specified in the files 
./overhead/util/lib/svcconf.c and ./overhead/mail/lib/mailconf.c, and 
whether /bin/mail and /usr/lib/sendmail are replaced with stubs that call 
AMDS. See AMS_DELIVERY_ENV in the previous section for actually building 
the delivery system.

}
\bold{RESOLVER_ENV}			[Default: defined]

\bold{
}\indent{RESOLVER_ENV is defined if the Internet Domain Name Resolver is to 
be used. See also the discussion for the symbol RESOLVLIB in the section 
describing the *.mcr files, because if RESOLVER_ENV is defined, RESOLVLIB 
will be used as the path to the resolver library routines.  If you undefine 
RESOLVER_ENV in your site.h file you should set RESOLVLIB to be empty in 
your site.mcr file.

}
\bold{DITROFF_ENV}			[Default: defined]

\bold{
}\indent{DITROFF_ENV is defined if ditroff is available for printing Andrew 
Toolkit documents. (See Section 4 Printing.)

}
\bold{DEFAULT_ANDREWDIR_ENV}	[Default: /usr/andrew]\bold{

}
\indent{DEFAULT_ANDREWDIR_ENV should be the pathname of the top of the 
installed tree containing Andrew software. This value is the pathname by 
which users will, by default, execute the Andrew software; for example, it 
is used by some Andrew software to know, at execution time, where other 
pieces of installed Andrew facilities may be found. This value may differ 
from the value for BASEDIR in ./config/\{allsys.mcr, system.mcr, site.mcr\} 
if, for instance, all the Andrew software is to be built using one path, 
and executed using another path.


Because Andrew software uses dynamic binding of information, it needs to 
know where to find various installed objects, libraries and files. The 
software assumes that everything will be found relative to the installed 
Andrew tree. The pathname of the top of the tree is, by default, 
$(DEFAULT_ANDREWDIR_ENV). If, however, you have not installed the Andrew 
software in $(DEFAULT_ANDREWDIR_ENV), you may override the software's idea 
of where the Andrew installation is to be found. This value may be 
overridden by each user's setting the environment variable $ANDREWDIR to 
another pathname, or by the administrator using the AndrewSetup mechanism 
(see ./overhead/util/lib/setup.help) and specifying a value for the 
``AndrewDir:'' attribute.


See the discussion under LOCAL_ANDREW_SETUP_ENV.

}
\bold{LOCAL_ANDREW_SETUP_ENV}	[Default: not defined]

\bold{
}\indent{The AndrewSetup mechanism, described in 
./overhead/util/lib/setup.help, is used for specifying system options to 
Andrew software at execution time. LOCAL_ANDREW_SETUP_ENV is defined if an 
additional path (or paths) for the AndrewSetup file should be compiled into 
Andrew software.


Andrew software has many options that may be re-bound dynamically with the 
AndrewSetup mechanism, where a configuration file is read in at execution 
time. (One of the options that may be re-bound, for example, is the 
location of the installed Andrew software.) One option that cannot be 
configured by the AndrewSetup mechanism is the location of the AndrewSetup 
configuration file itself. Instead, Andrew software searches a path to find 
the AndrewSetup file to use. The LOCAL_ANDREW_SETUP_ENV option is the way 
that the Andrew installer may specify that Andrew software look in 
additional locations for the AndrewSetup file.


Andrew software looks in the following five (or more) locations for an 
AndrewSetup file:

\leftindent{/AndrewSetup

/etc/AndrewSetup

$(LOCAL_ANDREW_SETUP_ENV)

/usr/vice/etc/AndrewSetup

$(DEFAULT_ANDREWDIR_ENV)/etc/AndrewSetup

/usr/andrew/etc/AndrewSetup}

(These alternatives have arisen from feedback about how typical sites 
protect their system directories.) If any file is found in this path, its 
values are used and no further files are examined; otherwise, 
compilation-time default values are used. The default condition for the 
LOCAL_ANDREW_SETUP_ENV option, that it not be defined, specifies that only 
those five locations are read. If LOCAL_ANDREW_SETUP_ENV is defined, it 
should be a path name of an AndrewSetup file, in double-quotes. It may also 
be a comma-separated list of double-quoted path names if many paths should 
be checked.


}\indent{An \indent{AndrewSetup file could, for example, contain the 
line}}\indent{


\leftindent{AndrewDir: "full path of andrew tree base not in quotations"

RequiredSubsFile: /usr/lib/RequiredSubscriptions

}}
\bold{DEFAULT_LOCALDIR_ENV}	[Default: "/usr/local"]\bold{

}
\indent{DEFAULT_LOCALDIR_ENV controls where to find locally-installed 
information. Only a few options are specified via this ``local'' directory; 
two examples are the name of a library of console files and the name of the 
file that names the folders to which all users must subscribe (via AMS). 
Andrew software's idea of the ``local'' directory may be overridden by 
either the value of the LOCALDIR environment variable or the value of the 
AndrewSetup option ``LocalDir''.

}
\bold{NDBM_ENV}			[Default: defined for only some platforms]

\bold{
}\indent{NDBM_ENV controls whether some parts of AMDS, the Andrew Message 
Delivery System, can use the ``ndbm'' package to manage small local 
databases.

}
\bold{GETDOMAIN_ENV}		[Default: defined for only some platforms]

\bold{
}\indent{GETDOMAIN_ENV, if defined, says that the getdomainname(2) call is 
available on this system and may be concatenated with the result of 
gethostname(2) to obtain a fully-qualified domain name for the local 
machine, for use by AMS. While this option is not defined in the 
distributed ./config/allsys.h file, it is defined in the platform-dependent 
./config/@sys/system.h file for all Suns, for Vax BSD, and for Vax Ultrix 
version 3.0 and later.

}
\bold{RELEASE2_ENV}			[Default: not defined]

\bold{
}\indent{RELEASE2_ENV controls the use of some X.V11R2 specific files. By 
default, this is undefined (which then assumes an X11 release 3, 4, or 5 
environment). This only affects which font compiler (fc versus bdftosnf) is 
used, how aliases for fonts are generated, and some workarounds for early 
bugs in the Xlib region code.

}

\subsection{1.2.6	Other Machine Types

}
If you are building this software on another machine type (other than one 
for which a .mcr and .h file have been provided for) you will need to 
create ./config/<machine>/system.mcr and ./config/<machine>/system.h files, 
and rework the ./config/platform.tmpl file to include your new 
./config/<machine>/system.mcr file. Other directories that need 
customization are:

	./overhead/class/machdep

	./atk/console/stats

	./atk/console/stats/<machine>

	./atk/console/stats/common


\subsection{1.2.7	Notes on Installation on a MIPS system (Including 
Decstations)}


The previous notes about dealing with -G 0 libraries no longer apply. MIPS 
has contributed a new ATK port which eliminates the complexities of the old 
setup.  However gcc should not be used, use the mips cc.


\subsection{1.2.8	Notes on Installation on a Sun 4 (SPARC) system

}
There have been reports of various version of the Sun C compiler dumping 
core when optimization is used. You may find it necessary to set the 
CDEBUGFLAGS= in the Imakefile for the directory in which the build fails. 
Then rebuild the Makefile for that directory and recompile it from scratch. 


XLIB and RESOLVLIB must be full pathnames of the archive libraries.


The GNU binutils should NOT be in your path while building AUIS.


As of ATK 4.10.0, there is support for the SunOS4.1 native dynamic loader. 
Unfortunately, Sun has not made dbx cognizant of any dynamically-loaded 
symbols. There is a patch set located on ftp.andrew.cmu.edu that, when 
applied to gdb 3.5, provides a new command, "add-dlopened-files", which 
finds out what objects have been loaded since the last time "gdb" checked 
what objects have been loaded, and loads the symbols for any new ones. \



[These notes about GDB 4.x and SunOS 4.x are from auspex!guy@uunet.uu.net 
(Guy Harris).]


GDB 4.x includes support for SunOS 4.x dynamically-loaded code, both shared 
libraries and "dlopen()"ed stuff. GDB 4.1 handles shared libraries better, 
in that it automatically finds them; you still have to use the 
"sharedlibrary" command to load up the symbol tables for stuff loaded up by 
"dlopen()" - "sharedlibrary", with no arguments, appears to find every 
shareable object that's been "dlopen()"ed since

the last time it checked, and read its symbols in.


There is a bug in GDB 4.1 where it doesn't set the "end of text" address in 
the "partial symbol table" entry for a shareable object correctly; it 
relocates the *beginning of text* address to put it where the object was 
actually loaded, but not the end of text address. One consequence of this 
is that you can't always (can't ever?) step into a routine in a 
"dlopen()"ed shareable object. The following patch appears to fix that (and 
has been sent to "bug-gdb", and appears in GDB 4.2):


\typewriter{\smaller{*** dbxread.c.dist	Fri Sep 20 23:47:25 1991

--- dbxread.c	Mon Sep 30 18:20:27 1991

***************

*** 1708,1714 ****

  #ifdef END_OF_TEXT_DEFAULT

    end_of_text_addr = END_OF_TEXT_DEFAULT;

  #else

!   end_of_text_addr = text_addr + text_size;

  #endif

  \


    symtab_input_desc = desc;	/* This is needed for fill_symbuf below */

--- 1708,1714 ----

  #ifdef END_OF_TEXT_DEFAULT

    end_of_text_addr = END_OF_TEXT_DEFAULT;

  #else

!   end_of_text_addr = text_addr + addr + text_size;	/* Relocate */

  #endif

  \


    symtab_input_desc = desc;	/* This is needed for fill_symbuf below */

}}
\subsection{1.2.9	Notes on displaying on an Open Windows server

}
Open Windows uses it's own font format.  To build the appropriate fonts, 
 you will need to compile on a machine with Open Windows installed and with 
OPENWINDOWS_ENV defined in your ./config/site.h file.  If you won't need 
the normal X .bdf fonts you can then replace the contents of the 
$ANDREWDIR/X11fonts directory with that of the $ANDREWDIR/Xnewsfonts.  If 
you don't wish to replace the contents of the X11fonts directory you will 
need to explicitly add the Open Windows versions of the Andrew fonts to 
your fontpath with a command like: xset +fp $ANDREWDIR/Xnewsfonts in your 
.xinitrc.


\subsection{1.2.10	Notes on Installation on a IBM RS/6000

}
This distribution builds for both rs_aix31 and rs_aix32.  Since there are 
no differences needed for the various sytem files, the term rs_aix3 is used 
for both system types.  \



If you are using AIX 3.1 or earlier running X.V11R3, you must use the 
version of imake in /usr/lpp/X11/Xamples/util/imake.  Otherwise, you can 
use the X11R4 imake that comes with AIX 3.2.  \



Do not build the Class pre-processor (./overhead/class/pp) with 
optimization-- it tickles a bug that causes later classes to fail.


If you are installing Andrew into a directory other than the one it is 
being built into (ie. your destination directory isn't $(BASEDIR)), you 
MUST set the parameter SHARED_LIB_PATH in your site.mcr file to match the 
destination directory.  Otherwise the RS/6000 dynamic library system will 
not be able to find important modules at run time.  The file 
./config/rs_aix31/system.mcr sets this by default:


SHARED_LIB_PATH = -L$\{BASEDIR\}/lib


for example, to set your destination directory to /usr/andrew you would

add the line:


SHARED_LIB_PATH = -L/usr/andrew/lib


to your ./config/site.mcr file.


\subsection{1.2.11	Notes on Installation on PS/2 AIXv1.2

}
The PS/2 C compiler will die with optimization in these directories:


./overhead/parsec

./atk/raster/cmd

./atk/eq


Compile these directories with "CDEBUGFLAGS=".


\subsection{1.2.12 Notes on Installation on SCO Unix \


}
First, in order to compile AUIS on standard SCO UNIX, you must use GCC. The 
C compiler has a limit on identifier lengths, and it will be entirely too 
painful to get around it. \



Second, you will want the following in your ./config/site.h and 
./config/site.mcr files:


./config/site.h:


#define MEMMOVE_IS_BROKEN 1

	-> this replaces memmove() with a correctly working bcopy()

#define POSIX_ENV 1


-> If you're using the Elan Eroff package, then try these:


#define print_FORMATCOMMAND "cat /tmp/%s.n |"

#define print_PRINTCOMMAND "/usr/sco/bin/netroff -Le -b %s"

#define print_PSCPRINTCOMMAND "lpr -dps"

#define EROFF_ENV 1


./config/site.mcr:


CC = gcc -fwritable-strings

GCCLIB = '/usr/local/lib/gcc-lib/architecture/version/libgcc.a'


GCCLIB should be the full path to libgcc.a.


AUIS has not be tested under SCO Unix for some time, there may be 
incompatibilies of which we are not yet aware.  If you have any problems 
please contact us at info-andrew-bugs@andrew.cmu.edu.  \


\subsection{1.2.13 Notes on HPUX

}
1.  This release supports only HPUX8.0 or greater.  If you have a need to 
build Andrew for an earlier version of HPUX, please contact the Andrew 
Consortium for details on how to do so.  \



2.  Because it is not possible to determine what version of HPUX you have 
on the machine, see the file andrew/config/hpx.series for hacks to enable 
compilation on HP Series 9000 machines.  \



3.  There are several problems with ld on HPUX8.0.  ATK dynamic objects are 
shared libraries.  The HPUX 8.05 link editor has a problem linking either 
1) normal archive libraries, or 2) shared libraries, into other shared 
libraries.  So, for instance, if you are working with a dynamic object, 
foo.\{c,ch\}, and it makes use of some math functions, you would normally 
use this imake rule to create it:


	DynamicObject( foo, foo.o,,-lm)


For HPUX8.0 do not include the math library in this rule.  The main 
executable, runapp, will contain the math library.  There has been defined 
a make macro, MATHLIB, that is set appropriately and should be used thusly:


	DynamicObject( foo, foo.o,,$\{MATHLIB\})


If any of your Andrew-related software is to be expected to compile on 
HPUX8.0 platforms, please use MATHLIB until there is an update to the 
system.  As of this writing, HPUX 8.07 apparently fixes this problems but 
has not been confirmed.  \



4.  There may be problems if you have LPATH set to favor pa1.1 libraries, 
unset LPATH before compiling AUIS.


5.  There is a problem building amsn.do (the messages interface to ams) 
because no shared version of libl.a is available,  this problem hasn't been 
encountered under HP-UX 9.03 though.  Upgrade if possible.  Otherwise 
complain to HP that a shared or pic version of libl.a should be available.

You may wish to get and use flex instead, but we haven't tested this.

To use flex:


First get flex and compile it with the +z option passed to cc.  Presumably 
you can do this with:


make CC="cc +z" <whatever arguments building flex calls for>


In site.h add:

#define FLEX_ENV 1


In site.mcr add:

LEX = flex /* or the path to flex */

LEXLIB = -lfl /* or the path to libfl.a */


Edit overhead/eli/lib/elil.flex:


Replace the line:


int my_yy_input(char *buf, int max_size, FILE *yyin)


with:


#ifdef ANSI_COMPILER

int my_yy_input(char *buf, int max_size, FILE *yyin)

#else

int my_yy_input(buf,max_size,yyin) char *buf; int max_size; FILE *yyin;

#endif


\subsection{1.2.14 Notes on NeXT

}
The cpp supplied with the 2.0 release of the NeXT OS is not suitable for 
use in imake.   Recent versions include a version of cpp and this cpp is 
known to work.


\subsection{1.2.15 Notes on SGI Iris}


Console has not been ported to this system.  To avoid attempting to build 
it, modify the following files as indicated:


./config/site.h: (add the following lines)

#undef MK_BASIC_UTILS

#define MK_EZPRINT 1

#define MK_PREVIEW 1


./config/site.mcr: (add the following line)

LAUNCHAPP = launchapp


\bold{1.2.16  Notes on Sun Solaris

}
The GNU binutils should NOT be in your path while building AUIS.


The C preprocessor does not define SOLARIS.  As such, you must add the 
-DSOLARIS flag to the initial imake that generates the top level Makefile. 
  Your initial command will be: \



imake -I. -I./config -Timake.tmpl -s Makefile -DSOLARIS -DTOPDIR=.


If you are not using the standard user account set up you may need to set 
LD_LIBRARY_PATH, or add the following to site.mcr:


 SHARED_LIB_PATH = 
-R$\{BASEDIR\}/lib:$\{XLIBDIR\}:/lib:/usr/lib:/usr/ccs/lib


This will ensure that all the shared libraries needed for AUIS can be 
found.  This is necessary only when LD_LIBRARY_PATH does not include the 
appropriate directories by default.


\bold{1.2.17 Notes on Decstation Ultrix 4.2 and Ultrix 4.3}


Ultrix 4.2 and 4.3

If you will be using the Dec versions of the X11 libraries you will need to 
add the following to site.mcr:


XLIB = /lib/libc.a $(XLIBDIR)/lib/libX11.a

RESOLVLIB=


If you need to set RESOLVLIB you may need to add it to XLIB (before 
/lib/libc.a) as well to avoid multiply defined symbols when building 
runapp.  The XLIB line would then be:


XLIB = $(RESOLVLIB) /lib/libc.a $(XLIBDIR)/lib/libX11.a


Ultrix 4.3a

This hackery avoids multiple definitions of malloc which occur because 
libX11.a has a malloc function of it's own.


If you are using Ultrix 4.3a and the latest version of the C compiler you 
may need to add the following to your site.mcr:


CC=cc -oldc


This fixes a problem with undefined symbols in atkams/messages/lib.


Ultrix 4.3 and AFS

Release 6 of the AUIS (and probably even previous releases) fails to build

on Ultrix 4.3 when it is built to run in an AFS 3.2 environment.  The

first time the problem is seen is when linking "runapp", and the symptom

is that a number of symbols for the XDR routines show up as multiply

defined.  These symbols are defined in both the AFS Rx library, and the

Ultrix C library, and differences in cross-module symbol references make

it impossible to link any program using XDR against both of these libraries

at the same time.


However, the XDR routines in AFS are taken directly from the Sun's

RPC source kit (which they distribute freely) - there is nothing special

about them.  It is therefore possible to simply use the XDR routines

provided in the C library instead of using AFS's versions.


To do this, it is necessary to delete the XDR modules from the

appropriate library (librx.a), as follows:


% cd $(AFSBASEDIR)/lib

% cp librx.a librx.a.orig      # Save a copy of the original!

% ar d librx.a xdr.o xdr_array.o xdr_float.o xdr_mem.o xdr_rec.o \\

       xdr_refernce.o xdr_update.o

% ranlib librx.a


Note that the module "xdr_rx.o" must remain in librx.a; this is the only

XDR module in this library that contains AFS-specific code.


Once this is done, Andrew will compile and link correctly without any 
"multiply defined" symbol errors.


\subheading{1.2.18  Notes on Installation on a Linux System}


AUIS has been successfully made on Linux version 0.99 patch level 14 and 
later.  It probably can be made on earlier versions also.  AUIS was tested 
using the Slackware 1.1.1 distribution.  The macro COMPILERFLAGS = -m486 
flag is set in the ./config/i386_Linux/system.mcr.  This flag gets passed 
to the gcc compiler. \



The following problem reports were submitted by the user who built AUIS on 
the Slackware 1.1.1 distribution. \



* In chart, select Rechart -> Dot.  The "points" are denoted with "C". 
  This is possibly a font problem.  See Section D2 of the FAQ for 
instructions on getting the correct fonts.  \



* In chart, select Rechart -> Dot or Rechart -> Line and then select Expose 
pallette.  Select Delete in the new pallette and then select any point on a 
 Line or Dot. Chart dies.


* Figure does not prompt when you modify a figure and then select Quit.  It 
just quits.


* The image do dies on certain documents.  It seems this happens when 
trying to import an Xpixmap.


* A raster cannot be imported into an image.


A full AUIS build will require about 95 MB of disk space for the object 
tree and 31 MB for the destination tree. Please note that the console 
application does not correctly read /proc and is therefore not very useful. 
 A binary distribution of AUIS 6.1 is available in 
ftp:/pub/Linux/X11/andrew on sunsite.unc.edu.  See the ./FAQ for a list of 
known problems.   A binary distribution of Release 6.2 will be made 
available soon.  Look for an announcement from the info-andrew distribution 
list. \



\subheading{1.2.19  Notes on Installation on BSD derivatives for 386 class 
machines}


This is the first public release to support NetBSD 0.9, BSDI/386, and 
possibly FreeBSD.  \



See <sources>/ossupport/i386_bsd/NetBSD.README for more information, 
including fixes needed to csh and make for them to work for AUIS.


\begindata{bp,751744}
\enddata{bp,751744}
\view{bpv,751744,2,0,0}
\chapter{2	Building the System

}
We assume you have a C preprocessor or static preprocessor similar to the 
4.3BSD cpp.c. (You should set symisiz at 7500 and sbfsize at 125*4096.)


To build AUIS,  'cd' to the top-level of the AUIS sources and type the 
following :


    \smaller{\{$XBINDIR\}/imake  -I.  -I./config  -Timake.tmpl  -s Makefile 
 -DTOPDIR=.

}
This will generate the top-level Makefile.  Continuing from the same 
directory, use the following commands:


\typewriter{\smaller{\leftindent{make World

}}}
If you installed the console application you will need to make 
$ANDREWDIR/bin/getstats and possibly $ANDREWDIR/bin/getconsole setuid root, 
or setgid to an appropriate group.  Typically these programs need access to 
/dev/mem and /dev/console.


If you want to build Andrew in stages, these are the steps:


\smaller{\typewriter{\leftindent{make Makefiles}

\leftindent{make dependInstall}

}}
You can clean out the directories using:


\leftindent{\typewriter{\smaller{make Clean}}}


\quotation{("Clean" recurses from that point on. "clean" only cleans out 
the current directory.)

}
\bold{\italic{NOTE}}: if you are using LINKINSTALL_ENV (default off, and 
against all our advice) you will probably want to use '\typewriter{make 
Tidy}' \underline{instead of} '\typewriter{make Clean}'. Tidy will only 
remove the non-installed generated files--i.e. it will leave libraries, 
programs, and .do files alone. "Tidy" recurses; "tidy" does not.


If you do not want to regenerate the dependencies, you can just do a 
"\typewriter{make Install}" instead of a "\typewriter{make dependInstall}". 
The dependencies shipped with the tape should work for all machine types; 
we remove general system include files from the dependency list.


\bold{\italic{NOTE}}: On vaxes we have found it necessary to increase the 
stack size. You can do this by:


\leftindent{\typewriter{\smaller{limit stack 2048}}}


\section{2.1	Error Recovery}


\subsection{2.1.1	Errors in the Build Process Itself}


If the build process should fail sometime before it has completely built 
and installed, you can do one of several things, depending on what has 
caused the build to fail. The simplest and most time consuming is to fix 
the problem and then do a "make dependInstall" from the root of the Andrew 
tree.


A faster approach is to continue the build process manually. For example, 
assume the make died in ./atk/eq. After correcting the problem, you could 
move into the ./atk directory and do a \



\leftindent{\smaller{\typewriter{make dependInstall SUBDIRS="fad table 
rofftext help ..."}}}


where the actual contents of the SUBDIRS entry can be determined by looking 
at ./atk/Imakefile. When the build for ./atk completes, examine the 
Imakefile for the top level and observe that the remaining SUBDIRS that 
need to be built are: ams atkams contrib helpindex xmkfontd and doc. So 
change directory to the root of the object tree (./) and execute


\leftindent{\typewriter{\smaller{make dependInstall SUBDIRS="ams atkams 
contrib helpindex xmkfontd doc"}}

}
After building the entire system you can recompile and install a subtree or 
directory, by moving to that directory and issuing


\leftindent{\smaller{\typewriter{make Install}}}


See the file FAQ for a list of common problems and the accompanying fixes. 
 \



\begindata{bp,751616}
\enddata{bp,751616}
\view{bpv,751616,3,0,0}
\section{2.2	System Components

}
The major parts of the distribution consists of: underlying libraries and 
programs (overhead), the Andrew Toolkit (atk), the Andrew Message System 
(atkams), applications of both ATK and AMS (atkams), and the Andrew 
Documentation. In addition, we also include a small collection of 
contributed AUIS insets.


This document contains a brief description of the contents of the Andrew 
Distribution. \



\subsection{2.2.1	Overhead}

\indent{\description{\bold{\bold{genmake} -} a script for generating 
Makefiles from Andrew style Imakefiles\bold{

\bold{sys} - }a program used for distinguishing between different system 
(hardware/os) types

\bold{util} - lots of utility functions. Includes the White Pages 
readers\bold{

addalias} - adds aliases for help probes

\bold{errors} - a package for handling some low-level error reports in a 
uniform way

\bold{index} - utility to map class names to file names

\bold{malloc} - the Andrew version of malloc

\bold{class} - an object-oriented C language preprocessor used by ATK

\bold{rxp} - a regular-expression package used in ELI

\bold{eli} - the ``embedded lisp interpreter'' used by AMS

\bold{\bold{image }- }various popular public domain image-compression 
libraries\bold{

conv} - several conversion programs for sites which have used earlier 
versions of the Andrew distribution.

\bold{fonts} - fonts used by ATK programs

\bold{xicons} - a small collection of icons for use under X window managers

\bold{\bold{cmenu} - }the ATK stack-of-cards X11 menu package\bold{

mail} - library of AMS functions

\bold{wputil} - programs and data to initialize and build a White Pages

\bold{wpi} - allows mail-basd updates to White Pages entries


}}
\subsection{2.2.2	ATK}

	\bold{Basics (or Core)}

\indent{\leftindent{\description{\bold{basics} - underlying ATK core

\bold{support} - underlying ATK core

\bold{supportviews}- underlying ATK core

\bold{text} - facilities for styled text and text formatting

\bold{utils} - support for dialog boxes \


\bold{frame} - support for file commands and buffers

\bold{textaux} - more support for text operations,  gnu-emacs compatibility 
and ISO Latin-1 input

\bold{atkvers} - version numbering scheme

\bold{ez} - a multi-media editor

\bold{extensions} - many user support packages, include gnu-search and 
meta-x

\bold{typescript} - a flexible csh window (not TERMCAP)

\bold{apps} - the core application executable

\bold{textobjects} - directory editor and a list view

\bold{hyplink} - a hypertext-like link inset

\bold{value} - a set of widgets for use with adew

\bold{adew }- a direct manipulation user interface builder

\bold{raster} - a raster (bitmap) editor


}}}\description{\leftindent{\bold{Basic Utilities}

\indent{\bold{console} - a system monitoring program

\bold{ezprint} - allows printing of ATK format documents

\bold{image} - a color raster viewer

\bold{preview} - a ditroff previewer

\bold{rofftext} - utility for viewing troff files


}\bold{Basic Insets}

\indent{\bold{eq} - an equation editor

\bold{fad} - a simple frame animator

\bold{table} - a simple spreadsheet


}\bold{Building Blocks}

\indent{\bold{apt} - basic components

\bold{org} - an organizational chart editor

\bold{bush} - a directory tree/file browser

\bold{figure} - a drawing editor

\bold{chart} - \description{a chart/graph program (line graphs, pie \


charts, histograms etc.)}

\bold{calc} - a simple calculator

\bold{prefed} - a preferences editor


}\bold{Help (program)}

\indent{\bold{help} - a user interface for help files and man pages


}\bold{Text Extensions}

\indent{\bold{srctext} - a text formatting package, including support for 
Assembly, C, Modula3 and other languages

\italic{(this package is not an active interpreter - only a formatter)}

\bold{spell} - a spell checker. See note below.


}\bold{Authoring Systems}

\indent{\bold{ness} - an embedded string manipulation authoring system

\bold{syntax} - a new set of tools has been introduced for token analysis 
and parsing.

\bold{syntax/bison} - a modified version of the Bison parser from the FSF

\bold{syntax/parse} - a parser object that uses tables \


\bold{syntax/lexan }- a superclass for lexical analyzers \


\bold{syntax/tlex} - a subclass of lexan which lexically analyzes input in 
the form of an ATK text object. }\bold{syntax/sym} - a symbol table package 
\indent{
}\bold{
Auxiliary Utilities}

\indent{\bold{datacat} \description{- a utility for concatenating two (or 
more) ATK format files together}

\bold{toez} - \description{a utility for converting files (scribe, troff) 
into ATK format}

\bold{layout} - \description{facility for designing screen layouts}

\bold{controllers} - \description{examples of adew-generated code }\


\bold{createinset} - \description{a program to create an example inset with 
the name customized}

\bold{lookz} -\description{ a style editor}

}\bold{
Example Programs}

\indent{\bold{examples}  - illustrates how to write an inset and 
application

}}}		\bold{launchapp} - demo application using in the Remote Andrew Demo 
service


\subsection{2.2.3	AMS}


\indent{\description{\bold{delivery} - the fundamental programs in AMDS 
that manage mail queues and deliver mail

\bold{demo} - builds a multi-media folder that you can use as an AMS/ATK 
demo

\bold{doc} - AMS documentation of all sorts

\bold{flames} - ELI application that handles new messages interpretively

\bold{libs} - libraries used in building AMS user agent programs

\bold{ms} - the RPC veneer over the lower-level parts of those AMS 
libraries, making the MessageServer process

\bold{msclients} - AMS user agent programs

\bold{utils} - useful programs in managing AMDS installations

}}
\subsection{2.2.4	ATKAMS}


\indent{\description{\bold{messages} - our flagship AMS program; 
multi-media mail and bboards


}}\subsection{2.2.5	Contrib}


Among other things, you will find:


\indent{\description{\bold{alink} - an audio inset for Sparcstations

\bold{atkbook} - examples from N. Borenstein's book on the Andrew Toolkit

\bold{bdffont} - a BDF font viewing and editting inset

\bold{calc }- a calculator program

\bold{champ} - a calendar program

\bold{demos }- an AUIS demo

\bold{\bold{eatmail} }- a program which transfers mail from 
/usr/spool/mail/\{uid\} into separate files in \{uid\}'s Mailbox directory

\bold{gestures} - a gesture-based text view

\bold{mit/annot} - a note and a postscript inset

\bold{\bold{mit/neos}} - Networked Educational On-line System\bold{

\bold{mit/}scribetext }- a scribe text formatter\bold{

\bold{mit/}thesis} - a thesis-writing package\bold{

mit/util} - header/footer object for text, a printer option dialog box, 
ez2ps

\bold{parsec} - a C language parser plus a procedure to clean up YACC 
output

\bold{snap2} - an RPC package used by the Andrew Message System

\bold{\bold{srctext/ltext} -} a LISP text editing package\bold{

srctext/ptext} - a PASCAL text editing package

\bold{srctext/html} - an HTML text editing package

\bold{\bold{time} }- analog and digital clocks, time-of-day and writestamp 
(useful in documents)

\bold{tm }- an alternative to typescript

}}	\bold{zip }- an hierarchical drawing editor


Many of these objects have proven very useful, and are a part of our 
default environment at CMU. We welcome your contributions.


\bold{2.2.6  Rdemo}


This directory tree contains the sources for the Remote Andrew Demo (rdemo 
for short).  Rdemo is an Internet network service provided by a few nodes 
at the Andrew Consortium.  It allows users anywhere on the Internet to 
interactively experiment with Andrew software.


We do not expect that people will want to build rdemo and provide the 
network service themselves.  We've included the sources because we expect 
that some people may wish to emulate this service and create their own 
remote demos.  The sources are included primarily for the edification of 
programmers who wish to do this (although there's nothing stopping you from 
building the rdemo suite if you so desire).  See the README in the ./rdemo 
directory for more information.  \



\section{2.3	Make Targets

}
The generated Makefiles contain the following targets:


\description{\leftindent{\typewriter{Makefile}: Generates the Makefile from 
the Imakefile in the current directory (assuming there is already a 
Makefile present).


\typewriter{Makefiles}: Generates the Makefiles for subdirectories (does 
not generate the Makefile for the current directory).


\typewriter{all}:

	Builds the contents of the current directory.

	\


\typewriter{depend}:

	Generates dependency information for the current directory.

	\


\typewriter{doc}:

	Installs documentation from the current directory.

	\


\typewriter{Doc}:

	Same as above but recurses thought subdirectories.

	(depends on "doc")


\typewriter{aliases}:

	Generates 'help alias' information for the current directory.

	\


\typewriter{Aliases}:

	Same as above but recurses through subdirectories.

	(depends on "aliases")


\typewriter{install}:

	Installs the binaries, libraries, include files, etc. for the current 
directory.

	(depends on "all" and "doc")


\typewriter{Install}:

	Same as above but recurses through subdirectories.

	(depends on "install")


\typewriter{dependInstall}:

	Generates dependency information.

	Installs binaries, libraries, include files etc.

	Installs documentation.

	Recurses through subdirectories.


\typewriter{world}:

	(depends on "depend", "install", "aliases")

	(for current directory only)


\typewriter{World}:

	Same as above but recurses through subdirectories.


\typewriter{tidy:

	}Removes only non-installed generated files (*.o *.BAK core, etc) thus not 
removing files which have links pointing to them from DESTDIR.


\typewriter{Tidy:}

	Same as above but recurses through subdirectories.


\typewriter{clean:}

	Removes all generated files (*.o, *.a, etc.) in current directory only.

	(depends on "tidy")


\typewriter{Clean:}

	Same as above but recurses through subdirectories.


}}\section{2.4	What Gets Built

}
During the build process, the makefile constructs applications, dynamically 
loadable objects, libraries, fonts, templates, console descriptions, help 
files and include files. Each of these collections goes into its own 
directory. At runtime, ATK applications and objects assume that there will 
be an environment variable called ANDREWDIR that will be the root of all 
andrew related run-time files. (See the discussion of 
DEFAULT_ANDREWDIR_ENV, above.) Within the makefiles, the variable BASEDIR 
is used for the value you expect to use for ANDREWDIR during run time. In 
particular, the system should install files so that the following 
directories are used for each category:


\description{\leftindent{$\{ANDREWDIR\}/bin - Runnable applications}

\leftindent{$\{ANDREWDIR\}/dlib/atk - Dynamic objects}

\leftindent{$\{ANDREWDIR\}/X11fonts -ATK specific fonts for X}

\leftindent{$\{ANDREWDIR\}/Xnewsfonts - ATK fonts for running under Open 
Windows (if enabled)

$\{ANDREWDIR\}/lib/tpls - Style templates for text-oriented objects}

\leftindent{$\{ANDREWDIR\}/lib/consoles - Console descriptions}

\leftindent{$\{ANDREWDIR\}/lib/atk - Compile time libraries}

\leftindent{$\{ANDREWDIR\}/include/atk - Compile time include files}

\leftindent{$\{ANDREWDIR\}/help - Help files}

\leftindent{$\{ANDREWDIR\}/doc - Doc files}}

\description{\leftindent{$\{ANDREWDIR\}/etc - Auxiliary files, usually not 
accessed directly by users}}


\section{2.5	Size of the System

}
The following list provides information about building the Andrew system. 
These are approximate values, derived from our test builds of the complete 
system with full debugging (-g). If you have  LINKINSTALL_ENV turned on 
then you should only be concerned with the size of the objects (the 
installed tree will just contain links back to the object tree). If you 
compile the system with optimization and no symbols (-O) these sizes will 
be much smaller -- by roughly a factor of two or three. 35-50M is 
sufficient for the objects on most systems with LINKINSTALL_ENV turned on 
and debugging off.


\smaller{The minimum setup (including help and the text extensions) 
occupies about 25% of the total space.

The default (enough to run the messages demo) is about 75% of the total.

Not compiling with -g will reduce these numbers substantially.}


Sources distributed:

\leftindent{50M}


Total Objects:


\leftindent{Dec Mips: 125M

Sun4: 170M

RS/6000: 222M\leftindent{

}
}Binaries:

\leftindent{
Dec Mips: 65M

Sun4: 82M

RS/6000: 60M

}
\begindata{bp,751488}
\enddata{bp,751488}
\view{bpv,751488,4,0,0}
\chapter{3	Setting up the Environment to Run Applications}



To run our software you must be running X11, and have your DISPLAY 
environment variable set appropriately. Our applications support the -fg, 
-bg, -display and -geometry switches.


In addition, most ATK applications also reference the file ~/preferences or 
~/.Xdefaults for lines of the form:


appname.foregroundcolor: colorspec

appname.backgroundcolor: colorspec

appname.geometry: geometryspec


where appname is the name of the application (i.e. console, ez, etc.).


If you want the \italic{\bold{Check Spelling}} menu in text to work, you 
will need the ispell program. Ispell must be found along a user's path.


Before running AMS, you may want to review the options available with the 
AndrewSetup mechanism, described in the setup.help file 
(BASEDIR/help/setup.help).


Examples of preferences files and other init files are in the sources in 
overhead/util/lib/samples, and are installed into $DESTDIR/lib/samples.


\chapter{4	Printing}


The ATK software uses the new version of troff (ditroff) and Adobe's 
TransScript software to provide printing support for Postscript printers. 
The defaults are set up to use lpr to spool print requests. Our 
applications use two values found in the user's preferences file to control 
printing:


\leftindent{\description{formatcommand: Command used to generate a file to 
be shipped to the printer.

printcommand: Command used to ship the file to the printer.}}


The defaults for these commands are:


\leftindent{formatcommand: eqn /tmp/%s.n | troff - |

printcommand: lpr -n}


This preference will make printing work on RS/6000's:


	?C=rs:*.printcommand: psdit|lpr


A temporary troff file is generated automatically in /tmp in the process of 
printing a file. You should run \



\leftindent{help preferences}


once you have brought up the system to see how to change your preferences.


A document describing in some detail how printing works and giving some 
guidelines for testing printing is in the source tree in 
atk/ezprint/printing.ins.


\chapter{5	Configuring a Help System }\



\section{5.1	The index}


Help is configured by default to index (and thus make available) files in 
the following directories:


\leftindent{$(DESTDIR)/help

/usr/man/man[1-8,n,o,l,p]

}
This collection of directories indexed by the Help system is specified in 
an input file to an index-making program, mkindex. If you want to index 
more than the Andrew help files and man pages in 
/usr/man(/man[1-8,n,o,l,p]), you should edit the file 
``./helpindex/index.tpl'' and add lines for each of the directories you 
want to be included in the Help system, in the following format (the 
following description is taken from ./atk/help/doc/Maint.d):


\smaller{#	comment

dir	actual-directory-name	link-directory-name

include	filename

key	keyword	filename


}The white space between the words on each line can be any number of tabs 
or spaces. Here is an explanation of the commands:


\bold{\typewriter{#	\italic{comment}}

}\indent{Any line beginning with "#" is a comment and is ignored.}


\bold{\typewriter{dir	\italic{actual-directory-name	link-directory-name}}}

\leftindent{This command tells mkindex to index the files in 
actual-directory-name, and record the path to those files as starting with 
link-directory-name. At Carnegie Mellon, /usr/man is a link to 
/afs/andrew/<machine>/usr/man, so mkindex's input file contains the line:


\typewriter{dir /afs/andrew/machinetype/usr/man/man1 /usr/man/man1


w}here machinetype is the name used to refer to a specific machine's 
system-specific directories.}


\bold{\typewriter{include	\italic{filename}}}

\indent{This line tells mkindex to read in the file filename as more 
mkindex commands. At Carnegie Mellon, this facility is used to allow 
different indices on different machine types to all include a set of common 
system directories.

}
\bold{\typewriter{key	\italic{keyword}		\italic{filename}}\italic{

}}\indent{This line tells mkindex to explicitly use the given keyword as an 
alias for the file filename. This alias functions identically to aliases in 
the help.aliases file, as described in the section Aliases in Maint.doc.

}
When the whole system is built, helpindex is built last and will make an 
index for Help using index.tpl as an input file. The build is accomplished 
by changing directory to the root of the object tree and saying


\leftindent{\typewriter{\smaller{make dependInstall 
SUBDIRS=helpindex}}}\typewriter{

}
or for any subtree with the command:


\leftindent{\typewriter{\smaller{make Aliases}}}


Further information on configuring the Help system and program can be found 
in the Help Maintainer's Guide which, once the system is installed, is in:


\leftindent{$(DESTDIR)/doc/help/Maint.doc}


\section{5.2	The documents}


The documents ("help files") that describe the system will probably need to 
be edited at some point to reflect the system you have built correctly, if 
you intend users not to be unpleasantly surprised by the lack of a 
documented feature. Unfortunately, the help files describe a full 
installation of Andrew; they are not configured during the building process 
to reflect partial installations. In particular, the Message System 
documentation may need to be reviewed because it describes a system that 
includes the White Pages, the Andrew Message Delivery System, and (at 
times) a bulletin board system. See the Help Maintainer's guide for more 
information.


\chapter{6	Hard Copy Documentation}


Hard copy user and programmer documentation is available by U.S. mail. The 
documents are provided at cost, plus shipping and handling. More 
information, as it becomes available, will be posted to info-andrew (see 
below), or you can write:


	Information Requests

\leftindent{Andrew Consortium}

	School of Computer Science\leftindent{

}	\leftindent{Carnegie-Mellon University}

\leftindent{Pittsburgh, PA 15213

U.S.A.}

\leftindent{(412) 268-6710

FAX: (412) 68}1-5739



\chapter{7	How to Get More Information about Andrew \


}
There are two(*) mailing lists read by the developers and others interested 
in the Andrew User Interface System. The first is a bug report list 
moderated by members of the Andrew Consortium. \



\leftindent{info-andrew-bugs@andrew.cmu.edu}


The second is an unmoderated list devoted (but not limited) to getting, 
compiling, and installing Andrew, announcements, bug reports, fixes, and 
request for features. This address is: \



\leftindent{info-andrew@andrew.cmu.edu}


Subscription requests should be sent to one of the following addresses:


\leftindent{info-andrew-request@andrew.cmu.edu}


When you send in a request, you will be put on both lists, unless you 
specify otherwise. If you are running the Andrew Message System, you can 
also request to be put on the multi-media list. This list receives exactly 
the same messages as info-andrew and info-andrew-bugs, except that the 
messages are sent out with their formatting intact, so you can see the 
multi-media portions of messages that have them. If you don't request 
multi-media, you will be put by default on the non-multi-media list.


(*)Note: the second list, info-andrew@andrew.cmu.edu, is bi-directionally 
gatewayed with the Netnews group comp.soft-sys.andrew. You do not/can not 
subscribe to the netnews group through us, and the netnews group contains 
ONLY non-multi-media posts.


\enddata{text,756992}
