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

Last change on this file since 9071 was 9071, checked in by mikel, 12 years ago

mechanical and style edits in install and build chapters

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