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

Last change on this file since 10914 was 10914, checked in by rme, 12 years ago

On Unix systems, if "ccl-init" is not present, try to load ".ccl-init".
No longer try to load (or warn about) openmcl-init. Upate manual
to reflect these changes.

(ticket:337)

File size: 36.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  <!-- ============================================================ -->
16  <sect1><title>Releases and System Requirements</title>
17   
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>
23
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>
41
42    <para>A 64-bit version of &CCL; requires a 64-bit processor
43      running a 64-bit OS variant.</para>
44     
45    <para>There are ongoing efforts to port &CCL; to the Windows
46      operating system and to 32-bit x86 processors.</para>
47   
48    <para>Additional platform-specific information is given in the
49      following subsections.</para>
50
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>
58
59    <!-- ***************************************************** -->
60    <sect2><title>LinuxPPC</title> 
61     
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>
66
67    <!-- ***************************************************** -->
68    <sect2><title>Linux X8664</title> 
69
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>
88
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>
97
98    <!-- ***************************************************** -->
99    <sect2><title>DarwinPPC-MacOS-X</title>
100
101      <para> &CCL; runs under OS X versions 10.4 and 10.5 and requires
102      at least version 10.3.9</para>
103
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>
108
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>
115
116    <!-- ***************************************************** -->
117    <sect2><title>Darwinx8664-MacOS-X</title> <para>&CCL; runs on
118    64-bit DarwinX86 (Mac OS X on Intel).</para>
119
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>
127
128    </sect2>
129  </sect1>
130
131
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>
145
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>
150
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="ftp://clozure.com/pub/testing/"/> </para>
159
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>
174   
175
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>
186
187
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>
192
193        <programlisting>
194          <![CDATA[
195svn co http://svn.clozure.com/publicsvn/openmcl/trunk/darwinx8664/ccl]]>
196        </programlisting>
197
198        <para>To get the 1.2 version of &CCL; type:</para>
199        <programlisting>
200          <![CDATA[
201svn co http://svn.clozure.com/publicsvn/openmcl/release/1.2/darwinx8664/ccl]]>
202        </programlisting>
203
204       
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>
209
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>
217
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> 
222
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>
227
228        <programlisting>
229          <![CDATA[
230joe:ccl> ./dx86cl64
231Welcome to Clozure Common Lisp Version 1.2  (DarwinX8664)!
232? (rebuild-ccl :full t)
233
234<lots of compilation output>
235
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="http://subversion.tigris.org/project_packages.html">Subversion
262        Packages page</ulink>.</para></sect3>
263
264    </sect2>
265
266    <!-- ***************************************************** -->
267    <sect2><title>Tarballs</title>
268      <para>Tarballs are available at <ulink
269      url="ftp://clozure.com/pub/testing/"/>.  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>
277
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>
283
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>
299
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>
339
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>
363
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>
373
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)!
380?
381      </programlisting>
382     
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
393#P"/Users/alms/my_lisp_stuff/ccl/level-1/level-1.lisp"
394      </programlisting>
395    </sect2>
396
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>
409
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
415      <literal>"home:ccl-init.fasl"</literal> upon starting up.
416      &CCL; does this by executing <literal>(load
417      "home:ccl-init")</literal>.  If it's unable to load the file
418      (for example because the file doesn't exist), &CCL; doesn't
419      signal an error or warning, it just completes its startup
420      normally.</para>
421    <para>
422      On Unix systems, if <literal>"ccl-init.lisp"</literal> is not
423      present, &CCL; will look for <literal>".ccl-init.lisp"</literal>
424      (post 1.2 versions only).
425    </para>
426    <para>The <literal>"home:"</literal> prefix to the filename is a
427      Common Lisp logical host, which &CCL; initializes to refer to
428      your home directory. &CCL; therefore looks for either of the
429      files
430      <literal>~/ccl-init.lisp</literal> or
431      <literal>~/ccl-init.fasl</literal>.</para>
432    <para>Because the init file is loaded the same way as normal Lisp
433      code is, you can put anything you want in it.  For example, you
434      can change the working directory, and load packages that you use
435      frequently.</para>
436    <para>To suppress the loading of this init-file, invoke &CCL; with the
437      <literal>--no-init</literal> option.</para>
438  </sect1>
439
440  <!-- ============================================================ -->
441  <sect1 id="Command-Line-Options">
442        <title>Command Line Options</title>
443    <para>When using &CCL; from the command line, the following
444      options may be used to modify its behavior.  The exact set of
445      &CCL; command-line arguments may vary per platform and
446      slowly changes over time.  The current set of command line
447      options may be retrieved by using the
448      <literal>--help</literal> option.</para>
449        <itemizedlist>
450          <listitem>
451            <para><literal>-h</literal> (or
452              <literal>--help</literal>).  Provides a definitive (if
453              somewhat terse) summary of the command line options
454              accepted by the &CCL; implementation and then
455              exits.</para>
456          </listitem>
457
458          <listitem>
459            <para><literal>-V</literal> (or
460              <literal>--version</literal>).  Prints the version of
461              &CCL; then exits.  The version string is the same value
462              that is returned by
463              <function>LISP-IMPLEMENTATION-VERSION</function>.</para>
464          </listitem>
465
466          <listitem>
467            <para><literal>-K</literal>
468              <parameter>character-encoding-name</parameter> (or
469              <literal>--terminal-encoding</literal>
470              <parameter>character-encoding-name</parameter>).
471              Specifies the character encoding to use for
472              <varname>*TERMINAL-IO*</varname> (see <xref
473                                                       linkend="Character-Encodings"/>).  Specifically, the
474              <parameter>character-encoding-name</parameter> string
475              is uppercased and interned in the KEYWORD package. If an
476              encoding named by that keyword exists,
477              <varname>CCL:*TERMINAL-CHARACTER-ENCODING-NAME*</varname> is set to the name
478              of that encoding.   <varname>CCL:*TERMINAL-CHARACTER-ENCODING-NAME*</varname> defaults to <literal>NIL</literal>, which
479              is a synonym for <literal>:ISO-8859-1</literal>.</para>
480            <para>For example:
481              <programlisting>
482<![CDATA[shell> ccl -K utf-8]]>
483              </programlisting>
484              has the effect of making the standard CL streams use
485              <literal>:UTF-8</literal> as their character
486              encoding.</para>
487          </listitem>
488
489          <listitem>
490            <para><literal>-n</literal> (or
491              <literal>--no-init</literal>). If this option is given, the
492              init file is not loaded.  This is useful if &CCL; is being
493              invoked by a shell script that should not be affected by
494              whatever customizations a user might have in place.</para>
495          </listitem>
496
497          <listitem>
498            <para><literal>-e</literal> <parameter>form</parameter>
499              (or <literal>--eval</literal>). An expression is read (via
500              <function>READ-FROM-STRING</function>) from the string
501              <parameter>form</parameter> and evaluated. If
502              <parameter>form</parameter> contains shell metacharacters,
503              it may be necessary to escape or quote them to prevent the
504              shell from interpreting them.</para>
505          </listitem>
506
507          <listitem>
508            <para><literal>-l</literal> <parameter>path</parameter>
509              (or <literal>--load</literal>
510              <parameter>path</parameter>). Loads file specified by
511              <parameter>path</parameter>.</para>
512          </listitem>
513
514          <listitem>
515            <para><literal>-T</literal> <parameter>n</parameter> (or
516              <literal>--set-lisp-heap-gc-threshold</literal>
517              <parameter>n</parameter>).  Sets the Lisp gc threshold to
518              <parameter>n</parameter>. (see <xref
519                                                linkend="GC-Page-reclamation-policy"/></para>
520          </listitem>
521
522          <listitem>
523            <para><literal>-Q</literal> (or
524              <literal>--quiet</literal>). Suppresses printing of
525              heralds and prompts when the <literal>--batch</literal>
526              command line option is specified.</para>
527          </listitem>
528
529          <listitem>
530            <para><literal>-R</literal> <parameter>n</parameter> (or
531              <literal>--heap-reserve</literal>). Reserves
532              <parameter>n</parameter> bytes for heap expansion.  The
533              default is <literal> 549755813888</literal>.  (see <xref
534                                                                    linkend="Heap-space-allocation"/>)</para>
535          </listitem>
536
537          <listitem>
538            <para><literal>-S</literal> <parameter>n</parameter> (or
539              <literal>--stack-size</literal> <parameter>n</parameter>). Sets the size of the
540              initial control stack to <parameter>n</parameter>. (see <xref
541                                                                         linkend="Thread-Stack-Sizes"/>)</para>
542          </listitem>
543
544          <listitem>
545            <para><literal>-Z</literal> <parameter>n</parameter> (or
546              <literal>--thread-stack-size</literal>
547              <parameter>n</parameter>). Sets the size of the first
548              thread's stack to <parameter>n</parameter>. (see <xref
549                                                                  linkend="Thread-Stack-Sizes"/>)</para>
550          </listitem>
551
552          <listitem>
553            <para><literal>-b</literal> (or <literal>--batch</literal>). Execute in "batch mode". End-of-file
554              from <varname>*STANDARD-INPUT*</varname> causes &CCL; to exit, as do attempts to
555              enter a break loop.</para>
556          </listitem>
557
558          <listitem>
559            <para><literal>--no-sigtrap</literal> An obscure option for running under GDB.</para>
560          </listitem>
561
562          <listitem>
563            <para><literal>-I</literal>
564              <parameter>image-name</parameter> (or
565              <literal>--image-name</literal>
566              <parameter>image-name</parameter>). Specifies the image
567              name for the kernel to load.  Defaults to the kernel name
568              with ".image" appended.</para>
569          </listitem>
570        </itemizedlist>
571
572    <para>The <literal>--load</literal> and
573      <literal>--eval</literal> options can each be provided
574      multiple times.  They're executed in the order specified on
575      the command line, after the init file (if there is one) is
576      loaded and before the toplevel read-eval-print loop is
577      entered.</para>
578  </sect1>
579
580  <!-- ============================================================ -->
581  <sect1 id="Using-CCL-with-GNU-Emacs-and-SLIME">
582    <title>Using &CCL; with GNU Emacs and SLIME</title>
583    <para>A very common way to use &CCL; is to run it within the
584      GNU Emacs editor, using a Lisp interface called SLIME ("Superior
585      Lisp Interaction Mode for Emacs"). SLIME is an Emacs package
586      designed to provide good support within Emacs for any of several
587      Common Lisp implementations; one of the supported
588      implementations is &CCL;. This page describes how you can
589      download SLIME and set it up to work with your &CCL;
590      installation.</para>
591    <para>Why use SLIME? With SLIME, you can do the following things from within
592      an Emacs editing session:</para>
593    <itemizedlist>
594      <listitem><para>run and control Lisp</para></listitem>
595      <listitem><para>evaluate, compile, and load files or expressions</para></listitem>
596      <listitem><para>macroexpand expressions</para></listitem>
597      <listitem><para>fetch documentation and source code for Lisp symbols</para></listitem>
598      <listitem><para>autocomplete symbols and package names</para></listitem>
599      <listitem><para>cross-reference function calls</para></listitem>
600      <listitem><para>examine stack traces and debug errors</para></listitem>
601     
602    </itemizedlist>
603    <para>For complete information about SLIME, see the
604      SLIME <ulink url="http://common-lisp.net/project/slime/">home
605      page</ulink>. The SLIME home page provides up-to-date downloads,
606      plus documentation, tutorials, and instructional
607      screencasts.</para>
608
609    <!-- ***************************************************** -->
610    <sect2 id="Assumptions-and-Requirements">
611          <title>Assumptions and Requirements</title>
612      <para>In order to simplify these instructions, we'll make
613        several assumptions about your system. Specifically, we
614        assume:</para>
615      <itemizedlist>
616        <listitem>
617              <para>You have a working installation of GNU Emacs. If you
618                don't have a working copy of GNU Emacs, see the web page on
619                <ulink url="http://www.gnu.org/software/emacs/#Obtaining">obtaining
620                Emacs</ulink>.  If you prefer to use XEmacs instead of GNU
621                Emacs, these instructions should still work; SLIME supports
622                XEmacs Version21. Mac OS X includes an Emacs installation.
623                If you want to look into different versions, you can check
624                out theEmacsWiki, which maintains a
625                page, EmacsForMacOS, that provides much more information
626                about using Emacs on the Mac.</para>
627          <para>A popular version of Emacs among Mac users is
628            <ulink url="http://aquamacs.org/">Aquamacs</ulink>. This
629            application is a version of GNU Emacs with a number of
630            customizations meant to make it behave more like a
631            standard Macintosh application, with windows, a menubar,
632            etc.  Aquamacs includes SLIME; if you like Aquamacs then
633            you can use SLIME right away, without getting and
634            installing it separately. You just need to tell SLIME
635            where to find your installation of &CCL;.</para>
636            </listitem>
637        <listitem>
638          <para>You have a working copy of &CCL;, installed in
639            <literal>"~/ccl"</literal>If you prefer to install
640            &CCL; in some directory other
641            than<literal>"~/ccl"</literal> then these
642            instructions still work, but you must remember to use your
643            path to your ccl directory instead of the one that we give
644            here.</para>
645        </listitem>
646        <listitem>
647          <para>You install emacs add-ons in the folder
648            <literal>"~/emacs/site/"</literal>If this directory
649            doesn't exist on your system, you can just create it.If
650            you prefer to install Emacs add-ons in some place other
651            than<literal>"~/emacs/site/"</literal> then you must
652            remember to use your path to Emacs add-ons in place of
653            ours.</para>
654        </listitem>
655       
656      </itemizedlist>
657    </sect2>
658
659    <!-- ***************************************************** -->
660    <sect2 id="Getting_Slime"><title>Getting SLIME</title>       
661
662      <para>You can get SLIME from the SLIME Home Page. Stable
663        releases and CVS snapshots are available as archive files, or
664        you can follow the instructions on the SLIME Home Page to
665        check out the latest version from their CVS repository.</para>
666
667      <para>It's worth noting that stable SLIME releases happen very
668        seldom, but the SLIME developers often make changes and
669        improvements that are available through CVS updates. If you
670        asked the SLIM developers, they would most likely recommend
671        that you get SLIME from their CVS repository and update it
672        frequently.</para>
673
674      <para>Whether you get it from CVS, or download and unpack one
675        of the available archives, you should end up with a folder
676        named "slime" that contains the SLIME distribution.</para>
677    </sect2>
678
679    <!-- ***************************************************** -->
680    <sect2><title>Installing SLIME</title> 
681
682      <para>Once you have the "slime" folder described in the previous
683        section, installation is a simple matter of copying the folder
684        to the proper place. You can drag it into the "~/emacs/site/"
685        folder, or you can use a terminal command to copy it
686        there. For example, assuming your working directory contains
687        the unpacked "slime" folder:</para> <para><literal>$ cp -R
688        slime ~/emacs/site/</literal></para> <para>That's all it
689        takes.</para>
690
691    </sect2>
692
693    <!-- ***************************************************** -->
694    <sect2 id="Telling-Emacs-About-SLIME">
695          <title>Telling Emacs About SLIME</title>
696      <para> Once SLIME and &CCL; are installed, you just need to
697        add a line to your "~/.emacs" file that tells SLIME where to
698        find the script that runs &CCL;:</para>
699      <para><literal>(setq inferior-lisp-program "~/ccl/scripts/ccl64")</literal></para>
700      <para>or</para>
701      <para><literal>(setq inferior-lisp-program "~/ccl/scripts/ccl")</literal></para>
702      <warning>
703        <para>Aquamacs users should add this line to the file "~/Library/Preferences/Aquamacs Emacs/Preferences.el".</para>
704      </warning>
705    </sect2>
706
707    <!-- ***************************************************** -->
708    <sect2 id="Running-CCL-with-SLIME">
709          <title>Running &CCL; with SLIME</title>
710      <para>Once the preparations in the previous section are
711        complete, exit Emacs and restart it, to ensure that it reads
712        the changes you made in your ".emacs" file (alternatively, you
713        could tell Emacs to reload the ".emacs" file). If all went
714        well, you should now be ready to run &CCL; using
715        SLIME.</para>
716      <para>To run &CCL;, execute the command "M-x slime". SLIME
717        should start an &CCL; session in a new buffer.  (If you are
718        unfamiliar with the Emacs notation "M-x command", see the GNU
719        Emacs FAQ; specifically, take a look at questions 1, 2, and
720        128.)</para>
721    </sect2>
722
723    <!-- ***************************************************** -->
724    <sect2 id="What-if-a-New-Version-of-CCL-Breaks-SLIME-">
725          <title>What if a New Version of &CCL; Breaks SLIME?</title>
726          <para>Sometimes you'll get a new version of &CCL;, set up
727            Emacs to use it with SLIME, and SLIME will fail. Most likely
728            what has happened is that the new version of &CCL; has a
729            change in the output files produced by the compiler (&CCL;
730            developers will say "the fasl version has changed." fasl
731            stands for "fast load" aka compiled files). This
732            problem is easy to fix: just delete the existing SLIME fasl
733            files. The next time you launch Emacs and start SLIME, it will
734            automatically recompile the Lisp files, and that should fix
735            the problem.</para>
736      <para>SLIME's load process stores its fasl files in a hidden
737        folder inside your home folder. The path is</para>
738      <para><literal>~/.slime/fasl</literal></para>
739      <para>You can use a shell command to remove the fasl files, or
740        remove them using your system's file browser.</para>
741      <para><emphasis role="bold">Note for Macintosh Users:</emphasis> 
742            The leading "." character in the ".slime" folder's name
743            prevents the Finder from showing this folder to you. If you
744            use the "Go To Folder" menu item in the Finder's "Go" menu,
745            you can type in "~/.slime" and the Finder will show it to
746            you. You can then drag the "fasl" folder to the trash.
747          </para>
748    </sect2>
749
750    <!-- ***************************************************** -->
751    <sect2 id="Known-Bugs">
752          <title>Known Bugs</title>
753          <para>SLIME has not been updated to account for recent changes
754            made in &CCL; to support x86-64 processors. You may run into
755            bugs running on those platforms.</para>
756      <para>The SLIME backtrace sometimes shows incorrect information.</para>
757      <para><literal>return-from-frame</literal> and
758        <literal>apply-in-frame</literal> do not work reliably.  (If
759        they work at all, it's pure luck.)</para>
760      <para>Some versions of Emacs on the Macintosh may have trouble
761        finding the shell script that runs &CCL; unless you specify
762        a full path to it. See the above section "Telling Emacs About
763        SLIME" to learn how to specify the path to the shell
764        script.</para>
765      <para>For more help with &CCL; on Mac OS X, consult the &CCL;
766        mailing lists. You can find information about the mailing
767        lists on the
768        &CCL; <ulink url="http://trac.clozure.com/openmcl">wiki</ulink>.</para>
769    </sect2>
770  </sect1>
771
772  <!-- ============================================================ -->
773  <sect1 id="Example-Programs">
774    <title>Example Programs</title>
775    <para>A number (ok, a <emphasis>small</emphasis> number), of
776    example programs are distributed in the "ccl:examples;" directory
777    of the source distribution. See the README-OPENMCL-EXAMPLES text
778    file in that directory for information about prerequisites and
779    usage.</para>
780    <para>Some of the example programs are derived from C examples
781      in textbooks, etc.; in those cases, the original author and work
782      are cited in the source code.</para>
783    <para>Unless the original author or contributor claims other
784      rights, you're free to incorporate any of this example code or
785      derivative thereof in any of your own works without
786      restriction. In doing so, you agree that the code was provided
787      "as is", and that no other party is legally or otherwise
788      responsible for any consequences of your decision to use
789      it.</para>
790    <para>If you've developed &CCL; examples that you'd like to see
791      added to the distribution, please send mail to the &CCL; mailing
792      lists. Any such contributions would be welcome and appreciated
793      (as would bug fixes and improvements to the existing
794      examples.)</para>
795  </sect1>
796</chapter>
Note: See TracBrowser for help on using the repository browser.