Allegro CL Startup

1.0 The Allegro directory

The Allegro directory is the directory where Allegro CL was installed. In it is the executable (see Allegro CL Executables: alisp, alisp8, mlisp, mlisp8, allegro, allegro-ansi, allegro-express 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\aclNN (where NN is the version number with the dots removed -- like 81, 82, 90) and on Unix is /usr/local/aclNN.

On most platforms, Allegro CL is distributed in two forms: the SMP version and the non-SMP version. Each has its own directory and can be considered a separate distribution. Allegro directory refers to the non-SMP directory when you are using the non-SMP version and the SMP directory when you are using the SMP version.

2.0 Allegro CL Executables: alisp, alisp8, mlisp, mlisp8, allegro, allegro-ansi, allegro-express

Allegro CL 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 Express edition users: On UNIX platforms, only one executable/image is supplied. On all UNIX platforms it is alisp/alisp.dxl (ANSI supporting international characters). A readme file in the Allegro directory tells you how to build other types of images (but only 16-bit images can be built). On Windows, none of the four executables/images listed next are supplied. Only allegro-express.exe/allegro-express.dxl, described after the bulleted list.

• mlisp (mlisp.exe on Windows): Common Lisp, modern mode (case sensitive lower, supports international 16-bit characters). Some Allegro CL-based products work better in this mode, AllegroServe and Allegro ORBLink being two.

• mlisp8 (mlisp8.exe on Windows): Common Lisp, modern mode (case sensitive lower, uses 8-bit characters and cannot support international character sets).

• alisp (alisp.exe on Windows): Common Lisp, ANSI mode (case insensitive upper, supports international 16-bit characters). Not all Allegro CL-based products work well in this mode -- modern languages such as C, C++, and XML are case sensitive, and supporting interfaces to these languages in a case insensitive Lisp is difficult. This is a copy of mlisp (mlisp.exe on Windows), renamed simply to start the image of the same name (and extension dxl).

• alisp8 (alisp8.exe on Windows): Common Lisp, ANSI mode (case insensitive upper, uses 8-bit characters and cannot support international character sets). This is a copy of mlisp8 (mlisp8.exe on Windows), renamed simply to start the image of the same name (and extension dxl).

On Windows and on Linux using Intel x86 processors, there are two additional executables: allegro.exe and allegro-ansi.exe. Both are copies of mlisp.exe, and so support 16-bit characters. They are associated with images (same name, extension dxl) that include the Common Graphics/IDE code and, when invoked, start the IDE automatically. Allegro Express users: only one executable/image is supplied: allegro-express.exe/allegro-express.dxl, equivalent to allegro-ansi.exe/allegro-ansi.dxl (ANSI with the IDE supporting international characters). A readme.txt in the Allegro directory tells you how to build other types of images.) See How to create an 8-bit image which starts the IDE in cgide.html for information on building an 8-bit image that includes the IDE and invokes it on startup.

Allegro CL has always supported modern (case-sensitive, lowercase preferred) mode, but, starting with release 6.0, a modern image and executable are 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 this document unless there is some reason to refer to a different version.

3.0 The Allegro CL license file

Allegro CL uses a license file, with name 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 will fail to start with a message similar to the following:

Missing or invalid license file (C:\Program Files\ACL81\devel.lic).
Lisp cannot start up.

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 Express download). As described in installation.html, information on obtaining license files is sent to Professional and Enterprise customers. Express users obtain a license file by following the instructions on the Franz Inc. website (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 index.html.

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 index.html.

Here is what a license file looks like. It is a text file, but some of the text (the actual license parts) is 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. Express versions will have an expiration date. Licensed versions (that is, to paying customers) have no expiration date.

;; BEGINNING OF FILE

;; This text should be saved to a file named devel.lic
;; in the Allegro directory.  Make sure the first line
;; in the file is ``;; BEGINNING OF FILE'', and that
;; there is no other text preceding the first
;; semi-colon (;) on that line.  Make sure the last
;; line in the file is ``;; END OF FILE''.

;; This license file is for version 11.0 of Allegro
;; CL.  It is not possible to use it with other
;; versions of Allegro CL.

;; This file contains the licenses necessary to
;; execute Allegro CL and add-on products.  Preceding
;; each license there is a comment describing the
;; contents of the encrypted block of text.  Included
;; in the encrypted text is information identifying
;; the licensee.

;; If you have questions or comments, please contact
;; us at [email protected] +1 510-452-2000, Franz
;; Inc., 3685 Mt Diablo Blvd, Suite 300, Lafayette, CA
;; 94549-6884, USA).
;;
;; License created on March 2, 2023, 14:51:55.

;; 
;; If your email address changes, please visit
;; http://franz.com/lfs/emailupdate to notify Franz
;; Inc. of your new email address and to get a new
;; license file containing this new email address.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; ACL version: 11.0
;; ACL type: enterprise
;; Architecture: ...
;; Licensed to: tester for ACL 11.0 pre-beta
;; Email address: [email protected]
;; Expiration date: 2023-5-15 00:00:00
;; AllegroCache # connections limit: unlimited
;; AllegroCache # objects limit: unlimited
;; AllegroCache # commits limit: unlimited
;; AllegroCache # classes limit: unlimited
;; Features: runtime generate-application aodbc
;;   enterprise-ssl enterprise-jlinker demo180 partners
(:lisp
 "...")

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; ACL version: 11.0
;; Architecture: ...
;; Licensed to: tester for ACL 11.0 pre-beta
;; Email address: [email protected]
;; Expiration date: 2023-5-15 00:00:00
(:dynamic-runtime
 "...")
...

;; END OF FILE

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 as follows. Note the -I argument, if specified, must be first.

$ mlisp [-I <image path and name>.dxl] [other args]

See Command line arguments for information on starting under emacs and for information on command-line arguments including the -I argument. See Allegro CL Executables: alisp, alisp8, mlisp, mlisp8, allegro, allegro-ansi, allegro-express for the names of executables other than mlisp.

4.1.1 Starting using a shell script

Shell scripts work on UNIX and on Windows in UNIX-like enviroment and command-line interfaces such as Cygwin. (See Starting on Windows using bat files for information on starting on Windows using a bat file.)

The UNIX feature of having a file that starts with !# (called hashbang or poundbang)

#! <program> <args>

works with Allegro CL on UNIX platforms and UNIX-like shells on Windows. Here is the form:

#! <lisp-executable> { -#D | -#C | #T | -#! }
[Lisp forms to be executed]

Where:

• is the name of the Allegro CL executable file. Note: cannot itself be a shell script: it must be one of the actual executable files, such as mlisp. Generally its full path is specified although a path relative to the location of the script file should also work.

  Initialization files are never read when Lisp is started with a script. So Lisp is started as if the command-line argument --qq was specified. See Command line arguments for information on command-line arguments.

• -#D is used for debugging (a backtrace is printed when an error occurs). The ACL_HASHBANG_DEBUG environment variable, if set, specifies this argument.

• -#C is used to have the script compiled. The ACL_HASHBANG_COMPILE environment variable, if set, specifies this argument.

• -#T is like -#C, in that the script is compiled, but the compiled script is placed in /tmp rather than the directory containing the script, and so the user need not have write permission in that directory. The ACL_HASHBANG_TEMPCOMPILE environment variable, if set, specifies this argument.

• -#! just loads the script.

• The [Lisp forms to be executed] are just ordinary Lisp forms.

The file may also have the following format:

#! /usr/bin/env mlisp
(format t "CLA = ~s~%" (sys:command-line-arguments))

Command-line argument are supplied either in the script file or to the script file or both:

foo.cl:

#! mlisp 1 2 3
(format t "CLA = ~s~%" (sys:command-line-arguments))

and

$ foo.cl
CLA = ("mlisp" "1" "2" "3")

$ foo.cl 4 5 6
CLA = ("mlisp" "1" "2" "3" "4" "5" "6")

You can also specify the full path of the Lisp executable, as in

#! /some/path/to/mlisp
(format t "CLA = ~s~%" (sys:command-line-arguments))

Scripts run using #! that signal an error will exit with a non-zero exit status.

Here's an example. Put this in a file hello_world.cl.

#! /usr/local/acl/mlisp -#!
(format t "Hello World!~%")

Then,

$ chmod 755 hello_world.cl
$ ./hello_world.cl
Hello World!
$ 

Operating system notes

Because different versions of UNIX handle shell scripts like these differently, there may be differences in how these scripts function on different platforms. Please test the simple example before trying a more complex one.

• macOS: "#" appears to be a comment character on the hashbang line, so

  #! mlisp -1#2

  will result in script getting arguments ("mlisp" "-1").

• Windows: shell scripts have only been tested with Cygwin.

Environment variables affecting shell scripts

The following environment variables change hashbang behavior:

• ACL_HASHBANG_DEBUG is like -#D
• ACL_HASHBANG_COMPILE is like -#C
• ACL_HASHBANG_TEMPCOMPILE is like -#T

Other notes

Hashbang scripts can also be used by development executables. For example, if the file "foo.cl" has this contents:

#! ...
(format t "CLA = ~s~%" (sys:command-line-arguments))

then it can be invoked with

$ mlisp foo.cl 1 2 3
CLA = ("mlisp" "1" "2" "3")
$

cl:load has a new keyword argument, script, which defaults to t. When script is non-nil, cl:load will ignore the first line of a source file if it starts with character #\# followed by #\!. (The ANS description of load is here, but it does not mention the script argument. The Allegro CL implementation, documenting the script argument along with other additional arguments, is described in the loading.html document.)

The script file path

The variable *script-name* is bound to the name of the script file being run when Allegro CL is being executed by a UNIX script file.

For example, consider this script file test.cl:

#! mlisp -#T
(format t "-#T ~a~%" *script-name*)

Here is that script being run:

$ ./test.cl
-#T ./test.cl
$ 

compile-file can skip the first line of a file being compiled

compile-file has an additional (Allegro CL-only) keyword argument :script. If true, the first line of the file being compiled will be skipped if the first two characters are #!. This allows a UNIX script file (whose first line begin with those two characters) to be compiled and loaded as ordinary Lisp files as well as being run as shell scripts. See compile-file in compiling.html.

fasl files can be appended to scripts

The following transcript show this capability.

$ cat foo.cl
(in-package :user)

(format t "foo!~%")

$ mlisp
International Allegro CL [master]

;; Optimization settings: safety 1, space 1, speed 1, debug 2.
;; For a complete description of all compiler switches given the current
;; optimization settings evaluate (explain-compiler-settings).
;;---
;; Current reader case mode: :case-sensitive-lower
cl-user(1): :cf foo.cl
;;; Compiling file foo.cl
;;; Writing fasl file foo.fasl
;;; Fasl write complete
cl-user(2): :exit
; Exiting

$ echo '#! usr/local/acl/mlisp -#!' > foo.sh
$ cat foo.fasl  >> foo.sh
$ chmod 755 foo.sh
$ ./foo.sh
foo!
$ 

4.2 Starting on Windows machines

A typical way to run on Windows is with the Integrated Development Environment (IDE). The IDE is discussed in cgide.html. Particularly see the section About IDE startup for information about IDE startup. Information is provided there about the startup steps and about the IDE-specific files that are read on startip (in addition to the .clinit.cl and siteinit.cl files common to all Allegro CL images -- see Initialization and the sys:siteinit.cl and [.]clinit.cl files below).

The rest of this section discusses general issues of starting on Windows and starting without the IDE.

There is an Allegro CL 11.0 menu item on the Windows All Programs (the Start menu in earlier versions of Windows). Choosing it displays a submenu, whose items include Modern ACL images and ANSI ACL 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.

To start using Emacs, see Running Lisp as a subprocess of Emacs. See Command line arguments for information on command-line arguments, including the -I argument (which specifies the image to use). See Allegro CL Executables: alisp, alisp8, mlisp, mlisp8, allegro, allegro-ansi, allegro-express for the names of executables other than mlisp.exe.

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 Command line arguments), like this:

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

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 Allegro CL, 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 arguments are described in Command line arguments.

4.2.2 Starting on Windows using bat files

While you cannot use a shell script to start Lisp at a Windows command prompt, you can in a shell provided by in UNIX-like enviroment and command-line interface such as Cygwin. See Starting using a shell script above for more information.

Suppose you want to create a quick application where Lisp is started, executes a number of forms, and then exits. This can be done by creating an application (see delivery.html or building-images.html), but that is time-consuming and involves additional machinery that makes it not quick enough. You can tell potential users to start Lisp and then load a particular file, but users like simplicity. On UNIX, you can use a shell script (see Starting using a shell script but shell scripts do not work on Windows.

A facility on Windows allows using a Windows bat file to contain Lisp forms, so the bat file will start Lisp, execute the forms, and exit. The command-line arguments --bat and --bat-pause tell Lisp that it is being executed in a bat file (they are ignored on UNIX which does not support bat files). --bat executes the code in the bat file and exits. --bat-pause executes the code and then pauses until a user action such as hitting the Enter key (thus allowing the user to examine information displayed in some fashion).

You do not specify either of those arguments to a command line typed directly to a command prompt, to the dialog displayed by Start | Run, or in the command executed by a shortcut. (Doing so is not illegal, it just serves no practical purpose.) Instead, the arguments are used in the call invoking Lisp in the bat file. The arguments tell Lisp to expect additional forms (which are specified later in the bat file) and to exit immediately (--bat) or pause before exiting (--bat-pause).

The function lisp-to-bat-file creates a bat file from a Lisp source file and arguments which specify the executable, the image file, and other details. You should use this function to create the bat file. The function works on all platforms even though the bat file will only work on Windows. See the description of lisp-to-bat-file for further details and a link to an example.

4.3 The executable, the image, and additional files

Allegro CL requires at least two files: an executable, typical xtension 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/acl81/mlisp and no dxl file is specified, /usr/acl81/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 Allegro CL Executables: alisp, alisp8, mlisp, mlisp8, allegro, allegro-ansi, allegro-express for the names of all executables supplied with Allegro CL. The name of the standard executable is mlisp on Unix and mlisp.exe on Windows (alisp for express on UNIX and allegro-express.exe for Express 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) 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. Using resources is discouraged 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.html, 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 operators like the following:

• command-line-arguments: returns a list of command-line arguments.
• command-line-argument: returns a specific command-line argument.
• command-line-argument-count: returns the number of command-line argument.
• with-command-line-arguments: this macro binds variables to the values of specific command-line arguments during the execution of the macro body.

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). Note the -I argument, if specified, must be first among all arguments starting with a -.

$ mlisp.exe [acl-arguments starting with +] [-I dxl-file]
            [other acl-arguments starting with -] 
            [-- application-arguments]

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

$ mlisp [-:] [-I dxl-file] [acl-arguments starting with -] 
        [-- application-arguments]

-: (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. See the discussion of command-line arguments in Accessing command-line arguments in os-interface.html. See also with-command-line-arguments, which is a macro that can be used to process command-line arguments (and can be useful for processing application command-line arguments).

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

Command line arguments starting with a + [Windows only]

Allegro CL on Windows run without arguments beginning with a + starts with a console window (minimized when the IDE is started, otherwise visible); an icon in the system tray; the property that a non-zero exit status causes the console window to remain; with a close button on the console window; and with titles, filenames, and icon and menu item labels that are variants of Lisp, ACL, Allegro CL, etc. The following arguments can modify all of those things.

Command line arguments starting with a - [All platforms]

$ mlisp -I foo.dxl

$ mlisp -I foo

$ mlisp -I foo.xxx

Table notes:

1. All arguments, including -e form, --ee form, and -L file, are read and processed in order. Reading of one -e/--ee 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. Some global variables are not set as expected at the time arguments are processed. For example, *readtable* is set to the (read-only) system readtable. You can modify such values but it requires extra work. See The standard readtable is read-only, affect on with-standard-io-syntax and modifying the readtable in init files and with -e in implementation.html, where it shows how to modify *readtable* in an init file using a method that also applies also to -e, -ee, and -L.

3. 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/--ee 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.

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]/src/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.

7. --start-local-client Microsoft Windows note: Probably nothing will be printed (as shown above) when you run Allegro CL in this way on Windows. And so it is not obvious that anything is happening, except that there is no next prompt because the Lisp is running and waiting for a connection from a web browser. The simple solution for the port not being printed is to also specify a particular port with the -o / --browser-server-port command line option, though that could be a problem if another running program is already using that port. The less convenient (but foolproof) solution would be to also pass the -i / --port-file option that writes the free port that the OS selected into the specified file, where you would then need to read the port to use from that file.

8. --start-local-client SECURITY NOTE: there are security implications to the -l no/--start-local-client no command line arguments: the Lisp server created will listen on interfaces that include connections from hosts other than just localhost. If you are running Allegro CL in an environment where this is not advised, then please do not run the server in this mode. It is recommended that you discuss this with your IT department if you are unsure whether this is a good idea or not.

Further description of the -e and --ee command-line arguments

Both -e and --ee take a form as a companion argument, The problem with the -e argument is that certain characters, such as the space charcater, might be part of the form or it might be a delimiter indicating the start of a new command-line argument. The system has difficulty distinguishing those cases.

The traditional way to get around that problem is to escape such characters, typically with a \ (backslash), or to wrap the companion argument is single or double quotes. Suppose, for example, you want to evaluate the form (setq foo 10) at startup. In answer to the 'Image arguments' question asked by fi:common-lisp (the Emacs function to start Allegro CL), you could put:

-e (setq\ foo\ 10)

And starting Lisp as a shell prompt, you might do

$ mlisp -e '(setq foo 10)'

These solutions generally work, but the escaping becomes more complicated with more complex forms. Further, when writing shell scripts to start Allegro CL, the shell processing may undo the escapes at the wrong time so when the argument is actually read, the characters that need escapes no longer have them.

The --ee argument is designed to get around that problem. When a --ee form argument is processed, the companion argument is scanned for character triplets of the form %hh, when hh is a pair of Hex numbers (0-9abcdef). Every %hh triplet is replaced by the character whose char-code is hh. Then the companion argument is processed.

Frequently used codes include:

• #\( -- code %28
• #\) -- code %29
• #\: -- code %3a
• #\space -- code %20
• #\% -- code %25

The (setq foo 10) argument could then be passed as

$ mlisp --ee '%28setq%20foo%2010%29'

Thus the notation allows Lisp forms to be passed as a single OS token unaffected by command line parsing or substitutions.

The function make-escaped-string takes a Lisp form (as a string) and returns a properly converted string where the characters that need to be escaped are replaced with the appropriate %hh triple.

Note that only characters with char-codes less than 256 can be represented.

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 start up 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 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 Files that may be looked for on startup and after startup or to delivery.html.

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

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.

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 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 (i.e (translate-logical-pathname "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):

International Allegro CL [enterprise]
8.1 [Linux (x86)] (Jul 18, 2007 13:20)
Copyright (C) 1985-2007, Franz Inc., Oakland, CA, USA.  All Rights Reserved.

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

;; Optimization settings: safety 1, space 1, speed 1, debug 2
;; For a complete description of all compiler switches given the
;; current optimization settings evaluate (EXPLAIN-COMPILER-SETTINGS).
;; --
;; Current reader case mode: :case-sensitive-lower

(The number of lines may differ.)

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

8.0 Running Lisp as a subprocess of Emacs

Your Emacs should have loaded all the Emacs-Lisp interface definitions. See What should be in your .emacs file in eli.html for details.

If you are using the Integrated Development Environment on Windows, see Using the IDE with Emacs below. Otherwise, see Starting Lisp as a subprocess of Emacs the first time just below.

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

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 6 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. This directory will be the one returned by current-directory and the initial value of *default-pathname-defaults* after Lisp starts.

4. Executable Image Name: the name of the Lisp executable. This is a small file. Its name has no extension on UNIX and has extension (type) exe on Windows. Various executable files are shipped with the Allegro CL distribution. The file itself is not typically created or modified at customer sites.

   There are two distinct executable files and often several copies of each. One executable file uses 16-bit characters (copies are named, for example, mlisp/mlisp.exe and alisp/alisp.exe). The other uses 8-bit characters (copies are named, for example, mlisp8/mlisp8.exe and alisp8/alisp8.exe). On Windows and Linux on Intel x86 processors, there is also allegro.exe and allegro-ansi.exe. The filename is used to determine the image name (so mlisp/mlisp.exe looks for the image file mlisp.dxl, and so on).

   The default is the value of the Emacs variable fi:common-lisp-image-name. (The name is historic: in earlier versions the executable file and the image file were the same. Now they are different. The variable fi:common-lisp-image-file has the image file as its value.)

5. Image: the name of the Lisp image (.dxl) file. The default is the value of the Emacs variable fi:common-lisp-image-file. (Note that, for historic reasons, the emacs variable fi:common-lisp-image-name names the executable file.) If this argument is not specified, its value is assumed to be the file in the same directory as the executable image name with the same name but with extension .dxl. Thus, if Executable Image Name is mlisp, the file mlisp.dxl in the same directory of mlisp will be looked for if this argument is unspecified.

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 (it may take several tries to get it right). The default is the value of the Emacs variable fi:common-lisp-image-arguments. Enter nothing if you want no arguments.

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

You can write your own Emacs function to call fi:common-lisp with your desired values (and thus avoid having to input values). See Functions and variables for Interacting with a CL subprocess in eli.html for examples of such functions.

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.

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:

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

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:

;; 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 by calling start-emacs-lisp-interface:

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

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.html). 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 or allegro-ansi.dxl as the Image file.

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

$ mlisp [-I <image>.dxl] [acl-arguments starting with -] \
        [-- user-supplied-arguments]

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

$ mlisp.exe [-I <image>.dxl] [acl-arguments starting with -] \
            [-- user-supplied-arguments]

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 operating system's 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).

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

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

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. Calling the function exit:

(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.html. 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. You may have to respond to questions (about, for example, whether certain processes should indeed be killed) before exiting completes. If you are running on Windows using the IDE (see cgide.html), you will usually have to confirm the exit by clicking Yes on a modal dialog asking if you really want to exit Lisp, and, often, also indicate whether unsaved files should be saved.

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. (The Emacs-Lisp interface uses 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:

(excl:exit 0 :no-unwind t :quiet t)

The no-unwind argument, when t, tells Lisp to try to exit without unwinding unwind-protect'ed forms. The quiet argument suppresses output (which might cause a problem in an Emacs *background-interaction* buffer).

The exit code (first argument) 0 is important, at least on Windows. A non-zero exit code may keep the Lisp console on Windows from exiting. See exit for more information.

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.

1. The initial value of *locale* is set. (See The initial locale when Allegro CL starts up in iacl.html for details. Note that the --locale command-line argument is not examined until command-line processing is done several steps down.)

2. All logical pathnames translations are flushed. The translations may have been defined in the parent image (particularly if the image was created with 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 logical-pathname-translations-database-pathnames. sys:hosts.cl is on that list. sys: itself translates to the Allegro directory.

3. On Windows NT/2000, the affinity (number of physical processors to be used) is set to 1. See processor-affinity-mask.

4. 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 *initial-terminal-io*.

5. 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. account manager if this is an issue.)

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

7. Command-line arguments are processed. All -e and -L arguments are processed, in order, at this time. (A -e argument specifies a form to evaluate. A -L argument specifies a file to load.)

8. Initialization files are read. The files are sys:siteinit.cl, the two user initialization files. Whether the files are read and exactly which files are read depends on the value of *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 *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.

9. The startup messages are printed. The function print-startup-info is called to print the message.

10. On Windows the PATH environment variable is modified to include the Allegro CL directory. Code similar to the following is run:

    #+mswindows
    (setf (sys:getenv "PATH")
      (concatenate 'simple-string
    (sys:getenv "PATH") ";" (namestring (truename "sys:"))))

    This allows Allegro CL to find DLL's located in the Allegro directory. The PATH variable is not permanently changed or changed for other programs by this action.

11. Restart actions are performed. The functions on the *restart-actions* list are called.

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

13. The restart init function is called. If *restart-init-function* is non-nil, its value is assumed to be a function of no arguments and it is funcall'ed.

14. 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 *restart-app-function* is true, 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 *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-12 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 12 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, *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 restart-app-function nil)", Lisp will start a Lisp listener instead of calling *restart-app-function*. We strongly advise against setting this environment variable except in an emergency.

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:

• 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, the home directory (the translation of ~) is HOMEDRIVE/HOMEPATH (i.e. the concatenation of the value of the HOMEDRIVE environment variable, the string "/", and the value of the HOMEPATH environment variable). The value of the HOME environment variable is used if HOMEDRIVE/HOMEPATH is not set. C:\ is used if HOMEDRIVE/HOMEPATH and HOME are not set.

• /.clinit.cl or /clinit.cl (unless the 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 *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.

Note of files read when starting the IDE

When starting the IDE on Windows or UNIX, additional files are read at startup, including a file named startup.cl. See About IDE startup in cgide.html for details.

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:

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

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. do-command does provide a functional equivalent of a top-level command (see the description in top-level.html). 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:

• *package* is bound to the current value of *package*
• *readtable* is bound to the current value of *readtable*
• *source-pathname* is bound to the name of the file being loaded, as a pathname
• *redefinition-warnings* is bound to the current value of *redefinition-warnings*

13.4 Delaying evaluation of a form in an init file

Init files are processed very early in the startup sequence (see the section What Lisp does when it starts up above). It can happen that you want to evaluate some form but things are not set up sufficiently when the init file is read to do the evaluation. In that case you can use code similar to the following:

(defun run-form-from-clinit-file-later ()
  (let ((initial-restart-init-function *restart-init-function*))
    (cond (initial-restart-init-function
            (setf *restart-init-function*
                  #'(lambda ()
                      ;; FORM YOU WANT GOES HERE
                      (setf *restart-init-function* 
                            initial-restart-init-function)
                      (funcall initial-restart-init-function))))
           (t
             (setf *restart-init-function*
                   #'(lambda ()
                       ;; FORM YOU WANT GOES HERE
                       (setf *restart-init-function* nil)))))))

(run-form-from-clinit-file-later)

This adds yout form to the start of the value of restart-init-function, and that function is run late in the startup process.

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?

A Lisp listener gets its bindings from three alists: *required-thread-bindings*, *required-top-level-bindings* and *default-lisp-listener-bindings*.

*required-thread-bindings* is not relevant to this discussion unless its initial value is changed, since the only entry involving an exported symbol is (readtable . readtable), binding the value of readtable to its global value. And then readtable is again bound by the *required-top-level-bindings* alist. So we will just discuss the remaining two alists.

Here are a few lines from each alist:

;; From excl:*required-top-level-bindings* (a few values only)
(*PRINT-LENGTH*) (*PRINT-LEVEL*) (*PRINT-RADIX*) (*PRINT-BASE* . 10)
(*PRINT-PRETTY* . T) (*PRINT-ESCAPE* . T) (*READTABLE* COPY-READTABLE NIL)

;; From tpl:*default-lisp-listener-bindings* (a few values only)
(TOP-LEVEL:*AUTO-ZOOM* . TOP-LEVEL:*AUTO-ZOOM*)
(TOP-LEVEL::*LAST-FILE-COMPILED* . TOP-LEVEL::*LAST-FILE-COMPILED*)

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

Notice that most of the entries in *required-top-level-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). The only pair shown which does not use a specific value is (*READTABLE* COPY-READTABLE NIL), which says make the value of *readtable* a copy of the initial readtable. If you look at the entire list you will see further entries that are associated with the value of a variable or a more complex form to evaluate (as with readtable). Most of the entries in *default-lisp-listener-bindings* associate variables with values of variables, but notice many 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 sets the binding of *print-length* to nil, as called for in *required-top-level-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

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

does the following:

• sees whether *print-length* is a key in the alist which is the value of *required-top-level-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 *required-top-level-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).

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.

;;;
;;; This file contains examples of user
;;; customizations which can be done via a 
;;; $HOMEDRIVE/$HOMEPATH/.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)))

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:

cl-user(1):

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. Note: this is the modern mode prompt. The ANSI mode prompt is CL-USER(1):.

15.2 Errors running Allegro CL

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.html for more information on the prompt and break levels.

15.3 What if the system seems to hang (as if it is in an infinite loop)?

For interrupting on UNIX, see here, for interrupting on Windows, see here.

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

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

(excl:print-startup-info t nil)

15.6.1 The package on startup

By default, the initial package on startup is common-graphics-user (nicknamed cg-user) when using the IDE and common-lisp-user (nicknamed cl-user) when not using the IDE. The current package is displayed in the prompt.

Getting a different package on startup is not as easy as you might thing. You cannot change packages in a file (since package is bound during file loading) so you cannot use an init file (see Initialization and the sys:siteinit.cl and [.]clinit.cl files) and the -e command-line argument is processed too early to be effective.

In the IDE, there is an option in the Options dialog for the initial package on startup. See the section Note on the initial package in cgide.html.

When not using the IDE, you have to modify the *restart-init-function* appropriately. How to do it is described in Specifying the initial value of *package* in delivery.html. delivery.html discusses writing your own application (where you control the values of the various global variables). The following code in your .clinit.cl file (see Initialization and the sys:siteinit.cl and [.]clinit.cl files) will modify the *restart-init-function* while preserving whatever else it does:

(defun set-init-pack-from-clinit-file ()
  (let ((initial-restart-init-function *restart-init-function*))
    (cond (initial-restart-init-function
       (setf *restart-init-function*
         #'(lambda ()
         (tpl:setq-default *package* (find-package :my-package))
         (rplacd (assoc 'tpl::*saved-package*
                tpl:*default-lisp-listener-bindings*)
             'common-lisp:*package*)
         (setf *restart-init-function* 
           initial-restart-init-function)
         (funcall initial-restart-init-function))))
      (t
       (setf *restart-init-function*
         #'(lambda ()
           (tpl:setq-default *package* (find-package :my-package))
         (rplacd (assoc 'tpl::*saved-package*
                tpl:*default-lisp-listener-bindings*)
             'common-lisp:*package*)
         (setf *restart-init-function* nil)))))))

(set-init-pack-from-clinit-file)

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.

Copyright (c) Franz Inc. Lafayette, CA., USA. All rights reserved.