Changeset 13338


Ignore:
Timestamp:
06/17/11 07:01:10 (12 years ago)
Author:
Mark Evenson
Message:

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.

Location:
trunk/abcl/doc/manual
Files:
4 added
1 edited

Legend:

Unmodified
Added
Removed

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

    r13335 r13338  
    1 % TODO
    2 %   1.  Create mechanism for swigging DocString and Lisp docs into
    3 %       sections.
    4 
    5 
    6 \documentclass[10pt]{article}
    7 
    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}
    13 
    14 \usepackage{a4wide}
     1% http://en.wikibooks.org/wiki/LaTeX/
     2
     3\include{index.sty}
    154
    165\begin{document}
    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}
    209
    … …  
    2615\section{Obtaining}
    2716
     17\subsection{Source Repositories}
     18
     19\begin[shell]{code}
     20  svn co http://svn.common-lisp.net/armedbear/trunk abcl
     21\end{code}
     22
    2823\subsection{Requirements}
    2924
    … …  
    3126
    3227\subsection{Building from Source}
    33 % TODO repeat install
     28
     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:
     31
     32\begin{itemize}
     33
     34\item Use the Ant build tool for Java environments.
     35
     36\item Use the Netbeans 6.x IDE to open ABCL as a project.
     37
     38\item Bootstrap ABCL using a Common Lisp implementation. Supported
     39  implementations for this process: SBCL, CMUCL, OpenMCL, Allegro
     40  CL, LispWorks or CLISP.
     41\end{itemize}
     42
     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.
     46
     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
     50environments.
     51
     52
     53\subsubsection{Using Ant}
     54
     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.
     58
     59[1]: http://ant.apache.org/bindownload.cgi
     60
     61Then simply executing
     62
     63\begin[shell]{code}
     64       unix$ ant
     65\end{code}
     66
     67or
     68
     69\begin[shell]{code}
     70    dos> ant.bat
     71\end{code}
     72
     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.
     76
     77
     78\subsubsection{Using NetBeans}
     79
     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.
     84
     85[2]: http://netbeans.org/downloads/
     86
     87
     88\subsubsection{Building from Lisp}
     89
     90
     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.
     96
     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).
     104
     105Then, one may either use the 'build-from-lisp.sh' shell script or load
     106the necessary files into your Lisp image by hand.
     107
     108\paragraph{Using the 'build-from-lisp.sh' script}
     109
     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.
     113
     114\begin[shell]{code}
     115    unix$ ./build-from-lisp.sh sbcl
     116\end{code}
     117
     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
     121build.
     122
     123If you're developing on ABCL, you may want to use
     124
     125\begin[shell]{code}
     126    unix$ ./build-from-lisp.sh <implementation> --clean=nil
     127\end{code}
     128
     129to not do a full rebuild.
     130
     131In case of failure in the javac stage, you might try this:
     132
     133\begin[shell]{code}
     134    unix$ ./build-from-lisp.sh <implementation> --full=t --clean=t --batch=nil
     135\end{code}
     136
     137This invokes javac separately for each .java file, which avoids running
     138into limitations on command line length (but is a lot slower).
     139
     140\subsubsubsection{Building from another Lisp by hand}
     141
     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
     144
     145\begin[lisp]{code}
     146    CL-USER> (build-abcl:build-abcl :clean t :full t)
     147\end{code}
     148
     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.
    34152
    35153\subsection{Contributing}
    … …  
    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
    55   (JAVA:JCALL, JAVA:JCALL-RAW, JAVA:JSTATIC)
    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).
    … …  
    67185
    68186\begin{itemize}
    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}
    81199
    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".
    88 
     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".
    89206
    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
     213
     214\begin[java]{code}
     215  import org.armedbear.lisp.*;
     216\end{document}
     217
     218to potentially import all the JVM symbol from the `org.armedbear.lisp'
     219namespace.
    95220
    96221Per JVM, there can only ever be a single Lisp interpreter.  This is
    97222started by calling the static method `Interpreter.createInstance()`.
    98223
    99 \begin{code}{java}
    100 Interpreter interpreter = Interpreter.createInstance();
     224\begin[java]{code}
     225  Interpreter interpreter = Interpreter.createInstance();
    101226\end{code}
    102227
    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:
    107232
    108 \begin{code}{java}
    109 Interpreter interpreter = Interpreter.getInstance();
    110 if (interpreter == null) {
    111   interpreter = Interpreter.createInstance();
    112 }
    113 \end{code}
    114 
    115 
    116 
    117 The Lisp `EVAL` primitive may be simply passed strings for evaluation,
     233\begin[java]{code}
     234  Interpreter interpreter = Interpreter.getInstance();
     235  if (interpreter == null) {
     236    interpreter = Interpreter.createInstance();
     237  }
     238\end{code}
     239
     240
     241
     242The Lisp \code{eval} primitive may be simply passed strings for evaluation,
    118243as follows
    119244
    120 \begin{code}{java}   
    121 String line = "(load \"file.lisp\")";
    122 LispObject result = interpreter.eval(line);
    123 \end{code}
    124 
     245\begin[java]{code}
     246  String line = "(load \"file.lisp\")";
     247  LispObject result = interpreter.eval(line);
     248\end{code}
    125249
    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)). 
    132256
    … …  
    137261parameters.
    138262
    139 \begin{code}{java}   
     263\begin[java]{code}
    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.
    154278
    155 \begin{code}{java}   
     279\begin[java]{code}
    156280    boolean nullp(LispObject object) {
    157281      LispObject result = Primitives.NULL.execute(object);
    … …  
    161285      return true;
    162286   }
    163 
    164 \end{code}
    165 
    166 /subsubsubsection{Introspecting a LispObject}
     287\end{code}
     288
     289\paragraph{Introspecting a LispObject}
     290\label{topic:Introspecting a LispObject}
    167291
    168292We present various patterns for introspecting an an arbitrary
    … …  
    170294into semantics that Java can meaniningfully deal with.
    171295
    172 /subsubsubsubsection{LispObject as \java{boolean}}
     296\paragragh{LispObject as \code{boolean}}
    173297
    174298If the LispObject a generalized boolean values, one can use
    175299\java{getBooleanValue()} to convert to Java:
    176300
    177 \begin{code}{java}
     301\begin[java]{code}
    178302     LispObject object = Symbol.NIL;
    179303     boolean javaValue = object.getBooleanValue();
    … …  
    183307use of Java equality it quite a bit easier and more optimal:
    184308
    185 \begin{code}{java}
     309\begin[java]{code}}
    186310    boolean javaValue = (object != Symbol.NIL);
    187311\end{code}
    188312
    189 /subsubsubsubsection{LispObject is a list}
     313\subsubsubsubsection{LispObject is a list}
    190314
    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
    193317iteration.
    194318
    195 \begin{code}{java}
     319\begin[java]{code}
    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:;
    205329
    206 \begin{code}{java}
     330\begin[java]{code}
    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.
    230356\end{itemize}
    231357
    … …  
    235361\section{Extensions}
    236362
    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.
     368
     369\include{extensions}
    238370
    239371\section{Multithreading}
    240372
    241373% TODO document the THREADS package.
     374\include{threads}
    242375
    243376\section{History}
    244377
    245378\end{document}
     379
     380% TODO
     381%   1.  Create mechanism for swigging DocString and Lisp docs into
     382%       sections.
     383
Note: See TracChangeset for help on using the changeset viewer.