10.9 Throwing symbols and packages out of the application

This section discusses the circumstances in which you might want to throw symbols and packages out of the application, by deleting or smashing them.

10.9.1 Deleting packages

When you delete a package, the following happens:

1. All the package's symbols are uninterned.
2. The package name is deleted.

After the package is deleted, its symbols continue to exist, but because they are no longer interned in a package they become eligible for collection at the next garbage collection. They survive only if there are useful references to them elsewhere in the application.

Note: Invoking the treeshaker has much the same effect on packages as deleting them. However, by deleting a package you regain some extra space taken up by hash tables.

10.9.2 How to delete packages

You can pass deliver a list of packages to delete with the keyword :delete-packages.

10.9.3 Smashing packages

When you smash a package, the following happens:

1. All the package's symbols are uninterned.
2. The package structure is deleted.
3. Its symbols' function definitions, property lists, classes, values, and structure definitions are deleted or set to nil.

After the package is smashed, the symbols continue to exist, but all the information they contained is gone. By being uninterned they become eligible for garbage collection. Also, the chances of any objects they referred to being collected are increased.

Caution: Smashing destroys a whole package and all information within its symbols. Use it carefully.

Note: Any symbol whose home package is to be smashed can be retained by being uninterned before delivery commences.

10.9.4 How to smash packages

You can pass deliver a list of packages to smash with the keyword :smash-packages or :smash-packages-symbols.

10.9.5 When to delete and smash packages

Note: In general, you are advised against deleting or smashing packages unless it is absolutely necessary. Always try to reduce the image size as much as possible by treeshaking first.

If an application does one of the following things, packages are involved and you must consider keeping them in the application:

1. Makes an explicit reference to a package by some of the package functions, for example, intern, find-symbol and so on.
2. Uses the reader, with read or any of the other reader functions.

   These functions make reference to a package (either *package* or one given explicitly) whenever they read a symbol.

3. Printing a symbol with the format directive ~S.

   The format function prints the symbol with a package prefix if the symbol is part of a package.

4. Loading a file, whether compiled or interpreted.
5. Using the function symbol-package.

Fortunately, most applications are unlikely to do these things to more than a small number of packages. You should, therefore, be able to delete most packages without breaking the application. When you know that none of the symbols belonging to a package are used, you can go one step further and smash it.

Smashing a package guarantees space savings where deleting it would not. Even in a case where a symbol is referenced but unused, because it has been smashed you still regain space taken up by objects hanging from slots for function definition, value, property list and so on.

You do not usually gain much by smashing your own packages that you would not gain by just deleting them — you are after all unlikely to have included an entire package of symbols in your final application if you know it is not going to use them. The real benefits of smashing can be seen when it is performed on the system's packages, some of which may be entirely irrelevant to your application. In addition, you are unlikely to gain very much by deleting a package that you would not gain by treeshaking. In general, you should try to avoid either deleting or smashing packages explicitly.

However, if symbols in your packages are referenced through complex data structures, making it difficult to track references down, smashing may still prove useful.