Allegro CL Startup

$Revision: 5.0.2.15 $

The document introduction.htm provides an overview of the Allegro CL documentation with links to all major documents. The document index.htm is an index with pointers to every documented object (operators, variables, etc.) The revision number of this document is below the title. These documents may be revised from time to time between releases.

1.0 The Allegro directory
2.0 Starting Allegro CL
    2.1 Starting on UNIX machines
    2.2 Starting on Windows machines
    2.3 The executable, the image, and additional files
    2.4 The executable and image names
    2.5 Argument defaults
3.0 Command line arguments
4.0 Files Lisp must find to start up and files it may need later
    4.1 Files Lisp needs to start up 1: .so (or dll) files built with image
    4.2 Files Lisp needs to start up 2: the Allegro directory
5.0 The start-up message
6.0 Running Lisp as a subprocess of Emacs
    6.1 Starting Lisp as a subprocess of Emacs the first time
    6.2 Starting Lisp within Emacs after the first time
    6.3 What if the Emacs-Lisp interface does not start?
    6.4 Using the IDE with Emacs
7.0 Starting Lisp from a shell
8.0 Start-up problems
9.0 How to exit Lisp
     9.1 How to exit for sure
10.0 What Lisp does when it starts up
11.0 Initialization and the sys:siteinit.cl and [.]clinit.cl files
     11.1 Errors in an initialization file
     11.2 No top-level commands in initialization files
     11.3 Cannot (effectively) set a variable bound by load
     11.4 Starting Allegro Composer from .clinit.cl
12.0 Setting global variables in initialization files
     12.1 Where are the bindings defined?
     12.2 Many bindings are to specific values, not to the variables' actual value
     12.3 How to set the value so a listener sees it?
     12.4 A sample initialization file
13.0 After Lisp starts up
     13.1 The initial prompt
     13.2 Errors
     13.3 What if the system seems to hang?
     13.4 Enough C-c's (on Unix) will always interrupt
     13.5 The Allegro Icon on the system tray will interrupt on Windows
     13.6 Help while running Lisp
14.0 Files that may be looked for on startup and after startup

1.0 The Allegro directory

The Allegro directory is the directory where Allegro CL was installed. In it is the executable (lisp.exe) and one or more standard images (with extension dxl and names like lisp.dxl and allegro.dxl) and other files and subdirectories which may be needed to run Allegro CL. If you follow the standard installation procedure, the Allegro directory on Windows machines is C:\Program Files\acl501 and on Unix is /usr/acl5.0.1.

2.0 Starting Allegro CL

2.1 Starting on UNIX machines

The recommended way to start Lisp on UNIX machines is as a subprocess of Emacs (Xemacs or GNU Emacs). However, Lisp may be started from a shell. The disadvantage of starting Lisp from a shell is that the editing and other features of the Emacs-Lisp interface are not available. If you use Allegro Composer, many features are unavailable unless Lisp is started as a subprocess of Emacs.

The command for starting in a shell (assuming the Allegro directory is in your PATH) is:

> lisp.exe [-I <image path and name>.dxl] [other args]

See below for information on starting under emacs and for information on command-line arguments including the –I argument.

2.2 Starting on Windows machines

Choose Run from the start menu, then specify the executable file, image file, and any additional needed or desired arguments (described below), like this:

> <Allegro directory>\lisp.exe [-I <image path and name>.dxl] [other args]

A menu item on the Start menu (under Programs) is often available. One or (usually) more are installed by default when Allegro CL is installed. See below for information on starting under emacs and for information on command-line arguments including the –I argument.

2.3 The executable, the image, and additional files

Allegro CL requires at least two files: an executable, typical extension exe, and an image file, typical extension dxl. The executable is small and can be used with any dxl file (from the same release and on the same platform). The dxl file is typically much larger and contains information on the Lisp environment. (Note that in earlier releases on Unix, the image file was executable.)

You run the executable specifying a dxl file as an argument (identified by the -I flag). If no dxl file is specified, the executable looks for a dxl file in the same directory as the executable (typically, the Allegro directory) and with the same name. Therefore, if the executable is /usr/acl5.0/lisp and no dxl file is specified, /usr/acl5.0/lisp.dxl will be looked for and used if it is present. If it is not present, the startup will fail (and a -I argument must be specified in that case).

2.4 The executable and image names

The name of the executable is lisp on Unix and lisp.exe on Windows. The executable can be copied to have any other name and doing so is useful if you want it automatically associated with an image file with that name. You should leave the executable in the Allegro directory (where it was installed off the CD) because its location serves as a pointer to the locations of files needed during execution.

The location of the executable is set when the software is installed. Typically, your system administrator will know where Allegro CL was installed (if you did not install the software yourself). The image files have extensions dxl. One or more are supplied with the distribution and are in the same directory as the executable. Images can also be created with excl:dumplisp and excl:build-lisp-image. Their location and name depends on the arguments specified to those functions. It is not necessary for the executable and the image to be in the same directory. The –I command-line argument specifies the image file to use and its value can contain directory information as well as the name of the image file.

In this manual, we typically assume that the name of the Allegro CL executable is lisp or lisp.exe, as the example is on Unix or on Windows, and the image lisp.dxl. When the platform is not explicit, either lisp or lisp.exe may be mentioned and readers should mentally add or remove .exe as they are working on Windows or on Unix. We also assume that the executable is located in a directory that is in your PATH environment variable (that means the image can be started by typing the image name without its path). You, of course, should use the executable name actually used on your system and should include its path or not as appropriate.

2.5 Argument defaults

Values for command line arguments can be specified as a resource. On Unix, this is done with the file lisprc in the same directory as the executable. On Windows, the arguments are stored in the executable. This feature is designed for applications, not for general use;

It has significant limitations; in particular, the arguments specified in the resource are concatenated with those specified directly on the command-line with the resource arguments first. That is, the resource + arguments (Windows only) are processed, then the command-line + (Windows only) arguments, then the resource – arguments, and finally the command-line – arguments. Since the first –I argument encountered is used and others are ignored, you can not override the resource –I argument if one is specified. (Actually, on Unix, you can move the lisprc file but on Windows, there is no such workaround.)

It is because of these limitations that using resources is discouraged for general use. We mention them here because if resources are used, users may not get the behavior they expect and may not easily figure out why. Resources are described in the document delivery.htm, in section 4.1 Resources. See that document for information on determining whether resources are being used and for information on specifying them for applications.

3.0 Command line arguments

A command line argument is specified after the executable name when starting Lisp from a UNIX shell, in response to a question when starting Lisp as a subprocess of Emacs, and in the Run dialog when starting under Windows. You may specify any of the predefined arguments described next and any other arguments you want. The arguments specified may affect the startup procedure but in any case, all specified arguments are available when the image is running using functions like sys:command-line-arguments.

Note that it is not necessary to specify any arguments when running Allegro CL so long as the dxl file has the same name and is in the same directory as the executable file or has its name and location stored in the executable file. If the dxl file has a different name or is in a different directory and is not specified in the executable file, it must be identified by a -I argument.

Command-line arguments are prefixed with a plus (+) or a minus (-). Those prefixed with a plus (+) are for Windows only. Those prefixed with a minus (-) are for all platforms.

The general form for command line arguments on Windows is (it should be all on one line but we have broken the line for ease of reading):

lisp.exe [-Q] [acl-arguments starting with +] [-I dxl-file]
[other acl-arguments starting with -] [-- application-arguments]

-Q (for quiet startup), if supplied, must be specified first. We have displayed the -I argument separately from the other - arguments because of its special importance.

On UNIX, the general form of the command-line, shown here when starting from a shell, is

% lisp [-Q -:] [-I dxl-file] [acl-arguments starting with -]
[-- application-arguments]

-Q (for quiet startup) and -: (controlling how the Allegro CL shared object file is to be looked for) must be specified first, if supplied. When starting in Emacs, you are asked for a `Lisp Image (dxl) file' and also for `Image arguments (separated by spaces)'. The image (value of the –I argument) should be specified to the first question and any remaining command-line arguments in answer to the second.

acl-arguments affect how Lisp is run. application-arguments have no direct effect on Lisp but are available once Lisp starts up. A double minus (`--') separates the acl-arguments from the application-arguments. Everything before the double minus is interpreted as an acl-argument; everything after is interpreted as an application-argument. Therefore, the same value can appear in either place (or in both places) without ambiguity. If an argument before the -- is unrecognized by Allegro CL, a warning is printed.

application-arguments (and acl-arguments as well) are available after Lisp starts up with the function sys:command-line-arguments and its relatives. We will not say more about application-arguments here.

Now to acl-arguments. The following tables show the arguments and describes their effects. The first table describes the arguments starting with a +, which apply to Windows only. The second table applies to all platforms. Note that (on Windows) arguments starting with a + must precede all arguments starting with a - other than -Q.

Arguments starting with a -, applies to all platforms:

lisp -I foo.dxl

lisp -I foo

lisp -I foo.xxx

Table notes:

1. All arguments, including -e form and –L file arguments, are read and processed in order. Reading of one –e form can depend on previous forms having been evaluated and previous –L files having been loaded. For example, if the package mypack is defined in file.fasl, the following will not fail:

-L file.fasl -e (mypack::myfun)

because the mypack package has been defined when the reader encounters mypack::myfun (since file.fasl has been loaded).

2. When Lisp is started as a subprocess of Emacs, the system adds the arguments `-e (start-emacs-lisp-interface t)' as the first arguments after the image name. Your own -e arguments are not affected by this since multiple -e's are permitted, but the emacs-supplied arguments will appear along with the image name under the `command' column in the information printed by the Unix `ps' command.
3. If form (in a –e form argument) contains any spaces, it must be entered in a way that prevents the spaces being regarded as argument delimiters. When using the Emacs-Lisp interface, a space must be preceded with a backslash. Thus, for example, in response to `Image arguments (separate by spaces):' asked by Emacs, you might enter:

-qq -e (setq\ user::foo\ 10)

When starting Lisp in a shell, the form to be evaluated should be enclosed in single or double quotes. Using the same example:

% cl -qq -e '(setq user::foo 10)'

For these reasons, it is often easier to put complex forms in a file and have the file loaded with a –L argument rather than trying to get the –e punctuation correct.

4. It may not be possible to recover from an error signaled during the evaluation of a -e form or the loading of a –L file (indeed, Lisp may exit without giving you the opportunity to recover). Even if you are presented with a prompt to type to, many top-level commands may not be available. Restarting the image with the form corrected is the recommended action.
5. When running in batch mode, if an error occurs, Lisp exits with error code 1. If an EOF is encountered, Lisp exits with error code 0.
6. This argument (-backtrace-on-error) is designed for use with -batch. It can be used with a non-batch image, but a backtrace is printed whenever an error occurs and most users find this annoying. A backtrace can be printed. The file <allegro directory>/code/autozoom.cl defines a macro with-autozoom-and-exit which can be wrapped around code where programmers want to force a backtrace (and the backtrace can be directed to any stream, not just *error-output*). That macro is much more appropriate for non-batch programs.

Special note on the -! command-line argument

ALPHA NT users, be sure to read the paragraph starting On the Alpha NT below.

If this argument is specified, it must appear first among the command-line arguments. This argument is typically used when using a C-based debugger like gdb. It should never be used in ordinary circumstances because it causes certain kinds of error which are typically not fatal to become fatal errors.

The -! command-line argument is designed to assist in using an external debugger. The primary effect of this switch is to prevent lisp from catching illegal memory references and turning them into calls to the segmentation violation handler. Because these bad references are not caught, the exception generated by the operating system will be passed to whatever program is controlling lisp (usually a C Debugger). Note that if there is no program controlling Lisp, then the operating system will put up a dialog box announcing the exception and Lisp will not be able to continue. A secondary effect is to startup in a more verbose mode.

On the Alpha NT, the exception handling that is performed by the lisp, whether the -! is in effect or not, is dependent on the address of the instruction counter. The Alpha NT uses Procedure Descriptors which set up address ranges and exception handlers for those address ranges. Allegro CL sets up and maintains procedure descriptors for both the Lisp heap and the (optional) .pll file. If an exception occurs within the address range of these descriptors, the Lisp exception mechanism is called as usual, and the -! has a similar effect as on Intel hardware. However, if the program jumps to some wild location, the Lisp will die, or if running under a debugger, an error dialog box will come up which cannot be continued from. For more information on procedure descriptors, see the latest Alpha AXP calling conventions manual or the documentation for the following functions:

RtlAddFunctionTable
RtlDeleteFunctionTable
RtlLookupFunctionEntry
RtlLookupDirectFunctionEntry.

4.0 Files Lisp must find to start up and files it may need later

The next series of headings describe files Lisp needs to start up. A complete list of such files can be found in 14.0 Files that may be looked for on startup and after startup below. Here we give an abbreviated description directed at users who are running standard installed images or images dumped with standard installed images but run in situ (i.e. the dumped image is not moved to another machine). Programmers who do intend to move dumped images to different machines (or who are trying to start such an image but having difficulty) and application programmers wishing to deliver an application should refer to 14.0 Files that may be looked for on startup and after startup or to delivery.htm.

4.1 Files Lisp needs to start up 1: .so (or dll) files built with image

Like any UNIX or Windows program, Lisp may have shared object (.so or .sl files on Unix, .dll files on Windows) files mapped into the image at build time. This is done with the user-shared-libraries argument to build-lisp-image.

On Unix, these files are looked for in the Allegro directory, the directory where the executable file is located (unless a –H command-line argument specifies another location).

On Windows, the following method is used:

With both implicit and explicit linking, Windows first searches the set of pre-installed DLLs such as the performance library (KERNEL32.DLL) and the security library (USER32.DLL). Windows then searches for the DLLs in the following sequence:

1. The directory where the executable module for the current process is located. (this is the likely location and corresponds to Unix behavior.)
2. The current directory.
3. The Windows system directory. The GetSystemDirectory function retrieves the path of this directory.
4. The Windows directory. The GetWindowsDirectory function retrieves the path of this directory.
5. The directories listed in the PATH environment variable.

Note that the LIBPATH environment variable is not used.

4.2 Files Lisp needs to start up 2: the Allegro directory

The Allegro directory is a directory that contains files Lisp may need to start up and while it is running. Because it needs files like the .pll file, Lisp may fail on startup if it cannot find this directory. The Allegro directory also refers to the directory where Allegro CL was installed off the CD. We used the same name because they are typically the same directory.

The .pll filename is stored in the image, either as just a filename, just a filename and type, or a filename (with or without a type) with directory information. If directory information is supplied, the pll file is looked for in that location only (using default type pll if no type is specified), relative to the current directory if the directory information is relative. No other location is searched in that case. If the pll file information in the image file is just a filename or filename and type, it is is searched for in the current directory and then in the Allegro directory, and then, on Windows only, in the Windows sytems directory. See pll-file.

Unless the –H command-line argument is specified, the Allegro directory  is assumed to be the directory containing the executable (the file, initially lisp.exe on Windows and lisp on Unix). Files that may be needed for running may be in that directory or in the code/ subdirectory. If –H is specified, the files must be in the directory specified. The structure of that directory should mimic the structure of the Allegro directory (that is, it should have a code/ subdirectory and files should be placed in the same relative locations as they are in the Allegro directory.

(In the 4.3.x releases on Unix, this directory was found using an environment variable named ALLEGRO_CL_HOME. That was necessary because the image file was executable and could be located anywhere, including a user's home directory. Now that the image is separate from the executable, the location of the executable can serve as a reference point for finding other needed files. The image can still be anywhere, including users' home directories. Earlier releases on Windows such as 3.0.x always used the separate executable and image model and always used the executable location to find needed files.)

Once Lisp finds the Allegro directory, it sets the translation of the logical host sys: to be that directory. That directory contains most of the files Lisp needs to start up. It may happen that the directory identified as the Allegro directory exists but is incorrect (that is, does not actually contain the files Lisp needs). Lisp will fail to start if it needs a .pll file but cannot find it in the current directory or identified Allegro directory. Other missing files may cause problems as well, but Lisp usually gets some way into the startup process. Dealing with an existing but misidentified Allegro directory is much like dealing with a non-existent one: find where the Allegro directory really is and communicate this information to Lisp.

5.0 The start-up message

When Lisp starts up, it prints information on which image (.dxl) file is being used, and which .pll file is being used, if any. (If the -Q command-line argument is specified, the locations of the image and pll files is not printed.) Then it prints the banner, which looks something like (this example is from a Sun):

The exact version number, the machine type, and the date and time will all likely differ in your Lisp.

The sys:siteinit.cl and the initialization files (.clinit.cl or clinit.cl) are read next (see below) and then the Emacs-Lisp interface is started (if Lisp was started as a subprocess of Emacs). Then the start-up message is printed. The default start-up message says:

(The number of lines may differ.)

Start-up messages are printed by the generic function excl:print-startup-info. Exactly what is printed is controlled by the variable excl:*print-startup-message*.

6.0 Running Lisp as a subprocess of Emacs

If you are using the Integrated Development Environment on Windows, see 6.4 Using the IDE with Emacs below.

6.1 Starting Lisp as a subprocess of Emacs the first time

This is the standard way to start a Lisp image. When an image is started in this way, all of the Emacs-Lisp interface will be available, making it easier to use Lisp. The Emacs-Lisp interface is documented in eli/eli.htm.

Allegro CL works with Xemacs or GNU Emacs. To avoid repetition, we simply say Emacs to refer to either product. The Release Notes may contain the exact version numbers and other information about these products.

To start Allegro CL within Emacs, enter the following:

M-x fi:common-lisp

(M-x means depress the `x' key while the Meta key is down or press the Escape key and then press the x key.) Emacs will ask 5 questions:

1. Buffer: what the buffer in which Lisp will run should be named. The default is the value of the Emacs variable fi:common-lisp-buffer-name, whose value is typically *common-lisp*.
2. Host: the name of the machine where Lisp will run. The default is the value of the Emacs variable fi:common-lisp-host.
3. Process directory: the directory in which to run Lisp (if you were running from the shell, this is the directory in which Lisp is started). The default is the value of the Lisp variable fi:common-lisp-directory.
4. Executable Image name: the name of the Lisp executable. This file, new for UNIX in 5.0 but present in earlier releases on Windows, is a small file with extension .exe (initially lisp.exe). This file is shipped with the Allegro CL distribution and cannot be created or modified at customer sites. The same executable file works with any image file. The default is the value or the car of the value of the Emacs variable fi:common-lisp-image-name. (The value of that variable should be a cons specifying the executable image file and the image file.)
5. Image: the name of the Lisp image (.dxl) file. The default is the cadr of the value of the Emacs variable fi:common-lisp-image-name. If unspecified, assumed to be the file in the same directory as the executable image with the same name but with extension .dxl.
6. Image arguments: the command line arguments described above. Since they are separated by spaces, you must use appropriate quotation marks or backslashes if your arguments contains spaces. The default is the Emacs variable fi:common-lisp-image-arguments.

All questions are asked in the Emacs minibuffer. Once you have answered all the questions, Lisp is started according to your specifications.

Warning: you must exit Lisp before quitting Emacs or killing the Common Lisp buffer. Doing either without exiting Lisp may leave the Lisp process running. Starting Lisp again from within Emacs after you have killed a *common-lisp* buffer without exiting from Lisp may result in Emacs being connected to the wrong running image.

6.2 Starting Lisp within Emacs after the first time

Emacs remembers your answers to the questions asked by fi:common-lisp so if you evaluate fi:common-lisp again (after killing off the first Lisp image for whatever reason), Emacs will use the old answers without asking again. If you want the questions asked again (because, e.g. you want to run on a different host or with different initial arguments), use the universal argument (typically C-u) before M-x fi:common-lisp. Thus:

C-u M-x fi:common-lisp

The defaults will be your previous set of answers.

Warning: if the cursor is at the end of the *common-lisp* buffer and superkeys are enabled, C-u will be interpreted as `delete back to the last CL prompt' rather than as universal argument. If Lisp is not running in the buffer and you enter C-u at the end of the buffer, Emacs will print

Wrong type of argument: processp, nil

in the minibuffer. To get C-u interpreted as universal argument in this case, go up a line (with previous-line, typically C-p) where C-u will then be interpreted as universal argument:

C-p C-u M-x fi:common-lisp

6.3 What if the Emacs-Lisp interface does not start?

When Lisp is started with Emacs, the Emacs-Lisp interface should start up automatically. The system will print:

;; Starting socket daemon and emacs-lisp interface...

in the *common-lisp* buffer and

Trying to start connection...done

in the minibuffer. If both these appear, the connection has been started. If they do not appear or if the `done' does not appear, the interface may not have started. If the Emacs-Lisp interface does not start-up, you can start it up by evaluating the form:

(excl:start-emacs-lisp-interface)

It is not an error to call this function when the interface has in fact started. If you do so, however, something similar to the following will appear in the Lisp listener:

^A1026 771990 :upper NIL 1^A

(You will likely see different numbers and perhaps :lower rather than :upper. This message can be ignored.)

6.4 Using the IDE with Emacs

Windows only. The Integrated Development Environment (IDE) is a collection of graphical tools for building a graphical interface to an application developed in Allegro CL. It provides editors and editing capability. However, users familiar with Emacs may prefer to use Emacs.

The complication of using the IDE and Emacs is that all evaluation of IDE-related code that receives events (mouse input of any sort and keyboard input to a dialog) must be done by the IDE. This is because all IDE-related events must happen within the IDE thread (see the document multiprocessing.htm). Emacs runs in a separate thread. IDE-associated events cannot be initiated by the Emacs thread (it is an error to do so). Thus, function definitions etc. can be done within emacs. But code that displays dialogs and handles events must be run within the IDE thread using IDE tools.

When using the IDE, specify allegro.dxl as the Image file.

7.0 Starting Lisp from a shell

You can start Lisp from a shell prompt or a DOS prompt. Assuming on UNIX the name of the Lisp executable is lisp and that the image is located in a directory specified in the PATH environment variable, the following will start Lisp (the command is all on one line – we break it for readability and indicate the break with a \):

Assuming on Windows the name of the Lisp executable is lisp.exe and that the image is located in a directory specified in the PATH environment variable, the following will start Lisp (the command is all on one line – we break it for readability and indicate the break with a \):

If lisp/lisp.exe is not in your PATH, you can specify the full path in order to start Lisp.

A Lisp started from a shell on UNIX will not benefit from the Emacs-Lisp interface and many features of Allegro Composer will not work.

8.0 Start-up problems

Generally, there are not many problems with start-up. If there is insufficient swap space to run Lisp, a message saying so will be printed and Lisp will not start. Insufficient swap space may be a temporary problem but if you often are prevented from starting for that reason, you should consider increasing the swap space on your machine (see the hardware System Administration manual for information on increasing swap space).

Most errors during startup cause Lisp to fail (it prints the error message). The exceptions include errors during the loading of an initialization file and failure to find a loaded .so file. Those errors produce warnings but do not prevent the startup procedure from continuing. Other errors cause failure. Usually, the cause is something added to the startup procedure (perhaps by a -e command line argument or an item on excl:*restart-actions*). The recommended action is try to start again without the -e arguments or to use -e arguments to set the value of excl:*restart-actions* to nil (perhaps first making it the value of another variable which can be examined after startup succeeds).

Other potential problems include the following:

• The Emacs-Lisp interface does not start. See the information under the heading What if the Emacs-Lisp interface does not start? above.

• The Allegro directory location cannot be found or necessary files cannot be found. Finding the Allegro directory is rarely a problem since it is typically the same directory as the executable (.exe) file. (The –H command-line argument can be used to specify a different location and startup may fail if that location does not exist, however.) Lisp may also fail to start because needed files are not in the Allegro directory.
• Lisp fails on startup (HP only). Are you running a version for HP-UX 10.20 on an HP-UX 11.x machine? See the HP-specific uinformation in release_notes.htm for information on this.

9.0 How to exit Lisp

The ANSI spec is silent on the question of how to exit Lisp. Allegro CL has several commands which will cause a Lisp session to terminate. The expression

(excl:exit)

will cause the current Lisp image to exit.

One can also exit Lisp directly from the top level, using the top-level command :exit, documented in top_level.htm. These operators behave somewhat differently according to whether the Lisp is running multiprocessing or not. If there are multiple processes running, the user may be concerned that these processes exit cleanly (with windows cleaned up, for example).

The functions used for exiting have options which allow for clean exits in each process, but the user should be aware that if some problem occurs, user intervention may be necessary to correct it, and it may take some time for the problem to manifest itself. Thus, users doing intense multiprocessing should not leave their terminal immediately after typing (excl:exit) but should wait until Lisp has exited.

Note that the top level command may not exit if there are other processes running, and the function exit called without arguments will try to clean up all processes that are running. Users using multiprocessing should read the description of the exit function. Users not using multiprocessing need not concern themselves with these fine points. (Note that if you use the Emacs-Lisp interface, you use multiprocessing. However, processes created by that interface, or by Allegro Composer, are generally well-behaved with respect to exit behavior. Problems typically arise with user-created processes.)

9.1 How to exit for sure

If a simple call to (excl:exit) does not cause Lisp to exit (typically because of problems with multiple processes), try the following form:

(excl:exit 0 :no-unwind t)

10.0 What Lisp does when it starts up

In this section, we describe the Allegro CL startup procedure. While this is usually of academic interest only, if the startup does not go as expected, the reason may be that things are done in a different order than you expect. See the file <allegro directory>/src/aclstart.cl, which is the source to the startup code.

1. All logical pathnames translations are flushed. The translations may have been defined in the parent image (particularly if the image was created with excl:dumplisp after the initial build). They are flushed because there is no guarantee that they are valid. The image will find translations anew by looking in the files in the list returned by excl:logical-pathname-translations-database-pathnames. sys:hosts.cl is on that list. sys: itself translates to the Allegro directory.
2. On Windows NT, the affinity (number of pohysical processors to be used) is set to 1. See sys:processor-affinity-mask.
3. The standard streams are bound. The standard streams are *terminal-io*, *standard-input*, *standard-output*, *error-output*, *trace-output*, *query-io*, and *debug-io*. They are bound to excl:*initial-terminal-io*.
4. The Allegro CL banner is printed. (It is a violation of the license agreement to suppress the printing of the Allegro CL banner except under certain conditions. Contact your Franz Inc. sales representative if this is an issue.)
5. Loaded .so (.sl, .dll) files are reloaded. Shared object files are mapped into a running image, not built into the executable image. therefore, all such files must be reloaded on startup. Under certain circumstances, the image may not be able to find these files. If it cannot find a .so file, a warning is printed but no error is signaled. If Lisp gets to the first prompt without error, the missing .so file can usually be loaded at that time.
6. Command-line arguments are processed. All -e and –L arguments are processes, in order, at this time. (A –e argument specifies a form to evaluate. A –L argument specifies a file to load.)
7. Initialization files are read. The files are sys:siteinit.cl, the two user initialization file. Whether the files are read and exactly which files are read depends on the value of excl:*read-init-files* and the command-line arguments. If any initialization files are read, sys:siteinit.cl is read first. If both user initialization files are read, the one in the home directory is read first. Errors that occur reading the files are ignored. If an error occurs in a file, the remainder of the file is ignored. User initialization files are named by the variable excl:*init-file-names*. The initial value of this variable is the list (.clinit.cl clinit.cl). Whatever the value, only one file (the first found processing the list in order) is read from any location.
8. The startup messages are printed. The function excl:print-startup-message is called to print the message.
9. Restart actions are performed. The functions on the *restart-actions* list are called.
10. The initial stack-group is set up.
11. ACL_STARTUP_HOOK is examined. The environment variable ACL_STARTUP_HOOK is polled. If set, its value is read by read-from-string and the result is evaluated. This is a last-chance backdoor into the startup process.
12. The restart init function is called. If excl:*restart-init-function* is non-nil, its value is assumed to be a function of no arguments and it is funcall'ed.
13. The Lisp listener is started or the restart-app function is called. The following form is executed:

(tpl:start-interactive-top-level s
   (or *restart-app-function*
       #'tpl:top-level-read-eval-print-loop)
    nil)

If excl:*restart-app-function* is non-nil, its value is assumed to be a function of no arguments which is started within a tpl:start-interactive-top-level form (which sets up bindings for global variables). It is assumed to provide the application top-level if there is one or do whatever the application does without user interaction. It should not return.

If excl:*restart-app-function* is nil>, tpl:top-level-read-eval-print-loop is called. It starts a Lisp listener (the Initial Lisp Listener) and presents the user with a prompt.

One thing we want to emphasize by detailing the startup sequence is that because of the order, certain things cannot affect other things. Trivially, a command-line argument can affect whether and which init files are read but an init file cannot affect command-line processing. Note the following about the startup procedure:

• The source code for the startup procedure is in <Allegro directory>/src/aclstart.cl. That file can be examined for more details of starting up.
• The steps 2-11 are run within a handler-case form. If an unhandled error occurs during startup, a message is printed and Lisp exits. The acts of reading the init files and reloading loaded .so files are protected against errors so problems there do not cause unhandled errors.
• Step 10 provides a backdoor hook into Lisp via an environment variable. In some cases, this hook can be used to force a startup which is failing. If, for example, excl:*restart-app-function* is causing problems, but init files are not read and command-line arguments are ignored (two other ways to affect startup), starting Lisp in an environment where ACL_STARTUP_HOOK is "(setq excl:restart-app-function* nil)", Lisp will start a Lisp listener instead of calling excl:*restart-app-function*. We strongly advise against setting this environment variable except in an emergency.

11.0 Initialization and the sys:siteinit.cl and [.]clinit.cl files

When Allegro CL is first invoked it may look for and load if present several initialization files. The variable excl:*read-init-files* controls whether the files are looked for at all and the command-line arguments -q and -qq also control which or whether init files are read. The files are:

• sys:siteinit.cl. The sys: component names the system directory, which is interpreted by Allegro CL to be the Allegro directory. If any initialization files are read, this one is read first.

• ~/.clinit.cl or ~/clinit.cl (that is, with and without a leading dot). On Unix, ~ is the current user's home directory. On Windows, ~ is C:\. The first named file found is the only one read.
• <current-directory>/.clinit.cl or <current-directory>/clinit.cl (unless the <current directory> is ~ and ~/.clinit.cl or ~/clinit.cl has been loaded). On Unix, the current directory is the working directory where Lisp is started. On Windows, the current directory is usually the directory containing the executable (.exe) file that is invoked, but may be something different, such as a directory specified in Start In field of a shortcut. The first named file found is the only one read (that is, only one of clinit.cl and .clinit.cl will be read even if both are present).

The value of the variable excl:*init-file-names* is a list of strings naming the initialization files to look for (other than sys:siteinit.cl). Its initial value is (".clinit.cl" "clinit.cl"). We use a name with and a name without a leading dot because of the difference between handling of initial dots on Unix and on Windows. (On Unix, a leading dot means do not normally include the file in a file listing. On Windows, a leading dot is just confusing.) In a directory, the files are looked for in the order they appear in the list and the first one found (and only that one) is read.

Any valid Lisp form may be present in an initialization file. Initialization files are often used to customize your Lisp environment, by, for example, loading files or changing reader syntax. Loading of initialization files can be suppressed with an argument on the command line that initiates Lisp. If -q is specified on the command line, the [.]clinit.cl in your home directory will not be read (unless that is also the current directory). When -q is specified, the sys:siteinit.cl file and the [.]clinit.cl file in the current directory (even if it is also your home directory) are looked for and loaded if present.

If -qq is specified on the command line, no initialization file will be read.

11.1 Errors in an initialization file

Note that an error in an initialization file will not cause Lisp to enter a break loop, although an error message will be printed. If you wish to debug an initialization file, load it explicitly, using the -qq argument if necessary to suppress its initial loading. As a simple example, consider a [.]clinit.cl file containing the forms:

(setq xx (firt '(1 2 3 4)))
(setq yy 5)

In the first form, firt is a misprint for the Common Lisp function first. When Lisp is initialized and the .clinit.cl file is read, messages similar to the following are printed:

Error: attempt to call `firt' which is an undefined function.
Error loading #p"/h/dm/.clinit.cl"

Lisp does not enter a break level upon errors in a [.]clinit.cl file. Instead it aborts further processing of the file. (Thus yy will be unbound.) The command

:ld .clinit.cl

will, on the other hand, generate a continuable error allowing the user to correct the bad function name.

11.2 No top-level commands in initialization files

Top-level commands (prefixed by the top-level command character) can not be used from within the initialization file, or any other file. They may only be typed to the top level. tpl:do-command does provide a functional equivalent of a top-level command (see the description in chapter 4). Note, however, that the information necessary to successfully perform certain commands (such as :zoom) is not available when the initialization files are loaded and so the call may fail, in some cases with a recursive (i.e. non-recoverable) error.

11.3 Cannot (effectively) set a variable bound by load

Note that certain global variables are bound when load is loading a file. Therefore, setting those variables in an initialization file will not have the desired effect. (See also the discussion of setting global values in initialization files below). The following table shows what variables are bound by load:

11.4 Starting Allegro Composer from .clinit.cl

UNIX only. Simply putting (composer:start-composer) in your .clinit.cl file works but has the annoying side effect of printing several lines of bogus warnings. Better is to use the following code, which is in <Allegro directory>/examples/composer/clinit_start.cl.

12.0 Setting global variables in initialization files

Allegro CL starts a Lisp listener by binding many standard Common Lisp special variables and also many Allegro-CL-specific special variables to appropriate values. The listener runs within the scope of these bindings. Allegro CL does this because it implements a multiprocessing extension. The bindings permit one process to set a special without another process being affected. (For example, if a process doing output sets *print-base* to 8 in order to print out octal numbers, the Lisp listener, running concurrently and trying to print the integer nine, will print 9 rather than 11.) Even if you are running Lisp without initiating multiprocessing, the Listener runs within the scope of the bindings.

12.1 Where are the bindings defined?

A Lisp listener gets its bindings from two alists: excl:*cl-default-special-bindings* and tpl:*default-lisp-listener-bindings*. Here are a few lines from each alist:

12.2 Many bindings are to specific values, not to the variables' actual value

Notice that most of the entries in excl:*cl-default-special-bindings* associate a variable with a specific value such as t (the value associated with *print-pretty* and *print-escape*) or 10 (the value associated with *print-base*) or nil (the value associated with *print-length*, *print-level*, and *print-radix* -- the nil isn't printed because in an alist, (*print-escape* . nil) and (*print-escape*) are the same thing). Indeed, all of the pairs shown associate a variable with a specific value but if you look at the entire list you will see some entries that are associated with the value of a variable. Most of the entries in tpl:*default-lisp-listener-bindings* associate variables with values of variables, but notice most of them are unexported.

The variables associated with specific values will be bound to those values when a Lisp listener is started regardless of the actual value of the variable at the time the binding is done. This means that setting (with setf or setq) the value of such a variable in an initialization file (or anywhere prior to a Lisp listener being started) cannot affect the binding in effect within the listener. To be concrete, suppose the following form is in your .clinit.cl file and that file is read on Lisp startup:

(setq *print-length* 20)

If you evaluate *print-length* in the listener that appears after startup, you get:

USER(1): *print-length*
NIL

Why? Because the listener sees the binding of *print-length* to nil, as called for in excl:*cl-default-special-bindings*. The value set in the initialization file is ignored.

12.3 How to set the value so a listener sees it?

You change the alist from which the bindings are drawn so that the binding is made to the value you want. (You could also remove the entry from the alist so that the value is not bound when a listener is started, but that is not recommended.) The macro tpl:setq-default is designed to do exactly that. The form

(tpl:setq-default *print-length* 20)

does the following:

• It sees whether *print-length* is a key in either excl:*cl-default-special-bindings*. If it is, it replaces the value of the pair with (sys:global-symbol-value '*print-length*). If it does not appear as the key in either list, it adds

(*print-length* . (sys:global-symbol-value '*print-length*)

to the excl:*cl-default-special-bindings* alist.

• It sets the global symbol value of *print-length* to 20 as if with the form

(setf (sys:global-symbol-value '*print-length*) 20)

Now, when a Listener is started, *print-length* will be bound to (sys:global-symbol-value '*print-length*), which, if the global symbol value has not been subsequently changed, is 20. So, the form

(tpl:setq-default *print-length* 20)

should go in the initialization file instead of (setq *print-length* 20).

12.4 A sample initialization file

If a file .clinit.cl or clinit.cl exists in the user's home directory (C:\ on Windows) or in the working directory (the Allegro directory on Windows), it is loaded when Lisp starts up (the first one found and only the first one found is loaded from any directory). This provides a method for customizing your Lisp environment. The sample initialization file below sets several top-level variables. There is a sample .clinit.cl file in the distribution at <Allegro directory>/misc/dot-clinit.cl.

A sys:siteinit.cl file (which will be read by every Lisp image at your site) will typically not have this level of customization. However, the form (using tpl:setq-default, e.g.) is similar.

;;;
;;; This file contains examples of user
;;; customizations which can be done via a
;;; $HOME/.clinit.cl or C:\clinit.cl.
 
(format *terminal-io* "~%; Loading home ~a~@[.~a~] file.~%"
       (pathname-name *load-pathname*)
       (pathname-type *load-pathname*))
 
;;; Set a few top-level variables.
(tpl:setq-default top-level:*history* 50)
(tpl:setq-default top-level:*print-length* 20)
(tpl:setq-default top-level:*print-level* 5)
(tpl:setq-default top-level:*zoom-print-level* 3)
(tpl:setq-default top-level:*zoom-print-length* 3)
(tpl:setq-default top-level:*exit-on-eof* t)
 
;;; Display 10 frames on :zoom,
(tpl:setq-default top-level:*zoom-display* 10)
;;; and don't print anything but the current frame on
;;; :dn, :up and :find
(tpl:setq-default top-level:*auto-zoom* :current)
 
;;; Have the garbage collector print interesting stats.
(setf (sys:gsgc-switch :print) t)
(setf (sys:gsgc-switch :stats) t)
 
;;; To have all advice automatically compiled.
(tpl:setq-default *compile-advice* t)
 
;;; Have packages print with their shortest nickname
;;; instead of the package name.
(tpl:setq-default *print-nickname* t)
 
;;; Allow concise printing of shared structure.
(tpl:setq-default *print-circle* t)
 
;;; Only print "Compiling" messages for files, not for individual functions,
;;; unless there is a warning or error.
(tpl:setq-default *compile-verbose* t)
(tpl:setq-default *compile-print* nil)
 
;;; Set up a top-level alias.
(top-level:alias ("shell" 1 :case-sensitive) (&rest args)
   "`:sh args' will execute the shell command in `args'"
   (let ((cmd
       (apply #'concatenate 'simple-string
             (mapcar #'(lambda (x)
                        (concatenate 'simple-string
                          (write-to-string x :escape nil) ""))
                     args))))
  (prin1 (shell cmd))))
 
;;; The following makes the source file recording
;;; facility compare only the names of pathnames, for
;;; the purposes of determining when a redefinition
;;; warning should be issued.
(push #'(lambda (old new fspec type)
        (string= (pathname-name old) (pathname-name new)))
     *redefinition-pathname-comparison-hook*)
 
;;; Use the Composer package if it is available.
(eval-when (eval compile load)
(when (find-package :wt)
  (use-package :wt)))

13.0 After Lisp starts up

13.1 The initial prompt

After the initial messages are printed (and the Emacs-Lisp interface is started, if appropriate), the first prompt is printed. Unless you have changed the prompt, it will look like:

>

USER(1):>

Here, USER specifies the common-lisp-user (nicknamed user) package (Lisp starts in that package) and the 1 indicates the command number. You can now type forms to Lisp.

If you are using the Integrated Development Environment on Windows, the Console window has a prompt like the one just described. The Debug window has a > prompt.

13.2 Errors

In the course of running Allegro CL, you may make an error. If Allegro CL detects an error, it will go into a break loop. The prompt will indicate a break loop by a number in brackets preceding the prompt. The following script shows what happens when an error is signaled:

user(2): (car '(1 2))
1
user(3): (car 1)
Error: Attempt to take the car of 1 which is not a cons.
[condition type: simple-error]
[1]user(4): (car 2)
 
Error: Attempt to take the car of 2 which is not a cons.
[condition type: simple-error]
[2] user(5): 

See top_level.htm for more information on the prompt and break levels.

13.3 What if the system seems to hang?

For interrupting on UNIX, see 13.4, for interrupting on Windows, see 13.5.

At times, the system may seem to `hang', that is make no response to what you have typed and seem to be doing nothing. This may be normal, since some commands take a long time to execute, or it may indicate that the system has gone into some loop or received improper input.

If you are running in a shell, a common cause is unclosed parentheses in the input line. Try adding some closing parentheses and see if that helps -- too many right parentheses will signal a warning but not an error. (If you are running under Emacs, it should be clear that parentheses are missing because the cursor will be indented since Emacs expects more information.)

If too few right parentheses is not the problem, try to regain control by hitting the Unix interrupt character (user-settable but typically C-c in the shell and C-c C-c in Emacs). Entering this character sends signal #2 (SIGINT) to the Lisp process. Allegro CL checks for a keyboard interrupt at almost every function call and at least once in each iteration of a loop compiled at proper safety, and this method will typically work. However, it will not work in two cases: (1) when Lisp is executing foreign code (if the infinite loop is in C or FORTRAN code loading into Lisp) and (2) when Lisp is executing a function compiled so that interrupt checks are suppressed (it is possible to set the compiler options so that this check is not made in user defined compiled functions, see compiling.htm).

13.4 Enough C-c's (on Unix) will always interrupt

Often, a Control-C will interrupt on Unix (C-c C-c if using Emacs). If a single Control-C does not work, after 5 SIGINTs (C-c in a shell, C-q C-c when running Lisp under Emacs) will cause Lisp to be interrupted with a non-continuable error (a single SIGINT triggers a continuable error).

Note we say `C-q C-c' when in the Emacs-Lisp interface. Typically, C-c C-c sends a SIGINT to Lisp when running in Emacs. However, that sends it through the interface, and the interface will not process things while Lisp is in an infinite loop. C-q C-c cause the SIGINT to go directly to Lisp.

Warnings will be printed after 3 and 4 interrupts have been received, telling you that 2 more (after 3) or 1 more (after 4) will cause Lisp to signal a non-continuable error.

Lisp can do this because in fact, SIGINTs are recorded whenever they occur, but Lisp does not do anything until an appropriate moment (typically, at the beginning of a function call, unless the function was compiled in such a way as to suppress that check). If 5 SIGINTs are recorded without being handled, Lisp will now interrupt for sure. It does not matter when these SIGINTs happen (in foreign or Lisp code compiled in any fashion) except garbage collections will not be interrupted.

We chose five because users often enter several interrupts to interrupt a program, and we did not want normal behavior to trigger a non-continuable error. With the warnings mentioned above, we do not believe that users will unintentionally enter five interrupts without really wanting to break into the Lisp process.

Users should be warned that it is possible for an interrupt generated by 5 SIGINTs to leave the stack in a corrupted state. When you break into Lisp in this fashion, you should immediately enter :pop or :reset to try to clear the stack. In some cases, Lisp may not be able to recover. (Almost all those cases happen when foreign code is called with the call-direct argument to ff:def-foreign-call -- see foreign_functions.htm. Please note that some Franz code, particularly CLIM code, calls foreign code using call-direct. We have done several things to ensure Lisp is not corrupted even when the break occurs in a call-direct, but failure is a possibility.) However, it is likely that you will be able to recover (and recovery was typically not possible in earlier versions when an infinite loop was entered).

Users have tried (with more or less success) to break into Lisp from another shell by sending a Signal 4 or Signal 11 to the Lisp process. This can still be done (with the same success rate) but note that only SIGINTs (Signal 2) are recorded as counting to the 5 necessary to break for sure.

13.5 The Allegro Icon on the system tray will interrupt on Windows

The Break/Pause key will interrupt on Windows when the system is chcking for events. However, when Break/Pause does not work, look for the Allegro icon (a bust of Franz Liszt, after whom the company Franz Inc. was named), which appears in the system tray (at the lower right) of teh Windows screen. Right clicking on this icon will display a menu which includes the command Interrupt Lisp. Choosing that command will usually cause an error to be signaled within Lisp which will return control to the user. Note that there is a small probability that the interrupt will occur at a time when an interrupt cannot be processed and Lisp may fail.

It is usually possible to interrupt from the Console window (where you typically have a prompt that is responsive). The same menu over the Allegro icon on the system tray has a command to display the console if it is not already visible.

13.6 Help while running Lisp

There are a number of facilities to assist you while you are running Lisp. Some of them are listed in this section.

Some useful Common Lisp functions include apropos and describe. apropos takes a case-sensitive string (or a symbol whose print name will be used as the string) and an optional package as arguments and returns all symbols whose names contain the string. Thus, if you can't quite remember a function name, but are sure of part of it, call apropos with the part you are sure of. We recommend using the package argument, for without it apropos may return many symbols internal to the system or the compiler package which clutter up the output.

describe takes a Lisp object as an argument. It is especially useful when given a symbol. Included in the information it provides about the symbol are whether it has a function binding (with the formal argument list if it does), its package, whether it is internal or external in that package, whether it is bound, and its value if it is bound.

The function excl:arglist provides the argument list of functions and macros.

The top-level commands are listed when you enter the command :help with no arguments. All top-level commands are listed, with short descriptions. A longer description of a command is printed when you enter :help with a command name as an argument.

The function excl:print-startup-info (as its name implies) is used for printing information when Lisp starts up. However, the information can be useful at times other than start up. The functions uses the current values of variables, compiler optimization qualities, etc. to generate its message. Evaluating the following form will cause all available information to be printed:

(excl:print-startup-info t nil)

14.0 Files that may be looked for on startup and after startup

The following two tables list files that may be looked for when Allegro CL starts up and immediately afterwards.

Table 1 lists the files that Lisp may need to start up at all. Failure to find one will result in a message from the operating system or the executable itself explaining the failure. No recovery is possible.

Table 2 lists other files that Lisp may need during or after startup. Failure to find these files may cause a Lisp warning or error. Failure to find a file in some cases causes Lisp to exit.

We distinguish between system files, application files, and user files. System files are supplied as part of Allegro CL, the operating system, or other system components such as the window system; application files are those loaded into Lisp by the application programmer prior to the creation of the executable image; user files are additional runtime files belonging to the current user and referenced after the executable image is invoked.

Certain of the files in Table 1 are looked for in the Allegro directory location.

After all the needed files in the above table are found, the logical pathname translations for SYS: are established to refer to the Allegro directory. The ALLEGRO_CL_HOME environment variable, used in release 4.3 to find files, is no longer used to locate files.

Copyright (C) 1998-1999, Franz Inc., Berkeley, CA. All Rights Reserved.