[slime-cvs] CVS slime/doc
mbaringer
mbaringer at common-lisp.net
Wed Sep 20 18:37:47 UTC 2006
Update of /project/slime/cvsroot/slime/doc
In directory clnet:/tmp/cvs-serv8318/doc
Modified Files:
slime.texi
Log Message:
--- /project/slime/cvsroot/slime/doc/slime.texi 2006/04/20 05:46:50 1.47
+++ /project/slime/cvsroot/slime/doc/slime.texi 2006/09/20 18:37:47 1.48
@@ -34,7 +34,7 @@
@end macro
@set EDITION 2.0
- at set UPDATED @code{$Date: 2006/04/20 05:46:50 $}
+ at set UPDATED @code{$Date: 2006/09/20 18:37:47 $}
@titlepage
@title SLIME User Manual
@@ -64,96 +64,8 @@
* Debugger::
* Extras::
* Customization::
+* Tips and Tricks::
* Credits::
-
- at detailmenu
- --- The Detailed Node Listing ---
-
-Getting started
-
-* Platforms::
-* Downloading::
-* Installation::
-* Running::
-
-Downloading SLIME
-
-* CVS::
-* CVS Incantations::
-
-Downloading from CVS
-
-* CVS Incantations::
-
- at code{slime-mode}
-
-* User-interface conventions::
-* Commands::
-* Semantic indentation::
-* Reader conditionals::
-
-User-interface conventions
-
-* Temporary buffers::
-* Key bindings::
-* inferior-lisp::
-* Multithreading::
-
-Commands
-
-* Compilation::
-* Finding definitions::
-* Lisp Evaluation::
-* Documentation::
-* Programming Helpers::
-* Recovery::
-* Cross-reference::
-* Inspector::
-* Profiling::
-
-Programming Helpers
-
-* Completion::
-* Macro Expansion::
-* Accessing Documentation::
-* Disassembly::
-
-REPL: the ``top level''
-
-* REPL commands::
-* Input Navigation::
-* Shortcuts::
-
-SLDB: the SLIME debugger
-
-* Examining frames::
-* Restarts::
-* Frame Navigation::
-* Miscellaneous::
-
-Extras
-
-* slime-selector::
-* slime-autodoc-mode::
-* slime-macroexpansion-minor-mode::
-* Multiple connections::
-* Typeout frames::
-
-Customization
-
-* Emacs-side customization::
-* Lisp-side::
-
-Emacs-side
-
-* Hooks::
-
-Lisp-side (Swank)
-
-* Communication style::
-* Other configurables::
-
- at end detailmenu
@end menu
@node Introduction, Getting started, Top, Top
@@ -1271,7 +1183,7 @@
(add-hook 'slime-connected-hook 'slime-ensure-typeout-frame)
@end example
- at node Customization, Credits, Extras, Top
+ at node Customization, Tips and Tricks, Extras, Top
@chapter Customization
@menu
@@ -1334,7 +1246,7 @@
This variable controls filename translation between Emacs and the Lisp
system. It is useful if you run Emacs and Lisp on separate machines
which don't share a common file system or if they share the filessytem
-but have different layouts, os is the case with @acronym{SMB}-based
+but have different layouts, as is the case with @acronym{SMB}-based
file sharing.
@item slime-net-coding-system
@@ -1508,7 +1420,162 @@
@end table
- at node Credits, , Customization, Top
+ at node Tips and Tricks, Credits, Customization, Top
+ at chapter Tips and Tricks
+
+ at menu
+* Connecting to a remote lisp::
+* Global IO Redirection::
+* Auto-SLIME::
+ at end menu
+
+ at node Connecting to a remote lisp
+ at section Connecting to a remote lisp
+
+One of the advantages to the way @SLIME{} is implemented is that we
+can easily run the Emacs side (slime.el) on one machine and the lisp
+backend (swank) on another. The basic idea is to start up lisp on the
+remote machine, load swank and wait for incoming slime connections. On
+the local machine we start up emacs and tell slime to connect to the
+remote machine. The details are a bit messier but the underlying idea
+is that simple.
+
+ at menu
+* Setting up the lisp image::
+* Setting up Emacs::
+* Setting up pathname translations::
+ at end menu
+
+ at node Setting up the lisp image
+ at subsection Setting up the lisp image
+
+
+When you want to load swank without gonig through the normal, Emacs
+based, process just load the @file{swank-loader.lisp} file. Just
+execute
+
+ at example
+(load "/path/to/swank-loader.lisp")
+ at end example
+
+inside a running lisp image at footnote{@SLIME{} also provides an
+ at acronym{ASDF} system definiton which does the same thing}. Now all we
+need to do is startup our swank server. This example assumes we're
+using the default settings, if you need to do anything particular
+(like be able to reconnect to swank after you're done, look into
+ at code{swank:create-server}'s other arguments).
+
+ at example
+(swank:create-server)
+ at end example
+
+Since we're going to be tunneling our connection via
+ssh at footnote{there is a way to connect without an ssh tunnel, but it
+has the side-effect of giving the entire world access to your lisp
+image, se we're not gonig to talk about it} and we'll only have on
+port open we want to tell swank to not use an extra connection for
+output:
+
+ at example
+(setf swank:*use-dedicated-output-stream* nil)
+ at end example
+
+ at node Setting up Emacs
+ at subsection Setting up Emacs
+
+Now we need to create the tunnel between the local machine and the
+remote machine.
+
+ at example
+ssh -L4005:127.0.0.1:4005 username@@remote.example.com
+ at end example
+
+That ssh invocation creates an ssh tunnel between the port 4005 on our
+local machine and the port 4005 on the remote machine at footnote{By
+default swank listens for incoming connections on port 4005, had we
+passed a @code{:port} parameter to @code{swank:create-server} we'd be
+using that port number instead}.
+
+Finally we can start @SLIME{}:
+
+ at example
+M-x slime-connect RET RET
+ at end example
+
+The @kbd{RET RET} sequence just means that we want to use the default
+host (@code{127.0.0.1}) and the default port (@code{4005}). Even
+though we're connecting to a remote machine the ssh tunnel fools Emacs
+into thinking it's actually @code{127.0.0.1}.
+
+ at node Setting up pathname translations
+ at subsection Setting up pathname translations
+
+One of the main problems with running swank remotely is that Emacs
+assumes the files can be found using normal filenames. if we want
+things like @code{slime-compile-and-load-file} (@kbd{C-c C-k}) and
+ at code{slime-edit-definition} (@kbd{M-.}) to work correctly we need to
+find a way to let our local Emacs refer to remote files.
+
+There are, mainly, two ways to do this. The first is to mount, using
+NFS or similar, the remote machine's hard disk on the local machine's
+file system in such a fashion that a filename like
+ at file{/opt/project/source.lisp} refers to the same file on both
+machines. Unfortunetly NFS is usually slow, often buggy, and not
+always feasable, fortunetely we have an ssh connection and Emacs'
+ at code{tramp-mode} can do the rest.
+
+What we do is teach Emacs how to take a filename on the remote machine
+and translate it into something that tramp can understand and access
+(and vice-versa). Assuming the remote machine's host name is
+ at code{remote.example.com}, @code{cl:machine-instance} returns
+``remote'' and we login as the user ``user'' we can use @SLIME{}'s
+built-in mechanism to setup the proper transaltions by simply doing:
+
+ at example
+(push (slime-create-filename-translator :machine-instance "remote.example.com"
+ :remote-host "remote"
+ :username "user")
+ slime-filename-translations)
+ at end example
+
+ at node Global IO Redirection
+ at section Globally redirecting all IO to the REPL
+
+By default @SLIME{} does not change @code{*standard-output*} and
+friends outside of the @REPL{}. If you have any other threads which
+call @code{format}, @code{write-string}, etc. that output will be seen
+only in the @code{*inferior-lisp*} buffer or on the terminal, more
+often than not this inconvenient. So, if you want code such as this:
+
+ at example
+(run-in-new-thread
+ (lambda ()
+ (write-line "In some random thread.~%" *standard-output*)))
+ at end example
+
+to send its output to @SLIME{}'s repl buffer, as opposed to
+ at code{*inferior-lisp*}, set @code{swank:*globally-redirect-io*} to T.
+
+Note that the value of this variable is only checked when swank
+accepts the connection so you should set it via
+ at file{~/.swank.lisp}. Otherwise you will need to call
+ at code{swank::globally-redirect-io-to-connection} yourself, but you
+shouldn't do that unless you know what you're doing.
+
+ at node Auto-SLIME
+ at section Connecting to SLIME automatically
+
+To making @SLIME{} connect to your lisp whenever you open a lisp file
+just add this to your @file{.emacs}:
+
+ at example
+(add-hook 'slime-mode-hook
+ (lambda ()
+ (unless (slime-connected-p)
+ (save-excursion (slime)))))
+ at end example
+
+ at node Credits, , Tips and Tricks, Top
@chapter Credits
@emph{The soppy ending...}
More information about the slime-cvs
mailing list