Function

Summary

Saves the image to a new file.

Package

hcl

Signature

save-image filename &key dll-exports gc type normal-gc restart-function multiprocessing console environment remarks clean-down => nil

The dll-exports argument is available only in LispWorks for Windows.

The console argument is available only in LispWorks for Windows and LispWorks for Macintosh.

Arguments

filename

A string. It is the name of the file that the image is saved as. This name should not be the same as the original name of the image.

dll-exports

A list of strings, or the keyword :default .

gc

If non- nil , there is a garbage collection before the image is saved. The default value is t .

type

Determines if some global variables are cleared before the image is saved. You can generally use the default value, which is :user .

normal-gc

If this is t the function normal-gc is called before the image is saved. The default is t .

restart-function

A function to be called on restart.

multiprocessing

Controls whether multiprocessing is enabled on restart.

console

On Windows console controls whether the new image will be a Console or GUI application and when, if ever, to make a console window in the latter case.

On the Macintosh console controls when, if ever, to make a console window.

Possible values are discussed below.

environment

environment controls whether the LispWorks environment is started on restart. Possible values are discussed below.

remarks

remarks adds a comment to the save history. The value should be a string.

clean-down

When t , calls (clean-down t) .

Values

Returns nil .

Description

Using this function, you can make modifications to the image, and then save the image with the modifications inside. This is particularly important when patches are sent by Lisp Support.

Do not use this function when the programming environment is running. Instead, create an initialization script or run LispWorks in a subprocess using the Application Builder tool.

You cannot use save-image on Windows, Linux and Mac OS X when multiprocessing is running. It signals an error in this case.

dll-exports is implemented only in Lispworks for Windows. It controls whether the image saved is an executable or a DLL. The default value is :default and this value means an executable is saved. Otherwise a DLL is saved and the value of dll-exports should be a list of strings naming the exports of the DLL, each of which should be defined as a Lisp function using fli:define-foreign-callable .

restart-function , if non- nil , specifies a function (with no arguments) to be called when the image is started. If multiprocessing is true, restart-function is called in a new process. restart-function is called after the initialization file is loaded. The default value of restart-function is nil .

Note: restart-function is not called if the command line argument -no-restart-function is present

When multiprocessing is nil , the image will start without multiprocessing enabled. When multiprocessing is true, the image will start with multiprocessing enabled. The default value of multiprocessing is nil .

console is implemented only in Lispworks for Windows and LispWorks for Macintosh. The possible values for console are as follows:

:default

Unchanged since previous save.

t

On the Macintosh, the value t has the same effect as the value :always .

On Windows, a Console application is saved, else a Windows application is saved which creates its own console according to the other possible values.

:input , :output , :io

Whenever input, output or any I/O is attempted on *terminal-io* .

:init

At startup, if input and output are not redirected

:always

At startup, even if input and output are redirected.

The LispWorks for Windows and LispWorks for Macintosh images shipped have console set to :input .

The possible values for environment are as follows:

:default

Unchanged since previous save.

nil

Start with just the TTY listener.

t

Start the environment automatically, no TTY listener.

:with-tty-listener

Start the environment automatically, but still have a TTY listener.

The LispWorks image shipped is saved with :environment t on all platforms except for the Motif images on Mac OS X, Solaris, HP-UX and DEC Tru64 UNIX.

You should not try to save a new image over an existing one. Always save images using a unique image name, and then, if necessary, replace the new image with the old one after the call to save-image has returned.

Example

Here is an example initialization script. Save this to a file such as my-file.lisp , then run LispWorks with the command line argument -init c:/my-file.lisp to build the image my-image.exe .

(load-all-patches)

(load "my-application")

(save-image "my-image")

(quit)

See also

deliver
load-all-patches
quit