add simple debugging tutorial "doc/Debugging.htm"
[eql:eql.git] / doc / Slime.htm
1 <html>
2 <head>
3 <link rel="stylesheet" href="style.css" type="text/css">
4 </head>
5 <h2>Slime</h2>
6 Requires <b>ECL threads</b>.
7 <p>
8 This should work with any Slime version that plays together with ECL.
9 <br>Tested with ECL 12.7.1 (Windows: ECL 12.12.1)
10 </p>
11 <ul>
12 <h3>Prepare</h3>
13 <ul>
14 <li>Add to your <code>~/.emacs</code> file:
15 <pre>
16 (add-to-list 'load-path "~/slime/")         ; slime path
17 (add-to-list 'load-path "~/slime/contrib/") ; slime/contrib path
18 (require 'slime)
19 (slime-require 'swank-listener-hooks)       ; EQL requires a listener hook
20 (slime-setup '(slime-fancy))
21 </pre>
22 <li>Add to your <code>~/.swank.lisp</code> file (or copy file <code>eql/slime/.swank.lisp</code> in your home directory):
23 <br>(Please note: this isn't really optional -- you <b>need</b> to set this option for a useful Slime + EQL.)
24 <pre>
25 (setf swank:*globally-redirect-io* t) ; show print output in Emacs
26 </pre>
27 <li>Copy the file <code>eql/slime/eql-start-swank.lisp</code> in your <code>slime/</code> directory
28 </ul>
29 <br>
30 <h3>Run</h3>
31 <ul>
32 <li>Run the Swank server (the command line option <code>-slime</code> can be omitted if the file name contains "start-swank"):
33 <pre>
34 eql &lt;path-to-slime&gt;/eql-start-swank.lisp
35 </pre>
36 <li>Run Emacs and do:
37 <code>Meta-X slime-connect</code> (please note:
38 use <code>slime-connect</code>) and hit <code>Return</code> 2 times
39 (confirming the default values).
40 <p>Please note: if <code>:dont-close</code> is set to <code>T</code>
41     in <code>eql-start-swank.lisp</code>, quitting/restarting Emacs will not
42     affect a running EQL program, that is: if you quit/restart Emacs, you can
43     connect to the same Swank/EQL you left when quitting Emacs.</p>
44 </ul>
45 <br>
46 <h3>Notes</h3>
47 <h4>Eval Region</h4>
48 <ul>
49 <li><b>Load</b> your Lisp file <b>from the Slime REPL</b>: <code>(load "file.lisp")</code>
50 <li><b>Run</b> your program <b>from the Slime REPL</b> (not using Eval Region).
51 <li>Only at this point you may use Eval Region for re-defining functions etc.
52 </ul>
53 <p>The point here is: if you directly try to Eval Region an expression containing an
54   EQL function, your swank server <b>will crash</b>, because it will not be
55   evaluated in the GUI thread (Qt GUI methods need to be called from the GUI thread).
56 </p>
57 <p>So, only run EQL functions <b>directly</b> from the <b>Slime REPL</b>.
58 <br>If you want to use <b>Eval Region</b> containing EQL functions, use the
59 method described above.
60 </p>
61 <hr>
62 <p>You may use the macro <code>qeval</code> if you want to ensure evaluation
63   in the GUI thread (this is meant to be used together with Eval Region only).
64 <br>It behaves like a <code>progn</code>, so you can do something like this:
65 <pre>
66 (qeval
67   (defvar *label* (qnew "QLabel"))
68   (defvar *edit*  (qnew "QLineEdit")))
69 </pre>
70 Wrapping forms in <code>qeval</code> will have no effect if you
71 run your code outside of Slime (so there's no need to
72 remove <code>qeval</code> in your final program).</p>
73 <hr>
74 <p>But note: the advantage using <b>Eval Region</b>
75   (<i>without</i> <code>qeval</code>) is that Lisp error conditions (not
76   driven by Qt events) will not stop/pause your EQL program (that is, Qt event
77   processing will continue).</p>
78 <p>Instead, if there is an error in code you either enter in the Slime REPL, or
79   run with Eval Region wrapped in <code>qeval</code>, the
80 program will always pause (Qt event processing will be stopped until you take some
81   action).</p>
82 <br>
83 <h4>Abort / Restart</h4>
84 <p>Be careful after entering the Slime debugger. If you see this:
85 <br>
86 <br><code>[ABORT] Return to SLIME's top level.</code>
87 <br><code>[RESTART-QT-EVENTS] Last resort only - prefer "Return to SLIME's top level"</code>
88 <br>
89 <br>Always choose the first one, otherwise you'll be stuck.
90 </p>
91 <br>
92 <h4>Help</h4>
93 <p>For help see the <code>qapropos</code> and <code>qgui</code> functions.</p>
94 </ul>
95 <br>
96 <hr>
97 <p><i>For a simple alternative, see <code>CL_EQL/</code>.
98 </i></p>
99 </br>
100 </html>