\begindata{text,537426132}
\textdsversion{12}
\template{default}
\define{chapter
menu:[Title~3,Chapter~20]
attr:[Justification LeftJustified Point 0]
attr:[Flags KeepPriorNL Int Set]
attr:[Flags KeepNextNL Int Set]
attr:[FontFace Bold Int Set]
attr:[FontSize PreviousFontSize Point 2]}
\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 5.1 


(April, 1992)


}\bold{CDROM Release}










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


Andrew Toolkit 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 IBM Corporation 1988, 1991 - All Rights Reserved

Copyright Carnegie Mellon University 1991, 1992  - All Rights Reserved

\begindata{bp,538376328}
\enddata{bp,538376328}
\view{bpv,538376328,8,0,0}

Copyright IBM Corporation 1988, 1991 - All Rights Reserved

Copyright Carnegie Mellon University 1991, 1992  - 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,538376392}
\enddata{bp,538376392}
\view{bpv,538376392,9,0,0}

\chapter{1	Installation Instructions for the Andrew Distribution

}
This document contains instructions for the installation of the Andrew 
software, namely the Andrew Toolkit (ATK), and its applications, including the 
Andrew Message System (AMS).


This release includes innumerable bug fixes and evolutionary improvements to 
many of Andrew's components. Several new sub-systems and components are 
included in this release, including a new 3D look for many of the components, 
the addition of a menubar, and an overhaul of several parts of the text 
object. The contrib section of our release now includes quite a number of 
objects, including an adaptation of Dean Rubine's gesture recognizer to the 
text object, a Sparcstation audio object, a header/footer object for text, and 
a postscript inset.


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


You'll need to modify two files:  config/site.h and config/site.mcr. 
 config/site.h includes your site's adjustments to allsys.h and system.h.  You 
should specify the location of the DEFAULT_ANDREWDIR_ENV.  config/site.mcr 
contains your site's adjustments to macros in allsys.mcr and system.mcr.  You 
may want to change XINCDIR, XLIBDIR and XINCDIR which define the location of 
your X libraries and utilities.  You may want to check the other options 
available below under section 1.2.1 for the site.h file and section 1.2.4 for 
the site.mcr file. 


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}


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 RT AOS 3.4, RT AIX 2.2.1, RS/6000 
AIX3.1\footnote{\
\begindata{fnote,537818888}
\textdsversion{12}
See Notes on Installation of RS/6000 for information about AIX 3.2\
\enddata{fnote,537818888}
\view{fnotev,537818888,10,0,0}}, PS/2 AIX1.2, Sun3 3.5, Sun3 4.0, Sun4 4.0, 
Sun3 4.1, Sun4 4.1, Vax Ultrix 3.1, Vax Ultrix 4.2, Vax BSD, DEC MIPS, SCO 
I386, SGI IRIX 4.0, Apollo, HP, and Macintosh II MacMach. We run it on RS/6000 
AIX3.1,  and RT AOS. 


As shipped, the Andrew Toolkit distribution is about 30 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 40 megabytes; changing 
that configuration to include building everything generates about 85 
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 the Andrew Toolkit, 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:


\formatnote{Machine Type		Operating System		<machine>


IBM RT			AOS December 1988	rt_aos4

IBM RT			AIX 2.2.1			rt_aix221

IBM RS/6000		AIX 3.1			rs_aix31

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

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_42

SGI				IRIX 4.0			sgi_4d

SCO				SCO				sco_i386

}
\subsection{1.2.1	The allsys.mcr, system.mcr, and site.mcr 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 
site.mcr file is distributed, in which you can make your edits by overriding 
what has come before, typically with #undef and #define, possibly within 
#ifdef/#endif pairs, or by simply setting a Make variable with as ``FOO=bar''. 
(Make does lazy evaluation of its $(FOO) variables, so it's reasonable to 
override variables such as XUTILDIR in site.mcr.)


\bold{BASEDIR}		[Default: DEFAULT_ANDREWDIR_ENV, from allsys.h/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. It 
may be set to other values only in the course of testing developments.


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

\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 
info-afs+@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.}


\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. 
It is used only if RESOLVER_ENV is defined, which it is unless your system.h 
or site.h file undefines it. 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 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 (SetUp.ref), the Andrew Message System Installation 
manual (AMS.ins), the Andrew Message Delivery System Installation manual 
(AMDS.ins), and in the White Pages installation manual (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 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 allsys.h or system.h. Instead, an empty site.h file 
is distributed, in which you can make your edits by overriding what has come 
before. (You can do this using both #undef and #define.)


In the simplest case, you would not edit 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 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.

}
\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 andrew/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 Xv11r3 server product and DEC's 
DecWindows product both 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 $(TOPDIR)/site. See further documentation in 
$(TOPDIR)/site/README.site.ez.

}
\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 
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 config system.mcr 
files include a CONVERTFONT macro to be defined as 
/usr/openwin/bin/convertfont. You can override this default value in your 
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 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).


}\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 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: not defined]

\bold{
}\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 + champ + preview)

MK_BASIC_INSETS 	(= eq + fad + table)

MK_BLD_BLKS 	(= apt + org + bush + zip + chart + calc)

MK_HELP 		(= glist + rofftext + help)

MK_TEXT_EXT 	(= ctext + lookz)

MK_AUTHORING 	(= value + lset + controllers + music + ness)

MK_AUX_UTILS 	(= datacat + toez)

MK_AUX_INSETS 	(= gob)

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

MK_CHAMP

MK_CHART

MK_CONSOLE

MK_CONTROLLERS

MK_CTEXT

MK_DATACAT

MK_EQ

MK_EXAMPLES

MK_EZPRINT

MK_FAD

MK_GLIST

MK_GOB

MK_HELP

MK_LOOKZ

MK_LSET

MK_MUSIC

MK_NESS

MK_ORG

MK_PREVIEW

MK_ROFFTEXT

MK_TABLE

MK_TOEZ

MK_VALUE

MK_ZIP

}}}
\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 programs \bold{\typewriter{rtf2}}, \bold{\typewriter{2rtf}}, and 
\bold{\typewriter{scribetext}} are located in andrew/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. }


\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: defined]

\bold{
}\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). This saves considerable space.

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

\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 info-afs+@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 overhead/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.

}
\bold{DITROFF_ENV}			[Default: defined]

\bold{
}\indent{DITROFF_ENV is defined if ditroff is available for printing Andrew 
Toolkit documents. (See installation of 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 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 (cf. 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 (cf. setup.help), 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 allsys.h 
file, it is defined in the platform-dependent 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/imake.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}


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.


\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. 


As of ATK 4.10.0 (what we used to call ATK 17.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 
emsworth.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 */

}}

\subheading{1.2.9	Notes on Installation on a IBM RS/6000}


This distribution has been run on AIX 3.2 but the ATK Consortium has AIX 3.1 
and thus has not tested this. 


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 site.mcr file.



\subheading{1.2.10	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=".


\bold{1.2.11 Notes on Installation on SCO Unix }


First, in order to compile ATK 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 things in your site.h and site.mcr files:


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


site.mcr:


CC = gcc

COMPILERLIBS = /usr/local/lib/gcc-gnulib


Other patches and a README detailing fixes necessary to build Andrew for SCO 


\bold{1.2.12 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 Toolkit 
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/hp.series for hacks to enable the 
compilation for any of HP 9000 series 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.  


\begindata{bp,538376456}
\enddata{bp,538376456}
\view{bpv,538376456,11,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 the Andrew Toolkit, as distributed on the X.V11R5 tape, 'cd' to the 
top-level Andrew source directory (contrib/andrew ?) and type the following:


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

}
This will generate the top-level Makefile from which the rest becomes easier 
to do. Continuing from the same directory, use the following commands:


\typewriter{\smaller{\leftindent{make World

}}}
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 on) 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 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="glist 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 helpindex helpaliases xmkfontd. So change directory to the root of 
the object tree and execute


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

}
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.ez for a list of common problems and the accompanying fixes. 
 


\begindata{bp,538376520}
\enddata{bp,538376520}
\view{bpv,538376520,12,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 
(AMS), applications of both ATK and AMS (ATKAMS), and the Andrew 
Documentation. In addition, we also include a small collection of contributed 
ATK insets.


This document contains a brief description of the contents of the Andrew 
Distribution. The content descriptions are noted in order of installation. 



\subsection{2.2.1	Overhead}

\indent{\description{\bold{addalias} - adds aliases for help probes

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

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

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

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

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

\bold{fonts} - fonts used by ATK programs

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

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

\bold{mail} - library of AMS functions

\bold{malloc} - the Andrew version of malloc

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

\bold{pobbconf} - houses the mechanism to turn on AMDS at your site

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

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

\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{wpi} - allows mail-based updates to White Pages entries

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

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

}}

\subsection{2.2.2	ATK}


\description{\leftindent{1. Basics (or Core):

}}\indent{\leftindent{\description{- underlying ATK libraries

- \bold{ez} - a multi-media editor

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

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

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

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

}}}\description{\leftindent{2. Basic Utilities

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

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

- \bold{champ} - a calendar program

- \bold{preview} - a ditroff previewer

}3. Basic Insets

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

- \bold{fad} - a simple frame animator

- \bold{table} - a simple spreadsheet

}4. Building Blocks

\indent{- \bold{apt} - basic components

- \bold{org} - an organizational chart editor

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

- \bold{zip} - an hierarchical drawing editor

- \bold{chart} - a chart/graph program (line graphs, pie charts, histograms 
etc.)

- \bold{calc} - a simple calculator

}5. Help (program)

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

}6. Text Extensions

\indent{- \bold{ctext} - a C text editing package

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

- \bold{lookz} - a style editor

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

}7. Authoring Systems

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

}8. Auxiliary Utilities

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

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

}9. Auxiliary Insets

\indent{- \bold{gob} - 

}10. Example Programs

\indent{- examples illustrating how to write an inset and application

- examples from N. Borenstein's book on the Andrew Toolkit

}}}

\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{gestures} - a gesture-based text view

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

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

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

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

- \bold{mtext} - a MODULA2 text editing package

- \bold{ptext} - a PASCAL text editing package

- \bold{rctext} - another C text editing package

- \bold{rmtext} - another MODULA 2 text editing package

- \bold{m3text} - a MODULA 3 text editing package

- \bold{tm }- an alternative to typescript

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

}}
Many of these objects have proven very useful, and are a part of our default 
environment at the ITC. 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 Toolkit 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 andrew/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.


}}\description{\leftindent{
}}
\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 left 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{41M}


Total Objects:


\leftindent{Dec Mips: 125M

Sun4: 170M

RS/6000: 222M\leftindent{

}
}Binaries:

\leftindent{
Dec Mips: 65M

Sun4: 82M

RS/6000: 60M

}
\begindata{bp,538376584}
\enddata{bp,538376584}
\view{bpv,538376584,13,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 (teh following description is taken from BASEDIR/doc/help/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{

}
The aliases can be rebuiilt from the root with


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


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:


\leftindent{Andrew Toolkit Information}

\leftindent{Information Technology Center

4910 Forbes Avenue}

\leftindent{Carnegie-Mellon University}

\leftindent{Pittsburgh, PA 15213-3890

U.S.A.}

\leftindent{(412) 268-6700

FAX: (412) 268-6787}



\chapter{7	How to Get More Information about Andrew 

}
There are two(*) mailing lists read by the developers and others interested in 
the Andrew Toolkit. The first is a bug report list moderated by members of the 
ATK Group. 


\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,537426132}
