Introduction to Allegro CL Documentation

$Revision: 5.0.2.19 $

The index for the Allegro CL documentation is in index.htm.

1.0 Documentation introduction
    1.2 Some notation
2.0 The Overview section
    2.1 Contents of Allegro CL documentation (to go directly to contents.htm, click here)
    2.2 List of HTML overview documents
3.0 The Reference section
4.0 Assistance available on the internet and the World Wide Web
    4.1 The Allegro CL FAQ
    4.2 Patches
    4.3 Further information
    4.4 Should you get all patches?
5.0 Reporting bugs
    5.1 Where to report bugs and send questions
6.0 Common Graphics and Integrated Development Environment documentation [Windows only]

1.0 Documentation introduction

The documentation for Allegro CL 5.0.1 is for the most part been put online. It is arranged into an Overviews section and a Reference section.

There is an index to Allegro CL documentation in index.htm. The contents of the overview documents is in contents.htm.

Installation information can be found in <Allegro directory>/readme.htm.

The User Guide for the Emacs-Lisp interface is in ../../eli/readme.htm. See startup.htm#6.0 Running Lisp as a subprocess of Emacs for information on connecting Emacs to Allegro CL.

The documentation for Common Graphics and the Integrated Development Environment is described below in this document.

The documentation for Common Graphics (a window system available with Allegro CL 5.0.1 on Windows 95/98 and NT) and for the Integrated Development Environment is separate. The best entry point is the cgide.hlp Windows help file. When using the IDE, you can bring up that file by clicking Common Graphics Index on the Help menu. The Introduction entry describes CG and IDE documentation. See below in this document for more information on documentation for Common Graphics and the Integrated Development Environment.

There is an online version of the ANSI Common Lisp specification. (The link is to the starting page of that document.) This provides the primary documentation for Common Lisp functionality. In this release, there are no links between Allegro CL documentation and the ANSI spec (either way). Extensions and implementation details of standard Common Lisp functionality are described in various Allegro CL documents, particularly implementation.htm. The index in index.htm has links to this documentation (look up, e.g. open and disassemble -- the links go where the index link will go).

1.2 Some notation

Allegro directory	Used two ways: (1) the directory in which Allegro CL is installed, and (2) the translation of the sys: logical host, which is the directory where files needed while Allegro CL is running are located. We use the same term for both because these are normally the same directory. (sys: in fact translates to the directory containing the Allegro CL executable, usually lisp or lisp.exe, usually located in the directory into which Allegro CL was installed.) In earlier releases on Unix, this directory was called the Allegro CL home or the home directory. You may see those terms used as well in the documentation. The home directory used in that sense is unrelated to a user's home directory on a Unix machine.
Allegro executable or executable	The file, initially lisp (on Unix) or lisp.exe (on Windows) which is invoked to run Allegro CL. This is a small file and cannot be created by users. It can be copied and/or renamed as desired, however.
Allegro image file or image	This file contains the bulk of Lisp data. It is typically large and has the extension dxl. The executable can only be run with an image file. Image files can be created by users (with, e.g., excl:build-lisp-image and excl:dumplisp).

2.0 The Overview section

Html files in the doc/cl/ subdirectory of the Allegro directory (the directory where Allegro CL and related products were installed from the CD) describe the various features of Allegro CL. There are links where necessary between these files and to relevant files in the reference section.

Section 2.1 just below is a guide to the Allegro CL overview HTML documents in a table of contents format. Section 2.2 contains a table listing the documents in alphabetical order with a brief description of each one.

2.1 Allegro CL documentation table of contents

The document contents.htm is an outline of the Allegro CL documentation in table of contents format. (Note that documentation of Common Graphics, the Integrated Development Environment or ancillary products such as Allegro Composer are not included.) The outline is too large to reasonably be included in this document.

2.2 Allegro CL documentation: list of overview HTML documents

Here is an alphabetical list of the HTML files that make up the base Allegro CL documentation.

aclwffi.htm	This document describes how users porting from Allegro CL 3.0.x for Windows to Allegro CL 5.0/5.0.1 should update their foreign function calls. The foreign function interface in Allegro CL is quite different from the interface in 3.0.x. See foreign_functions.htm for information on the new interface. Users who did not work with Allegro CL 3.0.x for Windows need not refer to this document.
aclwin.htm	This document describes the language incompatibilities between Allegro CL 5.0/5.0.1 and Allegro CL 3.0.x for Windows. This document mostly discusses Lisp code (version 3.0.x was essentially based on Common Lisp: the Language, first edition, while Allegro CL 5.0.1 is an ANSI standard Common Lisp). See aclwffi.htm for information on changes in the foreign function interface. Users who did not work with Allegro CL 3.0.x for Windows need not refer to this document. (It is unchanged for the 5.0.1 release.)
aodbc_v2.htm	This file (which is not yet included in the contents.htm file) describes version 2 of Allegro ODBC. This is a new version with (we believe) a better user interface. Unfortunately, it is wholly incompatible with version 1. Not all users get Allegro ODBC, but if you have it, you will have both version 1 and version 2. You should use one version only. Version 1 is described in a printed document. Version 2 in this HTML file.
advice.htm	The advice facility allows adding code that is run before, around, or after functions (in some ways similar to before, after, and around methods but implemented prior to CLOS). This document describes how to use the facility and has links to the relevant reference documentation.
building_images.htm	The function excl:build-lisp-image creates a new image from existing components, inheriting a few features but no functionality from the running image (the one in which build-lisp-image is called). This document describes the build-lisp-image functionality and describes how to make custom images configured for your purposes. Note that creating an image which contains the functionality of the running Lisp image is done with dumplisp (see dumplisp.htm) while creating images for delivery is done with generate-application, described in delivery.htm.
case.htm	As an extension to standard Common Lisp, Allegro CL permits case sensitivity. This document discusses the issues with case sensitivity, describes how to make a case-sensitive image and how to convert the case-sensitivity of an image.
compiling.htm	This document describes the compiler. It provides information on how code generated by the compiler is controlled by the safety, space, speed, and debug optimization qualities. Information is also provided on declarations that will speed up code and tools for determining the effectiveness of declarations.
cross_reference.htm	This document describes the cross reference facility in Allegro CL. This facility can analyze Lisp code and determine what functions call what other functions and what functions are called by other functions.
debugging.htm	This document describes the debugger in Allegro CL. The commands that provide debugging information and features of the debugger are discussed.
defsystem.htm	Defsystem is a facility for managing files associated with an application. (It allows specifying the order in which files should be processed and the dependence of one file on another etc.) This document describes the defsystem facility in Allegro CL. Note that projects built with the Integrated Development Environment on Windows should not use defsystem since files are managed differently. See the cgide.hlp document.
delivery.htm	This document describes how to deliver an application written in Allegro CL. It describes the function generate-application which can be used to create images and bundle files together in a directory suitable for delivery. There is also a description of how to establish a patch system for your application which complements the patch system for Allegro CL, and other delivery-related issues.
dumplisp.htm	Like excl:build-lisp-image, excl:dumplisp creates a new Lisp image file. However, the file created by dumplisp contains most of the functionality present in the currently running images, so all defined functionality will still be defined, and the current values of variables will be retained -- for the most part, see the document for details. (Contrast this with excl:build-lisp-image which produces a fresh image which inherits very little from the running Lisp image.) This document describes dumplisp functionality and discusses issues of importance when using dumplisp.
Emacs-Lisp Interface: ../../eli/readme.htm	The linked document describes the Emacs-Lisp interface provided with Allegro CL. See also startup.htm#6.0 Running Lisp as a subprocess of Emacs for information on connecting Emacs to Allegro CL.
errors.htm	Some common errors which may be encountered while using Allegro CL are discussed, along with, where possible, suggestions for fixing them. The condition system type hierarchy in Allegro CL is also discussed.
ffi43com.htm	This document describes how to update your foreign function interface code from version 4.3.x on Unix to use the new foreign function interface in 5.0. (It is unchanged for the 5.0.1 release.) It also describes a compatibility mode which allows all 4.3.x foreign function code to run in 5.0/5.0.1 with minor exceptions.
flavors.htm	Flavors is an object-oriented system for use in Lisp. It predates and has been effectively replaced by CLOS. We maintain flavors for backward-compatibility only. The Allegro CL flavors implementation is described in this document. Note that the reference portion (definitions of functions, macros, variables, etc.) is included with the text of this document. (Most functionality is described in the reference section of the documentation rather than being integrated into these html documents.)
foreign_functions.htm	The foreign function interface allows compiled foreign code to be loaded into a Lisp image and run from Lisp. (Foreign means C, C++, and Fortran, along with other C compatible object files.) Because of differing internal representations of data, it is not entirely straightforward to pass data from Lisp to C, to call foreign functions from Lisp, and to call back to Lisp from a foreign function. This document describes the tools provided for defining and calling foreign code.
ftype.htm	This document describes how foreign types (e.g. C longs and shorts, C strings, C structures, etc.) can be defined in Lisp and how Lisp can access and operate on instances of foreign types.
gc.htm	Lisp maintains a garbage collector which regularly frees up space in the Lisp heap which is no longer used. This process is called garbage collection. While garbage collection is fully automatic and so a user need not necessarily think about it, configuring the garbage collector to a specific application or to a pattern of Lisp use often results in significantly better performance.
iacl.htm	This document describes International Allegro CL (IACL), a version that supports extended character sets. IACL is a separate product. The documentation is only useful to those who have purchased IACL. IACL functionality is not described on separate description pages. (Some functionality is changed and new functionality is provided in IACL, as described in the document.)
implementation.htm	This document provides specific information about the implementation of Allegro CL. Many details of the Common Lisp standard are implementation-dependent (such as the number of distinct floating-point types and their mapping to machine floats, the largest fixnum, the implementation of random, etc.) and this document says what Allegro CL does. Also discussed are extensions to Common Lisp functions (such as open, make-array, and others where an Allegro-specific enhancement is provided).
index.htm	This document provides links to other documents, including links to all Allegro CL functions, variables, etc. and those Common Lisp functions, variables, etc. for which there are Allegro-specific implementation details (see implementation.htm above). Topics are links to the document where the topic is discussed.
inspector.htm	This document describes the non-windowized inspector. (Users on Windows with the Integrated Development Environment get all the functionality described in this document in inspector windows.)
introduction.htm	The document you are now reading.
loading.htm	This document describes details of the implementation of cl:load (such as where is a file with no path information looked for). cl:require is also discussed.
main.htm	Allegro CL allows you to define your own C main(), as described in this document.
miscellaneous.htm	This document describes functionality too limited to need a separate document. Examples are excl:fasl-read and excl:fasl-write and various functions, like fixnump, which might have been part of standard Common Lisp but aren't.
mop/contents.html	The files in the mop/ subdirectory are an HTML version of the description of the MetaObject Protocol in chapters 5 and 6 of The Art of MetaObject Protocol by G. Koczales, J. des Rivieres, and D. Brobrow. The HTML version was prepared by Howard Stearns and copyrighted by the Elwood Corporation, as described in mop/admin.html. We thank Mr. Stearns and the Elwood Corporation for their kind permission is allowing Franz Inc. to use these files in our product. Much useful information about Lisp, including these files, can be found on the Association of Lisp Users (ALU) home page, maintained by the Elwood Corporation, at http://www.elwoodcorp.com/alu/.
multiprocessing.htm	Allegro CL supports multiprocessing using lightweight processes (within the running Lisp process) on UNIX and multiprocessing using OS threads on Windows. The functionality is described in this document.
ole.htm	A document describing interfacing to OLE. Allegro CL 5.0.1 for Windows only.
os_interface.htm	This document describes how to run OS functionality from within Lisp and also how to find out the current directory, how to change the current directory, and other aspects of interfacing with the operating system.
packages.htm	This document provides details of the implementation of packages in Allegro CL and includes a description of package locking (which prevents accidental redefinition of Common Lisp and Allegro CL functionality).
pathnames.htm	This document provides information on the implementation of pathnames (including logical pathnames) in Allegro CL.
plugin.htm	This document describes how to create a Netscape plugin from an Allegro CL application. Only works on Windows 95/98 and NT.
profiling.htm	Allegro CL provides a profiling utility as an add-on product. Both time and space usage can be profiled, though not at the same time. This document describes how the profiler works, how to use it, and how to interpret the results. Note that not all versions of Allegro CL include the profiler.
regexp.htm	This document describes the regular expression API available in Allegro CL.
release_notes.htm	This document is the release notes for Allegro CL on all platforms. Please refer to this document if you see unexpected behavior.
runtime.htm	Runtime is the technical solution to the restriction of runtime licenses. It has both legal and programming meanings. The legal meaning (determining, e.g., to whom a runtime image can be distributed and at what royalty) is defined in the Allegro CL Runtime License Agreement. In this document (runtime.htm), the programming meaning is discussed. Information is provided on how to create runtime images (but also see delivery.htm and building_images.htm), what are the limitations of a runtime image, and so on.
socket.htm	Sockets are a way for different running programs to communicate with each other. This document describes the support for sockets within Allegro CL.
source_file_recording.htm	Allegro CL provides a facility for remembering the file in which a Lisp function (or variable, parameter, macro, etc.) is defined. That facility is described in this document.
startup.htm	This document describes starting Allegro CL. Various methods of starting (from a shell, as a subprocess of emacs, on Windows with or without the Integrated Development Environment, etc.) are discussed. Command-line arguments and initializations files (both how to use them and how to suppress them) are described along with other things you should know about startup. Startup problems and suggested solutions are also discussed.
streams.htm	This file provides details of the implementation of streams in Allegro CL.
top_level.htm	The top level is the interface to a running development Lisp image. (We say `development' to distinguish from a Lisp application. Most applications provide their own top level.) This document provides information about the Allegro CL top level.

3.0 The Reference section

Standard Common Lisp functionality is described in the online version of the ANSI Common Lisp specification. (The link is to the starting page of that document.)

For Allegro CL-specific functionality, virtually every operator (function, generic function, or macro), every constant and variable, and many classes defined in Allegro CL, other than standard Common Lisp functionality, are described in individual HTML files called description pages. These files are arranged as follows:

<allegro directory>/doc/cl/pages/<kind>/<package>/<symbol>.htm

Where:

<allegro directory> is the directory into which Allegro CL was installed. The document you are reading is <allegro directory>/doc/cl/introduction.htm.

<kind> is one of

operators (for functions, generic functions, and macros)

variables (for variables and constants)

classes

other (currently, only top-level commands)

<package> is the home package of the symbol being documented, and is one of

compiler, defsys, excl, ff, mp, prof, socket, system, top-level, xref

and <symbol> is the symbol naming the object (or the name of the top-level command). A * character in a symbol name is handled specially. * appears as s_ or _s depending on whether the * is leading or trailing.

Thus, the documentation for the variable excl:*enable-package-locked-errors* is in the file:

<allegro directory>/doc/cl/pages/variables/excl/s_enable-package-locked-errors_s.htm

And the documentation for the function system:command-line-arguments is in the file

<allegro directory>/doc/cl/pages/operators/system/command-line-arguments.htm

Each page names the symbol, its home package, and the type of the object being described (function, macro, variable, class, etc.)

Descriptions of operators include the argument list. Generally the argument list is the same as returned by functions like excl:arglist but not always. It will not be when (1) the stored argument list is abbreviated (e.g. &rest args or &key &allow-other-keys, where argument processing is done within the operator body) and thus unhelpful; or (2) the stored argument names are unhelpful (struct -- because the object is a struct -- rather than, say, process or pathname).

Some arguments are listed but described as not for programmer use (these arguments may be intended for later enhancements or may support internal actions only). A few pages describe internal functionality not intended for programmer use. Symbols naming such functionality are exported for unavoidable system reasons and because they are exported, they have description pages.

4.0 Assistance available on the internet and the World Wide Web

Franz Inc. maintains a publicly-accessible (login is "anonymous", password is your email address) FTP site (ftp://ftp.franz.com/pub/faq) and has a World Wide Web home page (http://www.franz.com/). You may use either location to access the Allegro CL FAQ and patches to Allegro CL and related products.

4.1 The Allegro CL FAQ

FAQ stands for Frequently Asked Questions. The Allegro CL FAQ is a document written in question and answer format containing answers to questions often asked by users of Allegro CL and related products. Franz Inc. updates the FAQ regularly. We recommend that all users look at it on the Franz Inc. web site regularly or get a copy and update it regularly. Please do look in the FAQ when you have a question: it is quite possible that the answer will be there. This is particularly true for questions concerning product installation.

The FAQ is available via FTP:

ftp://ftp.franz.com/pub/faq

It is also available on the Franz Inc. WWW home page:

http://www.franz.com/

The exact structure changes more often than the documentation but once you have access to the home page or the FTP, finding things is usually not too difficult.

The FAQ as of the release of this updated document is available in ../faq/faq.htm.

4.2 Patches

A patch is a file (typically a fasl -- compiled Lisp -- file) which either corrects some error in the product or provides some enhancement or new feature. Patches are available from the Franz Inc. Web or FTP site. Patches are stored in both locations with a directory structure that mirrors the distribution directory structure, so that patch files can be downloaded into the correct directories off the distribution.

Start with the README file in the ftp://ftp.franz.com/pub/patches directory if you are accessing patches via FTP. On the Web site, choose Online Support, then click on the link to patches and follow the instructions.

4.3 Further information

Note the following points.

The patch files are numbered and coded by product, and they are read in order, lower numbers first. The order in which they are read is very important. Do not change the names of patch fasl files. A single patch may have various versions. This means the patch has been updated. All but the highest numbered file are essentially dummies. Their purpose is to overwrite the file of that name on your system, if there is one.
When you receive a new version of Lisp, you should delete all patch files used with previous versions.

4.4 Should you get all patches?

Whether or not you should get all available patches depends on your current tolerance for instability. Because patches are less well tested than releases, patches may occasionally introduce errors as well as fix problems. However, even a correct patch may introduce instability: if a patch enables a feature which was previously ignored or signals an error (correctly) where none was previously signaled, your code may fail because the patch uncovered a problem which was previously unnoticed. Suppose, for example, a patch causes certain declarations to be used during compilation (without the patch they are ignored). Such a patch would not fix a bug (since ignoring declarations is permitted) but if your code happened to contain incorrect declarations, then the patch would be destabilizing. (Without the patch, the wrong declarations were ignored and so did not harm. With the patch, they are used.)

The potential impact of a patch is given in the LOG file in the patch directory. Here are two entries from the 5.0 patch LOG (the 5.0.1 patch LOG file will be organized similarly):

Mon Sep 14 11:27:52 PDT 1998
Patch: update/p0a001.001
Fixes a bug where find-restarts, when given the optional condition argument, would not consider restarts that are not associated with any condition.
Impact: Should be minor

Tue Sep 1 14:33:29 PDT 1998
Patch: update/p0b002.001
Fixes self tail recursive call with intermixed args. Problem resulted in errors in compiled code, not in interpreted.
Impact: Recommended.:

Notice the Impact line (shown in bold here for emphasis). It provides an assessment of how destabilizing a patch may be. Note that in these cases, one is minor and the other patch (which fixes a problem where compiled code ran incorrectly) is recommended.

If you are in a development cycle, our advice is to get all available patches for their platform (machine type) and Allegro CL version. Patches for associated products (such as CLIM 2.1) should be included as well.

But if you are preparing a delivery, we advise you to be selective, perhaps getting only the patches that deal with problems you report.

Note that we have previously advised even users who are developing applications rather than preparing for delivery to only include patches when they experienced the problem fixed by the patch. There are pluses and minuses to each recommendation. While including all patches gives you all available fixes, as we said above, patches are not as well tested as releases and sometimes a patch introduces a new problem or bug. However, we have changed our advice for when you are developing because many patches are for performance, and therefore generally useful, and because problems introduced by patches, while they do happen, are uncommon and are usually fixed quite quickly (typically with an updated patch), and because it is relatively easy to back out a patch if it causes problems.

Note that the report created by excl:dribble-bug lists all patches included in the image. It is very important that this information be included with a bug report.

5.0 Reporting bugs

Before reporting a bug, please study this document and the ANSI CL Standard document.

A report that such and such happened is generally of limited value in determining the cause of a problem. It is very important for us to know what happened before the error occurred: what you typed in, what Allegro CL typed out. A verbatim log may be needed. If you are able to localize the bug and reliably duplicate it with a minimal amount of code, it will greatly expedite repairs.

It is much easier to find a bug that is generated when a single isolated function is applied than a bug that is generated somewhere when an enormous application is loaded. Although we are intimately familiar with Allegro CL, you are familiar with your application and the context in which the bug was observed. Context is also important in determining whether the bug is really in Allegro CL or in something that it depends on, such as the operating system.

To this end, we request that your reports to us of bugs or of suspected bugs include the following information. If any of the information is missing, it is likely to delay or complicate our response.

dribble-bug output. The function excl:dribble-bug is like common-lisp:dribble but prefaces the transcript with information about the image being run (platform, OS, Allegro CL version, patches loaded, and much else). Please include the output of excl:dribble-bug in the first report of any bug or problem.
Information about you. Tell us who you are, where you are and how you can be reached (an electronic mail address if you are reachable via the Internet, a postal address otherwise, and your telephone number), and in whose name the license is held. It is best to put the email address in the text of the message (in case the mailer program messes up the return address). Please include a telephone number in case an email response bounces.
A description of the bug or problem. Describe clearly and concisely the behavior that you observe and why it is not what you expect or want.
Exhibits. Provide us with the smallest, self-contained Lisp source fragment that will duplicate the problem, and a log (e.g. produced with excl:dribble-bug) of a complete session with Allegro CL that illustrates the bug.

Use excl:dribble-bug as follows. Entering

(excl:dribble-bug filename)

causes implementation and version information to be written to the file specified by filename, and then records the Lisp session in the same file. Exiting Lisp or entering

(dribble)

will close the file after the bug has been exhibited. The following dialogue provides a rudimentary template for the kernel of a bug report.

USER(5) (dribble-bug "bug.dribble")
USER(6) ;; Now duplicate your bug . . .
USER(7) (dribble)

Send bug reports to either the electronic mail or postal address given in 5.1 Where to report bugs and send questions. We will investigate the report and inform you of its resolution in a timely manner.

Important note about excl:dribble-bug: its log does not capture things printed by the operating system or by operating system utilities. These messages may be important. Please be sure you include them in the message.

5.1 Where to report bugs and send questions

Send problem reports and technical questions of any type by email to bugs@franz.com. Our mailing address is Franz Inc., Suite 275, 1995 University Ave., Berkeley CA 94704 USA; and our telephone number (in the USA) is +510-548-3600.

6.0 Common Graphics and Integrated Development Environment documentation [Windows only]

Common Graphics (CG) is a window system available (in the 5.0/5.0.1 releases) on Windows 95/98 and Windows NT only. The main documentation is a Windows help file, cgide.hlp in <Allegro directory>/cg/cgide.hlp. The Integrated Development Environment (IDE) is a graphical tool for building application interfaces. It is also documented in cgide.hlp. When using the Integrated Development Environment, pressing F1 brings up a page from that file describing the currently selected object. The index of cgide.hlp is displayed by clicking the Common Graphics Index command on the Help menu.

The CG and IDE are only available on Windows. The documentation may not be supplied with Allegro CL on non-Windows platforms, in which case the links in this section will not work.

There is a User Guide for the IDE, also online, and several essays about aspects of the product. These documents are in <allegro directory>/doc/cg/ and its subdirectories:

Document title	Location
Using Forms to Create an Application	<Allegro Directory>/doc/cg/form/form.htm
Menus	<Allegro Directory>/doc/cg/menu/menu.htm
Pixmaps	<Allegro Directory>/doc/cg/pixmaps/pixmap.htm
Working with Projects	<Allegro Directory>/doc/cg/project/project.htm
System Internals	<Allegro Directory>/doc/cg/system/system.htm
compat.hlp (discusses changes from Allegro CL for Windows 3.0.x to Allegro CL 5.0 on Windows, unchanged for the 5.0.1 release).	<Allegro Directory>/doc/cg/compat.hlp (a Windows Help file)
porting.hlp (examples of porting code from Allegro CL for Windows 3.0.x to Allegro CL 5.0 on Windows, unchanged for the 5.0.1 release).	<Allegro Directory>/doc/cg/porting.hlp (a Windows Help file)
CG and IDE Documentation Introduction	<Allegro Directory>/doc/cg/index.htm