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