ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0

This document describes installation of Enteprise and Professional Allegro Common Lisp and related products. Installation of the free Allegro Common Lisp Express Edition is described in another document (express-installation.html).

Allegro CL 11.0 is provided in two versions on most platforms: an SMP version which can use more than one hardware processor at a time and a non-SMP version which uses only one processor. These two versions have separate downloads and their fasl files (output of the Lisp compiler) are not compatible: you download and install each separately. Please also note:

- SMP is supported on all platforms. If you intend to use the SMP version, please look at smp.html. Note that Lisp code which runs correctly in the non-SMP version may fail (often by producing incorrect results rather than erroring) in the SMP version if, for example, separate processes try to simultaneously modify stored values.
- There is no 32-bit version for ARM, only 64-bit is available there.
- Common Graphics and the IDE are only available on Windows, Linux and macOS. There is no version for FreeBSD.

For each distribution, the installation process of Allegro CL 11.0 is similar to installation of previous versions of Allegro CL. In some cases, the process has been simplified. Linux and Apple macOS users no longer need to install GTK (and XQuartz on macOS), as the IDE is purely browser based on those platforms.

Once Allegro CL is installed, the following documents are a good place to start:

- release-notes.html: the Release Notes for Allegro CL and all add-on products.

- index.html: this document is the introduction to and overview of the documentation and has links to all other documents.

- startup.html: this document describes how to start Allegro CL and what the startup procedure is. See particularly Starting on Windows machines in that document.

- cgide.html: this document is the introductory document for Common Graphics and the Integrated Development Environment. It contains pointers to the rest of the CG and IDE documentation.

- eli.html: this is the documentation for the Emacs-Lisp interface (ELI). While the IDE can provide a substitute for running Allegro CL as a subprocess of Emacs, many users like to use Emacs along with the IDE. The Emacs-Lisp interface provides many commands etc. for facilitating running Allegro CL in that way. See particularly What should be in your .emacs file in that document for information on what to add to your .emacs in order to ensure the Emacs-Lisp interface code is loaded.

  Some users prefer to use SLIME, and we feel it is a good alternative to ELI. In recent years, SLIME has seen more development than ELI.

  SLY is a fork of SLIME and is an alternative to both SLIME and ELI.

  Both SLIME and SLY are fine alternatives to ELI.

## 1.0 Definitions of some terms used in this document

- Allegro directory: the directory where Allegro CL is installed. On Windows, the installation default is `c:\acl11.0\`. When we describe a pathname including the Allegro directory, we typically surround it in brackets, for example: the directory where you put patch files is [Allegro directory]/update/.
- Download file: the compressed tar file (on UNIX), or the self-extracting executable file (on Windows), or the dmg file (on macOS), which contains the Allegro CL software and which is uncompressed and untarred (UNIX) or run (Windows) or opened (macOS).
- Platform: the combination of hardware and operating system on which you will install Allegro CL. Some operating systems (macOS, Linux) have multiple hardware types. Take care to download the correct one for your specific machine.

## 2.0 Preinstallation information

### 2.1 Installation sizes and supported Operating Systems

The size of the Allegro directory, after installation, is approximately 500 Mbytes, but it varies by platform. More space may be required during installation for temporary files.

The list of supported operating systems can be found in the release notes for the version of Allegro you are installing.

### 2.2 Previous versions of Allegro CL

Before installing a new version of Allegro CL, you do not need to uninstall the previous version.

Note: on Windows, installation updates the registry so that extensions (such as .lpr and .dxl) refer to the most recently installed version.

### 2.3 Obtaining a license file

You must have a license file to use Allegro CL and its associated products. The license file is not included with the regular distribution (it is included with the Express Edition and pre-releases of Enterprise/Professional). The license file also controls access to certain features in the product.

Professional and Enterprise customers with current support agreements should have received an email message with instructions on how to obtain their license file. The email contains a URL from which the license file can be retrieved. If you are unable to download the license file from this email, let us know.

You should retrieve the license as soon as you receive the email, even if you have not downloaded the software, so the license file will be ready when you install Allegro CL. The name of the file, when it is installed, must be devel.lic.

The license file is a text file which includes plain and encrypted text parts. See The Allegro CL license file in startup.html for a sample, if you have problems starting Allegro and think your license file may be corrupted.

If you upgrade your license or purchase additional add-on products, you will be sent new email with instructions for retrieving a new license file. Placing the new license file in the Allegro directory is all you must do to use the upgraded version of the new add-on products. You should regenerate any applications which were built with the old license file, however.

If you do not have a license file or the license file you have does not seem to license the correct product mix, contact your Account Manager.

## 3.0 Installing Allegro Common Lisp

If you have the Express Edition, see express-installation.html.

Here are the installation steps:

1. Download the software: you should have received email instructions for downloading the software. See the information above about how to contact us if you have a problem with your license file or downloading.

   In all cases, the download is a single file. The file's extension is exe for Windows, dmg for macOS, and tbz2 for Linux and FreeBSD.

2. Install the software: skip to the appropriate section for your platform:

   - Windows .exe installation
   - macOS .dmg installation
   - Linux and FreeBSD .tbz2 installation

3. Install the license file: If you do not already have the license file, then please read obtaining a license file above. You cannot use the product until you have installed a valid license file.

   Note: the license file is included in the Express Edition.

   Installing the license file on Macs requires special steps, see below. On all other platforms you install the license file by copying it to the Allegro installation directory and making sure it is named devel.lic.

4. Test the installation: now that everything is installed, it is time to make sure it works. See testing the installation worked below.

5. Install OpenSSL libraries (OPTIONAL): see Installing OpenSSL below for more information.

6. Download patches: patches (correcting bugs or providing new features) are released for Allegro CL regularly. For normal usage, we recommend that you update regularly, including immediately after installation. See The update program below for information on getting and installing patches.

   On some operating systems, you may need to elevate to administrator privileges to perform the update process.

   On Windows, there is a menu item update.exe (download new updates + rebuild images) that will perform both tasks (and ask for administrator privileges if it needs to be administrator to do so).

7. Install Emacs and ELI (OPTIONAL): see our website for details, if you want to install GNU Emacs or ELI.

### 3.1 Installing on Linux and FreeBSD

1. The installation on UNIX uses built-in command `tar`:

       $ cd /usr/local
       $ tar jxf acl11.0-linux-x64.tbz2

   You may choose any parent directory for the installation. Just change the first `cd` command above to include your desired parent location. The above command will create a new directory with a name something like acl11.0.64. In this case, the Allegro installation directory would be /usr/local/acl11.0.64/.

2. Copy the license file into the Allegro directory and change its name to devel.lic.

See the testing the installation section below.

#### Troubleshooting on Linux

Newer versions of Glibc (we know it happens with version 2.41) might cause problems. For example, if you see this error:

    /usr/local/acl11.0express.64/libacli11029t6.so:
    cannot enable executable stack as shared object requires: Invalid argument

This is due to security changes in Glibc for which we made a patch in March 2025 for version 11.0.

There is a bit of a chick and egg problem with patching this: the patch mechanism runs Allegro CL to patch itself and if Allegro CL does not run then it cannot patch itself. In this case, you can fix the issue without patching by doing this:

    $ cd /usr/local/acl11.0.64/
    $ execstack -c *.so

This will clear the executable stack flag of the shared libraries that Allegro CL uses.

NOTE:: if `execstack` does not exist on your system, then you will need to install it. It is out of the scope of this document to specify how this is done for your particular flavor of Linux.

### 3.2 Installing on Windows

1. Exit any existing running Allegro CL instances. Installation is most likely to be trouble free if there are no other Allegro CL instances running.

2. Execute the downloaded installer. This will start the installation program. Each dialog in the installation program has a different purpose (agree to license, choose installation directory, etc). Click Next until you are presented with a Finish button, selecting your preferred options along the way.

3. A dialog may appear when the installation is finished saying you must restart the machine to complete the installation and asking if you want to do this now. Restarting is not always necessary. Clicking Cancel ends the installation process and does not restart the machine. If restarting is required and you choose to delay it, do not use Allegro CL until you have restarted. We assume in the subsequent steps you have restarted if necessary.

4. Copy the license file into the Allegro directory and change its name to devel.lic.

See the testing the installation section below.

### 3.3 Installing on macOS

NOTE: see this note about updating in the presence of OpenSSL 3.3.

(Be sure to see the macOS 14 (and later) permission fix for updating Allegro CL below.)

Allegro CL on macOS is distributed both as a dmg file and as a zip file. This section will focus on the dmg installation, as the zip installation is for advanced users who should know how to use and install it.

Open the dmg file you downloaded. When you do, you will see something like this:

To install, you drag the AllegroCL64 icon to the /Applications folder icon. (The picture shows AllegroCL64 but the actual name may differ depending on what you downloaded). You may be asked to authenticate during the copy to /Applications. The Finder will show a progress bar during the copying process, which should take no more than a few seconds. Once it is done, you can close the Finder window for the dmg and unmount it (eject the icon on your Desktop, etc). You should now see a new application in /Applications for what was just installed. The name will depend on which version you installed, but it will always start with AllegroCL.

Installing the License File on the Mac

NOTE: Express users can ignore this section, as the license file is already included in the installation.

You must let Allegro CL install the license file just after installation by starting Allegro CL without the license and telling it where the license can be found. If you copy the license file into the /Applications/AllegroCL64.app/Contents/Resources/ directory and then try to start Allegro CL, macOS will think the application is damaged and will not start. Once you have run Allegro CL the first time and the license has been installed, you can copy new licenses in (when, for example, you add new features and get one with a later expiration) to replace the existing one. If you delete the license file, starting Allegro CL will again prompt you for its location.

As noted, the license file lives in the Contents/Resources/ subdirectory of the main application directory:

    /Applications/AllegroCL64.app/Contents/Resources/devel.lic

IMPORTANT: if the license file is invalid or becomes corrupted and you try to start the IDE from Finder, then you will briefly see the icon for Allegro CL in the Dock but the IDE will not start properly. (If the license file is simply not there, you will be prompted for its location.) To confirm the reason for the IDE not starting, run it from a Terminal to see the error message (use the correct folder name if it differs from AllegroCL64.app, script is the correct startup script when running in a terminal to start the IDE):

    $ /Applications/AllegroCL64.app/Contents/Resources/script
    Looking for valid 64-bit Mac OS (Apple Silicon) license file, but found
    invalid license file
    (/Applications/AllegroCL64SMP.app/Contents/Resources/devel.lic).  Lisp
    cannot start up.
    $

This means you have a corrupt or improperly installed license file.

See the testing the installation section below.

## 4.0 Installing OpenSSL

If you have no interest in using the SSL module in Allegro CL or deploying Common Graphics applications via a web browser, then you may skip this entire section and its subsections. Otherwise, there is very important information in this section, especially for deployment of applications.

### 4.1 OpenSSL requirements

Allegro CL uses OpenSSL for the See Secure Socket Layer (SSL) protocol and the `:ssl` module. It is the basis for HTTPS communication using AllegroServe.

The IDE uses SSL communication but has its own version of the OpenSSL libraries, if none are found via the mechanisms discussed here. This means developers who need a specific version of OpenSSL can configure their environment so the IDE uses it, and users who do not use and install OpenSSL can still use the IDE.

The `:ssl` module, when loaded, generally finds the newest installed version of OpenSSL libraries and loads them. There are exceptions to this (see below).

If you load foreign libraries which themselves use OpenSSL, either in a development image or in a delivery (application) image, those libraries must be compatible with the version of OpenSSL used by the `:ssl` module. If they are not, the `:ssl` module cannot be used.

In general, we support currently supported versions of OpenSSL, which, at the time of the 11.0 release, are 1.0 (Linux only), 1.1, 3.0 and 3.1.

> OpenSSL 1.0 is only supported on Linux, even though official support for it has been dropped, because Red Hat themselves are maintaining it for their customers. This means that some Linux versions, CentOS and RHEL variants (e.g. Rocky Linux), will continue to support OpenSSL 1.0 for some time. When native operating system support is dropped on these platforms, we will cease to support it on those platforms.

On Linux and FreeBSD, we strongly recommend that you use the native operating system version of OpenSSL with Allegro CL.

On macOS and Windows, the situation is more complex. See the sections below for each of these platforms for a detailed explanation of how OpenSSL is installed on those platforms.

### 4.2 Application deployment considerations

There are two issues with deployment:

- The application developer is responsible for communicating to users of the application the need to install a compatible version of OpenSSL.
- Application security relies on OpenSSL being kept up to date.

Installation of OpenSSL by users of the application

Unless you include a version of OpenSSL with your application, users will be required to install it before they can use the application.

See the next section for considerations on including it or not, but if you have determined you want to include it, then merely including the specific OpenSSL libraries loaded when `(require :ssl)` is evaluated in the main application directory is enough.

Security of data touched by the application

Because SSL is used to secure communications, it is imperative that it be secure. OpenSSL, like all software, can have vulnerabilities. It is vital that any vulnerabilities in OpenSSL be patched quickly as soon as they are discovered. There are many organizations looking for vulnerabilities in OpenSSL and updates with security fixes are common.

When you build an application that uses OpenSSL, the product of the application build is a set of files in a directory. By design, OpenSSL libraries are not included in that directory. It is also up to you to inform your customers about the security implications of OpenSSL and keeping it up to date.

What happens when OpenSSL is not found

The startup of a generated application that does not have a compatible OpenSSL installed and available will trigger an error page in the user's default browser. The default version of this error page is not suitable for end users and it should be replaced with one which is.

There are two templates for this error page that can be used to construct an application-specific error page. The files are ssl-not-found.html and ssl-not-found-app.html; both live in the Allegro installation directory. The former is used by the IDE if it does not find OpenSSL when it starts up, and the latter is the default used by CG/JS applications generated with Allegro CL's IDE. The name of the error file in the generated application is ssl-not-found.html. Please read the discussion of adding your own version of ssl-not-found.html to your IDE project.

macOS-specific issues for deployment

On macOS, be aware there are Finder issues for deployment of applications.

Specifying the location of shared libraries on macOS can be tricky. See our discussion of OS-Specific Library Search Path.

### 4.3 Installing OpenSSL on Linux and FreeBSD

Many linux platforms and the Mac include OpenSSL as part of the regular OS installation. On such platforms, no action is typically required to use OpenSSL with Allegro CL. If your platform does not include OpenSSL libraries or if for some reason you want a different version than that supplied by the OS, get further information at openssl.org. See Secure Socket Layer (SSL) in socket.html for further information and instructions on how to ensure Allegro CL can find the OpenSSL libraries when required.

### 4.4 Installing OpenSSL on macOS

NOTE: see this note about updating in the presence of OpenSSL 3.3.

Long ago Apple made it impossible for developers to use the macOS native SSL libraries. For this reason, you must install another version of OpenSSL. We recommend you use Homebrew or Macports. We prefer Homebrew because it is easier to install and update. Also, Homebrew, unlike MacPorts, does not require root installation. Homebrew merely requires administrator rights for installation.

Before installing either Homebrew or MacPorts

You should install Apple's Command Line Developer Tools, using the following command in a Terminal:

    $ xcode-select --install

This process takes a few minutes and installs the Xcode compilers. It makes installing Homebrew or MacPorts packages easier.

Also, updates to Command Line Developer Tools will be handled in the usual way on macOS, to ensure they stay up to date.

Homebrew installation:

1. Download and install Homebrew.

2. Install OpenSSL:

       $ brew install openssl

Note: from time to time, a new major version of OpenSSL is released. When 3.1.0 came out, it appeared in the updates to Homebrew quickly. New versions of OpenSSL require patches for our `:ssl` module to properly load them, so you might need to keep installed an older version of OpenSSL. On Homebrew, this is easy. The example below is to illustrate how to use an older version of OpenSSL until Allegro CL supports the newer version.

For example, to install OpenSSL 1.1 and ignore the also installed OpenSSL 3.1:

>     $ brew install openssl@1.1

> Then, to ensure that OpenSSL 1.1 is being used, do this before you execute Allegro CL's IDE:

>     $ PATH=$(brew --prefix openssl@1.1)/bin:$PATH /Applications/AllegroCL64/Contents/Resources/script

> We have revealed some information not discussed thus far: the actual program invoked on macOS for the application installed in /Applications/ is called `script`.

MacPorts installation:

1. Download and install MacPorts.

2. Install OpenSSL:

       # port install openssl

Finder issues for application deployment

When starting an application from the Finder, it is important to know that environment variables you set in your BASH or shell initialization files are not known by the Finder. The Finder environment is not the same as the shell/command line environment. For this reason, any setting you may have for `DYLD_LIBRARY_PATH` to allow Allegro CL to find OpenSSL libraries will not be known by Allegro CL, or your application, when started via the Finder.

For this reason, the Allegro CL IDE is actually a shell script which sets `DYLD_LIBRARY_PATH` so the `:ssl` module can be loaded. When you deploy on macOS, you will need to do something similar if you want users to execute your application from the Finder.

### 4.5 Installing OpenSSL on Windows

Microsoft does not maintain a version of OpenSSL for developers to use. Unfortunately, there is no easily available, free version of OpenSSL for Windows. We do, however, make builds of OpenSSL available for purposes of testing your application. We build from official sources and make no changes to them. WARNING:

> DO NOT DEPLOY YOUR APPLICATION WITH THIS VERSION of OpenSSL or use it in situations where security is important. We are not responsible for your application being exploited by security vulnerabilities which exist in this version of OpenSSL. We DO NOT make timely security-related fixes to these OpenSSL binaries and you will put your application and data at risk if you use them in situations where threats are present. If you require secure SSL communication, then you MUST obtain OpenSSL libraries from another source, possibly building them yourself.

### 4.6 Testing that Allegro CL can load the OpenSSL libraries

To test that Allegro CL can load the `:ssl` module, start a non-IDE image, either `alisp` or `mlisp`, and evaluate the `require` form below. It is important that you start a non-IDE image, otherwise you will not see any error messages, should the OpenSSL libraries fail to load:

    cl-user(1): (require :ssl)
    ; Fast loading /net/quadra/acl/11.0/bin/linux86/code/ssl.fasl
    ;   Fast loading /net/quadra/acl/11.0/bin/linux86/code/osi.fasl
    ;     Fast loading from bundle code/fileutil.fasl.
    ;     Fast loading from bundle code/acldns.fasl.
    ;     Fast loading from bundle code/iodefs.fasl.
    ;       Fast loading from bundle code/iordefs.fasl.
    ;         Fast loading from bundle code/efmacs.fasl.
    ;   Foreign loading libcrypto.so.10.
    ;   Foreign loading libssl.so.10.
    ;   Foreign loading sys:aclissl.so.
    t
    cl-user(2):

If in the above, loading the OpenSSL 1.0 libraries failed, then you should try loading the 1.1, 3.0 or 3.1 version, to see if they work:

    :reset
    ;;;; Choose one!
    (setq *aclssl-version* '(1 1))
    (setq *aclssl-version* '(3 0))
    (setq *aclssl-version* '(3 1))
    (require :ssl)

If one of the alternate versions works, then you can make the change permanent by creating a file in the Allegro CL installation directory called `ACL_OPENSSL_VERSION`. Here is a table with all possible values for the file's contents:

OpenSSL version | `*aclssl-version*` value | file contents
--- | --- | ---
1.0.x | `(1 0)` | `10`
1.1.x | `(1 1)` | `11`
3.0.x | `(3 0)` | `30`
3.1.x | `(3 1)` | `31`

## 5.0 Testing that the installation worked

The steps to test that the installation worked are to start an Integrated Development Environment (IDE) image. This tests the installation more thoroughly than starting one of the alisp or mlisp images.

Also, by default, on macOS and Linux the IDE uses your native browser. It is important to test the communication between the browser and Allegro CL on those platforms.

When the IDE starts, you will see a Debug window with a prompt similar to `cg-user(1):`. You can enter the Lisp expression

    (+ 1 2)

and press ENTER to see the response, which shoudl be `3`. In that case, your IDE is operational.

### 5.1 Starting the IDE on Windows

Test the installation by starting the IDE from the Start menu. You should see an Allegro CL 11.0 item on the All Programs submenu of the Start menu. That item has a submenu, with (among other items) submenus Modern ACL Images and ANSI ACL Images. There are also separate choices for running the IDE either in a web browser or directly on the Windows desktop. Select one of the IDE images, such as

> Start > All Programs > Allegro CL 11.0 > Modern Executables > Allegro CL 11.0 (Desktop IDE, Modern)

You should see a splash window and then a window titled Allegro Common Lisp Console. Shortly thereafter, the console window should disappear and the the IDE windows should appear, typically starting with some dialogs which you must resond to or dismiss (dismissing is okay).

You should see something like this after it starts up:

In that example, three forms have been typed to the Debug Window and their responses are shown.

If you see something similar to the above, then you are finished with the installation of Allegro CL.

### 5.2 Starting the IDE on macOS

For macOS, use the Finder to locate the version of Allegro CL you installed in the /Applications/ folder. You can double-click on it to run it and you should see something like this:

You may now either exit Allegro CL with choosing File | Exit (that is, the Exit choice from the File menu) or you may continue using Allegro CL. If you choose to exit, a dialog will appear asking if you really want to exit.

You may also close the browser tab to kill the running IDE.

### 5.3 Starting the IDE on Linux

Once Allegro CL is installed, test the installation by starting Allegro CL from a shell prompt. Assuming the Allegro directory is /usr/local/acl11.0/, start the IDE with the following command:

    $ /usr/local/acl11.0/allegro

It should give you a new tab in your default browser.

If you do not see the above picture, then there is a problem. There are two things to try:

- diagnose problems with loading OpenSSL above
- check SELinux as the source of the problem (see below)

Allegro CL may have problems starting up when SELinux is enabled.

Security-Enhanced Linux, or SELinux, is a feature that is available on many modern versions of Linux and is enabled by default on some. It affects the way shared libraries are loaded and that can prevent Allegro CL from starting up. To test this as the possible problem, as you started the allegro image above, start mlisp:

    $ /usr/local/acl11.0/mlisp
    cannot restore segment prot after reloc: Permission denied

The above error or something like segmentation fault is an indication there is a basic problem. Try the SELinux remedy first, then contact support if that fails.

## 6.0 Installing source code

In order to get source code (if your license allows it), you must return the source code license addendum included with the distribution. When that addendum is received, you will be sent a new license which allows installing source code. (Some sources are free to licensed customers and others are provided for an additional charge. If you have questions about getting source code, please contact your Account Manager.)

The sources available are:

- Lisp: The Lisp sources to basic Common Lisp and CLOS, plus many Allegro provided features (jLinker, regexp v2, etc) and Common Graphics, the IDE, and DDE on Windows. No compiler or runtime system is provided.
- AODBC: v2 Lisp sources.
- MYSQL: sources for Allegro MySQL (see mysql.html).
- ORACLE: sources for Allegro Oracle Direct interface (see oracle-interface.html).
- ORBLink: the entire sources to ORBLink (all in Lisp).

Encrypted source files are already supplied with the Allegro CL distribution. Various `src*.sh` files (on UNIX and macOS) or `src*.bat` files (on Windows) will, on UNIX, decrypt these files directly into a subdirectory named `src/` and, on Windows, generate .zip files for you to unzip. Assuming you have an appropriate updated license, here are the steps for installing the sources:

1. On Windows, open the Windows Explorer.

2. On Windows, find the Allegro directory in the explorer (it is typically `c:\Program Files\acl11.0\` but you may have chosen a different directory).

   On UNIX, cd to the Allegro directory (it is typically /usr/local/acl11.0/ but you may have chosen a different directory) in a shell.

3. On Windows, double-click on the files srclisp.bat (and also if appropriate srcaodbc.bat, srcmysql.bat, srcoracle.bat, and srcorblink.bat). Note that the CG and IDE sources are unpacked by srclisp.bat.

   On UNIX, run ./srclisp.sh (and also, if appropriate ./srcaodbc.sh, ./srcmysql.sh, ./srcoracle.sh, and ./srcorblink.sh).

4. On UNIX, you are now done. The files decrypt into the `src/` subdirectory and are now available. On Windows, you will see a .zip file for each `src*.bat` file run. Clicking on the file in the Windows explorer will often allow you to extract the contents. Or if you have Cygwin installed, it has an unzip program.

## 7.0 Updating Allegro CL and the update program

Like all complex programs, Allegro CL should be regularly updated with patches and other updates. Patches are either compiled Lisp files (though the file extension is usually not fasl) or shared library files.

The update program, update.sh on non-Windows platforms, update.exe on Windows, rebuilds Allegro CL images (dxl files). Only dxl default files (such as mlisp.dxl and allegro-ansi.dxl to name two) are rebuilt. The update process does not know how to rebuild dxl files you may have created.

Patches are downloaded by the Lisp function sys:update-allegro, by the Download Patches dialog in the Integrated Development Environment (IDE), and by the update program itself when passed the `-u` option. (The `-u` option always downloads all new patches. The other two download options allow choosing which patches to get.) update may have to be run by a user with admin privileges.

So on non-Windows machines:

    % ./update.sh -u

does everything necessary including rebuilding images (but see below for other arguments to handle proxies if necessary), as does

    % ./update.sh

after you have called sys:update-allegro and exited lisp or you have downloaded patches using the IDE's Download Patches dialog.

macOS note 1

> Both sys:update-allegro, and the Download Patches dialog may trigger a call to update so a separate call is not necessary.

macOS note 2

> Starting with version 14 (Sonoma), `update.sh` may not have permissions to modify files in the installation directory. This only happens on some installations of Sonoma (and possibly with later versions), but if it does happen you will see this error in one in the .build files after running `update.sh`:

    Operation not permitted

> If you see this error, then the fix is to modify your system as follows. In the System Settings dialog, under Privacy & Security and then App Management, turn on access (by moving the slider) for the Terminal entry. This will allow the update process to modify the installation directory. Systems without an entry for Terminal are likely not impacted by this problem.

macOS note 3

> To update the original version of Allegro CL 11.0 with the latest OpenSSL 3.3, you will need to do the following, after installing the license file:

    $ brew update
    $ brew upgrade
    $ brew install openssl@3.0
    $ cd /Applications/AllegroCL64.app/Contents/Resources
    $ env ACL_OPENSSL_VERSION=30 DYLD_LIBRARY_PATH="$(brew --prefix openssl@3.0)/lib:$DYLD_LIBRARY_PATH" ./mlisp
    (require :ssl)
    (sys:update-allegro)

If the `(require :ssl)` fails, then contact us (support@franz.com).

Windows note

> On Windows, replace `update.sh` with `update.exe` or select Start | Allegro CL | update.exe (download new update and rebuild images) (equivalent to `update.sh -r`) or get patches with sys:update-allegro or the download-patches dialog and then Start | Allegro CL | update.exe (rebuild images only) (equivalent to `update.sh`).

All that sounds and is very simple. But update.sh/update.exe in fact has two arguments to deal with proxies (`-p` and `-P`) and a bunch more arguments to allow specifying details of the rebuilt images. Here are the proxy arguments:

- `-p` - set the proxy argument to sys:update-allegro; the form of this argument is host:port. This argument may be specified without also specyfing `-P`.

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

- `--skip-ide` [update.sh only] causes the updating process to skip rebuilding the allegro images (which are the images with the IDE that start the IDE when started).

The remaining arguments specify details of the images that will be rebuilt. All have the same names as equivalent argument to the build-lisp-image, the function that creates a dxl file from scratch. They arguments are (all are optional):

    for update.sh [--newspace size], for update.exe [-n size]
    for update.sh [-o size], for update.exe [--oldspace size]
    [--lisp-heap-start addr]
    [--lisp-heap-size size]
    [--aclmalloc-heap-start addr]
    [--aclmalloc-heap-size size]

`addr` (addresses) are positive integers less than 2^62. `size` arguments must be of of the form

    size := number + suffix
    number := [0-9]+
    suffix := g | m | k

The "g", "m" and "k" in the suffix stand for "gigabytes", "megabytes" and "kilobytes" respectively, so 10000000k, 10000m and 10g all mean 10 gigabytes.

The `--newspace`, `--oldspace`, and `--*-heap-start` arguments use the same format as the `--*-heap-size` arguments above.

See build-lisp-image for more information on these arguments.

### 7.1 More information on patches

Kinds of patch files

- Files with names like p8a002.001. These are called patches and are compiled Lisp files (despite not having the extension fasl) which fixes some specific problem or provides an enhancement or, sometimes, adds a new feature). The names of these files encode information about their applicability and use. Please do not rename them. The extension indicates the patch version. Patches are often replaced (perhaps to provide additional fixes, perhaps to fix an introduced problem). When that happens, a new version (with a different extension) is provided. The patch system ensures you have a consistent set of patches. These patch files go in the update/ directory of the Allegro directory. Note the second character ("8" in the example) identifies the version of Allegro CL and is the value of `excl::*cl-patch-version-char*`.)

- Files with module names and three-digit numeric extensions (top-level.001 or streams.003). These files replace Lisp library files in the code/ subdirectory of the Allegro directory. (Most of these files are originally in the Lisp bundle file and so you may not see the originals of these files.) The system knows to look in the code/ subdirectory before looking in the bundle file. The names of these files must also not be changed.

- Miscellaneous other files.

Further important points to note

- Many patch files are numbered in the file extensions and also coded by product. They are read in order, higher numbers first. The order in which they are read is very important. Do not change the names or extensions of patch fasl files. A single patch may have various versions. This means the patch has been further updated.

- Do not use an patch for one release of Allegro CL with another release. (Patches are placed in a subdirectory of the Allegro directory. Since each new release (typically) has a different Allegro directory, you can have more than one distribution on a single machine, and patches in each one. If you do that, be sure that patches for a particular release are placed only in that release's Allegro directory.)

- Note on backups of dxl files**: the first time update.sh/exe* is run, the dxl files are copied to files with orig added -- mlisp.dxl to mlisporig.dxl, e.g. The second time, they are copied with old added -- mlisp.dxl to mlispold.dxl (so mlisporig.dxl is always the actual original mlisp.dxl). Subsequent runs replace the mlispold.dxl so if you want to preserve that, rename it before a subsequent update, to, say *oldn.dxl (for some n -- for example, mlispold.dxl to mlispold1.dxl).

- Backing out of patches: you may occasionally discover that an updated image does not work properly. (Perhaps the patch was faulty, or perhaps the fix, whatever it is, interacts incorrectly with your application.) To back out of patches, (1) rename the new dxl files, (2) copy the original dxl files (they will have "old" or "orig" appended to their filenames) to their original names, and (3) move any new fasl files out of the code/ subdirectory. You are now back to where you were before running update.sh or update.exe. Or you can reinstall and just download the patches you want.

Lists of patches can be found on the Franz Inc. web site, at https://franz.com/support/patches/log/.

The report created by dribble-bug lists all patches included in the image. It is very important that this information be included with a bug report.

### 7.2 Should you get all patches?

Whether or not you should get all available patches depends on your current tolerance for instability. Because patches are less well tested than releases, patches may occasionally introduce errors as well as fix problems.

However, even a correct patch may introduce instability: if a patch enables a feature which was previously ignored or signals an error (correctly) where none was previously signaled, your code may fail because the patch uncovered a problem which was previously unnoticed. Suppose, for example, a patch causes certain declarations to be used during compilation (without the patch they are ignored). Such a patch would not fix a bug (since ignoring declarations is permitted) but if your code happened to contain incorrect declarations, then the patch would be destabilizing. (Without the patch, the wrong declarations were ignored and so did not harm. With the patch, they are used.)

The potential impact of a patch is given in the LOG file in the update directory. Here are two entries from the 10.1 patch LOG (the current patch LOG file will be organized similarly):

    lisp patch pma049 ...
    Date posted:    Thu Jun 8 10:48:16 PDT 2023
    Patch names:    update/pma049.001,
    code/streamc.001
    Description:    Fixes a stream bug where if with-output-to-buffer is given a null optional buffer argument and non-character operations are peformed within in the body then nil is overwritten, which can cause dire consequences.
    Impact: recommended

    compiler patch pmb007 for intel only
    Date posted:    Tue Aug 21 10:41:36 PDT 2018
    Patch name: update/pmb007.001
    Description:    Enhances the compilation of bitwise and operations to generate more efficient code. All intel-based architectures benefit from this optimization.
    Impact: minor
    Other info: Recompilation is necessary to see the benefits of this patch.

Notice the Impact line. It provides an assessment of how destabilizing a patch may be. Note that in these cases, one is minor and the other patch is recommended.

If you are in a development cycle, our advice is to get all available patches for a platform (machine type) and Allegro CL version. Patches for associated products should be included as well.

But if you are preparing a delivery, we advise you to be selective, perhaps getting only the patches that deal with problems you report.

### 7.3 Updating the bundle file

The bundle file contains a collection of fasl files associated with Allegro CL modules. When a module is autoloaded or loaded by a call to require, it is typically loaded from the bundle file. (If you see the message "Fast loading from bundle...", the file is being loaded from the bundle file.) The location and name of the bundle file are returned by the function bundle-pathname.

Sometimes module fasl files have to be updated. In that case, a new file is downloaded from the Franz Inc. update repository and is placed in the code/ subdirectory of the Allegro directory. The system always checks the code directory first for a module fasl file before looking in the bundle file. That assures that the latest version of a module fasl file is loaded.

However, it is often useful to update the bundle file to include all the updated module fasl files. In Allegro CL, this update is performed automatically (when update.sh or update.exe is run).

You can create your own bundle file with the bundle program. See The bundle program in Other Programs.

Copyright (c) Franz Inc. Lafayette, CA., USA. All rights reserved.

ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0