This section describes each of the deliver keywords. They are presented in alphabetical order.
:action-on-failure-to-open-display Keyword
Default value: nil
GTK and Motif applications only: if the application uses the X11 code or CAPI, it may fail to run if it cannot open the X display.
In this case, if the value is a function it calls this function with one argument, the display name. The default value of nil means that a message is printed and Lisp quits.
Default value: nil
When non-nil, the delivery code arranges to generate an analysis of what there is in the image before running the application. If the value of :analyse is a string or a pathname, it writes the analysis to this file, otherwise it writes to *standard-output*.
Default value: t on Microsoft Windows, nil on other platforms
:automatic-init specifies whether a LispWorks dynamic library should initialize automatically on loading. Automatic initialization is useful when the dynamic library does not communicate by function calls but prevents you from relocating the library if necessary or doing other initialization.
To deliver a dynamic library on non-Windows platforms, the build machine must have a C compiler installed. This is typically gcc (which is available on the Macintosh by installing Xcode).
deliver uses :automatic-init just like save-image. See save-image in the LispWorks® User Guide and Reference Manual for more details.
For more information about the behavior of LispWorks DLLs (dynamic libraries) and in particular a discussion of automatic and explicit initialization, see the chapter "LispWorks as a dynamic library" in the LispWorks® User Guide and Reference Manual.
Default value: nil
This keyword can be used to produce reports about what is left in the image when delivery is over. It is useful when determining which remaining parts of the system are not needed. When nil, no reports are generated.
Possible values of :call-count are:
:size |
After running the application, the image is scanned, and the size of each object, in bytes, is printed out. This produces a lot of output, comparable in size to the delivered image itself, so make sure you have plenty of disk space first. |
:all |
After running the application, the image is scanned, and the name of each symbol found is printed out. A
Delivery sets the call counter for all symbols to Interpreted functions do not maintain a call counter. |
t |
This has the same effect as :all, but only symbols with function definitions that were not called are printed. |
The output is written to a file or the standard output. You can specify its name with :diagnostics-file.
:classes-to-keep-effective-slots Keyword
Default value: nil
Classes on this list retain their effective-slot-definitions.
Default value: nil
This keyword accepts a list naming the classes to be deleted from image during delivery.
Note: Their subclasses are also deleted, because they have lost their connection to the root class.
Default value: t
If true, call clean-down before saving the image.
Default value: :user
Related to the :type argument of save-image. This is for expert use only - please consult Lisp Support before using.
Default value: nil
With this keyword you can make the delivered image print a list of the remaining classes, methods, or both, after execution terminates.
Possible values of :clos-info are:
:classes |
Print remaining classes only. |
:methods |
Print remaining methods only. |
:classes-and-methods | |
|
Print remaining classes and methods. | |
The output is written to the file given by :diagnostics-file.
:clos-initarg-checking Keyword
Default value: (if (delivery-value :keep-debug-mode) :default nil)
The value of the :clos-initarg-checking keyword controls whether CLOS checks initialization arguments. Initializations checked can include:
If the value is t and :keep-clos is t, :full-dynamic-definition or :method-dynamic-definition then all of these checks are switched on.
If the value is t and :keep-clos is nil, :no-dynamic-definition or :meta-object-slots then only the make-instance checking is switched on, and the other checks are switched off.
If the value is :default, the checks are not affected by the delivery process. See the function clos:set-clos-initarg-checking for instructions on controlling the checks in this situation.
If the value is nil, then all of these checks are switched off.
Note: :clos-initarg-checking always affects the behavior of the delivered application, regardless of :keep-clos.
Note: :keep-debug-mode retains the current setting of CLOS initialization checks (as set by :clos-initarg-checking or clos:set-clos-initarg-checking), rather than forcing the checks to be switched on.
Affected by: :keep-debug-mode, :keep-clos.
Default value:
(and (not (delivery-value :keep-debug-mode))
(not (delivery-value :interrogate-symbols))
(eq (delivery-value :dll-exports) :no))
x86 platforms only: If this is non-nil, the heap is compacted just before the delivered image is saved, with all functions being made static. This usually gives the greatest size reduction in delivery. You may want to leave this until the final delivery if you are using a slow machine on which this operation takes some time.
:condition-deletion-action Keyword
Default value: (when (> *delivery-level* 0) :delete)
The value is one of:
nil |
Do not delete any condition class. This is the default at delivery level 0. |
:delete |
Delete unwanted conditions. If an error for a deleted condition is signaled, it is signalled as a simple error condition, with the arguments in the format-arguments slot. This is the default at delivery level > 0. |
:redirect |
Redirect unwanted conditions to the first parent in their hierarchy which is not deleted. |
See 10.5.1 Deleting of condition classes.
Default value: :default
Windows and Macintosh only. This is the same as the :console keyword argument to hcl:save-image. See the LispWorks® User Guide and Reference Manual for details.
Default value: nil
This keyword takes a list of packages, in addition to those in the variable *delete-packages*, that should be deleted during delivery. The Common Lisp function delete-package is used to do this.
When a package is deleted, all of its symbols are uninterned, and the package's name and nicknames cease to be recognized as package names.
After the package is deleted, its symbols continue to exist, but because they are no longer interned in a package they become eligible for removal at the next garbage collection. They survive only if there are 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.
Affected by: :packages-to-keep.
Default value: nil
The string passed with this keyword specifies a file to which output generated by :call-count and :clos-info is written (in that order). The value nil means write to *standard-output*.
Compatibility Note: In LispWorks 4.4 and previous on Windows and Linux platforms, the default value of :diagnostics-file was "dvout.txt". The default value is now nil on all platforms.
Default value: t
Windows only: by default a progress bar is displayed during the delivery process. If the value of the :display-progress-bar keyword is false, it does not display a progress bar.
Compatibility Note: In LispWorks for Windows 4.4 and previous, there was no way to prevent the display of the progress bar.
Default value: nil
non-Windows platforms only: A list value means that the saved image is a dynamic library file rather than an executable. The build machine must have a C compiler installed.
If non-nil, :dll-added-files should be a list of filenames and then a dynamic library containing each named file is saved. Each file must be of a format that the default C compiler can incorporate into a shared library and must not contain exports that clash with predefined exports in the LispWorks shared library. The added files are useful to write wrappers around calls into the LispWorks dynamic library.
deliver uses :dll-added-files just like save-image. See save-image in the LispWorks® User Guide and Reference Manual for more details.
For more information about the behavior of LispWorks DLLs (dynamic libraries) see the chapter "LispWorks as a dynamic library" in the LispWorks® User Guide and Reference Manual.
Default value: :default
: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), just as for save-image.
If :dll-exports is :default, the delivered image is an executable. 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.
To deliver a dynamic library on non-Windows platforms, the build machine must have a C compiler installed. This is typically gcc (which is available on the Macintosh by installing Xcode).
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 Microsoft Windows you can use LoadLibrary from the main application to load the DLL and GetProcAddress to find the address of the external names.
There is an example DLL delivery script in 4.4 Delivering a dynamic library.
For more information about the behavior of LispWorks DLLs (dynamic libraries) see the chapter "LispWorks as a dynamic library" in the LispWorks® User Guide and Reference Manual.
:dll-extra-link-options Keyword
Default value: nil
Unix/Linux/FreeBSD and Macintosh only: A list of strings passed as arguments to the linker when creating a dynamic library file.
:dll-extra-link-options is used just like save-image. See save-image in the LispWorks® User Guide and Reference Manual for more details.
For more information about the behavior of LispWorks DLLs (dynamic libraries) see the chapter "LispWorks as a dynamic library" in the LispWorks® User Guide and Reference Manual.
:editor-commands-to-delete Keyword
Default value: :all-groups
When the Editor is loaded, you can delete some of its commands by passing a list of them with this keyword. Note that, by default, most Editor commands are retained. See 10.3 Editors for delivered applications for more details.
Affected by: :keep-debug-mode.
:editor-commands-to-keep Keyword
Default value: nil
When the Editor is loaded, you can keep some of its commands by passing a list of them with this keyword. Note that, by default, most Editor commands are retained. See 10.3 Editors for delivered applications for more details.
Default value: :default
This controls the editor emulation style used in capi:editor-pane (and subclasses) in the delivered image.
The value should be one of:
:emacs |
Use Emacs emulation. |
:pc |
Use Microsoft Windows emulation on Windows, and KDE/Gnome style keys on GTK and Motif. |
:mac |
Use macOS editor emulation. |
:default |
Use the default emulation style for the current platform. That is, use :pc on Microsoft Windows, :mac on macOS/Cocoa and :emacs on GTK and Motif. |
nil |
Use the default setting on the current machine. |
Note that not all emulation styles are supported on all platforms. See the the "Emulation" chapter of the Editor User Guide for details about the different emulation styles.
Default value: nil
The value :btrace changes error handling, so that a simple backtrace is generated whenever error is called.
:error-on-interpreted-functions Keyword
Default value: nil
If this is non-nil, an error is signalled during delivery if the interpreter is removed (with :keep-eval nil) while interpreted functions remain in the image.
On Microsoft Windows, used as the basis for the new executable. This is for expert use only - please consult Lisp Support before using.
Default value: nil
This keyword takes a list of symbols that should be exported from their home packages before any delivery work takes place.
Default value: t
If this is nil, part of the functionality of format is removed. The format directives deleted are:
~ | R P O G E C B ? < / W $
The value can also be a list of directives to keep. The elements of the list should be Lisp characters corresponding to (some of) the format directives above.
Default value: nil
This keyword takes a list of symbols to be fmakunbound during delivery.
:generic-function-collapse Keyword
Default value:
(and (>= *delivery-level* 3)
(not (member (delivery-value :keep-clos)
'(t
:full-dynamic-definition
:method-dynamic-definition))))
If this is non-nil, generic functions with single methods and simple arguments are collapsed — that is, replaced by ordinary functions.
Note: Methods cannot be added to collapsed generic functions, since after their collapse to ordinary functions the generic functions definitions are deleted.
:gf-collapse-output-file Keyword
Default value: nil
If the value is a string, it is the name of the file in which a formatted report detailing the actions performed during the generic function collapse is written. If the value is nil, no report is written.
:gf-collapse-tty-output Keyword
Default value: nil
If true, send the report of generic function collapsing to the console.
Default value:(if (eq (delivery-value :console) t) nil :default)
Windows only: The name of a file containing the icon to use, in Windows .ico format, or nil (meaning no icon -- not recommended except for console applications) or :default (which uses the icon from the LispWorks image).
Note: to achieve the same effect on macOS, do not pass :icon-file, but put your delivered image in a suitable application bundle which contains the application icon. See 15.1 Delivering a Cocoa CAPI application examples.
Default value: (if (eq (delivery-value :dll-exports) :no) :exe :dll)
:image-type defines whether the image is to be an executable or a dynamic library, , just as for save-image.
The value can be :exe, :dll or :bundle. It 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 filename extension of the delivered image, and the format of the delivered image is the same as the default. On Microsoft Windows :image-type :bundle is ignored.
On non-Windows platforms, :image-type :bundle requires that the build machine has a C compiler installed. This is typically gcc (available by installing Xcode on the Macintosh).
Note: :image-type :bundle is completely unrelated to the macOS notion of an application bundle.
Default value: nil
If this is non-nil, the delivered application is not saved, but run in memory instead.
This can be useful while still deciding on the best delivery parameters for your application. Writing the delivered image to disk takes a lot of time, and is not really necessary until you have finished work on delivering it.
Note: When using this keyword, the deliver function still demands that you pass it a filename. However, the filename you give is ignored. You can use nil.
Default value: nil
Set this to :capi for applications that use the CAPI and/or Graphics Ports.
Because the CAPI uses multiprocessing, :interface :capi also sets the deliver keyword :multiprocessing to t.
Default value: nil
When non-nil this does two things:
First it loads the reverse-pointers-code module. This can be used to check what things to keep in the image. If you need documentation for reverse-pointers-code, please contact Lisp Support.
Secondly it sets the image up such that calling the application with command line argument -interrogate-symbols, before starting the application, allows you to interrogate-symbols. See 11.15 Interrogate-Symbols.
Default value: :quit
The :interrupt-function keyword specifies what happens when the delivered application is interrupted. The value should be one of:
:quit (the default) or t. | |
|
On interrupt, the application quits. Note that | |
:ignore | The application ignores interrupts. |
:break | On interrupt, the application calls break. This is the same behaviour as in non-delivered LispWorks. |
| A function that takes no arguments. | |
| On interrupt, the function is called. The application does nothing else except call the function, so if the function returns without doing anything the interrupt is effectively ignored. Typically, the function will ask the user whether they want to quit or not. | |
Default value:
(if (= *delivery-level* 0)
:full-dynamic-definition
(if (= *delivery-level* 1)
:method-dynamic-definition
:no-dynamic-definition))
If this is :no-dynamic-definition, then the functions for dynamic class and method definition are deleted -- defmethod , defclass and so on and the direct slots and direct methods slots all classes are set to nil.
If the value of the :keep-clos keyword is nil, then it is treated as :no-dynamic-definition.
If it is :meta-object-slots, then the direct slots and direct methods of all classes are retained, and the dynamic definition functionality is deleted.
If it is :method-dynamic-definition, nothing is smashed or deleted, though the direct slots and direct methods of all classes are emptied. With this setting, methods can be defined dynamically but not classes.
If it is :full-dynamic-definition or t, then all dynamic class and method definition is allowed.
Compatibility Note: In LispWorks 4.3 and previous versions the values :no-empty and :no-empty-no-dd were documented for the :keep-clos keyword. These values are still accepted in LispWorks 8.0, but you should not rely on this. Change to one of the new values described above.
Note: CLOS initarg checking in the delivered application by make-instance and other initializations may be controlled by :clos-initarg-checking.
:keep-clos-object-printing Keyword
Default value:
(or (delivery-value :keep-debug-mode)
(<= *delivery-level* 2))
If nil, the generic function print-object is redefined to be the ordinary function x-print-object:
(defun x-print-object (object stream) (t-print-object object stream))
(defun t-print-object (object stream)
(print-unreadable-object (object stream :identity t)
(if (and (fboundp 'find-class)
(find-class 'undefined-function nil)
(ignore-errors
(typep object 'undefined-function)))
(progn
(write-string "Undefined function " stream)
(prin1 (cell-error-name object) stream))
(progn
(princ (or (ignore-errors (type-of object))
"<Unknown type>")
stream)
(ignore-errors
(when-let (namer (find-symbol "NAME" "CLOS"))
(when-let (name (and (slot-exists-p object namer)
(slot-boundp object namer)
(slot-value object namer)))
(format stream " ~a" name))))))))
You may redefine x-print-object.
Affected by: :keep-debug-mode.
Default value: (delivery-value :numeric)
If this is non-nil, all numeric functions that can handle complex numbers are retained.
Compatibility Note: This keyword has an effect on all platforms in LispWorks 5.0 and later. It has no effect in LispWorks 4.4 and previous on Windows and Linux platforms.
Affected by: :numeric.
Default value: nil
The value should be one of:
:none |
Eliminate all conditions. |
:minimal | Keep only the conditions that are in the class-precedence-list of simple-error. (simple-error, simple-condition error, and serious-condition condition). This is useful for applications that use only ignore-errors. It is equivalent to: :keep-conditions '(simple-error) :packages-to-remove-conditions '("COMMON-LISP")
|
:all |
Keep all conditions. |
| A list |
A list of conditions to keep. For each condition, all the precedence list is kept. |
See 10.5.1 Deleting of condition classes.
Default value: (> 5 *delivery-level*)
If this is non-nil, by default delivery retains the full TTY debugger, so it can be used when debugging delivered applications.
On Unix, if the value is :all, all debug information is kept.
On all platforms, if :keep-debug-mode is set to :keep-packages, all packages are retained as well as the debugger, so that they can be used for debugging purposes.
The value of :keep-debug-mode affects the default value of the following keywords too:
Default value: (= *delivery-level* 0)
If non-nil, documentation strings in the image are preserved.
Default value: nil
Keep the editor intact. By default some parts of the editor (mainly those that deal with Lisp definitions) are explicitly eliminated. When this keyword is true, nothing is removed.
Default value:
(or (delivery-value :keep-debug-mode)
(< *delivery-level* 4))
If this is non-nil, the evaluator is preserved.
Default value: nil
If this is non-nil, the internal functions needed to dump fasl files are preserved.
Default value: nil
This keyword is ignored.
Default value:
(if (delivery-value :shake-shake-shake)
(if (delivery-value :keep-debug-mode) t nil)
:all)
This keyword controls the retention of names for functions. The following values are accepted:
nil |
Do not keep names. |
:minimal |
Keep names as strings, but keep no other debug information. |
t |
Keep names as strings and retain argument information. |
:all |
Do not modify function names. |
On x86 platforms, if :call-count is either t or :all, then :keep-function-name is set to t automatically.
When :keep-debug-mode is non-nil, :keep-function-name is set to t automatically.
Affected by: :keep-debug-mode, :shake-shake-shake.
Compatibility Note: In LispWorks 4.4 and previous on Windows and Linux platforms, if the keyword :compact is non-nil, function names are eliminated. This is not true in LispWorks 5.0 and later versions.
Default value: nil
Windows only: If this is non-nil, the mouse pointer turns into a distinctive `GC' cursor during the garbage collection of generations 1 and above. (Even if the cursor is kept, generation 0 collections are never indicated, because they occur frequently and do not cause a noticeable delay in operation.)
Default value: t
If non-nil, keep symbol names of keywords.
Default value:
(or (delivery-value :keep-debug-mode)
(< *delivery-level* 5))
If the value is nil, the functions and values used to read Lisp expressions are deleted. This means that the listener no longer works. On non-Windows platforms it also prevents lw:user-preference and capi:top-level-interface-geometry-key from working.
The :keep-lisp-reader keyword is set to t automatically if :keep-debug-mode is t.
Default value:
(when (or (delivery-value :keep-debug-mode)
(delivery-value :keep-modules)
(<= *delivery-level* 2))
:full)
If this is nil, the load function is deleted. Run time loading is no longer possible when this is done, whether or not require is being used.
It can take two non-nil values:
t |
Keeps the loading code required to load data files. |
:full |
Keeps the code as for t, plus those internal functions that are required for loading Lisp code. Note that if the Lisp code uses functions that are shaken, these functions must be explicitly kept. |
Note: In most cases you need to keep the COMMON-LISP package if files might be loaded into your application, and probably some other packages too. (See :packages-to-keep.)
Default value: (< *delivery-level* 2)
If this is nil, the functions macroexpand, macroexpand-1 and macro-function are deleted, and all macro functions and special forms are undefined.
Note: This has no effect on compiled code, unless it explicitly calls macroexpand.
Default value: nil
If non-nil, the mechanism for loading modules supplied by LispWorks is preserved. We recommend using require to load all modules before delivery (see 10.7 Modules).
Compatibility note: In LispWorks 7.0 and previous versions, this defaulted to (< *delivery-level* 1).
:keep-package-manipulation Keyword
Default value: (< *delivery-level* 2)
If this is non-nil, the following package manipulation functions are preserved: shadowing-import, shadow, unexport, unuse-package, delete-package, rename-package, import, export, make-package, use-package, unintern.
Default value: nil
If nil the pprint functionality is eliminated.
Default value:
(or (delivery-value :keep-debug-mode)
(case *delivery-level*
((0 1) t)
(2 :print)
(otherwise nil)))
This keyword controls the extent to which structure internals are shaken out of the image.
If nil, all references from structure-objects to their conc-names, (BOA) constructors, copiers, slot names, printers and documentation are removed. See also :structure-packages-to-keep.
To retain slot name information (necessary if either the #S() reader syntax or CLOS slot-value are to be used for structure-objects) set :keep-structure-info to :slots.
To retain slot names and the default structure printer, set :keep-structure-info to :print.
Note: Any functions (constructors, copiers or printers) referenced in the application are retained, just as any other code would be. It is therefore not normally necessary to set this keyword.
Affected-by: :keep-debug-mode.
Default value: t
When this is non-nil, all functions deleted by the treeshaker are replaced by small stub functions. When a deleted function is called by the application, its stub prints a message telling you that the function has been deleted and how it can be reinstated. These stubs can take up a lot of space if you smash large packages, but are invaluable while refining delivery parameters.
For instance, if your application calls complexp after delivery with :keep-complex-numbers set to nil, a message like the following is printed:
Attempt to invoke function COMPLEXP on arguments (10). COMPLEXP was removed by Delivery keyword :KEEP-COMPLEX-NUMBERS NIL. Try :KEEP-COMPLEX-NUMBERS T.
Default value: nil
A list of symbols that must retain their symbol names.
Default value: nil
This keyword takes a list of symbols that are retained in the delivered image. A pointer to this list is kept throughout the delivery process, protecting them from garbage collection.
Default value:
(or (< *delivery-level* 5) (delivery-value :keep-debug-mode))
If this is nil, functions for handling the top level read-eval-print loop are deleted. Note that this means that if the line based debugger is invoked, there is no way to communicate with it.
Note: the top level history is cleared, regardless of the value of the :keep-top-level argument.
Affected by: :keep-debug-mode.
Default value: (delivery-value :numeric)
If this is nil, eliminate transcendental functions (for example sin).
Compatibility Note: This keyword has an effect on all platforms in LispWorks 5.0 and later. It has no effect in LispWorks 4.4 and previous on Windows and Linux platforms.
Affected by: :numeric.
Default value: nil
If this is nil, the walker is deleted.
Default value: nil
If non-nil, keep cross-reference information that is used by functions like hcl:who-calls and hcl:calls-who.
Compatibility note: In LispWorks 6.1 and earlier versions cross-reference information is kept if any of the functions that use it is kept. Now the cross-reference information is cleared even if any of these functions is kept, unless this keyword is non-nil.
Default value: (> *delivery-level* 0)
The dspec table is an internal table used for tracking redefinitions by defadvice, trace and so on. If this keyword is non-nil it does an implicit call to untrace, and previous uses of trace and defadvice are discarded.
Default value: nil
This keyword is obsolete. Was previously used to pass license information for products on certain platforms.
:macro-packages-to-keep Keyword
Default value: nil
A list of package names. Symbols in these packages that have a macro definition are not fmakunbound when the delivery process deletes macros from the image (when :keep-macros is nil). Note that if these symbols are not referenced, they may be shaken anyway. When :keep-macros is nil, this keyword has no effect.
:make-instance-keyword-check Keyword
Default value: (if (delivery-value :keep-debug-mode) :default nil)
This keyword is deprecated in favor of :clos-initarg-checking.
The value of the :make-instance-keyword-check keyword controls whether make-instance checks its initargs in the delivered application, and in LispWorks 6.1 this was extended to include checking in the other CLOS initializations.
Note: :make-instance-keyword-check now does the same comprehensive checking as :clos-initarg-checking but is deprecated as its name is no longer accurate. Please use :clos-initarg-checking instead.
Affected by: :keep-debug-mode.
Default value: nil
Windows only. Overrides the default application manifest, which can affect whether an executable application is themed.
If the value is a string it must name a file that is a legal application manifest containing the "dependency" element for Microsoft.VC80.CRT. If the value is the keyword :no-common-controls-6 a manifest without the element for common controls is used. If the value is nil, then the LispWorks manifest is used.
See 7.2 Application Manifests for more information about Windows application manifests in LispWorks applications.
:metaclasses-to-keep-effective-slots Keyword
Default value:
(when (member (delivery-value :keep-clos)
'(t :full-dynamic-definition))
:all)
If the value is a list, the elements are metaclasses whose classes retain their effective-slot-definitions. Value :all means all metaclasses.
Default value: nil
If set to t, starts multiprocessing with the delivery function (that is, the first argument to deliver) running in a process created specially for it.
If set to :manual, allows multiprocessing to be started by the delivery function, which should call mp:initialize-multiprocessing.
If set to nil, multiprocessing cannot be used in the delivered application.
The value of this keyword argument is automatically t when :interface is :capi, so you only need to supply it if CAPI is not being used.
Default value: delivery::*never-shake-packages*
A list of package names that will not be shaken. These packages and all their symbols are preserved.
:no-symbol-function-usage Keyword
Default value: (not (delivery-value :keep-debug-mode))
x86 platforms only: eliminates symbols that are used only for function calls.
See 11.14 Debugging with :no-symbol-function-usage for information about debugging an image where these symbols have been eliminated.
Default value: t
Keep all numeric operations, unless overridden by :keep-complex-numbers.
Compatibility Note: This keyword has an effect on all platforms in LispWorks 5.0 and later. It has no effect in LispWorks 4.4 and previous on Windows and Linux platforms.
Default value: t
This keyword has an effect on x86 32-bit platforms only. It allows the delivered image to run on old Pentium-compatible CPUs that do not support SSE2 instructions.
LispWorks 6.0 and later on x86 platforms uses instructions that are part of SSE2. All new CPUs have SSE2, but it may be required to run LispWorks runtimes (that is, delivered images) on old machines without SSE2. On these machines the SSE2 instructions are not implemented, and cause exceptions.
When :old-cpu-compatible is non-nil, deliver creates a runtime with a mechanism that checks for SSE2 on startup. If the run time machine does not have SSE2, this mechanism then eliminates the SSE2 instructions. This mechanism allows the runtime to run on any Pentium-compatible CPU.
The cost associated with this mechanism is negligible, so normally there is no reason to change the default value of :old-cpu-compatible.
Default value: nil
This keyword takes a list of packages to be retained. All packages in the list are kept in the delivered image, regardless of the values of the :smash-packages and :delete-packages keywords.
If :packages-to-keep is :all, then the two variables above are set to nil. See also 10.11 Coping with intern and find-symbol at run time.
Note: Other keywords push packages onto the :packages-to-keep list.
Note: When you keep a package by :packages-to-keep, this does not cause that package's symbols to be kept. To retain symbols, see 10.10.2 Ensuring that symbols are kept.
:packages-to-keep-externals Keyword
Default value: nil
A list of packages that should retain their external symbols, even when :shake-externals is t (the default). When :shake-externals is nil, this keyword has no effect.
The externals of the setf package are always retained, regardless of the value of :packages-to-keep-externals.
:packages-to-keep-symbol-names Keyword
Default value:
(if (or
(delivery-value :keep-debug-mode)
(< *delivery-level* 5))
:all
nil)
A list of packages that should keep their symbol names. The names of symbols in these packages are not modified, irrespective of the value of :symbol-names-action.
The value can also be :all, meaning all packages.
:packages-to-remove-conditions Keyword
Default value: nil
A list of packages whose conditions are removed (that is where the symbol-package of the name of the condition is one of the packages). The system automatically adds the internal packages to this list. Conditions that are in these packages but are also in the :keep-conditions list or its precedence list are kept. The defaults cause all the conditions that are defined by the system and are not standard to be deleted. To keep all the conditions, you should pass :keep-conditions :all (or :condition-deletion-action nil). To eliminate all conditions, you should pass :keep-conditions :none.
See 10.5.1 Deleting of condition classes.
:packages-to-shake-externals Keyword
Default value: nil
A list of package names for which their external symbols should be shaken when the value of :shake-externals is nil. When the value of :shake-externals is t (the default), this keyword has no effect.
The externals of the keyword package are always shaken, regardless of the value of :packages-to-shake-externals.
:post-delivery-function Keyword
Default value: nil
When non-nil, the value :post-delivery-function should be a function designator for a function of one argument:
post-delivery-function successp
The system calls :post-delivery-function after delivery. successp is true if delivery was successful and false otherwise.
Note: during the delivery process, the Lisp system can be in an unstable state, so it is not always possible to recover when delivery is not successful.
Default value:
(or (= *delivery-level* 0)
(delivery-value :interrogate-symbols))
When this is nil, the mechanism for printing circular structures is eliminated.
Default value: nil
This keyword is ignored.
Default value: nil
On Microsoft Windows only :product-name provides the name that is used in CAPI dialogs which have no specific title or owner.
On other platforms, :product-name is ignored.
Default value: t
If t, then after the application has opened at least one CAPI window, whenever the application is waiting for input, a routine is run to check whether any of its CAPI windows are still open. If there are no open windows, the application exits.
On Microsoft Windows, if the application is an automation server, the checking routine also checks the server. If the application uses com:automation-server-top-loop (maybe indirectly via com:automation-server-main), the checking routine does not cause exit until com:automation-server-top-loop exits. Otherwise the checking routine does not cause exit as long as the server is used. After the server is not used, the exit is further delayed by the exit-delay (default 5 second, see documentation for com:set-automation-server-exit-delay).
The function set-quit-when-no-windows can be used to turn checking on and off dynamically at run time regardless of the value of the :quit-when-no-windows keyword.
Note: a multiprocessing LispWorks executable will stop multiprocessing when there is no process other than the Idle Process. So if your application simply displays a window, which is closed, then multiprocessing will stop. This is independent of :quit-when-no-windows.
Default value: (>= *delivery-level* 1)
When this is true, the function compile is eliminated from the image.
Note: the function compile-file is always removed by delivery, regardless of :redefine-compiler-p.
Path for storing user preferences.
On Microsoft Windows this is relative to HKEY_CURRENT_USER.
On macOS, Linux and other Unix-like platforms this is relative to the user's home directory.
Note: see 10.4 Delivery and CAPI for information on a possible problem with delivered applications that record window geometries in the registry.
:remove-plist-indicators Keyword
Default value: nil
This keyword takes a list of plist indicators to be deleted.
:remove-setf-function-name Keyword
Default value: (not (delivery-value :keep-macros)
When t, the direct pointer from a symbol to its setf expansion is removed. That means that macroexpansion of setf is not reliable anymore. Normally, that is not a problem for the application.
Default value: t
If this is t, the function argument to deliver is used as the application startup function.
If this is nil, no application startup function is called when the delivered image is started up.
The image exits immediately upon startup when :run-it is nil. Any :call-count report requested is still generated on exit.
This keyword can be useful if you want to look at the symbols in the image (with the keyword :call-count) but cannot you actually run the application — for example because the application links up to a database, but the database has not been started up. In such cases, set it to nil.
:shake-class-accessors Keyword
Default value:
(cond ((>= *delivery-level* 4) :remove)
((>= *delivery-level* 3) t)
(t nil)))
This keyword controls whether class accessor functions are kept in their slot-definition objects. Removing them allows unreferenced functions to be deleted.
If it is nil it ensures all accessors are kept.
If it is non-nil, class accessors which are never referenced are deleted.
If it is :remove, all class accessor functions are removed from their slot descriptions.
In general, accessors may be safely removed. However, if your application needs to examine the slots of class instances, you need to retain them.
:shake-class-direct-methods Keyword
Default value: (>= *delivery-level* 3)
This keyword controls whether class-direct methods are deleted.
Note: A method is not deleted if it specializes on a class that remains in the delivered image.
Default value: (>= *delivery-level* 2)
This keyword controls whether classes are shaken.
Default value: t
If this is nil, all external symbols are preserved.
If this is non-nil, external symbols are also made eligible for garbage collection when the treeshaker is invoked. See also :packages-to-shake-externals.
Default value: (>= *delivery-level* 2)
If this is non-nil, the treeshaker is invoked during delivery. The treeshaker attempts to get rid of unreferenced symbols from the delivered image.
It uninterns every package's internal symbols. (In the special case of the KEYWORD package, it uninterns the external symbols.) A garbage collection is then carried out, after which any remaining symbols are re-interned in the package from which they came. A similar procedure for class definitions and methods discriminating on classes is also performed.
If you require that certain internal symbols be kept, and know they will not be kept because they are not referenced in the image, you can export them explicitly. See :exports. Doing so prevents them from being deleted.
External symbols are shaken by default.. See :shake-externals.
Default value: nil
This keyword takes a list of packages that should be smashed during delivery.
When a package is smashed, all of its symbols are uninterned, and the package structure is deleted. Also, its function definitions, property lists, classes, values, and structure definitions are deleted or set to nil.
See 10.9.3 Smashing packages for more details.
Caution: Smashing destroys a whole package and all information within its symbols. You are advised to avoid using it if possible. A better alternative, if you cannot deal individually with symbols, is :smash-packages-symbols.
Affected by: :keep-clos, :packages-to-keep, :keep-debug-mode.
:smash-packages-symbols Keyword
Default value: nil
Takes a list of packages as for :smash-packages but only the symbols in each specified package are smashed. The package is left, making it easier to see which symbols in the specified packages are pointed to by other packages.
Default value: :default
The main use of :split is to allow third-party code signing to be applied to the executable or dynamic library.
See the documentation for split argument to save-image in the LispWorks® User Guide and Reference Manual.
Default value: :internal
Either nil, :internal or a string naming a file containing an image to be displayed when the application starts.
The value nil means no bitmap is displayed.
The default value :internal causes the "Built With LispWorks" splash screen to be displayed.
If a string is supplied on Microsoft Windows, the image needs to be in Windows Bitmap format and must be Indexed Color rather than RGB color.
If a string is supplied on Cocoa, GTK and Motif, the image can be in any format supported by Graphics Ports, and the file will be read as if by gp:read-external-image. See the "Working with images" section in the CAPI User Guide and Reference Manual for details.
On Windows the user can dismiss the startup screen by clicking on it. It can be dismissed programmatically by calling win32:dismiss-splash-screen - see the LispWorks® User Guide and Reference Manual for details.
:structure-packages-to-keep Keyword
Default value: nil
A list of packages. For symbols in these packages that have a structure definition, delivery keeps all the information in this structure definition, regardless of the value of :keep-structure-info.
Default value: (>= *delivery-level* 5)
Defines what to with symbol names. When it is nil, or when :packages-to-keep-symbol-names is :all, all symbol names are kept. When :symbol-names-action is t, symbol names (except those which are kept by :keep-symbol-names, :keep-keyword-names or :packages-to-keep-symbol-names) are changed to the same string "Dummy Symbol Name".
:symbol-names-action is treated as nil unless the treeshaker is invoked during delivery (see :shake-shake-shake).
Compatibility Note: in LispWorks 4.4 and previous on Windows and Linux platforms, :symbol-names-action t shortens symbol names to a three-character unique code. This has changed, as described above, in LispWorks 5.0 and later.
Removing symbol names makes it very difficult to debug the application, and it is assumed that it is done after the application is essentially error free. However, some applications may make use of symbol names as strings, which may cause errors to appear only when the symbol names are removed. In some cases the easiest solution is to retain symbol names. This will result in a larger executable, though the size increase is usually small.
If you do want to remove symbol names and need to debug your application, :symbol-names-action takes these other values :spell-error, :reverse, :invert and :plist. Note that these other values are only useful when debugging an application which works with :symbol-names-action nil but not with :symbol-names-action t. In other cases they simply make debugging difficult to no advantage.
In the case of :spell-error (which is probably the most useful), the last alphabetic characters in the first 6 characters of the symbol name are rotated by one, that is, A becomes B, g becomes h, and Z becomes A. This leaves the symbol names quite readable, but any function that relies on symbol names fails. A more drastic effect is achieved by the value :reverse, which reverses the symbol name. The value :invert just changes the case of every alphabetic character to the other case. This is more readable than :spell-error, but if the application relies on symbol names but does not care about case, the errors do not appear. The value :plist causes the symbol names to be set to the dummy name, but the old string is being put on the plist of the symbol (get symbol 'sys::real-symbol-name). A simple backtrace (obtained after :error-handler :btrace) uses this property when it exists to get the symbol name to display.
If the debugging shows that some symbols must retain their symbol name for the application to work, this must be flagged to deliver by either :keep-symbol-names or :packages-to-keep-symbol-names.
After debugging your delivered application using :spell-error, :reverse, :invert or :plist, you may want the production build to be done with :symbol-names-action t to remove symbol names and achieve a small reduction in size.
Compatibility Note: in LispWorks 4.4 and previous on Windows and Linux platforms, :symbol-names-action allows the value :dump. This is no longer supported.
:symbols-to-keep-structure-info Keyword
Default value: nil
A list of symbols of which the structure information should be kept, in addition to the symbols in the packages in :structure-packages-to-keep.
Default value: nil
Windows only. The keyword :default or a plist containing containing version information to be placed in the delivered file.
If :versioninfo is nil, no version information is supplied. If :versioninfo is :default, then the version information in the :exe-file is retained (by default, there is no version info). Otherwise :versioninfo should be a plist of the following keywords. All strings should be in a form suitable for presentation to the user. Some of the keywords discussed below are mandatory, and some are optional.
Mandatory keywords:
:binary-version :binary-file-version :binary-product-version | |
|
You must specify either The file version relates to this file only; the product version relates to the product of which this file forms a part.
If
The binary version numbers are 64-bit integers; conventionally, this quantity is split into 16-bit subfields, denoting, for example, major version, minor version and build number. For example, version 1.10 build 15 might be denoted Note: There is no requirement to follow this convention; the only requirement is that later versions have larger binary version values. | |
:version-string :file-version-string :product-version-string | |
|
You must specify either The file version relates to this file only; the product version relates to the product of which this file forms a part.
If The version strings specify the file and product versions as strings, suitable for presentation to the user. There are no restrictions on the format. | |
:company-name |
The name of the company producing the product. |
:product-name |
The name of the product of which this file forms a part. |
:file-description | A (brief) description of this file. |
Optional keywords:
:private-build | Indicates that this is a private build. The value should be a string identifying the private build (for example, who the build was produced for). |
:special-build | Indicates that this is a special build, and the file is a variation of the normal build with the same version number. The value should be a string identifying how this build differs from the standard build. |
:debugp |
A non-nil value indicates that this is a debugging version. |
:patchedp |
A non-nil value indicates that this file has been patched; that is, it is not identical to the original version with the same version number. It should normally be nil for original files. |
:prereleasep |
A non-nil value indicates that this is a prerelease version. |
:comments |
A string value, which allows additional comments to be specified, in a form suitable to presentation to the user. |
:original-filename | This specifies the filename (excluding drive and directory) of this file. Normally it is defaulted based on the filename argument to deliver. |
:internal-name |
This the internal name of this file. Normally it is defaulted to the value of |
:legal-copyright | A string containing copyright messages. |
:legal-trademarks | A string containing trademark information. |
:language | The language for which this version of the file is intended.
This can be either a numeric Windows language identifier, or one of the keywords listed below. The default is :arabic :bulgarian :catalan :traditional-chinese :czech :danish :german :greek :us-english :castilian-spanish :finish :french :hebrew :hungarian :icelandic :italian :japanese :korean :dutch :norwegian-bokmal :polish :brazilian-portuguese :rhaeto-romanic :romanian :russian :croatio-serbian-latin :slovak :albanian :swedish :thai :turkish :urdu :bahasa :simplified-chinese :swiss-german :uk-english :mexican-spanish :belgian-french :swiss-italian :belgian-dutch :norwegian-nynorsk :portuguese :serbo-croatian-cyrillic :canadian-french :swiss-french |
:character-set | Specifies the character set to use. Acceptable values are either the numeric ID of a character set, or one of keywords listed below: :ascii :windows-japan :windows-korea :windows-taiwan :unicode :windows-latin-2 :windows-cyrillic :windows-multilingual :windows-greek :windows-turkish :windows-hebrew :windows-arabic |
:additional-pairs |
Allows adding arbitrary string-name/value pairs to the main
The argument is a plist whose elements are all strings. Each two strings constitute a string-name/value pair, which are added to the main The string-name in a pair can be also one of the recognized keywords. Example: :additional-pairs '("MIMEType" "application/basic-plugin")
|
:string-file-info |
Adds a
The argument has to be a plist. Each two items in the list constitute a pair of string-name/value, which are added to the block. The special keywords
To be useful, the plist must include either |
:warn-on-missing-templates Keyword
Default value: nil
Controls whether to warn about missing CLOS templates, which should be pre-compiled. See 10.1.2.1 Finding the necessary templates for details.
Delivery User Guide - 01 Dec 2021 19:35:04