Changeset 13660


Ignore:
Timestamp:
10/21/11 21:28:49 (12 years ago)
Author:
Mark Evenson
Message:

Merge from abcl-20111021b Draft from 1.0.x branch.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r13657 r13660  
    66\begin{document}
    77\title{A Manual for Armed Bear Common Lisp}
    8 \date{October 20, 2011}
     8\date{October 21, 2011}
    99\author{Mark~Evenson, Erik~Huelsmann, Alessio~Stalla, Ville~Voutilainen}
    1010
    … …  
    1313\chapter{Introduction}
    1414
    15 Armed Bear is a mostly conforming implementation of the ANSI Common
     15Armed Bear is a (mostly) conforming implementation of the ANSI Common
    1616Lisp standard.  This manual documents the Armed Bear Common Lisp
    1717implementation for users of the system.
    1818
    1919\subsection{Version}
    20 This manual corresponds to abcl-0.28.0, as yet unreleased.
     20This manual corresponds to abcl-1.0.0, released on October 22, 2011.
     21
     22\subsection{License}
     23
     24The implementation is licensed under the terms of the GPL v2 of June
     251991 with the ``classpath-exception'' that makes its deployment in
     26commercial settings quite reasonable.  The license is viral in the
     27sense that if you change the implementation, and redistribute those
     28changes, you are required to provide the source to those changes back
     29to be merged with the public trunk.
     30
     31\subsection{Contributors}
     32
     33% TODO format this better, optionally link to URI
     34
     35% Thanks for the markup
     36Philipp Marek
     37
     38% Thanks for the whacky IKVM stuff and keeping the flame alive
     39Douglas Miles
     40
     41% Thanks for JSS
     42Alan Ruttenberg
     43
     44and of course
     45
     46Peter Graves
    2147
    2248\chapter{Running}
    2349
    2450\textsc{ABCL} is packaged as a single jar file usually named either
    25 ``abcl.jar'' or possibly``abcl-0.28.0.jar'' if you are using a
    26 versioned package from your system vendor.  This byte archive can be
    27 executed under the control of a suitable JVM by using the ``-jar''
    28 option to parse the manifest, and select the named class
    29 (\code{org.armedbear.lisp.Main}) for execution:
     51``abcl.jar'' or possibly``abcl-1.0.0.jar'' if one is using a versioned
     52package from your system vendor.  This byte archive can be executed
     53under the control of a suitable JVM by using the ``-jar'' option to
     54parse the manifest, and select the named class
     55(\code{org.armedbear.lisp.Main}) for execution, viz:
    3056
    3157\begin{listing-shell}
    … …  
    3662to be in your path.
    3763
    38 To make it easier to facilitate the use of ABCL in tool chains (such as
    39 SLIME) the invocation is wrapped in a Bourne shell script under UNIX
    40 or a DOS command script under Windows so that ABCL may be executed
    41 simply as:
     64To make it easier to facilitate the use of ABCL in tool chains (such
     65as SLIME \footnote{SLIME is the Superior Lisp Mode for Interaction
     66  under Emacs}) the invocation is wrapped in a Bourne shell script
     67under UNIX or a DOS command script under Windows so that ABCL may be
     68executed simply as:
    4269
    4370\begin{listing-shell}
    … …  
    7299\end{verbatim}
    73100
    74 All of the command line arguments which follow the occurrence of ``--''
     101All of the command line arguments which follow the occurrence of ``----''
    75102are passed into a list bound to the EXT:*COMMAND-LINE-ARGUMENT-LIST*
    76103variable.
    … …  
    83110
    84111The user's home directory is determined by the value of the JVM system
    85 property ``user.home''.
     112property ``user.home''.  This value may--or may not--correspond to the
     113value of the HOME system environment variable at the discretion of the
     114JVM implementation that \textsc{ABCL} finds itself hosted upon.
    86115
    87116\chapter{Conformance}
    88117
    89118\section{ANSI Common Lisp}
    90 \textsc{ABCL} is currently a non-conforming ANSI Common Lisp implementation due
    91 to the following issues:
     119\textsc{ABCL} is currently a (non)-conforming ANSI Common Lisp
     120implementation due to the following known issues:
    92121
    93122\begin{itemize}
    94123  \item The generic function signatures of the DOCUMENTATION symbol do
    95124    not match the CLHS.
    96   \item The TIME form does not return a proper VALUES to its caller.
     125  \item The TIME form does not return a proper VALUES environment to
     126    its caller.
    97127\end{itemize}
    98128
    99 ABCL aims to be be a fully conforming ANSI Common Lisp
    100 implementation.  Any other behavior should be reported as a bug.
     129Somewhat confusingly, this statement of non-conformance in the
     130accompanying user documentation fullfills the requirements that
     131\textsc{ABCL} is a conforming ANSI Common Lisp implementation
     132according to the CLHS \footnote{Common Lisp Hyperspec language
     133  reference document.}.  Clarifications to this point are solicited.
     134
     135ABCL aims to be be a fully conforming ANSI Common Lisp implementation.
     136Any other behavior should be reported as a bug.
    101137
    102138\section{Contemporary Common Lisp}
    103139In addition to ANSI conformance, \textsc{ABCL} strives to implement features
    104 expected of a contemporary Common Lisp.
     140expected of a contemporary Common Lisp \footnote{i.e. a Lisp of the
     141  post 2005 Renaissance}
     142
     143\subsection{Deficiencies}
     144The following known problems detract from \textsc{ABCL} being a proper
     145contemporary Comon Lisp.
    105146\begin{itemize}
    106   \item Incomplete (A)MOP
    107     % N.B.
     147  \item An incomplete implementation of a properly named metaobject
     148    protocol (viz. (A)MOP \footnote{Another Metaobject Protocol} )
     149
     150    % N.b.
    108151    % TODO go through AMOP with symbols, starting by looking for
    109152    % matching function signature.
    110153    % XXX is this really blocking ANSI conformance?  Answer: we have
    111154    % to start with such a ``census'' to determine what we have.
    112   \item Incomplete Streams:  need suitable abstraction between ANSI
    113     and Gray streams.
     155
     156  \item Incomplete streams abstraction, in that \textsc{ABCL} needs suitable
     157    abstraction between ANSI and Gray streams.  The streams could be
     158    optimized to the JVM NIO abstractions at great profit for binary
     159    byte-level manipulations.
    114160   
     161  \item Incomplete documentation (missing docstrings from exported
     162      symbols.
     163
    115164\end{itemize}
    116165
    117 \chapter{Interaction with host JVM}
    118 
     166\chapter{Interaction with Hosting JVM}
     167
     168%  Plan of Attack
     169%
    119170% describe calling Java from Lisp, and calling Lisp from Java,
    120171% probably in two separate sections.  Presumably, we can partition our
    121172% audience into those who are more comfortable with Java, and those
    122173% that are more comforable with Lisp
     174
     175The Armed Bear Common Lisp implementation is hosted on a Java Virtual
     176Machine.  This chapter describes the mechanisms by which the
     177implementation interacts with that hosting mechanism.
    123178
    124179\section{Lisp to Java}
    … …  
    144199\subsection{Low-level Java API}
    145200
    146 There's a higher level Java API defined in the
    147 \ref{topic:Higher level Java API: JSS}(JSS package) which is available
    148 in the \code{contrib/} directory. This package is described later in this
    149 document.  This section covers the lower level API directly available
    150 after evaluating \code{(require 'JAVA)}.
    151 
    152 \subsubsection{Calling Java object methods}
    153 
    154 There are two ways to call a Java object method in the basic API:
     201We define a higher level Java API in the \ref{topic:Higher level Java
     202  API: JSS}(JSS package) which is available in the \code{contrib/} \ref{topic:contrib}
     203directory. This package is described later in this document.  This
     204section covers the lower level API directly available after evaluating
     205\code{(require 'JAVA)}.
     206
     207\subsubsection{Calling Java Object Methods}
     208
     209There are two ways to call a Java object method in the low-level (basic) API:
    155210
    156211\begin{itemize}
    … …  
    177232returned.
    178233
    179 Once you have a reference to the method, you can call it using \code{JAVA:JCALL},
    180 which takes the method as the first argument. The second argument is the
    181 object instance to call the method on, or \code{NIL} in case of a static method.
    182 Any remaining parameters are used as the remaining arguments for the call.
     234Once one has a reference to the method, one may invoke it using
     235\code{JAVA:JCALL}, which takes the method as the first argument. The
     236second argument is the object instance to call the method on, or
     237\code{NIL} in case of a static method.  Any remaining parameters are
     238used as the remaining arguments for the call.
    183239
    184240\subsubsection{Calling Java object methods: dynamic dispatch}
    … …  
    191247select the best matching method and dispatch the call.
    192248
    193 \subsubsection{Dynamic dispatch: caveats}
     249\subsubsection{Dynamic dispatch: Caveats}
    194250
    195251Dynamic dispatch is performed by using the Java reflection
    … …  
    212268\begin{listing-java}
    213269java.lang.IllegalAccessException: Class ... can
    214 not access a member of class java.util.zip.ZipFile$2 with modifiers
     270not access a member of class java.util.zip.ZipFile\$2 with modifiers
    215271"public"
    216272       at sun.reflect.Reflection.ensureMemberAccess(Reflection.java:65)
    … …  
    318374an intended class around and values which can be converted to Lisp values will
    319375be converted.
    320 
    321376
    322377\section{Lisp from Java}
    … …  
    596651\subsubsection{Compilation}
    597652
    598 AbclScriptEngine implements the javax.script.Compilable
     653AbclScriptEngine implements the \code{javax.script.Compilable}
    599654interface. Currently it only supports compilation using temporary
    600655files. Compiled code, returned as an instance of
    … …  
    691746\end{listing-lisp}
    692747
    693 NB \code{add-to-classpath} only affects the classloader used by ABCL
     748N.b \code{add-to-classpath} only affects the classloader used by ABCL
    694749(the value of the special variable \code{JAVA:*CLASSLOADER*}. It has
    695750no effect on Java code outside ABCL.
    … …  
    702757\section{THREADS}
    703758
    704 Multithreading
     759The extensions for handling multithreaded execution are collected in
     760the \code{THREADS} package.  Most of the abstractions in Doug Lea's
     761excellent \code{java.util.concurrent} packages may be manipulated
     762directly via the JSS contrib to great effect.
    705763
    706764\subsection{API}
    … …  
    740798\section{Pathname}
    741799
    742 We implment an extension to the Pathname that allows for the
     800We implement an extension to the Pathname that allows for the
    743801description and retrieval of resources named in a URI scheme that the
    744802JVM ``understands''.  Support is built-in to the ``http'' and
    … …  
    752810representation is defined to be the NAMESTRING of the Pathname.
    753811
    754 PATHNAME : URL-PATHNAME : JAR-PATHNAME
    755 
    756 Both URL-PATHNAME and JAR-PATHNAME may be used anu where will a
    757 PATHNAME is accepted witht the following caveats
    758 
    759 A stream obtained via OPEN on a URL-PATHNAME cannot be the target of
    760 write operations.
    761 
    762 No canonicalization is performed on the underlying URI (i.e. the
     812\begin{verbatim}
     813  JAR-PATHNAME isa URL-PATHNAME isa PATHNAME
     814\end{verbatim}
     815
     816Both URL-PATHNAME and JAR-PATHNAME may be used anywhere a PATHNAME is
     817accepted with the following caveats:
     818
     819\begin{itemize}
     820
     821\item A stream obtained via OPEN on a URL-PATHNAME cannot be the
     822  target of write operations.
     823
     824\item No canonicalization is performed on the underlying URI (i.e. the
    763825implementation does not attempt to compute the current name of the
    764826representing resource unless it is requested to be resolved.)  Upon
    … …  
    766828resource (e.g. following redirects) are discarded. 
    767829
     830\end{itemize}
     831
    768832The implementation of URL-PATHNAME allows the ABCL user to laod dynamically
    769833code from the network.  For example, for Quicklisp.
    … …  
    776840
    777841\ref{XACH2011}
     842
     843\subsubsection{Implementation}
     844
     845\textsc{DEVICE} either a string denoting a drive letter under DOS or a cons
     846specifying a \textsc{URL-PATHNAME}.
    778847         
    779848\section{Extensible Sequences}
    … …  
    845914We implement a special hexadecimal escape sequence for specifying
    846915characters to the Lisp reader, namely we allow a sequences of the form
    847 \# \textbackslash Uxxxx to be processed by the reader as character whose code is
    848 specified by the hexadecimal digits ``xxxx''.  The hexadecimal sequence
    849 must be exactly four digits long, padded by leading zeros for values
    850 less than 0x1000.
     916\# \textbackslash Uxxxx to be processed by the reader as character
     917whose code is specified by the hexadecimal digits ``xxxx''.  The
     918hexadecimal sequence must be exactly four digits long \footnote{This
     919  represents a compromise with contemporary in 2011 32bit hosting
     920  architecures for which we wish to make text processing efficient.
     921  Should the User require more control over UNICODE processing we
     922  recommend Edi Weisz' excellent work with FLEXI-STREAMS which we
     923  fully support}, padded by leading zeros for values less than 0x1000.
    851924
    852925Note that this sequence is never output by the implementation.  Instead,
    … …  
    857930
    858931The JSS contrib consitutes an additional, optional extension to the
    859 reader in the definition of the #\" reader macro.
     932reader in the definition of the \#\" reader macro.
    860933
    861934\section{ASDF}
    862935
    863 asdf-2.017 is packaged as core component of ABCL, but not intialized
    864 by default, as it relies on the CLOS subsystem which can take a bit of
    865 time to initialize.  It may be initialized by the ANSI
     936asdf-2.017.22 is packaged as core component of ABCL, but not
     937intialized by default, as it relies on the CLOS subsystem which can
     938take a bit of time to initialize.  It may be initialized by the ANSI
    866939\textsc{REQUIRE} mechanism as follows:
    867940
    … …  
    876949This contrib to ABCL enables an additional syntax for ASDF system
    877950definition which dynamically loads JVM artifacts such as jar archives
    878 via a Maven encapsulation.
    879 
    880 The following ASDF components are added:  JAR-FILE, JAR-DIRECTORY, CLASS-FILE-DIRECTORY
    881 and MVN.
     951via a Maven encapsulation.  The Maven Aether can also be directly
     952manipulated by the function associated with the RESOLVE-DEPENDENCIES symbol.
     953
     954%ABCL specific contributions to ASDF system definition mainly concerned
     955%with finding JVM artifacts such as jar archives to be dynamically loaded.
     956
     957
     958The following ASDF components are added: \textsc{JAR-FILE}, \textsc{JAR-DIRECTORY},
     959\textsc{CLASS-FILE-DIRECTORY} and \textsc{MVN}.
     960
     961
     962
     963\subsection{ABCL-ASDF Examples}
     964
     965\begin{listing-lisp}
     966    ;;;; -*- Mode: LISP -*-
     967    (in-package :asdf)
     968
     969    (defsystem :log4j
     970      :components ((:mvn "log4j/log4j"
     971                    :version "1.4.9")))
     972\end{listing-lisp}
     973
     974\subsection{abcl-asdf API}
     975
     976We define an API as consisting of the following ASDF classes:
     977
     978\textsc{JAR-DIRECTORY}, \textsc{JAR-FILE}, and
     979\textsc{CLASS-FILE-DIRECTORY} for JVM artifacts that have a currently
     980valid pathname representation
     981
     982And the MVN and IRI classes descend from ASDF-COMPONENT, but do not
     983directly have a filesystem location.
     984
     985For use outside of ASDF, we currently define one method,
     986\textsc{RESOLVE-DEPENDENCIES} which locates, downloads, caches, and then loads
     987into the currently executing JVM process all recursive dependencies
     988annotated in the Maven pom.xml graph.
     989
     990\subsection{ABCL-ASDF Example 2}
     991
     992Bypassing ASDF, one can directly issue requests for the Maven
     993artifacts to be downloaded
     994
     995\begin{listing-lisp}
     996    CL-USER> (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user")
     997    WARNING: Using LATEST for unspecified version.
     998    "/Users/evenson/.m2/repository/com/google/gwt/gwt-user/2.4.0-rc1/gwt-user-2.4.0-rc1.jar:/Users/evenson/.m2/repository/javax/validation/validation-api/1.0.0.GA/validation-api-1.0.0.GA.jar:/Users/evenson/.m2/repository/javax/validation/validation-api/1.0.0.GA/validation-api-1.0.0.GA-sources.jar"
     999\end{listing-lisp}
     1000
     1001To actually load the dependency, use the JAVA:ADD-TO-CLASSPATH generic
     1002function:
     1003
     1004\begin{listing-lisp}
     1005    CL-USER> (java:add-to-classpath (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user"))
     1006\end{listing-lisp}
     1007
     1008Notice that all recursive dependencies have been located and installed
     1009locally from the network as well.
     1010
    8821011
    8831012\section{asdf-jar}
    … …  
    8881017required source and fasls in a jar archive.
    8891018
    890 \section{abcl-asdf}
    891 
    892 ABCL specific contributions to ASDF system definition mainly concerned
    893 with finding JVM artifacts such as jar archives to be dynamically loaded.
    894 
    895 \subsection{ABCL-ASDF Examples}
    896 
    897 \begin{listing-lisp}
    898     ;;;; -*- Mode: LISP -*-
    899     (in-package :asdf)
    900 
    901     (defsystem :log4j
    902       :components ((:mvn "log4j/log4j"
    903                     :version "1.4.9")))
    904 \end{listing-lisp}
    905 
    906 \subsection{abcl-asdf API}
    907 
    908 We define an API as consisting of the following ASDF classes:
    909 
    910 \textsc[JAR-DIRECTORY}, \textsc{JAR-FILE}, and
    911 \textsc{CLASS-FILE-DIRECTORY} for JVM artifacts that have a currently
    912 valid pathname representation
    913 
    914 And the MVN and IRI classes descend from ASDF-COMPONENT, but do not
    915 directly have a filesystem location.
    916 
    917 For use outside of ASDF, we currently define one method,
    918 \textsc{RESOLVE-DEPENDENCIES} which locates, downloads, caches, and then loads
    919 into the currently executing JVM process all recursive dependencies
    920 annotated in the Maven pom.xml graph.
    921 
    922 \subsection{ABCL-ASDF Example 2}
    923 
    924 Bypassing ASDF, one can directly issue requests for the Maven
    925 artifacts to be downloaded
    926 
    927 \begin{listing-lisp}
    928     CL-USER> (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user")
    929     WARNING: Using LATEST for unspecified version.
    930     "/Users/evenson/.m2/repository/com/google/gwt/gwt-user/2.4.0-rc1/gwt-user-2.4.0-rc1.jar:/Users/evenson/.m2/repository/javax/validation/validation-api/1.0.0.GA/validation-api-1.0.0.GA.jar:/Users/evenson/.m2/repository/javax/validation/validation-api/1.0.0.GA/validation-api-1.0.0.GA-sources.jar"
    931 \end{listing-lisp}
    932 
    933 Notice that all recursive dependencies have been located and installed
    934 as well.
    935 
    936 
    9371019\section{jss}
    9381020
    … …  
    9591041
    9601042ABCL was originally the extension language for the J editor, which was
    961 started in 1998 by Peter Graves.  Sometime in 2003, it seems that a
    962 lot of code that had previously not been released publically was
    963 suddenly committed that enabled ABCL to be plausibly termed an ANSI
    964 Common Lisp implementation.
     1043started in 1998 by Peter Graves.  Sometime in 2003, a whole lot of
     1044code that had previously not been released publically was suddenly
     1045committed that enabled ABCL to be plausibly termed an emergent ANSI
     1046Common Lisp implementation canidate.
     1047
     1048From 2006 to 2008, Peter manned the development lists, incorporating
     1049patches as made sense.  After a suitable search, Peter nominated Erik
     1050Huelsmann to take over the project.
    9651051
    9661052In 2008, the implementation was transferred to the current
    … …  
    9681054contemporary Common Lisp implementation.
    9691055
    970 In 201x, with the publication of this Manual explicitly stating the
    971 conformance of Armed Bear Common Lisp to ANSI, we release abcl-1.0.
     1056On October 22, 2011, with the publication of this Manual explicitly
     1057stating the conformance of Armed Bear Common Lisp to ANSI, we released
     1058abcl-1.0.0.
    9721059
    9731060
    … …  
    9821069libraries.  \url{http://www.quicklisp.org/}
    9831070
     1071[RHODES2007]:  Christopher Rhodes
     1072
    9841073
    9851074\end{document}
    … …  
    9871076% TODO
    9881077%   1.  Create mechanism for swigging DocString and Lisp docs into
    989 %       sections.
    990 
     1078%       sections ('grovel.lisp')
     1079
Note: See TracChangeset for help on using the changeset viewer.