ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version

# Allegro Composer

This document contains the following sections:

1.0 Introduction
2.0 Customizing and executing Allegro Composer
2.1 Setting up your system for Allegro Composer
2.2 Building an image that contains Allegro Composer
2.3 Starting and stopping Allegro Composer
2.3.1 Starting Allegro Composer
2.3.2 Starting Allegro Composer from your .clinit.cl file
2.3.3 After Allegro Composer starts up
2.3.4 Stopping Allegro Composer
2.4 Errors while running Allegro Composer
2.5 Composer variables
2.6 Definitions of terms associated with Allegro Composer
3.0 Overview of Composer functionality
3.1 The big picture
3.2 The ACL/Composer menu
3.2.1 The Inspect menu item
3.2.2 The CLOS submenu
3.2.3 The Xref submenu
3.2.4 The Profiler submenu
3.2.5 The Options menu item
3.2.6 The Other submenu
3.2.7 The Help submenu
3.2.8 The Exit Composer/Common Windows menu item
3.3 Gestures and presentations
3.3.1 Changing gesture bindings
3.4 Menus in Allegro Composer
3.5 Graphs
3.5.1 Scrolling graphs
3.5.2 The graph overview window
3.5.3 The Window menu on a graph window menu bar
3.5.4 The History menu on a graph window menu bar
3.5.5 The :menu gesture over a graph node
3.5.6 The :secondary-menu gesture over a graph node
3.5.7 The Find Node(s) from Name menu choice
4.0 The debugger in Allegro Composer
4.1 Displaying a stack backtrace in a window
4.1.1 The Window menu on a Debugger window menu bar
4.1.2 The Debugger menu on a Debugger window menu bar
4.1.3 Menus over frames 1: the :secondary-menu gesture menu
4.1.4 Menus over frames 2: the :menu gesture menu
4.1.5 Menus over objects
4.1.6 The :menu gesture over a local
5.0 The window-based inspector
5.1 Inspector windows and their menus
5.1.1 The Window menu on an Inspector window
5.1.2 The Inspect As menu on an Inspector window
5.1.3 The History menu on an Inspector window
5.1.4 Menus over labels and values in an Inspector window
6.0 Composer Browsers
6.1 CLOS class browsers
6.2 Cross reference browsers
6.3 The defsystem browser
6.4 The Process Browser
6.4.1 The :menu gesture over a process
7.0 The window interface to the runtime analyzer
7.1 Runtime analyzer profile graphs
Appendix A. Configuring X windows for Allegro Composer
Appendix A.1. Name and class of Composer tools
Appendix A.2. Resources of tools
Appendix A.3. Specifying resource values in .Xdefaults
Appendix A.4. Reinitializing resources
Appendix B. Problems starting Allegro Composer
Appendix B.1. Error: there is no process named Connect to Emacs daemon
Appendix B.2. Error: package Composer not found
Appendix B.3. Error: Unknown hostname:

## 1.0 Introduction

Allegro Composer is no longer supported. The version of the software it depends on (CLX), which works with Allegro Composer is also out of date. Users on Windows, Linux, and MacIntosh machines are urged to use the IDE (see cgide.htm) instead.

Allegro Composer is an interactive, window-based development environment to be used with Allegro CL on Unix platforms. It contains a debugger, an inspector, a runtime analyzer, various browsers (for processes, CLOS objects, etc.), a connection to the Cross Reference facility, and more. You must run Allegro CL as a subprocess of Emacs. The Composer windows are X windows.

## 2.0 Customizing and executing Allegro Composer

Subsections of this section describe how to set up your system for Allegro Composer, how to start Allegro Composer, and how to customize Allegro Composer.

## 2.1 Setting up your system for Allegro Composer

You need to have the X window system running on the machine where you intend to display Composer Windows. This machine is typically (but not necessarily) the same machine that displays the Emacs window (it need not be the machine where Emacs is running, of course).

It is possible for a window manager to interfere with the mouse events associated with Composer windows. However, the mouse actions associated with gestures can be configured at run time (as described in Section 3.3.1 Changing gesture bindings) and the Emacs menus use mouse buttons without associated keys. Assuming that the left and right mouse buttons are not used alone by your window manager, you should not have a problem with the interface between Allegro Composer and your window manager. In general, that means that your window manager should not be configured to use button1 (what we call the left mouse button) or button3 (what we call the right mouse button) without also using keyboard keys.

See Appendix A Configuring X windows for Allegro Composer for more information on setting up your system. We have the information in an appendix because users generally do not have difficulty once things are set up correctly.

## 2.2 Building an image that contains Allegro Composer

There are no Allegro CL images that contain Allegro Composer. If you want to build such an image, start Allegro CL and (as the first action) load the file buildcomposer.cl. This will create an image named composer.dxl or composer8.dxl (as you are running a 16-bit character or an 8-bit character image). It also copies the executable (mlisp or mlisp8 to composer or composer8). You can then use that image, and Allegro Composer will be loaded.

## 2.3 Starting and stopping Allegro Composer

If Allegro Composer is not included in the running image (see Section 2.2 Building an image that contains Allegro Composer, you must load composer.fasl (which in turn may load additional files). Do this by evaluating:

    (require :composer)

You may invoke Allegro Composer whenever you are running Allegro CL as a subprocess of Emacs (using the emacs-lisp interface) and X is available to you. For information on starting Allegro CL as a subprocess of Emacs, see Running Lisp as a subprocess of Emacs in startup.htm; see also eli.htm. (Note that Emacs, Lisp, and X may all be running on different machines communicating over the network. Of course, X must be displaying on the machine where you are sitting.)

The functions used to start and stop Allegro Composer, along with other composer-related functions and variables, are in the `composer` package. The nickname of this package is `wt`.

You may wish to use this package (so that you do not have to package-qualify exported symbols). Do so by evaluating `(use-package :composer)`.

## 2.3.1 Starting Allegro Composer

You can start Allegro Composer by choosing the Start Composer menu item on the Emacs ACL/Composer menu.

You can also start Allegro Composer with the function start-composer. Arguments to this function allow you to specify the X host, display, and screen, and allow you to load an init file. If the host, display, and screen default to the value of the DISPLAY environment variable, it is often not necessary to specify them. (See the description page for a complete description.)

If the read-init-file is true, the system tries to read the Composer init file, whose name is the value of `*composer-init-filename*`. The initial value of that variable is "~/.comp2init.cl". The Start Composer menu command on the Emacs ACL/Composer menu calls start-composer with read-init-file true. If an error is encountered reading the Composer init file, reading stops and the error message is printed but no error is signaled (just as with the .clinit.cl file). If you wish to debug the error, load the file after Composer has started.

You interact with Allegro Composer using Emacs menus, particularly the ACL/Composer menu. Once Allegro Composer is started, the items in that menu will be available.

The function composer-initialized-p returns true after Composer starts.

## 2.3.2 Starting Allegro Composer from your .clinit.cl file

You may wish to start Allegro Composer automatically whenever Allegro CL is started, perhaps by putting the form `(composer:start-composer)` (perhaps with additional arguments) in your .clinit.cl file. That works but has the annoying side effect of printing several lines of bogus warnings.

You can avoid these bogus warnings by having code in your .clinit.cl which modifies the value of `*restart-init-function*` in such a way that Allegro Composer is started when that variable is processed (which is at the end of the startup process). Do this by putting the following form in your .clinit.cl file:

    (defun start-composer-from-clinit-file ()
      (let ((initial-restart-init-function *restart-init-function*))
        (cond (initial-restart-init-function
                (setf *restart-init-function*
                      #'(lambda ()
                          (composer:start-composer)
                          (setf *restart-init-function*
                                initial-restart-init-function)
                          (funcall initial-restart-init-function))))
               (t
                 (setf *restart-init-function*
                       #'(lambda ()
                           (composer:start-composer)
                           (setf *restart-init-function* nil)))))))

    (start-composer-from-clinit-file)

Note that the value of `*restart-init-function*` is restored after Allegro Composer is started.

## 2.3.3 After Allegro Composer starts up

Allegro Composer works using Emacs menus. (Most Allegro Composer functionality is unavailable if you are not running Allegro CL as a subprocess of Emacs using the Emacs-Lisp interface. See eli.htm for general information on the Emacs-Lisp interface.)

There are a number of Emacs menus associated with Allegro CL that are submenus of the ACL menu, including File, Edit, Debug, and Composer. When Allegro Composer is started, the ACL/Composer Menu items become available. (More precisely, before Allegro Composer is started, only the Start Composer item is available. After Allegro Composer is started, that item becomes unavailable, and the remaining items become available.

Allegro Composer needs the X window system and Emacs to be running to work. If there is a problem starting up, an error message should be printed. Please see Appendix B Problems starting Allegro Composer for discussion of possible errors.

## 2.3.4 Stopping Allegro Composer

You stop Allegro Composer by choosing the Exit Composer/Common Windows item from the Emacs ACL/Composer menu or by calling stop-composer function. As the menu choice indicates, Common Windows is stopped along with Composer when the menu item is chosen. stop-composer has an argument that allows Common Windows to continue running after Composer is stopped.

Common Windows is an old windowing system no longer supported by Allegro CL but still used by Allegro Composer. It will not be further discussed in this manual.

## 2.4 Errors while running Allegro Composer

The most common errors caused by user action when running Allegro Composer are the usual Lisp errors you (may) see from time to time: typing mistakes that lead to unbound variables or undefined functions, leaving a quote out when it is needed or supplying one when it is not, or supplying a value of the wrong type.

Because almost all Composer input is via the Emacs minibuffer, such errors are caught by the Emacs-Lisp interface, which prints a message to the Emacs minibuffer explaining what was done wrong, but does not cause a Lisp error to be signaled. For example, choosing the Composer/Clos/Inspect Class menu item prompts you in the minibuffer for the name of a class to inspect. Entering `'stream` results in this message being displayed in the minibuffer:

    Cannot inspect 'stream: (quote stream) is not a legal class name

Since the value typed to the minibuffer is not (in this case) evaluated, there should be no quote.

Another problem you may run into is choosing a Composer command (from the ACL/Composer menu) that requires use of the Emacs minibuffer while the minibuffer is already in use. For example, enter the Emacs command to read a file into a new buffer (C-X C-F is the typical key combination for doing that) and, without specifying a file, choose the Inspect menu command from the ACL/Composer menu. (That command prompts for something to inspect in the minibuffer.) A message is printed to the minibuffer that an attempt was made to use the minibuffer while it was in use, but again no Lisp error is signaled.

Composer errors do occur, usually because of an improper argument to a Composer function. Resetting out of these errors (using :reset) is the usual course.

Other problems. The following is a list (by no means exhaustive) of things that may go wrong and what may be done about them.

- Composer does not respond to mouse actions. If this happens, the likely cause is another X client (perhaps the Window manager) is catching and using the mouse clicks. For example, a left click may be caught by the Window manager to expose a window and thus be ignored when trying to display a menu on a Composer Window.

  However, if mouse clicks worked and then suddenly stop working, that is likely not the cause. More likely is something has grabbed the mouse and that something must be cleared before Composer can respond.

  It may be that Allegro CL is garbage collecting or that the system is very loaded, in which case waiting will typically solve the problem.

  Do not stack mouse events (that is do something new before the previous thing has completed). This can confuse the event handler.

- Composer windows look odd. If Composer windows have stray bits in them or are incorrect in some other way, try choosing Refresh (or one of its relatives, like Update) from the Window menu on the menubar of most Composer windows. Moving the window or iconifying and then expanding it (both of which actions cause the system to redraw the window) may also help. If those do not work, try flushing and recreating the window.

## 2.5 Composer variables

These variables either store information about Allegro Composer or are set to useful values during execution.

- `*c*`: this variable provides a temporary location for values. Some menus include the command Set *C* to object, providing a useful way to get a handle on displayed values.
- `*composer-init-filename*`: the name (and typically the path) of the initialization file read when Composer starts.
- `*composer-title-and-version*`: a string providing version information.

## 2.6 Definitions of terms associated with Allegro Composer

- browser: a window that displays information about a collection of items. For example, the Process Browser (displayed with Composer/Other/Process Browser) displays information about processes within Lisp.
- click: To click a mouse button means to depress and immediately release it. A click is distinguished from a press, where a button is pressed and held down for some period.
- Composer window: Any window associated with Allegro Composer.
- debugger window: a window showing the backtrace of the current execution state of a process. This window displays what is printed by :zoom.
- Emacs: Emacs is the name of the editor that must be used in conjunction with Allegro Composer.
- Emacs buffer: Emacs organizes information into buffers. One or more is displayed in an Emacs window. A special buffer is the minibuffer, described below.
- graph window: these windows display graphs which show relations between Lisp objects. Examples are runtime analyzer profile graph windows and Calls To and Calls From (displayed by Composer/Xref/Show calls to and Composer/Xref/Show calls from).
- Inspection: An Inspector window can inspect multiple objects and can inspect the same object in different ways. At any point in time, the window displays an inspection of a single object in a single way. Menus on the Inspector window menubar allow you to change the display to show a different inspection of the same object or the inspection of a different object.
- Inspector window: an Inspector window shows the slots and values associated with a Lisp object. Many Inspector windows can be on the screen at one time and each window can contain inspections of several objects (although only one is visible at any one time).
- left button: a standard mouse has three buttons, typically numbered 1, 2, and 3. Mice are either right- or left-handed. On a right-handed mouse (the most common variety), button 1 is the left button. In this manual, we assume a right-handed mouse, so left button means button 1. This button is used to display menus on Composer window menubars.
- menu: a menu is a small window containing a number of items (or choices), usually identified by one or a few words denoting some action. Menus are typically displayed when a mouse button is pressed or clicked. If you click the mouse button, the menu will stay on the screen until you click again (either over an item or away from the menu). If you press the mouse button, the menu stays displayed until the button is released, and releasing over an item chooses that item.
- middle button: a standard mouse has three buttons, typically numbered 1, 2, and 3. Mice are either right- or left-handed but on either type of three button mouse, the middle button is button 2.
- minibuffer: a small buffer in the Emacs window, always visible, where Emacs commands are input and system messages are displayed. Composer uses the minibuffer for input and also for messages. When prompted by Composer for input, you can cancel the request by entering the keyboard quit chord (typically C-g).
- Overview window: a graph displayed in a graph window is typically much larger than the window itself, so only a portion can be visible at one time. An Overview window is associated with a graph window and displays the entire layout of the graph in small format (too small for the contents of nodes to be visible). Clicking a mouse button inside an Overview window causes the associated graph to be scrolled to the location corresponding to the mouse cursor location.
- press: when we say press (or depress) a mouse button, we mean you should depress the button and hold it down (following other instructions before releasing it). See also click.
- Process browser: displayed when you choose Composer/Other/Process Browser, this window displays information about processes in Lisp.
- right button: a standard mouse has three buttons, typically numbered 1, 2, and 3. Mice are either right- or left-handed. On a right-handed mouse (the most common variety), button 3 is the right button. In this manual, we assume a right-handed mouse, so right button means button 3. When the right button is clicked over an object in a Composer window, a menu of object-specific choices is typically displayed.
- submenu: some menu items have additional choices associated with them, so clicking over them (or, if the mouse button is pressed, moving the cursor over them) displays a submenu of these additional choices. Many of the items on the ACL/Composer menu have submenus.

## 3.0 Overview of Composer functionality

## 3.1 The big picture

After Allegro Composer is initialized, most input comes from the mouse and the Emacs minibuffer and information is displayed either in Composer windows or, occasionally in the minibuffer. You need not, in general, evaluate forms or issue commands in Lisp to get Allegro Composer to do things. An exception is the windowized debugger, which can only be displayed with the top-level command :wdebug, and other utilities (such as the windowized inspector) have functional or top-level command equivalents.

A big advantage of using the mouse, and an advantage that Allegro Composer depends upon, is the ability to denote things by pointing to them. If you are able to point to something, you need not know how to denote it in another way. Allegro Composer is set up to display things which it can act upon. Almost all Composer windows list things (processes, values, frames, local variables, etc.) which you can act on in some way.

We have tried to make Allegro Composer easy to use. The quickest way to figure out what the various tools and utilities do is to try them. If you start playing with the system in order to find out its capabilities, keep the following things in mind:

- You must run Lisp as a subprocess of Emacs using the Emacs-lisp interface (therefore you must start Lisp with fi:common-lisp.
- Many Composer commands require that you input information in the Emacs minibuffer. Keep your eye on the minibuffer while you run Composer, particularly if you expect Composer to do something but nothing seems to be happening.
- Choosing Help from the Composer/Help menu causes useful introductory information to be printed in an Emacs buffer.

## 3.2 The ACL/Composer menu

The Composer menu is a submenu of the ACL MENU on the Emacs menu bar. Before Allegro Composer is started, only the Start Composer item is available (active). The various items that display submenus are available in the sense that mousing on them displays the submenus, but all items that are commands (rather than displaying submenus) are unavailable.

Once Allegro Composer is started (by choosing the Start Composer menu item or calling start-composer), the menu changes so that the Start Composer item is unavailable and the remaining items are available. At that point the menu looks like this:

We describe each item (and its associated submenu if it has one) in the next series of subsections.

- Section 3.2.1 The Inspect menu item
- Section 3.2.2 The CLOS submenu
- Section 3.2.3 The Xref submenu
- Section 3.2.4 The Profiler submenu
- Section 3.2.5 The Options menu item
- Section 3.2.6 The Other submenu
- Section 3.2.7 The Help submenu
- Section 3.2.8 The Exit Composer/Common Windows menu item

## 3.2.1 The Inspect menu item

Choosing this item prompts the user in the Emacs minibuffer for an object to inspect. That object is then inspected in an Inspector window. What is entered in the minibuffer is evaluated. Thus, if you want to inspect, say, the symbol `mysymbol`, enter `'mysymbol` in the minibuffer.

If you decide that you do not want to enter an object to be inspected, enter the keyboard quit Emacs command (typically C-g).

The system tries to determine a suitable default value as the object to inspect based on the Emacs cursor location.

If there is a problem inspecting the object entered in the minibuffer (for example, if you enter `mysymbol` without a quote and `mysymbol` does not have a value), a message explaining the problem is displayed in the minibuffer but no error is signaled.

A new Inspector window is created each time the Inspect menu item, is chosen.

The top-level command :winspect and the function winspect also display Inspector windows.

See Section 5.1 Inspector windows and their menus for a description of Inspector windows.

## 3.2.2 The CLOS submenu

The CLOS submenu (displayed when the Composer menu is visible and the mouse cursor is over CLOS) contains items that display Inspector windows for inspection of classes and generic functions and graph windows displaying class hierarchies. When you choose an item from the submenu, you are prompted in the Emacs minibuffer for a class or generic function name (which is not evaluated, so to enter, for example, the class `stream`, enter `stream` with no quote).

The system tries to determine a suitable default value based on the Emacs cursor location.

If you decide after choosing a menu item to cancel the command, enter the keyboard quit Emacs command (typically C-g).

If there is a problem with what you enter in the minibuffer (for example, what you enter does not name a class or generic function, or you enter `'stream` -- with a quote -- rather than `stream`), a message explaining the problem is displayed in the minibuffer but no error is signaled.

The submenu items are:

- Inspect class: prompts in the minibuffer for the name of a class (what is entered in the minibuffer is not evaluated) and displays an Inspector window for that class. See Section 5.1 Inspector windows and their menus for information on inspector windows.
- Inspect generic function: prompts in the minibuffer for the name of a generic function (what is entered in the minibuffer is not evaluated) and displays an Inspector window for that generic function. See Section 5.1 Inspector windows and their menus for information on inspector windows.
- Show class subclasses: prompts in the minibuffer for the name of a class (what is entered in the minibuffer is not evaluated) and displays a graph window showing the class hierarchy of subclasses of the entered class. See Section 6.1 CLOS class browsers and also Section 3.5 Graphs.
- Show class superclasses: prompts in the minibuffer for the name of a class (what is entered in the minibuffer is not evaluated) and displays a graph window showing the class hierarchy of superclasses of the entered class. See Section 6.1 CLOS class browsers and also Section 3.5 Graphs.

## 3.2.3 The Xref submenu

The Xref submenu (displayed when the Composer menu is visible and the mouse cursor is over Xref) contains items that display graph windows showing calls to and/or from a function and an additional item that discards Cross Reference data. Choosing an item that displays a graph causes you to be prompted in the minibuffer for a function name (which is not evaluated, so to enter, for example, the function `my-function`, enter `my-function` with no quote).

The system tries to determine a suitable default value based on the Emacs cursor location.

If you decide after choosing a menu item to cancel the command, enter the keyboard quit Emacs command (typically C-g).

If there is a problem with what you enter in the minibuffer (for example, what you enter does not name a function, or you enter `'my-function` -- with a quote -- rather than `my-function`), a message explaining the problem is displayed in the minibuffer but no error is signaled.

See cross-reference.htm for details of the Allegro CL cross-reference utility. The graphs displayed by this submenu are based on the database of cross-reference information collected by the cross-reference utility. See also Section 6.2 Cross reference browsers.

The submenu items are:

- Show calls to: prompts in the minibuffer for the name of a function (what is entered in the minibuffer is not evaluated) and displays a graph window showing calls to that function (using information in the Cross Reference database). See Section 3.5 Graphs for information on graph windows.
- Show calls from: prompts in the minibuffer for the name of a function (what is entered in the minibuffer is not evaluated) and displays a graph window showing calls from that function (using information in the Cross Reference database). See Section 3.5 Graphs for information on graph windows.
- Show calls to and from: prompts in the minibuffer for the name of a function (what is entered in the minibuffer is not evaluated) and displays a graph window showing calls to and from that function (using information in the Cross Reference database). See Section 3.5 Graphs for information on graph windows.
- Discard xref info: choosing this item causes discard-all-xref-info to be called and all cross-reference information stored in the system to be flushed.

## 3.2.4 The Profiler submenu

The Profiler submenu (displayed when the Composer menu is visible and the mouse cursor is over Profiler) contains items that allow starting and stopping of the Allegro CL time and the space runtime analyzers, displaying runtime analysis data, and displaying a dialog of runtime analyzer options. See runtime-analyzer.htm for information on the Allegro CL runtime analyzer.

The submenu items are:

- Start time profiler: choosing this item will start a time runtime analysis. A message in the minibuffer will indicate when initialization has completed and data collection has started. Choosing this item will cause any undisplayed data (from previous analysis runs) to be lost.
- Start space profiler: choosing this item will start a space analysis. A message in the minibuffer will indicate when initialization has completed and data collection has started. Choosing this item will cause any undisplayed data (from previous analysis runs) to be lost.
- Stop profiler: choosing this item will stop collection of data. (Note that data collection is stopped, not suspended.) You choose this item when you have completed running the code which you want analyzed.
- Display time: choosing this item will display time analysis information in a profile window. See Section 7.1 Runtime analyzer profile graphs for information on windows that display data.
- Display space: choosing this item will display space analysis information in a profile window. See Section 7.1 Runtime analyzer profile graphs for information on windows that display data.
- Options: displays the profile options dialog, which is described in Section 7.0 The window interface to the runtime analyzer.

## 3.2.5 The Options menu item

Choosing this item displays the Composer Options Dialog pictured above. This dialog allows setting of certain options related to Allegro Composer. All options can be set Yes or No and clicking on an option value toggles it to the other value (thus clicking on Yes toggles it to No). A change is effected as soon as a value is toggled. Choosing [Undo Changes] (at the bottom) restores all values to what they were when the dialog was first displayed.

The Window menu on the menubar has three choices:

- Quit: close the window. Equivalent to clicking on [Dismiss] at the bottom of the Window or clicking the Close button. Since all changes to values are effected immediately, closing the Window does not affect the values of the options.
- Resize to fit: resize the dialog so it is just large enough to display all data.
- Refresh: update the display to reflect the current values of the options. (If you change the value of a variable associated with an option away from the Options dialog, the change will not be reflected unless you choose this item. Thus, the `Record Xref Info` option is associated with the variable `*record-xref-info*`. If you change the value of that variable in the Emacs Listener Buffer, the change will be seen only when you choose this item.)

The options are:

- `Record Source File Info`: Yes or No as the variable `*record-source-file-info*` is true or `nil`.
- `Load Source File Info`: Yes or No as the variable `*load-source-file-info*` is true or `nil`.
- `Record Xref Info`: Yes or No as the variable `*record-xref-info*` is true or `nil`.
- `Load Xref Info`: Yes or No as the variable `*load-xref-info*` is true or `nil`.
- `In-Package Compatibility`: Yes or No as the variable `*cltl1-in-package-compatibility-p*` is true or `nil`.
- `Xref Scans Entire Heap`: this option is not associated with an exported variable, but rather an internal one. If the value is Yes, cross reference graphs (displayed by the Xref submenu) include information gathered by scanning code-vectors in the heap as well as the cross reference database. Compare the display when `Xref/Show Calls To` is chosen for the function `cons` when this option is Yes (a very big display) and No (typically little or nothing is displayed).
- `Redefinition Warnings`: Yes or No as the variable `*redefinition-warnings*` is true or `nil`. Note that changing from No to Yes changes the value of the variable from `nil` to `t`. However, the initial value is typically a list indicating what kind of redefinition warnings are desired.

At the bottom of the dialog are the commands [Undo Changes] (which restores values to what they were when the dialog was first displayed) and [Dismiss] (which closes the dialog).

## 3.2.6 The Other submenu

The Other submenu (displayed when the Composer menu is visible and the mouse cursor is over Other) contains two items that display Composer Browsers and one item that reinitializes X resources.

The items are:

- Process Browser: display the Process Browser window, described in Section 6.4 The Process Browser.
- System Browser: display the Defsystem Browser window, described in Section 6.3 The defsystem browser.
- Reinitialize Composer Resources: this item causes Lisp to see changes to X resources made after Allegro Composer was started. See Appendix A.4 Reinitializing resources for more details. Resources are discussed in Appendix A Configuring X windows for Allegro Composer.

## 3.2.7 The Help submenu

The Help submenu (displayed when the Composer menu is visible and the mouse cursor is over Help) contains two items that display useful information about Allegro Composer.

The items are:

- Help: display useful information about using Allegro Composer in a `*Composer Help*` Emacs buffer.
- Current pointer gesture bindings: display, in a `*Composer Gesture Bindings*` Emacs buffer, the current list of logical gestures (the association of mouse keys or mouse key/shift key combinations) and actions, as described further just below.

Here is a sample display when Current pointer gesture bindings is chosen:

    The current logical gesture definitions are:
     :select            on Left.
     :inspect           on Control-Left.
     :describe          on Shift-Left.
     :edit              on Middle.
     :menu              on Right.
     :secondary-menu    on Shift-Right.

See Section 3.3 Gestures and presentations for a discussion of gestures.

## 3.2.8 The Exit Composer/Common Windows menu item

Choosing this item exits Allegro Composer, just as calling stop-composer does. It also exits Common Windows, a windowing system no longer supported but still used by Allegro Composer. (If you wish to stop Allegro Composer while leaving Common Windows running, you can do so using stop-composer.) After this item is chosen, all items that are associated with actual commands (rather than just display submenus) on the Composer menu become unavailable except Start Composer.

## 3.3 Gestures and presentations

The way a Lisp object is displayed in a Composer window and the effect of mouse actions on that object are controlled by the presentation system and the defined gestures. A presentation controls how an object is printed or displayed, and which commands can be applied to it (e.g. with the mouse). Generally, users of Allegro Composer need not concern themselves with presentations since they simply see the object (more precisely, a printed representation of the object, in a window.

Gestures, also called logical gestures, are more important. Because we cannot specify how you should configure your window manager (detailing which mouse button/keyboard combinations should do what where), we refer to mouse actions on presentations by abstract gestures identified by keywords: `:menu`, `:inspect`, etc. (a complete list is given below). There is a mapping from mouse/keyboard actions to gestures and you can define the mapping which best suits your purposes.

The following gestures are defined in Allegro Composer:

- `:select`
- `:inspect`
- `:describe`
- `:edit`
- `:menu`
- `:secondary-menu`

The current mapping from mouse/keyboard actions to gestures is printed in a `*Composer Gesture bindings*` Emacs buffer when you choose `Current Pointer Gesture Bindings` from the Help submenu of the Composer menu. Typical contents are:

    The current logical gesture definitions are:
     :select            on Left.
     :inspect           on Control-Left.
     :describe          on Shift-Left.
     :edit              on Middle.
     :menu              on Right.
     :secondary-menu    on Shift-Right.

In the description, Left, Middle, and Right refer to mouse buttons (we assume a right handed mouse) and Control and Shift refer to keyboard keys. Thus to perform the `:inspect` gesture, hold the Control key down and click the left mouse button. The other keys typically used (but not in the list above) are Meta, Hyper, and Super. Double clicks are supported and are called Double-[button], e.g. Double-Left.

Using the mouse, you can perform a variety of actions on a mouse-sensitive object printed or drawn in a Composer window. Each action is a command. A large number of commands are defined by Allegro Composer. Some commands (such as Inspect and Describe) are applicable to any Lisp object, while others are applicable only to objects of some limited types or which otherwise satisfy some criterion. For instance, Process Kill is applicable to any process but Process Unarrest is applicable only to processes which are arrested. Allegro Composer dynamically computes the commands applicable to the object under the mouse. Indeed, having at least one applicable command is what makes the presentation of an object mouse sensitive in the first place.

A command will be available only if it is appropriate to the object and is included in the command set of a particular tool. However, with some exceptions, any generally useful command will be available with any tool. For example, the various specialized commands which operate on processes are available not only in the Process Browser but on a process object displayed, say, in an Inspector window.

Nonetheless, for purposes of organization, we usually document commands on specialized objects in the section on specialized tools concerning them. Thus, commands on processes are documented in Section 6.4 The Process Browser.

When the mouse is over a mouse-sensitive object in a Composer window, the `:menu` gesture will pop up a menu of applicable commands. Clicking a command will execute it.

Frequently commands will also be available on particular gestures. The gestures are identified on the menu (in abbreviated form). Here is the menu displayed by the `:menu` (usually clicking right) on an object in an Inspector window:

The first three choices have associated gestures -- `Describe` (Sh-L = Shift-Left), `Inspect` (L = Left), `Inspect in New Window` (C-L = Control-Left).

## 3.3.1 Changing gesture bindings

You can change a gesture binding with the following macro (named by the unexported symbol `excl::define-gesture-name`).

### excl::define-gesture-binding

### Macro

#### Package: excl

Arguments: gesture-name &key button shifts action unique

The macro returns gesture-name after (re)defining the button and keyboard combination associated with gesture-name. The value of gesture-name must be a keyword naming a gesture (i.e. `:inspect`, `:menu`, etc.)

The value of the button must be one of `:left`, `:middle`, `:right`, `:double-left`, `:double-middle`, or `:double-right`. The `double-` means a double click is required. A value must be supplied for this argument. There is no default.

The value of the shifts must be either `nil` (the default); or one of the symbols `:shift`, `:control`, `:meta`, `:hyper`, or `:super`; or a list of one or more of those symbols (note: the argument is not evaluated). All specified keys must be pressed when the specified button is clicked in order to perform the gesture.

If the unique argument is true (the default), any previous gesture binding for gesture-name is removed. Specifying `nil` permits defining a logical gesture with multiple bindings.

For example:

    ;; When the following is evaluated, the :inspect gesture will
    ;; be performed by clicking the middle button while holding
    ;; down the Control key:
    (excl::define-gesture-name :inspect :button :middle
                               :shifts :control)

## 3.4 Menus in Allegro Composer

Menus are an important part of Allegro Composer, typically providing a list of options suitable to the location and situation of the mouse and the state of Lisp and Composer.

Some menus are on menu bars (the Composer menu is on the Emacs menu and most composer windows have menu bars). Other are pop-up menus displayed by the `:menu` gesture (and, in graph windows, the `:secondary-menu` gesture).

Menu bar menus: most Composer windows have menu bars. Clicking over a menu label displays the menu. Most windows have a Window menu, with choices Quit (close the window), Resize to Fit (resize the window to exactly fit the displayed data, if possible), and Refresh (update the data displayed in the window).

Menus over objects. Many objects in Composer windows are mouse sensitive, meaning some command can be performed on the object with a gesture. Whenever an object in a Composer window is mouse-sensitive, the `:menu` gesture (usually clicking the Right mouse button) is defined and displays a menu. In graph windows, the `:secondary-menu` gesture is usually defined as well.

It is important to be sure what is selected and mouse-sensitive. Allegro Composer indicates this by boxing. Note that objects and parts of objects may be boxed. For example, the following shows the display of the list `(2 a 22)` in an Inspector window. In the upper image, the whole list is selected (boxed) while in the lower image, just the symbol `a` (the second element of the list) is selected.

The choices in menus over objects are usually self-explanatory. Here are some choices you will often see:

- Inspect: choosing this will cause the selected item to be inspected in an Inspector window.
- Describe: choosing this will cause a description (as printed by describe) of the selected item to be printed in an Emacs buffer.
- Set *C* to object: choosing this will cause the value of the variable `*c*` to be set to the selected object.
- Edit Definition: choosing this will open an Emacs buffer to the source of the selected object, if such source exists and is known to Composer.

Background menus. many Composer windows have background menus, displayed by the `:menu` gesture over the background of a window (i.e. in a window but away from mouse-sensitive objects). This menu is typically the same as the Window menu on the menu bar.

Menus over graph nodes and debugger items. Graph nodes are special in the following way. They often display Lisp objects which can be acted upon like Lisp objects displayed in other windows. However, you may be interested in the node as a node of a graph rather than as a container of what it displays. Because it is complicated to distinguish between pointing to a node and pointing to its contents, separate gestures are provided for each purpose. The `:menu` gesture performed at the node of a graph displays a menu appropriate to its contents while the `:secondary-menu` gesture displays a menu with commands applicable to the node itself. The same issue affects frames in a Debugger window, and both the `:menu` and the `:secondary-menu` gestures are applicable to frames in a Debugger window.

## 3.5 Graphs

Graph windows are used by several Composer utilities. They are used to display runtime analysis data, to display cross-reference information, and to display class hierarchies.

Allegro Composer does not correctly display non-ASCII characters in graphs.

Here is a graph displaying the subclasses of the class `stream` (displayed by choosing `CLOS/Show class subclasses` and entering `stream` in the minibuffer).

## 3.5.1 Scrolling graphs

Since most graphs are larger than the window displaying them, only part of the graph is visible. You can scroll the graph about in a window in three ways: (1) with the scroll bars; (2) by dragging (described next); and (3) with the overview window.

Drag scrolling works by placing the mouse cursor in the interior of the window, but away from any node, and pressing the left or middle mouse button and dragging the mouse. The graph will move in concert with the mouse cursor.

## 3.5.2 The graph overview window

The overview window is displayed when you choose `Show Overview` from the Window menu on the menu bar of a graph window. The overview window of the stream subclasses window shown above is shown here:

The whole graph is visible (though the nodes do not display any information). The area currently displayed is shaded. Clicking any mouse button over a location in the overview window scrolls the associated graph window so the location clicked on is (roughly) in the center of the graph window.

## 3.5.3 The Window menu on a graph window menu bar

The menu typically contains the following commands:

- Quit: close the graph window (and its associated overview window, if present).
- Resize to Fit: resize the graph window to fit (as best as possible) the data displayed.
- Refresh: redraw the graph, usually to clean up garbage bits and other visual irregularities. Note the data is not recomputed or otherwise modified.
- Show Overview: show the overview window described in Section 3.5.2 The graph overview window.
- Recompute Graph: recreate the graph. All derived graphs stored on the History menu are destroyed (so the History menu reverts to having one entry). This choice takes into account new data (new subclasses to `stream` defined since the graph was originally displayed, for example).
- Find Node(s) From name: similar to the Lisp apropos function. See Section 3.5.7 The Find Node(s) from Name menu choice for details.

## 3.5.4 The History menu on a graph window menu bar

As described in Section 3.5.6 The :secondary-menu gesture over a graph node, you can display derived graphs that leave out specific subtrees or just display specific subtrees, etc. Each such derived graph is added as an item on the History menu. Choosing that item replaces the graph display with the derived graph. Graphs are typically named by their root (leftmost) node (perhaps with more information). The item on the menu corresponding to the currently displayed graph is grayed out.

When the graph first appears, the only entry on the History menu is the graph itself. Derived graphs are added as they are displayed. The image below shows the History menu for the stream subclasses graph when it is created (the only entry is labeled `stream`) and then the History menu after the derived graph containing the `fundamental-stream` subtree (labeled `subtree: fundamental-stream`) is displayed.

Note that choosing Recompute Graph from the Window menu destroys all derived graphs.

## 3.5.5 The :menu gesture over a graph node

The `:menu` gesture over a node displays a menu applicable to the object displayed in the node, with the additional choice `Menu of graph commands`, which displays the menu associated with the `:secondary-menu` gesture over the node. See the description of that menu below.

## 3.5.6 The :secondary-menu gesture over a graph node

The `:secondary-menu` gesture over a node displays a menu of choices which will display derived graphs. Typical choices include:

- Display More Parents: this choice only appears in the secondary menu over the root (leftmost) node. If more parents are known about, this item will be on the menu and choosing it will redisplay the graph. If this is chosen over the `stream` node, a new node labeled `standard-object` appears as `stream`'s parent.
- Hide Subtree: choosing this causes the graph to be redisplayed with the subtree to the right of the node removed. The node will then be boxed with a dotted rather than a solid line.
- Just Display Subtree: choosing this redisplays the graph with the node as the root node, and only the subtree to the right of it displayed.
- Print Subtree: this choice, which does not affect the graph, causes the names of nodes starting with the node under the menu, to be printed to an Emacs buffer, indented to approximate the graphical relationships.

## 3.5.7 The Find Node(s) from Name menu choice

Find Node(s) From Name is a choice in the Window menu on the menu bar of a graph window. When you choose this item, the following happens:

1. You are prompted in the Emacs minibuffer for a name. What you type is not evaluated. Symbol completion is available. You need only enter a portion (contiguous letters -- `undamental-st` from `fundamental-stream`, e.g.) of the desired name, just as with apropos.
2. The graph is searched for nodes whose names contain the entered contiguous letters.
3. If no matches are found, the message "No matching node found" is printed in the minibuffer.
4. If exactly one matching node is found, the graph is scrolled (not redrawn) so the matching node is placed left middle (as much as possible).
5. If more than one matching node is found, two things happen. (1) The graph is scrolled (not redrawn) so that the first (according to an internal list) match is left middle (as much as possible). (2) The overview window (if displayed) is redrawn so that the matching nodes are filled with gray. The gray fills disappear the next time the overview window is updated.

## 4.0 The debugger in Allegro Composer

The debugger in Allegro Composer uses both Emacs buffers and Composer windows to display information about broken processes. It utilizes the Allegro CL facilities for evaluation in context and for separate listeners.

The debugger functionality provided is not significantly different from that described in debugging.htm. What Allegro Composer adds is enhanced display of debugging information and the ability to identify and manipulate objects by pointing to them with the mouse.

You may note there is no item on the Composer menu corresponding to the debugger. That is because debugging facilities in Allegro Composer are only available when a Lisp process is in a break loop. Debugger windows are displayed with the top-level command :wdebug. Debugger windows display a stack backtrace (a zoom, displayed in a listener with the :zoom top-level command).

Debugging background processes (broadly, processes not set up to receive typed input) in special listener buffers occurs automatically, as described in Debugging background processes in debugging.htm. Note that this is a Lisp rather than a Composer feature.

## 4.1 Displaying a stack backtrace in a window

You can create a debugger window for a broken process by entering the command :wdebug to the listener for that process.

The window displaying the backtrace is called a debugger window. Clearing the error in the listener (using e.g. :pop or :reset) will cause the associated debugger window to be closed, as does clearing the error using the appropriate item in the Debugger menu on the debugger window also closes the window. But note that closing the window (by choosing Quit from the Window menu or clicking on the Close button) does not clear the error.

Here is the debugger window displayed when an undefined function `badfun` is called.

Note the following about this window:

- The individual frames are surrounded by parentheses.
- Only a maximum of three lines of each frame is displayed (unless you cause the whole frame to be displayed by choosing the appropriate item on the menu displayed by the `:secondary-menu` gesture over the frame).
- The function called in the frame is printed in bold type while the arguments are in regular type.
- The current frame is indicated with a `->`.

Debugger windows inherit the values of `*print-level*` and `*print-length*` from the listener to which the :wdebug command was typed. If the system determines the values are inappropriate, it will select appropriate values and print a message to that effect to the listener.

If another error occurs in the listener associated with a Debugger window, the Debugger window is not changed or updated. You should enter the :wdebug command again, which will cause the current Debugger window to be closed and a new one to be created.

The frames and some of the contents of frames are mouse-sensitive. The subsections that follow describe menus and mouse actions in debugger windows.

- Section 4.1.1 The Window menu on a Debugger window menu bar
- Section 4.1.2 The Debugger menu on a Debugger window menu bar
- Section 4.1.3 Menus over frames 1: the :secondary-menu gesture menu
- Section 4.1.4 Menus over frames 2: the :menu gesture menu
- Section 4.1.5 Menus over objects
- Section 4.1.6 The :menu gesture over a local

## 4.1.1 The Window menu on a Debugger window menu bar

This menu contains the usual Window menu entries. The same entries are on the background menu, displayed with the `:menu` gesture over a non-mouse-sensitive piece of a Debugger window (note that there are few places in a Debugger window that are not mouse-sensitive).

- Quit: close the Debugger window. Note that choosing this option does not clear the Lisp error being debugged.
- Resize to Fit: resize the Debugger window to fit (as best as possible) the data displayed.
- Refresh: redraw the Debugger window, usually to clean up garbage bits and other visual irregularities. Note the data is not recomputed or otherwise modified.

## 4.1.2 The Debugger menu on a Debugger window menu bar

The Debugger menu has choices which affect the broken process as well as the Debugger window itself. The choices depend on the state of the window. The two possibilities are illustrated next.

- Show All Frames: choosing this is similar to calling :zoom with arguments `:all t`. All frames, including those normally hidden, are displayed. This choice is only available when frames are hidden.
- Hide Frames: choosing this is simliar to calling :zoom with arguments `:all nil`. Frames normally hidden are hidden. This choice is only available when all frames are shown.
- Pop: choosing this has the programmatic effect of entering :pop to the listener of the broken process: the process pops up one break level (or to the top-level). The Debugger window will be closed (even if the process was in a break level higher than 1, and so is not reset to the top-level). See Pop and Refetch below.
- Reset: choosing this has the programmatic effect of entering :reset to the listener of the broken process: the process throws out to the top-level. The Debugger window will be closed.
- Refetch: choosing this causes the Debugger window to be updated (the window will go blank and then refill). This command has several uses. Among them are (1) redisplay when values have changed (because, perhaps, you set values in the Listener) and (2) redisplay when you want locals or specials to be hidden (locals and specials are not displayed after a Refetch even if they were displayed before the Refetch).
- Pop and Refetch: similar to choosing Refetch except the process is popped one break level and the Debugger window is recreated (if the process is still in a break level -- if popping takes the process to the top-level, the Debugger window is not recreated). The Debugger window will disappear and then reappear if the process is still in a break level.
- Restarts ->: if the process has any available restarts, they are listed in a submenu (whose existence is indicated by the ->). If no restarts are available, this item is grayed out (but restarts are essentially always available).

## 4.1.3 Menus over frames 1: the :secondary-menu gesture menu

When you perform the `:secondary-menu` gesture over a frame in a Debugger window, a menu of commands appropriate to the frame appears. The exact contents of the menu depends on the state of the Debugger window. The illustration below is the menu as soon as the Debugger window appears. To display this menu, the cursor must be over the frame, but the frame itself need not be selected (boxed). The `:secondary-menu` works even if something in the frame is selected (boxed).

The choices are:

- Show entire frame representation: choosing this will cause the entire frame to be displayed, rather than restricting the representation to a few lines. There is no direct inverse. Choosing Refetch from the Debugger menu will recompute the window and display frames in the abbreviated mode again.
- Show locals: choosing this will cause the window to be redisplayed with local variables associated with the frame displayed. If the frame is associated with compiled code, it must have been compiled with the compiler instructed to save local names (see `save-local-names-switch`). To get rid of locals, choose Hide locals from the (modified) menu or choose Refetch from the Debugger menu.
- Hide locals (not illustrated): If locals for the frame are shown, this item will be on the menu and choosing it will hide the locals.
- Show specials: choosing this will cause the window to be redisplayed with special variables bound in the frame displayed. To get rid of specials, choose Hide specials from the (modified) menu or choose Refetch from the Debugger menu.
- Hide the frame: choosing this causes the window to be redisplayed with this frame hidden. To get the frame back, choose Refetch from the Debugger menu.
- Restart this frame: choosing this is similar to entering the top-level command :restart to the listener.
- Restart this frame from a value: choosing this is similar to entering the top-level command :restart with an argument to the listener. You are prompted for the argument in the minibuffer. The argument must be a frame-like object, a list whose first element is the function called and whose remaining elements are the evaluated arguments.
- Return a value: choosing this is similar to entering the top-level command :return to the listener. You are prompted for a value in the minibuffer.

## 4.1.4 Menus over frames 2: the :menu gesture menu

Performing the `:menu` gesture over a frame displays a menu of commands on the frame. Note that the entire frame must be selected (boxed) for Composer to treat the frame as the object being pointed to (there are menus for objects represented in frames as well). The menu displayed is illustrated below.

- Inspect: inspect the frame object in an Inspector window.
- Setq *C* to Object: set the value of `*c*` to the frame object.
- Edit Definition: if the source file location is known for the code associated with the frame, that file is accessed and displayed in an Emacs buffer.
- Select this frame: make the frame the current frame.
- Menu of Frame Commands: display the menu displayed by the `:secondary-menu` gesture over the frame. That menu is described in Section 4.1.3 Menus over frames 1: the :secondary-menu gesture menu.

## 4.1.5 Menus over objects

The objects displayed in a Debugger window are presentations upon which gestures can be performed. When the mouse is over an object on which a gesture can be performed, that object is boxed. We described the menu over frames in the previous section and the menu over locals in the next section.

## 4.1.6 The :menu gesture over a local

Consider the function bar:

    (defun bar (x y)
      (break)
      (+ x y))

We evaluate `(bar 1 2)` and display a Debugger window. We have locals displayed because we have chosen Show locals from the `:secondary-menu` gesture over the frame (see Section 4.1.3 Menus over frames 1: the :secondary-menu gesture menu). The local Y is boxed.

When you perform the `:menu` gesture over a local, the menu displayed has choices:

- Set this variable: if you choose this, you are prompted in the minibuffer for a form. The variable is set to the value of the form.
- Set this variable from *C*: the value of the local variable will be set to the value of `*c*`.

## 5.0 The window-based inspector

The window-based inspector allows the user to examine the internals of any Lisp object. Many Composer windows present Lisp objects and allow you to inspect those objects using the `:inspect` gesture.

Inspector windows maintain a history of objects inspected. You can use the mouse to choose elements from that history for display in the window. Providing a history mechanism prevents a proliferation of inspector windows.

There are five ways to bring up an Inspector window:

- Call the winspect function: the function winspect takes any lisp object as an argument and displays an Inspector window for that object.
- Use the :winspect top-level command: the top-level command :winspect takes any Lisp object as an argument and displays an Inspector window for that object.
- Choose Inspect from the Composer menu: as described in Section 3.2.1 The Inspect menu item, the Inspect item of the Composer menu prompts you in the minibuffer for an object to inspect.
- Choose Inspect from another Composer menu: the Inspect command is typically available on the menu displayed by the `:menu` gesture. In this case, the object to inspect is the object being pointed to.
- Perform the :inspect gesture while over a mouse-sensitive object: when the menu displayed by the `:menu` gesture includes an Inspect item, the `:inspect` gesture (usually Control-Left) has the same effect as choosing Inspect from the menu.

## 5.1 Inspector windows and their menus

The illustration below shows an Inspector window inspecting `(cons 1 2)`.

The window has a title bar, a menu bar (with menus Window, Inspect as, and History), an interior (displaying the information) and scroll bars (not currently active).

The interior of an Inspector window has one or two header lines (only one in the illustration) identifying the object being inspected, and, below the header lines, two columns. The one on the left is the labels column and the one on the right the values column. (Note that zero, one, or more values may appear next to a single label though one value is most common.)

In the illustration, the one-line header line says `(1 .2) is of #<built-in class cons>`. Only two lines are allocated for header lines. Suspension points (...) are used if two lines are insufficient, to indicate missing material. If you want to see more, make the window wider (using window manager tools) and choose Refetch from the Window menu. Note that choosing Resize to Fit usually does not work for this purpose.

In the next illustration, we show the result of choosing Inspect from the Composer menu and entering `(find-class 'stream)` in the minibuffer. Note that this window is organized somewhat differently than the one illustrated above: instead of there being a column of labels and a column of values, the description is more discursive. This style of presentation is thought more useful for CLOS classes, and so it is used by default when a class is being inspected. The `Inspect as` menu (which we describe in more detail below in Section 5.1.2 The Inspect As menu on an Inspector window) shows different presentation styles. The one in the window is the `std-class` style. If you select the `t`, the window will redisplay in the label column/value column format.

Note too about the Inspector window for the stream class that the display is complete (because the scroll bars are not active) but none of the 17 methods mentioned at the bottom are displayed. `17 methods` is mouse sensitive and choosing Inspect from the menu displayed by the `:menu` gesture will inspect the methods.

In an Inspector window, you can (1) display an inspection of an object displayed; (2) set the value of (most of the) slots, and (3) change the method of inspection.

Using the `:select` gesture (typically clicking Left) over an object causes it to be inspected in the same window (previous inspections are available using the History menu). The `:inspect` gesture (typically clicking Control Left) brings up a new window. We recommend using the `:select` gesture to reduce the number of windows.

Using the `:select` gesture (typically clicking Left) over a label (actually, the label and the value are boxed) prompts you in the minibuffer for a new value and replaces the current value with the new one.

When the value column has no entry for a label, it means the slot named by the label is unbound. It does not mean that the value is `nil` or, say the empty string "". Symbols without a value have an empty value slot, for example.

In some cases a label has more than one corresponding value. This is an artifact of the presentation style: you can inspect a 2-d array (as returned by `(make-array '(2 2) :initial-contents '((1 2)(3 4)))`) as a 2-d matrix, with two labels indicating rows and having two values or as a vector with four labels with one value each. You can select each individual value and modify it. If you select the label and call for a new value, only one value is accepted and one changed.

## 5.1.1 The Window menu on an Inspector window

The Window menu has these choices:

- Quit: close the window.
- Resize to Fit: cause the window to be resized to fit (as best it can) the contents.
- Refresh: redisplay the window (to remove garbage bits, e.g.) but do not update the contents.
- Change Package: specify (in the minibuffer) the name of the package that is the current package when the contents are displayed (this affects which symbols are and are not package qualified). This action does not affect the current package in the listener.
- Refetch: redisplay the window and update the contents.
- Clone: create a new Inspector window with the same contents and history.

The background menu, displayed with the `:menu` gesture over a non-mouse-sensitive portion of the interior of an Inspector window, has the same contents as the Window menu.

## 5.1.2 The Inspect As menu on an Inspector window

The contents of this menu are determined by the inspected object. The choice `t` will always be present and there may be other choices as well.

The illustration shows the contents of the menu when inspecting a `cons`. The choices are `t`, `cons inspector`, and `list inspector`. The choices affect what labels are used, and how the values are grouped.

## 5.1.3 The History menu on an Inspector window

This menu keeps track of the history of inspections in the window. The printed representation of the object inspected is presented as a menu selection. The currently inspected object is masked. The purpose of this menu is to reduce the number of windows in use by using a single window many times.

## 5.1.4 Menus over labels and values in an Inspector window

The `:menu` gesture over a label of a settable slot (not all slots are settable) in an inspector window displays a menu with two choices:

- Set Slot: you are prompted in the minibuffer for a new value for the slot, if you choose this. If more than one value is displayed for a slot, only one is changed.
- Set slot from *c*: the value of the slot will be set to the value of `*c*`.

The `:menu` over a value will display a menu of choices suitable for that value.

## 6.0 Composer Browsers

A browser is a tool to examine some aspect of the Lisp system. Allegro Composer provides browsers for CLOS classes, cross reference information, systems defined with defsystem, and processes.

## 6.1 CLOS class browsers

The CLOS submenu (see Section 3.2.2 The CLOS submenu) of the Composer menu includes items `Show Class Superclasses` and `Show Class Subclasses`. When you choose either of these items, you are prompted in the minibuffer for a class name (which is not evaluated). See Section 3.5 Graphs for information on graphs.

## 6.2 Cross reference browsers

The Xref submenu (see Section 3.2.3 The Xref submenu) of the Composer menu includes items `Show Calls To`, `Show Calls From`, and `Show Calls To and From`. Only compiled functions add information to the cross reference database, and information is only added if `*record-xref-info*` and (when loading a fasl file) `*load-xref-info*` are true (but see the comment next on the `Xref Scans Entire Heap` option).

The cross reference facility (on which the graphs are based) is described in cross-reference.htm. Note that more information may be displayed in the Cross Reference graphs (if the option `Xref Scans Entire Heap` is on, see Section 3.2.5 The Options menu item) than cross reference data displayed in a listener. The latter only displays cross reference data collected from user files. The former (when the option is on) scans all compiled code vectors and thus finds much more information.

See also Section 3.5 Graphs for information on graphs.

## 6.3 The defsystem browser

A defsystem browser will be displayed when you choose `Other/System Browser` from the Composer menu. All systems are defined by the defsystem utility described in defsystem.htm.

Consider the following simple example. There are four files:

    ;; filea.cl

    (in-package :user)
    (defun funa () 'yow)

    ;; fileb.cl

    (in-package :user)
    (defun funb () 'wow)

    ;; macros.cl

    (in-package :user)
    (defmacro this-is-a-macro (x) '(+ ,x ,x))

    ;; not-macros.cl

    (in-package :user)
    (defun use-macro (x)
      (this-is-a-macro x))

The file sys.cl defines three systems:

    (in-package :user)

    (defsystem :my-system ()
      (:parallel "filea" "fileb"))

    (defsystem :my-other-system ()
      (:definitions "macros" "mot-macros"))

    (defsystem :my-super-system ()
      (:serial :my-system :my-other-system))

Load sys.cl and choose `Other/System Browser` from the Composer menu. The following window is displayed (assuming you do not already have systems defined. If you do, they will also be listed.)

The Window menu on the menu bar has the following choices:

- Quit: close the window.
- Resize to Fit: cause the window to be resized to fit (as best it can) the contents.
- Refresh: redisplay the window (to remove garbage bits, e.g.) but do not update the contents.
- Update Browser: redisplay the window and update the contents.

Applying the `:menu` gesture over a system displayed in the browser (in either column) displays the menu shown here.

It has the following choices:

- Describe: describe (in an Emacs buffer) the indicated system.
- Inspect: display an Inspector window inspecting the indicated system.
- Set *c* to Object: set the value of `*c*` to the the indicated system object.
- Edit Definition: find the file where the system is defined and open it in an Emacs buffer (the file sys.cl would be opened in our example).
- Show System: print a description of the indicated system to an Emacs buffer.
- Compile System: apply compile-system to the indicated system.
- Load System: apply load-system to the indicated system.
- Compile and Load System: apply compile-system and then load-system to the indicated system.

## 6.4 The Process Browser

Choosing `Other/Process Browser` from the Composer menu displays the Process Browser, which contains information about processes (or threads) currently running. (See multiprocessing.htm for information on processes and threads.) The Process Browser is illustrated below. This window is regularly automatically updated.

The header line at the top of the interior of the window labels the columns of information. These headings are the same as those printed by the :processes top-level command. They are:

- P: `*' if the process is set to be profiled by the runtime analyzer.
- Dis: The number of times this process has been resumed by the scheduler since the previous report.
- Sec: The total cpu time consumed by this process (approximate).
- dSec: The cpu time consumed by this process since the last report.
- Priority: The integer process priority.
- State: one of inactive, runnable, or waiting.
- Process name, Whostate, Arrest: the process name, the process whostate (if any), and a list of arrest reasons (if any).

The Process Browser has a Window menu on its menu bar. The choices are:

- Quit: close the window.
- Resize to Fit: resize the window (as best as can be done) to show all data.
- Refresh: redraw the window and update the contents.
- Change Update rate: the Process Browser is automatically updated regularly. This menu item allows you to specify the update rate. You are prompted in the Emacs minibuffer for an integer number (of seconds) when you choose this item. You can also specify `nil` to suppress automatic updating. When the window is not updated automatically, you can update manually be choosing Refresh.

## 6.4.1 The :menu gesture over a process

Only processes (the whole line, not any part) are boxed as you move the mouse about the interior. The menu displayed by the `:menu` gesture over a process is shown next.

- Describe: describe (in an Emacs buffer) the process object.
- Inspect: inspect the process object in an Inspector window.
- Set *c* to Object: set the value of `*c*` to the the indicated process object.
- Process Break: interrupt the process and put it in a break loop. Warning: do not use this on Allegro Composer processes.
- Process Kill: kill the process (with process-kill). Warning: do not use this on Allegro Composer processes.
- Process Arrest: add an arrest reason to the list of arrest reasons for the process. Warning: do not use this on Allegro Composer processes.
- Toggle Profile Stack Group P: change whether the space and time analyzers will collect data when this process is the current process. See profile-process-p.
- Restrict Profile to This Process Only: after choosing this, only this process will have a * in the P column indicating that it will be profiled by the runtime analyzer.

## 7.0 The window interface to the runtime analyzer

Runtime analysis using profiling in Allegro CL is described in runtime-analyzer.htm. There are space and time analyzers (as well as a call-counting profiler which has no window interface). The window interface described here is most useful for examining runtime analysis data. You can start and stop data collection with items on the profiler menu (see Section 3.2.4 The Profiler submenu) but you cannot suspend it, as you can with the functional interface.

Here is an illustration of the profiler submenu.

The items are described in Section 3.2.4 The Profiler submenu. Here we just discuss the Options choice. When you choose Options, the following dialog is displayed:

The `Profile Time or Space` option is set to time. Click on it to change it to space. Only one of [Start Profiler] (which starts data collection of the indicated type) and [Stop Profiler] is active, as the data collection is or is not occurring. The [Display Time Profile] and [Display Space Profile] are active only when there is data of the appropriate type to display. Note that items on the Profiler menu allow starting the time and the space data collection, and stopping them, and displaying data.

Two of the display parameters are associated with runtime analyzer variables, `*fractional-significance-threshold*` and `*significance-threshold*`. You can set the values by clicking on the current value, at which point you are prompted in the minibuffer for a new one. Max Number of Children specifies the value of an internal variable that controls the maximum number of child nodes a node in a graph may have. `nil` means no restriction. A change made to a value immediately changes the associated variable's value.

[Undo Changes] restores values to what they were when the dialog was first displayed. [Dismiss] closes the dialog.

## 7.1 Runtime analyzer profile graphs

Runtime analyzer profile graphs are similar in most respects to other Composer graph windows described in Section 3.5 Graphs but they do have some additional features. Let us consider an example. First display the Process Browser (choose `Other/Process browser` from the Composer menu. Click right (the `:menu` gesture over the Initial Lisp Listener process and choose Restrict Profile To This Process Only (this will reduce the amount of extraneous data). Start the time runtime analyzer profile by choosing `Profiler/Start Time Profiler` and evaluate `(pprint (list-all-packages))` in the listener. When that form completes, stop the data collection by choosing `Profiler/Stop Profiler`. Finally choose `Profiler/Display Time`. A window similar to this should appear.

Note the several double-headed arrows (<=>). These indicate elisions, where nodes have been left out (elided) because no significant time was used between the node to the left and the one to the right.

The first (leftmost) node is labeled `start 100%`. This node does not correspond to any actual Lisp function. It is simply the root of the graph.

All boxed nodes are sensitive to the mouse and have `:menu` and `:secondary-menu` menus defined. As usual, the `:menu` is associated with the contents of the node and the `:secondary-menu` gesture is associated with the node itself and the graph. here is the menu displayed by the `:secondary-menu` gesture over a node:

- Hide Subtree: this standard graph menu command displays a graph with the subtree starting at this node hidden.
- Just Display Subtree: this standard graph menu command displays a graph with just the subtree starting at this node displayed.
- Print Subtree: prints a description of the subtree starting at this node to an Emacs buffer.
- Hide This Subchain: this profile-graph-specific command is similar to Hide Subtree except the node is hidden as well.
- Unhide Suppressed Subchains (not illustrated): this profile-graph-specific command appears if subchains below the selected node are hidden. This command unhides them.
- Show Combined Subtree: show a new graph with all nodes naming the same function as the selected node combined. This is a useful choice when investigating one function.
- Print Statistics: print statistics associated with the selected node to an Emacs buffer.
- Expand Elision (not illustrated): when the menu is displayed over an elision marker (<=>), this command is on the menu and expands the elision.

## Appendix A: Configuring X windows for Allegro Composer

Allegro Composer is a standard X client. It therefore depends on standard X facilities for customization. In this appendix, we provide information necessary for using X utilities to customize Allegro Composer but it is beyond the scope of this document to describe X utilities in detail. We assume you are familiar with customizing X.

Like most X clients, Allegro Composer uses X resources for configuration. Unfortunately, different implementations of X on different machines set up resources differently. In most, however, there is a file name .Xresources which is used by X for configuration. The exact details of how this file is used are system-dependent but if the file is set up correctly when X is started, things should work as you want.

## Appendix A.1 Name and class of Composer tools

In X, tools have a name and a class. The following table shows the name and class of various Composer tools.

Tool | Name | Class
debugger | `composer.debugger` | `Composer.Debugger`
class graph | `composer.classGraph` | `Composer.Grapher`
who calls | `composer.whoCallsGraph` | `Composer.Grapher`
process browser | `composer.processBrowser` | `Composer.ProcessBrowser`
defsystem browser | `composer.defsysBrowser` | `Composer.DefsysBrowser`
inspector | `composer.inspector` | `Composer.Inspector`
profile graph | `composer.profilerGraph` | `Composer.Grapher`
listener | `composer.listener` | `Composer.Listener`
profiler options | `composer.profilerOptions` | `Composer.ProfilerOptions`

Graph overview windows have a name/class that is the same as the graph window name/class with `.overview'/`.Overview' appended to the name/class. Thus `composer.whoCallGraph.overview` and `Composer.Grapher.Overview`.

## Appendix A.2 Resources of tools

Tool resources include the following:

- geometry
- font
- boldFont
- italicFont
- boldItalicFont
- foreground
- background
- baseColor
- borderWidth
- matWidth
- borderColor
- matColor
- titleColor
- titleFont
- title
- iconGeometry
- backingStore
- maxWidth
- maxHeight

A resource of a particular tool is the name.resource. For example, the font resource of the process browser is `composer.processBrowser.font`.

The baseColor resource sets the tone colors of the window. It is normally a light color. The font resource specifies the default font. Bold, italic, and boldItalic fonts are derived from font unless they are also specified.

## Appendix A.3 Specifying resource values in .Xdefaults

You can specify the resource values in several ways.

You can specify exact matches, as with the following specifying the font of the Defsys Browser:

    composer.defsysBrowser.font -adobe-courier-medium-r-normal--12-120-75-75-m-70-iso8859-1

You can match the class and apply the resource to all tools of that class:

    Composer.Grapher: -adobe-courier-medium-r-normal--12-120-75-75-m-70-iso8859-1

You can use wildcards to specify a number of matching tools:

    composer*font: -adobe-courier-medium-r-normal--12-120-75-75-m-70-iso8859-1

You can specify both specific and general resources in the same file. The specific will take precedence over the general. For example, if the file contains this:

    composer*background: pink
    composer.processBrowser.background: purple

the background of all Composer windows will be pink except for the Process Browser. Its background will be purple.

## Appendix A.4 Reinitializing resources

The X resources are read by Lisp when Allegro Composer starts up. The resources are typically read by the X server. If you change the resources in the server (typically by modifying your .Xdefaults file and using the xrdb utility to load them into the server) Lisp will not see the changes unless you choose the `Reinitialize Composer Resources` item from the Other submenu of the Composer menu on the Emacs menu bar. Stopping and restarting Allegro Composer also works.

Note that we said `typically' several times in the last paragraph. It may be that resources are not loaded into the server but are handled in a different fashion. If that is the case, you must adapt what we have said to that situation. If choosing `Reinitialize Composer Resources` does not work, stop Allegro Composer and restart it.

## Appendix B: Problems starting Allegro Composer

If you start Allegro Composer from Allegro CL started with the Emacs command fi:common-lisp, so it is running as a subprocess of an Emacs displaying in a X window, you should not have any startup problems, since things should be set up in such a way that they will just work. Nonetheless, this appendix discusses potential problems.

## Appendix B.1 Error: there is no process named Connect to Emacs daemon

Allegro Composer can only be started when Allegro CL was started as a subprocess of Emacs with fi:common-lisp (in that case, there will be a Lisp process that communicates with Emacs called "Connect to Emacs daemon"). If you get this error, you have likely tried to start Allegro Composer when Lisp is not running as a subprocess of Emacs or the Emacs-Lisp interface has not started. Exit Lisp and restart in Emacs with fi:common-lisp.

## Appendix B.2 Error: package Composer not found

Allegro Composer is only available on Unix platforms. It is not available on the Windows version of Allegro CL, and the `composer` package is not defined in the Windows version. If you see this error, it is likely you are trying to start Allegro Composer in the Windows version. The Integrated Development Environment, which has many tools similar to those in Allegro Composer, is available in the Windows version.

## Appendix B.3 Error: Unknown hostname:

Since Emacs should already be running in an X window (and thus knows the host information), and Composer usually inherits this information from Emacs, this error should be unusual. However, you may be specifying a value for the host to start-composer, and that value is invalid, of (for some reason) the value within Emacs has changed. You might try calling start-composer with what you know to be the right host name.

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

ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version