Installation Guide for Allegro CL 5.0.1

Windows (95/98/NT/2000) and UNIX (including Linux and FreeBSD)

$Revision: 5.0.2.64 $

Copyright (C) 1999 by Franz Inc. All rights reserved. Allegro CL is a registered trademark of Franz Inc. Allegro Presto is a trademark of Franz Inc.

The HTML version of this document looks best when viewed with Netscape 4.0 or later.


Contents

Allegro CL Lite users: look for the <Lite> symbol below for details on Lite.

Overview
    Add-On Products
    Available Platforms for Allegro CL
    Where Are the New Features Documented?
    <Lite> Description of Allegro CL Lite
    Description of Allegro CL Trial
Pre-Installation
UNIX Installation
    CD-ROM Distribution on UNIX
        Installing Add-on Products in UNIX
        Upgrading from one version of Allegro CL to another
    FTP Distribution on UNIX
Windows Installation
    CD-ROM Distribution on Windows (non-Lite)
         Installing Windows Add-on in Windows
         Upgrading from one version of Allegro CL to another
    <Lite> CD-ROM Distribution on Windows (Lite)
    FTP Distribution on Windows (non-Lite)
    <Lite> FTP Distribution on Windows (Lite)
AllegroStore Installation
Allegro ODBC (v1) Installation
Installation of GNU Emacs and XEmacs
Installation and Use of the Emacs-Lisp Interface
<Lite> Installation of Patches
Uninstalling Allegro CL
Post-Installation
    Allegro CL
    <Lite> Allegro CL Lite [Windows only]
    Allegro ODBC (v2)
    Allegro Composer
    CLIM
    Allegro ORBLink
    Source Code: Common Lisp
    Source Code: Common Graphics and the IDE
    Source Code: CLIM
    Source Code: Allegro ODBC
    C/C++ Binder tool
    The Emacs-Lisp Interface and the IDE [Windows only]
Links to Related Documents


Overview

This document covers the installation of the following versions of Allegro CL:

  • Allegro CL Enterprise Edition, Domestic and International versions
  • Allegro CL Professional Edition, Domestic and International versions
  • Allegro CL Personal Edition (Windows only)
  • Allegro CL Student Edition (Windows only)
  • Allegro CL Trial Edition (Linux and FreeBSD only)
  • Available for Linux (Redhat 4 and 5/6), FreeBSD (3.x) and MkLinux (DR3)/LinuxPPC (R4)
  • Allegro CL Lite (Windows only)
  • There are four CD-ROMs containing Allegro CL:

    Add-On Products

    This table contains information about which add-ons are standard (Y) , which are available as options to be purchased separately (a), and which are not available (n).

     

    Add-On Product

    Base Lisp name

    Enterprise

    Professional

    International Enterprise

    International Professional

    Personal

    [Windows only]

    Student

    [Windows only]

    Trial

    Lite

    [Windows only]

    Allegro ODBC v1

    Y a n n n n

    Allegro ODBC v2

    Y a Y a n n
    AllegroStore a a a a a a n n
    CLIM a a a a a a n n
    Composer (unix only) Y a Y a n n n n
    Dynamic Runtime a a a a n n n n
    ICLIM n n a a n n n n
    ORBLink a a a a a a n n
    Profiler Y a Y a a a Y Y
    Runtime Y a Y a n n n n
    Socket Library Y Y Y Y a a Y Y
    Source Code: Common Graphics + IDE (windows only) Y Y Y Y a a n n
    Source Code: CLIM a a a a a a n n
    Source Code: Lisp Y Y Y Y a a n n
    Source Code: ODBC Y a Y a a a n n
    Legend: § Allegro ODBC requires the Socket Library
    Source code NOTE: All source code products require the execution of the Source Code and Support Addendum to Franz Software License Agreement (shipped with your package) before they can be installed.
    International NOTE: The non-International version is included in the International.  That is, when you install the International version, you have access to both the International (lispi) and non-International Lisp (lisp) executables.

    Available Platforms for Allegro CL

    The following bullets show the Operating System versions on which Allegro CL and related products run. Contact Franz Inc. (bugs@franz.com) for information on OS versions released after this document was published or for an update on released versions where Allegro CL or related products do not work. There is platform-specific information sections for each version in the Release Notes. Each bullet has a link. Note that there may not be additional information for all platforms.

    AllegroStore note: all add-on products except AllegroStore work on the same OS versions as Allegro CL unless otherwise noted. AllegroStore does not work on all versions of Solaris (Sun SPARC) and IRIX (SGI).

    The following table shows the availability of add-ons for each platform.  Y means available and n means unavailable.

    Add-On Product

    Lisp Platform

    Alpha Digital UNIX

    HP-UX Sun Solaris SGI IRIX

    IBM AIX

    x86 Linux Redhat FreeBSD MkLinux
    LinuxPPC
    x86 Windows AXP Windows NT

    Allegro ODBC v1

    n Y Y n Yf n n n Y Y

    Allegro ODBC v2

    Ya Ya Ya Ya Ya Ya Ya Ya Ya Ya
    AllegroStore n Y Yd Yc n n n n Y n
    CLIM Y Y Y Y Y Yb Yb ne Y Y
    Composer Y Y Y Y Y Y Y Y n n
    Dynamic Runtime Y Y Y Y Y Y Y Y Y Y
    ICLIM Y Y Y Y Y Y Y ne Y Y
    ORBLink Y Y Y Y Y Y Y Y Y Y
    Profiler Y Y Y Y Y Y Y Y Y Y
    Runtime Y Y Y Y Y Y Y Y Y Y
    Socket Library Y Y Y Y Y Y Y Y Y Y
    Source Code: Common Graphics + IDE n n n n n n n n Y Y
    Source Code: CLIM Y Y Y Y Y Y Y ne Y Y
    Source Code: Lisp Y Y Y Y Y Y Y Y Y Y
    Source Code: ODBC Y Y Y Y Y Y Y Y Y Y
    Notes:
    a Allegro ODBC v2 has only been tested on Solaris and Windows, but it should work on all platforms.
    b CLIM on Redhat 4 and 5/6, and FreeBSD is only supported with Metro Link Motif 1.2.4.  See the Metro Link web site www.metrolink.com for details.  Metro Link Motif Complete! required for FreeBSD.  There are serious known issues with using CLIM and LessTif on these platforms.
    c Only works on IRIX 6.4 or later.
    d Only works on Solaris 2.5.1 or 2.6.
    e MetroLink Motif does not exist for MkLinux/ LinuxPPC.  Because CLIM does not work with LessTif, CLIM is not currently available on this platform.
    f Allegro ODBC on IBM/AIX requires at least AIX 4.2.1 and Intersolv DataDirect version 3.11 drivers.

    Where Are the New Features Documented?

    New features and changes to Allegro CL 5.0.1 are documented in the Release Notes.

    Description of Allegro CL Lite

    The Lite Edition is available for free, on both CD-ROM and as a download.  See our website for information about both.

    The Lite Edition has the following features:

    The Lite Edition has the following limitations:

    Add-on products are not available for the Lite Edition.

    Description of Allegro CL Trial

    The Trial Edition is available for free, on both CD-ROM and as a download.  See our website for information about both.

    The Trial Edition contains the following features:

    The Trial Edition of Allegro CL has the following limitations:

    Add-on products are not available for the Trial Edition.

    | Contents | TopRelated Documents |


    Pre-Installation

    Windows users take note:

    1. Uninstall all previous releases of Allegro CL 4.x and 5.x.  We strongly urge you to uninstall Allegro CL 5.0. There are known problems with installing later releases on top of earlier ones. To uninstall use the Uninstall item on the Allegro CL submenu of the Start menu or use the Start | Settings | Control Panel | Add/Remove Programs command. Be sure to uninstall all the uninstallable items, if you installed add-on products; also, uninstall the most recently installed components first. If you simply delete the previously installed directory you will still have problems installing the newer release.

    You should save all your personal files in a separate location. (Do not save 5.0 or 5.0.1.beta2 patch files as they should not be used with 5.0.1.) After uninstallation completes, it is likely that the 5.0 Allegro Directory (by default C:\Program Files\acl5.0\) will not be removed (because uninstallation did not remove all files). You can remove the directory by hand after uninstall completes.

    1. Exit all other applications before beginning the installation. This insures a cleaner installation process.
    2. If you are installing ORBLink. ORBLink requires the Allegro CL Socket Library, so if you plan on using ORBLink with the Personal or Student Editions of Allegro CL, you will also need to purchase and install the Allegro CL Socket Library.

    This document generically uses the term <ACL directory> to refer to the place you installed Allegro CL. This is also referred to as the Allegro directory.

    The International products are a superset of the non-International product of the same name.  That is, if you install International Allegro CL Enterprise Edition, you should not install Allegro CL Enterprise Edition, since it is effectively already installed.

    | Contents | TopRelated Documents |


    UNIX Installation

    Choose a specific set of installation instructions from either the CD-ROM or the FTP section.

    When you have completed the appropriate installation instructions, you can execute Allegro CL by running <ACL directory>/lisp (see below for starting Allegro Composer). See Allegro CL Startup for more information on starting and running Allegro CL.

    Allegro CL Trial Edition:

    Allegro CL Trial Editions are distributed on a separate CD-ROM.   For installation of the Trial Editions, see the README.trial in the root directory of the Trial CD-ROM.


    CD-ROM Distribution on UNIX

    The Allegro CL distribution on a CD-ROM includes several subdirectories corresponding to platform names onto which Allegro CL can be installed--the list of platform subdirectories is given below. If your distribution CD-ROM does not contain a subdirectory corresponding to your desired platform, contact us before proceeding.

    You need one or more license keys from Franz Inc to install Allegro CL on your desired platform. A license key is a string of letters and digits used by the copydist program described below. The license key(s) are written on sticker labels included in your Allegro CL package. We recommend that you put one set of the stickers on the CD-ROM jewel case so it will be made available to you when you install the product. If you do not have a license key for your software, please contact us before proceeding.

    Important: Be sure to save your list of license keys for future reference and reinstallation. Some add-on products have different keys from that of the base Lisp product.

    The installation procedure consists of one step, copying the distribution files to your computer's disks via the copydist program. Each platform subdirectory on this CD-ROM has its own version of copydist. This section gives instructions on where to find the appropriate copydist on your CD-ROM.

    When invoked, copydist asks you for the following:

    1. the product whose distribution is to be copied,
    2. the license key supplied to you for that product, and
    3. the directory into which the distribution will be copied.

    After entering answers to the above questions, copydist creates the directory in (3) containing the files for the product you wish to install.

    The general form of the installation is:

    % cd directory
    % ./copydist

    where directory is one of the values from the first column in the following table:

    Directory Machine and Operating System
    sol24 Sun Solaris 2.4 or later
    irix62 SGI/Irix 6.2 or later
    hpux1020 HP-UX 10.20 or 11.0 (despite the directory name)
    alphadu4 Compaq (formerly DEC) Alpha/Tru64 UNIX 4.0 or later (Compaq recently renamed Digital UNIX to Tru64 UNIX).
    aix42 IBM RS6000/AIX 4.2 or later
    redhat4 Intel/Linux Redhat 4.x
    redhat5 Intel/Linux Redhat 5.x/6.x
    freebsd FreeBSD 3.x
    linuxppc MkLinux DR3 and LinuxPPC R4

    Installing Add-on Products in UNIX

    There are two types of products you can install with copydist: base Lisp products and add-on products (which have [add-on] next to their name as displayed by copydist). Add-on products must be installed into the same directory as the Allegro CL product you installed. copydist requires the -e command line argument to allow the use of an existing directory. To install an add-on product you must supply the -e command line argument and specify the same directory you previously supplied to copydist to install Allegro CL.

    See the Add-On tables above for information about which products are automatically installed with each version of Allegro CL.

    Upgrading from one version of Allegro CL to another

    If you wish to upgrade from one version of Allegro CL (Allegro CL Personal or Allegro CL Professional) to another (Personal to Professional or Enterprise, or Professional to Enterprise), install the new version in a different directory (or remove the existing directory and then install the new version).


    Sample Installation Using copydist

    User input in the text below is shown in the bold Courier font.

    % ./copydist
    
    Please select your licensed product:
      1) ACL Enterprise Ed.
      2) ACL Professional Ed.
      3) Int'l ACL Enterprise Ed.
      4) Int'l ACL Professional Ed.
      5) Allegro CLIM [addon]
      6) Int'l Allegro CLIM [addon]
      7) Allegro Composer [addon]
      8) Allegro ODBC (v2) [addon]
      9) ACL Profiler [addon]
      10) Allegro ORBLink [addon]
      11) ACL Runtime [addon]
      12) ACL Dynamic Runtime [addon]
      13) ACL Source Code for Common Lisp [addon]
      14) ACL Source Code for Allegro ODBC [addon]
      15) ACL Source Code for CLIM [addon]
    Enter [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, or -1 to exit]: 1
    
    You have selected
     1) ACL Enterprise Ed..
    
    Is that correct [y or n]? y
    
    Please enter license key [EOF to exit]: <license key>
    
    Enter below the directory name where you want
    the licensed products to be installed.
    
    [If you are licensed to use the products over a network,
     you should enter the common directory name that will be
     used by all networked machines using this product.]
    
    Please enter directory name (an absolute pathname
    which must not already exist):
    > /usr/local/acl501
    Copying...  Please wait...
    .........................................
    Copy Complete!
    
    Please refer to the Installation and Release Notes
    for complete information about how to use the product
    you selected: ACL Enterprise Ed.
    
    ======================
    
    Would you like to install another product into this directory [n]? y
    
    Please select your licensed product:
      1) ACL Enterprise Ed.
      2) ACL Professional Ed.
      3) Int'l ACL Enterprise Ed.
      4) Int'l ACL Professional Ed.
      5) Allegro CLIM [addon]
      6) Int'l Allegro CLIM [addon]
      7) Allegro Composer [addon]
      8) Allegro ODBC (v2) [addon]
      9) ACL Profiler [addon]
      10) Allegro ORBLink [addon]
      11) ACL Runtime [addon]
      12) ACL Dynamic Runtime [addon]
      13) ACL Source Code for Common Lisp [addon]
      14) ACL Source Code for Allegro ODBC [addon]
      15) ACL Source Code for CLIM [addon]
    Enter [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, or -1 to exit]: 5
    
    You have selected
     5) Allegro CLIM [addon].
    
    Is that correct [y or n]? y
    
    Please enter license key [EOF to exit]: <another license key>
    Copying...  Please wait...
    .......
    Copy Complete!
    
    Please refer to the Installation and Release Notes
    for complete information about how to use the product
    you selected: Allegro CLIM [addon]
    
    ======================
    
    Would you like to install another product into this directory [n]? n
    0.28u 2.20s 3:28 1%; 0pf, 0sw, 384phy, st 2k, d 2k
    % /usr/local/acl501/lisp
    Allegro CL Enterprise Edition 5.0.1 [DEC Alpha] (6/19/99 21:25)
    Copyright (C) 1985-1999, 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): (exit)
    ; Exiting Lisp
    % 

    FTP Distribution on UNIX

    This option is not always available for each release; usually only pre-releases are available via FTP.

    Using the information provided to you regarding the file's location:

            % cd /tmp/acltmp
            % ...FTP the files from the location you were provided with...
            % chmod +x unzip   (required to make it executable)
            % cd /usr/local
            % /tmp/acltmp/unzip /tmp/acltmp/acl<version>.zip

    where /usr/local is replaced by the real installation directory and acl<version>.zip is replaced by the actual name of the file you retrieved via FTP. This unzip command creates a directory called acl<version>. /usr/local/acl<version> is the Allegro directory.

    Can I use my own version of unzip?

    If you already have unzip version 5.3.1 or later (with encryption built-in) you may use your version.

    | Contents | TopRelated Documents |


    Windows Installation

    Important:

    We strongly urge you to uninstall Allegro CL 5.0. There are known problems with installing later releases on top of earlier ones. See the Preinstallation section above.

    Depending on the method (CD-ROM or FTP) of distribution, choose a set of specific installation instructions from this section. Refer to the general notes following for details on both types of installations.

    Default Installation Location

    The default location for the installation is c:\Program Files\acl501. Hereafter, we will use <ACL directory> instead of c:\Program Files\acl501.   For Allegro CL Lite, the default is c:\Program Files\acl501Lite.

    Installation Prerequisites

    Installing on Both NT and 95 Platforms

    If you wish to install on both Windows 95 and NT, you will need to install once on each platform to get the Explorer extensions and Start menu items. Allegro CL will not function properly on both operating systems without doing the installation twice. If you choose the same installation options, then the same files will be installed each time setup.exe is run.

    Windows NT Users

    You must be a member of the Administrator group for setup.exe to properly add items to the Start Menu.

    Multiple Installations

    Install ACL on each computer where you intend to run it if you are licensed for running on more than one computer. We do not support a one-time installation on the network which runs from many machines.

    Updating the Explorer Icons and Start Menu

    After installation of the Allegro CL software, some icons and the Start menu items we add may not be updated in the Windows 95/NT 4.0 Explorer until you restart your computer. Restarting afterwards is a very good idea. Windows may not flash a banner requesting a restart after your installations, so don't rely on a prompt from the system to restart. Be sure to do it automatically after a base Lisp or an add-on installation.


    CD-ROM Distribution on Windows (non-Lite)

    Disk space requirements for each installation depends on the selection of add-on components.

    For the Intel version run windows\setup.exe from the root directory of the CD-ROM.  For the Alpha version run winaxp\setup.exe from the root directory of the CD-ROM.

    This walks you through the installation. On Windows 95, Windows 98, and NT 4.0, if you have not disabled the AutoPlay feature of CDs, then loading the CD-ROM automatically executes the Setup program. If you wish to browse the CD-ROM and have AutoPlay enabled, then you must right-click with the mouse on the CD-ROM in the Windows Explorer and select Open. Double-clicking selects the default action, which is AutoPlay. This causes setup.exe to run.

    Japanese versions of Windows 95

    The AutoPlay feature of CDs may not work; there might be an error message about fisetup.dll not loading properly. If it does not, run the Setup program from the CD-ROM, as <drive>:\windows\setup.exe.

    After running setup.exe, the first dialog displayed is:

    Image1.jpg

    Choose the particular product(s) you purchased by clicking the name. The default selected product is the Allegro CL Enterprise Edition.  Be sure to check the Add-on Products table above for information on which add-ons are included in each base Lisp product.  If an add-on is indicated as included in the base Lisp version you are installing, do not also check the product in the above dialog.   If it is not indicated as included, you must select it, along with the base Lisp version, for it to be installed.

    To Install the Professional Edition
    1. After possibly choosing a Destination Directory (using the Browse... button), un-select Allegro CL Enterprise Edition by clicking on its name. If you do not click it to un-select it, the installation won't work properly.
    2. Select Allegro CL Professional Edition by clicking on its name.

    Next you will be asked for the license key(s) for the products you are installing. Refer to your CD-ROM jewel case or to the literature sent with your purchase for this key. Enter the key in the blank window and click Next.  If you do not have a license key for your software, please contact us before proceeding.

    Image2.jpg

    If you are installing a base Lisp product, you will now be asked for the type of installation.

    With respect to Typical, Compact removed the following components: Help files, Integrated Development Environment and IDE Help files.

    Image3.jpg

    If you chose Custom in the last dialog, you will next be asked to choose the list of components you wish to install. Click Next > to proceed.

    Image4.jpg

    Click on the square boxes to the left to either select or un-select each component. Click on the name of any component to see text describing the component in the Description area of the dialog.

    Next, choose the folder you wish to use for the software. The default is a good choice here.

    Image5.jpg

    Clicking Next > at this point installs the software.

    Installing Windows Add-on in Windows

    If you wish to add products or components of the base Lisp product after installing Allegro CL, merely run setup.exe again. Nothing will be selected by default.   If you choose the Custom installation type, components you have already installed will be unchecked in the Select Components dialog. Leaving them unchecked will not remove these components. Each time you run setup.exe to install add-on products you will get a unique un-installation menu item on the Start menu, as well as an uninstall item in the Add/Remove Programs dialog in the Windows Control Panel.

    Upgrading from one version of Allegro CL to another

    If you wish to upgrade from one version of Allegro CL (Allegro CL Personal or Allegro CL Professional) to another (Personal to Professional or Enterprise, or Professional to Enterprise), first uninstall the current version and then install the new version.

    Uninstalling or Preparing to Re-Install?
    1. Uninstall the most recently installed products or components first, the ones for add-ons and added components to the base Lisp.
    2. Always uninstall your Alpha or Beta version of the software before installing the Final version.

    Your new installation may not work properly if you do not follow this procedure. See Uninstalling Allegro CL for details.


    CD-ROM Distribution on Windows (Lite)

    Disk space requirements for the Lite installation depends on the selection of components.

    Run windows\setup.exe from the root directory of the CD-ROM. This walks you through the installation. On Windows 95, Windows 98, and NT 4.0, if you have not disabled the AutoPlay feature of CDs, then loading the CD-ROM automatically executes the Setup program. If you wish to browse the CD-ROM and have AutoPlay enabled, then you must right-click with the mouse on the CD-ROM in the Windows Explorer and select Open. Double-clicking selects the default action, which is AutoPlay. This causes setup.exe to run.

    Japanese versions of Windows 95

    The AutoPlay feature of CDs may not work; there might be an error message about fisetup.dll not loading properly. If it does not, run the Setup program from the CD-ROM, as <drive>:\windows\setup.exe.

    The Lite version has fewer installation options than the non-Lite version.  Taking the defaults is a safe way to install.

    | Contents | TopRelated Documents |


    FTP Distribution on Windows (non-Lite)

    This option is no longer available.

    | Contents | TopRelated Documents |


    FTP Distribution on Windows (Lite)

    Allegro CL Lite is distributed on our FTP and Website as a self-extracting executable.   To install it just run it.  It will walk you through the installation.

    | Contents | TopRelated Documents |


    AllegroStore Installation

    OS Versions: AllegroStore does not work on Solaris 2.7 (on Sun/SPARCs) or IRIX versions other than 6.4 (on SGI's) even though Allegro CL does work on those OS versions.

    IMPORTANT NOTE when upgrading to AllegroStore 1.3, supplied with Allegro CL 5.0.1 (this warning is repeated in step 1):

    AllegroStore 1.3 database file format is not compatible with earlier AllegroStore version database files. If you wish to use databases created with earlier AllegroStore versions, you must convert them by:

    1. Before installing AllegroStore 1.3, dump the databases using the asdump module for the AllegroStore version that created the database.
    2. Install AllegroStore 1.3.
    3. Restore the dumped databases using the AllegroStore 1.3 asrestore module.

    There are five steps to installing AllegroStore 1.3.

    1. Install the AllegroStore add-on files from your distribution media
    2. Install ObjectStore
    3. Set up the individual Runtime environments
    4. Build an AllegroStore Lisp image [optional]
    5. Test the AllegroStore installation

    Step 1: Install the AllegroStore add-on files from your distribution media

    See the section on Installation for your particular platform (Unix or Windows) for more information; AllegroStore is installed as an add-on component.

    Warning (this repeats the warning at the beginning of the AllegroStore Installation instructions): AllegroStore 1.3 database file format is not compatible with earlier AllegroStore version database files. If you wish to use databases created with earlier AllegroStore versions, you must convert them by:

    1. Before installing AllegroStore 1.3, dump the databases using the asdump module for the AllegroStore version that created the database.
    2. Install AllegroStore 1.3.
    3. Restore the dumped databases using the AllegroStore 1.3 asrestore module.

    Step 2: Install ObjectStore

    Unix The supported operating system version levels are:
    • Solaris 2.5.1 and 2.6
    • HP-UX 10.20
    • SGI/IRIX 6.4 and 6.5

    Make sure the OS_ROOTDIR environmental variable is not set before beginning the installation. The installation procedure will print an error message telling you to un-set the OS_ROOTDIR variable if it is set when you begin the installation.

    The osinstal (one l) script starts the installation. You must be root to run this script.

    # cd <ACL directory>/astore/ostore
    # ./osinstal

    When the osinstal script ends, it instructs you what to do next. When running the osconfig step, calling osconfig with a server argument is recommended for most users.

    Windows Recall that the minimum-supported operating system version levels are:
    • Windows 95
    • Windows NT 4.0 (Intel processor only)

    Run <ACL directory>/astore/ostore/setup.exe to begin the installation. Most users will want to select the Online Runtime Client and Server installation option.

    On Windows 95/98, you may need to increase your environment space for MS-DOS.  Do this by adding the following line to your config.sys file on your boot drive:

    SHELL=C:\COMMAND.COM C:\ /E:2048 /P

    If you get "out of environment space" error when booting Windows 95, then you will need to add the above line.

    NOTE: on Windows 95/98, you will need to reboot after the ObjectStore installation (even though the ObjectStore installation process does not ask you to reboot).  This is because changes are made to your autoexec.bat file, which is only consulted during a full reboot of your computer.

    Step 3: Set up the individual Runtime environments

    Each user should update their environment appropriately for their use of AllegroStore. The environment variables in the following table are used by ObjectStore and you may wish to change them from their default value. Variables required for proper AllegroStore operation are noted in the following table; don't remove those.

    Variable Required? Description
    OS_ROOTDIR yes The value of this variable should be the name of the root directory of the ObjectStore installation. The value of this variable is set automatically on Windows by the ObjectStore installation.
    AS_CONFIG_PATH yes The value of this variable is the AllegroStore configuration directory, which is in all cases the same as the <Allegro directory>.
    PATH yes The value of this variable should include $AS_CONFIG_PATH and $OS_ROOTDIR/bin. The value of this variable is set automatically on Windows by the ObjectStore installation.
    OS_AS_START yes (SGI only) Specifies the starting address for the persistent virtual memory address space. The size of that space is controlled by the related OS_AS_SIZE variable. On SGI/IRIX, the default ObjectStore value (0x64000000) conflicts with the Lisp C heap. A value of 0x64100000 will not conflict with the Lisp C heap.
    OS_AS_SIZE no Specifies the maximum size of the persistent virtual memory address space.
    OS_16K_PAGE no On some SGI IRIX machines, ObjectStore will abnormally exit
    with an error message that looks similar to:

    ObjectStore internal error
    Fatal error Invalid argument(errno = 22)
    mmap failed: os_map_memory addr 0x74ee0000, len 0x1000, prot 3, fd 17, share 4 off 0x2000
    (err_internal)

    If you experience this problem, set OS_16K_PAGE to 1 (one), and try again.
    Operating System-Specific Configurations and Notes
    Solaris If the ObjectStore installation choice that creates links in /usr/lib was not selected, then the LD_LIBRARY_PATH environmental variable must include the ObjectStore lib subdirectory, $OS_ROOTDIR/lib, as well as /usr/lib and /usr/local/lib.
    HP-UX The SHLIB_PATH environmental path must include the <Allegro directory>, as well as /usr/lib. If the ObjectStore installation choice that creates links in /usr/lib was not selected, then it must also include the ObjectStore lib subdirectory, $OS_ROOTDIR/lib.

    See the ObjectStore installation readme.txt file for information about HP-UX patches recommended by ODI.

    SGI/IRIX If the ObjectStore installation choice that creates links in /usr/lib was not selected, then the LD_LIBRARY_PATH environmental variable must include the ObjectStore lib subdirectory, $OS_ROOTDIR/lib.
    Windows 95 & Windows 98 Add the AS_CONFIG_PATH variable setting statement to the Os_auto.bat file located in your boot disk's root directory.
    Windows NT Right-click on the My Computer desktop icon and choose Properties. On the Environment tab add AS_CONFIG_PATH.

    Step 4: Build an AllegroStore Lisp image [optional]

    UNIX Start Allegro CL with aslisp -I lisp.dxl on HP-UX and SGI/IRIX, and lisp on all other UNIX platforms.  aslisp is needed on HP-UX and SGI/IRIX to be able to load the AllegroStore shared library.  If you use lisp on HP-UX or SGI/IRIX, the load of this shared library will fail.  For International Allegro CL start ACL with aslispi -I lispi.dxl on HP-UX and SGI/IRIX and just lispi on all other UNIX platforms.
    Windows On Windows, start Allegro CL from the Start menu choosing a menu item that contains AllegroStore in it.  On Windows only, Lisp needs special command line arguments for AllegroStore to work properly.   See the command line in the shortcut for the AllegroStore menu items for details.   You can choose to use either the International or non-International versions to build your AllegroStore image.
    If you would like to build a Lisp image with AllegroStore pre-loaded, then evaluate the following form in Lisp:
    (build-lisp-image "<ACL directory>/astore.dxl"
                      :lisp-files '(:allegrostore))

    Step 5: Test the AllegroStore installation

    Start Lisp as you did in Step 4.   Then, evaluate the following forms:
    (require :allegrostore)
    (load "<ACL directory>/astore/verify.cl")
    On SGI/IRIX, if you see an error that looks like:

    ObjectStore internal error
    Fatal error Invalid argument(errno = 22)
    mmap failed: os_map_memory addr 0x74ee0000, len 0x1000, prot 3, fd 17, share 4 off 0x2000
    (err_internal)

    then you need to set the OS_16K_PAGE environmental variable, as detailed in Step 3.

     | Contents | TopRelated Documents |


    Allegro ODBC (v1) Installation

    To use Allegro ODBC you'll need each of the following components:

    aodbc.fasl The Lisp component of Allegro ODBC.
    aodbc.dll, aodbc.so, or adobc.sl The C component of Allegro ODBC.
    An ODBC Driver Manager Unix:  ODBC vendors such as Intersolv supply Driver Managers for you.
    Windows 95/98/NT: There is a Driver Manager supplied by Microsoft.
    An ODBC driver for your target database Often you can get the needed driver from the same vendor as the Driver Manager. Sometimes the database vendor will supply the ODBC driver.
    A Database Management System This part is optional, depending on your target database. Accessing databases from sophisticated DBMS's (such as Ingres, Oracle and Informix) will require that the ODBC driver communicate with the DBMS in question. For simple databases (such as a text database), the ODBC driver will do all of the work.
    Step 0: Install any needed operating system patches.
    On HP-UX, install patch PHSS_14262 obtained from HP. Patches are available to registered users at both the American/Asia-Pacific Electronic Support Center and the European Electronic Support Center. Registration is easy and takes very little time.
    AIX: you must be running at least AIX 4.2.1 and Intersolv DataDirect version 3.11 drivers for Allegro ODBC to operate properly.
    Step 1: Make sure you installed Allegro ODBC.  See the appropriate Installation section (depending on your Unix or Windows platform) for general instructions on doing an add-on installation.  Also, Allegro ODBC is included with some products automatically.   Refer to the Overview section above for more information.
    Step 2: Install the ODBC Driver Manager.
    Install the driver manager and drivers, using the instructions that came with that software.

    AIX: Intersolv DataDirect version 3.11 drivers are required for Allegro ODBC to operate properly.

    Step 3: Install additional drivers.
    If there are drivers you need to use in addition to those supplied with your Driver Manager, install those now. The file <ACL directory>/code/aodbc.so is linked with the Intersolv v3 ODBC drivers.
    Solaris 2 users: If you wish to use the Intersolv v2 ODBC drivers, then you must use <ACL directory>/code/v2-aodbc.so instead of the default .so provided. This means you must rename the original aodbc.so and copy v2-aodbc.so to aodbc.so.
    Step 4: Set up your environment to use the Driver Manager and drivers.
    Unix: You'll likely have to set some environment variables so that the Unix dynamic loader can find the Driver Manager and drivers. This should be explained in your third-party Driver Manager documentation.
    Windows: No work is usually required for this step.
    Step 5: Define the data sources you wish to access. You won't be able to access these until Step 6.
    ODBC saves the application from having to know which drivers are needed to access a database by having the application only deal with symbolic database names called data source names.
    Unix: The file ~/.odbc.ini is used to define the data sources. This will be documented in your third-party Driver Manager document.
    Windows: Data source names are defined via a sequence of dialog boxes found by double clicking on the ODBC icon in the Windows Control Panel (from the Start | Settings | Control Panel menu).
    Step 6: Test the Allegro ODBC installation. Now you can access the data sources you defined in Step 5.
    Start up Lisp and evaluate (require :aodbc)

    Then evaluate: (dbi:connect :data-source-name "mydatasourcename")

    where "mydatasourcename" is replaced by the data source name you set up in Step 5. This returns a non-nil value once you've correctly set up all the ODBC components.

    | Contents | TopRelated Documents |


    Installation of GNU Emacs and XEmacs

    Obtaining GNU Emacs for Windows

    1. from the CD-ROM in the directory \emacs\emacs20.zip.
      If you received Allegro CL on a CD-ROM, see the Zip File Note first.

    2. via FTP from ftp://ftp.franz.com/pub/emacs/gnu-emacs/windows-binaries/emacs-20.3.1.zip, or

    3. from http://www.cs.washington.edu/homes/voelker/ntemacs.html.

    Zip File Note: We provide zip files with long filenames, so you'll need to use an Unzip program that can handle them. If you don't already have an Unzip program that handles long filenames, see http://www.winzip.com, for one possible software solution. This software has restrictions, so please follow them.

    If you install from one of the above zip files, then you will need to extract the emacs-20.3.1 directory from the zip file.

    Obtaining GNU Emacs for UNIX

    Information on downloading GNU software via FTP is available at: ftp://prep.ai.mit.edu/pub/gnu/GNUInfo/FTP. The files themselves are available at /pub/gnu.   Since we do not distribute GNU Emacs binaries or source for UNIX, you will need to FTP, build and install GNU Emacs yourself.

    Obtaining XEmacs for UNIX

    The binaries for XEmacs 20.x are in the /xemacs directory on the root of the UNIX CD-ROM.  See the README files in that directory for help on installation.

    NOTE for AIX 4.3 users: the XEmacs binaries on the UNIX CD-ROM will work on AIX 4.2 but not on later operating systems (AIX 4.3 and 4.3.1).  Users of AIX 4.3 and later can get GNU Emacs (not XEmacs) binaries from our ftp site at ftp://ftp.franz.com/pub/emacs/gnu-emacs/aix4_3emacs20_3.tar.gz. Instructions for installation are at ftp://ftp.franz.com/pub/emacs/gnu-emacs/aix4_3emacs20_3.txt.

    NOTE for FreeBSD XEmacs users: if you use the binaries on the CD-ROM, you may see a message like the following when you run the xemacs binary:

    Absurd new brk addr = 0x328000 (current = 0x37a000)

    This message can be (in our opinion) safely ignored.

    Installation of GNU Emacs on Windows

    Once you have copied the GNU Emacs directory to your computer, execute the following command to set up the shortcuts on the Start Menu and to add the registry entries needed by GNU Emacs.

    If you copied it to c:/, then execute this command:

    c:\emacs-20.3.1\bin\addpm

    If you copied it to d:/, then execute this command:

    d:\emacs-20.3.1\bin\addpm

    Windows NT Users:

    You must be a member of the Administrators group for addpm to properly add items to the Start Menu.

    Run addpm.exe on Every System

    You will need to execute the above command on each operating system you use (Windows NT and 95) for GNU Emacs to work on each operating system. GNU Emacs will not work without executing addpm.exe, since GNU Emacs relies on the changes addpm.exe makes in the registry.

    Upgrade if your Emacs is 19.34.5 or Earlier

    If you already have GNU Emacs 19.34.6 or later, it will work fine with the Emacs-Lisp interface. If you have an earlier version of GNU Emacs, upgrade to the newest version before trying to use the Emacs-Lisp interface. We made and submitted one change that causes the Emacs-Lisp function start-process to allow the window created by the process it starts to be visible. This is particularly useful when the Emacs-Lisp interface is used to start ACL; without this change, the ACL Console window is hidden.

    Emacs Source Code Available

    See the Obtaining... sections above for FTP location where you can obtain source code.

    | Contents | TopRelated Documents |


    Installation and Use of the Emacs-Lisp Interface

    NOTE: on Windows, the Emacs-Lisp interface is part of Enterprise and Professional only.

    The Emacs-Lisp interface is installed as part of the Allegro CL Enterprise and Professional Editions, described installed above, into <ACL directory>/eli.   On UNIX, a second directory is installed, <ACL directory>/xeli.   The latter is for use with XEmacs.

    Using the Interface

    1. Put the following forms either in c:\.emacs on Windows or in ~/.emacs on Unix. GNU Emacs loads .emacs in c:\ upon startup, no matter where GNU Emacs or Allegro CL were installed.  <eli> is either eli or xeli, depending on if you are using GNU Emacs or XEmacs 20.
          (load "<ACL directory>/<eli>/fi-site-init")
           (setq fi:common-lisp-image-name "<ACL directory>/lisp")
    2. Use the Emacs command M-x fi:common-lisp to start Common Lisp within Emacs and to establish the connection between Emacs and Allegro CL.

      If you want to call fi:common-lisp from an Emacs-Lisp program, it takes the following (all-optional) arguments:

      buffer-name
      directory
      executable-image-name
      image-args
      host
      , and
      lisp-image-file (new from ACL 4.3)

      For example:

           (fi:common-lisp "*common-lisp*" "<ACL directory>/"
                           "<ACL directory>/lisp")

      In the above forms, just replace <ACL directory> with the actual path for your installation.

    | Contents | TopRelated Documents |


    Installation of Patches

    There are several kinds of patches for Allegro CL:
    • Standard patch files. These have names like p0a003.002 (always p<something>.<number>). Put these patch files into the <ACL directory>/update/ directory.
    • fasl patch files. These have names like hash.fasl (always <something>.fasl). Put these patch files into the <ACL directory>/code/ directory. Doing so may overwrite files already there. This is what is intended, but copy <ACL directory>/code/ to, say, <ACL directory>/code-old/ , creating that directory if necessary, before installing the fasl-file patches if you wish.   
    • Patched libraries. A new libaclNNN.so on most Unix machines (e.g. libacl503.so), libaclNNN.sl on HP's, aclNNN.dll on Windows may be supplied. This goes in the <ACL directory> and will overwrite the corresponding file in that directory. Copy the current file to <name>.orig before installing the new one.

    See the discussion of patches in introduction.htm.

    Unix
    (non-trial)
    Run <ACL directory>/update.sh.
    Unix
    (trial)
    Patches are loaded when Trial starts up.
    Windows
    (non-Lite)
    Run <ACL directory>/update.bat.

    The above scripts will rebuild all the .dxls in the Allegro directory to include all available patches, so you should be careful not to store spurious images in the Allegro directory.  See the discussion of patches in introduction.htm.

    Windows
    (Lite)
    Patches are loaded when Lite starts up.

    | Contents | TopRelated Documents |


    Uninstalling Allegro CL

    Unix Remove the directory you created in the Installation step.
    Windows Run Start | Programs | Allegro CL 5.0.1 | Uninstall to uninstall ACL. This removes all the files originally installed by the installation program and removes the items added to the Windows registry by the installation. You may need to remove the Allegro directory if you created files in that directory after installation. Always check to see if any files exist after an uninstall and remove them. This prevents potential problems if you reinstall Allegro CL into the same location.

    If add-ons were installed separately from Allegro CL, then uninstall them first.

    Note: if you install the Allegro CL Enterprise Edition with Allegro CL Dynamic Runtime add-on product, and then you uninstall the Allegro CL Dynamic Runtime, you will also uninstall Allegro CL Runtime (which is included with both the Allegro CL Enterprise Edition and Allegro CL Dynamic Runtime).

    Note about files that are not deleted: when uninstalling Allegro CL, the system may display a dialog at the end of the process saying that some files could not be removed. These files are typically in the Allegro directory (the default location is something like C:\Program Files\acl501). If this happens, do the following after the uninstall program completes: (1) remove any unneeded files from the Allegro directory (they are typically user-created, i.e. not part of the distribution); (2) copy any desired files elsewhere; and (3) then remove the Allegro directory.

    | Contents | TopRelated Documents |


    Post-Installation

    Allegro CL

    On Windows, Start menu shortcuts that contain the phrase lisp only do not contain the Integrated Development Environment.  You can load the IDE into such images by doing (require :ide), and you can start the IDE by evaluating (cg:start-ide).

    HP-UX 11.0 requires use of different versions of lisp.exe and the ACL shared library (libaclclNNN.sl, where NNN is some number).  These new files can be found in the hpux11/ subdirectory of your Allegro CL directory. Merely replace the files of the same name in your Allegro CL directory with the ones from hpux11/ if you are running on HP-UX 11.0. See also the platform-specific information on HP's in the Release Notes.

    Linux Redhat 4: in order that foreign loading and the foreign function interface work properly, you should now install an updated ld.so on your Redhat 4 system.  On the CD-ROM in the directory redhat4/ there are two files:

    You can unpack and build the new ld.so like this:

    cd /usr/src
    tar zxf <...>/ld.so-1.9.2.tar.gz
    cd ld.so-1.9.2.tar.gz
    patch -N < <...>/ld.so-1.9.2.diffs
    make

    You will need to be root to install the new ld.so.  Please follow the instructions in the ld.so README for more information.

    MkLinux/LinuxPPC: in order that foreign loading and the foreign function interface work properly, you should now install an updated ld.so on your MkLinux/LinuxPPC system.  See the README-ld.so file on the CD-ROM in the directory linuxppc/ for more information.

    Allegro CL Lite [Windows only]

    The Lite version of Allegro CL is different than the non-Lite versions of Allegro CL in the following ways:

    However, the Lite version does contain the following features:

    Additionally, the following items should be noted about Lite:

    Allegro ODBC (v2)

    If you install Allegro ODBC version 2, then you can load it with the following form:

    (require :aodbc-v2)

    For more information see doc/cl/aodbc_v2.htm.

    Allegro Composer

    Allegro Composer is only available on Unix platforms.

    You can start Allegro CL with Allegro Composer by running the executable <Allegro directory>/composer, or <Allegro directory>/composeri if you are using an International version of Allegro CL. As is discussed in Running Allegro CL 5.0.1, running the composer binary will load composer.dxl, which is in the Allegro directory. See Allegro CL Startup for more information on starting and running Allegro CL.

    Allegro Composer is intended to be used with GNU Emacs; we recommend that you use the version which comes with Allegro CL 5.0.1. When you start Emacs and load the Emacs-Lisp interface, there will be a Composer menu, and a Start Composer item on that menu. Choose this menu item to start Allegro Composer.

    See the section above for information on installing Emacs.

    CLIM

    There are no pre-built CLIM images.  You can either:

    1. make an image containing CLIM by loading <ACL directory>/buildclim.cl, or
    2. load CLIM into a running Lisp image by evaluating (require :climxm) on UNIX or (require :climnt) on Windows.

    Refer to the printed CLIM User Guide, the printed Release Notes for CLIM 2.2 on Allegro CL 5.0.1, and CLIM on Allegro CL 5.0.1 in the online Release Notes (doc\cl\release_notes.htm) for information on using CLIM.

    CLIM on Windows

    CLIM on Windows can only be used in a case insensitive Lisp.  We hope to remove this restriction in a future release.

    CLIM on Linux

    CLIM on Linux is only supported with the Metro Link Motif (v. 1.2.4) software on Redhat 4.x and 5.x/6.x. See the Metro Link web site, http://www.metrolink.com, for details on Motif.

    Allegro ORBLink

    For further installation instructions on ORBLink, please see the Installation section of orblink/doc/index.htm.

    Source Code: Common Lisp

    When you install this product the resulting source code files can be found in <ACL directory>/src/cl.

    Source Code: Common Graphics and the IDE

    When you install this product the resulting source code files can be found in <ACL directory>/src/cg. Please refer to the file <ACL directory>/src/cg/loadsfi.cl in this directory for more information about using these files.

    Source Code: CLIM

    When you install this product the resulting source code files can be found in <ACL directory>/src/clim.

    Source Code: Allegro ODBC

    When you install this product the resulting source code files can be found in <ACL directory>/src/aodbc.

    C/C++ Binder tool

    Now available is a tool that facilitates the building of interfaces between Allegro CL and foreign libraries written in C and C++. The interface to libraries is typically defined by one or more header files.

    The C Binder tool scans C header files and generates the appropriate Lisp code necessary to use the facilities defined in the header file. This normally consists of:

    The C++ Binder is a tool that performs the same task for C++ header files. In the C++ case, we generate many more C function wrappers in order to deal with overloaded functions correctly.

    In a few cases, it is not possible to generate the correct interface automatically. In these cases we try to generate appropriate warning messages.

    The Binder tools are located on the CD-ROM in the cbind/ directory in the root of the CD-ROM. There are subdirectories for the supported platforms (among the platforms on the CD-ROM). The following files in each subdirectory provide more information:

    The Emacs-Lisp Interface and the IDE [Windows only]

    On Windows, there is a bad interaction between the Integrated Development Environment (IDE) and the Emacs-Lisp interface.  When running Lisp connected to Emacs, a run bar is displayed in the mode line of Emacs.  This run bar shows the status of Lisp, whether or not it is idle, running or doing a garbage collection.  When the Lisp connected to Emacs is running the IDE, the run bar may flicker quite rapidly.   To turn off the run bar, put the following form in your .emacs file, just after the loading of fi-site-init:

    (setq fi:start-lisp-interface-hook
      (delete 'fi:show-run-status fi:start-lisp-interface-hook))

    | Contents | TopRelated Documents |


    Links to Related Documents

    An Overview of the Allegro CL documentation
    Release Notes
    ANSI Common Lisp Specification

    | Contents | Top |