defpatch

$Revision: 5.0.2.4 $

Macro

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.