update-allegro

Arguments: &key documentation-only destination-directory except-patches force host list patches platform verbose version (keep-old-patches t) proxy proxy-basic-authorization auto-rebuild-images

Updating using update.exe to download patches

update.exe, when given the argument -u, will also download available patches and updates and also rebuild images. The Start | Programs | Allegro CL menu has an entry (if you have a Start menu) for Rebuild images which runs update.exe with no arguments and a Rebuild images (download new updates first) menu item. It runs update.exe with the -u argument so updates and patches are downloaded.

update.exe also takes -p and -P arguments to deal with proxies when downloading updates. These do the following:

• -p - set the proxy argument to sys:update-allegro; the form of this argument is host:port
• -P - set the proxy-basic-authorization argument to sys:update-allegro; the form of this argument is username:password.

On Windows, you may have to run update.exe as administrator.

Description of sys:update-allegro

This function contacts the Franz Inc. website and downloads the patches appropriate for your platform (computer type) and version of Allegro CL. In order to work, the computer running Allegro CL must be able to make an FTP connection to the internet. If the connection is not made for any reason, update-allegro signals an error.

On Windows using the IDE, the Download Patches dialog can be used to call this function.

Calling this function with no arguments will download and install all patches.

If you have AllegroCache or AllegroGraph installed, update-allegro will tell you if there are newer versions available (but it does not itself download these newer versions).

Unless the force argument is true, a patch file is not downloaded if the size and CRC (checksum) of an existing local file with the same name and location is the same as the remote file (but this does not cause an error or prevent downloading of other files).

Fasl file (destined for the update/ and various other directories), shared library (UNIX), and Dynamically Linked Library (DLL) patches are all handled by sys:update-allegro. On Windows, because "in use" files cannot be replaced, you will be asked to reboot your computer to finish the update process. Without rebooting, you will not see the patched DLL.

As noted below, you must rebuild images after downloading patches. This is done automatically on Macs unless the auto-rebuild-images keywrod argument is specified nil.

The keyword arguments to sys:update-allegro are as follows:

• documentation-only: retrieve only the `DESCRIPTIONS' files. Useful when you want to see what the current set of patches is. Note that new documentation files may be downloaded, but this argument has nothing to do with those files.
• destination-directory: put the patches in this directory. Useful when you want to pick and choose which patches to install. If you use a directory other than "sys:" (the Allegro directory), you will then be responsible for installing the patches. (In earlier Windows versions of this function, DLL files were installed in the Windows system directory. This is no longer done. No files are installed in the Windows system directory by update-allegro.
• except-patches: a list of patches (by location and name) to skip downloading and installing. The location should be relative to the Allegro directory (see the example below). If a name does not correspond to an actual patch file, it is ignored and no error is signaled.
• force: cause patches that have been previously downloaded to be downloaded again. In other words, the file size and CRC check mentioned above is not performed.
• host: never specify a value for this argument unless instructed to do so by Franz Inc. Technical Support.
• keep-old-patches: defaults to t. If true, old patch files are renamed to end in "bak" (or if a "bak" file is present, a numbered "bak" file -- "bak2", "bak3", etc.) Thus, if a new, modified code/streams.fasl is downloaded, the older one becomes streams.faslbak and if a new p2a002.001 is downloaded, the old one becomes p2a002.001bak. (This makes it easier to back out of a patch, particularly a patched fasl file in the code/ directory.) If the value of this argument is nil, the old file is overwritten.
• list: if specified true, no files are downloaded. Instead, sys:update-allegro returns a list of the patches that would have otherwise downloaded and installed if this argument were nil.
• patches: if true, the value should be a list of specific patches to download and install. The list should contain relative pathnames from the /pub/patches/[version]/[arch] directory on the FTP site. Only those files are downloaded.
• platform: the platform for which you wish to download patches. If you change this from the default value, you must also specify a destination-directory (an error is signaled if you do not). Installing patches for the incorrect architecture would cause serious problems, probably making your Lisp unusable (requiring uninstallation and installation to make it work again).

  We recommend that if possible you do not specify this argument and instead call sys:update-allegro on the platform of interest. (However, there might be cases, such as where the desired platform is not connected to the internet, where using this argument is necessary.)

• proxy: defaults to nil. Allows using an http proxy. See Note on using proxies below the argument descriptions.
• proxy-basic-authorization: this argument is passed to do-htpp-request, the AllegroServe function which is used during the update (see aserve/aserve.html). It allows specifying a username and a password to the proxy. The value, if non-nil, can be in one of two formats. The first allowable format is a cons of two strings: the username and the password, like this:

  :proxy-basic-authorization (cons "username" "password")
  

  The second allowable format for this argument is a string of the form "username:password". See Note on using proxies below the argument descriptions.

• verbose: if true, various status messages are printed.
• version: a specific version for which patches should be downloaded. As with platform, if you change this from the default value, you must also specify a destination-directory (an error is signaled if you do not). Installing patches for the incorrect version would cause serious problems, probably making your Lisp unusable (requiring uninstallation and installation to make it work again).
• auto-rebuild-images: Mac only. If true (the default) images will be rebuilt automatically when all patches have been downloaded. The running Lisp will exit in order that the rebuild can occur.) Specify nil if you do not want auto-rebuilding.

Note on using proxies

Users that surf through an http proxy (usually as a security measure on sites with firewalls) can specify the proxy name and port number using the proxy keyword argument, and, if necessary, a username and password using the proxy-basic-authorization keyword argument. Suppose the proxy is www.foo.com and it uses port 8000, then such users would specify the sys:update-allegro form like this (specifying other arguments as desired, of course):

(sys:update-allegro :proxy "www.foo.com:8000")

If a username and a password is also, needed, they can be specified like this (replacing "username" and "password" with the actual strings and also specifying other arguments as desired):

(sys:update-allegro :proxy "www.foo.com:8000" 
                    :proxy-basic-authorization (cons "username" "password")
  )

or, using the second allowable format for proxy-basic-authorization:

(sys:update-allegro :proxy "www.foo.com:8000" 
                    :proxy-basic-authorization (cons "username:password")
  )

Without proxy specified, sys:update-allegro will try and contact franz.com directly. In the case where users are using a proxy, that would not work. The failure symptom would be that sys:update-allegro would just hang and finally time out.

Examples:

To download all available patches for your platform and version, do:

(sys:update-allegro)

If you want all patches except update/p2a001.001, then do this:

(sys:update-allegro :except-patches
'("update/p2a001.001"))

If you want a list of patches that would be downloaded but do not want to download anything, then do this:

(sys:update-allegro :list t)

After downloading is complete

On the Mac, if the auto-rebuild-images keyword argument has its default value, which is true, images will be rebuilt when the pattches have downloaded (and the running Lisp will exit). If that argument is nil, you must rebuild images by hand as on other platforms.

It is important that you follow the instructions given to you by sys:update-allegro. It may ask you to rebuild your images or, on Windows only, to reboot your machine. If you do not follow the instructions, the update procedure will not be complete.

On Windows, when a reboot is necessary, sys:update-allegro displays a dialog asking you if you want to reboot immediately, and performs the reboot if you answer `yes'. Even if you do not reboot immediately, you should reboot before using Allegro CL further.

Patches are described in section Patches and updates of introduction.htm. The sections after that one also contain information about patches.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.