1 | % http://en.wikibooks.org/wiki/LaTeX/ |
---|
2 | |
---|
3 | \include{index.sty} |
---|
4 | |
---|
5 | \begin{document} |
---|
6 | \title{A Manual for Armed Bear Common Lisp} |
---|
7 | \date{June 17, 2011} |
---|
8 | \author{Mark Evenson, Erik Huelsmann, Alessio Stallo, Ville Voutilainen} |
---|
9 | |
---|
10 | \section{Introduction} |
---|
11 | \subsection{Version} |
---|
12 | |
---|
13 | This manual corresponds to abcl-0.26.0, as yet unreleased. |
---|
14 | |
---|
15 | \section{Obtaining} |
---|
16 | |
---|
17 | \subsection{Source Repositories} |
---|
18 | |
---|
19 | \begin[shell]{code} |
---|
20 | svn co http://svn.common-lisp.net/armedbear/trunk abcl |
---|
21 | \end{code} |
---|
22 | |
---|
23 | \subsection{Requirements} |
---|
24 | |
---|
25 | java-1.5.xx, java-1.6.0__10+ recommended. |
---|
26 | |
---|
27 | % Omit the build instructions? This really doesn't belong in a User |
---|
28 | % Manual, or if it does, then in an appendix. --ME 20110725 |
---|
29 | \subsection{Building from Source} |
---|
30 | |
---|
31 | |
---|
32 | |
---|
33 | There are three ways to build ABCL from the source release with the |
---|
34 | preferred (and most tested way) is to being to use the Ant build tool: |
---|
35 | |
---|
36 | \begin{itemize} |
---|
37 | |
---|
38 | \item Use the Ant build tool for Java environments. |
---|
39 | |
---|
40 | \item Use the Netbeans 6.x IDE to open ABCL as a project. |
---|
41 | |
---|
42 | \item Bootstrap ABCL using a Common Lisp implementation. Supported |
---|
43 | implementations for this process: SBCL, CMUCL, OpenMCL, Allegro |
---|
44 | CL, LispWorks or CLISP. |
---|
45 | \end{itemize} |
---|
46 | |
---|
47 | In all cases you need a Java 5 or later JDK (JDK 1.5 and 1.6 have been |
---|
48 | tested). Just the JRE isn't enough, as you need the Java compiler |
---|
49 | ('javac') to compile the Java source of the ABCL implementation. |
---|
50 | |
---|
51 | Note that when deploying ABCL having JDK isn't a requirement for the |
---|
52 | installation site, just the equivalent JRE, as ABCL compiles directly |
---|
53 | to byte code, avoiding the need for the 'javac' compiler in deployment |
---|
54 | environments. |
---|
55 | |
---|
56 | |
---|
57 | \subsubsection{Using Ant} |
---|
58 | |
---|
59 | Download a binary distribution [Ant version 1.7.1 or greater][1]. |
---|
60 | Unpack the files somewhere convenient, ensuring that the 'ant' (or |
---|
61 | 'ant.bat' under Windows) executable is in your path and executable. |
---|
62 | |
---|
63 | [1]: http://ant.apache.org/bindownload.cgi |
---|
64 | |
---|
65 | Then simply executing |
---|
66 | |
---|
67 | \begin[shell]{code} |
---|
68 | unix$ ant |
---|
69 | \end{code} |
---|
70 | |
---|
71 | or |
---|
72 | |
---|
73 | \begin[shell]{code} |
---|
74 | dos> ant.bat |
---|
75 | \end{code} |
---|
76 | |
---|
77 | from the directory containing this README file will create an |
---|
78 | executable wrapper ('abcl' under UNIX, 'abcl.bat' under Windows). Use |
---|
79 | this wrapper to start ABCL. |
---|
80 | |
---|
81 | |
---|
82 | \subsubsection{Using NetBeans} |
---|
83 | |
---|
84 | Obtain and install the [Netbeans IDE][2]. One should be able to open |
---|
85 | the ABCL directory as a project in the Netbeans 6.x application, |
---|
86 | whereupon the usual build, run, and debug targets as invoked in the |
---|
87 | GUI are available. |
---|
88 | |
---|
89 | [2]: http://netbeans.org/downloads/ |
---|
90 | |
---|
91 | |
---|
92 | \subsubsection{Building from Lisp} |
---|
93 | |
---|
94 | |
---|
95 | Building from a Lisp is the most venerable and untested way of |
---|
96 | building ABCL. It produces a "non-standard" version of the |
---|
97 | distribution that doesn't share build instructions with the previous |
---|
98 | two methods, but it still may be of interest to those who absolutely |
---|
99 | don't want to know anything about Java. |
---|
100 | |
---|
101 | First, copy the file 'customizations.lisp.in' to 'customization.lisp', |
---|
102 | in the directory containing this README file, editing to suit your |
---|
103 | situation, paying attention to the comments in the file. The critical |
---|
104 | step is to have Lisp special variable '*JDK*' point to the root of the |
---|
105 | Java Development Kit. Underneath the directory referenced by the |
---|
106 | value of '*JDK*' there should be an exectuable Java compiler in |
---|
107 | 'bin/javac' ('bin/java.exe' under Windows). |
---|
108 | |
---|
109 | Then, one may either use the 'build-from-lisp.sh' shell script or load |
---|
110 | the necessary files into your Lisp image by hand. |
---|
111 | |
---|
112 | \paragraph{Using the 'build-from-lisp.sh' script} |
---|
113 | |
---|
114 | Under UNIX-like systems, you may simply invoke the |
---|
115 | 'build-from-lisp.sh' script as './build-from-lisp.sh |
---|
116 | <lisp-of-choice>', e.g. |
---|
117 | |
---|
118 | \begin[shell]{code} |
---|
119 | unix$ ./build-from-lisp.sh sbcl |
---|
120 | \end{code} |
---|
121 | |
---|
122 | After a successful build, you may use \file{abcl} (\file{abcl.bat} on |
---|
123 | Windows) to start ABCL. Note that this wrappers contain absolute |
---|
124 | paths, so you'll need to edit them if you move things around after the |
---|
125 | build. |
---|
126 | |
---|
127 | If you're developing on ABCL, you may want to use |
---|
128 | |
---|
129 | \begin[shell]{code} |
---|
130 | unix$ ./build-from-lisp.sh <implementation> --clean=nil |
---|
131 | \end{code} |
---|
132 | |
---|
133 | to not do a full rebuild. |
---|
134 | |
---|
135 | In case of failure in the javac stage, you might try this: |
---|
136 | |
---|
137 | \begin[shell]{code} |
---|
138 | unix$ ./build-from-lisp.sh <implementation> --full=t --clean=t --batch=nil |
---|
139 | \end{code} |
---|
140 | |
---|
141 | This invokes javac separately for each .java file, which avoids running |
---|
142 | into limitations on command line length (but is a lot slower). |
---|
143 | |
---|
144 | \subsubsubsection{Building from another Lisp by hand} |
---|
145 | |
---|
146 | There is also an ASDF definition in 'abcl.asd' for the BUILD-ABCL |
---|
147 | which can be used to load the necessary Lisp definitions, after which |
---|
148 | |
---|
149 | \begin[lisp]{code} |
---|
150 | CL-USER> (build-abcl:build-abcl :clean t :full t) |
---|
151 | \end{code} |
---|
152 | |
---|
153 | will build ABCL. If ASDF isn't present, simply LOAD the |
---|
154 | 'customizations.lisp' and 'build-abcl.lisp' files to achieve the same |
---|
155 | effect as loading the ASDF definition. |
---|
156 | |
---|
157 | \subsection{Contributing} |
---|
158 | |
---|
159 | \section{Interaction with host JVM} |
---|
160 | |
---|
161 | % describe calling Java from Lisp, and calling Lisp from Java, |
---|
162 | % probably in two separate sections. Presumably, we can partition our |
---|
163 | % audience into those who are more comfortable with Java, and those |
---|
164 | % that are more comforable with Lisp |
---|
165 | |
---|
166 | \subsection{Lisp to Java} |
---|
167 | |
---|
168 | ABCL offers a number of mechanisms to manipulate Java libraries from |
---|
169 | Lisp. |
---|
170 | |
---|
171 | \begin{itemize} |
---|
172 | \item Java values are accessible as objects of type JAVA:JAVA-OBJECT. |
---|
173 | \item The Java FFI presents a Lisp package (JAVA) with many useful |
---|
174 | symbols for manipulating the artifacts of expectation on the JVM, |
---|
175 | including creation of new objects \ref{JAVA:JNEW}, \ref{JAVA:JMETHOD}), the |
---|
176 | introspection of values \ref{JAVA:JFIELD}, the execution of methods |
---|
177 | (\ref{JAVA:JCALL}, \ref{JAVA:JCALL-RAW}, \ref{JAVA:JSTATIC}) |
---|
178 | \item The JSS package (\ref{JSS}) in contrib introduces a convenient macro |
---|
179 | syntax \ref{JSS:SHARPSIGN_DOUBLEQUOTE_MACRO} for accessing Java |
---|
180 | methods, and additional convenience functions. |
---|
181 | \item Java classes and libraries may be dynamically added to the |
---|
182 | classpath at runtime (JAVA:ADD-TO-CLASSPATH). |
---|
183 | \end{itemize} |
---|
184 | |
---|
185 | \subsection{Lisp from Java} |
---|
186 | |
---|
187 | Manipulation of the Lisp API is currently lacking a stable interface, |
---|
188 | so what is documented here is subject to change. |
---|
189 | |
---|
190 | \begin{itemize} |
---|
191 | \item All Lisp values are descendants of LispObject.java |
---|
192 | \item Lisp symbols are accessible via either directly referencing the |
---|
193 | Symbol.java instance or by dynamically introspecting the |
---|
194 | corresponding Package.java instance. |
---|
195 | \item The Lisp dynamic environment may be saved via |
---|
196 | \code{LispThread.bindSpecial(BINDING)} and restored via |
---|
197 | LispThread.resetSpecialBindings(mark). |
---|
198 | \item Functions may be executed by invocation of the |
---|
199 | Function.execute(args [...]) |
---|
200 | \end{itemize} |
---|
201 | |
---|
202 | \subsubsection{Lisp FFI} |
---|
203 | |
---|
204 | FFI stands for "Foreign Function Interface" which is the phase which |
---|
205 | the contemporary Lisp world refers to methods of "calling out" from |
---|
206 | Lisp into "foreign" languages and environments. This document |
---|
207 | describes the various ways that one interacts with Lisp world of ABCL |
---|
208 | from Java, considering the hosted Lisp as the "Foreign Function" that |
---|
209 | needs to be "Interfaced". |
---|
210 | |
---|
211 | \subsubsubsection{Calling Lisp from Java} |
---|
212 | |
---|
213 | Note: As the entire ABCL Lisp system resides in the org.armedbear.lisp |
---|
214 | package the following code snippets do not show the relevant import |
---|
215 | statements in the interest of brevity. An example of the import |
---|
216 | statement would be |
---|
217 | |
---|
218 | \begin[java]{code} |
---|
219 | import org.armedbear.lisp.*; |
---|
220 | \end{document} |
---|
221 | |
---|
222 | to potentially import all the JVM symbol from the `org.armedbear.lisp' |
---|
223 | namespace. |
---|
224 | |
---|
225 | Per JVM, there can only ever be a single Lisp interpreter. This is |
---|
226 | started by calling the static method `Interpreter.createInstance()`. |
---|
227 | |
---|
228 | \begin[java]{code} |
---|
229 | Interpreter interpreter = Interpreter.createInstance(); |
---|
230 | \end{code} |
---|
231 | |
---|
232 | If this method has already been invoked in the lifetime of the current |
---|
233 | Java process it will return null, so if you are writing Java whose |
---|
234 | life-cycle is a bit out of your control (like in a Java servlet), a |
---|
235 | safer invocation pattern might be: |
---|
236 | |
---|
237 | \begin[java]{code} |
---|
238 | Interpreter interpreter = Interpreter.getInstance(); |
---|
239 | if (interpreter == null) { |
---|
240 | interpreter = Interpreter.createInstance(); |
---|
241 | } |
---|
242 | \end{code} |
---|
243 | |
---|
244 | |
---|
245 | The Lisp \code{eval} primitive may be simply passed strings for evaluation, |
---|
246 | as follows |
---|
247 | |
---|
248 | \begin[java]{code} |
---|
249 | String line = "(load \"file.lisp\")"; |
---|
250 | LispObject result = interpreter.eval(line); |
---|
251 | \end{code} |
---|
252 | |
---|
253 | Notice that all possible return values from an arbitrary Lisp |
---|
254 | computation are collapsed into a single return value. Doing useful |
---|
255 | further computation on the ``LispObject'' depends on knowing what the |
---|
256 | result of the computation might be, usually involves some amount |
---|
257 | of \code{instanceof} introspection, and forms a whole topic to itself |
---|
258 | (c.f. [Introspecting a LispObject](#introspecting)). |
---|
259 | |
---|
260 | Using ``EVAL'' involves the Lisp interpreter. Lisp functions may be |
---|
261 | directly invoked by Java method calls as follows. One simply locates |
---|
262 | the package containing the symbol, then obtains a reference to the |
---|
263 | symbol, and then invokes the `execute()` method with the desired |
---|
264 | parameters. |
---|
265 | |
---|
266 | \begin[java]{code} |
---|
267 | interpreter.eval("(defun foo (msg) (format nil \"You told me '~A'~%\" msg))"); |
---|
268 | Package pkg = Packages.findPackage("CL-USER"); |
---|
269 | Symbol foo = pkg.findAccessibleSymbol("FOO"); |
---|
270 | Function fooFunction = (Function)foo.getSymbolFunction(); |
---|
271 | JavaObject parameter = new JavaObject("Lisp is fun!"); |
---|
272 | LispObject result = fooFunction.execute(parameter); |
---|
273 | // How to get the "naked string value"? |
---|
274 | System.out.println("The result was " + result.writeToString()); |
---|
275 | \end{code} |
---|
276 | |
---|
277 | If one is calling an primitive function in the CL package the syntax |
---|
278 | becomes considerably simpler if we can locate the instance of |
---|
279 | definition in the ABCL source, we can invoke the symbol directly. To |
---|
280 | tell if a `LispObject` contains a reference to a symbol. |
---|
281 | |
---|
282 | \begin[java]{code} |
---|
283 | boolean nullp(LispObject object) { |
---|
284 | LispObject result = Primitives.NULL.execute(object); |
---|
285 | if (result == NIL) { |
---|
286 | return false; |
---|
287 | } |
---|
288 | return true; |
---|
289 | } |
---|
290 | \end{code} |
---|
291 | |
---|
292 | \paragraph{Introspecting a LispObject} |
---|
293 | \label{topic:Introspecting a LispObject} |
---|
294 | |
---|
295 | We present various patterns for introspecting an an arbitrary |
---|
296 | `LispObject` which can represent the result of every Lisp evaluation |
---|
297 | into semantics that Java can meaniningfully deal with. |
---|
298 | |
---|
299 | \paragragh{LispObject as \code{boolean}} |
---|
300 | |
---|
301 | If the LispObject a generalized boolean values, one can use |
---|
302 | \java{getBooleanValue()} to convert to Java: |
---|
303 | |
---|
304 | \begin[java]{code} |
---|
305 | LispObject object = Symbol.NIL; |
---|
306 | boolean javaValue = object.getBooleanValue(); |
---|
307 | \end{code} |
---|
308 | |
---|
309 | Although since in Lisp, any value other than NIL means "true", the |
---|
310 | use of Java equality it quite a bit easier and more optimal: |
---|
311 | |
---|
312 | \begin[java]{code}} |
---|
313 | boolean javaValue = (object != Symbol.NIL); |
---|
314 | \end{code} |
---|
315 | |
---|
316 | \subsubsubsubsection{LispObject is a list} |
---|
317 | |
---|
318 | If LispObject is a list, it will have the type `Cons`. One can then use |
---|
319 | the \code{copyToArray} to make things a bit more suitable for Java |
---|
320 | iteration. |
---|
321 | |
---|
322 | \begin[java]{code} |
---|
323 | LispObject result = interpreter.eval("'(1 2 4 5)"); |
---|
324 | if (result instanceof Cons) { |
---|
325 | LispObject array[] = ((Cons)result.copyToArray()); |
---|
326 | ... |
---|
327 | } |
---|
328 | \end{code} |
---|
329 | |
---|
330 | A more Lispy way to iterated down a list is to use the `cdr()` access |
---|
331 | function just as like one would traverse a list in Lisp:; |
---|
332 | |
---|
333 | \begin[java]{code} |
---|
334 | LispObject result = interpreter.eval("'(1 2 4 5)"); |
---|
335 | while (result != Symbol.NIL) { |
---|
336 | doSomething(result.car()); |
---|
337 | result = result.cdr(); |
---|
338 | } |
---|
339 | \end{code} |
---|
340 | |
---|
341 | |
---|
342 | \subsection{JAVA} |
---|
343 | |
---|
344 | % include autogen docs for the JAVA package. |
---|
345 | |
---|
346 | \section{ANSI Common Lisp Conformance} |
---|
347 | |
---|
348 | ABCL is currently a non-conforming ANSI Common Lisp implementation due |
---|
349 | to the following (known) issues: |
---|
350 | |
---|
351 | \begin{itemize} |
---|
352 | \item Lack of long form of DEFINE-METHOD-COMBINATION |
---|
353 | \item Missing statement of conformance in accompanying documentation |
---|
354 | \item Incomplete MOP |
---|
355 | % TODO go through AMOP with symbols, starting by looking for |
---|
356 | % matching function signature. |
---|
357 | % XXX is this really blocking ANSI conformance? Answer: we have |
---|
358 | % to start with such a ``census'' to determine what we have. |
---|
359 | \end{itemize} |
---|
360 | |
---|
361 | ABCL aims to be be a fully conforming ANSI Common Lisp |
---|
362 | implementation. Any other behavior should be reported as a bug. |
---|
363 | |
---|
364 | \section{Extensions} |
---|
365 | |
---|
366 | The symbols in the EXTENSIONS package consititutes extensions to the |
---|
367 | ANSI standard that are potentially useful to the user. They include |
---|
368 | functions for manipulating network sockets, running external programs, |
---|
369 | registering object finalizers, constructing reference weakly held by |
---|
370 | the garbage collector and others. |
---|
371 | |
---|
372 | \include{extensions} |
---|
373 | |
---|
374 | \subsection{Beyond ANSI} |
---|
375 | |
---|
376 | Naturally, in striving to be a useful contemporary Common Lisp |
---|
377 | implementation, ABCL endeavors to include extensions beyond the ANSI |
---|
378 | specification which are either widely adopted or are especially useful |
---|
379 | in working with the hosting JVM. |
---|
380 | |
---|
381 | \subsubsection{Extensions to CLOS} |
---|
382 | |
---|
383 | There is an additional syntax for specializing the parameter of a |
---|
384 | generic function on a java class, viz. (java:jclass CLASS__STRING) |
---|
385 | where CLASS__STRING is a string naming a Java class in dotted package |
---|
386 | form. |
---|
387 | |
---|
388 | For instance the following specialization would perhaps allow one to |
---|
389 | print more information about the contents of a java.util.Collection |
---|
390 | object |
---|
391 | |
---|
392 | \begin[java]{code} |
---|
393 | (defmethod print-object ((coll (java:jclass "java.util.Collection")) stream) |
---|
394 | ⊠|
---|
395 | \end[java]{code} |
---|
396 | |
---|
397 | If the class had been loaded via a classloader other than the original |
---|
398 | the class you wish to specialize on, one needs to specify the |
---|
399 | classloader as an optional third argument. |
---|
400 | |
---|
401 | \begin[java]{code} |
---|
402 | (defmethod print-object ((device-id (java:jclass "dto.nbi.service.hdm.alcatel.com.NBIDeviceID" |
---|
403 | (#"getBaseLoader" cl-user::*classpath-manager*))) |
---|
404 | ⊠|
---|
405 | \end[java]{code} |
---|
406 | |
---|
407 | \subsubsection{Extensions to the Reader} |
---|
408 | |
---|
409 | We implement a special hexadecimal escape sequence for specifying |
---|
410 | characters to the Lisp reader, namely we allow a sequences of the form |
---|
411 | #\Uxxxx to be processed by the reader as character whose code is |
---|
412 | specified by the hexadecimal digits `xxxx'. The hexadecimal sequence |
---|
413 | must be exactly four digits long, padded by leading zeros for values |
---|
414 | less than 0x1000. |
---|
415 | |
---|
416 | Note that this sequence is never output by the implementation. Instead, |
---|
417 | the corresponding Unicode character is output for characters whose |
---|
418 | code is greater than 0x00ff. |
---|
419 | |
---|
420 | \section{Multithreading} |
---|
421 | |
---|
422 | % TODO document the THREADS package. |
---|
423 | \include{threads} |
---|
424 | |
---|
425 | \section{History} |
---|
426 | |
---|
427 | ABCL was originally the extension language for the J editor, which was |
---|
428 | started in 1998 by Peter Graves. Sometime in 2003, it seems that a |
---|
429 | lot of code that had previously not been released publically was |
---|
430 | suddenly committed that enabled ABCL to be plausibly termed an ANSI |
---|
431 | Common Lisp implementation. |
---|
432 | |
---|
433 | In 2006, the implementation was transferred to the current |
---|
434 | maintainers, who have strived to improve its usability as a |
---|
435 | contemporary Common Lisp implementation. |
---|
436 | |
---|
437 | |
---|
438 | \end{document} |
---|
439 | |
---|
440 | % TODO |
---|
441 | % 1. Create mechanism for swigging DocString and Lisp docs into |
---|
442 | % sections. |
---|
443 | |
---|