$Revision: 5.0.2.4 $
Package: SYSTEM
Arguments: (id version desc &key compile-feature
superseded withdrawn (defpatch-version 1) (post-loadable t))
This macro is used for its side-effects, to define the file it appears in as a patch file. Also, whether the contents of the file are actually loaded can be controlled based on the conditions and features existing within the version of Lisp compiling the patch or the version into which the patch is loaded.
At any given time during execution, those patches currently loaded are tracked and can
be listed by the excl:dribble-bug function. A useful related function (currently
undocumented and named by an unexported symbol) is excl::print-dribble-bug-info,
which takes a stream argument (t means *terminal-io*) and prints the
dribble-bug information to that stream.
Whether or not the patch file contents were actually loaded, the sys:defpatch information is recorded in the image that attempted to load it, including information, if applicable, as to why the load was not completed. See the description of sys:load-patches for information on why a load might be aborted and what errors might occur during the loading of a patch file.
A patch file are named as follows, as described in in 5.1 The Allegro CL patch naming scheme in delivery.htm):
p<m><p><n>.<v>
So the first letter is p, followed by
sys:defpatch required arguments:
Argument |
Description |
| id | A string identifying the patch number or name. This is usually the <m><p><nnn> of the patch file name and typically includes zero-filled numeric characters -- e.g. "0a001", "1j195", "0z234" -- but can include alphabetic characters and need not be exactly five characters long. It is not the patch file prefix. This id is unique to the patch. |
| version | A fixnum in the range 1 to 999 inclusive. This is the <v> of the patch file name. |
| desc | A string containing a brief description of the patch. Short strings are better because this string is printed by excl:dribble-bug when it reports information of patches and long strings may mess up the printing (by forcing line wraps). Example "Fixes filename bug" or "Speeds up processing employee info". |
sys:defpatch keyword arguments:
Argument |
Description |
| type | A character specifying the type of the patch. Default
is nil. The update/ directory is reserved for Allegro CL and related
products. Application programmers should decide on another directory (specified as the update-directory
argument to load-patches). |
| defpatch-version | Default is 1. If a new version of sys:defpatch is supplied by Franz Inc., the default will be changed and patches with the old version will be rejected. In general, do not worry about this argument unless a new version of sys:defpatch is distributed (that distribution will include additional instructions). |
| post-loadable | Default t. When t, the patch
file can be loaded into a running image. When nil. the patch file can only be
included in an image during the original build with build-lisp-image.
The patch load will abort if load-patches tries to load it
into a running image. |
| superseded | Default nil. If true, the patch (when
loaded with load-patches) will be marked `superseded patch
- more recent version exists' and the patch will not be (further) loaded. The compile-time
effect of specifying this argument true is to ignore the remainder of the file after the sys:defpatch
form. |
| withdrawn | Default nil. If true, the patch (when
loaded with load-patches) will be marked `withdrawn patch'
and the patch will not be (further) loaded. The compile-time effect of specifying this
argument true is to ignore the remainder of the file after the sys:defpatch
form. |
| feature | Default nil. When non-nil,
value can be any form acceptable as an argument to excl::featurep (defined below in this
document). If excl:featurep returns nil
when applied to the form, the patch loading is aborted. The reason for aborting printed by
the system is the form that is the value of this argument (made into a string). |
| compile-feature | Default nil. When true, value can be any
form acceptable as an argument to excl::featurep (defined below in this document). If
excl::featurep returns nil when applied to the form during the compilation of
this patch, an error is generated with a restart 'sys::abort-patch-compiling. The purpose
of this argument is to allow patches to be compiled on several platforms. See below for
more information. |
More information on compile-feature keyword argument. This argument is designed to facilitate producing patches for different platforms. For example, suppose a patch is only applicable to :dlfcn versions of Allegro CL (those that load .so foreign files rather than .sl or .dll foreign files -- Sparc/Solaris 2 e.g.) Specifying :dlfcn as the value of compile-feature will cause compilation to proceed when compiled by a :dlfcn Allegro CL but to abort when compiled by a non-:dlfcn version. Aborting is what you want in that case, since the patch is not needed for those versions. The aborting of compilation will signal a condition which looks for a sys::abort-patch-compiling restart. If that restart is not present, an error is signaled (and the programmer must intervene to do something). More typically, compilation of patch files are done in a form like the following:
(dolist (x patch-files)
(restart-case (compile-file x)
(sys::abort-patch-compiling (patch)
;; Actions of your choice, e.g printing a message like:
(format t "Aborted patch file ~s, featurep returned nil" x))))
Compilation of the remaining patch files will continue and all relevant patch files will be present when the dolist form completes.
Patches are described in 5.0 Patching your application after delivery in delivery.htm. Patches for Allegro CL products are described in 4.2 Patches in introduction.htm.
The general documentation description is in introduction.htm. The index is in index.htm.
Copyright (C) 1998-1999, Franz Inc., Berkeley, CA. All Rights Reserved.