Installing Andrew7.5 Andrew User Interface System Version 7.5 (September, 1996) Andrew Consortium School of Computer Science Carnegie Mellon University 5000 Forbes Avenue Pittsburgh, PA 15213-3891 USA telephone: (412) 268-6710 fax: (412) 268-5571 Web: http://www.cs.cmu.edu/~AUIS Bugs to: info-andrew-bugs@andrew.cmu.edu Demo: finger @atk.cs.cmu.edu Orders, requests: info-andrew-request@andrew.cmu.edu Archives: ftp.andrew.cmu.edu/pub/AUIS A version of this file with Andrew formatting is installed into $ANDREWDIR/doc/INSTALL.ez. For more information on Andrew, see the accompanying README file, which is also available (in Andrew format) in $ANDREWDIR/doc/README.ez. Copyright Carnegie Mellon University 1991, 1996 - All Rights Reserved. Please see further copyrights and disclaimer at the end of this file. Andrew7.5 is a compound document architecture and application suite as described in the accompanying file, README. Installing the binary release of Andrew7.5 requires these steps, which are covered in more detail in subsequent sections. 1) Fetch the distribution from an archive server. 2) Decompress and untar the files to a directory. 3) Set environment variables. 4) Give an Andrew command: ez, launchapp, or ... AND Please see the final section of this file which gives information specific to your platform. To order the separate, instructional user manual, contact us as above or via info-andrew-request@andrew.cmu.edu. Please report bugs to info-andrew-bugs@andrew.cmu.edu. ___________________________________________ 1) Fetch the distribution from an archive server. 1a) Check that your system is supported. In many cases the Andrew7.5 distribution will operate on later versions of the supported operating system; in some cases it will also work on earlier versions. The following are supported. letter platform directory a RS/6000, AIX 3.2.5 rs_aix325 h HP720, hpux9.0 pa1.1_hpux90 l Intel x86, Linux ix86_linux p Dec PMAX, Ultrix 4.3 pmax_ultrix43 o Sparc, Solaris sparc_sunos54 s Sparc, SunOS sparc_sunos413 1b) Choose what to install. You can begin with the `w' package and fetch others later. The package naming convention is as follows: auis75{sys}{pkg}.{ext} where sys is the letter (a, h, l, p, o, or s) given in the above table, pkg is one of w - the `ez' word processor h - help program, source code editing support, and help files. (requires w) i - insets: ADEW, figure, image, ness, raster, table. (requires w) a - all other Andrew files (requires w) m - mail/bboard system (requires w & i) d - documentation and header files and ext is .tar.gz or .tgz. The supported configurations are: w basic word processing w & i wp & insets w & i & m wp & insets & mail w & h wp & help w & h & i wp & help & insets w & h & i & a everything except mail w & h & i & m wp & help & insets & mail w & h & i & m & a everything Other configurations may work to one degree or another. Use the .tar.gz files for most purposes; the .tgz files are the same, and can be used when the destination system requires names in the 8.3 format. For instance, given this name, auis75aw.tar.gz we know the file has Andrew7.5 binaries for the system type RS/6000 AIX(a) and the ez word processor / source editor (w). The file is in tar'd and gzip'd format (.tar.gz). 1c) Determine the size of the compressed package distribution file from the platform dependent section below, from the web directory listing, or via the ftp `dir' command. 1d) Choose a destination directory for the .tar.gz file. It has to have enough free space to hold the package size determined in the previous step. 1e) Fetch the file using web or ftp; see one of the two next sections. 1e-web) Using the web. Visit the web page with the binaries. This can always be found by navigating from the Andrew home page http://www.cs.cmu.edu/~AUIS As of August 1996, the binaries are accessible from http://www.cs.cmu.edu/~AUIS/bin-dist/ where the directory is as listed in the last column of the table above. Click on the package name (the one ending in .tar.gz). You will be prompted for the destination directory (the one you selected in step 1c) and then the file will be transferred. If your browser does not support file transfer, you may be forced to use ftp. 1e-ftp) Change directory to the directory chosen in step (1d) and execute the ftp program to attach to ftp.andrew.cmu.edu: ftp ftp.andrew.cmu.edu When ftp prompts you for a name, respond with the name "anonymous" (no quotes) and as a password, enter your email address. Change to the binary distribution subtree: cd pub/AUIS/bin-dist Change further to the directory for the desired platform: cd using the directory name given in the table in step 1a. Set the type to binary: bin The response will say that the type has been set to `I', which stands for "image". Fetch the desired package, replacing xx as appropriate: get auis75xx.tar.gz Some seconds or minutes later, the command will finish and tell you how long it took. The time is heavily dependent on competing network traffic. Finally, exit from ftp: quit ___________________________________________ 2) Decompress and untar the files to a directory. 2a) The Andrew7.5 binary distribution files have been compressed with `gzip'. The decompression program, gunzip, is part of the gzip package and is available from most sites that have Free Software Foundation sources. Source code for gzip is available in the file ftp://ftp.andrew.cmu.edu/pub/AUIS/util/gzip-1.2.4.tar If necessary, fetch and compile it; this should produce, among others, the program `gunzip'. Be sure your PATH environment variable includes a directory containing gunzip. 2b) Check the platform dependent section at the end of this file to determine how much space will be occupied when the package you have chosen is installed. Since you may eventually wish to install the h, i, m, a, and d packages as well as wp, you should probably have a size large enough for the sum of their sizes. Find a directory to contain the expanded Andrew distribution; this directory should be on a disk with at least as much free space as the size required. Examples below will assume that the name of the chosen directory is /usr/local/andrew. If you use this name, several steps will be a bit simpler. 2c) Change directory to the chosen directory: cd /usr/local/andrew 2d) Uncompress and untar the files: gunzip < ...path.../auis75xx.tar.gz | tar pxf - replacing ...path... and xx apropriately. Be sure to include the `p' flag among the flags to `tar'. ___________________________________________ 3) Set environment variables. If you have installed Andrew7.5 into /usr/local/andrew, this step is not necessary. You can execute Andrew7.5 applications by giving their full name or simply setting your PATH to include /usr/local/andrew/bin; for instance, /usr/local/andrew/bin/ez or PATH=/usr/local/andrew/bin:$PATH. If you have installed Andrew7.5 in some other directory, you need to have at least two variables, ANDREWDIR and PATH, defined in your shell environment. Other variables may also be necessary for your platform; see the platform dependent section below. Some parts of your system environment may also be tailored to adapt to Andrew; See section 5 below. The exact procedure for setting variables depends on what type of shell you are using, sh or csh. 3-Bourne shell (sh, bash, ksh, ...) Give these commands ANDREWDIR=/usr/local/andrew; export ANDREWDIR PATH=${ANDREWDIR}/bin:$PATH Be sure to replace "/usr/local/andrew" if you have installed Andrew somewhere else. To have these variable settings in force at all times, you can put the above commands in $HOME/.profile or whatever file is the startup script for your shell. 3-C-shell (csh, tcsh, ...) Give these commands setenv ANDREWDIR /usr/local/andrew setenv PATH ${ANDREWDIR}/bin:$PATH Be sure to replace "/usr/local/andrew" if you have installed Andrew somewhere else. To have these variable settings in force at all times, you can put the above commands in $HOME/.cshrc or whatever file is the startup script for your shell. ___________________________________________ 4) Give an Andrew command All Andrew commands are now available. For instance, to edit a file with ez, give the command ez filename other commands include help, auis, figure, raster, image, table. ___________________________________________ ___________________________________________ 5. What Gets Installed As a result of the installation process, some or all of the following directories may be created in /usr/local/andrew or whatever directory you have chosen as the $ANDREWDIR directory: ${ANDREWDIR}/bin - Runnable applications ${ANDREWDIR}/lib/atk - Dynamically loaded libraries ${ANDREWDIR}/help - Help files for users ${ANDREWDIR}/X11fonts -ATK specific fonts for X ${ANDREWDIR}/Xnewsfonts - ATK fonts for running under Open Windows (if enabled, only on SunOS 4.1.3) ${ANDREWDIR}/lib/tpls - Style templates for text and text-like objects ${ANDREWDIR}/lib/consoles - Console descriptions ${ANDREWDIR}/include/atk - Compile time include files ${ANDREWDIR}/doc - Programmer documentation files ${ANDREWDIR}/etc - Auxiliary files, usually not accessed directly by users 6. Setting up the Environment to Run Certain Andrew Applications To run Andrew you must be running X11, and have your DISPLAY environment variable set appropriately. Andrew applications support the -fg, -bg, -display and -geometry switches. In addition, most Andrew 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.). Examples of preferences files and other init files are in $ANDREWDIR/lib/samples. See the U section of the FAQ file for more hints about tailoring the system. If you want the Check Spelling menu in text to work, you will need the ispell program. Ispell must be found along the user's path. Before running AMS, you should review the options available with the AndrewSetup mechanism, described in the setup.help file ($ANDREWDIR/help/setup.help), contained in the auis75Xh.tar.gz package. 6.1 Printing Andrew prints by generating PostScript; the output is passed to a command which, by default, uses 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. To see how to change your preferences, run help preferences once you have brought up a system that includes the h package.. {Older versions of Andrew printed by generating troff and having it sent through di-troff and and Adobe's TransScript to generate Postscript. This mechanism is still operative if you have old documents and the requisite troff and psdit programs. On some systems, it may be possible to avoid these by using `lpr -n'.} 6.2 Configuring a Help System 6.2.1 The help index Help is configured by default to index (and thus, makes available) files in the following directories: /usr/local/andrew/help /usr/man 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, or if you have added or deleted files from the indexed directories, you need to rerun help's mkindex program. First, you must create an input file for mkindex describing which directories are to be indexed. For the default help directories, this file need contain only dir /usr/local/andrew/help /usr/local/andrew/help dir /usr/man /usr/man where "/usr/local/andrew" should be replaced with whatever is your value for $ANDREWDIR. Lines of the following four kinds can appear in the input to mkindex. (The description is taken from $ANDREWDIR/doc/atk/help/help-maint.doc): # 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. # 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. When the user requests help on the keyword, the named file will be displayed. (The "key" line in mkindex has the same effect as adding aliases with the help.aliases file, as described in the section Aliases in help-maint.doc; we recommend avoiding help.aliases and using the "key" option of mkindex instead.) When the input file is ready, the help index is built with the command mkindex name-of-input-file /usr/local/andrew/lib/help.index where, again, "/usr/local/andrew" should be replaced with your $ANDREWDIR value. The help.index file will be completely cleared at the beginning of the process; so it must be used for no other purpose. In particular, DO NOT try to put the index files in the same directory as the help files. 6.2.2 The help 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, if you intend for users not to be 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.3 Installing mail If you have installed the auis75Xm package to get mail, please see $ANDREWDIR/INSTALL.mail, which is installed as part of that package. Installation Notes - rs_aix325 This distribution operates on RS/6000 under AIX 3.2.5 and successor systems. (It has not been tested on AIX 4.xxx, nor on PowerPC systems. It may function on PowerPC systems running AIX 3.2.5.) Sizes (in mega bytes) of the tar file and the installed binaries are in the following table. It would be wise to have the corresponding directories somewhat larger to provide for growth. Pkg .tar.gz installed wp 3 9 help 2 5 insets 4 14 other 3 11 doc 2 6 mail 3 8 X11 Version AUIS has been linked dynamically with X11R4 as shipped with AIX 3.2.5. (In /usr/lib.) Installing elsewhere than in /usr/local/andrew In addition to setting ANDREWDIR and PATH as described in section 3 above, the variable LIBPATH must also be given a value. If there is no pre-existing value for this variable, it should be set to ${ANDREWDIR}/lib/atk:/usr/lib:/lib otherwise its value should be ${ANDREWDIR}/lib/atk:$LIBPATH Set LIBPATH after setting ANDREWDIR and use the same syntax. Be sure to include the `export' part if using a Bourne-type shell. The distribution assumes that between them the directories /lib and /usr/lib contain both libc.a and libX11.a. If not, the directories containing these libraries must be included in the LIBPATH value. Copyright Carnegie Mellon University 1991, 1996 - All Rights Reserved Additional copyright information can be found in $ANDREWDIR/config/COPYRITE. $Disclaimer: Andrew User Interface System - Binary Distribution 7.5 Permission to use, copy, modify, and distribute this software for any purpose is hereby granted, provided (a) that no fee is charged for the software, for the medium on which it is distributed, for the distribution process, or for effort involved in making the distribution; (b) that all copyright notices, this permission notice, and the following disclaimer remain in these files and appear in supporting documentation; (c) that you do not translate, reverse engineer, decompile, or disassemble the software; and (d) 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. CARNEGIE MELLON UNIVERSITY, IBM, AND THE OTHER COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY, IBM, OR ANY OTHER COPYRIGHT HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. $