This document has Franz Inc. document number D-IR-00-CL-50-80427-1-0. Copyright © 1998 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 better when viewed with Netscape 4.0 or later.
The text version of this document shows the text rendering of links in the HTML document but they are (obviously) not active. The HTML version of the document is much easier to use and understand.
NOTE: This documentation supercedes all other Allegro CL documentation--pre-existing documentation for items documented here should be considered obsolete. Any items not documented here can be assumed not to have changed and existing documentation should be used.
Information specific to Microsoft Windows (95/NT) users
- lisp.exe
- The Integrated Development Environment (IDE)
- build.exe
- Pathnames on Windows
- Differences when running on Windows 95 and NT
Differences between the UNIX and Windows versions of Allegro CL
Changes from Allegro CL 4.3.2 to Allegro CL 5.0
- The foreign function interface
- Changes to malloc and free in Allegro CL 5.0
- Windows specific changes
- UNIX specific changes
Delivering application written in Allegro CL
Information specific to users of Allegro CL for Windows 3.0.x
Lisp as a subroutine [Windows only]
The ANSI Common Lisp specification (this link will work only if you have installed the Help files component)
Supplemental documentation for the IDE and Common Graphics (this link will work only if you have installed the IDE Help files component)
A discussion of case sensitivity issues
This document covers the installation of Allegro CL and Allegro CL add-on products. Specifically, the following products:
The platforms for the above versions of Allegro CL are:
and the following add-on products, with notes about platform availability (no discussion of availability means on all Allegro CL platforms):
Both Allegro CL Professional Edition and International Allegro CL Professional Edition contain the following add-on product:
Note to Windows users: because the Emacs-Lisp interface uses the Allegro CL Socket Library, the Emacs-Lisp interface is not available in the Student and Personal editions.
Both Allegro CL Enterprise Edition and International Allegro CL Enterprise Edition contain the following add-on products, as well as the add-ons for the Professional editions:
The Enterprise editions also contain a (graphical and non-graphical) statistical profiler not found in other versions of Allegro CL.
While both the Enterprise and Professional editions contain the Source Code: Common Lisp add-on, you must sign a legal document in order to get the license key for this add-on product.
On Windows, all the Allegro CL products contain Common Graphics (CG) and the CG-based Integrated Development Environment (IDE).
This document will use <ACL directory> to mean the place you installed Allegro CL. This is also referred to as the Allegro directory.
Choose one of the two sections below, depending on how you received Allegro CL.
When you have completed the correct section below, you can execute Lisp by running <ACL directory>/lisp.
See Running Allegro CL 5.0 below for more information on executing Allegro CL.
The Linux release, if available, will be in the linux subdirectory on the CD-ROM. See the README file in that directory for installation instructions.
The Allegro CL distribution on a CD-ROM includes several subdirectories corresponding to platform names onto which Allegro CL can be installed. If your distribution CD-ROM does not contain a subdirectory corresponding to your desired platform, please contact us before proceeding.
In order to install Allegro CL on your desired platform, you need a license key from Franz Inc. A license key is a string of letters and digits that are used by the copydist program described below. Normally, this license key will be written on labels included in your package or otherwise made available to you. If you do not have this license key, please contact us before proceeding.
The installation procedure consists of one step, copying the distribution files to your computer's disks.
Each platform subdirectory on this CD-ROM has its own version of the copydist program. Below in this section are the instructions on where to find the appropriate copydist on the CD-ROM.
When invoked, copydist asks you for the following:
After entering answers to the above questions, copydist will create 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 in the following table:
| Machine and operating system | directory |
|---|---|
| Sun Solaris 2.4 or later | sol24 |
| SGI/Irix 6.2 or later | irix62 |
| HP-UX 10.20 | hpux1020 |
| DEC Alpha/Digital UNIX 4.0 | alphadu4 |
| IBM RS6000/AIX 4.2 | aix42 |
There are two types of products you can install with copydist: base Lisp products and add-on products (the latter 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.
Remember that with the Enterprise edition, the following add-on products are automatically installed:
and with the Professional edition the following is automatically installed:
Example installation using copydist:% ./copydist Please select your licensed product: 1) Allegro CL Professional Edition 2) International Allegro CL Professional Edition 3) Allegro CL Enterprise Edition 4) International Allegro CL Enterprise Edition 5) Allegro Composer [addon] 6) CLIM [addon] 7) Allegro CL Runtime [addon] 8) Allegro CL Dynamic Runtime [addon] 9) Source Code: Common Lisp [addon] 10) Source Code: CLIM [addon] Enter [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, or -1 to exit]: 3 You have selected 3) Allegro CL Enterprise Edition. Is that correct [yn]? y Please enter serial number: serial# 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/acl50 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 CL Enterprise Edition % ./copydist -e Please select your licensed product: 1) Allegro CL Professional Edition 2) International Allegro CL Professional Edition 3) Allegro CL Enterprise Edition 4) International Allegro CL Enterprise Edition 5) Allegro Composer [addon] 6) CLIM [addon] 7) Allegro CL Runtime [addon] 8) Allegro CL Dynamic Runtime [addon] 9) Source Code: Common Lisp [addon] 10) Source Code: CLIM [addon] Enter [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, or -1 to exit]: 6 You have selected 6) CLIM [addon]. Is that correct [yn]? y Please enter serial number: serial# 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 may already exist): > /usr/acl50 Copying... Please wait... ........ Copy Complete! Please refer to the Installation and Release Notes for complete information about how to use the product you selected: CLIM [addon] % cd /usr/acl50 % ls acl50b3.epll* composer.dxl doc/ libacl50b3.so readme.txt bin/ composere.pll eli/ lisp* src/ buildclim.cl contrib/ examples/ lisp.dxl update/ code/ custom.cl files.ebu misc/ update.cl composer@ develenv.cl hosts.cl readme.htm* update.sh* % ./lisp Loading /usr/acl50/libacl50b3.so. Mapping /usr/acl50/lisp.dxl...done. Mapping acl50b3.epll. Allegro CL Enterprise Edition 5.0.beta [DEC Alpha] (4/24/98 9:12) Copyright (C) 1985-1998, 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) % |
[This option is not always available.]
Using the information provided to you on where the files are located:
% cd /tmp/acltmp
% ...ftp the files...
% chmod +x unzip (required to make it executable)
% cd /usr/local
% /tmp/acltmp/unzip /tmp/acltmp/acl50pbxx.zip
where /usr/local is replaced by the real installation directory and acl50pbxx.zip is replaced by the actual name of the file you retrieved via ftp. This unzip command will create a directory called acl50pbxx. /usr/local/acl50pbxx is the Allegro directory.
NOTE: if you already have unzip version 5.3.1 or later, with encryption built-in, you may use your version.
We strongly urge you to uninstall any previous pre-release of Allegro CL 5.0. There are known problems with installing later releases over earlier ones. To uninstall use run Start -> Settings -> Control Panel -> Add/Remove Programs. If you simply delete the previously installed directory you will still have problems installing the newer release.
The pre-requisites for installing this software are:
Depending on the method of distribution, choose one of the following two sections for specific installation instructions.
You must install ACL on each computer you intend to run it, assuming that you are licensed for running on more than one computer. We do not support the install on the network once and run from many machines type of installation.
After installation of Allegro CL, some icons might not be updated in the Windows 95/NT 4.0 explorer until you reboot your machine.
The default location for the installation is c:\Program Files\ACL50. Hereafter, we will use <ACL directory> instead of c:\Program Files\ACL50.
Users who wish to install on both Windows 95 and NT will need to install twice to get the explorer extensions and Start menu items. Allegro CL might not function properly on both operating systems without doing the installation twice. If you choose the same installation options, then the same files are installed both times setup.exe is run.
NOTE: on Windows NT, we recommend that the user that installs the software be a member of the administrator group.
The disk space requirements depend on the chosen options.
Run windows\setup.exe from the root directory of the CD-ROM. This will walk you through the installation. On Windows 95 and NT 4.0, if you have not disabled the AutoPlay feature of CDs, then loading the CD-ROM will automatically execute 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 with the mouse will select the default action, which is AutoPlay, which will cause setup.exe to be run.
NOTE: on 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 you will see is:
Choose the particular product or products that you purchased. The default selected products is for Allegro CL Enterprise Edition. Remember that with Allegro CL Enterprise Edition the add-on products Allegro ODBC, Allegro CL Socket Library and Allegro CL Runtime will automatically be installed.
If you want to install Allegro CL Professional Edition, then select it instead of Allegro CL Enterprise Edition. Remember that with Allegro CL Professional Edition the add-on product Allegro CL Socket Library will automatically be installed.
You may select multiple products in this dialog. If you do, they will all be installed at the same time and you will get one uninstallation entry in your registry.
Add-on products must be installed with or after a base Lisp product (any product without [addon] in its name).
Next, you will be asked for the license key for the products you are installing:
Next, if you are installing a base Lisp product, you will be asked for the type of installation. Typical chooses options good for most users. If you want to see those options, choose Custom. Compact is for a minimal installation on computers with limited disk space. With respect to Typical, Compact removes the following components (see the Select Components dialog below): Help files, Integrated Development Environment and IDE Help files.
If you chose Custom in the above dialog, you will next be asked to choose the list of components you wish to install:
If you click on the square box on the left, it will select or unselect the component. If you click on the name of the component, you will see text describing the component in the Description area of the dialog.
Next, choose the program folder you wish to use. The default is a good choice here.
At this point, choosing Next> will install the software.
If you wish to add components after installing Allegro CL, merely run setup.exe again. The defaults for Allegro CL will be the components you have not installed. 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 you get a unique uninstallation set in the Add/Remove Programs in the Windows Control Panel. When installing this software, it is best to uninstall the most recently installed products first (the installation sets are numbered sequentially).
[This option is not always available.]
Retrieve the self-extracting executable file via ftp. When you run this executable on the Windows machine on which you want to install Allegro CL, it will automatically extract the installation files and run the installation program. There are few options for which your input is needed in this mode of distribution.
See the previous section for information on the installation of the AllegroStore files.
Recall that the minimum supported operating system version levels are:
- Solaris 2.5.1
- HP-UX 10.20
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 unset 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 # ./osinstalWhen the osinstal script ends, it will instruct you what to do next. When running the osconfig step, calling osconfig with a server argument is recommended for most users.
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.
Each AllegroStore 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. Any variable required for proper AllegroStore operation is so noted.
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 no 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. OS_AS_SIZE no Specifies the maximum size of the persistent virtual memory address space.
Additional operating system specific configuration and notes:
If the ObjectStore installation choice that creates links in /usr/lib was not selected, then the LD_LIBRARY_PATH environental variable must include the ObjectStore lib subdirectory, $OS_ROOTDIR/lib, as well as /usr/lib and /usr/local/lib.
The SHLIB_PATH environemental 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 that ODI recommends.
Add the AS_CONFIG_PATH variable setting statement to the Os_auto.bat file you will find in your boot disk's root directory.
Right click on the My Computer desktop icon and choose Properties. On the Environment tab add AS_CONFIG_PATH.
If you would like to build a Lisp image with AllegroStore pre-loaded, then evaluate the following forms in Lisp:
(build-lisp-image "<ACL directory>/astore.dxl" :lisp-files '(:allegrostore))
Start Allegro CL:
lispThen, evaluate the following forms:
(require :allegrostore) (load "<ACL directory>/astore/verify.cl")
In order to use Allegro ODBC you'll need the following components:
On HP-UX, install patch PHSS_14262 obtained from HP.
See the previous section for information on the installation of the Allegro ODBC files.
Install the ODBC driver manager and drivers, using the instructions that come with that software.
If you've obtained drivers you need to use in addition to those supplied with the driver manager, install those now.
The file <ACL directory>/code/aodbc.so is linked with the Intersolv v3 ODBC drivers.
Note for 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.
On Windows no work is usually required for this step.
On UNIX you'll likely have to set some envionrment variables so that the UNIX dynamic loader can find the driver manager and drivers. This should be explained in the driver manager documentation.
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.
On 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).
On UNIX the file ~/.odbc.ini is used to define the data sources. This is documented in the Driver Manager document.
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" in replaced by the data source name you set up in step 5. If this returns a non-nil value then you've correctly setup all the ODBC components.
The binaries for XEmacs 20.x are in the /xemacs directory on the root of the CD-ROM. See the README files in that directory for help on installation.
The disk space requirements for GNU Emacs are in the Installation section above.
If you need GNU Emacs for Windows NT or 95, you can get it from:
Note: the zip files above contain long filenames, so you need an unzip program that can handle them. If you need an unzip program that handles long filenames, see http://www.winzip.com, for example. 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-19.34 directory from the zip file.
Once you have copied the GNU Emacs directory to your computer, execute the following command to setup the shortcuts on the Start Menu and the registry entries needed by GNU Emacs. If you copied it to c:\, then you would execute this command:
c:\emacs-19.34\bin\addpm
If you copied it to d:\, then you would use this command:
d:\emacs-19.34\bin\addpm
Note: on Windows NT, you must be a member of the Administrators group for addpm to properly add items to the Start Menu.
Important: 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.
The source code from which the binary distribution of GNU Emacs you just installed can be obtained from the web site listed above.
If you already have GNU Emacs 19.34.6 or later, that you obtained from somewhere else, it will work fine with the Emacs-Lisp interface. However, if you have an earlier version of GNU Emacs, you should upgrade to the newest version. 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.
The Emacs-Lisp interface is installed as part of the Allegro CL installed above, in <ACL directory>/eli.
To use the interface, put the following forms in your c:\.emacs (GNU Emacs loads .emacs in c:\ upon startup, no matter where your emacs-19.34 or Allegro directories were installed) or ~/.emacs, for Windows and UNIX respectively:
(load "<ACL directory>/eli/fi-site-init") (setq fi:common-lisp-image-name "<ACL directory>/lisp")
and then use M-x fi:common-lisp to start ACL and the connection between Emacs and ACL.
If you want to call fi:common-lisp from an Emacs-Lisp program, it takes arguments (all optional) buffer-name, directory, executable-image-name, image-args, host, and lisp-image-file. The last argument is 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.
If you are using XEmacs 20 you will need to byte recompile the .el files in the eli/ directory:
% cd <ACL directory>/eli % make clean % make emacs=xemacs
You will get some warnings from the compilation of the .el files. You can safely ignore these warnings. If you are on Windows, you will need GNU Make for the above to work properly.
To use patches that you receive from Franz Inc., put the .fasl files into the <ACL directory>/update/ directory.
Change your directory to <ACL directory> and run update.sh.
In a DOS command prompt window, change your directory to <ACL directory> and run update.bat.
The above scripts will rebuild all the .dxls in the Allegro directory to include all available patches.
Uninstalling in the suggested way will remove all the files originally installed by the installation program and remove the Windows registry items added by the installation. If you just delete the files installed by setup.exe, then you will not completely remove Allegro CL.
If you installed only once, then run Start -> Programs -> Allegro CL 5.0 -> uninstall.
If you installed multiple times, perhaps to add components after the initial installation, run Start | Settings | Control Panel | Add/Remove Programs and select the Allegro CL 5.0 items for removal in the reverse order that you did the original installations. That is, uninstall the most recently installed items first. The order should be apparent from the names of the items in the dialog box.
After uninstallation, you may need to remove the Allegro directory if you created files in that directory after installation. In any case, it is a good idea to check that the directory has been removed by the uninstall process, and if it has not to remove it yourself. This will prevent potential problems if you reinstall Allegro CL into the same location in the future.
Just remove the directory created by copydist.
The basic model in which Lisp is constructed has changed. Previously, on UNIX systems, Lisp was a single executable and the function dumplisp created executables. Now, Lisp has been split into at least three components:
The executable file is a program, and this is what you run. On UNIX it is called lisp and on Windows it is called lisp.exe. This program is static, meaning it never changes (unless you were to get a patched version from us). The image file contains Lisp data, including the Lisp heap. The shared library contains the operating system interface and initialization routines needed to run Lisp. It is a shared library in the operating system sense.
All of these components reside, by default, in the same directory. This location is called the home location. (The home location can be overridden by the -H command line argument.)
There is a new command line argument, -I, that is used to specify an image file other than the default. The argument after -I on the command line is the file to use as the image. This file must have been created with the function excl:dumplisp. See Building custom Lisp images for information on building Lisp images.
When run, lisp performs the following tasks:
lisp will print verbose messages about what it is doing on startup if the environment variable ACL_STARTUP_DEBUG is present.
On UNIX, the LD_LIBRARY_PATH environment variable (and similarly named variables on various UNIX systems) is not used when loading the ACL shared library. On Windows, the ACL shared library is in the Windows system directory.
If the -I argument to lisp is not given, then the following heuristic is used to find an image file to load:
If the -I argument to lisp is given, then the following heuristic is used to find an image file to load (for the purposes of this example, the name of the -I companion argument is imagefile):
For example, if (on Unix) lisp is copied to myapp or (on Windows) lisp.exe is copied to myapp.exe, and you then create a myapp.dxl in the same directory as the executable, then myapp is equivalent to myapp -I myapp.
On Windows 95/ NT 4.0, you can also run Allegro CL from the Start -> Programs -> Allegro CL 5.0 menu.
If Lisp was built with a .pll file, then the same search rules above for finding a supplied image file apply to finding the .pll file. On Windows, the Windows system directory is also searched (system on Windows 95 and system32 on Windows NT).
Lisp code can be conditionalized on a platform basis by using the following features:
| hardware/software | features |
|---|---|
| DEC Alpha/Digitial UNIX 4.0 | :alpha and :digitial-unix |
| HP PA/HP-UX | :hpprism, :hpux and :hpux-10 |
| SGI MIPS/IRIX | :sgi, :mips, :irix6, :irix64 (on 64-bit machines) and :n32 |
| Microsoft Windows on the Intel processor | :x86 and :mswindows |
| IBM RS 6000/AIX | :rs6000, :aix and :aix-4-2 |
| Sun SPARC/Solaris | :sparc, :sun, :sun4 and :solaris2 |
The information in this section is for advanced users with very large applications. Most users can skip this section, until the need for a larger heap than can be obtained with the default settings is needed.
The address into which the heap is loaded is architecture dependent. It is potentially important for you to know this, in case you use the operating system primitives for memory mapping or want to move the heap from the default location in memory.
| Architecture/OS | Lisp heap start | C heap start |
| Sparc/Solaris 2.4 | 0x8000000 | 0x5000000 |
| MIPS 3 & 4/IRIX 6.2 | 0x30000000 | 0x64000000 |
| Intel Linux 2.0 | 0x20000000 | 0x64000000 |
| Windows 95 & NT (Intel) | 0x20000000 | 0x54000000 |
| DEC Alpha/DU 4.0 | 0x30000000 | 0x54000000 |
| RS6000/AIX 4.2 | 0x30000000 | 0x64000000 |
| HP/HPUX 10.20 | 0x20000000 | 0x64000000 |
To change the above values, see the section below on command line arguments for heap size and placement, in section Changes from Allegro CL 4.3 to Allegro CL 4.3.2.
You can start Allegro Composer by running <ACL directory>/composer, or <ACL directory>/composeri if you are using an International version of Allegro CL. As is discussed in the section Running Allegro CL 5.0, running the composer binary will load composer.dxl, which is in the Allegro directory. Allegro Composer is intended to be used with GNU Emacs--we recommend that you use the version which comes with Allegro CL 5.0. 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.
There are no pre-built CLIM images. You can build one by loading <ACL directory>/buildclim.cl. Alternatively, you can load CLIM into a running Lisp image by evaluating (require :climxm). Refer to the CLIM User Guide for information on using CLIM.
When you install this product the resulting source code files can be found in <ACL directory>/src/cl.
When you install this product the resulting source code files can be found in <ACL directory>/src/cg.
When you install this product the resulting source code files can be found in <ACL directory>/src/clim.