Source File Recording

$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 Source-file recording Introduction
2.0 Redefinition warnings
2.1 Pathname comparison

1.0 Source-file recording Introduction

Allegro CL provides the ability to associate with an object the location of the source used to define the object to Lisp. That location can be:

A Lisp source file (for objects defined by loading a file into Lisp).
An Emacs buffer open to a file (for objects defined by Lisp source in an Emacs buffer open to a file and dispatched to Lisp via the Emacs-Lisp interface).
The top-level (for objects defined with definitions typed directly to the top-level).

Allegro CL can record the source of functions and macros which are defined by the user. Whether of not such information is recorded and loaded depends on the values of the variables excl:*record-source-file-info* and excl:*load-source-file-info*. If you want source file information recorded, you should set both variables to be true. If you do not want source file information recorded, you should set both variables to be nil.

A side effect of recording this information is that warnings are printed when a function or macro is redefined by a source other than the original source (see the next section). The variable excl:*source-pathname* is recorded as the place of definition of an object (like a function, macro) or setting (like a variable). The variable is bound during loading.

The variables excl:*record-source-file-info* and excl:*load-source-file-info* control whether source file information is recorded. If excl:*record-source-file-info* is true, source file information will be recorded:

Whenever an object is defined at the top-level (i.e. the definition is typed directly to Lisp).
Whenever a Lisp source file is loaded.

Further, if a Lisp source file is compiled, the resulting fasl file will be annotated to include the source file information that should be recorded if the file is loaded.

If a fasl file was compiled with excl:*record-source-file-info* true, then the information stored in the file is loaded only if excl:*load-source-file-info* is true when the fasl file is loaded.

There are two variables for the following reason. Because defining forms (defun, defvar, etc.) are typically macros, it is not possible to identify defining forms in a fasl file because the macros will be macroexpanded away. For that reason, source file information must be added to the fasl file at compile time if it is to be available at load time. However, that information does increase the size of the fasl file (typically about 10 to 15%). Users who do not wish to pay the cost of increased fasl file size can suppress recording of information in the fasl file by having excl:*record-source-file-info* be nil when the file is compiled.

If a fasl file contains source file information, excl:*load-source-file-info* can be used to control whether or not the information is loaded along with the fasl file. The two variables give users maximum flexibility in deciding whether source file information is recorded at all and whether it is loaded into a particular image.

2.0 Redefinition warnings

Redefinition warnings are useful because code is sometimes unintentionally redefined, perhaps because the user forgot that a symbol was already used or because a symbol name was mistyped. Allegro CL will print a warning message informing the user that functions and macros have been redefined if the variable excl:*redefinition-warnings* is non-nil and the conditions specified in the variable description and just below are met.

The following information pertains to redefinition warnings.

Warnings are guaranteed to be printed only if the variables excl:*record-source-file-info*, excl:*load-source-file-info*, and excl:*redefinition-warnings* are non-nil. These variables are assumed to be non-nil in the discussion below.
If a macro is defined with the same name as an existing function or a function with the same name as an existing macro, a warning will be printed regardless of whether source file information exists for either the function or macro.
If source file information exists for an object, and it is redefined either in a file or at the top-level, a warning will be printed. The exception occurs when the redefinition is in the file recorded as the source file. Thus repetitive loads or compile-files of the same file will not generate warnings. However, a warning will be printed when an object is defined twice in the same file. Note too the comments under the heading 2.1 Pathname comparison below.
Since source file information is not stored for functions already defined in Allegro CL, redefining such functions will not generate warnings unless a macro is defined with an existing function name or vice versa. In particular, redefining standard Common Lisp functions will not generate warnings. However, most such definitions will trigger package-lock errors. See packages.htm for more information.
There are cases where redefinition warnings are printed when excl:*redefinition-warnings* is true but one or both of excl:*load-source-file-info* or excl:*record-source-file-info* are nil. The only way to guarantee that warnings are not printed is to set excl:*redefinition-warnings* to be nil.

2.1 Pathname comparison

A problem with source file recording in a network environment is that source file pathnames are not well-defined. Suppose you load a file in an image (and source file information is recorded for objects in the file) and then you dump the image out with excl:dumplisp. You then restart the image on another machine and load the same file. You may get redefinition warnings because the system thinks the file is different even though it is in fact the same. The difference typically comes from additional directories put on the front of the pathname. Thus, a local file on machine franz may have the pathname /usr/jones/foo.fasl but on another machine the pathname may be /net/franz/usr/jones/foo.fasl.

Another problem can occur when you are running Emacs on one machine and executing Lisp (as a subprocess of Emacs) on another machine. Emacs and Lisp may have different ideas about the pathname of a file.

To handle these annoyances, we provide the variables excl:*redefinition-pathname-comparison-hook*, sys:*source-file-frobbers* and function sys:tmp-mnt-frobber.