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

Last change on this file since 12330 was 12330, checked in by rme, 11 years ago

Minor updates, mainly an attempt to provide id attributes for most (if
not all) chapter, sect1, and sect2 tags.

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