Allegro CL Startup

The index for the Allegro CL Documentation is in index.htm. The documentation is described in introduction.htm.

The Allegro directory is the directory where Allegro CL was installed. In it is the executable (see 2.0 Allegro CL Executables below for executable names) and one or more standard images (with extension dxl and names the same as the executable names) 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\acl60 and on Unix is /usr/acl60.

2.0 Allegro CL Executables

Allegro CL 6.0 comes in at least four varieties, depending on the internal representation of strings and characters (whether 16 or 8 bits per character), and the case mode (whether ANSI or modern). Therefore, your distibution will have at least the following executables and corresponding image (dxl) files. Note too that on Windows, the executable files have extension .exe, while on Unix, the executables have no extension.

Note for Trial edition users: On UNIX paltforms, only one executable/image is supplied. On all UNIX platforms it is mlisp/mlisp.img (modern supporting international characters). A readme in the Allegro directory tells you how to build other types of images. On Windows, none of the four executables/images listed next are supplied. Only allegro-ansi.exe/allegro-ansi.img, described after the bulleted list.

On Windows, there are two additional executables: allegro.exe and allegro-ansi.exe. Both are copies of mlisp.exe. They are associated with images (same name, extension dxl) that include the Common Graphics/IDE code and, when invoked, start the IDE automatically. (Trial users: only one executable/image is supplied: the allegro-ansi.exe/allegro-ansi.exe (ANSI with the IDE supporting international characters). A readme.txt in the Allegro directory tells you how to build other types of images.)

Allegro CL has always supported modern (case-sensitive, lowercase preferred) mode, but release 6.0 is the first where a modern image and executable is supplied. We believe the benefits of using modern mode outweigh the slight inconveniences of porting case-insensitive code to it.

Allegro CL has also for some time supported international character sets, but with a special, add-on version called International Allegro CL. Starting in release 6.0, standard Allegro CL supports 16-bit characters (and strings) and does not support 8-bit characters. Because of automatic compatibility routines when loading text files, most users who do not use international character sets will not notice the change. However, some may (for example, users with applications that manipulate very large ASCII strings) and those users may wish to use the 8-bit versions. Note that a fasl file containing a string constant compiled in the standard (16-bit) Lisp cannot be loaded into the 8-bit version, but fasl files with string constants compiled in the 8-bit version can be loaded into the standard version.

Because of the multiplicity of executable names, we will refer to the executable as mlisp in the document unless there is some reason to refer to a different version.

Special executables for AllegroStore users on SGI's and some HP's

On HP's running HP/UX 11 and all SGI machines, there are special executables for AllegroStore only: aslisp is the 16-bit character version with AllegroStore and aslisp8 is the 8-bit character version.

3.0 The Allegro CL license file

Allegro CL uses a license file, devel.lic in the Allegro directory. This file must be present and have proper contents in order for Allegro CL to start. If the file is not present or does not have the proper contents, Lisp fails to start with a message like the following example from the Windows version, which appears in a pop-up dialog. On UNIX, the message (with a different path) appears in a shell window or in an Emacs buffer.

Note that the name of the license must be devel.lic. A valid file with a different name will not work (but the fix is easy -- copy that file to devel.lic in the Allegro directory).

This license file is not included on the distribution CD (or as part of the trial download). As described in installation.htm, information on obtaining license files is sent to Professional and Enterprise customers. Trial users obtain a license file by following the instructions on the Franz Inc. website (www.franz.com). If you do not have a license file or your license file is not valid, please contact Franz Inc. See Where to report bugs and send questions in introduction.htm.

Along with allowing Allegro CL to start up, the license indicates which add-on products and utilities are licensed, and prevents access to unlicensed products and utilities. If you believe you are licensed for a product or utility but the license file prevents you from using it, again, contact Franz Inc. See Where to report bugs and send questions in introduction.htm.

Here is what a license file looks like. It is a text file, but some of the text (the actual license parts) are encrypted. This is a bogus file, of course, with the encrypted portions much modified (and much shortened). We provide it so you can see what a license file looks like. This license file is used internally at Franz Inc. (as it says). It also has an expiration date. Trial versions will have an expiration date. Licensed versions (that is, to paying customers) have no expiration date.

4.0 Starting Allegro CL

4.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, you must run Lisp as a subprocess of Emacs.

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

See 5.0 Command line arguments for information on starting under emacs and for information on command-line arguments including the -I argument. See 2.0 Allegro CL Executables for the names of executables other than mlisp.

4.1.1 Starting on UNIX using a shell script

Where -#D is used for debugging (a backtrace is printed when an error occurs), -#C is used to have the script compiled, and -#! just loads the script.

4.2 Starting on Windows machines

There is an Allegro 6.0 menu item on the Windows Start menu (under Programs). Choosing it displays a submenu, whose items include Modern images and ANSI Images. These two display submenus with various choices, the first submenu of modern (case-sensitive) images and the second of ANSI (case-insensitive) images. On each, the item `Allegro CL (w IDE)' starts Allegro CL with the IDE and starts the IDE automatically.

If you want to start without using a menu item, you can choose Run from the start menu, then specify the executable file, image file, and any additional needed or desired arguments (described in 5.0 Command line arguments), like this:

4.2.1 Starting Allegro CL on Windows as a Console App

You can start Allegro CL on Windows as a Console Application by using the executable build.exe rather than mlisp.exe. build.exe is a WIN32 console application, whereas mlisp.exe is a WIN32 Windows application. If you want to run a command-line oriented version of ACL, use build.exe.

Note that there are issues with multiprocessing and build.exe. build.exe sometimes cannot tell if input is available or if a process that is waiting on input should wake up. For this reason, we recommend you do not use build.exe with multiprocessing applications.

Note further that build.exe does not accept the arguments that begin with +. Command-line argument are described in 5.0 Command line arguments.

4.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/acl60/mlisp and no dxl file is specified, /usr/acl60/mlisp.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).

4.4 The executable and image names

See 2.0 Allegro CL Executables for the names of all executables supplied with Allegro CL 6.0. The name of the standard executable is mlisp on Unix and mlisp.exe on Windows. Any 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 dumplisp and 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 mlisp or mlisp.exe, as the example is on Unix or on Windows, and the image mlisp.dxl or, on Windows when using the IDE, allegro.dxl or allegro-ansi.dxl. When the platform is not explicit, either mlisp or mlisp.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.

4.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 cannot 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 the section on Resources. See that document for information on determining whether resources are being used and for information on specifying them for applications.

5.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 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):

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

-: (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 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 describe 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 -.

Argument	Effect	See notes
`-:`	UNIX only. Causes the Lisp shared library (libacl<version>.so or libacl<version>.sl) to be searched for in a system-dependent way. On Solaris 2 this means using the environment variable LD_LIBRARY_PATH; other systems might use other ways. This argument must precede all others. (This argument is processed by the executable before the image file is loaded.)
`-I` `image-file`	Specifies the image file to use. This image must have been created with dumplisp or its relative build-lisp-image (or generate-application). The filename of the image file *must* have an extension (the standard extension is dxl but any extension will do). If the extension is dxl, the image can be specified without .dxl, so these are equivalent: `mlisp -I foo.dxl` `mlisp -I foo` If the extension is something other than dxl, it must be specified: `mlisp -I foo.xxx` mlisp.exe (Windows) or mlisp (Unix) handles the -I command line argument specially: if mlisp.exe/mlisp is started without an image file (i.e., no -I argument), then it will first look for an image file with the name of the executable and the type dxl in the current directory, then in the same directory as the executable file. (On Windows, these two directories are often the same but need not be, particularly if you are starting from a DOS prompt. On Unix, the current directory is the result of pwd typed to the prompt used to start Allegro CL.) That is, if you start c:\x\y\z\mlisp.exe it will look for the image file c:\x\y\z\mlisp.dxl. If it fails to find that image file it will prompt for an image file. Note: you can change the name of mlisp.exe/mlisp if you are delivering an application. If you change mlisp.exe/mlisp to myapp.exe/myapp then when myapp.exe/myapp starts it will look for myapp.dxl. If more than one �I argument is specified, the first (leftmost) is used and the remainder are ignored. (This means that if a �I argument is specified as a resource, it cannot be overridden. See the section on Resources in delivery.htm for information on resources.)
`-q`	Read working directory .clinit.cl or clinit.cl and sys:siteinit.cl, but do not read ~/.clinit.cl or ~/clinit.cl unless ~ is also the working directory. On Unix, the working directory is specified to Emacs, or, the current directory if starting in a shell. 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. On Unix ~ refers to the user's home directory. On Windows, the home directory is C:\. sys:siteinit.cl is hardwired in the system. The actual names of the other initialization files are in a list which is the value of `init-file-names`, whose initial value is (.clinit.cl clinit.cl) � that is clinit.cl with and without a leading dot. Do not also specify -qq.
`-qq`	Do not read sys:siteinit.cl or any initialization file. Do not also specify -q.
`-C` `file`	evaluates `(compile-filefile)`
`-d` `file`	Causes dribbling to file.
`-H` `directory`	Sets the Allegro directory location (the translation of the sys: logical host, the location where Lisp library files will be looked for). If this argument is unspecified, the Allegro directory location is the directory where the executable (mlisp.exe/mlisp) is located.
`-kill`	Evaluates (exit 0). That is, Lisp exits. Presumably you have other arguments which do things (like �C compiling a file) earlier in the list of command line arguments. Thus mlisp.exe �C foo.cl �kill will start Allegro CL, compile foo.cl, and exit.
`-L file`	Evaluates (load (string file)). Only one file per �L argument but as many �L arguments as desired can be specified. The �L arguments are processed from left to right.	1, 4
`-locale locale-name`	Sets the initial locale (the initial value of `locale`) to the locale named by locale-name, which must be the name of a locale available on the machine. See The initial locale when Allegro CL starts up and Locales, both in iacl.htm for details.	1, 4
`-Q`	Unused in 6.0. In 5.0.1 and earlier, this argument suppressed printing the name of the image and library file, but in 6.0, those filenames are not printed in any case. This argument will likely be removed in a later release but is kept in 6.0 for backward compatibility.
`-W`	Evaluates `(setq break-on-warnings t)`
`-e form`	Evaluates form.	1, 2, 3, 4
`-batch`	Run in batch mode: input comes from standard input, exit when an EOF is read. Exit on any error (but print a backtrace to error-output if -backtrace-on-error also specified).	5
`-backtrace-on-error`	Print a complete backtrace (as printed by :zoom :all t :count nil) whenever an error occurs.	6
`-compat-crlf`	When specified, #\return #\linefeed translates to '13 10' (as it did in release 5.0.1) instead of '13 13 10' (as it will in release 6.0 without this option). See #\newline Discussion in iacl.htm for details. Only users with code from Allegro CL 5.0/5.0.1 for Windows should even consider using this option, and most of those do not need it.	6
`-!`	Please see Special Note on the -! command-line argument below. This argument should only be used in unusual debugging situations and should never be used in ordinary situations.
`-project` project-lpr-file	[Windows when running the Integrated Development Environment only] have the project specified by the indicated project .lpr file be the current project when the IDE is started. See About IDE startup in cgide.htm.	6

Table notes:

Special note on the -! command-line argument

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.

6.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 16.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 16.0 Files that may be looked for on startup and after startup or to delivery.htm.

6.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).

6.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 systems 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 mlisp.exe on Windows and mlisp 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.

7.0 The start-up message

When Lisp starts up, 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.

Then (technically as part of the banner) information on who this version of Allegro CL is licensed to is printed.

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 actual Current reader case mode type depends on the type of image, this example is from a modern image):

8.0 Running Lisp as a subprocess of Emacs

8.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.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.

(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:

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

8.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:

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

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:

8.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:

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:

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:

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

8.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.

9.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 mlisp 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 mlisp.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 mlisp/mlisp.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.

10.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 *restart-actions*). The recommended action is to try to start again without the -e arguments or to use -e arguments to set the value of *restart-actions* to nil (perhaps first making it the value of another variable which can be examined after startup succeeds).

11.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

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.)

11.1 How to exit for sure

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

12.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 src/aclstart.cl (in the Allegro directory), which contains the source to the startup code.

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:

13.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 *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:

The value of the variable *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.

13.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:

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:

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

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

13.2 No top-level commands in initialization files

Top-level commands (prefixed by the top-level command character) cannot 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 top-level.htm). 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.

13.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:

13.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.

14.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.

14.1 Where are the bindings defined?

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

Notice that most of the entries in *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 *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:

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

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

14.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

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

14.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.

15.0 After Lisp starts up

15.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:

Here, CL-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.

15.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:

15.3 What if the system seems to hang?

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).

15.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 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.

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

The Break/Pause key will interrupt on Windows when the system is checking 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 the 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 possibility 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.

15.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 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 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 function 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:

16.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.

Argument	Effect
+c	Start ACL without a console window. Normally, there is a console window to read/write standard I/O. If you close the console window, the Lisp will be killed.
+cm	Start the console window in a minimized state.
+cn	Start the console window, but don't activate the console window. This allows Lisp to be started so as to not interfere with the currently selected window.
+cx	Start the console in a hidden state. Double-clicking on the tray icon will make the console visible. See also the right-click menu on the tray icon.
+cc	Causes any earlier +c, +cm, +cn, or +cx argument, including those specified as a resource, to be ignored. (The purpose of this argument is to overide such arguments specified as resources, see the section on Resources in delivery.htm.) Any of +c, +cm, +cn, or +cx can be specified and will be effective after +cc.
+p	Preserve the console window. Without this switch the console window goes away when Lisp exits with a zero exit status. If ACL is exiting unexpectedly you can use this switch to keep the window around to find out what it printed before it died. This is the opposite of the +M argument.
+R	Don't put the ACL icon in the tray.
+RR	Do put the ACL icon in the tray. This argument is useful when +R (described just above) is in a resource command line and you wish to override it. It is not necessary to specify this argument unless +R is specified in a resource. See Resources in delivery.htm.
+s scriptfile	Standard input is initially bound to this file. When the file is completely read, standard input reverts to the console window, if there is one.
+M	When this argument is present the console window does not need to be closed manually when Lisp exits with a non-zero exit status. This is the opposite of the +p argument.
+d dll-name	Use the given ACL dll instead of the default acl<version>.dll.
+t title	Sets the title of the console to title.
+B	Use no splash screen (a window that appears very quickly to let you know that Lisp is starting).
+b text	Make the splash screen display text instead of the default bitmap. text just appears in a gray box.
+Bt	Put up splash screen for a fixed amount of time (3 seconds). The splash screen is stored in the image file. See the description of set-splash-screen.

Variable	Bound to
`package`	`package`
`readtable`	`readtable`
`source-pathname`	name of file being loaded
`redefinition-warnings`	redefinition-warnings
`libfasl`	value of libfasl keyword argument to load, if specified, or libfasl

Table 1: Files required for Lisp to start up
File type	When file is required	Where file is looked for
Application loaded .so/.sl/.dll files	When specified to :user-shared-libraries (argument to build-lisp-image)	Allegro directory, i.e. directory where executable (exe) file is located or see 6.1 Files Lisp needs to start up 1: .so (or dll) files built with image
.pll file (always a single file, e.g. acl.pll)	Image built with :pll-file non-nil.	Allegro directory location
Bundle file (typically files.bu or files.ebu)	Executable built as Presto image	Allegro directory location

Table 2: Files looked for during or after Lisp starts up
File	When file is needed	Comments
The bundle file (typically sys:files.bu or sys:files.ebu)	File needs to be autoloaded (because of a form in init file or restart function or because of system actions such as starting Lisp/Emacs interface)	None
System fasl files, e.g. sys:;code;loop.fasl	As above for fasl files not in bundle.	Some system fasls are not included in the bundle file, and patched autoload fasl files supersede files in the bundle.
Loaded system .so files, e.g. sys:gc-cursor.so	Look in sys:.	None
Loaded application .so files	Found using LD_LIBRARY_PATH or equivalent.	None
[user-homedir]/.clinit.cl [user-homedir]/clinit.cl	Loaded during initialization unless: (1) -q or -qq specified on command line; (2) image created with :read-init-file (argument to dumplisp) nil; or (3) Specified restart function does not return. The homedir on Windows is C:\.	None
sys:;siteinit.cl	Loaded during initialization unless (1) `read-init-files` is `nil`, or (2) -qq command-line argument specified	None
[current-dir]/.clinit.cl [current-dir]/clinit.cl	Loaded during initialization unless: (1) -qq specified on command line; (2) `read-init-files` is `nil` or `:nohome`, or (3) specified restart function does not return. The current directory on Windows (on startup) is the directory containing the executable (usually mlisp.exe) file.	The names are specified in the list which is the value of `init-file-names`, whose initial value is `(.clinit.cl clinit.cl)`. If that variable is nil, no file will be looked for. Only one file, the first one found looking in the order they appear in the list, will be loaded. If both .clinit.cl and clinit.cl are in a directory, only .clinit.cl will be loaded (assuming `init-file-names` has its initial value).
sys:;hosts.cl	load-logical-pathname-translations is called.	Will also look in files returned by logical-pathname-translations-database-pathnames. See the description of that function for details.