The Andrew Distribution Version 6.1 (December, 1993) For more information, please contact: Andrew Consortium School of Computer Science Carnegie Mellon University 5000 Forbes Avenue Pittsburgh, PA 15213-3890 U.S.A. (412) 268-6710 Mailing list: info-andrew@andrew.cmu.edu (info-andrew-request@andrew.cmu.edu for subscriptions) Newsgroup: comp.soft-sys.andrew This product includes software developed by the University of California, Berkeley and its contributors. Copyright IBM Corporation 1988, 1991 - All Rights Reserved Copyright Carnegie Mellon University 1991, 1992 - All Rights Reserved The following copyright and permission notice apply to versions of the Andrew User Interface System distributed previously. The above notice applies to this release. Copyright IBM Corporation 1988, 1991 - All Rights Reserved Copyright Carnegie Mellon University 1991, 1992 - All Rights Reserved Permission to use, copy, modify, and distribute this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice, this permission notice, and the following disclaimer appear in supporting documentation, and that the names of IBM, Carnegie Mellon University, and other copyright holders, not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. IBM, CARNEGIE MELLON UNIVERSITY, AND OTHER CONTRIBUTORS OF THIS SOFTWARE DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ANY PARTICULAR PURPOSE. IN NO EVENT SHALL IBM, CARNEGIE MELLON UNIVERSITY , OR ANY OTHER CONTRIBUTOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA, OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE, OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 1 Installation Instructions for the Andrew Distribution This document contains instructions for the installation of the Andrew User Interface System software, namely the Andrew Toolkit (ATK), and its applications, including the Andrew Message System (AMS). 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. ***** Quick-Start Instructions for the Impatient ***** You'll need to modify two files: config/site.h and config/site.mcr. config/site.h includes your site's adjustments to allsys.h and system.h. You should specify the location of the DEFAULT_ANDREWDIR_ENV. config/site.mcr contains your site's adjustments to macros in allsys.mcr and system.mcr. You may want to change XINCDIR, XLIBDIR and XINCDIR which define the location of your X libraries and utilities. You may want to check the other options available below under section 1.2.1 for the site.mcr file and section 1.2.4 for the site.h file. Then check the "Notes on ..." sections later in this document for information possibly relevant to your particular system type, or X server. (There are notes for: MIPS,SPARC,Open Windows server, IBM RS/6000, Sun Solaris, PS/2 AIXv1.2, SCO Unix , HPUX, NeXT, SGI Iris) In the top level (directories overhead, atk, ams, ... exist), run the following command: imake -I. -I./config -Timake.tmpl -s Makefile -DTOPDIR=. This will generate the top level Makefile. Then run: make World Error reports and request for assistance should be sent to info-andrew-bugs@andrew.cmu.edu. 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,2}, PS/2 AIX1.2, Sun3{ 3.5, 4.0, 4.1}, Sun4 {4.0, 4.1}, Vax Ultrix 3.1, Vax Ultrix 4.2, Vax BSD, DEC MIPS, SCO I386, SGI IRIX 4.0, Apollo, HP, NeXT (under X11) and Macintosh II MacMach. We run it on RS/6000 AIX3.1 and AIX3.2, Sun 4 Mach, Pmax Mach, Pmax Ultrix 4.2(and 4.3, using cc but not gcc), and RT AOS. As shipped, the Andrew distribution is about 40 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 the appropriate operating system and machine dependent pieces. Because of the large size of the system, many options are provided. Definitions that you must provide are described in this section. Optional definitions are described later. Before building Andrew, you should look through the several files that configure the system, and change them as necessary so that the Andrew software will be built and installed correctly for your environment. Each file, and the modifications you might want to make to it, are explained below. Looking from the top of the extracted source tree, the files are: config/allsys.mcr config//system.mcr config/site.mcr (your site's adjustments to allsys.mcr and system.mcr) config/allsys.h config//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 "" is the machine type on which you plan to install and build Andrew. The (intended) available machine types are: Machine Type Operating System IBM RT AOS December 1988 rt_aos4 IBM RT AIX 2.2.1 rt_aix221 IBM RS/6000 AIX 3.1, 3.2 rs_aix3 IBM PS/2 M70/80 AIX 1.2 ps_aix12 Sun 3 SunOS 3.5 sun3_35 Sun 3 SunOS 4.0 sun3_4 Sun 3 SunOS 4.1 sun3_41 Sun 4 SunOS 4.0 sun4_40 Sun 4 SunOS 4.1 sun4_41 DEC Vax Ultrix 3.0 vax_3 DEC Vax BSD (4.3) vax_43 HP 300 HP UX hp300 HP 900 HP UX hp800 Macintosh II MacMach mac2_51 Apollo DomainOS apollo68k DEC MIPS Ultrix 3.0 pmax_3 DEC MIPS Ultrix 4.1 pmax_41 DEC MIPS Ultrix 4.2 pmax_ul4 DEC MIPS Ultrix 4.3 pmax_ul4 (using cc, not gcc) SGI IRIX 4.0 sgi_4d SCO SCO sco_i386 NeXT NeXt Mach 2.0 next_mach20 1.2.1 The allsys.mcr, system.mcr, and site.mcr Files config/allsys.mcr, config//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.) 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. DESTDIR may be set to other values only in the course of local Andrew-based development. For the Andrew build, this value will always be BASEDIR. But for developers of Andrew-based software who want to install their binaries, this value may be set to a location specifying a local binary tree. AFSBASEDIR [Default: /usr/andrew] AFSBASEDIR denotes the full path to files exported by an AFS (Andrew File System) installation. (AFS is a distributed file system available from Transarc Corporation. For more information, please send mail to afs-sales+@transarc.com.) It is used only if AFS_ENV is defined; otherwise, it is ignored entirely. If it is used, it is presumed that AFSBASEDIR/include/afs, AFSBASEDIR/lib/afs, and AFSBASEDIR/bin exist. Other specific requirements are listed in the discussion of AFS_ENV and AFS30_ENV in the section describing the *.h files. The default value is /usr/andrew . Override it in your site.mcr file if you need to. 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. 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. XINCDIR [Default: $(XBASEDIR)/usr/include] XLIBDIR [Default: $(XBASEDIR)/usr/lib] XBINDIR [Default: /usr/bin/X11] XBINDIR should point to the location of the X bin directory under the XBASEDIR. Do not include XBASEDIR in your definition of XBINDIR XUTILDIR [Default: /usr/bin/X11] As is the case with XBINDIR, XUTILDIR should also point to the location of the X bin directory under the XBASEDIR. Do not include XBASEDIR in your definition of XUTILDIR 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. XMKFONTDIR [Default: $(XBASEDIR)/$(XBINDIR)/mkfontdir] XFC [Default: RELEASE2_ENV implies $(XSRCDIR)/fonts/compiler/fc, FONTS_TO_PCF_ENV implies $(XBASEDIR)/$(XBINDIR)/bdftopcf, otherwise $(XBASEDIR)/$(XBINDIR)/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: $(BASEDIR}/etc/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 manuals (in ./ams/doc), the Andrew Message Delivery System Installation manual (./ams/doc/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//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//system.h that select what parts of Andrew will be built. The next section, 1.2.5, describes the options in config//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//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. This distribution also contains Metamail. See METAMAIL_ENV. 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: not defined] Metamail is an implementation of MIME, the Multipurpose Internet Mail Extensions, a proposed standard for multimedia mail on the Internet. Set MK_METAMAIL to build the version of Metamail that comes with this distribution and define METAMAIL_ENV if you are going to use it. Some AMS code takes advantage of Metamail and METAMAIL_ENV is used to communicate that metamail is installed on the system. Metamail is also distributed through other channels so, if you've already picked it up from elsewhere you would want to #define METAMAIL_ENV while not defining MK_METAMAIL. 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 site files define a CONVERTFONT macro to be /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). DOC_ENV [Default: not defined] DOC_ENV controls the installation of the documents in the top-level doc directory. You should define DOC_ENV in your site.h file if you would like to have the documents installed. 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] MK_METAMAIL [Default: defined] MK_CALC [Default: not defined] (in contrib) MK_CHAMP [Default: not defined] (in contrib) MK_ZIP [Default: not defined] (in contrib) 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 + preview + launchapp) MK_BASIC_INSETS (= eq + fad + table + layout) MK_BLD_BLKS (= apt + org + bush + chart + figure) MK_HELP (= rofftext + help) MK_TEXT_EXT (= srctext + lookz) MK_AUTHORING (= controllers + music + ness + createinset + layout) MK_AUX_UTILS (= datacat + toez + prefed ) MK_AUX_INSETS (obsolete) MK_EXAMPLES (= examples) If you only want to build part of one (or more) of these groups, a flag MK_ can be used to specify the ones you want to build; i.e.: MK_APT MK_BUSH MK_CALC (CONTRIB_ENV must also be set) MK_CHAMP (CONTRIB_ENV must also be set) MK_CHART MK_CONSOLE MK_CONTROLLERS MK_CREATEINSET MK_SRCTEXT (includes ctext) MK_DATACAT MK_EQ MK_EXAMPLES MK_EZPRINT MK_FAD MK_FIGURE MK_HELP MK_LOOKZ MK_MUSIC MK_NESS MK_ORG MK_PREFS (otherwise known as prefed) MK_PREVIEW MK_ROFFTEXT MK_TABLE MK_TOEZ MK_ZIP (CONTRIB_ENVmust also be set) The ATK Imakefile (atk/Imakefile), that uses these flags, has been fairly carefully set up so that it will build parts of the toolkit to support the parts that you ask to be built; in other words, it knows about the various inter-dependencies. Thus even if you don't have MK_AUTHORING set, it will build 'value' if you have AMS_ENV set, because it knows that the program 'Messages' uses the 'value' inset. The contrib Imakefile contrib/Imakefile uses MK_CALC, MK_CHAMP, MK_ZIP to decide whether to build those programs. It builds tm except on the SGI Iris. alink is built only on Sun Sparcs. If AMS_DELIVERY_ENV is defined the pobbconf directory will be built. (it consists of utilities for running the post office machines needded by AMDS.) If AMS_ENV is defined the eatmail program will be built. (This program incorporates mail from a normal Unix spool mail file into the AMS mailbox.) The programs rtf2, 2rtf, and scribetext are located in andrew/contrib/mit. These programs are only built if CONTRIB_ENV is defined as well as RTF_ENV (for 2rtf & rtf2) or SCRIBETEXT_ENV (for scribetext). These programs are not built by default. RTF_ENV [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. SCRIBETEXT_ENV [Default: not defined] Scribetext takes a Scribe compatible manuscript file and produces an ATK datastream file capable of being used by ATK client programs. NEOS_ENV [Default: not defined] Neos is a system for the electronic submission and grading of papers. It requires Kerberos. 1.2.5 The config/allsys.h, config//system.h, and config/site.h Files: Describing Your Environment The config/allsys.h, config//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: not defined] WARNING: As of Release 6.0 beta, this installation option has not been thoroughly tested and may not compile cleanly. 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. POSIX_ENV [Default: system dependent] You will normally not need to modify this symbol. When defined this symbol causes code mostly conformant to POSIX to be used where available. (The code is by no means completely conformant, and some old BSD-style code probably still persists.) 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.) 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 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//system.mcr and config//system.h files, and rework the config/platform.tmpl file to include your new config//system.mcr file. Other directories that need customization are: overhead/class/machdep atk/console/stats atk/console/stats/ atk/console/stats/common 1.2.7 Notes on Installation on a MIPS system (Including Decstations) The previous notes about dealing with -G 0 libraries no longer apply. MIPS has contributed a new ATK port which eliminates the complexities of the old setup. However gcc should not be used, use the mips cc. 1.2.8 Notes on Installation on a Sun 4 (SPARC) system There have been reports of various version of the Sun C compiler dumping core when optimization is used. You may find it necessary to set the CDEBUGFLAGS= in the Imakefile for the directory in which the build fails. Then Rebuild the Makefile for that directory and recompile it from scratch. As of ATK 4.10.0 (what we used to call ATK 17.0), there is support for the SunOS4.1 native dynamic loader. Unfortunately, Sun has not made dbx cognizant of any dynamically-loaded symbols. There is a patch set located on emsworth.andrew.cmu.edu that, when applied to gdb 3.5, provides a new command, "add-dlopened-files", which finds out what objects have been loaded since the last time "gdb" checked what objects have been loaded, and loads the symbols for any new ones. [These notes about GDB 4.x and SunOS 4.x are from auspex!guy@uunet.uu.net (Guy Harris).] GDB 4.x includes support for SunOS 4.x dynamically-loaded code, both shared libraries and "dlopen()"ed stuff. GDB 4.1 handles shared libraries better, in that it automatically finds them; you still have to use the "sharedlibrary" command to load up the symbol tables for stuff loaded up by "dlopen()" - "sharedlibrary", with no arguments, appears to find every shareable object that's been "dlopen()"ed since the last time it checked, and read its symbols in. There is a bug in GDB 4.1 where it doesn't set the "end of text" address in the "partial symbol table" entry for a shareable object correctly; it relocates the *beginning of text* address to put it where the object was actually loaded, but not the end of text address. One consequence of this is that you can't always (can't ever?) step into a routine in a "dlopen()"ed shareable object. The following patch appears to fix that (and has been sent to "bug-gdb", and appears in GDB 4.2): *** 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 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 site.h file. If you won't need the normal X .bdf fonts you can then replace the contents of the $ANDREWDIR/X11fonts directory with that of the $ANDREWDIR/Xnewsfonts. If you don't wish to replace the contents of the X11fonts directory you will need to explicitly add the Open Windows versions of the Andrew fonts to your fontpath with a command like: xset +fp $ANDREWDIR/Xnewsfonts in your .xinitrc. 1.2.10 Notes on Installation on a IBM RS/6000 This distribution builds for both rs_aix31 and rs_aix32. Since there are no differences needed for the various sytem files, the term rs_aix3 is used for both system types. If you are using AIX 3.1 or earlier running X.V11R3, you must use the version of imake in /usr/lpp/X11/Xamples/util/imake. Otherwise, you can use the X11R4 imake that comes with AIX 3.2. Do not build the Class pre-processor (./overhead/class/pp) with optimization-- it tickles a bug that causes later classes to fail. If you are installing Andrew into a directory other than the one it is being built into (ie. your destination directory isn't $(BASEDIR)), you MUST set the parameter SHARED_LIB_PATH in your site.mcr file to match the destination directory. Otherwise the RS/6000 dynamic library system will not be able to find important modules at run time. The file config/rs_aix31/system.mcr sets this by default: SHARED_LIB_PATH = -L${BASEDIR}/lib for example, to set your destination directory to /usr/andrew you would add the line: SHARED_LIB_PATH = -L/usr/andrew/lib to your site.mcr file. 1.2.11 Notes on Installation on PS/2 AIXv1.2 The PS/2 C compiler will die with optimization in these directories: ./overhead/parsec ./atk/raster/cmd ./atk/eq Compile these directories with "CDEBUGFLAGS=". 1.2.12 Notes on Installation on SCO Unix First, in order to compile AUIS on standard SCO UNIX, you must use GCC. The C compiler has a limit on identifier lengths, and it will be entirely too painful to get around it. Second, you will want the following in your site.h and site.mcr files: site.h: #define MEMMOVE_IS_BROKEN 1 -> this replaces memmove() with a correctly working bcopy() #define POSIX_ENV 1 -> If you're using the Elan Eroff package, then try these: #define print_FORMATCOMMAND "cat /tmp/%s.n |" #define print_PRINTCOMMAND "/usr/sco/bin/netroff -Le -b %s" #define print_PSCPRINTCOMMAND "lpr -dps" #define EROFF_ENV 1 site.mcr: CC = gcc COMPILERLIBS = /usr/local/lib/gcc-gnulib Other patches and a README detailing fixes necessary to build Andrew for SCO 1.2.13 Notes on HPUX 1. This release supports only HPUX8.0 or greater. If you have a need to build Andrew for an earlier version of HPUX, please contact the Andrew Consortium for details on how to do so. 2. Because it is not possible to determine what version of HPUX you have on the machine, see the file andrew/config/hpx.series for hacks to enable compilation on HP Series 9000 machines. 3. There are several problems with ld on HPUX8.0. ATK dynamic objects are shared libraries. The HPUX 8.05 link editor has a problem linking either 1) normal archive libraries, or 2) shared libraries, into other shared libraries. So, for instance, if you are working with a dynamic object, foo.{c,ch}, and it makes use of some math functions, you would normally use this imake rule to create it: DynamicObject( foo, foo.o,,-lm) For HPUX8.0 do not include the math library in this rule. The main executable, runapp, will contain the math library. There has been defined a make macro, MATHLIB, that is set appropriately and should be used thusly: DynamicObject( foo, foo.o,,${MATHLIB}) If any of your Andrew-related software is to be expected to compile on HPUX8.0 platforms, please use MATHLIB until there is an update to the system. As of this writing, HPUX 8.07 apparently fixes this problems but has not been confirmed. 1.2.14 Notes on NeXT The cpp supplied with the 2.0 release of the NeXT OS is not suitable for use in imake. Recent versions include a version of cpp and this cpp is known to work. 1.2.15 Notes on SGI Iris Console has not been ported to this system. To avoid attempting to build it, modify the following files as indicated: site.h: (add the following lines) #undef MK_BASIC_UTILS #define MK_EZPRINT 1 #define MK_PREVIEW 1 site.mcr: (add the following line) LAUNCHAPP = launchapp 1.2.16 Notes on Sun Solaris The C preprocessor does not define SOLARIS. As such, you must add the -DSOLARIS flag to the initial imake that generates the top level Makefile. Your initial command will be: imake -I. -I./config -Timake.tmpl -s Makefile -DSOLARIS -DTOPDIR=. 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.V11R6 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 off) 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 one of several things, depending on what has caused the build to fail. The simplest and most time consuming is to fix the problem and then do a "make dependInstall" from the root of the Andrew tree. A faster approach is to continue the build process manually. For example, assume the make died in atk/eq. After correcting the problem, you could move into the atk directory and do a make dependInstall SUBDIRS="fad table rofftext help ..." where the actual contents of the SUBDIRS entry can be determined by looking at atk/Imakefile. When the build for atk completes, examine the Imakefile for the top level and observe that the remaining SUBDIRS that need to be built are: ams atkams contrib helpindex xmkfontd and doc. So change directory to the root of the object tree and execute 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. 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 AUIS insets. This document contains a brief description of the contents of the Andrew Distribution. 2.2.1 Overhead genmake - a script for generating Makefiles from Andrew style Imakefiles sys - a program used for distinguishing between different system (hardware/os) types util - lots of utility functions. Includes the White Pages readers addalias - adds aliases for help probes errors - a package for handling some low-level error reports in a uniform way index - utility to map class names to file names malloc - the Andrew version of malloc class - an object-oriented C language preprocessor used by ATK rxp - a regular-expression package used in ELI eli - the ``embedded lisp interpreter'' used by AMS image - various popular public domain image-compression libraries conv - several conversion programs for sites which have used earlier versions of the Andrew distribution. fonts - fonts used by ATK programs xicons - a small collection of icons for use under X window managers cmenu - the ATK stack-of-cards X11 menu package mail - library of AMS functions wputil - programs and data to initialize and build a White Pages wpi - allows mail-basd updates to White Pages entries 2.2.2 ATK Basics (or Core) basics - underlying ATK core support - underlying ATK core supportviews- underlying ATK core text - facilities for styled text and text formatting utils - support for dialog boxes frame - support for file commands and buffers textaux - more support for text operations, gnu-emacs compatibility and ISO Latin-1 input atkvers - version numbering scheme ez - a multi-media editor extensions - many user support packages, include gnu-search and meta-x typescript - a flexible csh window (not TERMCAP) apps - the core application executable textobjects - directory editor and a list view hyplink - a hypertext-like link inset value - a set of widgets for use with adew adew - a direct manipulation user interface builder raster - a raster (bitmap) editor Basic Utilities console - a system monitoring program ezprint - allows printing of ATK format documents image - a color raster viewer preview - a ditroff previewer rofftext - utility for viewing troff files Basic Insets eq - an equation editor fad - a simple frame animator table - a simple spreadsheet Building Blocks apt - basic components org - an organizational chart editor bush - a directory tree/file browser figure - a drawing editor chart - a chart/graph program (line graphs, pie charts, histograms etc.) calc - a simple calculator prefed - a preferences editor Help (program) help - a user interface for help files and man pages Text Extensions srctext - a text formatting package, including support for Assembly, C, Modula3 and other languages (this package is not an active interpreter - only a formatter) spell - a spell checker. See note below. Authoring Systems ness - an embedded string manipulation authoring system syntax - a new set of tools has been introduced for token analysis and parsing. syntax/bison - a modified version of the Bison parser from the FSF syntax/parse - a parser object that uses tables syntax/lexan - a superclass for lexical analyzers syntax/tlex - a subclass of lexan which lexically analyzes input in the form of an ATK text object. syntax/sym - a symbol table package 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 layout - facility for designing screen layouts controllers - examples of adew-generated code createinset - a program to create an example inset with the name customized lookz - a style editor Example Programs examples - illustrates how to write an inset and application launchapp - demo application using in the Remote Andrew Demo service 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 atkbook - examples from N. Borenstein's book on the Andrew Toolkit bdffont - a BDF font viewing and editting inset calc - a calculator program champ - a calendar program demos - an AUIS demo eatmail - a program which transfers mail from /usr/spool/mail/{uid} into separate files in {uid}'s Mailbox directory gestures - a gesture-based text view mit/annot - a note and a postscript inset mit/neos - Networked Educational On-line System mit/scribetext - a scribe text formatter mit/thesis - a thesis-writing package mit/util - header/footer object for text, a printer option dialog box, ez2ps parsec - a C language parser plus a procedure to clean up YACC output snap2 - an RPC package used by the Andrew Message System srctext/ltext - a LISP text editing package srctext/mtext - a MODULA2 text editing package srctext/ptext - a PASCAL text editing package srctext/m3text - a MODULA3 text editing package time - analog and digital clocks, time-of-day and writestamp (useful in documents) tm - an alternative to typescript zip - an hierarchical drawing editor Many of these objects have proven very useful, and are a part of our default environment at CMU. We welcome your contributions. 2.2.6 Rdemo This directory tree contains the sources for the Remote Andrew Demo (rdemo for short). Rdemo is an Internet network service provided by a few nodes at the Andrew Consortium. It allows users anywhere on the Internet to interactively experiment with Andrew software. We do not expect that people will want to build rdemo and provide the network service themselves. We've included the sources because we expect that some people may wish to emulate this service and create their own remote demos. The sources are included primarily for the edification of programmers who wish to do this (although there's nothing stopping you from building the rdemo suite if you so desire). See the README in the andrew/rdemo directory for more information. 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 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}/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 - 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 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: 41M Total Objects: Dec Mips: 125M Sun4: 170M RS/6000: 222M 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//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: Information Requests Andrew Consortium School of Computer Science 242 BOM-D Carnegie-Mellon University Pittsburgh, PA 15213 U.S.A. (412) 268-6700 FAX: (412) 682-6938 7 How to Get More Information about Andrew There are two(*) mailing lists read by the developers and others interested in the Andrew User Interface System. The first is a bug report list moderated by members of the Andrew Consortium. 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.