$Revision: 5.0.2.34 $
Most of this document describes new features and changed features in Allegro CL 5.0.1 compared to 5.0 and 5.0.1/5.0 compared to earlier releases, release 4.3 and 4.3.1 on Unix platforms and release 3.0.x and 4.3.2 (a version with limited distribution) on Windows. Most of the information is, therefore, not of direct importance to new users of ACL 5.0.1.
The documentation has been entirely redone. All Allegro CL documentation is online. Start with introduction.htm which provides a documentation map. See 6.0 Common Graphics and Integrated Development Environment documentation in that document for an introduction to Common Graphics and Integrated Development Environment documentation, which is not integrated with the Allegro CL documentation.
The document index.htm is an index to the Allegro CL documentation.
A printed Read This First document is included with the release. This document is prepared after the distribution cd's are manufactured and may contain important information which is not in this document.
For installation information, please see <Allegro directory>/readme.htm.
The sections of this document are as follows. The sections dealing with the change from 3.0.x or 4.x to 5.0 are labeled (4.x-5.0) or (3.0.x-5.0) or (3/4.x-5.0). These sections have nothing new for users moving from 5.0 to 5.0.1. All unlabeled sections have information for users moving from 5.0 to 5.0.1 (although some information may also be relevant to users moving to 5.0.1 from 4.x or 3.0.x).
Allegro CL 5.0.1 compared to 5.0
AllegroStore 1.3 (All users porting from AllegroStore 1.2 read this section!)
CLIM on Allegro CL 5.0.1
Allegro OBDC: a new version for 5.0.1
Socket changes in 5.0.1
Emacs-Lisp interface changes in 5.0.1
OLE changes in 5.0.1
Miscellaneous Common Lisp changes
Changes to Allegro Common Windows (this does not affect most customers)
Changes to the Integrated Development Environment on Windows (section only refers to cgide.hlp file)
Platform-specific information (new in 5.0.1)
The executable and image files are different (4.x-5.0)
The Home Location/Allegro directory (4.x-5.0)
Running Allegro CL 5.0.1
Top-Level Initialization (3/4.x-5.0)
The Integrated Development Environment (IDE) [Windows only] (3.0.x-5.0)
Allegro Composer [UNIX only]
Information Specific to Users of International Allegro CL (Contains
new information for 5.0.1)
Profiler (3/4.x-5.0)
About the Lisp Heap (3/4.x-5.0)
Changes to malloc and free (3/4.x-5.0)
build.exe vs. lisp.exe (Windows only) (3.0.x-5.0)
lisp.exe (Windows only) (3.0.x-5.0)
New Command Line Options (3/4.x-5.0)
Building Custom Lisp Images (3/4.x-5.0)
Pathnames on Windows (3/4.x-5.0)
Some Windows-Specific information (3.0.x-5.0)
Differences Between Unix and Windows Versions of Allegro CL
(3/4.x-5.0)
Differences When Running on Windows 95/98 and NT (3.0.x-5.0)
User Control of Application Termination (Windows only) (3.0.x-5.0)
Pathnames and File Changes (3/4.x-5.0)
Merging Directory Components via merge-pathnames (3/4.x-5.0)
The Compiler (3/4.x-5.0)
Removed Symbols (3/4.x-5.0)
Conditionalizing Lisp Code
defsystem (3/4.x-5.0)
New disassemble functionality (3/4.x-5.0)
top-level stream variables (3/4.x-5.0)
:local Debugger Command (3/4.x-5.0)
excl:dumplisp (3/4.x-5.0)
The Emacs-Lisp Interface (3/4.x-5.0)
The Foreign Function Interface (3/4.x-5.0)
Foreign File Processing (3/4.x-5.0)
Changes in the Semantics of cl:load (3/4.x-5.0)
Search List Changes (3/4.x-5.0)
excl:run-shell-command (3/4.x-5.0)
The inspector
Garbage Collection (3/4.x-5.0)
Hash Tables (3/4.x-5.0)
New make-array functionality (3/4.x-5.0)
Packages (3/4.x-5.0)
Porting Applications to Allegro CL 5.0.1
Pure Lisp Libraries (formerly .lso files) (3/4.x-5.0)
Specialized Array Types (3/4.x-5.0)
The time macro (3/4.x-5.0)
Consecutive Errors (3/4.x-5.0)
Handling Printer Errors (3/4.x-5.0)
Miscellaneous (3/4.x-5.0)
Beyond bug fixes and patch integration, the base Lisp in Allegro CL 5.0.1 compared to 5.0 is not much changed. The changes in this release are mostly in add-on products: there is a completely new version of Allegro ODBC; there are significant enhancements to Common Graphics and the Integrated Development Environment (Windows only); and there are new versions of AllegroStore (the version with release 5.0.1 is 1.3; version 1.2 ran with release 5.0) and CLIM.
Note on compatibility of fasl files between 5.0 and 5.0.1 for Windows and Linux on Intel x86 platforms: in the Intel x86 versions of Allegro CL 5.0, there was a problem passing many arguments either to apply, or to a function with a stack-consed &rest argument. The bug manifests itself as a Segmentation violation during the call to the stack-resitfied function.The fix for this implemented in 5.0.1.beta2 (and in 5.0.1) causes a different compilation, and is preferred over the 5.0 compilation of dynamic-extent &rest arguments. A fasl file compiled by 5.0 will be compatible with 5.0.1, but, as in 5.0, it does not guard against large numbers of arguments being passed. Therefore, we recomend that if you have any dynamic-extent &rest arguments, you recompile your code for 5.0.1 on your x86 versions of Allegro CL. (Note that a bug in 5.0.1.beta2 compilation, fixed in 5.0.1, resulted in an all-platform fasl incompatibility between 5.0/5.0.1.beta1 and 5.0.1.beta2 but that incompatibility is not present in 5.0.1.)
Other changes are detailed in the following sections:
AllegroStore 1.3 (All users porting
from AllegroStore 1.2 read this section!)
CLIM on Allegro CL 5.0.1
Allegro OBDC: a new version for 5.0.1
Socket changes in 5.0.1
Emacs-Lisp interface changes in 5.0.1
OLE changes in 5.0.1
Miscellaneous Common Lisp changes
Known problems in 5.0.1
Changes to Allegro Common Windows (this
does not affect most customers)
Changes to the Integrated Development
Environment on Windows (section only refers to cgide.hlp file)
The version of AllegroStore with Allegro CL 5.0.1 is 1.3. (The version with ACL 5.0 was 1.2.)
There is a new printed AllegroStore 1.3 manual.
AllegroStore 1.3 database file format is not compatible with earlier AllegroStore version database files. If you wish to use databases created with earlier AllegroStore versions, you must convert them by:
Before installing AllegroStore 1.3, dump the databases using the asdump module for the AllegroStore version that created the database.
Install AllegroStore 1.3.
Restore the dumped databases using the AllegroStore 1.3 asrestore module.
You must run AllegroStore 1.3 with the ObjectStore version included on your installation CD. You can use the ObjectStore osversion utility to see your current version. The bulleted list just below shows the platform specific ObjectStore versions included on the ACL 5.0.1 installation CD.
Besides bug fixes, AllegroStore 1.3 includes:
The printed CLIM Release Notes have been changed for release 5.0.1. Also note that:
(define-gesture-name :OPEN :pointer-button (:left :double))
You can then use such a gesture in define-presentation-to-command-translator. On Windows, the double-click time is set by the operating system in the Mouse control panel. On UNIX, the double-click time is set by the internal variable tk-silica::*double-click-time*. Note that CLIM will generate a single-click event immediately before a double-click event. At the gesture level, this is equivalent to a :SELECT event followed immediately by an :OPEN event.
'("OK") or win:mb_ok '("OK" "CANCEL") win:mb_okcancel '("Yes" "No") win:mb_yesno '("Retry" "Cancel") win:mb_retrycancel '("Yes" "No" "Cancel") win:mb_yesnocancel '("Abort" "Retry" "Ignore") win:mb_abortretryignore
If you need something else, define your own application frame.
:dialog-type either :OPEN, :SAVE, or :DIRECTORY
:file-types default is '(("All Files" . "*.*"))
:multiple-select default is NIL
:warn-if-exists-p default is T (applies only to :SAVE)
- fixes to read-bitmap-file
- arrow keys work for editing input buffers
- scrolling does a better job of repainting
- fixed bug switching layouts and enforcing layout constraints
- fixed various reasons for lisp to hang
- fixes for stipples, flipping-ink, dashed lines, colors, draw-pattern*
Allegro ODBC v2 (AODBC, v2) is a second generation interface between Allegro and databases using odbc. Applications written with the version 1 interface will not work without source modification in version 2. Version 2 is documented in aodbc_v2.htm. (Version 1 is documented in a printed document. It is supported in Allegro CL 5.0.1 but, as said above, version 1 and version 2 cannot be used together.)
AODBC v2 works on most platforms including International Allegro CL on Windows.
These are the changes in version 2:
See socket.htm, which has been updated.
New functions socket:shutdown and socket-control.
More control over whether cached values are looked at or not in lookup-hostname and ipaddr-to-hostname.
New bivalent (either text or binary data can be used) in stream sockets (see make-socket). Chunking is supported with bivalent sockets (see socket-control).
The exported symbol socket:set-socket-format names a function for internal use. This function is not documented and is not intended for use.
This information from Miscellaneous CL changes may be of interest to users of the socket facility (the first is abbreviated here; the numbers are the entry numbers in the Miscellaneous CL changes section):
There are two new variables:
fi:connect-to-windows fi:common-lisp-subprocess-wait-forever
Both have doc strings and are discussed in ../../eli/readme.htm.
See ole.htm for a general description of the OLE interface in Allegro CL. Functionality is described in ole_reference.htm. Changes in 5.0.1 compared to 5.0 include:
(ole:def-ocx-class foo (foo-base :interfaces IDispatch (IViewObject2 IViewObject)) ())This says that when asked for either the IViewObject or the IViewObject2 interface, the object will supply its IViewObject2 interface.
A variant structure is a tagged union used to transmit arbitrary values between server and client using the COM IDispatch interface. We provide functions to store lisp values into and retrieve lisp values from variants.
These are now user-extendable so that the application coder can define new lisp types (structures and classes) and specify how they are to be stored into a variant.
The COM Date type, which used to be extracted as a lisp integer representing the equivalent universal-time, is now extracted as an instance of the ole:lisp-date structure, whose lisp-date-ut component is the universal-time (see 25 below). Storing a lisp-date into a variant sets the variant's type code to indicate a date is being transmitted.
The variant-handling functions now accept a wider range of array types so that arrays of values can be transmitted and received as Invoke parameters and results. More safe-arrays are handled, allowing Visual Basic to pass and receive vectors of values.
variant-value now returns a lisp-date object when the variant is of type VT_DATE. (setf variant-value) will set the variant to be a VT_DATE if the value to store is a lisp-date.
exception-info
execution-error
incoming-error
extended-incoming-error
idispatch-invoke-exception
A new function, signal-server-exception, allows server code implementing IDispatch.Invoke to return exception information to the client.
The more complicated changes are listed first.
(format t "Enter your name: ") (read)
to work, even if you forgot to do the force-output yourself.
Some users found cases where this behavior was undesirable. A stream is bidirectional and it is often necessary to control each side of the connection explicitly and independently. As a result we felt that the safest thing to do was to remove the automatic call to force-output when a read was done.
When porting your code to this version of lisp look in your code for reads from standard input and make sure that if a prompt was printed before the read, that a force-output is done after the prompt is printed. Thus, the code above should be changed to
(format t "Enter your name: ") (force-output) (read)
USER(1): (format nil "~,,' ,:B" 13) "1 101" USER(2): (format nil "~,,' ,4:B" 13) "1101" USER(3): (format nil "~,,' ,4:B" 17) "1 0001" USER(4): (format nil "~19,'0,' ,4:B" 3333) "000001101 0000 0101" USER(5): (format nil "~3,,,' ,2:R" 17) "1 22" USER(6): (format nil "~,,'|,2:D" #xFFFF) "6|55|35" USER(7):
Previously, the ordering of heaps was not enforced, and users were allowed to build images with lisp heaps above C heaps, with potential resulting data loss if the affected data types were used extensively.
In 5.0.1, an attempt to order the heaps incorrectly will result in a build failure. The locations are specified by the :c-heap-start and :lisp-heap-start arguments to build-lisp-image. See building_images.htm.
This problem was uncovered in release 5.0 but due to the globality of the complete fix, we were not able to put it into the 5.0.1 version. Instead, the debugger relies on a special mode of disassemble to determine how to interpret the values on the stack.
This means that if you are not running a runtime image, but are looking at stack locations, then you should require the disassembler, with
(require :disasm)so that such calls will be properly shown. If you are using a runtime, the fix will not work, since the disassembler cannot be used in a runtime image.
Allegro Common Windows is an X-based window system supported with earlier releases of Allegro CL. It still exists in the product (to support certain internal things and certain legacy code) though it is no longer officially supported and rarely changed. However, two changes regarding international characters have been added in 5.0.1, as reported here.
Windows only. See the Release Notes entry in the Common Graphics/IDE Winhelp file (<Allegro directory>/cg/cgide.hlp) for an extensive discussion of changes in the IDE and Common Graphics from 5.0 to 5.0.1.
To see this entry, start Allegro CL with the IDE, choose Help | Common Graphics Index, and enter Release notes in box 1 of the Index tab in the dialog that appears and click on the Display button.
This new section has been added to provide information specific to particular platforms. For 5.0.1, it is the HP-specific information that is important. Most other sections have no information at this time.
Sparc-specific information
HP-specific information
DEC-running DEC-UNIX-specific information
DEC-running NT-specific information
SGI-specific information
AIX-specific information
Linux-on-Intel-specific information
Linux-on-PowerPC-specific information
FreeBSD-specific information
Windows-specific information
See About the Lisp Heap in this document for information on the starting locations of the Lisp and C heaps in the images on the CD.
See Available Platforms for Allegro CL in readme.htm (the Installation Guide) for supported versions of the operating system.
See Available Platforms for Allegro CL in readme.htm (the Installation Guide) for supported versions of the operating system.
There are apparent problems with mmap with both HP/UX 10.20 and 11.x, which prevent Lisp from being able to use as much swap space as it should. These apparent problems should only affect users trying to run very large images (a significant fraction of a Gigabyte). Please contact Franz Inc. for further information if you are having problems running very large images on HP machines. The issues regarding swap space utilization are very complicated. Franz Inc. may refer you to HP support.
There exists a compatibility problem between HP-UX 10.20 and HP-UX 11.x. Of course, the usual downward-incompatibility exists, and binaries built on HP-UX 11.x systems will simply not run on HP-UX 10.20, as is expected. But more subtle compatibility problems exist when creating binaries on HP-UX 10.20 and expecting them to work on HP-UX 11.x. Indeed, much functionality does work, but any attempt to interact with the 11.x operating system (like loading any .sl files) will result in failure.
We have supplied lisp and libacl*.sl for both HP-UX 10.20 and for HP-UX 11.x. all .dxl files remain completely compatible, and can be run on either os version as long as the libacl*.sl is running on its native os level.
Failures:
In either case, the fix is to use the correct libacl*.sl for the version of HP-UX on which you are running. Both versions are supplied in each distribution, and both distributions should be supplied to customers if/when you distribute your application.
Features and the software-version function:
The *features* list will always have :hpux in it, but the Lisp will ensure in addition that the appropriate one of either :hpux-10 or :hpux-11 is added to *features* but always corresponding to the nativity of the libacl*.sl being run. Thus, if the warning is ignored and the libacl*.sl built on HP-UX 10.20 is run on HP-UX 11.0, the *features* list will have :hpux-10, and not :hpux-11.
The Common Lisp software-version function will return a string representing the current operating system on which the lisp is running, regardless of the nativity of the libacl*.sl. Thus a lisp running on HP-UX 11.0 will always return a string similar to "HP-UX gooey B.11.00 U 9000/777 ..." and a lisp running on a 10.20 system will return a string similar to "HP-UX heavy B.10.20 A 9000/780 ..."
See About the Lisp Heap in this document for information on the starting locations of the Lisp and C heaps in the images on the CD.
See Available Platforms for Allegro CL in readme.htm (the Installation Guide) for supported versions of the operating system.
See About the Lisp Heap in this document for information on the starting locations of the Lisp and C heaps in the images on the CD.
See Available Platforms for Allegro CL in readme.htm (the Installation Guide) for supported versions of the operating system.
Allegro CL is only supported with the Operating System Windows NT with Service Pack 4. It will not work with a service pack less that 4.
See About the Lisp Heap in this document for information on the starting locations of the Lisp and C heaps in the images on the CD.
See Available Platforms for Allegro CL in readme.htm (the Installation Guide) for supported versions of the operating system.
See About the Lisp Heap in this document for information on the starting locations of the Lisp and C heaps in the images on the CD.
See Available Platforms for Allegro CL in readme.htm (the Installation Guide) for supported versions of the operating system.
Allegro ODBC, version 2 users: Allegro ODBC now works on AIX 4.2.1 or later, with Merant (formerly Intersolve) DirectData drivers 3.11. Be sure to install the nothread version, as described in the /opt/odbc/READ.ME file.
See About the Lisp Heap in this document for information on the starting locations of the Lisp and C heaps in the images on the CD.
See Available Platforms for Allegro CL in readme.htm (the Installation Guide) for supported versions of the operating system.
See About the Lisp Heap in this document for information on the starting locations of the Lisp and C heaps in the images on the CD.
See Available Platforms for Allegro CL in readme.htm (the Installation Guide) for supported versions of the operating system.
See About the Lisp Heap in this document for information on the starting locations of the Lisp and C heaps in the images on the CD.
See Available Platforms for Allegro CL in readme.htm (the Installation Guide) for supported versions of the operating system.
See About the Lisp Heap in this document for information on the starting locations of the Lisp and C heaps in the images on the CD.
Many entries in this document are either Windows-specific or contrast Allegro CL on Windows and Allegro CL on Unix.
See Available Platforms for Allegro CL in readme.htm (the Installation Guide) for supported versions of the operating system.
See About the Lisp Heap in this document for information on the starting locations of the Lisp and C heaps in the images on the CD.
This entry reports a change from 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
This is not a new feature for users of Allegro CL 3.0.x for Windows but it is a significant change for users of Allegro CL 4.3.x on Unix platforms.
In Allegro CL 5.0.1, there is a small executable file, initially named lisp (on Unix) and lisp.exe (on Windows) and a large image file (extension dxl). The executable file cannot be created by users. However, the same executable should work (on a particular platform) with any image file. The name of the executable file is significant only because it provides the default name of the image file. (Thus, lisp looks for lisp.dxl by default.) The image file to use can be specified with the -I command-line argument. See startup.htm for information on specifying an image file.
Because the executable and image files are different, standalone images are not possible. (In Allegro CL 4.3.x and earlier on Unix, it was possible to generate a single executable image file that depended on no other file. In 5.0.1, that is not possible.)
This entry reports a change from 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
The home location (used in 4.3.x on Unix) concept has changed. The home location was (in 4.3.x) the location of files needed while Lisp was running. It was specified to Lisp by the ALLEGRO_CL_HOME environment variable. In even earlier versions, it was called the Lisp library location.
Allegro CL 5.0.1 uses the fact that the executable and image files are separate, as we describe in more detail in the next section. The location of the executable is taken to be the location of the files needed while running, corresponding to the 4.3.x home location. There is no need to specify this location to a running Lisp since the executable location is known automatically to a running program. We no longer call this location the home location (although you may see that term occasionally in the documentation.) Instead, it is called the Allegro directory. The directory in which Allegro CL was installed is also called the Allegro directory. We use the same name because they are usually the same location.
Allegro CL 3.0.x for Windows always had separate executable and image files.
Other than changing the version number to 5.0.1 and adding a reference to the International Allegro CL executable, there are no changes in this entry from the 5.0 Release Notes.
The basic model in which Lisp is constructed has changed. Previously, on Unix systems,
Lisp was a single executable and the function excl:dumplisp
created executables. Lisp has now split into several components:
All of these components reside, by default, in the same directory. This location is
called the Allegro directory, (it was called the home location in 4.3.x on Unix
and you may see that term in the documentation). The -H command line argument
can be used to specify a location other than the location of the executable as the Allegro
directory.
When run, lisp (or lispi) performs the following tasks:
lisp/lispi will print verbose messages about what it is doing
on startup if the environment variable ACL_STARTUP_DEBUG is present.
| Unix | The LD_LIBRARY_PATH environment variable (and similarly named variables
on various Unix systems) is not used when loading the ACL shared library. |
| Windows | The ACL shared library is in the Windows System directory. |
The -I argument to the executable (initially lisp on Unix and lisp.exe
on Windows) determines the location of the image file to load. If the -I
argument is not given, then the following heuristic is used to find an image file:
/usr/local/myapp that points to /usr/local/acl5/lisp
would make the default image name myapp.dxl, not lisp.dxl. If the -I argument to lisp is given, then the following heuristic
is used to find an image file to load (for the purposes of this example, the name of the -I
companion argument is imagefile):
imagefile if it does not already have a
type.imagefile contains a directory component, then check to make sure imagefile
exists. Use it if it does, signal an error if it does not.imagefile exists in the current directory, use it.imagefile exists in the Allegro directory, use it.Example: if (on Unix) lisp is copied to myapp or (on
Windows) lisp.exe is copied to myapp.exe, and you then
create a myapp.dxl in the same directory as the executable, then myapp is equivalent to myapp -I myapp.
If Lisp was built with a .pll file, then the same search rules above for finding a supplied image file apply to finding the .pll file. On Windows, the Windows system directory is also searched (system on Windows 95/98 and system32 on Windows NT).
On Windows 95/98/NT, you can also run Allegro CL from the Start | Programs | Allegro CL 5.0.1 menu.
This entry reports a change from 3.0.x on Windows or 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
The first one of .clinit.cl or clinit.cl in the commonly-searched directories (the user's home directory and the current directory on Unix, C:\ and the Allegro directory on Windows) is now loaded. See the variable excl:*init-file-names*.
The IDE and the Common Graphics window system are only available on Windows platforms.
See <Allegro directory>\cg\cgide.hlp for extensive documentation of Common Graphics and the IDE. See the Release notes entry in that file for extensive discussion of changes in 5.0.1 compared to 5.0. Only a few items are kept here.
Limitation |
Description |
||
| Single-Process Limitations | There is a one-to-one mapping between Allegro CL processes
and operating system threads. Common Graphics in Allegro CL 5.0.1 must run within a single
Allegro CL process. This is forced by the mapping plus the limitation of Microsoft Windows
that events for a window can only be received on the thread that creates the window, as
well as the limitations of Common Graphics itself. When the Integrated Development
Environment (IDE) starts, a special process named
In processes other than the |
||
| Finding the boundaries of the toplevel form: | All editor commands
that need to find the boundaries of a toplevel form (e.g. beginning-of-definition
or incremental-evaluation-command) find the start of a form simply by
searching back from the cursor position for the closest open parenthesis in the first
column.The alternative would be to parse the entire file. This actually is what the Lisp reader does when the compiler or loader reads the file, but using this as an alternative would cause unacceptable delays for large files, and would fail completely if the entire file were not syntactically correct. This is often the case when a file is actively being edited. So this is an unacceptable solution. Solution: searching backwards to the closest open parenthesis in the first column is simple, fast, and almost always suffices.
|
||
| Loss of keyboard shortcuts: | When using the File | Build Project Distribution menu item, at the end of the process of building the Project distribution a dialog box will pop up. If this dialog box gets buried (you do not dismiss it by clicking on OK), then the keyboard shortcuts in the IDE will stop working. They will start functioning again when you dismiss the dialog box. |
Allegro Composer is only available on UNIX platforms.
There is no mouseline window (even though the documentation mentions one). Instead, Allegro Composer must be run as a subprocess of Emacs. Menus in emacs provide the functionality previously provided by the mouseline window.
The following symbols have been removed and can no longer be used:
composer:*composer-display-specification*
composer:*use-notifier-windows-for-errors*
composer:*show-lisp-status*
There have been extensive changes in release 5.0.1. See iacl.htm#2.2 New in Release 5.0.1. Also:
For streams and foreign functions, the external-format used by iacl on Windows is different than that used by iacl on Unix. On Unix, we use EUC externally and Process-Code internally. On Windows, we use Windows MultiByte externally and Unicode internally.
This means, in particular, EUC source/text/data files specifying non-ascii data cannot be read with Windows iacl, and Windows MultiByte source/text/data specifying non-ascii data files cannot be read with Unix iacl.
We are also not supporting reading back files written using 16-bit string data that are written across the Windows/Unix boundary.
Any lisp strings passed to foreign functions or any lisp strings being stored in (or copied into) foreign structures used by foreign functions need to be converted (with either string-to-native, string-to-mb, or with-native-string). This is necessary even if only ascii characters are ever used in lisp strings passed to foreign functions.
The reason for this restriction even for ascii-only strings is that iacl lisp internally uses a flat wide-character representation where each character is 16-bits wide. Thus, looked at from an 8-bit byte point of view, every other 8-bit byte is zero.
Foreign functions expecting to receive 'char *' arguments assume that the only 8-bit byte holding all zeros (ie, the NULL character) occurs only after the last character of the string.
Thus, in iacl, if an unconverted lisp string of all ascii characters is passed to a foreign function expecting a 'char *' argument, the foreign function will (depending on machine byte-ordering) behave as if the string is null-terminated either before or after the first character.
Also, note the following difference with the non-International version of Allegro CL:
The vector version of run-shell-command is not supported, and the non-vector version is limited to 8192 (wide) characters.
See Also
iacl.htm
This entry reports a change from 3.0.x on Windows or 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
On Windows, the profiler works best when the scheduler is running, as in that mode it is able to take a sample nearly every millisecond. When the scheduler is not running, the profiler can, at best, take a sample every 13 milliseconds.
The profiler has also been enhanced to separate closure calls.
prof:start-profiler and prof:with-profiling have a new keyword
called :interpret-closures. See the discussion of the :interpreted-closures
keyword in the prof:start-profiler
page.
A function specialization called prof:closure has been added. This is
valid whenever an analyzed profile exists and identifies the closures which the profiler
has seen. The specialization is (prof:closure n) where n is
a small integer enumerating the closures in the profile. This allows the user to grab the
closure object and to do a prof:disassemble-profile
on it without having to know what symbol holds as its fdefinition (sometimes
this is very hard).
When flat profiles and call-graphs are reported, closures are identified by (prof:closure
n), followed by the printed representation of the closure
object itself.
See Also
Profiling.htm
This section contains information intended for advanced users with very large applications. Most users can skip this section until they need a heap larger than the default.
The address into which the heap is loaded is architecture-dependent. It is potentially important for you to know this, in case you use the operating system primitives for memory mapping or want to move the heap from the default location in memory. The values in the table are in hexadecimal format. 0x400 is 1K. 0x100000 is 1M. 0x40000000 is 1G.
| Architecture/OS | Lisp Heap Start | C Heap Start |
| DEC Unix (Dec/Compaq Alpha) | 0x30000000 | 0x54000000 |
| HPUX (on HP machines) | 0x10000000 | 0x64000000 |
| Linux (Intel-based machines) | 0x20000000 | 0x64000000 |
| MkLinux/LinuxPPC (PowerPC) | 0x30000000 | 0x64000000 |
| IRIX (SGI Mips machines) | 0x30000000 | 0x64000000 |
| AIX (RS6000 and PowerPC) | 0x30000000 | 0x64000000 |
| Sparc/Solaris(Sun machines) | 0x04000000 | 0x54000000 |
| Windows 95/98 & NT (Intel-based machines) | 0x20000000 | 0x54000000 |
| Windows NT (DEC/Compaq Alpha) | 0x30000000 | 0x54000000 |
| FreeBSD (Intel-based machine) | 0x10000000 | 0x64000000 |
See building_images.htm for information on excl:build-lisp-image's :lisp-heap-start, :lisp-heap-size, :c-heap-start and :c-heap-size keyword arguments for information on specifying the heap sizes and starting locations. The Lisp heap start must be below the C heap start.
This entry reports a change from 3.0.x on Windows or 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
Allegro CL has always used some calls to malloc to allocate static blocks of data, and has provided an implementation of malloc and free (and other functions) that is both compatible with the system version of malloc and satisfies Allegro CL's requirements. The implementation was called pdmalloc.c and was freely available in source form on the FTP site. The malloc space was always preserved using excl:dumplisp, and the programmer could always count on any block allocated in this space to be still at the same location after the dumped lisp was restarted. Under this system, all calls to malloc were shadowed and were in reality calls to this pd version of malloc.
The malloc situation changed starting in Allegro CL 5.0. The malloc and free functions (along with other functions associated with malloc) are no longer shadowed by our own implementation, but are taken again from the system libraries. Instead, we introduce aclmalloc and aclfree, and provide interfaces both in C and in Lisp to these functions. aclmalloc allows three possible allocation strategies:
Warning: The syntax for the above changes are in place, but the functionality for items #2 and #3 are not yet implemented. Thus, the C portion of the heap must stay in one place as of ACL 5.0/5.0.1.
In 5.0/5.0.1, a decision will need to be made as to whether the data to be allocated should live across excl:dumplisp boundaries; if the data must live across excl:dumplisp boundaries then aclmalloc should be used, otherwise malloc should be used.
| Rule of thumb for using aclmalloc vs. malloc | If the data is "owned" more by Lisp functionality
than C functionality, it should be allocated via aclmalloc,
and if the data is owned more by C functionality than by Lisp then it is better to use malloc instead. As always, there will be exceptions and non-obvious cases requiring more judgement than this rule can give. |
This entry reports a change from 3.0.x on Windows to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
build.exe is a WIN32 console application, whereas lisp.exe is a WIN32 Windows application. If you want to run a command-line oriented version of ACL, use build.exe, but otherwise you should use lisp.exe. lisp.exe is intended to be used for development and delivery of applications on Windows.
There are issues with multiprocessing and build.exe. build.exe sometimes cannot tell if input is available or if a process that is waiting on input should wake up. For this reason, we recommend you do not use build.exe with multiprocessing applications.
International versions have buildi.exe and lispi.exe, the International versions of these applications. They work just as build.exe and lisp.exe do for the Domestic versions.
| Note: | build.exe does not accept the arguments that begin with +. |
This entry reports a change from 3.0.x on Windows to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
Under normal circumstances, when lisp.exe is run it displays a window containing a read-eval-print loop, which we call the Console window. International versions of Allegro CL have lispi.exe, which is the International version of lisp.exe.
In addition to the Console Window, the Windows Explorer tray icon can be used to interact with the Lisp. Double left-clicking on this icon in the tray makes the Console visible (if necessary it will un-minimize and/or un-hide it, and it will raise it above other windows). A right click on the icon brings up a menu. There is a bug in that you have to click on the menu (or another Lisp-controlled window) to dismiss the menu. As a result there is a do-nothing menu item called Dismiss menu which you can use until we fix this bug.
See the next section, New Command Line Options, for information on newly available arguments to lisp.exe.
Quoting of arguments via the Windows Explorer is somewhat confusing. To load a file (foo.cl
is used for example) from a short cut or from the Start | Run... menu, you could do
this:
lisp.exe -I dcl -e "(load "foo.cl")"
This entry reports a change from 3.0.x on Windows or 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
-C file |
Evaluates (compile-file file) |
-d file |
Causes dribbling to file. |
-H directory |
Overrides the default home location calculation
using directory |
-kill |
Evaluates(exit 0) |
-L file |
Evaluates (load file) |
-Q |
Allows quiet startup (without pll, dll and dxl messages) |
-W |
Evaluates (setq *break-on-warnings* t) |
See Also
3.0 Command line arguments in startup.htm
This entry reports a change from 3.0.x on Windows or 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
In Allegro CL 5.0.1, the Lisp function excl:build-lisp-image is used to create custom images. (It is the rough equivalent of the config program in release 4.3.x on Unix.) Note that except for defaults for certain arguments, the newly created image inherits nothing from the running image. If foo is a function defined in the running image, foo will not be defined in the new image unless code to define it was loaded during the build process.
The document building_images.htm is the best place to learn about build-lisp-image. The description page for build-lisp-image (follow that link) is less complete (we are trying to avoid having two locations for the same information).
This entry reports a change from 3.0.x on Windows or 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
See 5.0 Parsing Windows pathnames in pathnames.htm for more information.
This entry reports a change from 3.0.x on Windows to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
On Windows, when the Console window is the active window, typing the BREAK key will send an interrupt to Lisp. Previously the F12 key was the interrupt key. It is still the case that if Lisp is in a loop where it isn't checking for interrupts, it is not possible to break Lisp out of this loop using the BREAK key.
If the Lisp scheduler is running and the variable mp::*message-peek-mode* is set to 1, then Lisp will not process Windows messages, and instead the scheduler will set mp::*pending-windows-message* to t and then look for a Lisp process that is run-able. This means that a user can create their own Lisp lightweight process to process Windows messages.
The advantage of this is that it gets around the problem that errors cannot be debugged on the scheduler stack group (which is where Windows messages are normally processed). This is an experimental feature, subject to change. This variable is initially 0.
sys:set-splash-bitmap (Windows only).
sys:stack-cushion and sys:set-stack-cushion.
See also multiprocessing.htm for information on changes affecting Windows multiprocessing users.
There is now a low-level OLE interface for Windows only.
There is no new information in this entry for 5.0.1.
| Foreign Code | The only foreign code that can be loaded into Lisp is that in Dynamic Link Libraries (DLLs). Object files themselves cannot be loaded into Lisp. See the section on the Foreign Function Interface for more information. |
| Home Directory | The .clinit.cl or clinit.cl files are loaded from the "home directory and the current directory". Those terms are meaningful on Unix but not really on Windows. On Windows, the home directory is hardwired to C:\. The current directory is the location of the executable (typically, the Allegro directory). |
| Pathnames | See Pathnames on Windows. |
| run-shell-command differences | See excl:run-shell-command. |
| sbrk() | There is no sbrk()
in the Microsoft C runtime library. The WIN32 API function VirtualAlloc()
can be used to allocate large blocks of memory. This method might be preferred over using malloc(),
depending on how malloc() is implemented on Windows (which is unknown to
us). When using dumplisp, understand that memory allocated with VirtualAlloc() and malloc() is not saved in the resulting image file. excl::malloc does not call the C runtime library version of malloc(). It calls another version (internal to ACL), and this memory is saved and restored by dumplisp. |
| End of line convention in
text files: carriage return, line feed, and newline issues. |
In a file containing text, Windows
separates lines by two characters: a carriage return (ascii #x13) and a linefeed
(ascii #x10). A Common Lisp program wants to use one character (which it calls #\newline) to separate lines. This incompatibility is solved by specifying a mode for every Common Lisp stream that reads or writes a file. The mode of a stream can be specified by the :mode argument to cl:open. If there is no :mode argument then the :element-type argument determines the mode in this way: if the element type is character (which is the default) then :text mode is used, otherwise :binary mode is used. Specifying the :text mode means that when Common Lisp writes a #\newline, the carriage return and linefeed characters are written to the file. :text mode also insures that when a carriage return and linefeed are read from a file, the single character #\newline is returned by read-char. Files opened in :binary mode don't get this translation. One further feature of :text mode is that a CTRL-Z character is an end of file marker; you can't read past a CTRL-Z in :text mode. This is required by our use of the built-in support for text mode in Windows. If we move the text mode processing into Lisp, then we will likely remove this behavior. |
| SIGIO | The SIGIO facility is not implemented on Windows. This facility uses Unix features not present in Windows. There are no current plans to implement it in a future release of ACL on Windows. (See set-sigio-hander.) |
There is no new information in this entry for 5.0.1.
| Our goal is to make the NT and 95/98 versions of Allegro CL exactly the same from your point of view. This section details the features we have been unable to make identical on both systems. | ||||
| Mapping the Lisp Heap: | ||||
| NT: | On NT, the heap is mapped (from the .dxl file) into memory (with the WIN32 memory mapping primitives). This allows for much faster startup, especially when starting up multiple times using the same image. | |||
| 95/98: | On 95/98, mapping the heap does not work because the memory mapping primitives do not work there. This is a "feature" of Windows. | |||
Notes: |
.pll
file mapping works identically on Windows and NT. See the section on pure Lisp libraries for more information on .pll files. See About the Lisp Heap if you need to change the default settings. |
|||
| Profiling: | ||||
| In both versions of Windows we sample using a real-time clock. | ||||
| NT: | A clock interrupt results in a sample if there's a thread that has used the processor most of the time since the last tick. | |||
| 95/98: | We can't
tell how much time the processor uses, so we take a sample if the current thread owner
isn't in a sleep or a wait.
This really only affects non-mp mode on 95/98, and means that you won't get samples inside a foreign subroutine call for which Lisp released the heap. We have no way of knowing whether such a foreign function is burning cycles or sitting in a long-term wait. Thus we can't reliably produce information from such samples. |
|||
This entry reports a change from 3.0.x on Windows to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
See excl:console-close.
This entry reports a change from 3.0.x on Windows or 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
The following items have undergone change or are new for this release:
| New behavior: | |
| equal | equal now compares the host and device fields of a pathname with equalp. |
| excl:*open-rename-function* (new defaults) | |
| *default-pathname-defaults* | *default-pathname-defaults*
now starts as the value of (excl:current-directory). *default-pathname-defaults* in ACL 4.3 was #p""; the pre-4.3 behavior has been reinstated. |
| logical-pathname-translations | logical-pathname-translations has a new :autoload keyword (default value t) which causes it to look at the sys:hosts.cl file, if that file hasn't already been loaded. Normally, load-logical-pathname-translations must be explicitly called to load the translations for a particular host. |
| merge-pathnames | The first argument of merge-pathnames
is now translated if it is a logical pathname--before any merging is done--when that
pathname is a relative logical pathname and default (the second argument) is a physical
absolute pathname. |
| (namestring (make-pathname :directory '(:absolute :wild-inferiors))) |
This previously printed as a relative pathname on Unix and Windows. |
| New Functions: | |
| excl:copy-directory excl:delete-directory excl:delete-directory-and-files excl:directory-size excl:map-over-directory excl:make-directory excl:pathname-as-directory excl:pathname-as-file excl:pathname-sans-file system:copy-file system:make-temp-file-name system:temporary-directory |
|
| Un-exported Symbols: | |
| system:mkdir system:rmdir |
See excl:make-directory and excl:delete-directory. |
This entry reports a change from 3.0.x on Windows or 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
| The first argument of merge-pathnames
is now translated if it is a logical pathname--before any merging is done--when that
pathname is a relative logical pathname and default (the second argument) is a physical
absolute pathname. There is a problem with the behavior of the merge-pathnames on the directory component of pathnames, when first argument is a relative logical namestring/pathname and the second argument is absolute and either:
Examples of this are: (merge-pathnames "src:;sys;make.cl" "/burn/layer/") (merge-pathnames "src:;sys;make.cl" "bar:;burn;layer;") |
|||
| ANSI CL rules for merging | Pathname merging treats a relative
directory specially. If (pathname-directory pathname) is a
list whose car is :relative, and (pathname-directory
default-pathname) is a list, then the merged directory is the value of: (append (pathname-directory default-pathname) (cdr ;remove :relative from the front (pathname-directory pathname))) except that if the resulting list contains a string or :wild immediately followed by :back, both of them are removed. This removal of redundant :back keywords is repeated as many times as possible. If (pathname-directory default-pathname) is not a list or (pathname-directory pathname) is not a list whose car is :relative, the merged directory is: (or (pathname-directory pathname) (pathname-directory default-pathname)) |
||
In the non-logical
world, merging relative and absolute directories is straightforward and very clear; what
you see in the directory namestring of the relative pathname is what is appended to the
end of the absolute directory.
|
|||
| However, with a
relative logical pathname there is often a hidden directory component that you cannot see
unless you perform the translation. For example, in the pathname #p"src:;sys;make.cl",
there is no way (except by examining the translation itself) to know what the directory
component of the translated pathname will be. So, according to the directory merging rules
above (merge-pathnames "src:;sys;make.cl"
"/burn/layer/") would evaluate to #p"src:burn;layer;sys;make.cl",
which probably will not make any sense. The solution to this problem is stated at the beginning of this discussion: having the first argument translated in a particular way under specific conditions before any merging is done. The ANSI merging rules above indirectly state that an absolute directory component as the first argument to merge-pathnames is untouched. Is #p"foo:"bar"baz.cl" a relative pathname? It is relative with respect to the directory contained in the logical translation, which is most likely different than the physical translation, often an absolute pathname.
|
|||
| The ANSI specification
does not address the issues raised here, so we have decided on an intentional
non-conformance and to translate the logical pathname under the specific conditions listed
at the beginning of this discussion above. Consequently, merging ".." with absolute pathnames is changed. For example, (merge-pathnames ".." "/") returns #p"/". |
|||
See Also
pathnames.htm
This entry reports a change from 3.0.x on Windows or 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
In certain cases apply is now compiled more efficiently, to remove consing. Consider the following code:
(defun foo (x &rest y) (apply fcn 1 x 2 y))
The &rest argument is used to supply a variable length
argument list to apply. This case is now
compiled in such a way that
apply is not actually used, but an index to the n'th
argument to foo is compiled instead.&rest argument is considered dead as if declared ignored.In this optimized case, the code works exactly as it did when the &rest
argument was consed, but without the consing.
Conditions that will cause this optimization to not be used:
&rest argument is declared special,&rest argument is a closed-over variable,&rest argument is set, or&rest argument is used anywhere except as the last
argument to apply.| Optimization
hint: the following call to apply will not be optimized: (defun wrap-it (flag &rest x &key &allow-other-keys) |
If non-consed operation is desired, then the following modification will allow the optimization:
(defun wrap-it (flag &rest x &key &allow-other-keys)
(if flag
(apply 'wrapped flag :new-key 10 x)
(apply 'wrapped flag x)))
| Symbol or Feature | Change |
| comp:verify-car-cdr-switch | This variable, ignored in release 4.3, has been reinstated
because although alignment traps are caught on almost all architectures, the operating
systems will not allow for recognition of misalignment, so list-ness of the object being
accessed via car/cdr cannot be verified by hardware. Those
versions of Allegro CL in which |
| *compile-print* | Initial value is nil instead of t. |
| Fasl files (.fasl) | Now identifiable in their first bytes, which are textual lines. This includes architecture, dates, and compilation settings at the time of the fasl write. The textual information about these global settings is accurate as long as speed, safety, and other settings do not change during the file compilation. |
| comp:list-call-direct-possibilities | This is a new function, callable with no arguments. It
returns a list of lists of descriptions which should aid in call-direct
compilation. Each list represents a kind of argument or return value, and starts with a string describing what the rest of the list describes. For those descriptions which start "bad ..." the types listed will force the compilation of a call to the function to be compiled out-of-line. The other lists describe those argument/return types required in order to compile the call as a direct-call. These types are Lisp types or specifiers; they can either be explicitly specified as the Lisp type or implied by the C type of the argument or the return value (see the description of ff:def-foreign-call and the general description of foreign functions in foreign_functions.htm). |
The value of the variable comp:trust-dynamic-extent-declarations-switch (>on by default) is a compiler switch that controls the trusting of dynamic-extent declarations. So the following declaration is trusted by default:
(declare (dynamic-extent ...))
The value of trust-dynamic-extent-declarations-switch can be set to nil
if you suspect you have a bad dynamic-extent declaration. This would be the
case if you use a variable declared dynamic-extent past the dynamic extent of
the point of creation of the variable on the stack.
For example, in this definition:
(defun foo (&rest bar) (declare (dynamic-extent bar)) bar)
bar is erroneously declared dynamic-extent. This could be the
cause of difficult-to-diagnose Lisp and garbage collection errors.
This entry reports a change from 3.0.x on Windows or 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
| Symbol | Notes |
| *optimize-intern-for-space* | This symbol worked only on symbol names, and was not adding anything in the way of
performance, so it has been removed. Especially in a Lisp with an lso (.pll)
file, it slowed things down to a crawl. If you have used *optimize-intern-for-space* in your code, you should now use a .pll ("pure") file to arrange for sharing of duplicate strings. It's not as slow as the original switch was, and gives a better result. The pure library now works for all strings, not just symbol names. |
| excl:*stream-package* | The stream package has been merged into the excl package (and stream is now
a nickname of excl). The value of excl:*excl-package* is the excl package. |
| rmdir and mkdir | rmdir and mkdir are renamed to delete-directory and make-directory. rmdir and mkdir are no longer exported from the excl package; do not use them. |
This entry reports a change from 3.0.x on Windows or 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
See the 5.3 Reader macros and cl:*features* in implementation.htm for features (on cl:*features*) on which Lisp code can be conditionalized.
This entry reports a change from 3.0.x on Windows or 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
There are three new long-form module options supported in the defsystem utility. See defsystem.htm for the definition of each of the new options.
| New Options: |
| :concatenate-system-ignore :force-dependent-recompile :force-load |
This entry reports a change from 3.0.x on Windows or 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
See implementation.htm for changes to the disassemble function.
This entry reports a change from 3.0.x on Windows or 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
| *trace-output* and *error-output* are bound on a per-listener basis (like *standard-input*, *standard-output*, *debug-io*, and *query-io* always have been) to *terminal-io* for that listener. | |
| A listener process-related change: | Because these specials are bound in listener processes, they were removed from the bound per process variables list. Specifically, all of these variables are no longer required top-level bindings. |
This entry reports a change from 3.0.x on Windows or 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
The :local debugger command now accepts :x as a flag and will print integer arguments in hexadecimal.
This entry reports a change from 3.0.x on Windows or 4.x on Unix to 5.0 (and thus 5.0.1). There is no new information for 5.0.1.
The :checkpoint argument to excl:dumplisp is ignored. A warning is issued if it is used. The default value for the dumplisp keyword name is "savedcl.dxl" (from "savedcl").
A new keyword to excl:dumplisp, :suppress-allegro-cl-banner, can be used to suppress the Franz Inc. copyright and startup banner.
When this keyword argument is given to excl:dumplisp and it has a non-nil
value, then a warning will be issued.
See Also
Application Delivery in Allegro CL
Repeating the information from Emacs-Lisp interface changes in 5.0.1 above:
There are two new variables:
fi:connect-to-windows fi:common-lisp-subprocess-wait-forever
Both have doc strings and are discussed in ../../eli/readme.htm.