$Revision: 1.1.2.16 $
This chapter has the following sections:
1.1 Version and History
1.2 Compatibility
1.3 Documentation
1.4 Editor
1.5 Configuration
1.6 Reporting bugs and asking questions
This is chapter 1 of the User Guide for the Allegro CL 5.0.1 Integrated Development Environment (IDE). The IDE is only supported on Windows 95/98 and Windows NT machines. Note that this product does not run under Windows 3.1 or Windows NT versions prior to 4.0.
Th remaining chapters of the IDE User Guide are:
Chapter 2: The Allegro CL Development Environment (IDE)
Chapter 3: An example
Chapter 4: Projects
Chapter 5: Components
Chapter 6: Designing a user interface
Chapter 7: Menus
Chapter 8: Events
Prior to the 5.0 release, there were two distinct versions of Allegro CL: the UNIX version (recent releases on UNIX platforms are 4.3 and 4.3.1 and on Windows NT, 4.3.2) and the PC version (recent release 3.0.2). These versions came from different original sources and shared little low-level code.
Allegro CL 5.0 was the first unified version of Allegro CL for both UNIX and Windows platforms. The underlying Common Lisp implementation comes from the UNIX Lisp (versions 4.3, 4.3.1, and 4.3.2) while the windowing system and development tools come from the Windows version (release 3.0.2).
Combining two separate implementations is a complicated process. It is not possible to preserve all features of both systems because some features are incompatible. Although Common Lisp code (with a few exceptions) that worked in one predecessor version should work the same in 5.0.1 (since Common Lisp code is portable), certain details, such as fixnum size and the number of supported floating-point types, are changed if you are porting from Allegro CL 3.0.2 for Windows. (For example, fixnums are 30 bits and single- and double-floats are distinct types, both the same as earlier UNIX versions but different from earlier PC versions which had 16 bit fixnums and one floating-point type.)
For extensions to Common Lisp, such as the foreign function interface, the changes are more radical, with the UNIX version generally being used rather than the PC version. The main exception is the windowing system. Common Graphics, the windowing system of Allegro CL 3.0.2, is the windowing system of the 5.0.1 product, at least on Windows platforms. (Using Common Graphics on UNIX platforms depends on the availability of the Windows API on UNIX platforms.)
The Integrated Development Environment is a windowized tool for developing user interfaces to applications. Common Graphics is the window system used by the IDE. Most symbols associated with the IDE and Common Graphics are in the common-graphics package.
Coming from Allegro CL 4.3.x on UNIX platforms or (version 4.3.2) Windows NT:
In general, all code that does not deal with windows will port to version 5.0.1 without significant problem. The foreign function interface is wholly new but the 4.3.x foreign function interface is supported with a backward-compatibility package. There were two windowing systems in 4.3.x, CLIM and Common Windows, the latter having been maintained only for backward compatibility for some time. Neither is supported in Allegro CL 5.0.1 on Windows with the IDE.
Coming from Allegro CL 3.0.2 for Windows:
Because the base Common Lisp implementation in Allegro CL 5.0.1 comes from earlier UNIX versions rather than the earlier PC version, there are many changes, many of them incompatible. Further, even though the Common Graphics windowing system is supported, it has been significantly modified, with many functions being renamed and some incompatibilities introduced. There is a compatibility document that describes what must be done to Allegro CL 3.0.2 programs to get them to work in 5.0.1.
Allegro CL 5.0.1, Common Graphics, and the IDE are documented with help files (Windows Help for Common Graphics and the IDE, HTML for the Allegro CL implementation of Common Lisp). The documentation includes (<Allegro directory> is the directory where Allegro CL is installed):
The Allegro CL Integrated Development Environment User Guide. This is the document you are now reading. It describes the tools for developing the user interface to an application.
The Allegro CL Documentation. All Allegro CL documentation (except for some add-on products such as CLIM, Allegro Composer, and version 1 of the Allegro ODBC) is online, in a collection of HTML files. The base directory for the Allegro CL online documentation is <Allegro directory>/doc/cl/ (where <Allegro directory> is the directory where Allegro CL was installed). The file introduction.htm in that directory provides a guide to the Allegro CL documentation. Clicking Help | HTML Documents when running the IDE displays introduction.htm.
The Release Notes. <Allegro directory>/doc/cl/release_notes.htm (the Release Notes for Common Graphics and the IDE are in the IDE Help file, cg\cgide.hlp)
The Installation Guide. <Allegro directory>/readme.htm
Compatibility. Two Windows Help files, <Allegro directory>/doc/cg/compat.hlp and <Allegro directory>/doc/cg/porting.hlp, provide information useful for people upgrading or porting from Allegro CL 3.0.x for Windows. Note that Allegro CL 3.0.x for Windows was mostly a CLtL-1 version of Common Lisp (that is, it implemented Common Lisp as described in Guy Steele's Common Lisp: the Language, 1st edition, with some CLtL-2 and ANSI additions. Allegro CL 5.0.1 is an ANSI standard Lisp. While most CLtL-1 code runs without problem in an ANSI Common Lisp, there are some changes which have significant programmatic effect.
See the description (in the Allegro CL documentation) of excl:*cltl1-in-package-compatibility-p* and comp:*cltl1-compile-file-toplevel-compatibility-p* for information. Note that the first time you compile an Allegro CL 3.0.x file, you may get many warnings because of issues related to these variables.
The ANSI Common Lisp specification. (The starting page of that document is in <Allegro directory>/ansicl/ansicl.htm.) This provides the primary documentation for Common Lisp functionality. In this release, there are no links between Allegro CL documentation and the ANSI spec (either way).
Extensions and implementation details of standard Common Lisp functionality are described in various Allegro CL documents, particularly implementation.htm. The index in index.htm has links to this documentation (look up, e.g. open and disassemble -- the links go where the index link will go).
Online Help. This online Windows Help file, <Allegro directory>/cg/cgide.hlp, describes the functionality of functions, macros, variables, etc. in Common Graphics and the Integrated Development Environment. The Common Graphics Tree of Knowledge, displayed with Help | Common Graphics Tree, is an outline control with links to Common Graphics and IDE documentation both in the Help file and in the HTML documents.
Doodler tutorial. This is a completely worked out example of using the IDE to build an application (which draws curves based on user specifications). The project is described and the steps of the tutorial are detailed in <Allegro directory>/tutorial/doodler.hlp.
Examples. There are many examples of using Common Graphics. See the Examples tab of the Navigator dialog, displayed by Help | Examples. (Help | Navigator displays the Navigator dialog as well).
Essays on certain Common Graphics and IDE features. These are HTML documents:
Using Forms to Create an Application in <Allegro Directory>/doc/cg/form/form.htm.
Menus in <Allegro Directory>/doc/cg/menu/menu.htm.
Pixmaps in <Allegro Directory>/doc/cg/pixmaps/pixmap.htm.
Working with Projects in <Allegro Directory>/doc/cg/project/project.htm.
System Internals in <Allegro Directory>/doc/cg/system/system.htm.
You can run the Allegro CL 5.0.1 IDE as a subprocess of GNU Emacs. Just start Allegro CL within Emacs in the usual way. Make sure you specify allegro.dxl as the image file (rather than lisp.dxl, which is Allegro CL without the IDE). Note that all window actions (creation and particularly events) must take place within the IDE thread/process. Emacs runs in a different thread/process. Thus all code which is window or event related can be edited in Emacs but must be evaluated in the IDE thread (perhaps by writing a file and loading the file using the File | Load... command or the equivalent toolbar button (looks like a pickup truck).
Files will be opened in Emacs (rather than the IDE Editor Workbook) if the Open Files in GNU Emacs option on the Editor Options pane (show just below) is selected (and Emacs is running and linked to Lisp).
Editing (other than using Emacs) should be in a text-edit windows or panes, such as the Debug window and the Editor Workbook (which has tabs for different editor buffers). The editing mode for text-edit windows can be Host, Emacs, or Brief. The mode is set in the Editor tab of the Options dialog (displayed with Tools | Options). Here is that dialog. The Host mode is chosen:
The :EMACS mode uses a subset of standard Emacs keybindings. Note that these may alter menu shortcuts, to prevent them from conflicting with the Emacs keybindings.
Your preferences about window arrangement, choice of fonts, editor mode, and so on are stored in a file in the Allegro folder (where Allegro CL was installed) called prefs.cl. This file is updated when you exit Allegro CL (unless the menu command Tools | Save Options on Exit is toggled off), incorporating changes made using the Options dialog (displayed by Tools | Options) and when you make direct changes to the configuration using the Inspector as described just below.
Most details of the system are stored as the value of the variable *system*. The information about the configuration choices are in the data structure returned by
(configuration *system*)Many configuration properties correspond to global variables. Accessors to such properties are named, generally, by the global variable name associated with the property without the *'s. Thus
(print-base (configuration *system*))returns the value of *print-base* and setting it with setf changes the value in the configuration and the current value of the variable. Other accessors are not associated with a specific global. Their names are usually intuitive. Thus, the editor mode is accessed (and set with setf) by
(editor-mode (configuration *system*))You can examine the configuration by clicking Tools | Inspect System Data | Configuration Options. The Inspector shows all configuration properties and their values. Values can be changed directly in the Inspector, by clicking on the value and typing or clicking on the extended editor button to the right of the value and entering the new value in the dialog that appears (different dialogs appear for different types of values). Here is the Inspector showing some configuration options:
Send problem reports and technical questions of any type by email to bugs@franz.com. Our mailing address is Franz Inc., Suite 275, 1995 University Ave., Berkeley CA 94704 USA; and our telephone number (in the USA) is +510-548-3600.
Please state explicitly in your message that you have Allegro CL 5.0.1 with the IDE and say what version of Windows you are using (95, 98, or NT). Use excl:dribble-bug to write a file showing a transcript of a failure. dribble-bug writes information about the release and its features as well as recording a transcript, so use it in preference to dribble. You can produce an automatic dribble along with a backtrace by doing File | Save while a backtrace pane is selected (the backtrace pane is displayed when you click on the Debug button of a Restarts dialog after an error). The saved file is suitable for including in a bug report. See the topic About submitting a bug report from a break in the IDE in the Help file.
See also <Allegro directory>/doc/cl/introduction.htm#5.0 Reporting bugs.
Copyright (C) 1998-1999, Franz Inc., Berkeley, CA. All Rights Reserved.