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 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 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 true, value can be
any form acceptable as an argument to excl::featurep (defined
below in this document). If 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 for applications are described in Patching your application after delivery in delivery.htm. Patches for Allegro CL products are described in Patches in introduction.htm.
The documentation is described in introduction.htm and the index is in index.htm.
Copyright (c) 1998-2000, Franz Inc. Berkeley, CA., USA. All rights reserved.
Created 2000.10.5.