Clozure CL provides the function CCL:SAVE-APPLICATION, which creates a file containing an archived Lisp memory image.

Clozure CL consists of a small executable called the Lisp kernel, which implements the very lowest level features of the Lisp system, and an image, which contains the in-memory representation of most of the Lisp system, including functions, data structures, variables, and so on. When you start Clozure CL, you are launching the kernel, which then locates and reads an image file, restoring the archived image in memory. Once the image is fully restored, the Lisp system is running.

Using CCL:SAVE-APPLICATION, you can create a file that contains a modified image, one that includes any changes you've made to the running Lisp system. If you later pass your image file to the Clozure CL kernel as a command-line parameter, it then loads your image file instead of its default one, and Clozure CL starts up with your modifications.

If this scenario seems to you like a convenient way to create an application, that's just as intended. You can create an application by modifying the running Lisp until it does what you want, then use CCL:SAVE-APPLICATION to preserve your changes and later load them for use.

In fact, you can go further than that. You can replace Clozure CL's toplevel function with your own, and then, when the image is loaded, the Lisp system immediately performs your tasks rather than the default tasks that make it a Lisp development system. If you save an image in which you have done this, the resulting Lisp system is your tool rather than a Lisp development system.

You can go a step further still. You can tell CCL:SAVE-APPLICATION to prepend the Lisp kernel to the image file. Doing this makes the resulting image into a self-contained executable binary. When you run the resulting file, the Lisp kernel immediately loads the attached image file and runs your saved system. The Lisp system that starts up can have any behavior you choose. It can be a Lisp development system, but with your customizations; or it can immediately perform some task of your design, making it a specialized tool rather than a general development system.

In other words, you can develop any application you like by interactively modifying Clozure CL until it does what you want, then using CCL:SAVE-APPLICATION to preserve your changes in an executable image.

On Mac OS X, the application builder uses CCL:SAVE-APPLICATION to create the executable portion of the application bundle. Double-clicking the application bundle runs the executable image created by CCL:SAVE-APPLICATION.

Also on Mac OS X, Clozure CL supports an object type called MACPTR, which is the type of pointers into the foreign (Mac OS) heap. Examples of commonly-user MACPTR objects are Cocoa windows and other dynamically-allocated Mac OS system objects.

Because a MACPTR object is a pointer into a foreign heap that exists for the lifetime of the running Lisp process, and because a saved image is used by loading it into a brand new Lisp process, saved MACPTR objects cannot be relied on to point to the same things when reconstituted from a saved image. In fact, a restored MACPTR object might point to anything at all—for example an arbitrary location in the middle of a block of code, or a completely nonexistent virtual address.

For that reason, CCL:SAVE-APPLICATION converts all MACPTR objects to DEAD-MACPTR objects when writing them to an image file. A DEAD-MACPTR is functionally identical to a MACPTR, except that code that operates on MACPTR objects distinguishes them from DEAD-MACPTR objects and can handle them appropriately—signaling errors, for example.

As of Clozure CL 1.2, there is one exception to the conversion of MACPTR to DEAD-MACPTR objects: a MACPTR object that points to the address 0 is not converted, because address 0 can always be relied upon to refer to the same thing.

As of Clozure CL 1.2, the constant CCL:+NULL-PTR+ refers to a MACPTR object that points to address 0.

On all supported platforms, you can use CCL:SAVE-APPLICATION to create a command-line tool that runs the same way any command-line program does. Alternatively, if you choose not to prepend the kernel, you can save an image and then later run it by passing it as a command-line parameter to the ccl or ccl64 script.

SAVE-APPLICATION filename &key toplevel-function init-file error-handler application-class clear-clos-caches (purify t) impurify (mode #o644) prepend-kernel native [Function]