source: trunk/source/doc/src/install.xml @ 13554

Last change on this file since 13554 was 13554, checked in by rme, 10 years ago

Some minor updates, primarily changingv version numbers from 1.3 to 1.4.
Hey, it's only 5 months late.

File size: 34.6 KB
Line 
1<?xml version="1.0" encoding="utf-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3          "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
4          <!ENTITY rest "<varname>&amp;rest</varname>">
5          <!ENTITY key "<varname>&amp;key</varname>">
6          <!ENTITY optional "<varname>&amp;optional</varname>">
7          <!ENTITY body "<varname>&amp;body</varname>">
8          <!ENTITY aux "<varname>&amp;aux</varname>">
9          <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
10          <!ENTITY CCL "Clozure CL">
11          ]>
12
13<chapter id="installing"><title>Obtaining, Installing, and Running &CCL;</title>
14 
15  <!-- ============================================================ -->
16  <sect1 id="releases"><title>Releases and System Requirements</title>
17   
18    <para>As of this writing, &CCL; 1.4 is the latest release; it was
19    made in October 2009.  For up-to-date information about releases,
20    please see <ulink url="http://ccl.clozure.com/"/>.
21    </para>
22
23   <para>&CCL; runs on the following platforms:</para>
24    <itemizedlist>
25      <listitem>
26        <para>Linux (x86, x86-64, ppc32, ppc64)</para>
27      </listitem>
28      <listitem>
29        <para>Mac OS X 10.4 and later (x86, x86-64, ppc32, ppc64)</para>
30      </listitem>
31      <listitem>
32        <para>FreeBSD 6.x and later (x86, x86-64)</para>
33      </listitem>
34      <listitem>
35        <para>Solaris (x86, x86-64)</para>
36      </listitem>
37      <listitem>
38        <para>Microsoft Windows XP and later (x86, x86-64)</para>
39      </listitem>
40    </itemizedlist>
41
42    <!-- ***************************************************** -->
43    <sect2 id="linuxppc"><title>LinuxPPC</title> 
44     
45      <para>&CCL; requires version 2.2.13 (or later) of the Linux
46      kernel and version 2.1.3 (or later) of the GNU C library (glibc)
47      at a bare minimum.</para>
48    </sect2>
49
50    <!-- ***************************************************** -->
51    <sect2 id="linuxx86"><title>Linux x86</title> 
52   
53      <para>
54        Because of the nature of Linux distributions, it's difficult
55        to give precise version number requirements.  In general, a
56        "fairly modern" (no more than 2 or three years old) kernel and
57        C library are more likely to work well than older
58        versions.</para>
59    </sect2>
60
61    <!-- ***************************************************** -->
62    <sect2 id="freebsdx86"><title>FreeBSD x86</title>
63    <para>&CCL; should run on
64    FreeBSD 6.x and 7.x.
65    FreeBSD 7 users will need to install the "compat6x" package in order to use
66    the distributed &CCL; kernel, which is built on a FreeBSD 6.x system.</para>
67    </sect2>
68
69    <!-- ***************************************************** -->
70    <sect2 id="macosx"><title>Mac OS X (ppc and x86)</title>
71
72      <para> &CCL; runs under Mac OS X versions 10.4 and later.  Post-1.4
73      versions will require at least 10.5.
74      </para>
75
76      <para>64-bit versions of &CCL; naturally require 64-bit processors
77      (e.g., a G5 or Core 2 processor).  Some early Intel-based Macintoshes
78      used processors that don't support
79      64-bit operation, so the 64-bit &CCL; will not run on them, although
80      the 32-bit &CCL; will.
81      </para>
82    </sect2>
83    <sect2 id="windows"><title>Microsoft Windows</title>
84    <para>
85      At the moment, the 32-bit &CCL; does not run under 64-bit Windows.
86    </para>
87    </sect2>
88  </sect1>
89
90
91  <!-- ============================================================ -->
92  <sect1 id="obtaining-ccl"><title>Obtaining &CCL;</title>
93    <para>There two main ways to obtain &CCL;.  For Mac OS X,
94    there are disk images that can be used to install &CCL; in
95    the usual Macintosh way. For other OSes, Subversion is the best
96    way to obtain &CCL;.  Mac OS X users can also use Subversion
97    if they prefer. Tarballs are available for those who prefer them,
98    but if you have Subversion installed, it is simpler and more
99    flexible to use Subversion than tarballs.
100    </para>
101
102    <para> There are three popular ways to use &CCL;: as a
103      stand-alone double-clickable application (Mac OS X only), as a
104      command-line application, or with EMACS and SLIME. The following
105      sections describe these options.</para>
106
107    <!-- ***************************************************** -->
108    <sect2 id="obtaining-the-mac-way"><title>The Mac Way</title>
109      <para>If you are using Mac OS X then you can install and use
110         &CCL; in the usual Macintosh way.  Download and mount a
111         disk image, then drag the ccl folder to the Applications folder
112         or wherever you wish.
113         After that you can double-click the Clozure CL application found
114         inside the ccl directory.  The disk images are available at
115         <ulink url="ftp://clozure.com/pub/release/1.4/"/> </para>
116
117      <para>So that &CCL; can locate its source code, and for other
118        reasons explained in
119        <xref linkend="Predefined-Logical-Hosts"/>, you keep the
120        Clozure CL application
121        in the <literal>ccl</literal> directory.  If you use a shell,
122        you can set the value of the
123        <varname>CCL_DEFAULT_DIRECTORY</varname> environment variable
124        to explicitly indicate the location of
125        the <literal>ccl</literal> directory. If you choose to do
126        that, then the <literal>ccl</literal> directory and the Clozure CL
127        application can each be in any location you find
128        convenient.</para>
129    </sect2>
130   
131
132    <!-- ***************************************************** -->
133    <sect2 id="obtaining-via-svn"><title>Getting &CCL; with Subversion</title>
134      <para>It is very easy to download, install, and build &CCL;
135      using Subversion. This is the preferred way to get either the
136      latest, or a specific version of &CCL;, unless you prefer
137      the Mac Way.  Subversion is a source code control system that is
138      in wide use.  Many OSes come with Subversion
139      pre-installed. A complete, buildable and runnable set of &CCL;
140      sources and binaries can be retrieved with a single Subversion command.
141      </para>
142
143      <para>Day-to-day development of &CCL; takes place in an area
144      of the Subversion repository known as the trunk.  At most times,
145      the trunk is perfectly usable, but occasionally it can be unstable
146      or totally broken.  If you wish to live on the
147      bleeding edge, the following command will fetch a copy of the trunk
148      for Darwin x86 (both 32- and 64-bit versions):
149      </para>
150
151        <programlisting>
152          <![CDATA[
153svn co http://svn.clozure.com/publicsvn/openmcl/trunk/darwinx86/ccl]]>
154        </programlisting>
155
156        <para>
157          To get a trunk &CCL; for another platform, replace
158          "darwinx86" with one of the following names (all versions
159          include both 32- and 64-bit binaries):
160        </para>
161        <itemizedlist>
162          <listitem><para>darwinx86</para></listitem>
163          <listitem><para>linuxx86</para></listitem>
164          <listitem><para>freebsdx86</para></listitem>
165          <listitem><para>solarisx86</para></listitem>
166          <listitem><para>windows</para></listitem>
167          <listitem><para>linuxppc</para></listitem>
168          <listitem><para>darwinppc</para></listitem>
169        </itemizedlist>
170
171        <para>Release versions of &CCL; are intended to be stable.  While
172        bugs will be fixed in the release branches, enhancements
173        and new features will go into the trunk.  To get the 1.4 release
174        of &CCL; type:</para>
175        <programlisting>
176          <![CDATA[
177svn co http://svn.clozure.com/publicsvn/openmcl/release/1.4/darwinx86/ccl]]>
178        </programlisting>
179
180       
181        <para>The above command will fetch the complete sources and binaries
182        for the Darwin x86 build of &CCL;. To get a &CCL; for another platform,
183        replace "darwinx86" with one of the following names (all versions
184        include both 32- and 64-bit binaries):</para>
185
186        <itemizedlist>
187          <listitem><para>darwinx86</para></listitem>
188          <listitem><para>linuxx86</para></listitem>
189          <listitem><para>freebsdx86</para></listitem>
190          <listitem><para>solarisx86</para></listitem>
191          <listitem><para>windows</para></listitem>
192          <listitem><para>linuxppc</para></listitem>
193          <listitem><para>darwinppc</para></listitem>
194        </itemizedlist>
195
196        <para>These distributions contain complete sources and
197        binaries. They use Subversion's "externals" features to share
198        common sources; the majority of source code is the same across
199        all versions.</para> 
200
201        <para>Once the checkout is complete you can build &CCL; by
202        running the lisp kernel and executing
203        the <literal>rebuild-ccl</literal> function. For
204        example:</para>
205
206        <programlisting>
207          <![CDATA[
208joe:ccl> ./dx86cl64
209Welcome to Clozure Common Lisp Version 1.2  (DarwinX8664)!
210? (rebuild-ccl :full t)
211
212<lots of compilation output>
213
214  ? (quit)
215  joe:ccl>]]>
216        </programlisting>
217
218        <para>
219          If you don't have a C compiler toolchain installed,
220          <literal>rebuild-ccl</literal> will not work.  Please
221          refer to <xref linkend="building-ccl-from-source"/> for
222          addtional details.
223        </para>
224        <sect3 id="Checking-Subversion-Installation"><title>Checking Subversion Installation</title>
225      <para>If <literal>svn co</literal> doesn't work, then make sure
226      that Subversion is installed on your system.  Bring up a command
227      line shell and type:
228        <programlisting>
229          <![CDATA[
230shell> svn]]>
231        </programlisting> 
232        If Subversion is installed, you will see something like:
233        <programlisting>
234          <![CDATA[
235Type 'svn help' for usage]]>
236        </programlisting>
237        If Subversion is not installed, you will see something
238        like:
239        <programlisting>
240          <![CDATA[
241-bash: svn: command not found]]>
242        </programlisting>
243        If Subversion is not installed, you'll need to figure out how
244        to install it on your OS. You can find information about
245        obtaining and installing Subversion at
246        the <ulink url="http://subversion.tigris.org/project_packages.html">Subversion
247        Packages page</ulink>.</para></sect3>
248
249    </sect2>
250
251    <!-- ***************************************************** -->
252    <sect2 id="obtaining-via-tarballs"><title>Tarballs</title>
253      <para>Tarballs are available at <ulink
254      url="ftp://clozure.com/pub/release/1.4/"/>.  Download and extract
255      one on your local disk.  Then edit the &CCL; shell script to set
256      the value of <varname>CCL_DEFAULT_DIRECTORY</varname> and start
257      up the appropriate &CCL; kernel. See <xref
258      linkend="The-ccl-Shell-Script"/> for more information about the
259      &CCL; shell scripts.</para>
260    </sect2>
261  </sect1>
262
263  <!-- ============================================================ -->
264  <sect1 id="command-line-setup"><title>Command Line Set Up</title>
265    <para>Sometimes it's convenient to use &CCL; from a Unix
266      shell command line.  This is especially true when using &CCL;
267      as a way to run Common Lisp utilities.</para>
268
269    <!-- ***************************************************** -->
270    <sect2 id="The-ccl-Shell-Script"><title>The ccl Shell Script</title>
271      <para>&CCL; needs to be able to find the
272        <literal>ccl</literal> directory in order to support features
273        such as <literal>require</literal> and
274        <literal>provide</literal>, access to foreign interface
275        information (see <link linkend="The-Interface-Database">The
276        Interface Database</link>) and the Lisp build process (see
277        <link linkend="Building-CCL">Building &CCL; from its Source
278        Code</link>). Specifically, it needs to set up logical
279        pathname translations for the <literal>"ccl:"</literal>
280        logical host.  If this logical host isn't defined (or isn't
281        defined correctly), some things might work, some things might
282        not, and it'll generally be hard to invoke and use &CCL;
283        productively.</para>
284
285      <para>&CCL; uses the value of the environment variable
286        <literal>CCL_DEFAULT_DIRECTORY</literal> to determine the
287        filesystem location of the <literal>ccl</literal> directory;
288        the ccl shell script is intended to provide a way to
289        invoke &CCL; with that environment variable set
290        correctly.</para>
291      <para>There are two versions of the shell script:
292        <literal>"ccl/scripts/ccl"</literal> is used to invoke
293        32-bit implementations of &CCL; and
294        <literal>"ccl/scripts/ccl64"</literal> is used to invoke
295        64-bit implementations.</para>
296      <para>To use the script:</para>
297      <orderedlist>
298        <listitem>
299          <para>Copy the script to a directory that is on your
300          <varname>PATH</varname>.  This is often
301          <literal>/usr/local/bin</literal> or
302          <literal>~/bin</literal>.  It is better to do this than to
303          add <literal>ccl/scripts</literal> to your
304          <varname>PATH</varname>, because the script needs to be edited,
305          and editing it in-place means that Subversion sees the script as
306          modified..</para>
307        </listitem>
308        <listitem>
309          <para>Edit the definition of
310            <literal>CCL_DEFAULT_DIRECTORY</literal> near the
311            beginning of the shell script so that it refers to
312            your <literal>ccl</literal> directory.  Alternately, set
313            the value of the <literal>CCL_DEFAULT_DIRECTORY</literal>
314            environment variable in your .cshrc, .tcshrc,
315            .bashrc,.bash_profile, .MacOSX/environment.plist, or
316            wherever you usually set environment variables.  If there
317            is an existing definition of the variable, the ccl
318            script will not override it.
319          </para>
320        </listitem>
321
322        <listitem>
323          <para>Ensure that the shell script is executable, for
324            example:</para> 
325          <para><literal>$ chmod +x
326            ~/ccl/ccl/scripts/ccl64</literal></para> 
327          <para>This command grants execute permission to the named
328            script. If you are using a 32-bit platform, substitute
329            "ccl" in place of "ccl64".
330            <warning>
331                  <para>The above command won't work if you are not the
332                    owner of the installed copy of &CCL;. In that case,
333                    you can use the "sudo" command like this:</para>
334              <para><literal>$ sudo chmod +x
335                  ~/ccl/ccl/scripts/ccl64</literal></para>
336              <para>Give your password when prompted.</para>
337              <para>If the "sudo" command doesn't work, then you are
338                not an administrator on the system you're using, and you
339                don't have the appropriate "sudo" permissions. In that
340                case you'll need to get help from the system's
341                administrator.</para>
342          </warning></para>
343        </listitem>
344      </orderedlist>
345
346      <para>Note that most people won't need both
347      <literal>ccl</literal> and <literal>ccl64</literal> scripts.
348      You only need both if you sometimes run 32-bit &CCL; and
349      sometimes run 64-bit &CCL;.  You can rename the script that
350      you use to whatever you want.  For example, if you are on a
351      64-bit system, and you only use &CCL; in 64-bit mode, then
352      you can rename  <literal>ccl64</literal> to
353      <literal>ccl</literal> so that you only need to type
354      "<literal>ccl</literal>" to run it.</para>
355
356      <para>Once this is done, it should be possible to invoke &CCL;
357        by typing <literal>ccl</literal>
358        or <literal>ccl64</literal> at a shell prompt:</para>
359      <programlisting>
360&gt; ccl [args ...]
361Welcome to &CCL; Version 1.2 (DarwinPPC32)!
362?
363      </programlisting>
364     
365      <para>The ccl shell script passes all of its arguments to the
366      &CCL; kernel.  See <xref linkend="Invocation"/> for more
367      information about these arguments.  When invoked this way, the
368      Lisp should be able to initialize the <literal>"ccl:"</literal>
369      logical host so that its translations refer to the
370      <literal>"ccl"</literal> directory. To test this, you can call
371      <literal>probe-file</literal> in &CCL;'s read-eval-print
372      loop:</para>
373      <programlisting>
374? (probe-file "ccl:level-1;level-1.lisp")  ;returns the physical pathname of the file
375#P"/Users/alms/my_lisp_stuff/ccl/level-1/level-1.lisp"
376      </programlisting>
377    </sect2>
378
379    <!-- ***************************************************** -->
380    <sect2 id="Invocation">
381          <title>Invocation</title>
382          <para>Assuming that the shell script is properly installed, it can be used to invoke &CCL; from a shell prompt:
383            <programlisting>
384shell&gt;<replaceable>ccl</replaceable> <emphasis>args</emphasis>
385            </programlisting>
386            <literal>ccl</literal> runs a 32-bit session;
387            <literal>ccl64</literal> runs a 64-bit session.
388          </para>
389    </sect2>
390  </sect1>
391
392  <!-- ============================================================ -->
393  <sect1 id="Personal-Customization-with-the-Init-File">
394        <title>Personal Customization with the Init File</title>
395    <para>By default &CCL; tries to load the file
396      <literal>"home:ccl-init.lisp"</literal> or the compiled
397      <literal>"home:ccl-init.fasl"</literal> upon starting up.
398      &CCL; does this by executing <literal>(load
399      "home:ccl-init")</literal>.  If it's unable to load the file
400      (for example because the file doesn't exist), &CCL; doesn't
401      signal an error or warning, it just completes its startup
402      normally.</para>
403    <para>
404      On Unix systems, if <literal>"ccl-init.lisp"</literal> is not
405      present, &CCL; will look for <literal>".ccl-init.lisp"</literal>
406      (post 1.2 versions only).
407    </para>
408    <para>The <literal>"home:"</literal> prefix to the filename is a
409      Common Lisp logical host, which &CCL; initializes to refer to
410      your home directory. &CCL; therefore looks for either of the
411      files
412      <literal>~/ccl-init.lisp</literal> or
413      <literal>~/ccl-init.fasl</literal>.</para>
414    <para>Because the init file is loaded the same way as normal Lisp
415      code is, you can put anything you want in it.  For example, you
416      can change the working directory, and load packages that you use
417      frequently.</para>
418    <para>To suppress the loading of this init-file, invoke &CCL; with the
419      <literal>--no-init</literal> option.</para>
420  </sect1>
421
422  <!-- ============================================================ -->
423  <sect1 id="Command-Line-Options">
424        <title>Command Line Options</title>
425    <para>When using &CCL; from the command line, the following
426      options may be used to modify its behavior.  The exact set of
427      &CCL; command-line arguments may vary per platform and
428      slowly changes over time.  The current set of command line
429      options may be retrieved by using the
430      <literal>--help</literal> option.</para>
431        <itemizedlist>
432          <listitem>
433            <para><literal>-h</literal> (or
434              <literal>--help</literal>).  Provides a definitive (if
435              somewhat terse) summary of the command line options
436              accepted by the &CCL; implementation and then
437              exits.</para>
438          </listitem>
439
440          <listitem>
441            <para><literal>-V</literal> (or
442              <literal>--version</literal>).  Prints the version of
443              &CCL; then exits.  The version string is the same value
444              that is returned by
445              <function>LISP-IMPLEMENTATION-VERSION</function>.</para>
446          </listitem>
447
448          <listitem>
449            <para><literal>-K</literal>
450              <parameter>character-encoding-name</parameter> (or
451              <literal>--terminal-encoding</literal>
452              <parameter>character-encoding-name</parameter>).
453              Specifies the character encoding to use for
454              <varname>*TERMINAL-IO*</varname> (see <xref
455                                                       linkend="Character-Encodings"/>).  Specifically, the
456              <parameter>character-encoding-name</parameter> string
457              is uppercased and interned in the KEYWORD package. If an
458              encoding named by that keyword exists,
459              <varname>CCL:*TERMINAL-CHARACTER-ENCODING-NAME*</varname> is set to the name
460              of that encoding.   <varname>CCL:*TERMINAL-CHARACTER-ENCODING-NAME*</varname> defaults to <literal>NIL</literal>, which
461              is a synonym for <literal>:ISO-8859-1</literal>.</para>
462            <para>For example:
463              <programlisting>
464<![CDATA[shell> ccl -K utf-8]]>
465              </programlisting>
466              has the effect of making the standard CL streams use
467              <literal>:UTF-8</literal> as their character
468              encoding.</para>
469          </listitem>
470
471          <listitem>
472            <para><literal>-n</literal> (or
473              <literal>--no-init</literal>). If this option is given, the
474              init file is not loaded.  This is useful if &CCL; is being
475              invoked by a shell script that should not be affected by
476              whatever customizations a user might have in place.</para>
477          </listitem>
478
479          <listitem>
480            <para><literal>-e</literal> <parameter>form</parameter>
481              (or <literal>--eval</literal>). An expression is read (via
482              <function>READ-FROM-STRING</function>) from the string
483              <parameter>form</parameter> and evaluated. If
484              <parameter>form</parameter> contains shell metacharacters,
485              it may be necessary to escape or quote them to prevent the
486              shell from interpreting them.</para>
487          </listitem>
488
489          <listitem>
490            <para><literal>-l</literal> <parameter>path</parameter>
491              (or <literal>--load</literal>
492              <parameter>path</parameter>). Loads file specified by
493              <parameter>path</parameter>.</para>
494          </listitem>
495
496          <listitem>
497            <para><literal>-T</literal> <parameter>n</parameter> (or
498              <literal>--set-lisp-heap-gc-threshold</literal>
499              <parameter>n</parameter>).  Sets the Lisp gc threshold to
500              <parameter>n</parameter>. (see <xref
501                                                linkend="GC-Page-reclamation-policy"/></para>
502          </listitem>
503
504          <listitem>
505            <para><literal>-Q</literal> (or
506              <literal>--quiet</literal>). Suppresses printing of
507              heralds and prompts when the <literal>--batch</literal>
508              command line option is specified.</para>
509          </listitem>
510
511          <listitem>
512            <para><literal>-R</literal> <parameter>n</parameter> (or
513              <literal>--heap-reserve</literal>). Reserves
514              <parameter>n</parameter> bytes for heap expansion.  The
515              default is <literal> 549755813888</literal>.  (see <xref
516                                                                    linkend="Heap-space-allocation"/>)</para>
517          </listitem>
518
519          <listitem>
520            <para><literal>-S</literal> <parameter>n</parameter> (or
521              <literal>--stack-size</literal> <parameter>n</parameter>). Sets the size of the
522              initial control stack to <parameter>n</parameter>. (see <xref
523                                                                         linkend="Thread-Stack-Sizes"/>)</para>
524          </listitem>
525
526          <listitem>
527            <para><literal>-Z</literal> <parameter>n</parameter> (or
528              <literal>--thread-stack-size</literal>
529              <parameter>n</parameter>). Sets the size of the first
530              thread's stack to <parameter>n</parameter>. (see <xref
531                                                                  linkend="Thread-Stack-Sizes"/>)</para>
532          </listitem>
533
534          <listitem>
535            <para><literal>-b</literal> (or <literal>--batch</literal>). Execute in "batch mode". End-of-file
536              from <varname>*STANDARD-INPUT*</varname> causes &CCL; to exit, as do attempts to
537              enter a break loop.</para>
538          </listitem>
539
540          <listitem>
541            <para><literal>--no-sigtrap</literal> An obscure option for running under GDB.</para>
542          </listitem>
543
544          <listitem>
545            <para><literal>-I</literal>
546              <parameter>image-name</parameter> (or
547              <literal>--image-name</literal>
548              <parameter>image-name</parameter>). Specifies the image
549              name for the kernel to load.  Defaults to the kernel name
550              with ".image" appended.</para>
551          </listitem>
552        </itemizedlist>
553
554    <para>The <literal>--load</literal> and
555      <literal>--eval</literal> options can each be provided
556      multiple times.  They're executed in the order specified on
557      the command line, after the init file (if there is one) is
558      loaded and before the toplevel read-eval-print loop is
559      entered.</para>
560  </sect1>
561
562  <!-- ============================================================ -->
563  <sect1 id="Using-CCL-with-GNU-Emacs-and-SLIME">
564    <title>Using &CCL; with GNU Emacs and SLIME</title>
565    <para>A very common way to use &CCL; is to run it within the
566      GNU Emacs editor, using a Lisp interface called SLIME ("Superior
567      Lisp Interaction Mode for Emacs"). SLIME is an Emacs package
568      designed to provide good support within Emacs for any of several
569      Common Lisp implementations; one of the supported
570      implementations is &CCL;. This page describes how you can
571      download SLIME and set it up to work with your &CCL;
572      installation.</para>
573    <para>Why use SLIME? With SLIME, you can do the following things from within
574      an Emacs editing session:</para>
575    <itemizedlist>
576      <listitem><para>run and control Lisp</para></listitem>
577      <listitem><para>evaluate, compile, and load files or expressions</para></listitem>
578      <listitem><para>macroexpand expressions</para></listitem>
579      <listitem><para>fetch documentation and source code for Lisp symbols</para></listitem>
580      <listitem><para>autocomplete symbols and package names</para></listitem>
581      <listitem><para>cross-reference function calls</para></listitem>
582      <listitem><para>examine stack traces and debug errors</para></listitem>
583     
584    </itemizedlist>
585    <para>For complete information about SLIME, see the
586      SLIME <ulink url="http://common-lisp.net/project/slime/">home
587      page</ulink>. The SLIME home page provides up-to-date downloads,
588      plus documentation, tutorials, and instructional
589      screencasts.</para>
590
591    <!-- ***************************************************** -->
592    <sect2 id="Assumptions-and-Requirements">
593          <title>Assumptions and Requirements</title>
594      <para>In order to simplify these instructions, we'll make
595        several assumptions about your system. Specifically, we
596        assume:</para>
597      <itemizedlist>
598        <listitem>
599              <para>You have a working installation of GNU Emacs. If you
600                don't have a working copy of GNU Emacs, see the web page on
601                <ulink url="http://www.gnu.org/software/emacs/#Obtaining">obtaining
602                Emacs</ulink>.  If you prefer to use XEmacs instead of GNU
603                Emacs, these instructions should still work; SLIME supports
604                XEmacs Version21. Mac OS X includes an Emacs installation.
605                If you want to look into different versions, you can check
606                out theEmacsWiki, which maintains a
607                page, EmacsForMacOS, that provides much more information
608                about using Emacs on the Mac.</para>
609          <para>A popular version of Emacs among Mac users is
610            <ulink url="http://aquamacs.org/">Aquamacs</ulink>. This
611            application is a version of GNU Emacs with a number of
612            customizations meant to make it behave more like a
613            standard Macintosh application, with windows, a menubar,
614            etc.  Aquamacs includes SLIME; if you like Aquamacs then
615            you can use SLIME right away, without getting and
616            installing it separately. You just need to tell SLIME
617            where to find your installation of &CCL;.</para>
618            </listitem>
619        <listitem>
620          <para>You have a working copy of &CCL;, installed in
621            <literal>"~/ccl"</literal>If you prefer to install
622            &CCL; in some directory other
623            than<literal>"~/ccl"</literal> then these
624            instructions still work, but you must remember to use your
625            path to your ccl directory instead of the one that we give
626            here.</para>
627        </listitem>
628        <listitem>
629          <para>You install emacs add-ons in the folder
630            <literal>"~/emacs/site/"</literal>If this directory
631            doesn't exist on your system, you can just create it.If
632            you prefer to install Emacs add-ons in some place other
633            than<literal>"~/emacs/site/"</literal> then you must
634            remember to use your path to Emacs add-ons in place of
635            ours.</para>
636        </listitem>
637       
638      </itemizedlist>
639    </sect2>
640
641    <!-- ***************************************************** -->
642    <sect2 id="Getting_Slime"><title>Getting SLIME</title>       
643
644      <para>You can get SLIME from the SLIME Home Page. Stable
645        releases and CVS snapshots are available as archive files, or
646        you can follow the instructions on the SLIME Home Page to
647        check out the latest version from their CVS repository.</para>
648
649      <para>It's worth noting that stable SLIME releases happen very
650        seldom, but the SLIME developers often make changes and
651        improvements that are available through CVS updates. If you
652        asked the SLIM developers, they would most likely recommend
653        that you get SLIME from their CVS repository and update it
654        frequently.</para>
655
656      <para>Whether you get it from CVS, or download and unpack one
657        of the available archives, you should end up with a folder
658        named "slime" that contains the SLIME distribution.</para>
659    </sect2>
660
661    <!-- ***************************************************** -->
662    <sect2 id="installing-slime"><title>Installing SLIME</title> 
663
664      <para>Once you have the "slime" folder described in the previous
665        section, installation is a simple matter of copying the folder
666        to the proper place. You can drag it into the "~/emacs/site/"
667        folder, or you can use a terminal command to copy it
668        there. For example, assuming your working directory contains
669        the unpacked "slime" folder:</para> <para><literal>$ cp -R
670        slime ~/emacs/site/</literal></para> <para>That's all it
671        takes.</para>
672
673    </sect2>
674
675    <!-- ***************************************************** -->
676    <sect2 id="Telling-Emacs-About-SLIME">
677          <title>Telling Emacs About SLIME</title>
678      <para> Once SLIME and &CCL; are installed, you just need to
679        add a line to your "~/.emacs" file that tells SLIME where to
680        find the script that runs &CCL;:</para>
681      <para><literal>(setq inferior-lisp-program "~/ccl/scripts/ccl64")</literal></para>
682      <para>or</para>
683      <para><literal>(setq inferior-lisp-program "~/ccl/scripts/ccl")</literal></para>
684      <warning>
685        <para>Aquamacs users should add this line to the file "~/Library/Preferences/Aquamacs Emacs/Preferences.el".</para>
686      </warning>
687    </sect2>
688
689    <!-- ***************************************************** -->
690    <sect2 id="Running-CCL-with-SLIME">
691          <title>Running &CCL; with SLIME</title>
692      <para>Once the preparations in the previous section are
693        complete, exit Emacs and restart it, to ensure that it reads
694        the changes you made in your ".emacs" file (alternatively, you
695        could tell Emacs to reload the ".emacs" file). If all went
696        well, you should now be ready to run &CCL; using
697        SLIME.</para>
698      <para>To run &CCL;, execute the command "M-x slime". SLIME
699        should start an &CCL; session in a new buffer.  (If you are
700        unfamiliar with the Emacs notation "M-x command", see the GNU
701        Emacs FAQ; specifically, take a look at questions 1, 2, and
702        128.)</para>
703    </sect2>
704
705    <!-- ***************************************************** -->
706    <sect2 id="What-if-a-New-Version-of-CCL-Breaks-SLIME-">
707          <title>What if a New Version of &CCL; Breaks SLIME?</title>
708          <para>Sometimes you'll get a new version of &CCL;, set up
709            Emacs to use it with SLIME, and SLIME will fail. Most likely
710            what has happened is that the new version of &CCL; has a
711            change in the output files produced by the compiler (&CCL;
712            developers will say "the fasl version has changed." fasl
713            stands for "fast load" aka compiled files). This
714            problem is easy to fix: just delete the existing SLIME fasl
715            files. The next time you launch Emacs and start SLIME, it will
716            automatically recompile the Lisp files, and that should fix
717            the problem.</para>
718      <para>SLIME's load process stores its fasl files in a hidden
719        folder inside your home folder. The path is</para>
720      <para><literal>~/.slime/fasl</literal></para>
721      <para>You can use a shell command to remove the fasl files, or
722        remove them using your system's file browser.</para>
723      <para><emphasis role="bold">Note for Macintosh Users:</emphasis> 
724            The leading "." character in the ".slime" folder's name
725            prevents the Finder from showing this folder to you. If you
726            use the "Go To Folder" menu item in the Finder's "Go" menu,
727            you can type in "~/.slime" and the Finder will show it to
728            you. You can then drag the "fasl" folder to the trash.
729          </para>
730    </sect2>
731
732    <!-- ***************************************************** -->
733    <sect2 id="Known-Bugs">
734          <title>Known Bugs</title>
735          <para>SLIME has not been updated to account for recent changes
736            made in &CCL; to support x86-64 processors. You may run into
737            bugs running on those platforms.</para>
738      <para>The SLIME backtrace sometimes shows incorrect information.</para>
739      <para><literal>return-from-frame</literal> and
740        <literal>apply-in-frame</literal> do not work reliably.  (If
741        they work at all, it's pure luck.)</para>
742      <para>Some versions of Emacs on the Macintosh may have trouble
743        finding the shell script that runs &CCL; unless you specify
744        a full path to it. See the above section "Telling Emacs About
745        SLIME" to learn how to specify the path to the shell
746        script.</para>
747      <para>For more help with &CCL; on Mac OS X, consult the &CCL;
748        mailing lists. You can find information about the mailing
749        lists on the
750        &CCL; <ulink url="http://trac.clozure.com/openmcl">wiki</ulink>.</para>
751    </sect2>
752  </sect1>
753
754  <!-- ============================================================ -->
755  <sect1 id="Example-Programs">
756    <title>Example Programs</title>
757    <para>A number (ok, a <emphasis>small</emphasis> number), of
758    example programs are distributed in the "ccl:examples;" directory
759    of the source distribution. See the README-OPENMCL-EXAMPLES text
760    file in that directory for information about prerequisites and
761    usage.</para>
762    <para>Some of the example programs are derived from C examples
763      in textbooks, etc.; in those cases, the original author and work
764      are cited in the source code.</para>
765    <para>Unless the original author or contributor claims other
766      rights, you're free to incorporate any of this example code or
767      derivative thereof in any of your own works without
768      restriction. In doing so, you agree that the code was provided
769      "as is", and that no other party is legally or otherwise
770      responsible for any consequences of your decision to use
771      it.</para>
772    <para>If you've developed &CCL; examples that you'd like to see
773      added to the distribution, please send mail to the &CCL; mailing
774      lists. Any such contributions would be welcome and appreciated
775      (as would bug fixes and improvements to the existing
776      examples.)</para>
777  </sect1>
778</chapter>
Note: See TracBrowser for help on using the repository browser.