Changeset 13646


Ignore:
Timestamp:
10/20/11 23:55:27 (9 years ago)
Author:
Mark Evenson
Message:

Getting out the burrs.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • branches/1.0.x/abcl/doc/manual/abcl.tex

    r13645 r13646  
    1818
    1919\subsection{Version}
    20 This manual corresponds to abcl-1.0.0, release on October 22, 2011.
     20This manual corresponds to abcl-1.0.0, released on October 22, 2011.
    2121
    2222\chapter{Running}
    2323
    2424\textsc{ABCL} is packaged as a single jar file usually named either
    25 ``abcl.jar'' or possibly``abcl-1.0.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
     25``abcl.jar'' or possibly``abcl-1.0.0.jar'' if one is using a versioned
     26package from your system vendor.  This byte archive can be executed
     27under the control of a suitable JVM by using the ``-jar'' option to
     28parse the manifest, and select the named class
    2929(\code{org.armedbear.lisp.Main}) for execution:
    3030
    3131\begin{listing-shell}
    32   cmd\$ java -jar abcl.jar
     32  cmd$ java -jar abcl.jar
    3333\end{listing-shell}
    3434
     
    4242
    4343\begin{listing-shell}
    44   cmd\$ abcl
     44  cmd$ abcl
    4545\end{listing-shell}
    4646
     
    9797\end{itemize}
    9898
    99 ABCL aims to be be a fully conforming ANSI Common Lisp
    100 implementation.  Any other behavior should be reported as a bug.
     99ABCL aims to be be a fully conforming ANSI Common Lisp implementation.
     100Any other behavior should be reported as a bug.
    101101
    102102\section{Contemporary Common Lisp}
    103103In addition to ANSI conformance, \textsc{ABCL} strives to implement features
    104104expected of a contemporary Common Lisp.
     105
     106\subsection{Deficiencies}
     107The following known problems detract from \textsc{ABCL} being a proper
     108contemporary Comon Lisp.
    105109\begin{itemize}
    106   \item Incomplete (A)MOP
     110  \item Incomplete (A)MOP \footnote{Another Metaobject Protocol}
    107111    % N.B.
    108112    % TODO go through AMOP with symbols, starting by looking for
     
    110114    % XXX is this really blocking ANSI conformance?  Answer: we have
    111115    % to start with such a ``census'' to determine what we have.
    112   \item Incomplete Streams:  need suitable abstraction between ANSI
    113     and Gray streams.
     116  \item Incomplete streams work, in that \textsc{ABCL} needs suitable
     117    abstraction between ANSI and Gray streams.
    114118   
    115119\end{itemize}
    116120
    117 \chapter{Interaction with host JVM}
     121\chapter{Interaction with Hosting JVM}
    118122
    119123% describe calling Java from Lisp, and calling Lisp from Java,
     
    121125% audience into those who are more comfortable with Java, and those
    122126% that are more comforable with Lisp
     127
     128The Armedbear Common Lisp implementation is hosted on a Java Virtual
     129Machine.  This chapter describes the mechanisms by which the
     130implementation interacts with that hosting mechanism.
    123131
    124132\section{Lisp to Java}
     
    177185returned.
    178186
    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.
     187Once one has a reference to the method, one may invoke it using
     188\code{JAVA:JCALL}, which takes the method as the first argument. The
     189second argument is the object instance to call the method on, or
     190\code{NIL} in case of a static method.  Any remaining parameters are
     191used as the remaining arguments for the call.
    183192
    184193\subsubsection{Calling Java object methods: dynamic dispatch}
     
    574583\subsubsection{Compilation}
    575584
    576 AbclScriptEngine implements the javax.script.Compilable
     585AbclScriptEngine implements the \code{javax.script.Compilable}
    577586interface. Currently it only supports compilation using temporary
    578587files. Compiled code, returned as an instance of
     
    669678\end{listing-lisp}
    670679
    671 NB \code{add-to-classpath} only affects the classloader used by ABCL
     680N.b \code{add-to-classpath} only affects the classloader used by ABCL
    672681(the value of the special variable \code{JAVA:*CLASSLOADER*}. It has
    673682no effect on Java code outside ABCL.
     
    680689\section{THREADS}
    681690
    682 Multithreading
     691The extensions for handling multithreaded execution are collected in
     692the \code{THREADS} package.  Most of the abstractions in Doug Lea's
     693excellent \code{java.util.concurrent} packages may be manipulated
     694directly via the JSS contrib to great effect.
    683695
    684696\subsection{API}
     
    730742representation is defined to be the NAMESTRING of the Pathname.
    731743
    732 PATHNAME : URL-PATHNAME : JAR-PATHNAME
    733 
    734 Both URL-PATHNAME and JAR-PATHNAME may be used anu where will a
    735 PATHNAME is accepted witht the following caveats
    736 
    737 A stream obtained via OPEN on a URL-PATHNAME cannot be the target of
    738 write operations.
    739 
    740 No canonicalization is performed on the underlying URI (i.e. the
     744\begin{verbatim}
     745  JAR-PATHNAME isa URL-PATHNAME isa PATHNAME
     746\end{verbatim}
     747
     748Both URL-PATHNAME and JAR-PATHNAME may be used anywhere a PATHNAME is
     749accepted with the following caveats:
     750
     751\begin{itemize}
     752
     753\item A stream obtained via OPEN on a URL-PATHNAME cannot be the
     754  target of write operations.
     755
     756\item No canonicalization is performed on the underlying URI (i.e. the
    741757implementation does not attempt to compute the current name of the
    742758representing resource unless it is requested to be resolved.)  Upon
    743759resolution, any cannoicalization procedures followed in resolving the
    744760resource (e.g. following redirects) are discarded. 
     761
     762\end{itemize}
    745763
    746764The implementation of URL-PATHNAME allows the ABCL user to laod dynamically
     
    864882\textsc{CLASS-FILE-DIRECTORY} and \textsc{MVN}.
    865883
     884
     885
     886\subsection{ABCL-ASDF Examples}
     887
     888\begin{listing-lisp}
     889    ;;;; -*- Mode: LISP -*-
     890    (in-package :asdf)
     891
     892    (defsystem :log4j
     893      :components ((:mvn "log4j/log4j"
     894                    :version "1.4.9")))
     895\end{listing-lisp}
     896
     897\subsection{abcl-asdf API}
     898
     899We define an API as consisting of the following ASDF classes:
     900
     901\textsc{JAR-DIRECTORY}, \textsc{JAR-FILE}, and
     902\textsc{CLASS-FILE-DIRECTORY} for JVM artifacts that have a currently
     903valid pathname representation
     904
     905And the MVN and IRI classes descend from ASDF-COMPONENT, but do not
     906directly have a filesystem location.
     907
     908For use outside of ASDF, we currently define one method,
     909\textsc{RESOLVE-DEPENDENCIES} which locates, downloads, caches, and then loads
     910into the currently executing JVM process all recursive dependencies
     911annotated in the Maven pom.xml graph.
     912
     913\subsection{ABCL-ASDF Example 2}
     914
     915Bypassing ASDF, one can directly issue requests for the Maven
     916artifacts to be downloaded
     917
     918\begin{listing-lisp}
     919    CL-USER> (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user")
     920    WARNING: Using LATEST for unspecified version.
     921    "/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"
     922\end{listing-lisp}
     923
     924To actually load the dependency, use the JAVA:ADD-TO-CLASSPATH generic
     925function:
     926
     927\begin{listing-lisp}
     928    CL-USER> (java:add-to-classpath (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user"))
     929\end{listing-lisp}
     930
     931Notice that all recursive dependencies have been located and installed
     932locally from the network as well.
     933
     934
    866935\section{asdf-jar}
    867936
     
    870939systems the code in this package will recursively package all the
    871940required source and fasls in a jar archive.
    872 
    873 
    874 
    875 \subsection{ABCL-ASDF Examples}
    876 
    877 \begin{listing-lisp}
    878     ;;;; -*- Mode: LISP -*-
    879     (in-package :asdf)
    880 
    881     (defsystem :log4j
    882       :components ((:mvn "log4j/log4j"
    883                     :version "1.4.9")))
    884 \end{listing-lisp}
    885 
    886 \subsection{abcl-asdf API}
    887 
    888 We define an API as consisting of the following ASDF classes:
    889 
    890 \textsc{JAR-DIRECTORY}, \textsc{JAR-FILE}, and
    891 \textsc{CLASS-FILE-DIRECTORY} for JVM artifacts that have a currently
    892 valid pathname representation
    893 
    894 And the MVN and IRI classes descend from ASDF-COMPONENT, but do not
    895 directly have a filesystem location.
    896 
    897 For use outside of ASDF, we currently define one method,
    898 \textsc{RESOLVE-DEPENDENCIES} which locates, downloads, caches, and then loads
    899 into the currently executing JVM process all recursive dependencies
    900 annotated in the Maven pom.xml graph.
    901 
    902 \subsection{ABCL-ASDF Example 2}
    903 
    904 Bypassing ASDF, one can directly issue requests for the Maven
    905 artifacts to be downloaded
    906 
    907 \begin{listing-lisp}
    908     CL-USER> (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user")
    909     WARNING: Using LATEST for unspecified version.
    910     "/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"
    911 \end{listing-lisp}
    912 
    913 To actually load the dependency, use the JAVA:ADD-TO-CLASSPATH generic
    914 function:
    915 
    916 \begin{listing-lisp}
    917     CL-USER> (java:add-to-classpath (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user"))
    918 \end{listing-lisp}
    919 
    920 Notice that all recursive dependencies have been located and installed
    921 locally from the network as well.
    922941
    923942\section{jss}
Note: See TracChangeset for help on using the changeset viewer.