INSTALLATION GUIDE FOR: ALLEGRO CL 4.3, ALLEGRO COMMON WINDOWS 2.1, ALLEGRO COMPOSER 2.0, CLIM 2.1 ON VARIOUS PLATFORMS. This document explains how to install Allegro CL 4.3, Allegro Common Windows 2.1, Allegro Composer 2.0, and CLIM 2.1 on all released platforms, including SPARCs running either Solaris 1.x or 2.x, HP's running HP/UX, IBM RS/6000's running AIX, Silicon Graphics workstations running IRIX, and DEC Alpha machines running Digital Unix 3.2 Section 3 Pre-installation and machine-specific notes provides information on operating system versions, etc. Other machine-specific information will be clearly labelled elsewhere in this document. This document is required when the products are installed and should be kept handy in case re-installation is necessary. Re-installation is required for most patches (i.e. bug fixes). 1. Introduction 2 2. Installation overview 2 3. Pre-installation and machine-specific notes 2 3.1. Hewlett-Packard workstations: machine-specific information 5 3.2. IBM RS/6000: machine-specific information 7 3.3. Silicon Graphics Iris: machine-specific information 9 3.4. Sun/Sparc running Solaris 1.x: machine-specific information 11 3.5. Sun/Sparc running Solaris 2.x: machine-specific information 13 3.6. DEC Alphas running Digital Unix 3.2: machine-specific information 15 4. Installation 16 4.1. Step 1: Copying the Allegro CL distribution from the CD 16 4.2. Run build/install_lisp to build customized images 19 4.3. Install Xemacs by running install_emacs 25 4.4. Provide information to users and clean up 26 4.5. Copy other files from the CD (optional) 26 5. Other installation options 27 6. Additional information for certain platforms 30 6.1. Including foreign code in the Allegro CL image: IBM RS/6000 only 30 6.2. Installing from a 4 mm tape (HP only) 33 7. Troubleshooting 34 8. How to contact us 36 1 Introduction This document describes standard installation of Allegro CL and related products (in sections 4 and 5 below). Section 19.4 The install_lisp program and building a Lisp image of the Allegro CL User Guide describes how to create anything but the standard installation. Please refer to that document if you wish to build an image with parameters different from those used in the procedure described here. Section 7 Troubleshooting below describes problems that may occur during installation and tells how to overcome them. At the very end of this document is the section How to contact us. It gives the e-mail address and phone numbers where you can get help if you have trouble installing our products. 2 Installation overview Allegro CL and related software is distributed on a CD. Each CD contains complete distributions for several platforms. The distributions are encoded and can only be read with a key provided by Franz Inc. The key (or keys, if you are receiving Allegro CL for more than one platform) should be written on the CD jewel case. The CD also contains various GNU products, a free (but limited) version of Allegro CL 3.0 for Windows, and some other material. None of those things are encoded. There are two steps to the installation procedure: 1. Copy the distribution from the CD to an empty directory. 2. Build an image. Step 2 can be avoided by using the prebuilt binary supplied with the distribution. You may wish to install Xemacs as well (there is a prebuilt Xemacs binary as well as a complete source distribution). Software is now distributed on a CD If you are unable to read a CD, please contact Franz Inc. for assistance. Information on contacting Franz Inc. can be found at the end of this document. This document is for all platforms This is the single Installation Guide for Allegro CL 4.3. Instructions are provided for all supported platforms. The subsections at the end of section 3 below provide important machine-specific information. Please read the subsection that applies to the platform on which you are installing. In some cases elsewhere, instructions or information may apply to only one (or several but not all) platforms. Such information or instructions are labelled with the platforms to which they apply. 3 Pre-installation and machine-specific notes Your system has to be set up appropriately in order to install Allegro CL and related products. Please look at the headings in this section and read the information under those that apply to you. Then look at the subsection following that applies to the platform on which you are installing. Copying the distribution from the CD A distribution is copied from the appropriate CD directory (named by the platform -- ibm, dec, etc.) with the copydist program in the directory. If you are licensed for more that one platform, you should copy the distributions from each directory for which you are licensed. Only one version of CLIM available Allegro CL 4.3 only supports CLIM 2.1 with Motif look-and-feel. Neither CLIM 1.1 nor CLIM 2.1 with OpenLook look-and-feel are longer supported. Xemacs 19.13 is included with the distribution A complete pre-built version of Xemacs 19.13 is included with the Allegro CL distribution. You are advised to use this version, or GNU Emacs version 19.30, in order to use Allegro Composer. Note that version 2.0.19 of the Franz Inc. Emacs-Lisp interface has not been tested on earlier versions of Xemacs or GNU Emacs. A note about Xemacs and GNU utility sources The sources for the various GNU utilities provided with the distribution are included on the CD. The sources for Xemacs and GNU Emacs 19.30 are also provided with the distribution. The sources for gcc (Sparc/Solaris 2.x distribution only) and gzip (gzip is the GNU compression/uncompression program used to uncompress files on the dis- tribution CD) are in the gnu_src directory on the distribution CD. Note that it is not necessary to have access to sources to install and run Xemacs. We expect that the typical user will not read the gnu_src directory from the distribution CD. Space requirements The amount of disk space needed to install Allegro CL depends on the platform and the product mix. The requirements for each platform are given in the platform-specific subsections that follow this section. The most free space required with any platform and product mix is 140 Megabytes (space for Allegro CL and Xemacs). If you have that much free space, you need not worry further, as long as you are using the default installation parameters. The build/custom.cl file This file is read into Lisp during the installation process. You can add forms to this file in order to customize details of the Lisp image that is produced. Typical things to add include setting global variables (note: see the description of tpl:setq-default in the Allegro CL User Guide); forms that require or load files, function definitions, etc. Each user can also modify the image he runs (at run time) with a .clinit.cl file (described in chapter 2 of the Allegro CL User Guide). It is not necessary to add anything to build/custom.cl but in order to make use of it, you must build an image with build/install_lisp. The pre-built binaries never refer to custom.cl. Patches for Allegro CL and related products You may want to include patches for Allegro CL, Allegro Common Windows, Allegro Composer, and CLIM in the image when it is installed. Patches are files that fix bugs or (more rarely) provide enhancements between releases of Allegro CL and related products. You receive patches from Franz Inc. Patch files must be put in the proper location before installation. Most patches cannot be loaded into Lisp after installation is complete. The following table shows the directory where patches for each product should be placed. All are (as indicated) subdirectories of the home/ directory copied from the distribution CD. See section 1.7 Patches of the Allegro CL User Guide for more information on patches. Note that the patch directory for Allegro Composer is home/update-composr (with no `e'). Product Patch Directory Allegro CL home/update/ Allegro Common Windows home/update-xcw/ Allegro Composer home/update-composr/ CLIM 2 home/update-clim2/ Patch directories for Allegro CL and related products Machine-specific information The following subsections each give information specific to a particular platform. Please read the subsection that applies to the platform on which you are installing. The subsections are: 3.1 Hewlett-Packard workstations: machine-specific information 3.2 IBM RS/6000: machine-specific information 3.3 Silicon Graphics Iris: machine-specific information 3.4 Sun/Sparc running Solaris 1.x: machine-specific information 3.5 Sun/Sparc running Solaris 2.x: machine-specific information 3.6 DEC Alpha running Digital Unix 3.2: machine-specific information 3.1 Hewlett-Packard workstations: machine-specific information Cannot read the distribution CD on some HP CD drives At the time this document was written, HP-supplied CD drives on certain versions of the HP-UX operating system apparently cannot read CD's in Rockridge format. Unfortunately, the Allegro CL distribution must be read in Rockridge format. If you received Allegro CL for the HP, your choices are: · Use a CD drive that does support Rockridge format on another type of machine on your network. For instance, if you have a Sun/Sparc with a CD drive on the network with your HP machine, mount the CD drive on the Sun with Rockridge format, load the CD and read it from the HP machine using the copydist program described in section 4.1 below. (The copydist binary in the hp/ directory is an HP binary, and so must be run from the HP machine.) · Receive the distribution on a 4 mm tape. See section 6.2 below for special instructions if you are installing from a tape rather than from a CD. In some cases, a tape may be sent along with the distribution. If you did not receive a tape but need one, please contact Franz Inc. (see the information on the last page of this document). You must be running HP-UX 9.05 or later Allegro CL 4.3 is not supported on versions of HP-UX 9.x earlier than 9.05. Please upgrade to that release of HP-UX if you have not already done so. If you have problems running under a later version of HP-UX, please contact us for assistance. Information on contacting us can be found at the end of this document. No shared libraries can be used with Allegro CL 4.3. HP-UX 10.0: Must use prebuilt CLIM image (or build on 9.05) There are no static equivalents of the necessary libraries in HP-UX 10.0 (as there are in 9.05), it is not possible to build a CLIM image under HP-UX 10.0. The pre-built CLIM image (included with the distribution) should work, as should any image built under HP-UX 9.05. /usr/lib/libBSD.a must be installed To install or use Allegro CL, you must have /usr/lib/libBSD.a installed on your machine. Please contact your HP representative for assistance if this library is not present on your machine. Developers Toolkit fileset required for development in CLIM 2 The Developers Toolkit fileset must be installed in order to develop programs in CLIM 2. Please contact your HP representative if you need assistance obtaining the Developers Toolkit fileset. Space required In our new installation scheme, users copy data from the CD to a single directory and all the installation work goes on in that directory (and in one of /tmp or /usr/tmp). Therefore, that directory must have sufficient space for copying the build/ and home/ directories off the CD and building the software. Determining sizes is complicated by several factors, including the following: · Choices made during installation (such as the size of newspace and oldspace or the inclusion of additional software) may increase the size requirement. The figures below assume default choices. · Pre-defined functionality can be stored in a .lso file (argument pure=shared-library which is the default), or in the heap or text space (pure=heap or pure=text). Storing in the heap or in text space requires more space. The figures below assume pure=shared-library. (The pure= argument is described in detail in chapter 19 of the Allegro CL User Guide.) The following table shows the space requirement to copy the directories and install the pre-built image. We do not give specific information on copying the directories (but not the pre-built image) and installing a specialized image with install_lisp, since the space needed depends on the arguments to install_lisp, but the figures given are a good estimate unless the specifialized image has unusual characteristics. The installation will fail if you run out of space. If that happens, increase the space available and try again. Product mix Space required Allegro CL only 47 Mbytes Allegro CL and Allegro Composer 56 Mbytes Allegro CL and CLIM 2 74 Mbytes Allegro CL, Allegro Composer, and CLIM 2 63 Mbytes Those sizes do not include space required for Xemacs, which requires 50 Mbytes. 3.2 IBM RS/6000: machine-specific information A kernel extension for AIX is provided with the distribution This extension improves foreign loading. It does not otherwise affect AIX or your environment. The code and instructions for installing it are in the kernel_extension directory on the distribution CD. See step 2.5 in section 4 or section 5 for more information. You must be running AIX 3.2.5 or 4.1 Allegro CL 4.3 will not run under versions of AIX other than 3.2.5 and 4.1. Please upgrade to one of these releases of AIX if you have not already done so. Special steps to include foreign (C or FORTRAN) code with the image See section 5.3 below for information if you want to include foreign code in the image when it is built. Simply listing .o files on the install_lisp command line (which works with other platforms) does not work with the RS/6000. Necessary IBM-supplied software and setup · To build the Lisp image on the RS/6000, certain (optional) IBM-supplied modules must be available. To build a vanilla Lisp image, you must have xlccmp.obj, all the bos.ext1 modules, and all the bosadt modules. To use the Emacs-Lisp interface, you must have in addition the bosnet.tcpip.obj and the bosnet.nfs.obj modules. To use any of CLX, Allegro Common Windows, Allegro Composer, and Allegro CLIM 2.1, one must have in addition all of the X11 modules. You can examine the modules available on your machine with the lslpp system command. Thus the following command will display the modules available: % lslpp -h | more · Lisp images can be quite large. The system parameters on the RS/6000 specify a maximum file size per user. That maximum must be large enough for the images. We recommend setting the limit so files as large as at least 20 Megabytes are permitted. A larger value may be necessary for some applications. The maximum must be set before Lisp is installed or the installation process may fail. The maximum can be set using the SMIT system utility. Choose Security and Users from the first menu, Users from the next, and Change/Show characteristics of a user from the next. Enter the name of the user and find Max File Size and set it appropriately. (Warning: we are describing IBM system software over which we have no control. These instructions are correct as of the date of this document but IBM may have made changes since that time. Please consult IBM documentation on SMIT for complete and up-to-date information.) · The amount of swap space specified in the default configuration of your workstation may be inadequate to run Lisp. We recommend a minimum of 30 Megabytes of swap -- more if more than one user will be using Lisp or if your application is very large. Lisp images are typically 5 to 17 Megabytes. Allegro Common Windows, Allegro Composer, and CLIM 2.1 increase the space required (an image built with all products using default settings is 17 Megabytes). You may need to reconfigure your machine to increase swap space. Please refer to your system administration manuals for details on reconfiguring you machine. Space required In our new installation scheme, users copy data from the CD to a single directory and all the installation work goes on in that directory (and in one of /tmp or /usr/tmp). Therefore, that directory must have sufficient space for copying the build/ and home/ directories off the CD and building the software. Determining sizes is complicated by several factors, including the following: · Choices made during installation (such as the size of newspace and oldspace or the inclusion of additional software) may increase the size requirement. The figures below assume default choices for sizes and no additional software. · Pre-defined functionality can be stored in a .lso file (argument pure=shared-library, which is the default), or in the heap or text space (pure=heap or pure=text). Storing in the heap or in text space requires more space. The figures below assume pure=shared-library. (The pure= argument is described in detail in chapter 19 of the Allegro CL User Guide.) The following table shows the space requirement to copy the directories and install the pre-built image. We do not give specific information on copying the directories (but not the pre-built image) and installing a specialized image with install_lisp, since the space needed depends on the arguments to install_lisp, but the figures given are a good estimate unless the specifialized image has unusual characteristics. The installation will fail if you run out of space. If that happens, increase the space available and try again. Product mix Space required Allegro CL only 40 Mbytes Allegro CL and Allegro Composer 59 Mbytes Allegro CL and CLIM 2 92 Mbytes Allegro CL, Allegro Composer, and CLIM 2 74 Mbytes Those sizes do not include space required for Xemacs, which requires 50 Mbytes, or pre-built Allegro CL binaries. 3.3 Silicon Graphics Iris: machine-specific information Operating System version You must be running IRIX 5.3 or later. If you are running an earlier version of IRIX, please upgrade. If you are running a later version and experience problems, please contact us for assistance. Information on contacting us can be found at the end of this document. You must have the right processor chip This version of Allegro CL will work on all machines with · an R3000 processor chip · an R4xxx processor chip where at least one `x' is not 0 -- e.g. R4600 · an R4000 Rev. 3.0 or later processor chip Allegro CL will not work on machines with Rev 2.x (or 1.x if it exists) R4000 processor chips. The hinv(1) command can be used to determine the chip type and rev number. Space required In our new installation scheme, users copy data from the CD to a single directory and all the installation work goes on in that directory (and in one of /tmp or /usr/tmp). Therefore, that directory must have sufficient space for copying the build/ and home/ directories off the CD and building the software. Determining sizes is complicated by several factors, including the following: · Choices made during installation (such as the size of newspace and oldspace or the inclusion of additional software) may increase the size requirement. The figures below assume default choices for sizes and no additional software. · Pre-defined functionality can be stored in a .lso file (argument pure=shared-library, which is the default), or in the heap or text space (pure=heap or pure=text). Storing in the heap or in text space requires more space. The figures below assume pure=shared-library. (The pure= argument is described in detail in chapter 19 of the Allegro CL User Guide.) The following table shows the space requirement to copy the directories and install the pre-built image. We do not give specific information on copying the directories (but not the pre-built image) and installing a specialized image with install_lisp, since the space needed depends on the arguments to install_lisp, but the figures given are a good estimate unless the specifialized image has unusual characteristics. The installation will fail if you run out of space. If that happens, increase the space available and try again. Product mix Space required Allegro CL only 38 Mbytes Allegro CL and Allegro Composer 55 Mbytes Allegro CL and CLIM 2 82 Mbytes Allegro CL, Allegro Composer, and CLIM 2 65 Mbytes Those sizes do not include space required for Xemacs, which requires 50 Mbytes, or pre-built Allegro CL binaries. A note about C compilers We assume that · SUNWhea Header Files · SUNWbtool CCS tools bundled with SunOS · SUNWarc Archive Libraries · SUNWtoo Programming Tools If these tools are not installed, the installation will inform you (and not complete). Also, the Sun utility pkginfo, typically in /usr/bin/, can be used to list installed packages. Please contact your Sun representative for information on obtaining these tools if you do not already have them. 2 Users running Solaris 2.2 or later (but not Solaris 2.1) In addition to the packages in item 1 above, the following SunOS package must be installed (installation of Allegro CL will fail if this product is not available): · SUNWsprot SPARCompilers Bundled tools 3 CLIM 2.1 users only (1) In addition to the packages in item 1 (and perhaps 2) above, the following SunOS package must be installed (installation of Allegro CL will fail if this product is not available): · SUNWmfrun Motif Run Time Kit (2) /usr/dt/lib must be on the LD_LIBRARY_PATH of the user installing a CLIM image (and must be on the LD_LIBRARY_PATH of any user running CLIM -- see the Release Notes). (3) In the 4.3 (and subsequent) releases, CLIM 2.1 runs with a Motif look-and-feel only. The OpenLook look-and-feel is no longer supported. 4 Users running Solaris 2.1 (but not Solaris 2.2 or later) There is a known problem with Solaris 2.1 that causes a machine crash under certain circumstances when trying to install Allegro CL over the network. The installation program tests for these conditions and will not proceed if it finds they hold. However, we strongly recommend (but do not at this time require) that users upgrade to Solaris 2.2 if at all possible. A note about C compilers for users running Solaris 2.x In the Solaris 2.x version of Allegro CL, C or Fortran code that you want to load into Lisp must be compiled with a compiler capable of producing position-independent code. The standard Sun C compiler produces position-independent code, but you may not have it installed (since it is no longer bundled with the Sun system). The GNU C compiler, gcc, is included on the Allegro CL distribution tape. It produces position-independent code and can be used to produce files suitable for loading into a Lisp image. See section 5.2 Installing gcc below for information on installing gcc on your system. We do not include a FORTRAN compiler. If you purchase one, please be sure it can produce position independent code. We strongly recommend installing gcc before installing Allegro CL if you do not have a PIC C compiler. See section 6.1 for instructions for installing gcc. Installation of Allegro CL may or may not require a C compiler (it depends on the mix of products ordered and on the command line options but the exact formula is too complicated to easily describe). If a C compiler is available, the installation will work in all cases (more precisely, it won't fail because there is no C compiler) but if no C compiler is available, the installation may fail because the product mix or the selected options make the C compiler necessary. 3.6 DEC Alphas running Digital Unix 3.2: machine-specific information This version has only been tested on Digital Unix (formerly DEC/OSF-1) version 3.2. Do not use an earlier version of Digital Unix. If you have a later version, please contact Franz Inc. if you experience difficulties. Space required In our new installation scheme, users copy data from the CD to a single directory and all the installation work goes on in that directory (and in one of /tmp or /usr/tmp). Therefore, that directory must have sufficient space for copying the build/ and home/ directories off the CD and building the software. Determining sizes is complicated by several factors, including the following: · Choices made during installation (such as the size of newspace and oldspace or the inclusion of additional software) may increase the size requirement. The figures below assume default choices for sizes and no additional software. · Pre-defined functionality can be stored in a .lso file (argument pure=shared-library, which is the default), or in the heap or text space (pure=heap or pure=text). Storing in the heap or in text space requires more space. The figures below assume pure=shared-library. (The pure= argument is described in detail in chapter 19 of the Allegro CL User Guide.) The following table shows the space requirement to copy the directories and install the pre-built image. We do not give specific information on copying the directories (but not the pre-built image) and installing a specialized image with install_lisp, since the space needed depends on the arguments to install_lisp, but the figures given are a good estimate unless the specifialized image has unusual characteristics. The installation will fail if you run out of space. If that happens, increase the space available and try again. Product mix Space required Allegro CL only 36 Mbytes Allegro CL and Allegro Composer 52 Mbytes Allegro CL and CLIM 2 77 Mbytes Allegro CL, Allegro Composer, and CLIM 2 61 Mbytes Those sizes do not include space required for Xemacs, which requires 50 Mbytes, or pre-built Allegro CL binaries. 4 Installation Here are the steps to installation: 1. Copy the files from the CD. The files include the Lisp home/ directory (needed to run Lisp), the build/ directory (needed to build images) and, optionally, a prebuilt image. This step is described in section 4.1. 2. Install the Lisp image to your specifications. This step is described in section 4.2. 3. Install Xemacs. This step is described in section 4.3. 4. Inform users and clean up. This step is described in section 4.4. 5. Copy other files from the CD (optional). This step is described in section 4.5. 4.1 Step 1: Copying the Allegro CL distribution from the CD It is not possible to install Allegro CL or to run it directly from the CD. The files necessary to install and run Allegro CL are encrypted on the CD. The program that copies the files from the CD decrypts them as they are copied. The CD contains various distributions, and you may only be licensed for one or several of them. The outside of the CD jewel case should show the licensed products. There should be a key (or serial number) for each platform. This key must be entered (when asked for, see below) to the program which copies (and decrypts) the files for that platform. Step 1.1: Choose the directory where Lisp will be installed The directory must not exist (it will be created by the data copying program) but its parent must exist. The recommended name is /usr/acl4.3/. If you use that, since /usr/ exists, it is necessary only to insure there is no acl4.3/ subdirectory of /usr/. You may decide on any directory name you like, of course. In the examples in this Installation Guide, we will use /usr/acl4.3/. Replace that where applicable with the directory you chose, if it is different. Step 1.2: Mount the CD drive and insert the CD In order to read the CD successfully, the drive should use the Rockridge Format. All Allegro CL files should copy correctly even if the drive is mounted with some format other than Rockridge, but the Emacs files may not copy correctly. Please refer to your hardware documentation or contact your hardware representative for information on how to mount a CD in Rockridge format. We assume the mount point (the name of the directory that accesses the CD) is /cdrom except on Sun/Solaris 2.x, where it is /cdrom/cdrom0. The mount point may differ on your machine. HP installers: certain versions of the HP-UX operating system (9.05 and 10.0 to our knowledge and perhaps others) do not permit mounting the associated HP CD drive in Rockrdige format. The CD must be read in Rockridge format. If you cannot mount your HP CD drive so that it reads in Rockridge format and you cannot use a CD mounted on a different machine on the network, you will need to recveive the distribution on a 4 mm tape. Please contact Franz Inc. for assistance (see the last page of this document for information on contacting Franz Inc.) If you have a tape, go to section 6.2 in this document for instructions on reading the tape. Step 1.3: Copy data from the CD The CD contains platform-specific directories containing Allegro CL (and related products) for the specific platform. The following table associates directories with platforms. You must use the copydist program in the platform-specific directory to copy the necessary files for that platform. The key (or serial number) needed for copydist to work should be written on the outside of the CD jewel case. Platform Directory DEC Alpha dec HP hp IBM RS/6000 ibm Silicon Graphics Iris sgi Sun Sparcs running Solaris 1.x sunos4 Sun Sparcs running Solaris 2.x sunos5 Not every directory appears on each CD. If the CD you have does not contain the directory for a licensed platform, please contact Franz Inc. for assistance. (See the last page of this document for information on contacting Franz Inc.) Change into the directory for the platform you wish to install. We will use Sun Sparc running Solaris 2.x in our example. The same procedure is used for every other platform except the mount point may be different (e.g. /cdrom rather than /cdrom/cdrom0). % cd /cdrom/cdrom0/sunos5 Run the copydist program in that directory. copydist is an interactive program. The following annotated transcript shows the questions and responses. Note that there is a pre-built binary (which contains all licensed products) which you may wish to install even if you want to build specialized images as well. The indented comments and expla- nations do not appear in the transcript you will see. % ./copydist In the next question you are asked for the licensed product mix. You should answer with the mix you are licensed for (not necessarily what you may wish to install at this particular moment). The serial number asked for below encodes the product mix, so the information is in fact entered twice. By (in effect) asking the question twice, we can be sure that what you think you are licensed for and what Franz Inc. thinks you are licensed for are the same. Please select your licensed product: 1) Allegro CL only 2) Allegro CL + Allegro Composer 3) Allegro CL + Allegro Composer + CLIM 2 4) Allegro CL + CLIM 2 5) International Allegro CL 6) International Allegro CL + CLIM 2 7) Allegro Runtime Enter [1, 2, 3, 4, 5, 6, 7, or -1 to exit]: 3 You have selected 3) Allegro CL + Allegro Composer + CLIM 2. Is that correct [yn]? y You will now be asked if you would like to install pre-built binaries for your chosen product. If you answer "y" (for "yes"), then a pre-built copy of the product will be included under the bin/ subdirectory of the distribution directory. You will be asked to specify the distribution directory later by this copydist procedure. Typically, the prebuilt product name will be named bin/pb_NAME where NAME is the default name for the product. You will still be able to build and configure different instances of the product regardless of your choice to include pre-built binaries. The prebuilt binary includes all licensed products for the platform where the software is being installed. Would you like pre-built binaries installed [yn]? y The serial number, also called the key, encodes the licensed product mix and other information. It should be written on the outside of the CD jewel case next the platform name. It is a string of letters and/or numbers (in our example, it is a string of x's but you should enter the number on the CD jewel case.). Case of the letters is important (entering `A' is not the same as entering `a'). The product mix encoded in the serial number must match the product mix specified in answer to the first question or copydist will fail with an error. Please contact Franz Inc. if you have any trouble getting copydist to work with the serial number supplied. See the end of this document for information on contacting Franz Inc. Please enter serial number: xxxxxxxxxxx You will now be asked for the directory pathname where installation materials are to be placed. The default installation procedures (which you can override) use this pathname as the root for the final installation. If you plan to use the default installation procedure and you are licensed to use this product over a network, you should enter the common pathname that will be used by all networked machines using this product. For example, if you are installing on machine vapor, in /usr/acl4.3, and other machines on the network access that directory with /net/vapor/usr/acl4.3, then enter /net/vapor/usr/acl4.3, as shown here. Note that the directory should not already exist (but its parent should). Please enter directory pathname (network aware if appropriate) for installation materials to be placed. This directory must be an absolute pathname and not already exist. ? /net/vapor/usr/acl4.3 Copying... Please wait... ....................................................................... Many lines of periods deleted to save space. ....................................................................... ............................. Copy Complete! Please refer to the Installation Guide for complete information about how to install the product you selected: -> Allegro CL + Allegro Composer + CLIM 2 (Pre-Built Executables) The following is asked only if you answered y to `Would you like pre-built binaries installed' above. If you answered n to that question, you will be asked if you want to run build/install_lisp (we describe running that program by hand in the next section). If you answer y to that question, an image will be built and installed using the defaults for all parameters. If you answer n, the script completes.. The normal way to install this pre-built product is to execute > bin/setacldir.sh bin/pb_clim2xm_composer /net/vapor/usr/acl4.3 from the > /net/vapor/usr/acl4.3 directory. Would you like to invoke this procedure now [yn]? y The standard thing is to answer `y' at this point. Answer `n' only if, for example, you wish to rename the binary. See below, for more information on the pre-built binary. + chdir /net/vapor/usr/acl4.3 + bin/setacldir.sh bin/pb_clim2xm_composer /net/vapor/usr/acl4.3 bin/pb_clim2xm_composer updated. On all platforms except the IBM RS/6000, you are now done installing Allegro CL if you asked for the pre-built binary and had it installed and it is satisfactory for your needs. You may next need to install Emacs (see section 4.3), report to users and clean up (section 4.4) and (optionally) copy other files from the CD (section 4.5). Also, see below in this section under the heading The pre-built binary for more information. If you are installing on an IBM RS/6000, see the information under the next heading. If you want additional binaries or you did not install the pre-built binary, continue to section 4.2. Step 1.4: Install the IBM-supplied kernel extension This step applies only when installing on an IBM RS/6000 workstation. Note that you work from the directory copied off the CD, not from the CD itself. IBM has supplied Franz Inc. with an AIX kernel extension designed to make foreign loading work properly in Allegro CL 4.3 The code and instructions for installing the kernel extension are in the kernel_extension directory, which should be a subdirectory of the directory where you copied the distribution. kernel_extension/README describes the extension and tells you how to install it. Follow the instructions in that file. If you are installing binaries in addition to the pre-built binary, install the kernel extension first. If it is not possible to install the kernel extension (for whatever reason), foreign loading will in fact work. However, performance is significantly degraded and certain coding restrictions apply. See the information under the heading Foreign loading without the kernel extension in section 2.4.1 Loading foreign code on IBM RS/6000 workstations of the `Release Notes for Allegro CL 4.3 on various platforms' for more information. Nothing in the installation procedure depends on the kernel extension being installed. The pre-built binary The pre-built binary actually consists of two files: an image file (with a name like pb_clim2xm_composer.img, but what comes between the pb_ and the .img depends on the product mix) and an executable shell script which has the same name without the extension. It is the shell script that is actually executed by users. It sets up the ALLEGRO_CL_HOME environment variable to point to the Lisp home directory and invokes the image file. The location is taken from the directory specified in the copydist script. Therefore, it is network aware (the directories are prefixed with something like `/net//') or not as you specified a network-aware name or not. Of course, the shell script is just a text file and can be edited as necessary. A shell-script template is also provided. It has the same name as the shell script but with the extension .template. It can be copied by users who want to execute their own shell script (particularly useful if they want to dump images with excl:dumplisp).I t is in the bin/ subdirectory along with the pre-built binary and its associated shell script. The program that writes the shell script, setacldir.sh, is also in bin/. It can be run to create new shell scripts It should be run from the directory above bin/ and has the following command line: % bin/setacldir.sh bin/ should be the name of the file. The resulting shell script will have that name. The image (which should exist) has that name with the extension .img. The template (.template) is used to create the shell script. Note that the pre-built binary has no stored home location. The Lisp home location will be determined from the ALLEGRO_CL_HOME variable, which is set in the shell script. 4.2 Run build/install_lisp to build customized images You may wish to build images that may not contain all the licensed software (and are thus smaller) or which do not use the default settings of the installation parameters. This section describes how to create such images. We assume you have copied the distribution from the CD, as described in section 4.1. Here are the general instructions from that point. Recall that we assume you copied the distribution into /usr/acl4.3 and we will use that directory in our examples and sample commands. We start this section with some information. The actual installation instructions start under the ehading Step 2.1: Install the IBM Kernel extension below. Installers on platforms other than the IBM RS/6000, the instructions start just below that under the ehading Step 2.2: Build the Lisp image. If you use options other than defaults to install install_lisp does not ask questions. Instead, it uses reasonable defaults in all cases and modifies those defaults with command line arguments. The arguments are listed in section 5 below and described in detail in section 19.4 The install_lisp program and building a Lisp image in the Allegro CL User Guide. As an example suppose you wish to indicate that your site does not use United States Daylight Saving Time (the default is that you do use US DST). Checking section 5, we find the argument is dst= with value yes or no, so call install_lisp as follows: % install_lisp dst=no [other arguments and options] You may want to write a shell script If you want to specify a number of arguments, you may wish to write a shell script which will call install_lisp. This may save you having to type all the arguments each time you install an image. The following simple script specifies several arguments. #! /bin/sh -e # file make-lisp.sh for installing Allegro CL build/install_lisp dst=no devel=yes xref=yes\ newspace=4m oldspace=4m speed=3 The root= argument and running over the network Allegro CL binaries need to be able to find and access their libraries while running. (Note that starting with 4.3, we call the Allegro CL library the home.) In each case location of the library is determined at installation time and the path of the appropriate library directory is stored in the Allegro CL images. On a single machine, there is little likelihood of a problem, but if you have a network of machines, the path stored in the image may be invalid if Lisp is run on a machine which accesses the filesystem containing the library directory. For example, suppose you install Allegro CL in /usr/acl4.3 on machine mach1. Suppose that directory is local to mach1 and pwd on mach1 returns /usr/acl4.3/. In that case, using the default installation, the home location will be stored in the image as /usr/acl4.3/home. When you run on mach1, everything will presumably work fine. However, on another machine, /usr/acl4.3/home might not exist, at least under that name. On a remote machine, the directory may be named something like /net/mach1/usr/acl4.3/home. You can use the root= argument to install_lisp to solve that problem. install_lisp is calling pwd to determine the current directory and resolving relative directories with respect to what pwd returns. If you specify a value for root=, install_lisp will resolve relative pathnames with respect to that value rather than what pwd returns. The value for root= should be the network absolute pathname of the directory where you read the tape and from which you are running install_lisp. In the example in the paragraph above, you would specify root=/net/mach1/usr/acl4.3/ and then the home location will be stored as /net/mach1/usr/acl4.3/home/. Note that Allegro CL 4.3 has changed its method of finding its library compared to 4.2 and earlier releases. First, a name change: what used to be called the library directory is now called the Lisp home directory (and the lib/ directory on the distribution is now the home/ directory). Second, the stored location mentioned above will be used unless an environment variable (ALLEGRO_CL_HOME) can be used to tell the image where to look. If the environment variable is set, the stored location is ignored. Step 2.1: Install the IBM-supplied kernel extension This step applies only when installing on an IBM RS/6000 workstation. This is a repeat of step 1.4 in section 4.1 above. If you installed the kernel extension there, go to the next step. Otherwise install it now. IBM has supplied Franz Inc. with an AIX kernel extension designed to make foreign loading work properly in Allegro CL 4.3 The code and instructions for installing the kernel extension are in the kernel_extension directory on the distribution CD. kernel_extension/README describes the extension and tells you how to install it. Follow the instructions in that file. Return to installing Allegro CL when you are done. You can do this directly from the CD, so you do not have to copy that directory from the CD. If it is not possible to install the kernel extension (for whatever reason), foreign loading will in fact work. However, performance is significantly degraded and certain coding restrictions apply. See the information under the heading Foreign loading without the kernel extension in section 2.4.1 Loading foreign code on IBM RS/6000 workstations of the `Release Notes for Allegro CL 4.3 on various platforms' for more information. Nothing in the installation procedure depends on the kernel extension being installed. Step 2.2: Build the Lisp image The Lisp image is built with the program build/install_lisp. Here is the command line for build/install_lisp: build/install_lisp [product] [install-options] [.o and .a files] [other options] The various arguments are described next, each description starting with a bulleted paragraph naming the argument type. Note that all arguments are optional. RS/6000 installers: see section 5.3 before installing with .o and .a files on the install_lisp command line. · product You can name the product or products being installed. It is not necessary to do so -- the system will build an image with all products ordered if you do not specify a value for product. The choices are: Note that there is no space between the product name, the = sign, and yes, no, or only. If no option is specified, an image containing all products will be built. In CLIM 2.1, the only supported look-and-feel is motif, so clim2=yes is equivalent to clim2xm=yes. · install-options The first install-option is CC=. CC=gcc-or-cc The CC option specifies the name of the C compiler. The hardware-vendor-supplied C compiler is called cc, the GNU C compiler is called gcc. This option tells the system which to look for. (Whichever you specify, the corresponding executable must be in your PATH environment variable, of course.) The C compiler is not necessarily needed to install Allegro CL on Sparc/Solaris 2, but it is needed in many cases and there is no easy rule which differentiates the cases where it is needed from those where it is not. Therefore, we recommend having a C compiler available when you install Allegro CL. If that C compiler is gcc, CC=gcc must appear on the install_lisp command line. If the C compiler is cc, you may specify CC=cc or not, since cc is the default. The installation will fail if a C compiler is required but one cannot be found. Note that the C compiler must be able to produce position independent code (both the Sun C compiler and gcc do produce such code but other C compilers may not). The other two options that we call install-options give finer control over what the binary image is called and where it is placed. (There is no real difference between install-options and other-options. We just highlight these two because they are often useful.) It is not necessary to specify either of these two install-options. If they are not specified, the binary will be in the bin/ subdirectory of the directory where the tape was read (we recommended /usr/acl4.3, so the binary will be in /usr/acl4.3/bin/) and have a name that concatenates the various products included (clim2xm_composer, e.g.) The two options are root= and binary=. We describe them in turn: root=directory The value of this argument should be the network pathname of the current directory (the directory where you read the tape and from which you run install_lisp). The network path typically differs from the local path by having something like /net/machine-name prepended. Thus if /usr/acl4.3/ is the local path, the network path is /net/machine-name/usr/acl4.3/ or something similar. Usually, the network path identifies the directory from every machine on the net (including the local machine) while the local path is often valid only on the local machine. All this matters to Lisp because the location of the Lisp library (what is called the home location in 4.3) is stored in the image. If it is the local path that is stored, Lisp may not be able to find its library when it is run on a different machine on the net. For example, suppose you read the tape into /usr/acl4.3/ on mach1. pwd on mach1 returns /usr/acl4.3/. Using the default installation procedure, the library location will be /usr/acl4.3/home/. But on another machine on the network, pwd in the same directory will likely return something like /net/mach1/usr/acl4.3/ (the exact network name is network-dependent). If that is the case, when you run the image on the other machine, it will not be able to find the library directory since /usr/acl4.3/home/ may not exist or may point to a different, invalid directory. That problem can be solved by specifying root=/net/mach1/usr/acl4.3/. All relative paths will be resolved with respect to that path and the location of the library will be stored as /net/mach1/usr/acl4.3/home/. The image should work on any machine on the network that can locate the library with that path. It is not necessary to provide a value for root=. Since for Lisp installation, it is only the stored library location that is affected by the difference between the local path and the network path, there is rarely a problem if you use the home= argument with the absolute network pathname of the eventual library location. binary=filename-or-path If a filename (i.e. no slashes), then the binary will be called that and placed in the root= directory (from the option just above) or, if root= is not specified, the bin/ subdirectory of the directory where the tape was read. This is a useful option when building an image containing several products since the default name may be quite long. For example an image containing Motif CLIM2 and Allegro Composer will be named clim2xm_composer, which is a fair amount to type. For example, if you read the tape into /usr/acl4.3, the following command will produce the image /usr/acl4.3/bin/clim2xm_composer: % install_lisp clim2xm=yes composer=yes While the next command will produce an identical image in /usr/acl4.3/bin/climcomp: % install_lisp clim2xm=yes composer=yes binary=climcomp While the next command will produce an identical image in /usr/local/acl-clim: % install_lisp clim2xm=yes composer=yes binary=/usr/local/acl-clim If you specify a path, as in the last example, it should be the absolute path complete with the name of the binary image. · .o and .a files These are compiled C or Fortran object files that you wish to have included in your image. (The routines in the files can be called from within Lisp using the foreign-function interface. Note that if you specify a .a file, only those routines necessary to resolve externals in the .o files are loaded into Lisp.) It is not necessary to specify any .o or .a files to build a Lisp image. First-time installers will often not specify any. (If any .o files appear on the command line, the C compiler will be invoked -- Sparc/Solaris 2.x installers see the CC= option described above). IBM RS/6000 installers: see section 5.3 below before installing an image that includes .o and .a files. · .so files On DLFCN platforms (including the DEC Alpha, Sparc Solaris 2.x and SGI, but see the Release Notes which say whether a platform is a DLFCN paltform), you may also include .so files on the install_lisp command line. The .so files will be linked into the Allegro CL image. The .so files must be available to the image when it starts up. They are located with LD_LIBRARY_PATH. · .fasl files fasl (compiled Lisp) files may also be included on the command line. They will be loaded into the image during the installation. If you have many fasl files to load, create one file that itself loads all the rest. The file build/custom.cl is loaded during the installation as well, so it can also contain forms that cause fasl files to be loaded. .so files must be available to the image when it starts up. It is located with LD_LIBRARY_PATH. · other options Many other options can be specified, but most users will not need to specify any. All of the options to config (the older program used to install Lisp) can be specified as options to build/install_lisp. Section 5 Other installation options below has a table of these options and section 19.4 of the Allegro CL User Guide has even more information on config options. Transcript of an installation The following transcript shows a successful installation. It is for Allegro CL only on a DEC Alpha machine. We have deleted some of the output to save paper. At the end, a message suitable for distribution to users is printed. % build/install_lisp binary=my-acl root=/net/vapor/usr/acl4.3 =========================================================================== Allegro CL 4.3 parameters, based on the input you have given: ICS (16-bit characters): no Default external char format: :ascii Use Allegro Presto: no Put pure objects into: shared-library Install Allegro NIS interface: yes Install CLIM 2.1: NA Install Allegro Composer: NA Install Allegro Common Windows: NA Install development environment: yes Xref info recording/loading: no Install Common Lisp compiler: yes Allegro CL image pathname: /net/vapor/usr/acl4.3/bin/my-acl Allegro CL home pathname: /net/vapor/usr/acl4.3/home Case mode: insensitive-upper Estimated max heap size: 120m bytes Size of initial oldspace: 12m bytes Newspace free in image: 2m bytes Oldspace free in image: 512000b bytes The "speed" default value: 1 The "safety" default value: 1 The "space" default value: 1 The "debug" default value: 2 U. S. Government customer: no Daylight savings time observed: yes machine configuration: OSF1 romeo V3.2 148 alpha ---------------------- Removing ucl, static.o, and nihroutines.o. Creating /net/vapor/usr/acl4.3/home/4.3.lso from cl-train-devel.cvs cl-interp.cvs cl-comp.cvs cl-devel.cvs acl.str processed from standard input, read 11311 codevector(s), 42567 string(s) dropped 213 replications dropped 250 replications dropped 258 replications dropped 456 replications Dropped 4735 code duplicates Dropped 10733 string duplicates Added 24600 lowercase strings Wrote 5395 vectors, 31834 strings, 4583024+(64) bytes to ./cvs14891 mv ./cvs14891 /net/vapor/usr/acl4.3/home/4.3.lso Creating ucl Initial generation spread = 1 Allocated 12589176 bytes for old space Allocated 2097152 bytes for new space ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; area address(bytes) cons symbols other bytes 8 bytes each 24 bytes each (free:used) (free:used) (free:used) Top #x14e74000 New #x14d74000(1048576) ----- ----- ----- New #x14c74000(1048576) 1019:1019 254:0 971904:376 Old #x14070f50(12595376) 0:49931 334:10853 11275864:641448 Root pages: 1 Allegro CL 4.3 [DEC Alpha Series; R1] (4/23/96 14:06) Copyright (C) 1985-1996, Franz Inc., Berkeley, CA, USA. All Rights Reserved. ;; Optimization settings: safety 1, space 1, speed 1, debug 2. ;; For a complete description of all compiler switches given the ;; current optimization settings evaluate (EXPLAIN-COMPILER-SETTINGS). USER(1): ; setting case mode... ; Loading ./load_devel.cl ; Fast loading from bundle code/list2.fasl. ; Fast loading from bundle code/seq2.fasl. [...] ; Fast loading from bundle code/a/disalpha.fasl. NIL [Current process: Initial Lisp Listener] USER(2): ; Loading ./custom.cl ; Fast loading ./acl-preload.fasl NIL [Current process: Initial Lisp Listener] USER(3): ; global gc... ; dumping image... ; Exiting Lisp echo "== Completed build of ./acltmp.14891" == Completed build of ./acltmp.14891 moving Allegro CL binary to /net/vapor/usr/acl4.3/bin/my-acl... mv ./acltmp.14891 /net/vapor/usr/acl4.3/bin/my-acl ******************************************************************************* You have successfully built Allegro Common Lisp, binary in: /net/vapor/usr/acl4.3/bin/my-acl The home location, ie. the location of the library files, for that image is: vapor:/net/vapor/usr/acl4.3/home You can now inform the Allegro users at your site to: 1. Modify their PATH environment variable to contain: /net/vapor/usr/acl4.3/bin So they can access my-acl. 2. Modify their ~/.emacs to contain: (setq load-path (cons "/net/vapor/usr/acl4.3/home/emacs/fi" load-path)) (load "fi-site-init") NOTE: Very old versions of the Emacs-Allegro CL interface required a different initialization. "fi-site-init" is now loaded instead of "fi/site-init" and load-path must be modified to explicitly contain the fi/ directory as above. ******************************************************************************* The output between the two lines of asterisks was saved in the file install_lisp.out in this directory. % 4.3 Install Xemacs by running install_emacs Xemacs 19.13 is supplied as a pre-built binary with Allegro CL 4.3. It is very easy to install the binary. Because the installation program is run from the the CD (not from the copy of build/ that you made in step 2 above), you must provide the name of the installation directory chosen in step 1.1 above as an argument. Assuming the CD is /cdrom/cdrom0/, proceed as follows ( is the platform on which you are installing): % cd /cdrom/cdrom0/ % ./install_emacs /usr/acl4.3/ 4.4 Provide information to users and clean up You should tell users the following three things. Note that a message suitable for sending to users is printed at the end of the Allegro CL installation procedure (see section 4.2 above for an example of that message) if you used install_lisp to install. (No such message is printed when the pre-built binary is installed.). 1. All users of Allegro CL should have the directory where the Allegro CL binary image is installed in their PATH environment variable. If you used the default location, then the binary is located in /usr/acl4.3/bin and that should be in their PATH. Users unfamiliar with PATH should be told to add the following line to their ~/.cshrc file (creating it if necessary): set path=(/usr/acl4.3/bin $path) where /usr/acl4.3/bin is changed to the proper value (where the Lisp and emacs binaries are located). 2. All users should have the following in their .emacs file: (setq load-path (cons "/usr/acl4.3/home/emacs/fi" load-path)) (load "fi-site-init") 3. All users should also be told about the name of the Allegro CL executable file and, on Sparc/Solaris 2, should be told to set up their LD_LIBRARY_PATH appropriately if they intend to use CLIM2 (they must add /usr/dt/lib to the list of directories that is the value of that environment variable). Clean up You can now clean up the files used in installation. You have several choices, as we describe below. · Only the bin/ and home/ directories are necessary to use Allegro CL. You may delete the build/ directory but note that you must re-install from the CD if you want to build more images or to build a runtime image (Allegro Runtime is a separate product from Allegro CL -- contact your sales representative for details) or a specialized image as described in Technical Memorandum #23. · If you do not want to remove build/, you can clean up files that were created in build/ during the installation (and also one in home/) with the following command: % build/install_lisp +clean See the description of this argument in section 19.4 of the Allegro CL User Guide for the list of files removed. Do not strip the image! The Unix strip program removes (supposedly) unnecessary pieces of an executable image. However, Allegro CL needs those pieces. For example, in Solaris 1.x, foreign loading, excl:dumplisp, and some other features will not work if the image is stripped. In Solaris 2.x, a stripped Lisp will not even start up. Do not strip the image! 4.5 Copy other files from the CD (optional) The CD contains a directory named extra/ with various subdirectories containing material that may be useful or interesting. You are free to use it (see the associated README or similar files for any restrictions). Copy whatever you wish from the CD to a permanent location. Except for the Xemacs 19.13 pre-built binaries (which you should have installed in section 4.3 above), none of the material is necessary to use or run Allegro CL or related products. Among the directories are aclwin/ (a free but limited version of Allegro CL 3.0 for Windows), dpANS3/ (an online description of the proposal for ANSI Common Lisp) and mule-2.3/ (an international character set version of Emacs). 5 Other installation options There are many options available when installing Allegro CL and related products. The table below, table 19.1 from the Allegro CL User Guide, lists options accepted by build/install_lisp. Most users will probably not need to specify any additional option. Chapter 19 of the Allegro CL User Guide has more discussion on each of these options. If an option is of the form option=, you specify it with its value as follows: option=value (with no spaces on either side of the = sign). The default is in the description. Some defaults depend on the values of other arguments. Other options are of the form +option. These take no arguments. Also, several types of files can be supplied as options. The +option options and the types of files are specified at the end of the table. The other options are in alphabetical order. Some options available in earlier releases of Allegro CL have been removed in Allegro 4.3. We have maintained the entries in the table for these options, indicating that they are no longer to be used. Other options do not apply to all platforms, as indicated. Table 19.1 Arguments to install_lisp Argument Values Comments binary= The specified file names the Lisp image. The default depends on the product mix. The filename alone or the filename with its absolute path should be given. case_mode= insensitive-upper sensitive-upper insensitive-lower sensitive-lower The default case mode (default is insensitive-upper) CC= cc-or-gcc Specify whether to use GNU C compiler. Default is cc, meaning use standard C compiler. clim= No longer supported. See description in chapter 19 of the User Guide for more information on this removed argument. clim2= clim2xm= yes-or-no Include CLIM2 in image. Default depends on other arguments clim2xm= means use the motif version of CLIM, but only that version is supported so the two arguments are equivalent. composer= yes-or-no Include Allegro Composer with image. Default depends on other arguments. compiler= yes-or-no Include compiler in image. Default yes.Specifying no does not leave all the compiler out. See description in chapter 19 of the User Guide for more information on this argument.. config_debug= yes-or-no Causes debugging information to be printed. Default no. debug= 0-1-2-or-3 Initial value for debug optimization quality. Default 2. devel= yes-or-no Include development environment. Default yes. dst= yes-or-no Do you observe US Daylight Saving Time schedules? Default yes. estimated_max_ heap_size= # of bytes #k of Kbytes #m of Mbytes Specifies estimated maximum size (but size can grow bigger than this value). Default 120 meaning 120 Megabytes. Replaces prealloc= which is kept for backward compatibility. Note the line break in the argument name is an artifact of the space available to print. It should all be one word. ffhole= # of bytes #k of Kbytes #m of Mbytes Leave this much space in image for foreign functions. Default depends on other arguments. Only applies to non-DLFCN platforms. generate_fonts= yes-or-no Generate fonts from server specified by server_name=. Default no. gov_flags= yes-or-no Indicates user works for/on behalf of US Government. Default no. home= The Lisp home location (called library directory in earlier releases). The contents of the home/ directory from the distribution will be copied to this location. Defaults to home/ directory on same level as build/. ics= yes-or-no Build an International Character Set image (yes) or a standard character set image (no). Default depends on whether ICS code is present. initial_oldspace= # of bytes #k of Kbytes #m of Mbytes Size of oldspace at beginning of installation. Default depends on product mix. library= Obsolete. Equivalent to home=. Do not specify both this and home=. libXol= No longer supported. Used to specify OpenLook library location for OpenLook CLIM 2, which is no longer supported. lso_file= Give .lso file specified name and location. Default depends on product mix. main_obj= See description in chapter 19 of the User Guide for more information on this argument. newspace= # of bytes #k of Kbytes #m of Mbytes Size of newspace. Default depends on product mix. nis= yes-or-no Use Network information system patch. Default yes. oldspace= # of bytes #k of Kbytes #m of Mbytes Free space in oldspace at end of installation process. Default depends on product mix. prealloc= # of bytes #k of Kbytes #m of Mbytes Obsolete. Same as estimated_max_heap_size=, which should be used instead. Kept for backward compatibility. pure= shared-library text heap Specify whether image should be built with code vectors in a .lso file, in the text segment, or in the Lisp heap. Default shared-library. restart_function= No longer supported! See description in chapter 19 of the User Guide for more information on this removed argument. safety= 0-1-2-or-3 Initial value for safety optimization quality. Default 1. server_name= Specifies X server from which to get fonts. Default is unspecified, meaning do not use a server. speed= 0-1-2-or-3 Initial value for speed optimization quality. Default 1. temp= Directory to use for temporary files (allows you to specify a local directory to avoid NFS problems). Default is unspecified, meaning use /tmp. whichclim2= No longer supported! Only motif CLIM2 is supported, so this argument is no longer relevant. xcw= yes-or-no Include Allegro Common Windows with image. Default depends on other arguments. xref= yes-or-no The initial values of excl:*record-xref-info* and excl:*load-xref-info* depend on this argument. Default is no (meaning value will be nil) +presto n/a (Takes no argument). Build a presto image. +clean n/a (Takes no arguments.) Do not install. Instead, remove files created during build. *.fasl n/a fasl files to include in image. *.o n/a .o files to include in image. *.so n/a .so files to map into image. *.a n/a Archive (.a) files to be used to resolve externals in .o files. *.cvs .cvs.gz n/a .cvs files to include in text space. cvs.gz files are compressed with gzip and install_lisp will uncompress them. 6 Additional information for certain platforms This section contains information on things that might have to be done on certain platforms in conjunction with installing Allegro CL but are usually not necessary and so are not needed by all installers. 1. Including foreign code in the Allegro CL image: IBM RS/6000 only. 2. Installing from a 4mm tape. HP only. 6.1 Including foreign code in the Allegro CL image: IBM RS/6000 only Allegro CL 4.3 on the RS/6000 does support dynamic loading of foreign files into a running Lisp image. Instructions for loading foreign code are given in the `Release Notes for Allegro CL 4.3 on various platforms.' Nonetheless, including foreign code in the image when it is built is still useful. An image with foreign code included when it was built is typically smaller than the same image with foreign code dynamically loaded. Dynamic loading of foreign code can put a gap in the Lisp heap, which may cause the image to grow more than otherwise necessary (gaps are discussed on page 15-3 and on page 15-9 of the Allegro CL User Guide). Please note that these same `problems' with foreign loading exist on every version of Allegro CL. For most use, dynamic loading of foreign code is what you want. However in some cases, particularly when preparing an image for further distribution, including foreign code in the image is desirable. The remainder of this section describes how this is done for Allegro CL on RS/6000's running AIX. The RS/6000 linker causes a complication when building images that include foreign code. The linker will not include functionality which it decides is not necessary. This has always been true with .a archive files: linkers and loaders only took out of such files what they knew to be necessary to resolve externals and ignored the rest. On the RS/6000, this process is applied to .o files as well. To be sure that your foreign code is included in the image, you must reference the functions in the file userstubs.c, which we discuss below. It is easiest to show how to include foreign files with a concrete example. Suppose you have a Fortran function named foo() defined in a file /usr/mydir/foo.o. foo() calls routines from the xlf system library. You must include all necessary foreign code in the image when it is built. There are four steps, which we list briefly and then describe in more detail. We will discuss a C function after describing including foo(). 1. (Before building the image) copy the file build/userstubs.orig to build/userstubs.c. 2. (Before building the image) modify userstubs.c. 3. (Before building the image) determine libraries require by foo(). 4. (At build time) build an image with foo.o and the libraries on the command line. 5. (After building the image) save the file build/userstubs.c (optional) 6. (At run time) call ff:defforeign to define foo() within Lisp. Each step in detail. 1. (Before building the image) copy the file userstubs.orig to userstubs.c. If you look in the build/ directory read off the tape, you will see several files named stubs.c (e.g. cstubs.c). The only one of these you should touch is userstubs.c. The file userstubs.orig is a clean version (which lists no dummy function calls). The idea is that you copy that file to userstubs.c, and modify userstubs.c to include the dummy function calls that you want (how is described below). Note the procedure we describe requires that all dummy function calls be added to userstubs.c each time an image is built. Obviously, that procedure will always work. However, you may develop a modified pro- cedure suitable for your specific needs (e.g. having different userstubs.c files with specific dummy function calls in each, perhaps for different applications or different users). Once you understand what userstubs.c is for, you can design a procedure tailored to your needs. We do recommend that you leave userstubs.orig unchanged since that allows you to start over without rereading the tape. Note that there is a userstubs.c file already on the tape. As delivered, it is identical to userstubs.orig. 2. (Before building the image) modify userstubs.c. This file should contain references to the foreign functions needed within Lisp. The file with no references looks like (we have modified the line breaks in the comments to fit them on our page) /* * Since the rs6000 /bin/ld does a garbage collection on * all unreferenced functions, we must protect those * functions by referencing them. This file is protected * by a "call" to userstubs that never gets executed. */ userstubs() { /* add calls to functions which you want to defforeign after this line but before the closing brace */ } We need to add foo(), so we put it on a line after the comment starting `add calls...', as follows: /* add calls to functions which you want to defforeign after this line but before the closing brace */ foo(); } Note that it is the function name, not the filename which goes there. The filename goes on the build/install_lisp command line. 3. (Before building the image) determine the libraries required by foo(). Required libraries must also be specified on the build/install_lisp command line. You must specify the full pathname of a library file. In particular, you cannot use the single letter abbreviation accepted by load and ld(). In our case, foo() requires the xlf library. You might specify that library to load or ld() with -lxlf. -l expands to /usr/lib/lib.a, so for the xlf library, the full path is /usr/lib/libxlf.a. Note: the math library (/usr/lib/libm.a), the bsd library (/usr/lib/libbsd.a), the ld library (/usr/lib/libld.a), and the standard C library (used by default by cc) are already included in the image. Do not specify them again. 4. (At build time) build an image with foo.o and the libraries on the command line. Recall that we said above that the full path of the file foo.o is /usr/mydir/foo.o. When you run build/install_lisp, be sure that the path of every needed file and archive is available. (You may use relative pathnames but we recommend absolute pathnames, especially for libraries.) In this case, you add /usr/mydir/foo.o and /usr/lib/libxlf.a to the build/install_lisp command line, as follows ([options] means other command line options described below): root# sh build/install_lisp [options] /usr/mydir/foo.o /usr/lib/libxlf.a 5. (After building the image) save userstubs.c (optional). This step relates to our comments above about managing userstubs files. You have to decide how and where to save these files. Obviously, in our simple example where only one function is listed, it does not make much difference whether you save the file or not. But it is not uncommon to have many foreign routines and typing them in every time is tedious. There is not much more to say on this point beyond the following two recommendations: (1) unless you are the only Lisp user (and even then), do not simply modify userstubs.c and leave it on disk. Another user needing different foreign functions may destroy the file inadvertently. userstubs.c should be viewed as a temporary file. (2) Do not modify userstubs.orig. As we said above, it is useful that that file be available to start over at any time. 6. (At run time) call ff:defforeign to define foo() within Lisp. This is no different than the case where foo.o is loaded dynamically. You must call ff:defforeign to define the foreign function to Lisp, as described in section 10.2 Defining a foreign function to Lisp in the Allegro CL User Guide. Suppose foo() was a C function instead of a Fortran function, and that it requires the math and the standard C libraries only. You would still put foo() in userstubs.c (as described in step 1 above) and put /usr/mydir/foo.o on the build/install_lisp command line but you would not specify any additional libraries or archives since both (math and standard C) are used by default. Two final points about userstubs.c and other stub files. (1) The function userstubs() is defined in userstubs.orig. That function is never in fact called so the actual order of external references is unimportant. (2) During the build process, appropriate stubs.c are concatenated into a file named stubs.c. That file is left in build/ after installation is complete. It might be useful in tracking down problems (since it indicates exactly what input was provided for the build) but has no other use. A new one is created (and the old one deleted) each time a Lisp image is built. 6.2 Installing from a 4 mm tape (HP only) If you are unable to read the distribution CD in Rockridge format (and HP CD drives with some versions of HP-UX do not support Rockridge format), you will have to read the distribution from a 4 mm tape. In this section, we assume you have such a tape. HP tape step 1: Read the tape into an empty directory Choose an empty directory with enough free space to read the contents of the tape (see the chart in section 3.1 above and add 50 Mbytes -- for Xemacs -- to the figure for your product mix). This is the final distribution directory. We assume you choose /usr/acl4.3 and that the directory exists, is empty, and has sufficient space. Then: 1. Insert the tape into the tape drive. 2. Read the tape with the command % tar xf /dev/rmt/0m HP tape step 2: Install the prebuilt binary (optional) The pre-built binary image will be in the bin/ subdirectory. It is a file whose name starts with pb_ and the filename must be specified as an argument to the pre-built binary installation program. That program creates the shell script that is actually executed by users (it sets up the ALLEGRO_CL_HOME variable correctly and starts the actual image). Enter the following command run from the directory where you read the tape: % bin/setacldir.sh bin/ is the filename of the pre-built image without its extension (the file is bin/pb_.img, so you enter bin/pb_). is the path- name of the directory with whatever network preface is used at your site (if any). For example, if the directory is /usr/acl4.3 and your site prefaces directories with /net/, you would specify /net/ argument. HP tape step 3: Install Emacs The pre-built Xemacs binary is already installed in the bin/ subdirectory. It is not necessary to do anything further. You may skip section 4.3. HP tape information: the extra directory The extra/ directory, containing GNU related sources and contributed software is not included on the tape. Please contact Franz Inc. for information on the contents (none of which are needed to run Allegro CL or related products). Material can be made available by ftp if desired. HP tape step 4: go to section 4.2 Go to section 4.2 to continue the installation process. Note that it is not necessary to perform the steps in section 4.3 Install Xemacs .... 7 Troubleshooting What can go wrong during installation? Well, the usual bunch of simple errors and complicated interactions. In this section, we give the messages that indicate some failures, and a description of what may be wrong and how to fix it. Misnamed argument If you specify an argument to install_lisp that it does not recognize, you will see an error message similar to the following (here bin= was specified instead of binary=): lava% build/install_lisp bin=myimg build/install_lisp: bad argument: bin=myimg ******************************************************************************* *** The build of Allegro Common Lisp failed. *** Please check that you have enough space and correct any errors *** above. ******************************************************************************* Not enough space Allegro CL requires quite a bit of space to install successfully. As the error message above indicates, running out of space is always a possible cause of installation failure. The message before the error notice when insufficient space is the problem is often a message that mv, rcp or cp failed, usually saying at some point `No space left on device'. Here is the end of a transcript that failed because of insufficient space. Appended to the transcript is the output of du, showing the device (sole:/usr) is indeed full. rcp /usr/tmp/cvs10580 sole:/usr/cl/lwolf/aclonlytape/a-lib/4.3.lso rcp: can't truncate /usr/cl/lwolf/aclonlytape/a-lib/4.3.lso: No space left on device bin/mv-nfs: rcp failed, will try and move the image... mv: /net/sole/usr/cl/lwolf/aclonlytape/a-lib/4.3.lso: write: No space left on device rm /usr/tmp/cvs10580 bin/mv-nfs: mv failed, too. ******************************************************************************* *** The build of Allegro Common Lisp failed. *** Please check that you have enough space and correct any errors *** above. ******************************************************************************* 19.1u 29.8s 3:30 23% 0+1256k 1526+2236io 1603pf+0w vapor% df . Filesystem kbytes used avail capacity Mounted on sole:/usr 871464 784330 0 100% /tmp_mnt/net/sole/usr vapor% Cannot access ucl ucl is the name of the raw Lisp image used to build the complete Lisp image. It is constructed out of ucl.o and other .o files. The installation process may think that ucl is available when in fact it needs to be created. If this happens, you typically find out when the system tries to copy it: + cp -p ucl ucl.orig cp: cannot access ucl The solution is to clean up things and try again. You clean up with the following command: % build/install_lisp +clean Sparc/Solaris 2.x only: Using /usr/ucb/cc by mistake On Solaris 2.x, you must use a C compiler that produces position-independent code. The Sun C compiler that produces such code is not bundled with Solaris 2.x (i.e. you have to buy it). gcc, supplied with Allegro CL also produces position-independent code. /usr/ucb/cc does not produce position-independent code. It may happen that your PATH points to /usr/ucb/cc instead of the new Sun C compiler and the system tries to install using /usr/ucb/cc. This will fail with a message similar to the following: /usr/ucb/cc: language optional software package not installed *** Error code 1 make: Fatal error: Command failed [...] The solution is to change your PATH so that the proper C compiler is used (it is typically in /usr/ccs/bin) or install gcc and specify CC=gcc on the install_lisp command line. In general, if an installation fails... If an installation of Allegro CL fails and you cannot diagnose and fix the cause of the failure, clean up with % build/install_lisp +clean Then try the installation again, just as before, but add the argument config_debug=yes to the command line. If this installation also fails, please contact us for assistance. (See the last page of this document for information on contacting us.) The transcript of the attempted installation with config_debug=yes specified will provide us with important information on what went wrong, so you may have to send the transcript to us. 8 How to contact us Please contact us if you have any problems configuring or installing Allegro CL, Allegro Composer, Allegro CLIM, Xemacs. Our voice phone number is (510) 548-3600. We are open from 8:00 am to 5:00 pm (Pacific time) every business day and technical people are available during those times to assist you. Our FAX number is (510) 548-8253. You may send us a fax at any time. The best way to send us a bug report is by electronic mail (e-mail). E-mail allows you to send exact transcripts of Lisp sessions. You can send e-mail to the following address: bugs@franz.com In any message, be sure to include your name and organization, your e-mail address, your phone number (very important), the machine make and type, and the operating system version identifier. Also include the Allegro CL version number, and as much information as you can give us about the problem, including, if possible, a small test case illustrating the problem. We recommend that Lisp sessions be recorded with the excl:dribble-bug function when preparing a bug report or question. This function, described in section 1.6 Reporting bugs in the Allegro CL User Guide, is similar to the Lisp function dribble with the added feature that it automatically records information about your version of Allegro CL in the dribble file. We need you to explicitly tell us your e-mail address in the body of the letter since the return addresses generated by mailers may be invalid. Also we need your phone number in case e-mail to you fails. We are also interested in your comments about our product. There is an information sheet in the Allegro CL User Guide with more electronic addresses for comments. You may also use one of the addresses above. Note that any technical communication with Franz Inc. should be sent to bugs@franz.com (i.e. the address near the top of the page). Despite the name of that mailing list, we welcome any question or comment, not just bug reports. FAQ, WWW homepage, and Mailing List Franz Inc. maintains a WWW homepage, http://www.franz.com/. It provides product information and has links to patches and the FAQ. The FAQ (Frequently Asked Questions document) contains useful information derived from questions to the Franz Inc. technical staff. We recommend that everyone obtain a copy. It can be accessed from the WWW page or by ftp from ftp.franz.com:/pub/faq The mailing list, Allegro-CL@cs.berkeley.EDU, is used by Franz Inc. for announcements related to the Allegro CL family of products. Customers can use it to start discussions with other customers. This list is unmoderated and completely open. If you want your name added to the mailing list, send a request to Allegro-CL-request@cs.berkeley.EDU. We hope you enjoy our product. We appreciate having you as a customer.