Macro | Package: system | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Unrevised from 8.2 to 9.0. 8.2 version

## defpatch

Arguments: id version desc &key compile-feature 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 dribble-bug function. A useful related function is print-system-state, which takes an optional stream argument defaulting to `*standard-output*` and prints the dribble-bug information to that stream.

Whether or not the patch file contents were actually loaded, the 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.

Patch files 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

- [m], one character denoting the version of Allegro CL, followed by
- [p], one character denoting the product, followed by
- [n], three characters denoting the patch sequence number, followed by a period (.), followed by
- [v], three characters denoting the patch version.

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`. No longer used. (Patches are loaded from highest version down, so a superseded patch will never be seen.)
withdrawn | Default `nil`. If true, the patch (when loaded with load-patches) will be marked `withdrawn patch' and earlier versions of the patch, if any, are looked for and loaded if present. 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 and updates in introduction.htm.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.

|  | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Unrevised from 8.2 to 9.0. 8.2 version