Source File Recording

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 or not such information is recorded and loaded depends on the values of the variables *record-source-file-info* and *load-source-file-info*.
If you want source file information recorded in a compiled source file (fasl file). sompile the file when *record-source-file-info* is true. If you want source file information recorded in a fasl file loaded, load the fasl file while *load-source-file-info* is true. (No source file information will be loaded if it was not recorded in the fasl file regardless of the value of *load-source-file-info*.)

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 *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 *record-source-file-info* and *load-source-file-info* control whether source file information is recorded. If *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 *record-source-file-info* true, then the information stored in the file is loaded only if *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 *record-source-file-info* be mil when the file is compiled.

If a fasl file contains source file information, *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.

1.1 Functions that implement source file recording

The function record-source-file stores information about an object being defined. This function is not typically called directly. It is called automatically when source file recording is enabled when standard definition macros (defun, defvar, etc.) are called. It is exported so that it can be added to programmer-defined definition macros if desired.

The function source-file returns the source file of a specified type (function, macro, operator, variable), if it is known, for the argument object. nil is returned if the argument object is of the specified type but no source file information is known. An error is signaled if the argument object is not of the specified type.

The function discard-all-source-file-info can be used to discard all recorded information (so after it is called, it is as if no information was ever gathered).

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 *redefinition-warnings* is true 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 *record-source-file-info*, *load-source-file-info*, and *redefinition-warnings* are true. These variables are assumed to be true 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 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.html for more information.
• There are cases where redefinition warnings are printed when *redefinition-warnings* is true but one or both of *load-source-file-info* or *record-source-file-info* are nil. The only way to guarantee that warnings are not printed is to set *redefinition-warnings* to be nil.
• Wrapping definition code with the without-redefinition-warnings macro will suppress redefinition warnings.

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 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 *redefinition-pathname-comparison-hook*, *source-file-frobbers* and function tmp-mnt-frobber.

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