Context Navigation

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

Visit:

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

Note: See TracBrowser for help on using the repository browser.

Download in other formats: