Installing Andrew Andrew User Interface System Version 8 (September 1996) Andrew Consortium School of Computer Science Carnegie Mellon University 5000 Forbes Avenue Pittsburgh, PA 15213-3891 USA Phone: (412) 268-6710 Fax: (412) 268-5576 Web: http://www.cs.cmu.edu/~AUIS Demo: finger @atk.cs.cmu.edu Archives: ftp.andrew.cmu.edu: /pub/AUIS Bugs: info-andrew-bugs@andrew.cmu.edu Info & Subscriptions: info-andrew-request@andrew.cmu.edu In the documentation, the source directory will be referred to as $/ and the destination directory as $ANDREWDIR/. If you are reading an all-ASCII version of this file, the version in Andrew format is in the distribution at: $ANDREWDIR/doc/ADMINISTRATOR/INSTALL.ez Copyright Carnegie Mellon University 1991, 1996 - All Rights Reserved. Copyright IBM Corporation 1988, 1991 - All Rights Reserved. Please see further copyrights and disclaimer at the end of this file. Introduction Greetings. To build Andrew for your local system, follow the instructions below. If you prefer to load a binary distribution, see our web pages at http://www.cs.cmu.edu/~AUIS/bin-dist/README or ftp from ftp.andrew.cmu.edu pub/AUIS/bin-dist/README If you have problems, please contact the Andrew Consortium at the addresses given in the README file. For a description of the files in the Andrew source distribution, see $/README ($/ indicates files in the source tree), which is installed as $ANDREWDIR/README and $ANDREWDIR/doc/README.ez (the installation tree is $ANDREWDIR). As noted in README, you must build and install the files distributed in environs.tar.gz and atk.tar.gz. To limit the installation to just these portions, some setting of _ENV and MK_ variables may be necessary in your site.h file (see section 3.2 below). 1. Space and Tools Requirements As shipped, the Andrew distribution is about 50 megabytes of source. Building everything generates both an object tree and a destination tree of installed binaries. For various platforms the sizes (in megabytes) as of February 1996 were: RS/6000 AIX 3.2.5: objects 215 installed 172 SunOS 4.1: objects 105 installed 75 Pmax UL4: objects 168 installed 108 HPUX 9.03: objects 136 installed 85 Linux: objects 95 installed 31 Installing a subset or using BuildInstallCramped can reduce these requirements substantially (see below). The object tree can be discarded after installation is complete. In addition to space requirements, the distribution assumes that you have the X Window System Distribution from MIT, including the following files and programs: imake -- generates Makefile from Imakefile (We do NOT use xmkmf, nor the X set of imake rules.) bdftosnf or bdftopcf -- font compiler makedepend -- generates dependencies in Makefiles Xlib -- X.V11 include files and libraries, version 4 or later You will need a C++ compiler to compile this release. g++ versions later than 2.6.3 should work. Other compilers which have been used include CSet++ on RS/6000s and the HP C++ compiler. The document $ANDREWDIR/doc/DEVELOPER/Porting.ez provides general rules for porting Andrew to a new platform. 2. Basic Installation Instructions In many cases the steps in this section are sufficient to build and install Andrew. Try them, if you like; but if they fail, please read other sections before you call us. In these notes the source directory will be referred to as $/ and the destination as $ANDREWDIR. 1. Create two directories having sizes somewhat bigger than those listed above, one ($/) for the source and build, the other ($ANDREWDIR) for the installed software. 2. Copy the sources into $/. 3. Copy the template files cd $/config cp presite.h.tpl presite.h cp site.h.tpl site.h cp site.mcr.tpl site.mcr 4. Edit presite.h to specify platform and compiler options. The default is to build with g++, which is assumed to be in your path. (However, on some platforms you must be sure the GNU binutils directory is NOT on your path.) 5. Edit site.h to set DEFAULT_ANDREWDIR_ENV. Set it to the full pathname of the destination directory. You may limit or expand your system with the various installation selection options. 6. Edit site.mcr, which is to contain your site's adjustments for Makefile parameters. 7. Check section 3 for possible changes you might need to config/site.mcr, config/site.h, and config/presite.h. 8. Check section 4 below for notes on your particular system type or X server. (There are notes for IBM RS/6000, Decstation Ultrix 4.2 and 4.3, SPARC, Sun Solaris, HPUX, Open Windows server, and Linux.) 9. Change directory to $/, and give the command make World This will take from four to twenty-four hours, depending on your system configuration. While you're waiting, please read the known problems list (The PROBLEMS file will appear in the top level of the source tree if known problems exist), or read through the remainder of this document. If the build fails to complete, you may be able to continue with a partial rebuild; see section 5. 10. If you installed the console application you will need to make $ANDREWDIR/bin/getstats and possibly $ANDREWDIR/bin/getconsole setuid root, or setgid to an appropriate group (often mem or kmem). Typically these programs need access to /dev/mem and /dev/console. 11. To use Andrew, users should have xxx/bin in their PATH environment, where xxx is the value of DEFAULT_ANDREWDIR_ENV as set in step 5 above. 12. If you have problems, please consult with your local system gurus. Error reports should be sent to: info-andrew-bugs@andrew.cmu.edu 3. 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. Before building Andrew, you should look through the several files that configure the system, and change them as necessary so that the Andrew software will be install correctly for your environment. Each file, and the modifications you may want to make, are explained below. Looking from the top of the extracted source tree, the files are: $/config/site.mcr $/config/presite.h $/config/site.h $/atk/console/lib/sitevars.h $/overhead/util/lib/svcconf.c $/overhead/mail/lib/mailconf.c $/helpindex/index.tpl The site.h, presite.h, and site.mcr files redefine variables that have been set in the allsys.xx and system.xx files: $/config/allsys.mcr $/config//system.mcr $/config/allsys.h $/config//system.h where "" is the machine type on which you plan to install and build Andrew. The available machine types are: Machine Type Operating System DEC MIPS Ultrix 4.3 pmax_ul4 IBM RS/6000 AIX 3.2 rs_aix3 HP 700 HP UX hp700_90 HP 800 HP UX hp700_90 386/486 Linux (ELF) ix86_Linux Sparc SunOS sun4_41 Sparc Solaris sun4_5x One additional configuration file is for your AndrewSetup. See section 3.5. 3.1 The site.mcr{.tpl} Files The definitions in $/config/allsys.mcr, $/config//system.mcr, and $/config/site.mcr 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 are processed first, then system-dependent overrides in system.mcr, and finally site-specific overrides in site.mcr. You should NOT edit either allsys.mcr or your system.mcr. Instead, copy $/config/site.mcr.tpl to $/config/site.mcr edit the latter. You can override make variables in your site.mcr file by using lines such as ``FOO=bar''; as a reminder of this, the variable names are given below followed by an equal-sign. The site.mcr file may also use #ifdef/#endif pairs to select which `make` variable settings should be used. `Make` does lazy evaluation of its variables, so it is possible to override variables such as CDEBUGFLAGS in site.mcr, or even in the Imakefile itself. In the simplest case, copy $/config/site.mcr.tpl to $/config/site.mcr, which results in the following default values. AFSBASEDIR= [Default: (empty)] AFSBASEDIR is the full path to files installed by an AFS installation. (AFS is the Andrew File System distributed by TransArc . Most installations will not have AFS.) AFSBASEDIR is used only if AFS_ENV is defined; otherwise, it is ignored entirely. If used, these files are expected to exist: $(AFSBASEDIR)/include/afs and $(AFSBASEDIR)/lib/afs. Other specific requirements are listed in the discussion of AFS_ENV and AFS30_ENV in the section describing the *.h files. Additional definitions are unlikely to change. However, you may want to check these values: BASEDIR= [Default: DEFAULT_ANDREWDIR_ENV, from $/config/allsys.h or $/config/site.h] BASEDIR specifies the root of an Andrew installed tree from which utilities are to be executed during the build. For most builds, this should be the same directory into which the tree is getting installed, as dictated by DESTDIR. In general, BASEDIR should not be set. It will automatically default to DEFAULT_ANDREWDIR_ENV. The value for BASEDIR is the path into which the installation process should put the Andrew system software, while the value for DEFAULT_ANDREWDIR_ENV (cf. section 3.2.2) 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. In general, when the build starts, BASEDIR will point to an empty directory. CC= [Default: cc] C compiler to use. CDEBUGFLAGS= [Default: -O] CDEBUGFLAGS are passed to the C compiler when compiling programs. CPPC= [Default: g++] C++ compiler to use. CSHELL= [Default: /bin/csh] CSHELL specifies the path to the C shell. DESTDIR= [Default: $(BASEDIR)] DESTDIR should always be identical to BASEDIR for system builds. DESTDIR specifies 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, etc, doc, and help. DESTDIR may be set to values other than BASEDIR only in the course of local Andrew-based development. GCCLIBDIR= [Default: computed] GCCLIBDIR specifies where the gcc library directory is located. This value is computed automatically as long as gcc is on the path. GNUEMACS= [Default: not defined] Specifies the full pathname to the executable for the GNU version of emacs, for use by the contrib/batmail program. This does not have to be set if users will have emacs in their path. Note that if the preferred emacs is called a name other than "emacs", such as "gnuemacs", then GNUEMACS must be set to the path and program name. IMAKE= [Default: $(XUTILDIR)/imake] XMAKEDEPEND= [Default: $(XUTILDIR)/makedepend] XMKFONTDIR= [Default: $(XUTILDIR)/mkfontdir] XFC= [Default: $(XUTILDIR)/bdftopcf] These four variables must be set to the full path names of the corresponding X utilities. These utilities are not always installed as a part of X11, but are found in the X11 source tree in the util directory. (If FONTS_TO_PCF_ENV is not set, then the default value for XFC is $(XUTILDIR)/bdftosnf.) INCLUDES= [Default: -I${BASEDIR}/include/atk -I${BASEDIR}/include -I$(AFSBASEDIR)/include -I${XINCDIR}] Specifies where compilations should look for include files. If AFS_ENV is not set, the AFSBASEDIR term is omitted from the default value. INSTALL= [Default: $(BASEDIR}/etc/install] The value of INSTALL should be the full pathname to the install program. By default, BUILDANDREWINSTALL_ENV is defined and Andrew crfeates its own install program, which resides as shown by the default value. You can override this value to utilize some other install program or to add switch specifications like '-ns' to avoid stripping binaries. JPEGLIBDIR= [Default: $(BASEDIR)/lib] If there is already a JPEG distribution at your site, #undefine MK_JPEG in the site.h file and set JPEGLIBDIR to the library containing libjpeg.a. KRBLIB= [Default: (empty)] If your AFS protection server relies on the MIT Athena Kerberos library, set KRBLIB to name where the Kerberos library lives. Usually this is set automatically if needed. RESOLVLIB= [Default: empty string] RESOLVLIB denotes the full path of the domain name resolver library. If RESOLVER_ENV is defined and the resolver functions are not in libc.a then RESOLVLIB should be set to the library which contains these functions, otherwise RESOLVLIB should be empty. The default value (the empty string) is useful if the resolver code is in your libc.a. If the resolver code is in a separate library, such as /usr/lib/libresolv.a, that name should be the definition for RESOLVLIB; define it in your site.mcr file. The programmer's interface to the resolver library has changed over time. The file $/overhead/mail/lib/valhost.c (which is built into DESTDIR/lib/libmail.a) makes calls to different versions of that programmer's interface, using the fact that definitions in the resolver's exported ``include'' files changed slightly with successive releases. In particular, it checks for the definition of NO_DATA in the 4.8 version of /usr/include/netdb.h and for the definition of CQUERYM in the pre-4.7.3 version of /usr/include/arpa/nameser.h. If your versions of these include files correspond to the version of the resolver named by RESOLVLIB (or libc.a otherwise), you will have no trouble with its interface to Andrew. The $/overhead/mail/lib/valhost.c file contains suggestions for what to do if this is not the case. SHELL= [Default: /bin/sh] SHELL specifies the path to the Bourne shell. TIFFLIBDIR= [Default: $(BASEDIR)/lib] If there is already a TIFF distribution at your site, #undefine MK_TIFF and set TIFFLIBDIR to point to the library containing libtiff.a. XINCDIR= [Default: /usr/include] Where to find X include files. XLIBDIR= [Default: /usr/lib] Where to find libX11.a. XUTILDIR= [Default: /usr/bin/X11] Where to find X11 utilities like makedepend, mkfontdir, and imake. YACC= [Default: yacc] If Bison is installed, you may change this variable to 'bison -y'. 3.2 Compilation Environment: $/config/site.h Preprocessor variables are defined by the include file . This file is included in every source compilation by including and is also included in every Makefile to render the preprocessor variables accessible during builds. in turn has four segments: , , many internal declarations, and . The first and last of these are specified by the site that builds Andrew and reside in $/config from whence they are installed in $ANDREWDIR/include. With this ordering, system.h can override allsys.h and site.h can override both. The file specifies attributes of the platform and compiler which need to be known before defining other variables. The file completes specifying the environment and chooses which portions of Andrew to build. These three topics are described in three subsections. You should NOT edit either $/config/allsys.h or $/config/system.h. Instead, copy $/config/site.h.tpl to $/config/site.h and edit the latter. To add or change a definition of VARIABLE, use this sequence #ifdef VARIABLE #undef VARIABLE #endif #define VARIABLE value If there is no other appropriate value, the value should be 1. To cause a variable to be undefined, use just the first three lines of the sequence. To indicate that the variables listed in this section are set and unset with #define, their names are followed by '#' in the descriptions. 3.2.1 presite.h - Platform and Compiler Selection GNU_ENV# [Default: defined] If g++ is used for compilatation, GNU_ENV must be set. IBMCSET_ENV# [Default: not defined] If GNU_ENV is undefined on an AIX system, the CSET compiler can be used by defining IBMCSET_ENV. _IBMR2# [Default: not defined] For AIX4, _IBMR2 must be defined because there is no other way to tell that it is an AIX platform. SOLARIS# [Default: not defined] If building on Solaris, this variable must be defined. 3.2.2 site.h - Installation Destination; Facilities Available Site.h.tpl specifies the following variables which are likely to need to be overriden. 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 $/config/{allsys.mcr, system.mcr, site.mcr} if, for instance, all the Andrew software is to be built using one path, and executed using another path. Because Andrew software uses dynamic binding of information, it needs to know where to find various installed objects, libraries and files. The software assumes that everything will be found relative to the installed Andrew tree. The pathname of the top of the tree is, by default, $(DEFAULT_ANDREWDIR_ENV). If, however, you have not installed the Andrew software in $(DEFAULT_ANDREWDIR_ENV), you may override the software's idea of where the Andrew installation is to be found. This value may be overridden by each user's setting the environment variable $ANDREWDIR to another pathname, or by the administrator using the AndrewSetup mechanism (see $/overhead/util/lib/setup.help) and specifying a value for the ``AndrewDir:'' attribute. See the discussion under LOCAL_ANDREW_SETUP_ENV. 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, 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 The following variables will not usually have to be modified. ANSI_COMPILER# [Default: system/compiler dependent] You will normally not need to modify this symbol. When not defined this symbol causes special measures to be taken to compile some code. (Particularly in $/overhead/image.) 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''. DITROFF_ENV# [Default: not defined] DITROFF_ENV is defined if ditroff is available for printing Andrew Toolkit documents. Printing for new installations should be done direct to postscript; this is specified in allsys.h where we find; #define PSPRINTING_ENV 1 There is no effective alternative to PostScript printing if insets are to be printed. 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 $/config/site.h file if you are using a version of Ultrix that has this bug. 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. If you undefine RESOLVER_ENV in your site.h file you should set RESOLVLIB to be empty in your site.mcr file. 3.2.3 site.h - Defining What Parts of Andrew to Build The default settings for this group of options will build most of Andrew, but not all. This includes the basic editor and typescript, the help system, a number of objects (including text, ctext, raster, spreadsheet/table, drawing, animation and equations), and the messages interface programs (messages, cui, vui). The set has been chosen to allow you to view most of the messages demonstration folder. You may add other parts of the system by defining the appropriate flags in your $/config/site.h file. You can also choose to build a smaller portion of the system by undefining the appropriate flags. Building highlevel directories is controlled with xyz_ENV variables. Individual directory builds are controlled with MK_xyz variables. Some MK_xyz variables control a group of directories. 3.2.3.1 Top level build options The top level build directory tests these xyz_ENV variables: AMS_ENV (ams atkams) [Default: built] X11_ENV (xmkfontd) [Default: built] WWW_ENV (WWW) [Default: built] MEGARUNAPP_ENV (megarunapp) [Default: built] CONTRIB_ENV (contrib) [Default: not built] SITE_ENV (site) [Default: not built] where the parenthesized names are the subdirectories which are built if the variable is defined. 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. This distribution also contains Metamail. See METAMAIL_ENV. If you are not installing ams and atkams (the sources from auis4.tar.Z) then you must undefine AMS_ENV by adding the following line to your $/config/site.h file: #undef AMS_ENV CONTRIB_ENV# [Default: not defined] CONTRIB_ENV controls the construction of the contributed software found under source directory $/contrib. At present, this includes (on selected platforms) alink - an audio inset from Bell Labs for Sun platforms, runbutton - a button object that runs scripts, and tm - the termulator shell interface. Other elements of $/contrib can be added by defining the variables noted in 3.2.3.4, below. In order to build the $/contrib section, you need to pick up the contrib.tar.Z file from the ftp server. MEGARUNAPP_ENV# [Default: defined] Runapp is the binary which is executed for any Andrew application; the specific application is chosen at run time from the program name. If megarunapp is not built, the installed runapp will dynamically load many applications. Building megarupp causes all Andrew applications and libraries to be included in one file. This works well in systems with shared, dynamically loaded libraries, but is unwieldy if all libraries must be loaded for every application. 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 $/site. See further documentation in $/site/README.site. WWW_ENV# [Default: defined] If WWW_ENV is defined, the build will create the web browser server (awww from $/WWW) and web browser client (web from $/atk/web). Otherwise the web browser will be unavailable. (Caution: even if you have a version of www compiled for other purposes, the Andrew www--called awww--must be built. Other versions of www do not respond to Andrew web browser requests.) X11_ENV# [Default: defined] Since X11 is the only supported window manager at present, this variable should always be defined. In the top level make tree, this variable causes xmkfontd to be built; this builds the index in the fonts directory. FUNCTION_INDEX_ENV# [Default: not defined] Define this is you want to build and install the source indexes doc/atk/FilesList and doc/atk/FunctionIndex. See BuildAndTest.ez. (This variable is tested in $/doc/Imakefile.) 3.2.3.2. Overhead build options CPPCONVERTER_ENV# [Default: not defined] If your site has Andrew source code written in C for version 6., it can be converted to C++ code for version 8. #Define CPPCONVERTER_ENV in your site.h file and follow the instructions in $/doc/atkprogramming/Conversion.ez. As a result of defining this variable two directories will be built $/overhead/c++conv - the converter $/overhead/class - the old preprocessor for header files MK_JPEG# [Default: defined] If your site has already built a jpeg library, you can prevent building it as part of Andrew by undefining MK_JPEG. You must also set JPEGLIBDIR in the site.mcr file. MK_METAMAIL# [Default: defined] If your site has already built metamail, you can prevent building it as part of Andrew by undefining MK_METAMAIL. MK_TIFF# [Default: defined] If your site has already built a tiff library, you can prevent building it as part of Andrew by undefining MK_TIFF. You must also set TIFFLIBDIR in the site.mcr file. WHITEPAGES_ENV# [Default: not defined] The white pages facility provides a data base in which to do approximate name matching, as for instance in receiving mail or doing the `finger` command. To build this facility, #define this variable. Two directories will be built as a result wputil - library of data base access code used by tyhe mail system wpi - an interactive program for users to query/update the data base 3.2.3.3. ATK build options Every build of $/atk will build these utility directories basics support supportviews utils frame extensions atkvers syntax doc these inset directories text textaux ez hyplink value textobjects adew raster and the directory that builds the main loadable module apps. Other features are built by default, but can be eliminated in groups or individually. In each of the next sections, the entire group can be eliminated by #undef'ing the MK_ variable at the head of the first line. If a group is turned off, each members can be built anyway by #define'ing the individual MK_ variables given on the indented lines. The $/atk/Imakefile 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. 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. MK_BLD_BLKS# MK_APT# apt Apt is a library of programming tools used by org, bush, and some other insets. MK_ORG# org Org is an inset for viewing hierarchical information MK_BUSH# bush Bush is a directory browser. MK_CHART# chart Chart displays chart information. MK_FIGURE# figure Figure is the Andrew drawing editor. MK_BASIC_UTILS# MK_LAUNCHAPP# launchapp Launchapp is a highlevel application which offers an on-screen menu to click to launch other Andrew applications. MK_CONSOLE# console Console monitors the system status and displays it as a line graph or other mode under control of the LACC language. (Console is not yet working on several of the newer platforms.) MK_EZPRINT# ezprint Ezprint is a script which takes a file name as argument and causes it to be printed ala Andrew conventions. MK_TYPESCRIPT# typescript Typescript is a shell interface. The user's input is in bold and system responses are not. MK_BASIC_INSETS# MK_EQ# eq Equation editor. MK_FAD# fad Frame animation editor and displayer. MK_IMAGE# image Multi-color, multi-format image displayer. MK_TABLE# table Spreadsheet and table editor / displayer. MK_WIDGETS# widgets A library of basics widgets and tools for building new ones. MK_HELP_APP# MK_HELP# help Help is the help browser application. MK_ROFFTEXT# rofftext Rofftext is used by 'help' to convert troff files to Andrew. It can be used as a standalone application. MK_TEXT_EXT# MK_SRCTEXT# srctext Provides language-specific editors for assembler, C++, c, help files, lisp, modula, modula3, perl, Pascal, raw ASCII. MK_LOOKZ# lookz The ez styles editor. MK_MIT_TOOLS# note A note inset is displayed within text, but prints as a footnote. ps The ps inset stores a PostScript string. On window managers with DisplayPostScript, the inset displays its image. gnucompat Defines a number of proctable entries useful for making ez behave more like gnu-emacs. See the documents $/atk/textaux/gemacs* or give the command `help gnucompat'. vutils Defines proctable entry `vutils-fork-help`. When called, it forks a process and runs help in a new window. ez2ascii Converts an ez file to ASCII.. ez2ps Converts an ez file to PostScript. MK_AUTHORING# MK_LAYOUT# layout An empty inset that provides for arbitrarily arranging other insets within it. MK_CONTROLLERS# controllers Sample ADEW applications. See $/atk/adew/Tutorial.doc. MK_NESS# ness The Andrew extension language. Can be used to write scripts that respond to keycodes, can be embedded in documents, or can be run stand-alone. Ez formatted text is a primitive data type of the language. MK_CREATEINSET# createinset Builds a set of dummy source files for a raw inset. This is the easiest way to start writing an inset. MK_AUX_UTILS# MK_DATACAT# datacat Concatenates together two or more ez files. MK_PREFS# prefed This is the 'prefs' editor which edits ~/preferences files. MK_TOEZ# toez Converts Scribe or Troff source text to ez format. MK_HTML# htmltext An editor/viewer for web pages in HTML format. web Web browser application. (Not built if WWW_ENV is #undef'ed.) MK_EXAMPLES# [Default: not defined] examples Example source code. NOT installed by default. 3.2.3.4 Contrib build options To build any of the facilities described here, you must also #define CONTRIB_ENV in the site.h file. MK_BATMAIL# [Default: defined] Batmail is a gnu-emacs interface to the messages mail/bboard reading system. (AMS_ENV must also be set to use this package.) MK_BDFFONT# [Default: defined] Bdffont is an editor for font files which are in bdf format. MK_CALC# [Default: not defined] Calc is a simple calculator. MK_CHAMP# [Default: not defined] Champ is a calendar/scheduling application with several interfaces. MK_CONTRIB_HTML# [Default: not defined] This is an older htmltexdt editor preserved for those who want it. MK_DEMOS# [Default: defined] Building DEMOS will build the circlepi program, which demonstrates how to compute pi by squaring a circle. MK_EATMAIL# [Default: defined] Eatmail consumes mail delivered to standard Unix queues and makes it available to the messages application. Sites will need this if they are not using AMDS (which most will not). (AMS_ENV must also be set to use this package.) MK_GOFIG# [Default: defined] Gofig is an inset that manages a diagram of a go game. It includes a conversion from diagrams of x's and o's into its own form. MK_GTEXT# [Default: defined] Gtext is Dean Rubine's gesture library. With it you can construct an interface to ez which is based on mouse gestures. MK_MIT# [Default: not defined] Turning on this option allows four further options: MK_NEOS# [Default: not defined] Neos is a system for the electronic submission and grading of papers. It requires Kerberos. (Currently it has compilation errors.) MK_RTF# [Default: not defined] 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. MK_SCRIBETEXT# [Default: not defined] Scribetext takes a Scribe compatible manuscript file and produces an ATK datastream file capable of being used by ATK client programs. MK_STROFFET# [Default: not defined] Stroffet is an inset for embedding troff commands in a document. It is somewhat less prone to error than the equivalent operation of marking the text with the FormatNote style. Works only with troff printing. MK_PREVIEW# [Default: not defined] The preview application views device-independent-troff files on screen. It works only with troff printing. MK_TIME# [Default: defined] This directory includes three insets: Inset `clock` displays an up-to-the-second, running analog clock. Inset `timeoday` displays a digital clock or the date. Inset 'writestamp' displays the date and time the file was last written to disk. MK_VUI# [Default: not defined] Vui is an interface to the messages system suitable for ASCII-only terminals. MK_WPEDIT# [Default: not defined] Wpedit provides a window interface for editing the user's entry in the white pages. The same functionality is available in a command line interface as `wpi.` MK_ZIP# [Default: not defined] Zip is an older generation Andrew drawing editor. It has the capacity to define successively move elaborate images which available by zooming in to the base drawing. 3.2.4 site.h - X11 and Fonts DPS_ENV# [Default: not defined] DPS_ENV should be defined if your systems support the Display PostScript extension to X Windows. IBM's X.V11R3 server product, DEC's DecWindows product, and Sun's Solaris 2.3 all have this extension, while the MIT servers typically do not. Defining this variable will cause some code to attempt to link against the DPS libraries. It will also cause some code to attempt to contact the DPS extension of an X server at runtime. 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. 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 $ANDREWDIR/X11fonts to supply pointers to the X11 fonts that comply with the ISO 8859 defined international character set. For sites that have these fonts, this is the preferred option, since it will make accented characters available to users and programmers in most applications, including messages. See the cpchar help file for details on how to use them. This option also provides better behavior when used with R5's scalable fonts, and with 100dpi fonts, and it also eliminates the need for additional fonts to be installed in the destination directory. The only known drawback is that these fonts are not as carefully tuned as the their Andrew counterparts. 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 site files define a CONVERTFONT macro to be /usr/openwin/bin/convertfont. You can override this default value in your $/config/site.mcr file. 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 $/config/site.h file if you do not want the Andrew fonts to be built. 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. X11_ENV# [Default: defined] X11_ENV is defined if the Andrew Toolkit is to be built for the X.11 Window System. 3.2.5 site.h - Mail System Options AFS_ENV# [Default: not defined] (Note: if AFS_ENV is defined, then WHITEPAGES_ENV should also be defined. Even if you don't intend to actually use the white pages.) AFS_ENV is defined if the Andrew File System is being used. This is a distributed file system available from Transarc Corporation. For more information, please send mail to afs-sales+@transarc.com. If AFS_ENV is defined, it is assumed that the following files will be available under AFSBASEDIR : 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 RUN_AMDS_ENV is also defined, so that $/contrib/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 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 $/ams/delivery/{mail,sendmail}. AMS_SUBSCRIPTIONMAPFILE# [Default: ".SubscriptionMap" or ".SubsMap"] This is the name of one of the files AMS uses to store information about the bboards which exist. For historical reasons it defaults to .SubscriptionMap unless compiling on an HP or a SysV system (where M_UNIX is defined). The reason for the distinction is the limitation of these systems to 14 character filenames. If bboards will be stored on filesystems with this limitation all clients which access them must be compiled with: #define AMS_SUBSCRIPTIONMAPFILE ".SubsMap" in the site.h file. If HP or SysV systems without the 14 character limit on filenames are used all clients should be compiled with: #define AMS_SUBSCRIPTIONMAPFILE ".SubscriptionMap" If you're not sure and don't have any existing AMS bboard trees the ".SubsMap" setting is safe for all systems. If you have an existing AMS bboard tree you can check which setting to use with ls -a ...$/.MESSAGES/.Subs* (Where .... is replaced with the path to the top of the bboard tree.) METAMAIL_ENV# [Default: defined] Metamail is an implementation of MIME, the Multipurpose Internet Mail Extensions, a proposed standard for multimedia mail on the Internet. Version 2.7 of metamail is incorporated into the sources in $/overhead/external/mail/metamail. 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. 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. 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. 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. 3.3 sitevars.h The 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. 3.4 mailconf.c and svcconf.c The files $/overhead/util/lib/svcconf.c and $/overhead/mail/lib/mailconf.c contain configuration information for the mail system. It is likely that you will not have to change anything in this file; instead, once the system is built, you will be able to change these options via the AndrewSetup mechanism. The details concerning the information in this file can be found in the AndrewSetup documentation ($/overhead/util/lib/setup.help), the Andrew Message System Installation manuals (in $/ams/doc), the Andrew Message Delivery System Installation manual ($/ams/doc/AMDS.ins), and in the White Pages installation manual ($/overhead/util/lib/WP.ins). After making your initial system build, but before expecting the mail-related software to work, you should review the AndrewSetup help file to check whether the settings for the available options are correct for your system. If you have problems bringing up the mail system and you believe that it is a result of information contained in the svcconf.c or mailconf.c files, you should send mail to: info-andrew-bugs@andrew.cmu.edu 3.5 AndrewSetup The Andrew Setup file location is as described above in section 3.2.2. It contains various parameter specifications that a site administrator wishes to apply to all users. Full documentation for this file is in the distrbution at $ANDREWDIR/doc/ADMINISTRATOR/SetUp. Each line of Andrew Setup is a variable name, a colon, and a value. Here are a few variables that you may want to specify: ANDREWDIR: pathname Default: /usr/andrew This specifies the directory where Andrew software exists on your system. The reason this is a configuration option in addition to an environment variable is that environment variables are not accessible to programs not descended from your login shell. Several Andrew programs, notably the messageserver, pcserver, and anything spawned by those processes, are not descended from your login shell. HelpSendCommentOnAddress: string Default: info-andrew-request+help@andrew.cmu.edu This specifies the mailing address for comments submitted via the "Send Comment on Help" command. LOCALDIR: pathname Default: /usr/local This specifies the directory where local files and programs exist on your system. MessagesBugAddress: string Default: see Note This string is the mailing address to which automatic bug reports from the Messages program should be directed. If it is null, the option to send a bug report will not appear. Note: If compiled with CMU_ENV the default is "postman+auto-messages-bugs@andrew.cmu.edu". If compiled without CMU_ENV the default is "postmaster". PSCPrintCommand:string Default: lpr The default print command for pure PostScript. Not generally used. PreviewCommand:string Default: ghostview The default preview command, that is fed the output of the format command above. Sites with interactive postscript previewers may wish to play with this. WelcomeMailFile: pathname Default: ${ANDREWDIR}/lib/Hello This specifies the name of the file that contains a piece of mail that can be given to each new user of the system as his or her first piece of mail. A multi-media message is provided, and installed in the appropriate place, with the standard Andrew distribution. This mail is placed in a user's Mailbox or mailfile when the mail folder is created. 4. Notes on Various Platforms Check this section for notes concerning your specific platform. 4.1 Notes about Installation on a IBM RS/6000 This distribution builds for rs_aix32, rs_aix4, and subsequent versions of AIX, but not necessarily for earlier versions. If you will be using IBM's CSet++ compiler for C++ you will need to add the following to presite.h: #define IBMCSET_ENV 1 #define _IBMR2 1 4.2 Notes on HPUX This release supports only HPUX9.03 or greater. There may be problems if you have LPATH set to favor pa1.1 libraries, unset LPATH before compiling Andrew. 4.3 Notes about Displaying on an Open Windows Server Open Windows uses it's own font format. To build the appropriate fonts, you will need to compile on a machine with Open Windows installed and with OPENWINDOWS_ENV defined in your $/config/site.h file. If you won't need the normal X .bdf fonts you can then replace the contents of the $ANDREWDIR/X11fonts directory with that of the $ANDREWDIR/Xnewsfonts. If you don't wish to replace the contents of the X11fonts directory you will need to explicitly add the Open Windows versions of the Andrew fonts to your fontpath with a command in your .xinitrc like: xset +fp $ANDREWDIR/Xnewsfonts Andrew automically adds a directory to the fontpath. This directory can be named in the preferences file as the preference AndrewFontDir. For instance: *.AndrewFontDir: /usr/me/myfonts To affect all users, this line could be added to $ANDREWDIR/lib/global.prf after installation of the system. 4.4 Notes about Installation on a Sun 4 (SPARC) System The GNU binutils should NOT be in your path while building Andrew. 4.5 Notes on Sun Solaris The GNU binutils should NOT be in your path while building Andrew. Add to presite.h the line #define SOLARIS 1 4.6 Notes on Decstation Ultrix 4.2 and Ultrix 4.3 Ultrix 4.2 and 4.3 If you will be using the Dec versions of the X11 libraries you may encounter a problem with 'malloc' as a multiply defined symbol. You will need to add the following to site.mcr: XLIB = /lib/libc.a $(XLIBDIR)/lib/libX11.a RESOLVLIB= If you need to set RESOLVLIB you may need to add it to XLIB (before /lib/libc.a) as well to avoid multiply defined symbols when building runapp. The XLIB line would then be: XLIB = $(RESOLVLIB) /lib/libc.a $(XLIBDIR)/lib/libX11.a Ultrix 4.3 and AFS Release 6 of Andrew (and probably earlier releases) fails to build on Ultrix 4.3 when it is built to run in an AFS 3.2 environment. The first time the problem is seen is when linking "runapp", and the symptom is that a number of symbols for the XDR routines show up as multiply defined. These symbols are defined in both the AFS Rx library, and the Ultrix C library, and differences in cross-module symbol references make it impossible to link any program using XDR against both of these libraries at the same time. However, the XDR routines in AFS are taken directly from the Sun's RPC source kit (which they distribute freely) - there is nothing special about them. It is therefore possible to simply use the XDR routines provided in the C library instead of using AFS's versions. To do this, it is necessary to delete the XDR modules from the appropriate library (librx.a), as follows: % cd $(AFSBASEDIR)/lib % cp librx.a librx.a.orig # Save a copy of the original! % ar d librx.a xdr.o xdr_array.o xdr_float.o xdr_mem.o xdr_rec.o \ xdr_refernce.o xdr_update.o % ranlib librx.a Note that the module "xdr_rx.o" must remain in librx.a; this is the only XDR module in this library that contains AFS-specific code. Once this is done, Andrew will compile and link correctly without any "multiply defined" symbol errors. 4.7 Notes on Installation on a Linux System Please note that the console application does not correctly read /proc and is therefore not very useful. See the $/FAQ for a list of known problems. 5. Partial Rebuilds Most directories are shipped with an Imakefile, but no Makefile. The Makefile is generated from the Imakefile with $ANDREWDIR/bin/genmake, which is among the earliest installed software. At the top level the distribution contains a Makefile, an Imakefile, and something called Amakefile. The Makefile and Imakefile are identical. When `make` is applied to the Makefile, it first executes an `imake' command to convert the Amakefile into a Makefile, replacing the original Makefile. It then recursively calls 'make', utilizing the new Imakefile. a) To build the original Makefile from the Imakefile: cp Imakefile Makefile (It should also work if you give the command `xmkmf'.) b) To manually build the Makefile from the Amakefile: imake -I. -I./config -Timake.tmpl -f Amakefile Note that there is a space after -f, but not the other flags. c) To build from a subset of subdirectories, define the SUBDIRS variable. Here is an example at the top level: cd $/ make Makefiles dependInstall SUBDIRS='overhead atk' and here's another within $/atk: cd $/atk make dependInstall SUBDIRS='basics support' You can build subdirectories one at a time and then clean them out out with make Clean This will require somewhat less space in the build tree. The make target dependInstallCramped has the same effect in the top level Makefile. 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 5.1 Error Recovery If the build process fails sometime before it has completely built and installed, you can do one of several things, depending on what has caused the build to fail. The simplest but 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="eq fad table rofftext help ..." where the actual contents of the SUBDIRS entry can be determined by looking at $/atk/Imakefile. When the build for $/atk completes, examine the Imakefile for the top level and observe that the remaining SUBDIRS that need to be built are: ams atkams contrib helpindex xmkfontd and doc. So change directory to the root of the object tree ($/) and execute make dependInstall SUBDIRS="ams atkams contrib helpindex xmkfontd doc" After building the entire system you can recompile and install a subtree or directory, by moving to that directory and issuing make Install See the file FAQ for a list of common problems and the accompanying fixes. 6. Make Targets The generated Makefile-s 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). (Obsolete, was used when installation was done by linking.) 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. dependInstallCramped: Available only in the top level directory, $/. Each subdirectory is built first with dependInstall and then with Clean. This option requires less space for the build tree. However, rebuilds are considerably slower. 7. 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: ${ANDREWDIR}/bin - Runnable applications ${ANDREWDIR}/X11fonts -ATK specific fonts for X ${ANDREWDIR}/Xnewsfonts - 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 - Documentation files ${ANDREWDIR}/etc - Auxiliary files, usually not accessed directly by users 8. Setting up the Environment to Run Applications To run Andrew 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. 8.1 Printing Andrew prints by generating PostScript; the output is passed to a command which, by default, use lpr to spool print requests. The command is specified in ~/preferences as *.pscprintcommand: lpr where "lpr" can be replaced with any other command which accepts a PostScript file from stdin. You should run help preferences once you have brought up the system to see how to change your preferences. {Older versions of Andrew printed by generating troff and having it sent through di-troff and and Adobe's TransScript to generate Postscript. A document which describes this older printing model is in the source at atk/ezprint/printing.ins.} 8.2 Configuring a Help System 8.2.1 The index Help is configured by default to index (and thus, makes 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 (the following description is taken from $/atk/help/doc/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//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 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: $ANDREWDIR/doc/HELP/Maint.doc 8.2.2 The documents The documents ("help files") that describe the system will probably need to be edited at some point to correctly reflect the system you have built. 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. Copyrights for this file and the entire Andrew User Interface System: Copyright Carnegie Mellon University 1991, 1996 - All Rights Reserved Copyright IBM Corporation 1988, 1991 - All Rights Reserved Additional copyright information can be found in config/COPYRITE.bls, config/COPYRITE.att, and config/COPYRITE.img in both the source and destination areas. This product includes software developed by the University of California, Berkeley and its contributors. $Disclaimer: # Permission to use, copy, modify, and distribute this software and its # documentation for any purpose and without fee is hereby granted, provided # that the above copyright notice appear in all copies and that both that # copyright notice and this permission notice appear in supporting # documentation, and that the name of IBM not be used in advertising or # publicity pertaining to distribution of the software without specific, # written prior permission. # # THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD # TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF # MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ANY COPYRIGHT # HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL # DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, # DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE # OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION # WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. # # $