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

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

added about.xml. many style edits and link repairs in build.xml and install.xml

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