10.18 Interrogate-Symbols

interrogate-symbols is designed to find why symbols are left in the image even though they should not be. Since keeping information in the image would itself keep symbols, the facility has as little functionality as possible. The result is a non-intuitive interface, and you should be ready for this. You are encouraged to try other methods first. In particular, you might consider contacting Lisp Support first.

To use interrogate-symbols pass :interrogate-symbols t to deliver . This loads the interrogate symbol facility. and causes the delivered image to check for the command line argument -interrogate-symbols on startup. If this command line argument appears, the image first does symbol interrogation, and then proceeds to run the application as normal.

Symbol interrogation starts by building an internal table of reverse pointers, during which the image prints some messages about its progress. When it finishes, it prompts:

The input is read one line at a time. Each line is interpreted as a single string, as follows:

1. If the string does not contain the character #\: , and does not begin with #\+ , it is a symbol name. The string is used as the argument to find-symbol (in the current package).

Note the string is used as-is, so it must not contain escape characters or leading or trailing spaces, and must be in the right case. For example, the symbol that is printed

SETF::\"USER\" \"WHATEVER\"

must be entered:

SETF::"USER" "WHATEVER"

[ omitting the escape characters #\\ ] and to find the symbol CAR , you must enter CAR , and not car. #\ : characters after the first one (or the first pair) are taken as part of the symbol.

If the symbol is found, the image prints a list, when the first element is the symbol, the second element is a list of interesting symbols that point to that symbol (possibly through uninteresting symbols), and the third element is a list of symbols that point to the symbol directly. A symbol B points to symbol B directly when there is a chain of pointers from A to B which does not go via another symbol.

An interesting symbol is a symbol in another package, or a symbol from the same package which is pointed to by a symbol from another package. The idea is that the interesting symbols are the symbols that are most likely to be worth further investigation.

Both the second and the third element may be the symbol :MANY rather than a list, if there are more the sys::*maximum-interrogate-return* (default value 30 ) of them.

2. If the string contains a #\: character or a pair of #\: characters, and there are characters after it, it is a package name followed by a symbol name. The characters up to the first #\: are used to search for the package. If it is found, it skips the #\: , and if the following characters are #\: it skips them, too. The rest of the string is then used as a symbol name. Like in 1. above, both the package name and the symbol name must match exactly the actual package and symbol name. The output is the same as in 1.
3. If the string starts with #\+ followed by a string as in 1. or 2., then the symbol is found as in 1. or 2. Instead of looking for symbols that point to it, the image builds a tree of rereverse pointers starting from the symbol, going to depth sys::*check-symbol-depth* . In the tree, the car is an object and the cdr is a list of pointers to it. Each pointer may be a single object (if it has reached the depth limit, or found an object that is already in the tree), or a recursive tree. The tree may be quite extensive.
4. If the first #\: character (or pair) is the last character in the string, than the line specifies a package name. If the string does not start with a #\+ , the image prints each symbol from other packages that points (as defined in 1.above) to symbols in the package, followed by a list of the symbols in the package that it points to. To construct is this it has to check the reverse pointers from all the symbols in the package, which may take a long time if the package contains many symbols.

This option is especially useful in conjunction with the :smash-packages-symbols keyword to deliver , to find why a package that should have gone remains in the image.

5. If the string ends with #\: as in 4. above, but starts with #\+ , then the rest of the string is treated as in 4., but the image simply prints for each the symbol in the package the same information that 1. prints for a single symbol.

LispWorks Delivery User Guide - 13 Dec 2011