








                        The Andrew Distribution 

                          Version 5.0.0 (1991)

                  Distributed with MIT's X11 Release 5









                                   For more information, please contact: 

                                            Information Technology Center
                                               Carnegie Mellon University
                                                       4910 Forbes Avenue
                                                Pittsburgh, PA 15213-3890
                                                                   U.S.A.
                                                           (412) 268-6700
                                                      FAX: (412) 268-6787

                                 Mailing list: info-andrew@andrew.cmu.edu
                   (info-andrew-request@andrew.cmu.edu for subscriptions)
                                          Newsgroup: comp.soft-sys.andrew


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.


1.1	Assumptions and Requirements 

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, PS/2 AIX1.2,
Sun3 3.5, 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. (The port to HP/UX 8.0 is
complete, but not merged into this release. We intend to include this in
the first patch to this release: ATK 5.1.)

As shipped, the Andrew Toolkit distribution is about 32 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:

    imake -- part of program construction (makefile) facility
    bdftosnf or bdftopcf -- font compiler
    makedepend --part of program construction (makefile) facility
    Xlib -- X.V11 include files and libraries


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:

    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 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:

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

1.2.1	The allsys.mcr, system.mcr, and site.mcr Files

config/allsys.mcr, config/<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.)

XBASEDIR		[Default: /] 

    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.

BASEDIR		[Default: DEFAULT_ANDREWDIR_ENV, from allsys.h/site.h] 

    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: include, bin, lib, dlib, etc, doc, and 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.

DESTDIR		[Default: $(BASEDIR)] 

    DESTDIR should always be identical to BASEDIR for system builds.
    It may be set to other values only in the course of testing
    developments.

AFSBASEDIR	[Default: $(DEFAULT_LOCALDIR_ENV)] 

    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 afsinfo@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/andy . Override it in your site.mcr
    file if you need to.

WMBASEDIR	[Default: ]

    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.

CDEBUGFLAGS	[Default: -O] 

    CDEBUGFLAGS are passed to the C compiler when compiling programs.

XUTILDIR		[Default: /usr/local/bin] 
IMAKE		[Default: $(XUTILDIR)/imake] 
XMAKEDEPEND	[Default: $(XUTILDIR)/makedepend] 

    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.

XINCDIR             [Default: $(XBASEDIR)/usr/include/X11] 
XMKFONTDIR  [Default: $(XBASEDIR)/usr/bin/X11/mkfontdir] 
XLIBDIR             [Default: $(XBASEDIR)/usr/lib] 
XFC                 [Default:
    RELEASE2_ENV implies $(XSRCDIR)/fonts/compiler/fc,
    FONTS_TO_PCF_ENV implies $(XBASEDIR)/usr/bin/X11/bdftopcf,
    otherwise $(XBASEDIR)/usr/bin/X11/bdftosnf] 
    
XSRCDIR             [Default: empty string] 

    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.

RESOLVLIB	[Default: empty string] 

    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.

INSTALL		[Default: install] 

    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:

    #define BUILDANDREWINSTALL_ENV  1

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

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

SHELL		[Default: /bin/sh] 

    SHELL specifies the path to the Bourne shell.

CSHELL		[Default: /bin/csh] 

    CSHELL specifies the path to the C shell.

CC			[Default: cc] 

    C compiler to use. On the IBM RT/PC, it is the hc Metaware
    compiler. On other systems, it is the pcc compiler.

ConstructMFLAGS	[Default: not defined]

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

1.2.2	The sitevars.h File

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:

_SITE_NON_ANDREW_MAIL               [Default: /usr/spool/mail]

        Directory where console should look to see if incoming mail
        has arrived.

_SITE_NON_ANDREW_PRINTDIR   [Default: /usr/spool/lpd]

        Directory where console should look to see if any
        outstanding printing requests are waiting.

_SITE_LOGFILE               [Default: /tmp/ConsoleLog]

        Default file where console logs should be written when
        requested by the user of console.

_SITE_MTAB          [Default: /etc/mtab]

        File that console should use for obtaining information about
        the mounted file systems.

_SITE_BIN_SH                [Default: /bin/sh]

        Default shell to use for exec'ing sub-programs.

_SITE_DEV_TTY               [Default: /dev/tty]


_SITE_DEV_PTYP              [Default: /dev/ptyp]


_SITE_DEV_CONSOLE   [Default: /dev/console]

        Stream that console intercepts for its log (actually, its 0th log).

_SITE_DEV_KMEM      [Default: /dev/kmem]

        Device that console should use to obtain memory statistics.

_SITE_VMUNIX                [Default: /vmunix]

    File where console should get information about the kernel's
        symbol table.


1.2.3	The mailconf.c and svcconf.c Files

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: 

    info-andrew-bugs@andrew.cmu.edu


1.2.4	The allsys.h, system.h, and site.h Files: Defining What Parts of
Andrew to Build

config/allsys.h, config/<machine>/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.

AMS_ENV				[Default: defined]

    AMS_ENV is defined if the Andrew Message System should be built.
    This is the messages program and related libraries and programs.

AMS_DELIVERY_ENV		[Default: not defined]

    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. 

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

WHITEPAGES_ENV			[Default: not defined]

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

SNAP_ENV				[Default: not defined]

    SNAP_ENV is defined if the Message Server is to be built.

WM_ENV				[Default: not defined]

    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. 

X11_ENV				[Default: defined]

    X11_ENV is defined if the Andrew Toolkit is to be built for the
    X.11 Window System.

PRE_X11R4_ENV			[Default: not defined]

    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.

DPS_ENV				[Default: not defined]

    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.

ANDREW_MALLOC_ENV	[Default: defined]

    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.

DEBUG_MALLOC_ENV		[Default: not defined]

    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.

SITE_ENV				[Default: not defined]

    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.

NO_FONTS_ENV			[Default: not defined]

    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.

FONTS_TO_BDF_ENV 		[Default: not defined]

    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.

FONTS_TO_PCF_ENV		[Default: defined]

    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.

OPENWINDOWS_ENV		[Default: not defined]

    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. 

OLD_ULTRIX_ENV		[Default: not defined]

    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.

CONTRIB_ENV			[Default: not defined]

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

ISO80_FONTS_ENV		[Default: defined]

    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.

MK_BASIC_UTILS			[Default: not defined]
MK_BASIC_INSETS			[Default: defined]
MK_BLD_BLKS				[Default: defined]
MK_HELP					[Default: defined]
MK_TEXT_EXT				[Default: defined]
MK_AUTHORING			[Default: not defined]
MK_AUX_UTILS			[Default: not defined]
MK_AUX_INSETS			[Default: not defined]
MK_EXAMPLES			[Default: not defined]

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

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

        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

    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.


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.

LINKINSTALL_ENV		[Default: defined]

    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.

AFS_ENV				[Default: not defined]

    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
    afsinfo@transarc.com If AFS_ENV is defined, it is assumed that
    the following files will be available under AFSBASEDIR :
        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:
        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.

AFS30_ENV				[Default: not defined]

    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:
        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

AFS31_ENV				[Default: not defined]

    AFS31_ENV is defined if version 3.1 or later of the Andrew File
    System (including the protection server) is being used. 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:

        lib/afs/libdes.a

RUN_AMDS_ENV			[Default: not defined]

    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.

RESOLVER_ENV			[Default: defined]

    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.

DITROFF_ENV			[Default: defined]

    DITROFF_ENV is defined if ditroff is available for printing
    Andrew Toolkit documents. (See installation of printing.)

DEFAULT_ANDREWDIR_ENV	[Default: /usr/andrew]

    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.

LOCAL_ANDREW_SETUP_ENV	[Default: not defined]

    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:
        /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.

    An AndrewSetup file could, for example, contain the line

        AndrewDir: "full path of andrew tree base not in quotations"
        RequiredSubsFile: /usr/lib/RequiredSubscriptions

DEFAULT_LOCALDIR_ENV	[Default: "/usr/local"]

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

NDBM_ENV			[Default: defined for only some platforms]

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

GETDOMAIN_ENV		[Default: defined for only some platforms]

    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.

RELEASE2_ENV			[Default: not defined]

    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.


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

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.

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"):

*** 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 */


1.2.9	Notes on Installation on a IBM RS/6000

To build on this platform you must use the version of imake in
/usr/lpp/X11/Xamples/util/imake.

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

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=".

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

1.2.12 Notes on HP machines

This release is believed to work on HP9000/800's running HP/UX 8.0. It
has also been ported to 300's, 400's and 700's, but those ports have not
yet been merged into our release -- we expect to merge those ports into
a future release/patch. Support for pre-8.0 versions of HP/UX is thought
to be broken at the time of this release.

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:

    {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:

    make World

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

    make Makefiles
    make dependInstall

You can clean out the directories using:

    make Clean

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

NOTE: if you are using LINKINSTALL_ENV (default on) you will probably
want to use 'make Tidy' instead of '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
"make Install" instead of a "make dependInstall". The dependencies
shipped with the tape should work for all machine types; we remove
general system include files from the dependency list.

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

    limit stack 2048


2.1	Error Recovery

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 

    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

    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

    make Install

2.1.2	Common Problems and their Causes

AMS Mail Aliases: 

If you build your UCB sendmail with the ``DBM'' option set, aliases in
/usr/lib/aliases are case-sensitive; if you build it without that
option, they're case-insensitive. For purposes of validating user names,
AMS assumes that aliases in /usr/lib/aliases are case-insensitive. This
might mean that a name that validates OK with AMS might be rejected by
UCB sendmail, if that sendmail uses DBM to do its alias lookup.

Console: 

You may see the following error message: 

    |>> console:<getstats/gvm> Cannot open /dev/kmem - will not
    monitor Disk and GVMStats <<| 
    console: ->> Try 'Restart Stats' Menu <<

If you get this message, your ``getstats'' program, installed from
atk/console/stats/common, wasn't installed with sufficient privilege to
be able to open /dev/kmem. This happens because your /dev/kmem is
protected against global reading, but you didn't do an Andrew
installation from an account with enough privilege to install
``getstats'' set-uid or set-gid. One possibility for this is that you
are running AFS although you didn't turn the AFS flag on for the
compilation. In order for console to monitor information available only
through /dev/kmem, you'll have to do the following: 

    cd ..../atk/console/stats/common
    su admin (or su root)
    chmod 4555 getstats

We have not included any consoles specifically tailored to a non-AMDS,
non-AFS environment. We hope to have some available in future patch
distributions. 

Fonts:

Some users do not remember to run mkfontdir in the ${DESDIR}/X11fonts
directory after the dependInstall operation is complete. If you do not
do so, you will see an error message similar to the following: 

    <appname>X error BadValue, integer parameter out of range ...

Running on HP-UX, you may see problems with the fonts. A possible
workaround for the font problem is to change the bodyfont font
preference in your preferences file to some font that is in the X
default font path. 

Some formulation of the bdf files causes either convertfont or the
window system to miscount the position of the glyphs in the font. This
means that the window system doesn't believe that you have glyphs for
lower-case characters. 

The distributed Andrew fonts are tailored for about 80 pixels to the
inch. By default these are not used, since for workstations with other
resolutions it is generally best to utilize the X fonts instead. See the
discussion of ISO80_FONTS_ENV above.

Help: 

If help files cannot be found or the alias data base is missing, the
following make operations from the root of the object tree may help:

    make dependInstall SUBDIRS='helpindex helpaliases'

These operations can be repeated as desired.

Imakefile/Makefile: 

Changes should never be made to the Makefile. All changes should be made
to Imakefile; "make Makefile" to regenerate that one file, or "make
Makefiles" to regenerate the Makefiles in all subdirectories,
recursively.

"make clean" and "make Clean" do not delete the Makefile, so a
subsequent "make Makefile" says it is up to date, i.e., comparing its
own timestamp against itself. Beware: once you remove the Makefile from
a directory, you can't say "make Makefile" there again, You can,
however, rename Makefile to another name and say "make Makefile -f
newname". 

Spell Checking: 

If Ispell, the spelling checker used by ez, is not available at your
site or is not along your path, ez will not be able to perform this
function. Ispell is widely available (e.g. via anonymous FTP off of
uunet.uu.net). All an installer has to do to get ez spell checking to
work is to install ispell somewhere along users' path. The following
.atkinit line will then be useful:

    addmenu "spell-check-document" "Search/Spell~1,Check Spelling~30" textview

Debugging the System:

In order to debug ATK applications you will need to have gdb version 3.5
or greater from the Free Software Foundation:

    Free Software Foundation, Inc.               Telephone: (617) 876-3296
    675 Massachusetts Avenue          Electronic mail: gnu@prep.ai.mit.edu
    Cambridge, MA 02139  USA
 
To compile the system such that symbol tables exist add these two lines
to your site.mcr:

        CDEBUGFLAGS = -g
        MAKEDODEBUG = -g

To debug the raster application you would first load the
statically-linked portion of the ATK run-time system, called runapp,
into gdb. It is important that the above make.1 macros are set to
include the -g switch so that the symbol table is created. There is no
use attempting to use gdb if the system has not been built with the -g
switch.

% gdb runapp
GDB, Copyright (C) 1987 Free Software Foundation, Inc.
There is ABSOLUTELY NO WARRANTY for GDB; type "info warranty" for details.
GDB is free software and you are welcome to distribute copies of it
 under certain conditions; type "info copying" to see the conditions.
Reading symbol data from runapp...
done.
Type "help" for a list of commands.
(gdb) run -d ezapp foo.ras -d
Starting program: runapp -d ezapp foo.ras -d
Starting ez (Version 7.0, ATK 15.0); please wait...
 raster: text = 0x10046594  data = 0x10049280  entry = 0x100498a8
 rasterview: text = 0x1004f820  data = 0x1005cc60  entry = 0x1005f8d8
 rasterimage: text = 0x1006701c  data = 0x100675d0  entry = 0x10067810
 pixelimage: text = 0x1006e758  data = 0x100703bc  entry = 0x1007068c

To load the symbol table for the raster dynamic object you would use
this command on a Sun or a DECstation 3100[An Andrew ToolKit view (a
footnote) was included here, but could not be displayed.]:
(gdb) add-file raster.dog 0x10046594

and on an RT:
(gdb) set-rel 0x10046594
(gdb) add-file raster.dog

Note that the addresses passed to these gdb commands come from the text
address that runapp outputs when the -d switch is used (the second -d
switch prevents runapp from forking itself to become an orphaned
process). To determine which module to load in the fashion described
above compare the various text addresses with the address at which the
program failed. For example, if the program died at address 0x1004a520
you would find that address between what was reported as the start of
the text segments for raster and rasterview. Since the raster module was
loaded first, we can conclude that the failure was somewhere in the
raster module.
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. 


2.2.1	Overhead
    addalias - adds aliases for help probes
    class - an object-oriented C language preprocessor used by ATK
    cmenu - the ATK stack-of-cards X11 menu package
    conv - several conversion programs for sites which have used
        earlier versions of the Andrew distribution.
    eli - the ``embedded lisp interpreter'' used by AMS
    errors - a package for handling some low-level error reports
        in a uniform way
    fonts - fonts used by ATK programs
    genmake - a script for generating Makefiles from Andrew
        style Imakefiles
    index - utility to map class names to file names
    mail - library of AMS functions
    malloc - the Andrew version of malloc
    parsec - a C language parser plus a procedure to clean up
        YACC output
    pobbconf - houses the mechanism to turn on AMDS at your site
    rxp - a regular-expression package used in ELI
    snap2 - an RPC package used by the Andrew Message System
    sys - a program used for distinguishing between different
        system (hardware/os) types
    util - lots of utility functions. Includes the White Pages readers
    wpi - allows mail-based updates to White Pages entries
    wputil - programs and data to initialize and build a White Pages
    xicons - a small collection of icons for use under X window
        managers


2.2.2	ATK

        1. Basics (or Core):
        - underlying ATK libraries
        - ez - a multi-media editor
        - typescript - a flexible csh window (not TERMCAP)
        - raster - a raster (bitmap) editor
        - hyplink - a hypertext-like link inset
        - adew - A direct manipulation user interface builder
        2. Basic Utilities
            - console - a system monitoring program
            - ezprint - allows printing of ATK format documents
            - champ - a calendar program
            - preview - a ditroff previewer
        3. Basic Insets
            - eq - an equation editor
            - fad - a simple frame animator
            - table - a simple spreadsheet
        4. Building Blocks
            - apt - basic components
            - org - an organizational chart editor
            - bush - a directory tree/file browser
            - zip - an hierarchical drawing editor
            - chart - a chart/graph program (line graphs, pie
            charts, histograms etc.)
            - calc - a simple calculator
        5. Help (program)
            - help - a user interface for help files and man pages
        6. Text Extensions
            - ctext - a C text editing package
            (this package is not an active interpreter - only a formatter)
            - lookz - a style editor
            - spell - a spell checker. See note below.
        7. Authoring Systems
            - ness - An embedded string manipulation authoring system
        8. Auxiliary Utilities
            - datacat - a utility for concatenating two (or more)
            ATK format files together
            - toez - a utility for converting files (scribe, troff)
            into ATK format
        9. Auxiliary Insets
            - gob - 
        10. Example Programs
            - examples illustrating how to write an inset and application
            - examples from N. Borenstein's book on the Andrew Toolkit


2.2.3	AMS

    delivery - the fundamental programs in AMDS that manage mail
        queues and deliver mail
    demo - builds a multi-media folder that you can use as an
        AMS/ATK demo
    doc - AMS documentation of all sorts
    flames - ELI application that handles new messages interpretively
    libs - libraries used in building AMS user agent programs
    ms - the RPC veneer over the lower-level parts of those AMS
        libraries, making the MessageServer process
    msclients - AMS user agent programs
    utils - useful programs in managing AMDS installations


2.2.4	ATKAMS

    messages - our flagship AMS program; multi-media mail and bboards


2.2.5	Contrib

Among other things, you will find:

    - alink - an audio inset for Sparcstations
    - gestures - a gesture-based text view
    - time - analog and digital clocks, time-of-day and
        writestamp (useful in documents)
    - mit/annot - a note and a postscript inset
    - mit/util - header/footer object for text, a printer option
        dialog box, ez2ps
    - ltext - a LISP text editing package
    - mtext - a MODULA2 text editing package
    - ptext - a PASCAL text editing package
    - rctext - another C text editing package
    - rmtext - another MODULA 2 text editing package
    - m3text - a MODULA 3 text editing package
    - tm - an alternative to typescript
    - 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.

2.3	Make Targets

The generated Makefiles contain the following targets:

        Makefile: Generates the Makefile from the Imakefile in the
        current directory (assuming there is already a Makefile present).

        Makefiles: Generates the Makefiles for subdirectories (does not
        generate the Makefile for the current directory).

        all:
                Builds the contents of the current directory.
                
        depend:
                Generates dependency information for the current directory.
                
        doc:
                Installs documentation from the current directory.
                
        Doc:
                Same as above but recurses thought subdirectories.
                (depends on "doc")

        aliases:
                Generates 'help alias' information for the current directory.
                
        Aliases:
                Same as above but recurses through subdirectories.
                (depends on "aliases")

        install:
                Installs the binaries, libraries, include files, etc.
        for the current directory.
                (depends on "all" and "doc")

        Install:
                Same as above but recurses through subdirectories.
                (depends on "install")

        dependInstall:
                Generates dependency information.
                Installs binaries, libraries, include files etc.
                Installs documentation.
                Recurses through subdirectories.

        world:
                (depends on "depend", "install", "aliases")
                (for current directory only)

        World:
                Same as above but recurses through subdirectories.

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

        Tidy:
                Same as above but recurses through subdirectories.

        clean:
                Removes all generated files (*.o, *.a, etc.) in current
        directory only.
                (depends on "tidy")

        Clean:
                Same as above but recurses through subdirectories.



2.4	What Gets Built

During the build process, the ATK 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:

        ${ANDREWDIR}/bin - Runnable applications
        ${ANDREWDIR}/dlib/atk - Dynamic objects
        ${ANDREWDIR}/X11fonts -ATK specific fonts for X
        ${ANDREWDIR}/xnwsfnts - ATK fonts for running under Open Windows
        (if enabled)
        ${ANDREWDIR}/lib/tpls - Style templates for text-oriented objects
        ${ANDREWDIR}/lib/consoles - Console descriptions
        ${ANDREWDIR}/lib/atk - Compile time libraries
        ${ANDREWDIR}/include/atk - Compile time include files
        ${ANDREWDIR}/help - Help files
        ${ANDREWDIR}/doc - Doc files
        ${ANDREWDIR}/etc - Auxiliary files, usually not accessed
        directly by users


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.

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:
    32M

Total Objects:

    Dec Mips: 125M
    Sun4: 170M
    RS/6000: 220M

Binaries:

    Dec Mips: 65M
    Sun4: 82M
    RS/6000: 60M

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

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:

    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:

    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 

    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.

5	Configuring a Help System 

5.1	The index

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

    $(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):

#	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:

#	comment
    Any line beginning with "#" is a comment and is ignored.

dir	actual-directory-name	link-directory-name
    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:

    dir /afs/andrew/machinetype/usr/man/man1 /usr/man/man1

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

include	filename
    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.

key	keyword		filename
    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

    make dependInstall SUBDIRS=helpindex

The aliases can be rebuiilt from the root with

    make dependInstall SUBDIRS=helpaliases

or for any subtree with the command:

    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:

    $(DESTDIR)/doc/help/Maint.doc

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.

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:

    Andrew Toolkit Information
    Information Technology Center
    4910 Forbes Avenue
    Carnegie-Mellon University
    Pittsburgh, PA 15213-3890
    U.S.A.
    (412) 268-6700
    FAX: (412) 268-6787


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. 

    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: 

    info-andrew@andrew.cmu.edu

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

    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.
