06/17/11 07:01:10 (10 years ago)
Mark Evenson

Add installation instructions.

HEADS-UP: This file is guaranteed not to compile in any LaTeX system
without further substantial work, as I am defining the DSL I want for
doumentation as I go, trying out different syntaxes.

Separate content/presentation rules via LaTeX include directives.
Properly use the as yet unwritten \code{} markup.

The 'java.tex', 'threads.tex', and 'extensions.tex' are placeholders
until we get the automatic documentation generator working.

1 edited


  • trunk/abcl/doc/manual/abcl.tex

    r13335 r13338  
    1 % TODO
    2 %   1.  Create mechanism for swigging DocString and Lisp docs into
    3 %       sections.
    6 \documentclass[10pt]{article}
    8 \usepackage{color,hyperref}
    9 \definecolor{darkblue}{rgb}{0.0,0.0,0.3}
    10 \hypersetup{colorlinks,breaklinks,
    11             linkcolor=darkblue,urlcolor=darkblue,
    12             anchorcolor=darkblue,citecolor=darkblue}
    14 \usepackage{a4wide}
     1% http://en.wikibooks.org/wiki/LaTeX/
    176\title{A Manual for Armed Bear Common Lisp}
    18 \date{June 16, 2011}
     7\date{June 17, 2011}
    198\author{Mark Evenson, Erik Huelsmann, Alessio Stallo, Ville Voutilainen}
     17\subsection{Source Repositories}
     20  svn co http://svn.common-lisp.net/armedbear/trunk abcl
    3227\subsection{Building from Source}
    33 % TODO repeat install
     29There are three ways to build ABCL from the source release with the
     30preferred (and most tested way) is to being to use the Ant build tool:
     34\item Use the Ant build tool for Java environments.
     36\item Use the Netbeans 6.x IDE to open ABCL as a project.
     38\item Bootstrap ABCL using a Common Lisp implementation. Supported
     39  implementations for this process: SBCL, CMUCL, OpenMCL, Allegro
     40  CL, LispWorks or CLISP.
     43In all cases you need a Java 5 or later JDK (JDK 1.5 and 1.6 have been
     44tested).  Just the JRE isn't enough, as you need the Java compiler
     45('javac') to compile the Java source of the ABCL implementation.
     47Note that when deploying ABCL having JDK isn't a requirement for the
     48installation site, just the equivalent JRE, as ABCL compiles directly
     49to byte code, avoiding the need for the 'javac' compiler in deployment
     53\subsubsection{Using Ant}
     55Download a binary distribution [Ant version 1.7.1 or greater][1].
     56Unpack the files somewhere convenient, ensuring that the 'ant' (or
     57'ant.bat' under Windows) executable is in your path and executable.
     59[1]: http://ant.apache.org/bindownload.cgi
     61Then simply executing
     64       unix$ ant
     70    dos> ant.bat
     73from the directory containing this README file will create an
     74executable wrapper ('abcl' under UNIX, 'abcl.bat' under Windows).  Use
     75this wrapper to start ABCL.
     78\subsubsection{Using NetBeans}
     80Obtain and install the [Netbeans IDE][2]. One should be able to open
     81the ABCL directory as a project in the Netbeans 6.x application,
     82whereupon the usual build, run, and debug targets as invoked in the
     83GUI are available.
     85[2]: http://netbeans.org/downloads/
     88\subsubsection{Building from Lisp}
     91Building from a Lisp is the most venerable and untested way of
     92building ABCL.  It produces a "non-standard" version of the
     93distribution that doesn't share build instructions with the previous
     94two methods, but it still may be of interest to those who absolutely
     95don't want to know anything about Java.
     97First, copy the file 'customizations.lisp.in' to 'customization.lisp',
     98in the directory containing this README file, editing to suit your
     99situation, paying attention to the comments in the file.  The critical
     100step is to have Lisp special variable '*JDK*' point to the root of the
     101Java Development Kit.  Underneath the directory referenced by the
     102value of '*JDK*' there should be an exectuable Java compiler in
     103'bin/javac' ('bin/java.exe' under Windows).
     105Then, one may either use the 'build-from-lisp.sh' shell script or load
     106the necessary files into your Lisp image by hand.
     108\paragraph{Using the 'build-from-lisp.sh' script}
     110Under UNIX-like systems, you may simply invoke the
     111'build-from-lisp.sh' script as './build-from-lisp.sh
     112<lisp-of-choice>', e.g.
     115    unix$ ./build-from-lisp.sh sbcl
     118After a successful build, you may use \file{abcl} (\file{abcl.bat} on
     119Windows) to start ABCL.  Note that this wrappers contain absolute
     120paths, so you'll need to edit them if you move things around after the
     123If you're developing on ABCL, you may want to use
     126    unix$ ./build-from-lisp.sh <implementation> --clean=nil
     129to not do a full rebuild.
     131In case of failure in the javac stage, you might try this:
     134    unix$ ./build-from-lisp.sh <implementation> --full=t --clean=t --batch=nil
     137This invokes javac separately for each .java file, which avoids running
     138into limitations on command line length (but is a lot slower).
     140\subsubsubsection{Building from another Lisp by hand}
     142There is also an ASDF definition in 'abcl.asd' for the BUILD-ABCL
     143which can be used to load the necessary Lisp definitions, after which
     146    CL-USER> (build-abcl:build-abcl :clean t :full t)
     149will build ABCL.  If ASDF isn't present, simply LOAD the
     150'customizations.lisp' and 'build-abcl.lisp' files to achieve the same
     151effect as loading the ASDF definition.
    50168\item Java values are accessible as objects of type JAVA:JAVA-OBJECT.
    51169\item The Java FFI presents a Lisp package (JAVA) with many useful
    52   symbols for manipulating the artifacts of executation on the JVM,
    53   including creation of new objects (JAVA:JNEW, JAVA:JMETHOD), the
    54   introspection of values (JAVA:JFIELD), the execution of methods
    56 \item The JSS package (JSS) in contrib introduces a convenient macro
    57   syntax (JSS:SHARPSIGN_HASH_DOUBLQUOTE_MACRO) for accessing Java
    58   methods, and additional convenience funtions.
     170  symbols for manipulating the artifacts of expectation on the JVM,
     171  including creation of new objects \ref{JAVA:JNEW}, \ref{JAVA:JMETHOD}), the
     172  introspection of values \ref{JAVA:JFIELD}, the execution of methods
     173  (\ref{JAVA:JCALL}, \ref{JAVA:JCALL-RAW}, \ref{JAVA:JSTATIC})
     174\item The JSS package (\ref{JSS}) in contrib introduces a convenient macro
     175  syntax \ref{JSS:SHARPSIGN_DOUBLEQUOTE_MACRO} for accessing Java
     176  methods, and additional convenience functions.
    59177\item Java classes and libraries may be dynamically added to the
    60178  classpath at runtime (JAVA:ADD-TO-CLASSPATH).
    69 \item All Lisp values are descendents of LispObject.java
    70 \item Lisp symbols are accessible via either directly referening the
     187\item All Lisp values are descendants of LispObject.java
     188\item Lisp symbols are accessible via either directly referencing the
    71189  Symbol.java instance or by dynamically introspecting the
    72190  corresponding Package.java instance.
    73 \item The Lisp dynamic envrionment may be saved via
    74   LispThread.bindSpecial(BINDING) and restored via
     191\item The Lisp dynamic environment may be saved via
     192  \code{LispThread.bindSpecial(BINDING)} and restored via
    75193  LispThread.resetSpecialBindings(mark).
    76194\item Functions may be executed by invocation of the
    80198\subsubsection{Lisp FFI}
    82 FFI stands for "Foreign Function Interface", which is the way the
    83 contemporary Lisp world refers to methods of "calling out" from Lisp
    84 into "foreign" langauges and envrionments.  This document describes
    85 the various ways that one interacts with Lisp world of Abcl from Java,
    86 considering the hosted Lisp as the "Foreign Function" that needs to be
    87 "Interfaced".
     200FFI stands for "Foreign Function Interface" which is the phase which
     201the contemporary Lisp world refers to methods of "calling out" from
     202Lisp into "foreign" languages and environments.  This document
     203describes the various ways that one interacts with Lisp world of ABCL
     204from Java, considering the hosted Lisp as the "Foreign Function" that
     205needs to be "Interfaced".
    90207\subsubsubsection{Calling Lisp from Java}
    92209Note: As the entire ABCL Lisp system resides in the org.armedbear.lisp
    93210package the following code snippets do not show the relevant import
    94 statements in the interest of brevity.
     211statements in the interest of brevity.  An example of the import
     212statement would be
     215  import org.armedbear.lisp.*;
     218to potentially import all the JVM symbol from the `org.armedbear.lisp'
    96221Per JVM, there can only ever be a single Lisp interpreter.  This is
    97222started by calling the static method `Interpreter.createInstance()`.
    99 \begin{code}{java}
    100 Interpreter interpreter = Interpreter.createInstance();
     225  Interpreter interpreter = Interpreter.createInstance();
    103228If this method has already been invoked in the lifetime of the current
    104229Java process it will return null, so if you are writing Java whose
    105 lifecycle is a bit out of your control (like in a Java servlet), a
     230life-cycle is a bit out of your control (like in a Java servlet), a
    106231safer invocation pattern might be:
    108 \begin{code}{java}
    109 Interpreter interpreter = Interpreter.getInstance();
    110 if (interpreter == null) {
    111   interpreter = Interpreter.createInstance();
    112 }
    113 \end{code}
    117 The Lisp `EVAL` primitive may be simply passed strings for evaluation,
     234  Interpreter interpreter = Interpreter.getInstance();
     235  if (interpreter == null) {
     236    interpreter = Interpreter.createInstance();
     237  }
     242The Lisp \code{eval} primitive may be simply passed strings for evaluation,
    118243as follows
    120 \begin{code}{java}   
    121 String line = "(load \"file.lisp\")";
    122 LispObject result = interpreter.eval(line);
    123 \end{code}
     246  String line = "(load \"file.lisp\")";
     247  LispObject result = interpreter.eval(line);
    126250Notice that all possible return values from an arbitrary Lisp
    128252further computation on the `LispObject` depends on knowing what the
    129253result of the computation might be, usually involves some amount
    130 of instanceof introspection, and forms a whole topic to itself
     254of \code{instanceof} introspection, and forms a whole topic to itself
    131255(c.f. [Introspecting a LispObject](#introspecting)). 
    139 \begin{code}{java}   
    140264    interpreter.eval("(defun foo (msg) (format nil \"You told me '~A'~%\" msg))");
    141265    Package pkg = Packages.findPackage("CL-USER");
    153277tell if a `LispObject` contains a reference to a symbol.
    155 \begin{code}{java}   
    156280    boolean nullp(LispObject object) {
    157281      LispObject result = Primitives.NULL.execute(object);
    161285      return true;
    162286   }
    164 \end{code}
    166 /subsubsubsection{Introspecting a LispObject}
     289\paragraph{Introspecting a LispObject}
     290\label{topic:Introspecting a LispObject}
    168292We present various patterns for introspecting an an arbitrary
    170294into semantics that Java can meaniningfully deal with.
    172 /subsubsubsubsection{LispObject as \java{boolean}}
     296\paragragh{LispObject as \code{boolean}}
    174298If the LispObject a generalized boolean values, one can use
    175299\java{getBooleanValue()} to convert to Java:
    177 \begin{code}{java}
    178302     LispObject object = Symbol.NIL;
    179303     boolean javaValue = object.getBooleanValue();
    183307use of Java equality it quite a bit easier and more optimal:
    185 \begin{code}{java}
    186310    boolean javaValue = (object != Symbol.NIL);
    189 /subsubsubsubsection{LispObject is a list}
     313\subsubsubsubsection{LispObject is a list}
    191315If LispObject is a list, it will have the type `Cons`.  One can then use
    192 the `copyToArray[]` to make things a bit more suitable for Java
     316the \code{copyToArray} to make things a bit more suitable for Java
    195 \begin{code}{java}
    196320    LispObject result = interpreter.eval("'(1 2 4 5)");
    197321    if (result instanceof Cons) {
    204328function just as like one would traverse a list in Lisp:;
    206 \begin{code}{java}
    207331    LispObject result = interpreter.eval("'(1 2 4 5)");
    208332    while (result != Symbol.NIL) {
    228352    % TODO go through AMOP with symbols, starting by looking for
    229353    % matching function signature.
     354    % XXX is this really blocking ANSI conformance?  Answer: we have
     355    % to start with such a ``census'' to determine what we have.
    237 % TODO document the EXTENSIONS package.
     363The symbols in the EXTENSIONS package consititutes extensions to the
     364ANSI standard that are potentially useful to the user.  They include
     365functions for manipulating network sockets, running external programs,
     366registering object finalizers, constructing reference weakly held by
     367the garbage collector and others.
    241373% TODO document the THREADS package.
     380% TODO
     381%   1.  Create mechanism for swigging DocString and Lisp docs into
     382%       sections.
Note: See TracChangeset for help on using the changeset viewer.