Changeset 13437


Ignore:
Timestamp:
08/04/11 16:04:45 (10 years ago)
Author:
Mark Evenson
Message:

Working through manual printing issues (incomplete).

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

Legend:

Unmodified
Added
Removed
  • trunk/abcl/doc/manual/abcl.tex

    r13415 r13437  
    11% http://en.wikibooks.org/wiki/LaTeX/
    2 
    3 \include{index.sty}
     2\include{index}
    43
    54\begin{document}
    65\title{A Manual for Armed Bear Common Lisp}
    7 \date{June 17, 2011}
     6\date{August 4, 2011}
    87\author{Mark Evenson, Erik Huelsmann, Alessio Stallo, Ville Voutilainen}
    98
    109\section{Introduction}
     10
     11Armed Bear is a mostly conforming implementation of the ANSI Common
     12Lisp standard.  This manual documents the Armed Bear Common Lisp
     13implementation for users of the system.
     14
    1115\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}
     16This manual corresponds to abcl-0.27.0, as yet unreleased.
     17
    15818
    15919\section{Interaction with host JVM}
     
    19454  corresponding Package.java instance.
    19555\item The Lisp dynamic environment may be saved via
    196   \code{LispThread.bindSpecial(BINDING)} and restored via
    197   LispThread.resetSpecialBindings(mark).
     56  \code{LispThread.bindSpecial(Binding)} and restored via
     57  \code{LispThread.resetSpecialBindings(Mark)}.
    19858\item Functions may be executed by invocation of the
    19959  Function.execute(args [...])
     
    20969needs to be "Interfaced".
    21070
    211 \subsubsubsection{Calling Lisp from Java}
     71\subsubsection{Calling Lisp from Java}
    21272
    21373Note: As the entire ABCL Lisp system resides in the org.armedbear.lisp
     
    21676statement would be
    21777
    218 \begin[java]{code}
     78\lstset{language=Java}
     79\begin{lstlisting}
    21980  import org.armedbear.lisp.*;
    220 \end{document}
     81\end{lstliting}
    22182
    22283to potentially import all the JVM symbol from the `org.armedbear.lisp'
     
    22687started by calling the static method `Interpreter.createInstance()`.
    22788
    228 \begin[java]{code}
     89\begin{code}[java]
    22990  Interpreter interpreter = Interpreter.createInstance();
    23091\end{code}
     
    23596safer invocation pattern might be:
    23697
    237 \begin[java]{code}
     98\begin{code}[java]
    23899  Interpreter interpreter = Interpreter.getInstance();
    239100  if (interpreter == null) {
     
    246107as follows
    247108
    248 \begin[java]{code}
     109\begin{code}[java]
    249110  String line = "(load \"file.lisp\")";
    250111  LispObject result = interpreter.eval(line);
     
    256117result of the computation might be, usually involves some amount
    257118of \code{instanceof} introspection, and forms a whole topic to itself
    258 (c.f. [Introspecting a LispObject](#introspecting)). 
     119(c.f. [Introspecting a LispObject])
    259120
    260121Using ``EVAL'' involves the Lisp interpreter.  Lisp functions may be
     
    264125parameters.
    265126
    266 \begin[java]{code}
     127\begin{code}[java]
    267128    interpreter.eval("(defun foo (msg) (format nil \"You told me '~A'~%\" msg))");
    268129    Package pkg = Packages.findPackage("CL-USER");
     
    280141tell if a `LispObject` contains a reference to a symbol.
    281142
    282 \begin[java]{code}
     143\begin{code}[java]
    283144    boolean nullp(LispObject object) {
    284145      LispObject result = Primitives.NULL.execute(object);
     
    297158into semantics that Java can meaniningfully deal with.
    298159
    299 \paragragh{LispObject as \code{boolean}}
     160\paragraph{LispObject as \code{boolean}}
    300161
    301162If the LispObject a generalized boolean values, one can use
    302 \java{getBooleanValue()} to convert to Java:
    303 
    304 \begin[java]{code}
     163\code{getBooleanValue()} to convert to Java:
     164
     165\begin{code}[java]
    305166     LispObject object = Symbol.NIL;
    306167     boolean javaValue = object.getBooleanValue();
     
    310171use of Java equality it quite a bit easier and more optimal:
    311172
    312 \begin[java]{code}}
     173\begin{code}[java]
    313174    boolean javaValue = (object != Symbol.NIL);
    314175\end{code}
    315176
    316 \subsubsubsubsection{LispObject is a list}
     177\paragraph{LispObject is a list}
    317178
    318179If LispObject is a list, it will have the type `Cons`.  One can then use
     
    320181iteration.
    321182
    322 \begin[java]{code}
     183\begin{code}[java]
    323184    LispObject result = interpreter.eval("'(1 2 4 5)");
    324185    if (result instanceof Cons) {
     
    331192function just as like one would traverse a list in Lisp:;
    332193
    333 \begin[java]{code}
     194\begin{code}[java]
    334195    LispObject result = interpreter.eval("'(1 2 4 5)");
    335196    while (result != Symbol.NIL) {
     
    382243
    383244There 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
     245generic function on a java class, viz. \code{(java:jclass CLASS-STRING)}
     246where \code{CLASS-STRING} is a string naming a Java class in dotted package
    386247form.
    387248
     
    390251object
    391252
    392 \begin[java]{code}
     253\begin{code}[lisp]
    393254(defmethod print-object ((coll (java:jclass "java.util.Collection")) stream)
    394  â€Š
    395  \end[java]{code}
     255\ldots
     256\end{code}
    396257
    397258If the class had been loaded via a classloader other than the original
     
    399260classloader as an optional third argument.
    400261
    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}
     262\begin{code}[lisp]
     263(defmethod print-object ((device-id (java:jclass "dto.nbi.service.hdm.alcatel.com.nNBIDeviceID"
     264                                    (\#"getBaseLoader" cl-user::*classpath-manager*)))
     265\ldots
     266\end{code}
    406267
    407268\subsubsection{Extensions to the Reader}
     
    409270We implement a special hexadecimal escape sequence for specifying
    410271characters 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
     272\# \textbackslash Uxxxx to be processed by the reader as character whose code is
     273specified by the hexadecimal digits ``xxxx''.  The hexadecimal sequence
    413274must be exactly four digits long, padded by leading zeros for values
    414275less than 0x1000.
  • trunk/abcl/doc/manual/extensions.tex

    r13338 r13437  
     1\begin{verbatim}
    12%CADDR
    23  Function: (not documented)
     
    247248WEAK-REFERENCE-VALUE
    248249  Function: (not documented)
     250\end{verbatim}
  • trunk/abcl/doc/manual/index.tex

    r13436 r13437  
    1515\usepackage{a4wide}
    1616
     17\newcommand{\code}[1]{
     18  \texttt{#1}
     19}
     20
     21\usepackage{listings}
     22
     23
     24\newenvironment{xx}[1]%
     25               {\begin{lstlisting} }%
     26               {\end{lstlisting}}
     27
     28\usepackage{verbatim}
     29
  • trunk/abcl/doc/manual/java.tex

    r13341 r13437  
     1\begin{verbatim}
    12%JGET-PROPERTY-VALUE
    23  Function: Gets a JavaBeans property on JAVA-OBJECT.
     
    147148UNREGISTER-JAVA-EXCEPTION
    148149  Function: Unregisters the Java Throwable EXCEPTION-NAME previously registered by REGISTER-JAVA-EXCEPTION.
     150\end{verbatim}
  • trunk/abcl/doc/manual/threads.tex

    r13338 r13437  
     1\begin{verbatim}
    12THREADS:CURRENT-THREAD
    23  Function: (not documented)
     
    4950THREADS:WITH-THREAD-LOCK
    5051  Function: (not documented)
     52\end{verbatim}
Note: See TracChangeset for help on using the changeset viewer.