[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