About this manual

This manual contains a user guide section (previously published separately as the LispWorks User Guide ) and a reference section (previously the LispWorks Reference Manual ).

User Guide section

The user guide section of this manual describes the main language-level features and tools available in LispWorks, and how to use them.

These chapters describe the central programming tools and features in LispWorks:

• Starting LispWorks describes how to start LispWorks and supply command line arguments.
• The Listener describes the read-eval-print loop (REPL) listener.
• The Debugger describes the REPL debugger.
• The REPL Inspector describes the REPL inspector.
• The Trace Facility describes the tracer.
• The Advice Facility.
• Dspecs: Tools for Handling Definitions describes the naming system for Lisp definitions, and in particular how to locate these.
• Action Lists describes how you can run code at various hook points.
• The Compiler describes the compiler optimization qualities and some ways to optimize your code.
• Storage Management covers the behavior (and for wizard level users, configuration) of the garbage collector.
• The Profiler describes a tool for identifying bottlenecks impeding performance of your program.

The next chapter, Customization of LispWorks, explains how to perform some commonly required customizations, such as controlling start-up appearance of LispWorks.

The remaining user guide chapters describe features of specialist interest:

• LispWorks as a dynamic library describes how LispWorks operates as a DLL, .dylib or .so.
• The Metaobject Protocol describes how the LispWorks MOP implementation differs from AMOP.
• Multiprocessing, including locks.
• Common Defsystem and ASDF describes how to use defsystem to combine a series of source files into a manageable project.
• The Parser Generator.
• Dynamic Data Exchange describes how to implement DDE functionality in your Microsoft Windows applications.
• Common SQL explains how to use LispWorks to communicate with databases using SQL.
• User Defined Streams provides an illustrative example showing how to define and implement your own streams.
• TCP/IP socket communication and SSL describes the use of socket streams, including the Secure Sockets Layer (SSL).
• Internationalization provides an overview of using international characters.
• LispWorks' Operating Environment explains how to find information about the Operating System and how LispWorks was started.
• 64-bit LispWorks outlines differences between 64-bit LispWorks and 32-bit LispWorks.

Please note that documentation for Graphics Ports is in the LispWorks CAPI User Guide and LispWorks CAPI Reference Manual .

Reference section

Most of the reference section is organized by package: each chapter contains reference material for the exported symbols in a given package. The chapters are organized alphabetically by package name.

Generally one chapter covers each package, but the WIN32 package symbols are split into four chapters, and the last chapter contains reference material for C functions. Within each chapter, the symbols are organized alphabetically (ignoring non-alphanumeric characters that are common in Lisp symbols, such as *). The chapters are:

• The CLOS Package, describes the LispWorks extensions to CLOS, the Common Lisp Object System.
• The COMM Package, describes the functions providing the TCP/IP interface.
• The COMMON-LISP Package, describes the LispWorks extensions to symbols in the COMMON-LISP package. You should refer to the Common Lisp Hyperspec, supplied in HTML format with LispWorks, for full documentation about standard Common Lisp symbols.
• The COMPILER Package, describes symbols available in the COMPILER package.
• The DBG Package, describes symbols available in the DBG package, used to configure the debugging information produced by LispWorks.
• The DSPEC Package, describes the symbols available in the DSPEC package, which are used for naming and locating definitions.
• The EXTERNAL-FORMAT Package, describes symbols available in the EXTERNAL-FORMAT package.
• The HCL Package, describes symbols available in the HCL package.
• The LINK-LOAD Package, describes symbols available in the LINK-LOAD package. It applies to LispWorks for UNIX only (not LispWorks for Linux, FreeBSD, or x86/x64 Solaris).
• The LISPWORKS Package, describes symbols available in the LISPWORKS package.
• The MP Package, describes symbols available in the MP package, giving you access to the multi-processing capabilities of LispWorks.
• The PARSERGEN Package, describes symbols available in the PARSERGEN package, the LispWorks parser generator.
• The SERIAL-PORT Package documents the Serial Port API. This is implemented only in LispWorks for Windows.
• The SQL Package documents symbols used in accessing LispWorks ODBC and SQL functionality.
• The STREAM Package documents the symbols available in the STREAM package that provide users with the functionality to define their own streams for use by the standard I/O functions.
• The SYSTEM Package, describes symbols available in the SYSTEM package.
• Miscellaneous WIN32 symbols, describes miscellaneous symbols available in the WIN32 package. It applies only to LispWorks for Windows.
• The Windows registry API, describes the Windows registry API. It applies only to LispWorks for Windows.
• The DDE client interface, describes the Dynamic Data Exchange (DDE) client API. It applies only to LispWorks for Windows.
• The DDE server interface, describes the Dynamic Data Exchange (DDE) server API. It applies only to LispWorks for Windows.
• Dynamic library C functions, describes C functions available in LispWorks dynamic libraries.

Many of these reference chapters should be used in conjunction with corresponding chapters in the user guide section. Reference material for some aspects of LispWorks can be found in other manuals.

The LispWorks manuals

The LispWorks manual set comprises the following books:

• The Common Lisp Hyperspec contains the specification for Common Lisp itself.
• The LispWorks User Guide and Reference Manual --this book--describes the main language-level features and tools available in LispWorks, along with an extensive reference of the functions, macros, variables and classes organized by package. Where LispWorks extends the functionality of a Common Lisp symbol, this is mentioned in The COMMON-LISP Package
• The LispWorks IDE User Guide describes the LispWorks IDE, the user interface for LispWorks. This is a set of windowing tools that let you develop and test Common Lisp code more easily and quickly.
• The LispWorks Editor User Guide describes the keyboard commands and programming interface to the LispWorks IDE editor tool.
• The LispWorks CAPI User Guide and the LispWorks CAPI Reference Manual describe the CAPI. This is a library of classes, functions, and macros for developing graphical user interfaces for your applications. The LispWorks CAPI User Guide is a tutorial guide to the CAPI, and the LispWorks CAPI Reference Manual is an in-depth reference text.
• The LispWorks Foreign Language Interface User Guide and Reference Manual explains how you can use C source code in applications developed using LispWorks.
• The LispWorks Delivery User Guide describes how you can deliver working, standalone versions of your LispWorks applications for distribution to your customers.
• Developing Component Software with CORBA describes how LispWorks can interoperate with other CORBA-compliant systems.
• The LispWorks COM/Automation User Guide and Reference Manual describes a toolkit for using Microsoft COM and Automation in LispWorks for Windows.
• The LispWorks Objective-C and Cocoa Interface User Guide and Reference Manual describes APIs for interfacing to Objective-C and Cocoa in LispWorks for Macintosh.
• The KnowledgeWorks and Prolog User Guide describes the LispWorks toolkit for building knowledge-based systems. Common Prolog is a logic programming system written in Common Lisp.
• The LispWorks Release Notes and Installation Guide explains how to install LispWorks and start it running. It also contains Release Notes describing the new features in this release and any issues that could not be included in the other manuals.

The LispWorks manuals are all available in Portable Documentation Format (PDF). You can use Adobe Reader to browse the PDF documentation online or to print it. Adobe Reader is available for free download from Adobe's web site at www.adobe.com .

The LispWorks manuals are also available in HTML format. Commands in the Help menu of any of the LispWorks IDE tools give you direct access to the HTML documentation, using your web browser. Details of how to use these commands can be found in the LispWorks IDE User Guide .

Please let us know if you find any mistakes in the LispWorks documentation, or if you have any suggestions for improvements.

Other documentation

The LispWorks manuals do not attempt to describe Lisp itself. For definitive information on Common Lisp, including CLOS, consult the American National Standard X3.226 for Common Lisp. An HTML version of this document is supplied with LispWorks and can be accessed from the Help menu.

For information on CLOS, Sonya E. Keene's book Object-Oriented Programming in Common Lisp: A Programmers' Guide is very helpful. This book is published by Addison-Wesley.

For an account of Metaobject protocols as well as a detailed study of an implementation of CLOS see Kiczales, Rivieres and Bobrow, The Art of the Meta-Object Protocol , published by MIT Press, often referred to as AMOP. The LispWorks MOP mostly conforms chapters 5 & 6 of AMOP; the differences are mentioned here in The Metaobject Protocol.

Notation and conventions

Throughout this manual you will find references such as "... the LispWorks file foo/bar.lisp ...". This means a file bar.lisp in a subdirectory foo of the LispWorks library directory. You can obtain the full path of such a file by evaluating this form in your LispWorks image:

(sys:lispworks-file "foo/bar.lisp")

The LispWorks manuals follow the notation used in Common Lisp: the Language (2nd Edition).

Please note that your windows may differ in some respects from the illustrations given in the LispWorks manuals. This is because some details are controlled by the window manager that you are using, not by LispWorks itself.