Allegro CL User Guide Volume 1 (of 2) version 4.3 March, 1996 Copyright and other notices: This is revision 6 of this manual. This manual has Franz Inc. document number D-U-00-000-01-60320-1-6. Copyright 1985-1996 by Franz Inc. All rights reserved. No part of this pub- lication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means electronic, mechanical, by photocopying or recording, or otherwise, without the prior and explicit written permission of Franz incorpo- rated. Restricted rights legend: Use, duplication, and disclosure by the United States Government are subject to Restricted Rights for Commercial Software devel- oped at private expense as specified in DOD FAR 52.227-7013 (c) (1) (ii). Allegro CL and Allegro Composer are registered trademarks of Franz Inc. Allegro Common Windows, Allegro Presto, Allegro Runtime, and Allegro Matrix are trademarks of Franz inc. Unix is a trademark of AT&T. The Allegro CL software as provided may contain material copyright Xerox Corp. and the Open Systems Foundation. All such material is used and distrib- uted with permission. Other, uncopyrighted material originally developed at MIT and at CMU is also included. Appendix B is a reproduction of chapters 5 and 6 of The Art of the Metaobject Protocol by G. Kiczales, J. des Rivieres, and D. Bobrow. All this material is used with permission and we thank the authors and their publishers for letting us reproduce their material. Contents Volume 1 Preface 1 Introduction 1.1 The language 1-1 1.2 History 1-1 1.3 Format of the manual 1-2 1.4 An outline of the manual 1-3 1.5 Assistance available on the internet and the World Wide Web 1-4 The Allegro CL FAQ 1-4 Patches 1-4 Should you get all patches? 1-4 1.6 Comments and suggestions 1-5 1.7 Reporting bugs 1-5 Where to report bugs and send questions 1-6 1.8 Patches 1-6 Further information 1-6 Old ftp site no longer contains patches 1-6 2 Customizing and executing Common Lisp 2.1 How to run Lisp 2-2 2.1.1 How to run Lisp: general information 2-2 The image name 2-2 Image you execute may be a shell script 2-2 Command line arguments 2-3 Files Lisp must find to start up and files it may need later 2-4 Files Lisp needs to start up 1: .so files built with image 2-4 Files Lisp needs to start up 2: the Lisp home 2-5 What to do when Lisp cannot find the Lisp home 2-5 How does Lisp find loaded .so files? 2-7 The start-up message 2-8 2.1.2 Running Lisp as a subprocess of Emacs 2-9 Starting Lisp as a subprocess of Emacs the first time 2-9 Starting Lisp within Emacs after the first time 2-10 What if the Emacs-Lisp interface does not start? 2-10 2.1.3 Starting Lisp from a shell 2-11 2.1.4 Start-up problems 2-11 Lisp won’t start up at all (killed immediately) 2-11 2.2 How to exit Lisp 2-12 How to exit for sure 2-12 2.3 What Lisp does when as it starts up 2-13 ALLEGRO COMMON LISP 4.3 c - 1 2.4 Initialization and the sys:siteinit.cl and .clinit.cl files 2-14 Errors in an initialization file 2-14 No top-level commands in initialization files 2-15 Cannot (effectively) set a variable bound by load 2-15 Starting Allegro Composer from .clinit.cl 2-15 2.4.1 Setting global variables in initialization files 2-16 Where are the bindings defined? 2-16 Many binding are to specific values, not to the variables actual value 2-16 How to set the value so a listener sees it? 2-17 Definitions and examples. 2-17 2.4.2 A sample initialization file 2-18 2.5 After Lisp starts up 2-19 The initial prompt 2-19 Errors 2-20 What if the system seems to hang? 2-20 Enough C-c’s will always interrupt 2-20 Help while running Lisp 2-21 2.6 Files that may be looked for on startup and after startup 2-22 Table 2 notes: 2-23 2.7 Reader case modes 2-24 2.7.1 Changing case modes 2-26 2.7.2 More on compatibility and case preference 2-27 3 Implementation and extensions 3.1 Allegro CL and the ANSI CL standard 3-2 Compatibility with pre-ANSI CLtL-1 in Allegro CL 4.3 3-2 Other package changes and compile-time-too behavior 3-3 The function data type 3-4 3.1.1 CLOS and MOP 3-4 CLOS and MOP conformance 3-5 CLOS optimization 3-6 3.2 Data types 3-7 3.2.1 Characters 3-7 3.3 Pathnames 3-8 Unix symbolic links and truenames 3-8 3.3.1 Parsing Unix pathnames 3-9 Preprocessing 3-9 Determining the :directory component 3-9 Determining the :name component 3-10 Determining the :type component 3-10 Anomalies 3-10 Table of examples 3-11 3.3.2 The directory component of merged Unix pathnames 3-12 3.3.3 Logical pathnames 3-12 Logical pathnames: introduction 3-12 Logical pathnames: implementation details 3-13 Logical pathnames: implementation details 3-14 3.4 Packages and package locking 3-17 Packages in Allegro CL 3-17 Notes on specific packages 3-17 Package nicknames 3-18 c - 2 ALLEGRO COMMON LISP 4.3 Package locking and package definition locking 3-20 Package locking: 3-20 Package definition locking: 3-21 Implementation packages 3-22 Package locked errors 3-23 Locally circumventing package locked errors 3-24 The packages locked by default 3-24 Justification for package locking 3-25 3.5 Extensions 3-25 3.5.1 List of extensions 3-26 3.6 Autoloading 3-26 Where the autoloaded files are located 3-27 Common Lisp symbols 3-27 Major extensions 3-27 How to load modules 3-27 3.7 Miscellaneous extensions and implementation details 3-28 3.7.1 Extensions to Common Lisp functions 3-31 The random function 3-35 Extensions to make-hash-table 3-35 3.8 Errors 3-36 3.8.1 Some common errors 3-37 3.9 A note on portability 3-38 4 The top-level 4.1 Initialization 4-1 4.2 Interaction and the prompt 4-2 4.3 Commands and expressions 4-4 4.3.1 Case sensitivity of input 4-4 4.3.2 Getting help 4-5 4.3.3 Command and expression history 4-5 Anomalies with the :history list 4-7 4.3.4 Break levels 4-8 4.3.5 Commands for compiling and loading 4-11 File arguments are read as strings 4-11 4.3.6 Top-level interaction with multiprocessing 4-12 4.3.7 Commands for killing processes and exiting Lisp 4-14 4.3.8 Miscellaneous commands 4-15 4.4 Top-level variables 4-16 4.5 Adding new top-level commands 4-18 5 The debugger Getting out of the debugger 5-1 5.1 Internal functions 5-2 5.2 Debugging background processes 5-2 5.3 Stack commands 5-3 5.3.1 zoom 5-4 :brief, :moderate, and :verbose 5-7 :all t and :all nil 5-8 :function t and :function nil 5-8 :specials t and :specials nil 5-9 ALLEGRO COMMON LISP 4.3 c - 3 :relative t and :relative nil 5-9 The :bt command for a quick look at the stack 5-9 5.3.1.1 Variables that affect the behavior of :zoom 5-10 5.3.1.2 Special handling of certain errors 5-11 5.3.2 :zoom analogs and stack movement commands 5-12 5.3.3 Commands that hide frames 5-13 5.3.4 Frame information commands 5-15 5.3.5 Local variables and evaluation 5-16 Local variables and the debugger 5-17 Discard local variable information before dumplisp 5-17 Summary of this discussion 5-17 What are local variables? 5-18 How does the compiler treat local variables? 5-18 What is the difference between using registers and using the stack? 5-19 Live and dead ranges of local variables 5-19 Locals and functions in the tail position 5-19 Example showing live range 5-19 The debug=1 behavior with locals 5-21 The behavior with debug=2 5-21 Problem with debug=1 and debug=2 behavior before a local has a value 5-22 Why only have good behavior of locals at debug=3? 5-23 The behavior with debug=3 (and speed < 3) 5-23 The behavior with debug=3 and speed=3 5-24 I compiled with debug=3 but I want to see dead locals anyway 5-26 5.3.6 Break on exit 5-27 5.3.7 :return and :restart 5-28 5.3.8 Ghost frames in backtraces 5-33 Summary of this section 5-33 What is a ghost frame? 5-35 What kinds of optimizations cause ghost frames? 5-35 How does the debugger know about ghost frames? 5-36 When will the debugger display ghost frames? 5-36 Can I return from or restart a ghost frame? 5-37 What do the suspension points (‘...’) mean in a ghost frame? 5-37 The ghost frame has no ‘...’s; are all possible frames displayed? 5-37 No ghost frames are displayed.