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> |
---|