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

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

Note need for C compiler toolchain in order to rebuild the lisp.

File size: 35.8 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 XP and later 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>linuxx86</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>linuxx86</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
238        <para>
239          If you don't have a C compiler toolchain installed, the
240          <literal>rebuild-ccl</literal> will not work.  Please
241          refer to <xref linkend="building-ccl-from-source"/> for
242          addtional details.
243        </para>
244        <sect3 id="Checking-Subversion-Installation"><title>Checking Subversion Installation</title>
245      <para>If <literal>svn co</literal> doesn't work, then make sure
246      that Subversion is installed on your system.  Bring up a command
247      line shell and type:
248        <programlisting>
249          <![CDATA[
250shell> svn]]>
251        </programlisting> 
252        If Subversion is installed, you will see something like:
253        <programlisting>
254          <![CDATA[
255Type 'svn help' for usage]]>
256        </programlisting>
257        If Subversion is not installed, you will see something
258        like:
259        <programlisting>
260          <![CDATA[
261-bash: svn: command not found]]>
262        </programlisting>
263        If Subversion is not installed, you'll need to figure out how
264        to install it on your OS. You can find information about
265        obtaining and installing Subversion at
266        the <ulink url="http://subversion.tigris.org/project_packages.html">Subversion
267        Packages page</ulink>.</para></sect3>
268
269    </sect2>
270
271    <!-- ***************************************************** -->
272    <sect2 id="obtaining-via-tarballs"><title>Tarballs</title>
273      <para>Tarballs are available at <ulink
274      url="ftp://clozure.com/pub/release/1.3/"/>.  Download and extract
275      one on your local disk.  Then edit the &CCL; shell script to set
276      the value of <varname>CCL_DEFAULT_DIRECTORY</varname> and start
277      up the appropriate &CCL; kernel. See <xref
278      linkend="The-ccl-Shell-Script"/> for more information about the
279      &CCL; shell scripts.</para>
280    </sect2>
281  </sect1>
282
283  <!-- ============================================================ -->
284  <sect1 id="command-line-setup"><title>Command Line Set Up</title>
285    <para>Sometimes it's convenient to use &CCL; from a Unix
286      shell command line.  This is especially true when using &CCL;
287      as a way to run Common Lisp utilities.</para>
288
289    <!-- ***************************************************** -->
290    <sect2 id="The-ccl-Shell-Script"><title>The ccl Shell Script</title>
291      <para>&CCL; needs to be able to find the
292        <literal>ccl</literal> directory in order to support features
293        such as <literal>require</literal> and
294        <literal>provide</literal>, access to foreign interface
295        information (see <link linkend="The-Interface-Database">The
296        Interface Database</link>) and the Lisp build process (see
297        <link linkend="Building-CCL">Building &CCL; from its Source
298        Code</link>). Specifically, it needs to set up logical
299        pathname translations for the <literal>"ccl:"</literal>
300        logical host.  If this logical host isn't defined (or isn't
301        defined correctly), some things might work, some things might
302        not, and it'll generally be hard to invoke and use &CCL;
303        productively.</para>
304
305      <para>&CCL; uses the value of the environment variable
306        <literal>CCL_DEFAULT_DIRECTORY</literal> to determine the
307        filesystem location of the <literal>ccl</literal> directory;
308        the ccl shell script is intended to provide a way to
309        invoke &CCL; with that environment variable set
310        correctly.</para>
311      <para>There are two versions of the shell script:
312        <literal>"ccl/scripts/ccl"</literal> is used to invoke
313        32-bit implementations of &CCL; and
314        <literal>"ccl/scripts/ccl64"</literal> is used to invoke
315        64-bit implementations.</para>
316      <para>To use the script:</para>
317      <orderedlist>
318        <listitem>
319          <para>Copy the script to a directory that is on your
320          <varname>PATH</varname>.  This is often
321          <literal>/usr/local/bin</literal> or
322          <literal>~/bin</literal>.  It is better to do this than to
323          add <literal>ccl/scripts</literal> to your
324          <varname>PATH</varname>, because the script needs to be edited,
325          and editing it in-place means that Subversion sees the script as
326          modified..</para>
327        </listitem>
328        <listitem>
329          <para>Edit the definition of
330            <literal>CCL_DEFAULT_DIRECTORY</literal> near the
331            beginning of the shell script so that it refers to
332            your <literal>ccl</literal> directory.  Alternately, set
333            the value of the <literal>CCL_DEFAULT_DIRECTORY</literal>
334            environment variable in your .cshrc, .tcshrc,
335            .bashrc,.bash_profile, .MacOSX/environment.plist, or
336            wherever you usually set environment variables.  If there
337            is an existing definition of the variable, the ccl
338            script will not override it. The shell script sets a local
339            variable (<literal>OPENMCL_KERNEL</literal>) to the
340            standard name of the &CCL; kernel approprate for the
341            platform, as determined by 'uname -s'. You might prefer to
342            set this variable manually in the shell script.</para>
343        </listitem>
344
345        <listitem>
346          <para>Ensure that the shell script is executable, for
347            example:</para> 
348          <para><literal>$ chmod +x
349            ~/ccl/ccl/scripts/ccl64</literal></para> 
350          <para>This command grants execute permission to the named
351            script. If you are using a 32-bit platform, substitute
352            "ccl" in place of "ccl64".
353            <warning>
354                  <para>The above command won't work if you are not the
355                    owner of the installed copy of &CCL;. In that case,
356                    you can use the "sudo" command like this:</para>
357              <para><literal>$ sudo chmod +x
358                  ~/ccl/ccl/scripts/ccl64</literal></para>
359              <para>Give your password when prompted.</para>
360              <para>If the "sudo" command doesn't work, then you are
361                not an administrator on the system you're using, and you
362                don't have the appropriate "sudo" permissions. In that
363                case you'll need to get help from the system's
364                administrator.</para>
365          </warning></para>
366        </listitem>
367      </orderedlist>
368
369      <para>Note that most people won't need both
370      <literal>ccl</literal> and <literal>ccl64</literal> scripts.
371      You only need both if you sometimes run 32-bit &CCL; and
372      sometimes run 64-bit &CCL;.  You can rename the script that
373      you use to whatever you want.  For example, if you are on a
374      64-bit system, and you only use &CCL; in 64-bit mode, then
375      you can rename  <literal>ccl64</literal> to
376      <literal>ccl</literal> so that you only need to type
377      "<literal>ccl</literal>" to run it.</para>
378
379      <para>Once this is done, it should be possible to invoke &CCL;
380        by typing <literal>ccl</literal>
381        or <literal>ccl64</literal> at a shell prompt:</para>
382      <programlisting>
383&gt; ccl [args ...]
384Welcome to &CCL; Version 1.2 (DarwinPPC32)!
385?
386      </programlisting>
387     
388      <para>The ccl shell script passes all of its arguments to the
389      &CCL; kernel.  See <xref linkend="Invocation"/> for more
390      information about these arguments.  When invoked this way, the
391      Lisp should be able to initialize the <literal>"ccl:"</literal>
392      logical host so that its translations refer to the
393      <literal>"ccl"</literal> directory. To test this, you can call
394      <literal>probe-file</literal> in &CCL;'s read-eval-print
395      loop:</para>
396      <programlisting>
397? (probe-file "ccl:level-1;level-1.lisp")  ;returns the physical pathname of the file
398#P"/Users/alms/my_lisp_stuff/ccl/level-1/level-1.lisp"
399      </programlisting>
400    </sect2>
401
402    <!-- ***************************************************** -->
403    <sect2 id="Invocation">
404          <title>Invocation</title>
405          <para>Assuming that the shell script is properly installed, it can be used to invoke &CCL; from a shell prompt:
406            <programlisting>
407shell&gt;<replaceable>ccl</replaceable> <emphasis>args</emphasis>
408            </programlisting>
409            <literal>ccl</literal> runs a 32-bit session;
410            <literal>ccl64</literal> runs a 64-bit session.
411          </para>
412    </sect2>
413  </sect1>
414
415  <!-- ============================================================ -->
416  <sect1 id="Personal-Customization-with-the-Init-File">
417        <title>Personal Customization with the Init File</title>
418    <para>By default &CCL; tries to load the file
419      <literal>"home:ccl-init.lisp"</literal> or the compiled
420      <literal>"home:ccl-init.fasl"</literal> upon starting up.
421      &CCL; does this by executing <literal>(load
422      "home:ccl-init")</literal>.  If it's unable to load the file
423      (for example because the file doesn't exist), &CCL; doesn't
424      signal an error or warning, it just completes its startup
425      normally.</para>
426    <para>
427      On Unix systems, if <literal>"ccl-init.lisp"</literal> is not
428      present, &CCL; will look for <literal>".ccl-init.lisp"</literal>
429      (post 1.2 versions only).
430    </para>
431    <para>The <literal>"home:"</literal> prefix to the filename is a
432      Common Lisp logical host, which &CCL; initializes to refer to
433      your home directory. &CCL; therefore looks for either of the
434      files
435      <literal>~/ccl-init.lisp</literal> or
436      <literal>~/ccl-init.fasl</literal>.</para>
437    <para>Because the init file is loaded the same way as normal Lisp
438      code is, you can put anything you want in it.  For example, you
439      can change the working directory, and load packages that you use
440      frequently.</para>
441    <para>To suppress the loading of this init-file, invoke &CCL; with the
442      <literal>--no-init</literal> option.</para>
443  </sect1>
444
445  <!-- ============================================================ -->
446  <sect1 id="Command-Line-Options">
447        <title>Command Line Options</title>
448    <para>When using &CCL; from the command line, the following
449      options may be used to modify its behavior.  The exact set of
450      &CCL; command-line arguments may vary per platform and
451      slowly changes over time.  The current set of command line
452      options may be retrieved by using the
453      <literal>--help</literal> option.</para>
454        <itemizedlist>
455          <listitem>
456            <para><literal>-h</literal> (or
457              <literal>--help</literal>).  Provides a definitive (if
458              somewhat terse) summary of the command line options
459              accepted by the &CCL; implementation and then
460              exits.</para>
461          </listitem>
462
463          <listitem>
464            <para><literal>-V</literal> (or
465              <literal>--version</literal>).  Prints the version of
466              &CCL; then exits.  The version string is the same value
467              that is returned by
468              <function>LISP-IMPLEMENTATION-VERSION</function>.</para>
469          </listitem>
470
471          <listitem>
472            <para><literal>-K</literal>
473              <parameter>character-encoding-name</parameter> (or
474              <literal>--terminal-encoding</literal>
475              <parameter>character-encoding-name</parameter>).
476              Specifies the character encoding to use for
477              <varname>*TERMINAL-IO*</varname> (see <xref
478                                                       linkend="Character-Encodings"/>).  Specifically, the
479              <parameter>character-encoding-name</parameter> string
480              is uppercased and interned in the KEYWORD package. If an
481              encoding named by that keyword exists,
482              <varname>CCL:*TERMINAL-CHARACTER-ENCODING-NAME*</varname> is set to the name
483              of that encoding.   <varname>CCL:*TERMINAL-CHARACTER-ENCODING-NAME*</varname> defaults to <literal>NIL</literal>, which
484              is a synonym for <literal>:ISO-8859-1</literal>.</para>
485            <para>For example:
486              <programlisting>
487<![CDATA[shell> ccl -K utf-8]]>
488              </programlisting>
489              has the effect of making the standard CL streams use
490              <literal>:UTF-8</literal> as their character
491              encoding.</para>
492          </listitem>
493
494          <listitem>
495            <para><literal>-n</literal> (or
496              <literal>--no-init</literal>). If this option is given, the
497              init file is not loaded.  This is useful if &CCL; is being
498              invoked by a shell script that should not be affected by
499              whatever customizations a user might have in place.</para>
500          </listitem>
501
502          <listitem>
503            <para><literal>-e</literal> <parameter>form</parameter>
504              (or <literal>--eval</literal>). An expression is read (via
505              <function>READ-FROM-STRING</function>) from the string
506              <parameter>form</parameter> and evaluated. If
507              <parameter>form</parameter> contains shell metacharacters,
508              it may be necessary to escape or quote them to prevent the
509              shell from interpreting them.</para>
510          </listitem>
511
512          <listitem>
513            <para><literal>-l</literal> <parameter>path</parameter>
514              (or <literal>--load</literal>
515              <parameter>path</parameter>). Loads file specified by
516              <parameter>path</parameter>.</para>
517          </listitem>
518
519          <listitem>
520            <para><literal>-T</literal> <parameter>n</parameter> (or
521              <literal>--set-lisp-heap-gc-threshold</literal>
522              <parameter>n</parameter>).  Sets the Lisp gc threshold to
523              <parameter>n</parameter>. (see <xref
524                                                linkend="GC-Page-reclamation-policy"/></para>
525          </listitem>
526
527          <listitem>
528            <para><literal>-Q</literal> (or
529              <literal>--quiet</literal>). Suppresses printing of
530              heralds and prompts when the <literal>--batch</literal>
531              command line option is specified.</para>
532          </listitem>
533
534          <listitem>
535            <para><literal>-R</literal> <parameter>n</parameter> (or
536              <literal>--heap-reserve</literal>). Reserves
537              <parameter>n</parameter> bytes for heap expansion.  The
538              default is <literal> 549755813888</literal>.  (see <xref
539                                                                    linkend="Heap-space-allocation"/>)</para>
540          </listitem>
541
542          <listitem>
543            <para><literal>-S</literal> <parameter>n</parameter> (or
544              <literal>--stack-size</literal> <parameter>n</parameter>). Sets the size of the
545              initial control stack to <parameter>n</parameter>. (see <xref
546                                                                         linkend="Thread-Stack-Sizes"/>)</para>
547          </listitem>
548
549          <listitem>
550            <para><literal>-Z</literal> <parameter>n</parameter> (or
551              <literal>--thread-stack-size</literal>
552              <parameter>n</parameter>). Sets the size of the first
553              thread's stack to <parameter>n</parameter>. (see <xref
554                                                                  linkend="Thread-Stack-Sizes"/>)</para>
555          </listitem>
556
557          <listitem>
558            <para><literal>-b</literal> (or <literal>--batch</literal>). Execute in "batch mode". End-of-file
559              from <varname>*STANDARD-INPUT*</varname> causes &CCL; to exit, as do attempts to
560              enter a break loop.</para>
561          </listitem>
562
563          <listitem>
564            <para><literal>--no-sigtrap</literal> An obscure option for running under GDB.</para>
565          </listitem>
566
567          <listitem>
568            <para><literal>-I</literal>
569              <parameter>image-name</parameter> (or
570              <literal>--image-name</literal>
571              <parameter>image-name</parameter>). Specifies the image
572              name for the kernel to load.  Defaults to the kernel name
573              with ".image" appended.</para>
574          </listitem>
575        </itemizedlist>
576
577    <para>The <literal>--load</literal> and
578      <literal>--eval</literal> options can each be provided
579      multiple times.  They're executed in the order specified on
580      the command line, after the init file (if there is one) is
581      loaded and before the toplevel read-eval-print loop is
582      entered.</para>
583  </sect1>
584
585  <!-- ============================================================ -->
586  <sect1 id="Using-CCL-with-GNU-Emacs-and-SLIME">
587    <title>Using &CCL; with GNU Emacs and SLIME</title>
588    <para>A very common way to use &CCL; is to run it within the
589      GNU Emacs editor, using a Lisp interface called SLIME ("Superior
590      Lisp Interaction Mode for Emacs"). SLIME is an Emacs package
591      designed to provide good support within Emacs for any of several
592      Common Lisp implementations; one of the supported
593      implementations is &CCL;. This page describes how you can
594      download SLIME and set it up to work with your &CCL;
595      installation.</para>
596    <para>Why use SLIME? With SLIME, you can do the following things from within
597      an Emacs editing session:</para>
598    <itemizedlist>
599      <listitem><para>run and control Lisp</para></listitem>
600      <listitem><para>evaluate, compile, and load files or expressions</para></listitem>
601      <listitem><para>macroexpand expressions</para></listitem>
602      <listitem><para>fetch documentation and source code for Lisp symbols</para></listitem>
603      <listitem><para>autocomplete symbols and package names</para></listitem>
604      <listitem><para>cross-reference function calls</para></listitem>
605      <listitem><para>examine stack traces and debug errors</para></listitem>
606     
607    </itemizedlist>
608    <para>For complete information about SLIME, see the
609      SLIME <ulink url="http://common-lisp.net/project/slime/">home
610      page</ulink>. The SLIME home page provides up-to-date downloads,
611      plus documentation, tutorials, and instructional
612      screencasts.</para>
613
614    <!-- ***************************************************** -->
615    <sect2 id="Assumptions-and-Requirements">
616          <title>Assumptions and Requirements</title>
617      <para>In order to simplify these instructions, we'll make
618        several assumptions about your system. Specifically, we
619        assume:</para>
620      <itemizedlist>
621        <listitem>
622              <para>You have a working installation of GNU Emacs. If you
623                don't have a working copy of GNU Emacs, see the web page on
624                <ulink url="http://www.gnu.org/software/emacs/#Obtaining">obtaining
625                Emacs</ulink>.  If you prefer to use XEmacs instead of GNU
626                Emacs, these instructions should still work; SLIME supports
627                XEmacs Version21. Mac OS X includes an Emacs installation.
628                If you want to look into different versions, you can check
629                out theEmacsWiki, which maintains a
630                page, EmacsForMacOS, that provides much more information
631                about using Emacs on the Mac.</para>
632          <para>A popular version of Emacs among Mac users is
633            <ulink url="http://aquamacs.org/">Aquamacs</ulink>. This
634            application is a version of GNU Emacs with a number of
635            customizations meant to make it behave more like a
636            standard Macintosh application, with windows, a menubar,
637            etc.  Aquamacs includes SLIME; if you like Aquamacs then
638            you can use SLIME right away, without getting and
639            installing it separately. You just need to tell SLIME
640            where to find your installation of &CCL;.</para>
641            </listitem>
642        <listitem>
643          <para>You have a working copy of &CCL;, installed in
644            <literal>"~/ccl"</literal>If you prefer to install
645            &CCL; in some directory other
646            than<literal>"~/ccl"</literal> then these
647            instructions still work, but you must remember to use your
648            path to your ccl directory instead of the one that we give
649            here.</para>
650        </listitem>
651        <listitem>
652          <para>You install emacs add-ons in the folder
653            <literal>"~/emacs/site/"</literal>If this directory
654            doesn't exist on your system, you can just create it.If
655            you prefer to install Emacs add-ons in some place other
656            than<literal>"~/emacs/site/"</literal> then you must
657            remember to use your path to Emacs add-ons in place of
658            ours.</para>
659        </listitem>
660       
661      </itemizedlist>
662    </sect2>
663
664    <!-- ***************************************************** -->
665    <sect2 id="Getting_Slime"><title>Getting SLIME</title>       
666
667      <para>You can get SLIME from the SLIME Home Page. Stable
668        releases and CVS snapshots are available as archive files, or
669        you can follow the instructions on the SLIME Home Page to
670        check out the latest version from their CVS repository.</para>
671
672      <para>It's worth noting that stable SLIME releases happen very
673        seldom, but the SLIME developers often make changes and
674        improvements that are available through CVS updates. If you
675        asked the SLIM developers, they would most likely recommend
676        that you get SLIME from their CVS repository and update it
677        frequently.</para>
678
679      <para>Whether you get it from CVS, or download and unpack one
680        of the available archives, you should end up with a folder
681        named "slime" that contains the SLIME distribution.</para>
682    </sect2>
683
684    <!-- ***************************************************** -->
685    <sect2 id="installing-slime"><title>Installing SLIME</title> 
686
687      <para>Once you have the "slime" folder described in the previous
688        section, installation is a simple matter of copying the folder
689        to the proper place. You can drag it into the "~/emacs/site/"
690        folder, or you can use a terminal command to copy it
691        there. For example, assuming your working directory contains
692        the unpacked "slime" folder:</para> <para><literal>$ cp -R
693        slime ~/emacs/site/</literal></para> <para>That's all it
694        takes.</para>
695
696    </sect2>
697
698    <!-- ***************************************************** -->
699    <sect2 id="Telling-Emacs-About-SLIME">
700          <title>Telling Emacs About SLIME</title>
701      <para> Once SLIME and &CCL; are installed, you just need to
702        add a line to your "~/.emacs" file that tells SLIME where to
703        find the script that runs &CCL;:</para>
704      <para><literal>(setq inferior-lisp-program "~/ccl/scripts/ccl64")</literal></para>
705      <para>or</para>
706      <para><literal>(setq inferior-lisp-program "~/ccl/scripts/ccl")</literal></para>
707      <warning>
708        <para>Aquamacs users should add this line to the file "~/Library/Preferences/Aquamacs Emacs/Preferences.el".</para>
709      </warning>
710    </sect2>
711
712    <!-- ***************************************************** -->
713    <sect2 id="Running-CCL-with-SLIME">
714          <title>Running &CCL; with SLIME</title>
715      <para>Once the preparations in the previous section are
716        complete, exit Emacs and restart it, to ensure that it reads
717        the changes you made in your ".emacs" file (alternatively, you
718        could tell Emacs to reload the ".emacs" file). If all went
719        well, you should now be ready to run &CCL; using
720        SLIME.</para>
721      <para>To run &CCL;, execute the command "M-x slime". SLIME
722        should start an &CCL; session in a new buffer.  (If you are
723        unfamiliar with the Emacs notation "M-x command", see the GNU
724        Emacs FAQ; specifically, take a look at questions 1, 2, and
725        128.)</para>
726    </sect2>
727
728    <!-- ***************************************************** -->
729    <sect2 id="What-if-a-New-Version-of-CCL-Breaks-SLIME-">
730          <title>What if a New Version of &CCL; Breaks SLIME?</title>
731          <para>Sometimes you'll get a new version of &CCL;, set up
732            Emacs to use it with SLIME, and SLIME will fail. Most likely
733            what has happened is that the new version of &CCL; has a
734            change in the output files produced by the compiler (&CCL;
735            developers will say "the fasl version has changed." fasl
736            stands for "fast load" aka compiled files). This
737            problem is easy to fix: just delete the existing SLIME fasl
738            files. The next time you launch Emacs and start SLIME, it will
739            automatically recompile the Lisp files, and that should fix
740            the problem.</para>
741      <para>SLIME's load process stores its fasl files in a hidden
742        folder inside your home folder. The path is</para>
743      <para><literal>~/.slime/fasl</literal></para>
744      <para>You can use a shell command to remove the fasl files, or
745        remove them using your system's file browser.</para>
746      <para><emphasis role="bold">Note for Macintosh Users:</emphasis> 
747            The leading "." character in the ".slime" folder's name
748            prevents the Finder from showing this folder to you. If you
749            use the "Go To Folder" menu item in the Finder's "Go" menu,
750            you can type in "~/.slime" and the Finder will show it to
751            you. You can then drag the "fasl" folder to the trash.
752          </para>
753    </sect2>
754
755    <!-- ***************************************************** -->
756    <sect2 id="Known-Bugs">
757          <title>Known Bugs</title>
758          <para>SLIME has not been updated to account for recent changes
759            made in &CCL; to support x86-64 processors. You may run into
760            bugs running on those platforms.</para>
761      <para>The SLIME backtrace sometimes shows incorrect information.</para>
762      <para><literal>return-from-frame</literal> and
763        <literal>apply-in-frame</literal> do not work reliably.  (If
764        they work at all, it's pure luck.)</para>
765      <para>Some versions of Emacs on the Macintosh may have trouble
766        finding the shell script that runs &CCL; unless you specify
767        a full path to it. See the above section "Telling Emacs About
768        SLIME" to learn how to specify the path to the shell
769        script.</para>
770      <para>For more help with &CCL; on Mac OS X, consult the &CCL;
771        mailing lists. You can find information about the mailing
772        lists on the
773        &CCL; <ulink url="http://trac.clozure.com/openmcl">wiki</ulink>.</para>
774    </sect2>
775  </sect1>
776
777  <!-- ============================================================ -->
778  <sect1 id="Example-Programs">
779    <title>Example Programs</title>
780    <para>A number (ok, a <emphasis>small</emphasis> number), of
781    example programs are distributed in the "ccl:examples;" directory
782    of the source distribution. See the README-OPENMCL-EXAMPLES text
783    file in that directory for information about prerequisites and
784    usage.</para>
785    <para>Some of the example programs are derived from C examples
786      in textbooks, etc.; in those cases, the original author and work
787      are cited in the source code.</para>
788    <para>Unless the original author or contributor claims other
789      rights, you're free to incorporate any of this example code or
790      derivative thereof in any of your own works without
791      restriction. In doing so, you agree that the code was provided
792      "as is", and that no other party is legally or otherwise
793      responsible for any consequences of your decision to use
794      it.</para>
795    <para>If you've developed &CCL; examples that you'd like to see
796      added to the distribution, please send mail to the &CCL; mailing
797      lists. Any such contributions would be welcome and appreciated
798      (as would bug fixes and improvements to the existing
799      examples.)</para>
800  </sect1>
801</chapter>
Note: See TracBrowser for help on using the repository browser.