source: release/1.2/source/doc/src/install.xml @ 9200

Last change on this file since 9200 was 9200, checked in by gb, 12 years ago

synch with trunk

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