Packages

$Revision: 5.0.2.4 $

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

1.0 Packages introduction
2.0 Packages in Allegro CL
3.0 Notes on specific packages
4.0 Package nicknames
5.0 Package locking and package definition locking
     5.1 Package locking
     5.2 Package definition locking
     5.3 Implementation packages
     5.4 Package locked errors
     5.5 Locally circumventing package locked errors
     5.6 Package locked by default
     5.7 Justification for package locking

1.0 Packages introduction

Common Lisp allows the use of packages to keep different parts of an application separate, permitting multiple use of symbol names and independent development of different parts of a large program. As delivered, Allegro CL comprises several packages, and users should be aware of which packages are available, which should be used by the user, and which should, in general, be avoided.

Lisp permits already-defined functions to be redefined dynamically. However, redefining system-defined functions (either from the Common Lisp standard in the common-lisp package or from the Allegro CL implementation, in packages such as excl, system, etc.) is almost always a bad idea. Allegro CL implements a package-locking system which protects symbols in reserved packages from new or changed function definitions. See the discussions under the heading 5.0 Package locking and package definition locking below.

2.0 Packages in Allegro CL

The following packages used by Allegro CL are of direct importance to the user. Note that all nicknames are not listed in every case. Use cl:package-nicknames applied to a package to see the complete list. The first nickname listed in each case is the principal nickname.

Some of these packages may not exist in a standard Allegro CL image until a fasl file containing the functionality associated with the package is loaded. In most cases, the loading is automatic when the package is referenced. Thus

(find-package :cltl1)

causes cltl1.fasl to be loaded from the bundle.

Name	Some nicknames	Brief Description	Locked?	Notes
acl-socket		Socket interface functionality. See socket.htm.	No	Autoloaded
aclwin	aclwin302	Functionality from Allegro CL 3.0.2 kept in 5.0 for backward compatibility.	Yes	Exists in Windows and Unix. In Unix, do (require :aclwin) In Unix, symbols having to do with graphics have no function definition. Functionality that is Windows-specific genrates and error when called in Unix.
clos		the MOP extension to CLOS (CLOS functionality is in common-lisp).	Yes	Always present in an image.
cltl1		Some symbols removed from the Common Lisp standard by X3J13.	No	Functionality named by symbols in this package is out of date and use should be avoided. Autoloaded.
common-graphics	cg	Common Graphics windows and Integrated Development Environment functionality.	Yes	Windows only. Always present in an image with the IDE.
common-graphics-user	cg-user	User environment in the IDE	No	Windows only. Uses aclwin, excl, cg, cltl1, cl. Always present in an image with the IDE.
common-lisp	cl	Standard CL symbols.	Yes	Always present in an image.
common-lisp-user	user	User environment.	No	Uses cl and excl. Always present in an image.
compiler	comp	Symbols naming functionality associated with the compiler. See compiling.htm.	Yes	Autoloaded.
cross-reference	xref	Symbols naming functionality associated with the cross referencer. See cross_reference.htm.	Yes	Autoloaded.
defsystem		Symbols naming functionality associated with defsystem. See defsystem.htm	Yes	Autoloaded.
debugger	db	Symbols naming functionality associated with the debugger. See debugging.htm.	Yes	Autoloaded.
excl	excl	General extensions to Common Lisp	Yes	Always present in an image.
foreign-functions	ff	Symbols naming functionality associated with the foreign functions facility. See foreign_functions.htm.	Yes	Autoloaded.
garbage		Package for compiler labels and some CLOS names.	No	Always present in an image.
inspect		Symbols naming functionality associated with the inspector. See inspector.htm.	Yes	Autoloaded.
keyword		Standard CL package.	No	Always present in an image.
multiprocessing		Symbols naming functionality associated with multiprocessing. See multiprocessing.htm.	Yes	Autoloaded.
profiler	prof	Symbols naming functionality associated with the profiler. See profiling.htm.	Yes	Autoloaded.
system	sys, si	System functionality and internals.	Yes	Always present in an image.
top-level	tpl	Symbols naming functionality associated with the top level. See top_level.htm.	Yes	Always present in an image.

3.0 Notes on specific packages

When you start up Allegro CL on UNIX or without the Integrated Development Environment on Windows, you are in the common-lisp-user package. At the start, there are no symbols in the common-lisp-user package, but the common-lisp and excl packages are used, so external symbols from those packages are available to the user package. When you start the Integrated Development Environment (Windows only) you are in the common-graphics-user package.

The common-lisp package contains only those symbols specified in the ANSI CL specification. Some of the capabilities of standard Common Lisp functions have been extended, but they can all be used in the way specified in ANSI CL. The extensions are not portable, of course. See implementation.htm for more information on extensions to standard Common Lisp functionality.

With that caveat, if you use the common-lisp package only, you will have portable code that can with greatest ease be ported to Common Lisp systems other than Allegro CL.

A number of symbols were removed from the Common Lisp standard by the X3J13 committee. We have maintained many of these symbols in the cltl1 package, for the purpose of providing backward compatibility.

The excl and system packages contain many of the extensions in Allegro CL. Two packages in earlier versions on UNIX (4.3.x and earlier), franz and stream, have been merged with excl starting in version 5.0. Both stream and franz are nicknames of excl. excl is also the principal nickname of the excl package to ensure that name is used when *print-nickname* is true.

The top-level package contains symbols used by the top level. Note that some of these symbols have the same names as symbols in the common-lisp package (for example, tpl:*print-level* and tpl:*print-length*). Therefore, we recommend that a package using the common-lisp package not use (in the sense of use-package) the top-level package.

4.0 Package nicknames

Packages can have (usually shorter) nicknames, which can be used in place of the full names. Symbols unavailable in the current package are printed (during, e.g., tracing) with package qualifiers. Allegro CL allows you to specify whether you want the (non-nickname) package name as the qualifier or the principal nickname as the qualifier. The following variable excl:*print-nickname* controls whether the printer uses the full name or the principal nickname of a package (if true, the principal nickname is used, if nil, the package name is used). Note that certain utilities (e.g. apropos and the debugger) bind this variable to true and so always use the nickname.

The principal nickname of some of the packages of interest to users are listed next (nil means no defined nicknames).

Table 2: Package Nicknames
Package name	Principal Nickname (nil means none)	Other Nickname (some nicknames may not be listed)
common-lisp	cl	lisp
clos	nil
excl	excl	stream
system	sys	si
common-lisp-user	user	cl-user
debugger	debug	db
inspect	nil
compiler	comp
flavors	fla
foreign-functions	ff
multiprocessing	mp
top-level	tpl
defsystem	defsys	ds
cross-reference	xref

Package nicknames can be found with the Common Lisp function cl:package-nicknames, which returns a list of the nicknames of its argument, with the principal one first. Sometimes, you may wish to use a nickname of an Allegro CL package as the name of your own package. (E.g. some users would like to have their own package named db, perhaps for database functionality, but db is a nickname of the debugger package.) You can change the nicknames of a package with cl:rename-package. You must do it in a without-package-locks form, however, because of package locking described just below.

5.0 Package locking and package definition locking

Packages have two kinds of locks as an extension in Allegro CL. The package-lock protects a package from changes in its structure (its use list, its exported symbols, etc.). The package-definition-lock protects the symbols in the package from new or changed uses as the name of a function, macro, structure, or type.

Tracing and advice are not affected by either type of package locking.

5.1 Package locking

When the function excl:package-lock returns true when applied to a package, we say the package is package-locked. When a package is package-locked, the system will signal an error of type package-locked-error when code is executed that tries to:

import a symbol into the package (with import and shadowing-import)
export a symbol from the package (with export).
unexport a symbol (with unexport)
change the name of the package (with rename-package).
change the packages used by the package (with use-package and unuse-package).
unintern a symbol in the package (with unintern)
shadow a symbol (with shadow or shadowing-import).

The list is exhaustive. Note that intern and delete-package cannot signal a package-locked-error. The function excl:package-lock applied to a package object (but not a symbol or string naming a package) returns true if the package is locked and returns nil if it is not locked. Setf can be used with package-lock to lock or unlock a package.

5.2 Package definition locking

A package is package-definition-locked if the function excl:package-definition-lock (whose argument must be a package object, not a package name) returns true when applied to the package. When a package is package-definition-locked, the system will signal an error when code is executed that attempts any of the following actions on a symbol homed in the package:

defining it as a function (e.g. with defun or setf of fdefinition)
defining it as a macro (e.g. with defmacro)
defining it as a type specifier (with defstruct, defclass, deftype)
defining it as a structure (with defstruct)
defining it as a symbol macro
defining it as a compiler macro
if the symbol is fboundp, lexically binding it with flet, labels, or macrolet

Function names that are lists are also protected if the important symbol (usually the cadr, e.g. border in (setf border)) in the list is in the definition-locked package. We repeat here the definition of excl:package-definition-lock because it describes how the lock can be circumvented.

excl:package-definition-lock

Arguments: package

Returns t or nil as package is or is not definition-locked. package must be a package object (it cannot be a symbol or a string). setf may be used with this function to definition-lock or unlock a package.

Even if a package is package-definition-locked, no error will be signaled when

the value of excl:*enable-package-locked-errors* is nil;

the violation is dynamically inside the body of a call to the macro excl:without-package-locks;

the list returned by applying excl:package-implementation-packages to the value of *package* contains the home package of the symbol being operated on. Implementation packages are defined just below. Note that unless you have specified a list of implementation packages for a package that does not include the package itself (which would be unusual), no error will be signaled when *package* is the home package of the symbol being operated on.

If a violation is encountered while compiling a file, a warning is signaled rather than an error. If the resulting fasl file is loaded, an error will then be signaled.

5.3 Implementation packages

Allegro CL allows a package to have a list of associated packages (called implementation packages). No warning or error will be signaled for a definition or redefinition in one package when the value of *package* is an implementation package of that package. Both defpackage and make-package have been extended to accept an :implementation-packages keyword argument and the setfable function excl:package-implementation-packages accesses that list of packages.

The value of the :implementation-packages argument to defpackage and make-package should be a list of strings naming packages. When unspecified, the value of this argument defaults to the list containing the string naming the package being defined. The :implementation-packages argument is not standard Common Lisp. You may wish to conditionalize it in portable code.

(defpackage :mypack
    #+allegro (:implementation-packages '("MYPACK" "MYPACK-2"))
    ; other options as desired
     )

The :implementation-packages option will only be read by Allegro CL. Note that since we specified a value, we had to include "MYPACK" as well as "MYPACK-2" in order to allow symbols whose home package is mypack to be redefined without warning or error while the value of *package* is the mypack package.

Note that implementation packages protects against warnings and errors for package definition locks only. Package locks (the distinction is described above) are not affected.

Here is an example. Suppose we define two packages: foo and bar. "BAR" is on the :implementation-packages list for foo, but "FOO" is not on the :implementation-packages list for bar. Both packages are definition-locked.

(defpackage :foo (:implementation-packages '("FOO" "BAR")))
(defpackage :bar)
(setf (package-definition-lock (find-package :foo) t)
(setf (package-definition-lock (find-package :bar) t)

Consider the following two files. The first starts with (in-package :bar) and defines a function on foo::mysym. The second starts with (in-package :foo) and defines a function on bar::my-other-sym. Compiling or loading the first file signals no warning or error, since the bar package is an implementation package for the foo package. The second signals a warning on compilation and an error on loading because the foo package is not an implementation package for the bar package.

;; File # 1
;; Compiling or loading this file will not signal a warning
;; (for compilation)

;; or an error (for loading) even if the FOO package is
;; definition locked,
;; because the BAR package is an implementation package of
;; the FOO package.
(in-package :bar)
(defun foo::mysym (a b ) (+ a b))

;; File # 2
;; Compiling or loading this file will signal a warning
;; (for compilation)
;; or an error (for loading) if the BAR package is definition
;; locked, because
;; the FOO package is not an implementation package
;; of the BAR package.
(in-package :foo)
(defun bar::my-other-sym (c) (sqrt c))

5.4 Package locked errors

The following script shows what happens when you try to perform a protected action on a package-locked package. Here we try to export the symbol excl::*debug-enclose-printer-errors* from the excl package.

USER(3): (export 'excl:: *debug-enclose-printer-errors*
(find-package :excl))
Error: #<The EXCL package> is locked against changes by EXPORT.
[condition type: PACKAGE-LOCKED-ERROR]

Restart actions (select using :continue):
0: Allow EXPORT to modify #<The EXCL package>.
[1c] USER(4):

The next script shows what happens when you try to define a function on a symbol in a package-definition-locked package. We try to define a function on the symbol excl:*read-init-files*. We chose this admittedly strange example to make clear that a symbol need not already have a function definition (the symbol in question does not) in order for an error to be signaled.

USER(18): (defun excl:*read-init-files* nil nil)
Error: Attempt to make a FUNCTION definition for the name
EXCL:*READ-INIT-FILES*. This name is in
the EXCL package and defining it is a violation for
portable programs. The package EXCL has
PACKAGE-LOCK-DEFINITIONS set, which causes the system
to check for this violation.
[condition type: PACKAGE-LOCKED-ERROR]

Restart actions (select using :continue):
0: Set the FUNCTION definition of the name
EXCL:*READ-INIT-FILES* anyway.
[1c] USER(19):

In each case, the error has condition type package-locked-error and in each case the error is continuable. By entering :continue 0, the requested action (exporting the symbol or defining the function) will take place.

Note however that package locking is in place for a reason: changing a system-supplied package or defining (or particularly redefining) a function on a symbol in a system-supplied package can cause Lisp to fail because assumptions about the package are violated.

Obviously there are times when changing a package or the definition on a symbol is the right thing to do. If, for example, we instruct you to make some change (say, export a symbol accidentally left off an export list), we are guaranteeing that doing so will not have adverse consequences.

5.5 Locally circumventing package locked errors

The variable excl:*enable-package-locked-errors* and macro excl:without-package-locks can be used to prevent package-locked-errors (of either type -- ordinary locks and definition locks) without actually unlocking a package.

When excl:*enable-package-locked-errors* is true, executing code that violates package-locking or package-definition-locking will signal errors and compiling such code will signal warnings as described above. When it is nil, such code will execute without package-locked-errors or compile-time warnings.

The macro excl:without-package-locks, which takes one or more forms as its arguments, evaluates those forms with excl:*enable-package-locked-errors* bound to nil.

5.6 The packages locked by default

For symbols in the common-lisp package, all of the actions prevented by package locking and package definition locking are explicitly restricted by the ANSI specification. The common-lisp package is locked and definition locked as are a number of Allegro CL packages, including

aclwin (Windows only) clos cltl1 common-graphics(Windows only) common-lisp compiler cross-reference debugger defsystem excl foreign-functions inspect multiprocessing profiler system top-level

5.7 Justification for package locking

For the common-lisp package, the restrictions of both package-locks and package-lock-definitions locks are compliant with the ANSI standard. Other system-provided packages in Allegro CL are also locked, for the same reasons that the common-lisp package is locked.

Writers of application packages may want to lock their packages as well, especially if the package may be used by other packages written later. Package locks can detect inadvertent name collisions before they cause program failures. The following forms will package-lock and package-definition-lock the package foo. The same forms, with nil instead of t, unlock the package.

(setf (excl:package-lock (find-package :foo)) t)
(setf (excl:package-definition-lock (find-package :foo)) t)