CMU Common Lisp User's Manual

Robert A. MacLachlan, Editor

July 1992
CMU-CS-92-161

July 1997
Net Version

School of Computer Science
Carnegie Mellon University
Pittsburgh, PA 15213

Supersedes Technical Reports CMU-CS-87-156 and CMU-CS-91-108.

Abstract

CMU Common Lisp is an implementation of that Common Lisp runs on various Unix workstations. See the README file in the distribution for current platforms. The largest single part of this document describes the Python compiler and the programming styles and techniques that the compiler encourages. The rest of the document describes extensions and the implementation dependent choices made in developing this implementation of Common Lisp. We have added several extensions, including a source level debugger, an interface to Unix system calls, a foreign function call interface, support for interprocess communication and remote procedure call, and other features that provide a good environment for developing Lisp code.

This research was sponsored by the Defense Advanced Research Projects Agency, Information Science and Technology Office, under the title Research on Parallel Computing issued by DARPA/CMO under Contract MDA972-90-C-0035 ARPA Order No. 7330.

The views and conclusions contained in this document are those of the authors and should not be interpreted as representing the official policies, either expressed or implied, of the Defense Advanced Research Projects Agency or the U.S. government.

Keywords: lisp, Common Lisp, manual, compiler, programming language implementation, programming environment

 
• Contents
• 1 Introduction
  • 1.1 Support
  • 1.2 Local Distribution of CMU Common Lisp
  • 1.3 Net Distribution of CMU Common Lisp
    • 1.3.1 CMU Distribution
    • 1.3.2 Net Distribution
  • 1.4 Source Availability
  • 1.5 Command Line Options
  • 1.6 Credits
• 2 Design Choices and Extensions
  • 2.1 Data Types
    • 2.1.1 Symbols
    • 2.1.2 Integers
    • 2.1.3 Floats
      • 2.1.3.1 IEEE Special Values
      • 2.1.3.2 Negative Zero
      • 2.1.3.3 Denormalized Floats
      • 2.1.3.4 Floating Point Exceptions
      • 2.1.3.5 Floating Point Rounding Mode
      • 2.1.3.6 Accessing the Floating Point Modes
    • 2.1.4 Characters
    • 2.1.5 Array Initialization
  • 2.2 Default Interrupts for Lisp
  • 2.3 Packages
  • 2.4 The Editor
  • 2.5 Garbage Collection
    • 2.5.1 GC Parameters
    • 2.5.2 Weak Pointers
    • 2.5.3 Finalization
  • 2.6 Describe
  • 2.7 The Inspector
    • 2.7.1 The Graphical Interface
    • 2.7.2 The TTY Inspector
  • 2.8 Load
  • 2.9 The Reader
  • 2.10 Stream Extensions
  • 2.11 Running Programs from Lisp
    • 2.11.1 Process Accessors
  • 2.12 Saving a Core Image
  • 2.13 Pathnames
    • 2.13.1 Unix Pathnames
    • 2.13.2 Wildcard Pathnames
    • 2.13.3 Logical Pathnames
    • 2.13.4 Search Lists
    • Predefined Search-Lists
    • Search-List Operations
    • 2.13.7 Search List Example
  • 2.14 Filesystem Operations
    • 2.14.1 Wildcard Matching
    • 2.14.2 File Name Completion
    • 2.14.3 Miscellaneous Filesystem Operations
  • 2.15 Time Parsing and Formatting
  • 2.16 Random Number Generation
    • 2.16.1 Original Generator
    • 2.16.2 New Generator
  • 2.17 Lisp Library
• 3 The Debugger
  • 3.1 Debugger Introduction
  • 3.2 The Command Loop
  • 3.3 Stack Frames
    • 3.3.1 Stack Motion
    • 3.3.2 How Arguments are Printed
    • 3.3.3 Function Names
    • 3.3.4 Funny Frames
    • 3.3.5 Debug Tail Recursion
    • 3.3.6 Unknown Locations and Interrupts
  • 3.4 Variable Access
    • 3.4.1 Variable Value Availability
    • 3.4.2 Note On Lexical Variable Access
  • 3.5 Source Location Printing
    • 3.5.1 How the Source is Found
    • 3.5.2 Source Location Availability
  • 3.6 Compiler Policy Control
  • 3.7 Exiting Commands
  • 3.8 Information Commands
  • 3.9 Breakpoint Commands
    • 3.9.1 Breakpoint Example
  • 3.10 Function Tracing
    • 3.10.1 Encapsulation Functions
  • 3.11 Specials
• 4 The Compiler
  • 4.1 Compiler Introduction
  • 4.2 Calling the Compiler
  • 4.3 Compilation Units
    • 4.3.1 Undefined Warnings
  • 4.4 Interpreting Error Messages
    • 4.4.1 The Parts of the Error Message
    • 4.4.2 The Original and Actual Source
    • 4.4.3 The Processing Path
    • 4.4.4 Error Severity
    • 4.4.5 Errors During Macroexpansion
    • 4.4.6 Read Errors
    • 4.4.7 Error Message Parameterization
  • 4.5 Types in Python
    • 4.5.1 Compile Time Type Errors
    • 4.5.2 Precise Type Checking
    • 4.5.3 Weakened Type Checking
  • 4.6 Getting Existing Programs to Run
  • 4.7 Compiler Policy
    • 4.7.1 The Optimize Declaration
    • The Optimize-Interface Declaration
  • 4.8 Open Coding and Inline Expansion
• 5 Advanced Compiler Use and Efficiency Hints
  • 5.1 Advanced Compiler Introduction
    • 5.1.1 Types
    • 5.1.2 Optimization
    • 5.1.3 Function Call
    • 5.1.4 Representation of Objects
    • 5.1.5 Writing Efficient Code
  • 5.2 More About Types in Python
    • 5.2.1 More Types Meaningful
    • 5.2.2 Canonicalization
    • 5.2.3 Member Types
    • 5.2.4 Union Types
    • 5.2.5 The Empty Type
    • 5.2.6 Function Types
    • 5.2.7 The Values Declaration
    • 5.2.8 Structure Types
    • The Freeze-Type Declaration
    • 5.2.10 Type Restrictions
    • 5.2.11 Type Style Recommendations
  • 5.3 Type Inference
    • 5.3.1 Variable Type Inference
    • 5.3.2 Local Function Type Inference
    • 5.3.3 Global Function Type Inference
    • 5.3.4 Operation Specific Type Inference
    • 5.3.5 Dynamic Type Inference
    • 5.3.6 Type Check Optimization
  • 5.4 Source Optimization
    • 5.4.1 Let Optimization
    • 5.4.2 Constant Folding
    • 5.4.3 Unused Expression Elimination
    • 5.4.4 Control Optimization
    • 5.4.5 Unreachable Code Deletion
    • 5.4.6 Multiple Values Optimization
    • 5.4.7 Source to Source Transformation
    • 5.4.8 Style Recommendations
  • 5.5 Tail Recursion
    • 5.5.1 Tail Recursion Exceptions
  • 5.6 Local Call
    • Self-Recursive Calls
    • 5.6.2 Let Calls
    • 5.6.3 Closures
    • 5.6.4 Local Tail Recursion
    • 5.6.5 Return Values
  • 5.7 Block Compilation
    • 5.7.1 Block Compilation Semantics
    • 5.7.2 Block Compilation Declarations
    • 5.7.3 Compiler Arguments
    • 5.7.4 Practical Difficulties
    • 5.7.5 Context Declarations
    • 5.7.6 Context Declaration Example
  • 5.8 Inline Expansion
    • 5.8.1 Inline Expansion Recording
    • Semi-Inline Expansion
    • The Maybe-Inline Declaration
  • 5.9 Byte Coded Compilation
  • 5.10 Object Representation
    • 5.10.1 Think Before You Use a List
    • 5.10.2 Structure Representation
    • 5.10.3 Arrays
    • 5.10.4 Vectors
    • Bit-Vectors
    • 5.10.6 Hashtables
  • 5.11 Numbers
    • 5.11.1 Descriptors
    • Non-Descriptor Representations
    • 5.11.3 Variables
    • 5.11.4 Generic Arithmetic
    • 5.11.5 Fixnums
    • 5.11.6 Word Integers
    • 5.11.7 Floating Point Efficiency
    • 5.11.8 Specialized Arrays
    • 5.11.9 Specialized Structure Slots
    • 5.11.10 Interactions With Local Call
    • 5.11.11 Representation of Characters
  • 5.12 General Efficiency Hints
    • 5.12.1 Compile Your Code
    • 5.12.2 Avoid Unnecessary Consing
    • 5.12.3 Complex Argument Syntax
    • 5.12.4 Mapping and Iteration
    • 5.12.5 Trace Files and Disassembly
  • 5.13 Efficiency Notes
    • 5.13.1 Type Uncertainty
    • 5.13.2 Efficiency Notes and Type Checking
    • 5.13.3 Representation Efficiency Notes
    • 5.13.4 Verbosity Control
  • 5.14 Profiling
    • 5.14.1 Profile Interface
    • 5.14.2 Profiling Techniques
    • 5.14.3 Nested or Recursive Calls
    • 5.14.4 Clock resolution
    • 5.14.5 Profiling overhead
    • 5.14.6 Additional Timing Utilities
    • 5.14.7 A Note on Timing
    • 5.14.8 Benchmarking Techniques
• 6 UNIX Interface
  • 6.1 Reading the Command Line
  • 6.2 Useful Variables
  • 6.3 Lisp Equivalents for C Routines
  • 6.4 Type Translations
  • 6.5 System Area Pointers
  • 6.6 Unix System Calls
  • 6.7 File Descriptor Streams
  • 6.8 Making Sense of Mach Return Codes
  • 6.9 Unix Interrupts
    • 6.9.1 Changing Interrupt Handlers
    • 6.9.2 Examples of Signal Handlers
• Event Dispatching with SERVE-EVENT
  • 7.1 Object Sets
  • The SERVE-EVENT Function
  • Using SERVE-EVENT with Unix File Descriptors
  • Using SERVE-EVENT with the CLX Interface to X
    • 7.4.1 Without Object Sets
    • 7.4.2 With Object Sets
  • A SERVE-EVENT Example
    • 7.5.1 Without Object Sets Example
    • 7.5.2 With Object Sets Example
• 8 Alien Objects
  • 8.1 Introduction to Aliens
  • 8.2 Alien Types
    • 8.2.1 Defining Alien Types
    • 8.2.2 Alien Types and Lisp Types
    • 8.2.3 Alien Type Specifiers
    • The C-Call Package
  • 8.3 Alien Operations
    • 8.3.1 Alien Access Operations
    • 8.3.2 Alien Coercion Operations
    • 8.3.3 Alien Dynamic Allocation
  • 8.4 Alien Variables
    • 8.4.1 Local Alien Variables
    • 8.4.2 External Alien Variables
  • 8.5 Alien Data Structure Example
  • 8.6 Loading Unix Object Files
  • 8.7 Alien Function Calls
    • The alien-funcall Primitive
    • The def-alien-routine Macro
    • def-alien-routine Example
    • 8.7.4 Calling Lisp from C
    • 8.7.5 Accessing Lisp Arrays
  • Step-by-Step Alien Example
• 9 Interprocess Communication under LISP
  • 9.1 The REMOTE Package
    • 9.1.1 Connecting Servers and Clients
    • 9.1.2 Remote Evaluations
    • 9.1.3 Remote Objects
    • 9.1.4 Host Addresses
  • 9.2 The WIRE Package
    • 9.2.1 Untagged Data
    • 9.2.2 Tagged Data
    • 9.2.3 Making Your Own Wires
  • Out-Of-Band Data
• 10 Debugger Programmer's Interface
  • 10.1 DI Exceptional Conditions
    • Debug-conditions
    • Debug-errors
  • Debug-variables
  • 10.3 Frames
  • Debug-functions
  • Debug-blocks
  • 10.6 Breakpoints
  • Code-locations
  • Debug-sources
  • 10.9 Source Translation Utilities
• About this document ...