Saves the image to a new file.
hcl
save-image filename &key dll-exports dll-added-files dll-extra-link-options automatic-init gc type normal-gc restart-function multiprocessing console environment remarks clean-down image-type split => nil
| filename⇩ |
A pathname designator. |
| dll-exports⇩ |
A list of strings, or the keyword :default. |
| dll-added-files⇩ |
A list of strings. |
| dll-extra-link-options⇩ | |
|
A list of strings. | |
| automatic-init⇩ |
A generalized boolean. |
| gc⇩ |
A generalized boolean. |
| type⇩ |
A keyword. |
| normal-gc⇩ |
A generalized boolean. |
| restart-function⇩ |
A function or nil. |
| multiprocessing⇩ |
One of nil, t or :with-tty-listener. |
| console⇩ | |
| environment⇩ |
One of :default, nil, t or :with-tty-listener. |
| remarks⇩ |
A string or nil. |
| clean-down⇩ |
A generalized boolean. |
| image-type⇩ |
One of the keywords :exe, :dll or :bundle. |
| split⇩ | nil, t or :resources or :default (the default). |
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.
filename is used as 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.
For information about the sort of changes you might want to save in a new image, see 13 Customization of LispWorks.
Do not use save-image when the graphical IDE is running. Instead create a build script and use it with the -build command line argument similar to the examples below, or run LispWorks in a subprocess using the Application Builder tool.
You cannot use save-image 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, x86/x64 Solaris, Macintosh and 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. The value :com is supported on Microsoft Windows only (see below). Otherwise dll-exports should be list (potentially nil). 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 Microsoft Windows, dll-exports can also contain the keyword :com, or dll-exports can simply be the keyword:com, both of which mean that the DLL is intended to be used as a COM server. See the COM/Automation User Guide and Reference Manual for details.
On macOS, 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 macOS.
On Linux, Macintosh, x86/x64 Solaris and 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).
An image saved as a dynamic library (DLL):
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 14 LispWorks as a dynamic library.
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 dynamic library (see 52 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:
fli:define-foreign-funcallable.dlopen, by using __attribute__ ((constructor))
dll-extra-link-options should be a list of strings. It is ignored on Microsoft Windows. On other platforms if dll-extra-link-options is non-nil then the strings are passed as extra command line arguments to the linker. See the documentation for the linker (typically called ld) for the operating system you are using for the meaning of these arguments. On Macintosh, a default value for the -install_name option is generated using the file-namestring of the dynamic library if "-install_name" is not specified in dll-extra-link-options.
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 macOS 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 macOS notion of an application bundle.
When split is :default on non-macOS, it behaves the same as when split is nil, which means that the saved image is written as a single executable file containing the Lisp heap. When split is :default on macOS, it behaves the same as when split is t, unless the executable is being saved into a bundle, in which case it behaves the same as when split is :resources. save-image recognizes a bundle by checking that the last two components of the directory of the executable are Contents and MacOS. split defaults to :default.
If split is t, then the saved Lisp heap is split into a separate file, named by adding .lwheap to the name of the executable. When the executable runs, it reloads the Lisp heap from this file automatically.
In addition, when saving LispWorks on the Macintosh as an application bundle (for example by using create-macos-application-bundle) or as a framework bundle, split can be the symbol :resources. This places the Lisp heap file in the Resources directory of the bundle, which allows the heap to be included in the bundle's signature. For an application bundle, the Resources directory is in the Contents directory alongside the MacOS directory. For a framework bundle, the Resources directory is alongside the shared library. The executable and Lisp heap file must be in these directories within the bundle at run time.
Supplying split does not interact well with saving macOS universal binaries, because save-universal-from-script does not see it. Thus you should normally avoid supplying it and rely on the default to be the correct one. If you do need to supply it and you want to use save-universal-from-script, then you may need to supply it to save-universal-from-script too.
The main use of a non-nil value for split is to allow third-party code signing to be applied to the executable, which is often not possible when saving an image with the Lisp heap included in a single file.
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, starting processes in the list *initial-processes*. When *initial-processes* is nil or multiprocessing is :with-tty-listener, a TTY listener process is started as well. The default value of multiprocessing is nil.
console is implemented only in LispWorks for Windows and LispWorks for Macintosh. 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. The possible values for console are as follows:
:default |
Unchanged since previous save. |
t |
On the Macintosh, the value 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.
environment controls whether the LispWorks environment is started on restart. 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 GTK images on macOS.
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.
If gc is non-nil, there is a garbage collection before the image is saved. The default value of gc 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.
If normal-gc is non-nil, then the function normal-gc is called before the image is saved. The default of normal-gc is t.
If clean-down is non-nil, save-image calls (clean-down t). The default of clean-down is t.
If remarks is a string, then it is added as a comment in the save history.
:multiprocessing nil along with a true value of :environment t. Multiprocessing is needed for the GUI environment.-build command line argument, because LispWorks 6.1 and later versions call load-all-patches automatically. However, it does no harm for the build script to call load-all-patches too.
-init as the way to run LispWorks with a build script. This way is deprecated.-build, whereas with -init you need to call quit explicitly at the end of the build script.
Here is an example build script. Save this to a file such as c:/build-my-image.lisp:
(in-package "CL-USER") (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 macOS 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:
(in-package "CL-USER") (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 8.0/My LispWorks.app") #-:cocoa "my-lispworks")
deliver
dll-quit
*initial-processes*
InitLispWorks
LispWorksDlsym
load-all-patches
quit
QuitLispWorks
save-current-session
11.2 Guidance for control of the memory management system
LispWorks® User Guide and Reference Manual - 01 Dec 2021 19:30:35