source: trunk/abcl/doc/manual/abcl.tex @ 13415

Last change on this file since 13415 was 13415, checked in by Mark Evenson, 10 years ago

Don't print the #\Uxxxx representation for character codes greater than 0xff.

We make #\Uxxxx a synonym of character code but not the cannonical
character name, using instead the unicode character at that point.

File size: 14.5 KB
Line 
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
13This 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
25java-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
33There are three ways to build ABCL from the source release with the
34preferred (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
47In all cases you need a Java 5 or later JDK (JDK 1.5 and 1.6 have been
48tested).  Just the JRE isn't enough, as you need the Java compiler
49('javac') to compile the Java source of the ABCL implementation.
50
51Note that when deploying ABCL having JDK isn't a requirement for the
52installation site, just the equivalent JRE, as ABCL compiles directly
53to byte code, avoiding the need for the 'javac' compiler in deployment
54environments.
55
56
57\subsubsection{Using Ant}
58
59Download a binary distribution [Ant version 1.7.1 or greater][1].
60Unpack 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
65Then simply executing
66
67\begin[shell]{code}
68       unix$ ant
69\end{code}
70
71or
72
73\begin[shell]{code}
74    dos> ant.bat
75\end{code}
76
77from the directory containing this README file will create an
78executable wrapper ('abcl' under UNIX, 'abcl.bat' under Windows).  Use
79this wrapper to start ABCL.
80
81
82\subsubsection{Using NetBeans}
83
84Obtain and install the [Netbeans IDE][2]. One should be able to open
85the ABCL directory as a project in the Netbeans 6.x application,
86whereupon the usual build, run, and debug targets as invoked in the
87GUI are available.
88
89[2]: http://netbeans.org/downloads/
90
91
92\subsubsection{Building from Lisp}
93
94
95Building from a Lisp is the most venerable and untested way of
96building ABCL.  It produces a "non-standard" version of the
97distribution that doesn't share build instructions with the previous
98two methods, but it still may be of interest to those who absolutely
99don't want to know anything about Java.
100
101First, copy the file 'customizations.lisp.in' to 'customization.lisp',
102in the directory containing this README file, editing to suit your
103situation, paying attention to the comments in the file.  The critical
104step is to have Lisp special variable '*JDK*' point to the root of the
105Java Development Kit.  Underneath the directory referenced by the
106value of '*JDK*' there should be an exectuable Java compiler in
107'bin/javac' ('bin/java.exe' under Windows).
108
109Then, one may either use the 'build-from-lisp.sh' shell script or load
110the necessary files into your Lisp image by hand.
111
112\paragraph{Using the 'build-from-lisp.sh' script}
113
114Under 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
122After a successful build, you may use \file{abcl} (\file{abcl.bat} on
123Windows) to start ABCL.  Note that this wrappers contain absolute
124paths, so you'll need to edit them if you move things around after the
125build.
126
127If 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
133to not do a full rebuild.
134
135In 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
141This invokes javac separately for each .java file, which avoids running
142into limitations on command line length (but is a lot slower).
143
144\subsubsubsection{Building from another Lisp by hand}
145
146There is also an ASDF definition in 'abcl.asd' for the BUILD-ABCL
147which 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
153will build ABCL.  If ASDF isn't present, simply LOAD the
154'customizations.lisp' and 'build-abcl.lisp' files to achieve the same
155effect 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
168ABCL offers a number of mechanisms to manipulate Java libraries from
169Lisp.
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
187Manipulation of the Lisp API is currently lacking a stable interface,
188so 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
204FFI stands for "Foreign Function Interface" which is the phase which
205the contemporary Lisp world refers to methods of "calling out" from
206Lisp into "foreign" languages and environments.  This document
207describes the various ways that one interacts with Lisp world of ABCL
208from Java, considering the hosted Lisp as the "Foreign Function" that
209needs to be "Interfaced".
210
211\subsubsubsection{Calling Lisp from Java}
212
213Note: As the entire ABCL Lisp system resides in the org.armedbear.lisp
214package the following code snippets do not show the relevant import
215statements in the interest of brevity.  An example of the import
216statement would be
217
218\begin[java]{code}
219  import org.armedbear.lisp.*;
220\end{document}
221
222to potentially import all the JVM symbol from the `org.armedbear.lisp'
223namespace.
224
225Per JVM, there can only ever be a single Lisp interpreter.  This is
226started by calling the static method `Interpreter.createInstance()`.
227
228\begin[java]{code}
229  Interpreter interpreter = Interpreter.createInstance();
230\end{code}
231
232If this method has already been invoked in the lifetime of the current
233Java process it will return null, so if you are writing Java whose
234life-cycle is a bit out of your control (like in a Java servlet), a
235safer 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
245The Lisp \code{eval} primitive may be simply passed strings for evaluation,
246as follows
247
248\begin[java]{code}
249  String line = "(load \"file.lisp\")";
250  LispObject result = interpreter.eval(line);
251\end{code}
252
253Notice that all possible return values from an arbitrary Lisp
254computation are collapsed into a single return value.  Doing useful
255further computation on the ``LispObject'' depends on knowing what the
256result of the computation might be, usually involves some amount
257of \code{instanceof} introspection, and forms a whole topic to itself
258(c.f. [Introspecting a LispObject](#introspecting)). 
259
260Using ``EVAL'' involves the Lisp interpreter.  Lisp functions may be
261directly invoked by Java method calls as follows.  One simply locates
262the package containing the symbol, then obtains a reference to the
263symbol, and then invokes the `execute()` method with the desired
264parameters.
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
277If one is calling an primitive function in the CL package the syntax
278becomes considerably simpler if we can locate the instance of
279definition in the ABCL source, we can invoke the symbol directly.  To
280tell 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
295We present various patterns for introspecting an an arbitrary
296`LispObject` which can represent the result of every Lisp evaluation
297into semantics that Java can meaniningfully deal with.
298
299\paragragh{LispObject as \code{boolean}}
300
301If 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
309Although since in Lisp, any value other than NIL means "true", the
310use 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
318If LispObject is a list, it will have the type `Cons`.  One can then use
319the \code{copyToArray} to make things a bit more suitable for Java
320iteration.
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   
330A more Lispy way to iterated down a list is to use the `cdr()` access
331function 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
348ABCL is currently a non-conforming ANSI Common Lisp implementation due
349to 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
361ABCL aims to be be a fully conforming ANSI Common Lisp
362implementation.  Any other behavior should be reported as a bug.
363
364\section{Extensions}
365
366The symbols in the EXTENSIONS package consititutes extensions to the
367ANSI standard that are potentially useful to the user.  They include
368functions for manipulating network sockets, running external programs,
369registering object finalizers, constructing reference weakly held by
370the garbage collector and others.
371
372\include{extensions}
373
374\subsection{Beyond ANSI}
375
376Naturally, in striving to be a useful contemporary Common Lisp
377implementation, ABCL endeavors to include extensions beyond the ANSI
378specification which are either widely adopted or are especially useful
379in working with the hosting JVM.
380
381\subsubsection{Extensions to CLOS}
382
383There is an additional syntax for specializing the parameter of a
384generic function on a java class, viz. (java:jclass CLASS__STRING)
385where CLASS__STRING is a string naming a Java class in dotted package
386form.
387
388For instance the following specialization would perhaps allow one to
389print more information about the contents of a java.util.Collection
390object
391
392\begin[java]{code}
393(defmethod print-object ((coll (java:jclass "java.util.Collection")) stream)
394 â€Š
395 \end[java]{code}
396
397If the class had been loaded via a classloader other than the original
398the class you wish to specialize on, one needs to specify the
399classloader 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
409We implement a special hexadecimal escape sequence for specifying
410characters 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
412specified by the hexadecimal digits `xxxx'.  The hexadecimal sequence
413must be exactly four digits long, padded by leading zeros for values
414less than 0x1000.
415
416Note that this sequence is never output by the implementation.  Instead,
417the corresponding Unicode character is output for characters whose
418code is greater than 0x00ff.
419
420\section{Multithreading}
421
422% TODO document the THREADS package.
423\include{threads}
424
425\section{History}
426
427ABCL was originally the extension language for the J editor, which was
428started in 1998 by Peter Graves.  Sometime in 2003, it seems that a
429lot of code that had previously not been released publically was
430suddenly committed that enabled ABCL to be plausibly termed an ANSI
431Common Lisp implementation. 
432
433In 2006, the implementation was transferred to the current
434maintainers, who have strived to improve its usability as a
435contemporary 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
Note: See TracBrowser for help on using the repository browser.