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

% http://en.wikibooks.org/wiki/LaTeX/

\include{index.sty}

\begin{document}
\title{A Manual for Armed Bear Common Lisp}
\date{June 17, 2011}
\author{Mark Evenson, Erik Huelsmann, Alessio Stallo, Ville Voutilainen}

\section{Introduction}
\subsection{Version}

This manual corresponds to abcl-0.26.0, as yet unreleased.

\section{Obtaining}

\subsection{Source Repositories}

\begin[shell]{code} 
  svn co http://svn.common-lisp.net/armedbear/trunk abcl
\end{code}

\subsection{Requirements}

java-1.5.xx, java-1.6.0_10+ recommended.

\subsection{Building from Source}

There are three ways to build ABCL from the source release with the
preferred (and most tested way) is to being to use the Ant build tool:

\begin{itemize}

\item Use the Ant build tool for Java environments.

\item Use the Netbeans 6.x IDE to open ABCL as a project.

\item Bootstrap ABCL using a Common Lisp implementation. Supported
  implementations for this process: SBCL, CMUCL, OpenMCL, Allegro
  CL, LispWorks or CLISP.
\end{itemize}

In all cases you need a Java 5 or later JDK (JDK 1.5 and 1.6 have been
tested).  Just the JRE isn't enough, as you need the Java compiler
('javac') to compile the Java source of the ABCL implementation.

Note that when deploying ABCL having JDK isn't a requirement for the
installation site, just the equivalent JRE, as ABCL compiles directly
to byte code, avoiding the need for the 'javac' compiler in deployment
environments.


\subsubsection{Using Ant}

Download a binary distribution [Ant version 1.7.1 or greater][1].
Unpack the files somewhere convenient, ensuring that the 'ant' (or
'ant.bat' under Windows) executable is in your path and executable.

[1]: http://ant.apache.org/bindownload.cgi

Then simply executing

\begin[shell]{code}
       unix$ ant
\end{code}

or

\begin[shell]{code}
    dos> ant.bat
\end{code}

from the directory containing this README file will create an
executable wrapper ('abcl' under UNIX, 'abcl.bat' under Windows).  Use
this wrapper to start ABCL.


\subsubsection{Using NetBeans}

Obtain and install the [Netbeans IDE][2]. One should be able to open
the ABCL directory as a project in the Netbeans 6.x application,
whereupon the usual build, run, and debug targets as invoked in the
GUI are available.

[2]: http://netbeans.org/downloads/


\subsubsection{Building from Lisp}


Building from a Lisp is the most venerable and untested way of
building ABCL.  It produces a "non-standard" version of the
distribution that doesn't share build instructions with the previous
two methods, but it still may be of interest to those who absolutely
don't want to know anything about Java.

First, copy the file 'customizations.lisp.in' to 'customization.lisp',
in the directory containing this README file, editing to suit your
situation, paying attention to the comments in the file.  The critical
step is to have Lisp special variable '*JDK*' point to the root of the
Java Development Kit.  Underneath the directory referenced by the
value of '*JDK*' there should be an exectuable Java compiler in
'bin/javac' ('bin/java.exe' under Windows).

Then, one may either use the 'build-from-lisp.sh' shell script or load
the necessary files into your Lisp image by hand.

\paragraph{Using the 'build-from-lisp.sh' script}

Under UNIX-like systems, you may simply invoke the
'build-from-lisp.sh' script as './build-from-lisp.sh
<lisp-of-choice>', e.g.

\begin[shell]{code}
    unix$ ./build-from-lisp.sh sbcl
\end{code}

After a successful build, you may use \file{abcl} (\file{abcl.bat} on
Windows) to start ABCL.  Note that this wrappers contain absolute
paths, so you'll need to edit them if you move things around after the
build.

If you're developing on ABCL, you may want to use

\begin[shell]{code}
    unix$ ./build-from-lisp.sh <implementation> --clean=nil
\end{code}

to not do a full rebuild.

In case of failure in the javac stage, you might try this:

\begin[shell]{code}
    unix$ ./build-from-lisp.sh <implementation> --full=t --clean=t --batch=nil
\end{code}

This invokes javac separately for each .java file, which avoids running
into limitations on command line length (but is a lot slower).

\subsubsubsection{Building from another Lisp by hand}

There is also an ASDF definition in 'abcl.asd' for the BUILD-ABCL
which can be used to load the necessary Lisp definitions, after which

\begin[lisp]{code}
    CL-USER> (build-abcl:build-abcl :clean t :full t)
\end{code}

will build ABCL.  If ASDF isn't present, simply LOAD the
'customizations.lisp' and 'build-abcl.lisp' files to achieve the same
effect as loading the ASDF definition.

\subsection{Contributing}

\section{Interaction with host JVM}

% describe calling Java from Lisp, and calling Lisp from Java,
% probably in two separate sections.  Presumably, we can partition our
% audience into those who are more comfortable with Java, and those
% that are more comforable with Lisp

\subsection{Lisp to Java}

ABCL offers a number of mechanisms to manipulate Java libraries from
Lisp.

\begin{itemize}
\item Java values are accessible as objects of type JAVA:JAVA-OBJECT.
\item The Java FFI presents a Lisp package (JAVA) with many useful
  symbols for manipulating the artifacts of expectation on the JVM,
  including creation of new objects \ref{JAVA:JNEW}, \ref{JAVA:JMETHOD}), the
  introspection of values \ref{JAVA:JFIELD}, the execution of methods
  (\ref{JAVA:JCALL}, \ref{JAVA:JCALL-RAW}, \ref{JAVA:JSTATIC})
\item The JSS package (\ref{JSS}) in contrib introduces a convenient macro
  syntax \ref{JSS:SHARPSIGN_DOUBLEQUOTE_MACRO} for accessing Java
  methods, and additional convenience functions.
\item Java classes and libraries may be dynamically added to the
  classpath at runtime (JAVA:ADD-TO-CLASSPATH).
\end{itemize}

\subsection{Lisp from Java}

Manipulation of the Lisp API is currently lacking a stable interface,
so what is documented here is subject to change.  

\begin{itemize}
\item All Lisp values are descendants of LispObject.java
\item Lisp symbols are accessible via either directly referencing the
  Symbol.java instance or by dynamically introspecting the
  corresponding Package.java instance.
\item The Lisp dynamic environment may be saved via
  \code{LispThread.bindSpecial(BINDING)} and restored via
  LispThread.resetSpecialBindings(mark).
\item Functions may be executed by invocation of the
  Function.execute(args [...]) 
\end{itemize}

\subsubsection{Lisp FFI}

FFI stands for "Foreign Function Interface" which is the phase which
the contemporary Lisp world refers to methods of "calling out" from
Lisp into "foreign" languages and environments.  This document
describes the various ways that one interacts with Lisp world of ABCL
from Java, considering the hosted Lisp as the "Foreign Function" that
needs to be "Interfaced".

\subsubsubsection{Calling Lisp from Java}

Note: As the entire ABCL Lisp system resides in the org.armedbear.lisp
package the following code snippets do not show the relevant import
statements in the interest of brevity.  An example of the import
statement would be

\begin[java]{code}
  import org.armedbear.lisp.*;
\end{document}

to potentially import all the JVM symbol from the `org.armedbear.lisp'
namespace.

Per JVM, there can only ever be a single Lisp interpreter.  This is
started by calling the static method `Interpreter.createInstance()`.

\begin[java]{code}
  Interpreter interpreter = Interpreter.createInstance();
\end{code}

If this method has already been invoked in the lifetime of the current
Java process it will return null, so if you are writing Java whose
life-cycle is a bit out of your control (like in a Java servlet), a
safer invocation pattern might be:

\begin[java]{code}
  Interpreter interpreter = Interpreter.getInstance();
  if (interpreter == null) {
    interpreter = Interpreter.createInstance();
  }
\end{code}



The Lisp \code{eval} primitive may be simply passed strings for evaluation,
as follows

\begin[java]{code}
  String line = "(load \"file.lisp\")";
  LispObject result = interpreter.eval(line);
\end{code}

Notice that all possible return values from an arbitrary Lisp
computation are collapsed into a single return value.  Doing useful
further computation on the `LispObject` depends on knowing what the
result of the computation might be, usually involves some amount
of \code{instanceof} introspection, and forms a whole topic to itself
(c.f. [Introspecting a LispObject](#introspecting)).  

Using `EVAL` involves the Lisp interpreter.  Lisp functions may be
directly invoked by Java method calls as follows.  One simply locates
the package containing the symbol, then obtains a reference to the
symbol, and then invokes the `execute()` method with the desired
parameters.

\begin[java]{code}
    interpreter.eval("(defun foo (msg) (format nil \"You told me '~A'~%\" msg))");
    Package pkg = Packages.findPackage("CL-USER");
    Symbol foo = pkg.findAccessibleSymbol("FOO"); 
    Function fooFunction = (Function)foo.getSymbolFunction();
    JavaObject parameter = new JavaObject("Lisp is fun!");
    LispObject result = fooFunction.execute(parameter);
    // How to get the "naked string value"?
    System.out.prinln("The result was " + result.writeToString()); 
\end{code}

If one is calling an primitive function in the CL package the syntax
becomes considerably simpler if we can locate the instance of
definition in the ABCL source, we can invoke the symbol directly.  To
tell if a `LispObject` contains a reference to a symbol.

\begin[java]{code}
    boolean nullp(LispObject object) {
      LispObject result = Primitives.NULL.execute(object);
      if (result == NIL) {
        return false;
      }
      return true;
   }
\end{code}

\paragraph{Introspecting a LispObject}
\label{topic:Introspecting a LispObject}

We present various patterns for introspecting an an arbitrary
`LispObject` which can represent the result of every Lisp evaluation
into semantics that Java can meaniningfully deal with.

\paragragh{LispObject as \code{boolean}}

If the LispObject a generalized boolean values, one can use
\java{getBooleanValue()} to convert to Java:

\begin[java]{code}
     LispObject object = Symbol.NIL;
     boolean javaValue = object.getBooleanValue();
\end{code}

Although since in Lisp, any value other than NIL means "true", the
use of Java equality it quite a bit easier and more optimal:

\begin[java]{code}}
    boolean javaValue = (object != Symbol.NIL);
\end{code}

\subsubsubsubsection{LispObject is a list}

If LispObject is a list, it will have the type `Cons`.  One can then use
the \code{copyToArray} to make things a bit more suitable for Java
iteration.

\begin[java]{code}
    LispObject result = interpreter.eval("'(1 2 4 5)");
    if (result instanceof Cons) {
      LispObject array[] = ((Cons)result.copyToArray());
      ...
    }
\end{code}
    
A more Lispy way to iterated down a list is to use the `cdr()` access
function just as like one would traverse a list in Lisp:;

\begin[java]{code}
    LispObject result = interpreter.eval("'(1 2 4 5)");
    while (result != Symbol.NIL) {
      doSomething(result.car());
      result = result.cdr();
    }
\end{code}


\subsection{JAVA}

% include autogen docs for the JAVA package.

\section{ANSI Common Lisp Conformance}

ABCL is currently a non-conforming ANSI Common Lisp implementation due
to the following (known) issues:

\begin{itemize}
  \item Lack of long form of DEFINE-METHOD-COMBINATION
  \item Missing statement of conformance in accompanying documentation
  \item Incomplete MOP 
    % TODO go through AMOP with symbols, starting by looking for
    % matching function signature.
    % XXX is this really blocking ANSI conformance?  Answer: we have
    % to start with such a ``census'' to determine what we have.
\end{itemize}

ABCL aims to be be a fully conforming ANSI Common Lisp
implementation.  Any other behavior should be reported as a bug.

\section{Extensions}

The symbols in the EXTENSIONS package consititutes extensions to the
ANSI standard that are potentially useful to the user.  They include
functions for manipulating network sockets, running external programs,
registering object finalizers, constructing reference weakly held by
the garbage collector and others.

\include{extensions}

\section{Multithreading}

% TODO document the THREADS package.
\include{threads}

\section{History}

\end{document}

% TODO
%   1.  Create mechanism for swigging DocString and Lisp docs into
%       sections.