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

Last change on this file since 10218 was 10218, checked in by gb, 13 years ago

Fix typo in URL for 1.2.

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