[slime-cvs] CVS slime/doc

heller heller at common-lisp.net
Sun Sep 16 16:41:56 UTC 2007


Update of /project/slime/cvsroot/slime/doc
In directory clnet:/tmp/cvs-serv25401

Modified Files:
	slime.texi 
Log Message:
doc/slime.texi: Add a section Setup Tuning.


--- /project/slime/cvsroot/slime/doc/slime.texi	2007/08/26 18:42:23	1.55
+++ /project/slime/cvsroot/slime/doc/slime.texi	2007/09/16 16:41:56	1.56
@@ -8,9 +8,9 @@
 @end direntry
 @c %**end of header
 
- at set EDITION 2.0
+ at set EDITION 3.0-alpha
 @c @set UPDATED @today{}
- at set UPDATED @code{$Date: 2007/08/26 18:42:23 $}
+ at set UPDATED @code{$Date: 2007/09/16 16:41:56 $}
 @set TITLE SLIME User Manual
 @settitle @value{TITLE}, version @value{EDITION}
 
@@ -90,20 +90,20 @@
 @top SLIME
 
 @SLIME{} is the ``Superior Lisp Interaction Mode for Emacs''. This is
-the manual for version 1.2.
+the manual for version 3.0-alpha.
 
 @end ifinfo
 @menu
-* Introduction::
+* Introduction::                
 * Getting started::             
-* slime-mode::
+* slime-mode::                  
 * REPL::                        
 * Debugger::                    
 * Extras::                      
 * Customization::               
 * Tips and Tricks::             
 * Credits::                     
-* Index to Functions::                     
+* Index to Functions::          
 @end menu
 
 @c ----------------------- 
@@ -112,9 +112,9 @@
 
 @SLIME{} is the ``Superior Lisp Interaction Mode for Emacs.''
 
- at SLIME{} extends Emacs with new support for interactive programming in
-Common Lisp. The features are centered around @code{slime-mode}, an Emacs
-minor-mode that complements the standard @code{lisp-mode}. While
+ at SLIME{} extends Emacs with support for interactive programming in
+Common Lisp. The features are centered around @code{slime-mode}, an
+Emacs minor-mode that complements the standard @code{lisp-mode}. While
 @code{lisp-mode} supports editing Lisp source files, @code{slime-mode}
 adds support for interacting with a running Common Lisp process for
 compilation, debugging, documentation lookup, and so on.
@@ -145,15 +145,16 @@
 * Downloading::                 
 * Installation::                
 * Running::                     
+* Setup Tuning::                
 @end menu
 
 @c ----------------------- 
- at node Platforms, Downloading, Getting started, Getting started
+ at node Platforms
 @section Supported Platforms
 
 @SLIME{} supports a wide range of operating systems and Lisp
 implementations. @SLIME{} runs on Unix systems, Mac OSX, and Microsoft
-Windows. GNU Emacs versions 20 and 21 and XEmacs version 21 are
+Windows. GNU Emacs versions 20, 21 and 22 and XEmacs version 21 are
 supported.
 
 The supported Lisp implementations, roughly ordered from the
@@ -161,9 +162,9 @@
 
 @itemize @bullet
 @item
-CMU Common Lisp (@acronym{CMUCL}), 18e or newer
+CMU Common Lisp (@acronym{CMUCL}), 19d or newer
 @item
-Steel Bank Common Lisp (@acronym{SBCL}), latest official release
+Steel Bank Common Lisp (@acronym{SBCL}), 1.0 or newer
 @item
 OpenMCL, version 0.14.3 or newer
 @item
@@ -171,11 +172,12 @@
 @item
 Allegro Common Lisp (@acronym{ACL}), version 6 or newer
 @item
- at acronym{CLISP}, version 2.33.2 or newer
+ at acronym{CLISP}, version 2.35 or newer
 @item
 Armed Bear Common Lisp (@acronym{ABCL})
 @item
-Corman Common Lisp (@acronym{CCL}), version 2.51 or newer with the patches from @url{http://www.grumblesmurf.org/lisp/corman-patches})
+Corman Common Lisp (@acronym{CCL}), version 2.51 or newer with the
+patches from @url{http://www.grumblesmurf.org/lisp/corman-patches})
 @item
 Scieneer Common Lisp (@acronym{SCL}), version 1.2.7 or newer
 @end itemize
@@ -186,7 +188,7 @@
 commands (like ``restart frame'').
 
 @c ----------------------- 
- at node Downloading, Installation, Platforms, Getting started
+ at node Downloading
 @section Downloading SLIME
 
 You can choose between using a released version of @SLIME{} or
@@ -204,7 +206,7 @@
 @end menu
 
 @c ----------------------- 
- at node CVS, CVS Incantations, Downloading, Downloading
+ at node CVS
 @subsection Downloading from CVS
 
 @SLIME{} is available from the @CVS{} repository on
@@ -222,15 +224,14 @@
 
 If you checkout from @CVS{} then remember to @code{cvs update}
 occasionally.  Improvements are continually being committed, and the
- at code{FAIRLY-STABLE} tag is moved forward from time to time (about
-once per month).
+ at code{FAIRLY-STABLE} tag is moved forward from time to time.
 
 @menu
 * CVS Incantations::            
 @end menu
 
 @c ----------------------- 
- at node CVS Incantations,  , CVS, Downloading
+ at node CVS Incantations
 @subsection CVS incantations
 
 To download @SLIME{} you first configure your @code{CVSROOT} and login
@@ -262,7 +263,7 @@
 @end example
 
 @c ----------------------- 
- at node Installation, Running, Downloading, Getting started
+ at node Installation
 @section Installation
 
 With a Lisp implementation that can be started from the command-line,
@@ -287,7 +288,7 @@
 work correctly for a Lisp process started by @SLIME{}.
 
 @c ----------------------- 
- at node Running,  , Installation, Getting started
+ at node Running
 @section Running SLIME
 
 @SLIME{} is started with the Emacs command @kbd{M-x slime}. This uses
@@ -303,6 +304,130 @@
 @fcnanchor{slime-restart-inferior-lisp}
 @end table
 
+ at node Setup Tuning
+ at section Setup Tuning
+
+This section explains ways to reduce @SLIME{}'s startup time and how
+to configure @SLIME{} for multiple Lisp systems.  
+
+Please proceed with this section only if your basic setup works.  If
+you are happy with the basic setup, skip this section.
+
+ at menu
+* Autoloading::                 
+* Multiple Lisps::              
+* Loading Swank faster::        
+* Loading Contribs::            
+ at end menu
+
+ at node Autoloading
+ at subsection Autoloading
+
+The basic setup loads @SLIME{} always, even if you don't use @SLIME{}.
+Emacs will start up a little faster if we load @SLIME{} only on
+demand.  To achieve that, you have to change your @file{~/.emacs}
+slightly:
+
+ at example
+(setq inferior-lisp-program "@emph{the path to your Lisp system}")
+(add-to-list 'load-path "@emph{the path of your @file{slime} directory}")
+(require 'slime-autoloads)
+(slime-setup)
+ at end example
+
+The only difference compared to the basic setup is the line
+ at code{(require 'slime-autoloads)}.  It tells Emacs that the rest of
+ at SLIME{} should be loaded when one of the commands @kbd{M-x slime} or
+ at kbd{M-x slime-connect} is executed the first time.
+
+ at node Multiple Lisps
+ at subsection Multiple Lisps
+
+By default, the command @kbd{M-x slime} starts the program specified
+with @code{inferior-lisp-program}.  If you invoke @kbd{M-x slime} with
+a prefix argument, Emacs prompts for the program which should be
+started instead.  If you need that frequently or if the command
+involves long filenames it's more convenient to set the
+ at code{slime-lisp-implementations} variable in your @file{.emacs}.  For
+example here we define two programs:
+
+ at lisp
+(setq slime-lisp-implementations
+      '((cmucl ("cmucl" "-quiet"))
+        (sbcl ("/opt/sbcl/bin/sbcl") :coding-system utf-8-unix)))
+ at end lisp
+
+This variable holds a list of programs and if you invoke @SLIME{} with
+a negative prefix argument, @kbd{M-- M-x slime}, you can select a
+program from that list.  The elements of the list should look like
+
+ at lisp
+(NAME (PROGRAM PROGRAM-ARGS...) &key CODING-SYSTEM INIT INIT-FUNCTION)
+ at end lisp
+
+ at table @code
+ at item NAME
+is a symbol and is used to identify the program.
+ at item PROGRAM
+is the filename of the program.  Note that the filename can contain
+spaces.
+ at item PROGRAM-ARGS
+is a list of command line arguments.  
+ at item CODING-SYSTEM
+the coding system for the connection.  
+ at item INIT
+ at itemx INIT-FUNCTION 
+ ... to be written ...
+ at end table
+
+ at node Loading Swank faster
+ at subsection Loading Swank faster
+
+For SBCL, we recommend that you create a custom core file with socket
+support and @acronym{POSIX} bindings included because those modules
+take the most time to load.  To create such a core, execute the
+following steps:
+
+ at example
+shell$ sbcl
+* (mapc 'require '(sb-bsd-sockets sb-posix sb-introspect sb-cltl2 asdf))
+* (save-lisp-and-die "sbcl.core-for-slime")
+ at end example
+
+After that, add something like this to your @file{.emacs}:
+
+ at lisp
+(setq slime-lisp-implementations 
+      '((sbcl ("sbcl" "--core" "sbcl.core-for-slime"))))
+ at end lisp
+
+For maximum startup speed you can include the Swank server directly in
+a core file.  The disadvantage of this approach is that the setup is a
+bit more involved and that you need to create a new core file when you
+want to update @SLIME{} or @acronym{SBCL}.  The steps to execute are:
+
+ at example
+shell$ sbcl
+* (load ".../slime/swank-loader.lisp")
+* (save-lisp-and-die "sbcl.core-with-slime")
+ at end example
+
+ at noindent
+Then add this to your @file{.emacs}:
+
+ at lisp
+(setq slime-lisp-implementations 
+      '((sbcl ("sbcl" "--core" "sbcl.core-with-slime")
+              :init (lambda (port-file _)
+                      (format "(swank:start-server %S)\n" port-file)))))
+ at end lisp
+
+ at noindent
+Similar setups should also work for other Lisp implementations.
+
+ at node Loading Contribs
+ at subsection Loading Contribs
+... to be written ...
 
 @c ----------------------- 
 @node slime-mode, REPL, Getting started, Top
@@ -365,10 +490,10 @@
 @node Inferior-lisp, Multithreading, Temporary buffers, User-interface conventions
 @subsection @code{*inferior-lisp*} buffer
 
- at SLIME{} internally uses the @code{inferior-lisp} package to start
-Lisp processes. This has a few user-visible consequences, some good
-and some not-so-terribly. To avoid confusion it is useful to
-understand the interactions.
+ at SLIME{} internally uses the @code{comint} package to start Lisp
+processes. This has a few user-visible consequences, some good and
+some not-so-terribly. To avoid confusion it is useful to understand
+the interactions.
 
 The buffer @code{*inferior-lisp*} contains the Lisp process's own
 top-level. This direct access to Lisp is useful for troubleshooting,
@@ -377,18 +502,6 @@
 the fully-integrated @SLIME{} @REPL{} and ignoring the
 @code{*inferior-lisp*} buffer.
 
-An unfortunate property of @code{inferior-lisp} is it inserts some
-commands of its own directly into the @code{lisp-mode} keymap, such
-that they aren't easily disabled. This makes Lisp source buffers
-slightly schizophrenic, having both @SLIME{} and @code{inferior-lisp}
-commands bound to keys and operating independently.
-
- at SLIME{} overrides most key bindings, so in practice you are unlikely
-to accidentally use an @code{inferior-lisp} command. If you do find a
-command that pops up the @code{*inferior-lisp*} buffer, that command
-doesn't belong to @SLIME{}, and you should probably lookup our
-equivalent.
-
 @c ----------------------- 
 @node Multithreading,  , Inferior-lisp, User-interface conventions
 @subsection Multithreading
@@ -447,14 +560,18 @@
 
 @end table
 
- at emph{Note:} In this documentation the designation @kbd{C-h} is a @dfn{cannonical key} which might actually mean Ctrl-h, or F1, or whatever you have @code{help-command} bound to in your @code{.emacs}. Here is a common situation:
+ at emph{Note:} In this documentation the designation @kbd{C-h} is a
+ at dfn{cannonical key} which might actually mean Ctrl-h, or F1, or
+whatever you have @code{help-command} bound to in your
+ at code{.emacs}. Here is a common situation:
 
 @example
 (global-set-key [f1]   'help-command)
 (global-set-key "\C-h" 'delete-backward-char)
 @end example
 
- at noindent In this situation everywhere you see @kbd{C-h} in the documentation you would substitute @kbd{F1}.
+ at noindent In this situation everywhere you see @kbd{C-h} in the 
+documentation you would substitute @kbd{F1}.
 
 In general we try to make our key bindings fit with the overall Emacs
 style. We also have the following somewhat unusual convention of our
@@ -474,8 +591,8 @@
 C-h} will actually list the bindings for all documentation commands.
 This feature is just a bit too useful to clobber!
 
-You can assign or change default key bindings globally using the @code{global-set-key}
-function in your @file{~/.emacs} file like this:
+You can assign or change default key bindings globally using the
+ at code{global-set-key} function in your @file{~/.emacs} file like this:
 @example
 (global-set-key "\C-c s" 'slime-selector)
 @end example
@@ -483,8 +600,8 @@
 which binds @kbd{C-c s} to the function @code{slime-selector}.
 
 Alternatively, if you want to assign or change a key binding in just a
-particular slime mode, you can use the @code{global-set-key} function in
-your @file{~/.emacs} file like this:
+particular slime mode, you can use the @code{global-set-key} function
+in your @file{~/.emacs} file like this:
 @example
 (define-key slime-repl-mode-map (kbd "C-c ;") 
             'slime-insert-balanced-comments)
@@ -504,13 +621,13 @@
 to Functions}).
 
 @menu
-* Programming::         
+* Programming::                 
 * Compilation::                 
-* Evaluation::             
+* Evaluation::                  
 * Recovery::                    
 * Inspector::                   
 * Profiling::                   
-* Other::
+* Other::                       
 @end menu
 
 @c ----------------------- 
@@ -524,8 +641,8 @@
 
 @menu
 * Completion::                  
-* Closure::               
-* Indentation::               
+* Closure::                     
+* Indentation::                 
 * Documentation::               
 * Cross-reference::             
 * Finding definitions::         
@@ -544,14 +661,15 @@
 
 @table @kbd
 @anchor{slime-complete-symbol}
- at itemx M-TAB
- at item C-c C-i
- at item C-M-i
- at code{slime-complete-symbol}@*
-Complete the symbol at point. Note that three styles of completion are
-available in @SLIME{}, and the default differs from normal Emacs 
-completion (@pxref{slime-complete-symbol-function}). 
- at xref{Emacs-side customization}.

[140 lines skipped]




More information about the slime-cvs mailing list