Package

Signature

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
.

dll-added-files

A list of strings.

automatic-init

A generalized boolean.

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)
.

image-type

One of
:exe
,
:dll
or
:bundle
.

Values

Returns
nil
.

Description

The function
save-image
saves the LispWorks image to a new executable or dynamic library containing any modifications you have made to the supplied image.

For information about the sort of changes you might want to save in a new image, see "Customization of LispWorks" in the
LispWorks User Guide
.

Do not use
save-image
when the graphical IDE is running. Instead create a build script similar to the examples below, 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.

On Cocoa you can combine a call to
save-image
with the creation of an application bundle containing your new LispWorks image, as in the example shown below.

dll-exports
is implemented only on Windows/Linux/Macintosh/FreeBSD. It controls whether the image saved is an executable or a dynamic library (DLL). The default value is
:default
and this value means an executable is saved. Otherwise
dll-exports
should be list (potentially
nil
) of strings. In this case a dynamic library is saved, and each string in
dll-exports
names a function which becomes an export of the dynamic library and should be defined as a Lisp function using
fli:define-foreign-callable
. Each exported name can be found by
GetProcAddress
(on Windows) or
dlsym
(on other platforms). The exported symbol is actually a stub which ensures that the LispWorks dynamic library has finished initializing, and then enters the Lisp code.

On Mac OS X the default behavior is to generate an object of type "Mach-O dynamically linked shared library" with file type
dylib
. See
image-type
below for information about creating another type of library on Mac OS X.

On Linux/Macintosh/FreeBSD, to save a dynamic library image the computer needs to have a C compiler installed. This is typically
gcc
(which is available by installing Xcode on the Macintosh).

automatic-init
specifies whether a LispWorks dynamic library should initialize inside the call to
LoadLibrary
(on Microsoft Windows) or
dlopen
(on other platforms), or wait for further calls. Automatic initialization is useful when the dynamic library does not communicate by function calls. On Microsoft Windows it also allows
LoadLibrary
to succeed or fail according to whether the LispWorks dynamic library initializes successfully or not. Not using automatic initialization allows you to relocate the library if necessary using InitLispWorks, and do any other initialization that may be required. The default value of
automatic-init
is
t
on Windows,
nil
on other platforms. For more information about automatic initialization in LispWorks dynamic libraries, see "LispWorks as a dynamic library" in the
LispWorks User Guide
.

dll-added-files
should be a list of filenames. It is ignored on Microsoft Windows. On other platforms if
dll-added-files
is non-
nil
then a dynamic library containing each named file is saved. Each file must be of a format that the default C compiler (
scm:*c-default-compiler*
) knows about and can incorporate into a shared library. Typically they will be C source files, but can also be assembler or object files. They must not contain exports that clash with names in the LispWorks shared library (see Dynamic library C functions for the predefined exports). The added files are useful to write wrappers around calls into the LispWorks dynamic library. Such wrappers are useful for:

Calling InitLispWorks when required, for example to relocate the LispWorks dynamic library to avoid memory clashes with other software, as described under "Startup Relocation" in the
LispWorks User Guide
.

Changing calls that involve complex C structs or even C++ objects into plain calls, because accessing C structures in Lisp requires defining the structure, while in C it only needs to include the header.

Creating 'stub' functions that can be called from Lisp, for example for calling a C++ method. The address of the stub function can be passed to Lisp which can call it using a function defined by
fli:define-foreign-funcallable
.

Adding code that runs automatically inside the call to
dlopen
, by using
__attribute__ ((constructor))

image-type
defaults to
:exe
or
:dll
according to the value of
dll-exports
and therefore you do not normally need to supply
image-type
.

image-type
:bundle
is used only when saving a dynamic library. On Mac OS X it generates an object of type "Mach-O bundle" and is used for creating shared libraries that will be used by applications that cannot load dylibs (FileMaker for example). It also does not force the filename extension to be
dylib
. On other Unix-like systems
image-type
merely has the effect of not forcing the file type of the saved image, and the format of the saved image is the same as the default. On Microsoft Windows
image-type
:bundle
is ignored.

Note:
image-type
:bundle
is completely unrelated to the Mac OS X notion of an application bundle.

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 executable image will start without multiprocessing enabled. When
multiprocessing
is true or the image is a DLL, 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 build script. Save this to a file such as
c:/build-my-image.lisp
:

(load-all-patches)

(load "my-code")

(save-image "my-image")

Then run LispWorks with the command line argument
-build c:/build-my-image.lisp
to save the image
my-image.exe
.

This example shows a portable build script which, on Cocoa, saves your new LispWorks image in a Mac OS X application bundle. This allows your new LispWorks for Macintosh image to be launchable from the Finder or Dock and to have its own icon or other resources:

(load-all-patches)

(load "my-code")

#+:cocoa

(compile-file-if-needed

(example-file

"configuration/macos-application-bundle")

:load t)

(save-image

#+:cocoa

(write-macos-application-bundle

"/Applications/LispWorks 5.1/My LispWorks.app")

#-:cocoa

"my-lispworks")

Compatibility note

LispWorks 5.0 and previous versions documented
-init
as the way to run LispWorks with a build script. This method is deprecated.

Note that LispWorks quits automatically after processing a build script via
-build
, whereas with
-init
you need to call quit explicitly at the end of the build script.

Compatibility note

In LispWorks 5.0 and previous versions
dll-exports
is supported only on Windows.