SBCL Internals The pages on this CLiki-driven site can be edited by anybody at any time. No warranty of any kind can therefore be made; any implied warranties of merchantability or fitness for a particular purpose are expressly disclaimed

For people willing to do it, there's plenty TODO.

Here's an alternative proposal

* history (but please, not as the first chapter)

;; Quick start

* starting and stopping SBCL.  command-line args, if you want them
* using contrib modules, asdf-install etc (two paragraphs to cover require?, then fwd pointers)
* using lisp without going insane as quickly (external pointer to ilisp, etc)
* where to go for more lisp information (external pointers)
* porting: forward pointers to type inferencing, declarations, defconstant, style-warnings
* delivering applications (point to asdf, make-executable, save-l-a-d,  purify, wherever these features actually end up)
* optimizing: forward pointers to relevant sections of profiler, type system, gc issues ...

;; Reference

* driving the compiler : compiler policy, error messages
* the type system: truly-the, freeze-type, constant-function, inferencing etc
* trace, profile
* debugger 
* FFI (include SAP stuff in here as well: it's unavoidable)
* gc, gencgc, purify   [ we should be able to find a better home for this ]
* gray streams
* our clos implementation, and the mop
* contrib interface + asdf.  how to write a contrib module
* chapter for each contrib module, dynamically included from $SBCL_HOME/contrib

* implementation-defined constants, limits, etc
** chapter 1
** ...
** chapter 25

Getting there

I agree pretty much with Dan's sentiment as stated above, and propose the following reorganization of manual as a first step, requiring relatively little actual new text. The ideas here are to lift more material into their own chapters so that they gain more visibility, and to hide the distinction between the core SBCL and contributed modules as that isn't all that central to users (presumably). --Nikodemus

Table of contents

1. Introduction
   1. More Common Lisp Information
   2. More SBCL Information
   3. Overview
      1. Conformance With The ANSI Standard [was Non-Conformance]
      2. Idiosyncrasies
      3. History and Implementation
2. The Compiler
   1. Error Messages
      1. The Parts of the Error Message
      2. The Original and Actual Source
      3. Error Severity
      4. Errors During Macroexpansion
      5. Read Errors
   2. Handling of Types
      1. Type Errors at Compile Time
      2. Precise Type Checking
      3. Weakened Type Checking
      4. Getting Existing Programs to Run
      5. Implementation Limitations
   3. Compiler Policy
   4. Open Coding and Inline Expansion
   5. Efficiency
      1. Dynamic-extent allocation
      2. Modular arithmetic
      3. Extensions [truely-the, freeze-type, constant-function]
3. The Debugger
   1. Starting the Debugger
   2. The Debugger Command Loop
   3. Controlling Printing in the Debugger
   4. Stack Frames
      1. Stack Motion
      2. How Arguments are Printed
      3. Function Names
      4. Funny Frames
      5. Debug Tail Recursion
      6. Unknown Locations and Interrupts
   5. Variable Access
      1. Variable Value Availability
      2. Note On Lexical Variable Access
   6. Source Location Printing
      1. How the Source is Found
      2. Source Location Availability
   7. Debugger Policy Control
   8. Exiting Commands
   9. Information Commands
4. The Foreign Function Interface
   1. Introduction to the Foreign Function Interface
   2. Foreign Types
      1. Defining Foreign Types
      2. Foreign Types and Lisp Types
      3. Foreign Type Specifiers
   3. Operations On Foreign Values
      1. Accessing Foreign Values
      2. Coercing Foreign Values
      3. Foreign Dynamic Allocation
   4. Foreign Variables
      1. Local Foreign Variables
      2. External Foreign Variables
   5. Foreign Data Structure Examples
   6. Loading Unix Object Files
   7. Foreign Function Calls
      1. The alien-funcall Primitive
      2. The define-alien-routine Macro
      3. define-alien-routine Example
      4. Calling Lisp From C
   8. Step-By-Step Example of the Foreign Function Interface
   9. Groveling [sb-grovel]
5. Threading
6. Package Locks
   1. Package Lock Concepts
      1. Package Lock Overview
      2. Implementation Packages
      3. Package Lock Violations
      4. Package Locks in Compiled Code
      5. Operations Violating Package Locks
   2. Package Lock Dictionary
7. OS Interface
   1. Builtins OS Interfaces [Support for Unix]
   2. sb-posix
8. Profiling [sb-profile, sb-sprof]
9. Networking [sb-bsd-sockets]
10. Miscellaneus Extensions
    1. Pseudostandard Extensions [Things Which Might Be In the Next ANSI Standard]
    2. Function Tracing
    3. Purify and Saving Cores
    4. Customization Hooks
    5. sb-rotate-byte
    6. sb-md5
    7. sb-aclrepl

Interesting. OK, here's an alternative^3 which I think is mostly about rearranging your chapter headings a bit further. One goal is to end up with as little as possible in 'miscellaneous'

intro
repl + debugger (inc. aclrepl) + trace
compiler, minus the inlining and efficiency section
performance 
  - compiler 'efficiency' section
  - profile, sprof
  - gc and runtime information will go here too
package locks
networking
threading
non-networking non-threading unix interface stuff (sb-posix, run-program)
ffi (inc. SAPs and grovel)
delivery
  - saving cores
  - asdf (and asdf-install?)
  - sb-executable and related tricks
misc extensions: try and find more suitable homes for these - e.g. sb-rotate-byte may belong in 'performance'

I agree with minimizing the misc sections, but doubt we'll be able to clear all of it: there's a lot of stuff in SB-EXT that I don't see going away that really are tiny individual extensions to ANSI (PSXHASH, DEFINE-HASH-TABLE-TEST, floating point modes, etc). One option might be to group them by CLHS chapters.

This page is linked from: Manual   One Point Zero  

CLiki pages can be edited by anyone at any time. Imagine a fearsomely comprehensive disclaimer of liability. Now fear, comprehensively