Changeset 13683


Ignore:
Timestamp:
10/28/11 08:19:59 (9 years ago)
Author:
Mark Evenson
Message:

Grinding through filling in the manual.

File:
1 edited

Legend:

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

    r13680 r13683  
    66\begin{document}
    77\title{A Manual for Armed Bear Common Lisp}
    8 \date{October 27, 2011}
     8\date{October 28, 2011}
    99\author{Mark~Evenson, Erik~Huelsmann, Alessio~Stalla, Ville~Voutilainen}
    1010
     
    151151contemporary Comon Lisp.
    152152\begin{itemize}
     153
     154  \item An incomplete implementation of interactive debugging
     155    mechanisms namely a no-op version of
     156    \code{STEP} \footnote{Somewhat surprisingly allowed by
     157      \textsc{ANSI}}, the inability to inspect local variables in a
     158    given call frame, and the inability to resume a halted computation
     159    at an arbitrarily selected call frame.
     160
    153161  \item An incomplete implementation of a properly named metaobject
    154     protocol (viz. (A)MOP \footnote{Another Metaobject Protocol} )
     162    protocol (viz. (A)MOP \footnote{The Art of the Metaobject Protocol} )
    155163
    156164    % N.b.
     
    166174   
    167175  \item Incomplete documentation (missing docstrings from exported
    168       symbols.
     176    symbols and the draft status of the User Manual).
    169177
    170178\end{itemize}
     
    205213\subsection{Low-level Java API}
    206214
    207 We define a higher level Java API in the \ref{topic:Higher level Java
    208   API: JSS}(JSS package) which is available in the \code{contrib/}
    209 \ref{topic:contrib} directory . This package is described later in
    210 this document, see \ref{sec:jss} on page \pageref{sec:jss}.  This
    211 section covers the lower level API directly available after evaluating
    212 \code{(require 'JAVA)}.
     215We define a higher level Java API in the topic:Higher level Java JSS
     216package developed by Alan Ruttenberg which is available in the
     217\code{contrib/} directory, see the  . This package is
     218described later in this document, see \ref{section:jss} on page
     219\pageref{section:jss}.  This section covers the lower level API
     220directly available after evaluating \code{(require 'JAVA)}.
    213221
    214222\subsubsection{Calling Java Object Methods}
     
    937945
    938946The JSS contrib consitutes an additional, optional extension to the
    939 reader in the definition of the \#\" reader macro.
     947reader in the definition of the \#\" reader macro.  See
     948\ref{section:jss} on page \pageref{section:jss} for more information.
    940949
    941950\section{ASDF}
    942951
    943952asdf-2.017.22 is packaged as core component of ABCL, but not
    944 intialized by default, as it relies on the CLOS subsystem which can
    945 take a bit of time to initialize.  It may be initialized by the ANSI
    946 \textsc{REQUIRE} mechanism as follows:
     953initialized by default, as it relies on the CLOS subsystem which can
     954take a bit of time to start \footnote{While this time is ``merely'' on
     955  the order of seconds for contemporary 2011 machines, for
     956  applications that need to initialize quickly, for example a web
     957  server, this time might be unnecessarily long}.  ASDF may be loaded
     958by the \textsc{ANSI} \code{REQUIRE} mechanism as follows:
    947959
    948960\begin{listing-lisp}
     
    952964\chapter{Contrib}
    953965
     966The ABCL contrib is packaged as a separate jar archive usually named
     967\code{abcl-contrib.jar} or possibly something like
     968\code{abcl-contrib-1.0.0.jar}.  The contrib jar is not loaded by the
     969implementation by default, and must be first intialized by the
     970\code{REQUIRE} mechanism before using any specific contrib:
     971
     972\begin{listing-lisp}
     973CL-USER> (require 'abcl-contrib)
     974\end{listing-lisp}
     975
    954976\section{abcl-asdf}
    955977
    956 This contrib to ABCL enables an additional syntax for ASDF system
    957 definition which dynamically loads JVM artifacts such as jar archives
    958 via a Maven encapsulation.  The Maven Aether can also be directly
    959 manipulated by the function associated with the RESOLVE-DEPENDENCIES symbol.
    960 
    961 %ABCL specific contributions to ASDF system definition mainly concerned
    962 %with finding JVM artifacts such as jar archives to be dynamically loaded.
    963 
    964 
    965 The following ASDF components are added: \textsc{JAR-FILE}, \textsc{JAR-DIRECTORY},
    966 \textsc{CLASS-FILE-DIRECTORY} and \textsc{MVN}.
    967 
    968 
    969 
    970 \subsection{ABCL-ASDF Examples}
     978This contrib enables an additional syntax for \textsc{ASDF} system
     979definition which dynamically loads \textsc{JVM} artifacts such as jar
     980archives via encapsulation of the Maven build tool.  The Maven Aether
     981component can also be directly manipulated by the function associated
     982with the \code{ABCL-ASDF:RESOLVE-DEPENDENCIES} symbol.
     983
     984%ABCL specific contributions to ASDF system definition mainly
     985%concerned with finding JVM artifacts such as jar archives to be
     986%dynamically loaded.
     987
     988
     989The following \textsc{ASDF} components are added: \code{JAR-FILE},
     990\code{JAR-DIRECTORY}, \code{CLASS-FILE-DIRECTORY} and \code{MVN}.
     991
     992
     993\subsection{Referencing Maven Artifacts via ASDF}
     994
     995Maven artifacts may be referenced within \textsc{ASDF} system
     996definitions, as the following example references the
     997\code{log4j-1.4.9.jar} JVM artifact which provides a widely-used
     998abstraction for handling logging systems:
    971999
    9721000\begin{listing-lisp}
     
    9791007\end{listing-lisp}
    9801008
    981 \subsection{abcl-asdf API}
    982 
    983 We define an API as consisting of the following ASDF classes:
     1009\subsection{API}
     1010
     1011We define an API for \textsc{ABCL-ASDF} as consisting of the following
     1012ASDF classes:
    9841013
    9851014\textsc{JAR-DIRECTORY}, \textsc{JAR-FILE}, and
    9861015\textsc{CLASS-FILE-DIRECTORY} for JVM artifacts that have a currently
    987 valid pathname representation
    988 
    989 And the MVN and IRI classes descend from ASDF-COMPONENT, but do not
     1016valid pathname representation.
     1017
     1018Both the MVN and IRI classes descend from ASDF-COMPONENT, but do not
    9901019directly have a filesystem location.
    9911020
    992 For use outside of ASDF, we currently define one method,
    993 \textsc{RESOLVE-DEPENDENCIES} which locates, downloads, caches, and then loads
    994 into the currently executing JVM process all recursive dependencies
    995 annotated in the Maven pom.xml graph.
    996 
    997 \subsection{ABCL-ASDF Example 2}
    998 
    999 Bypassing ASDF, one can directly issue requests for the Maven
     1021For use outside of ASDF system definitions, we currently define one
     1022method, \textsc{ABCL-ASDF:RESOLVE-DEPENDENCIES} which locates,
     1023downloads, caches, and then loads into the currently executing JVM
     1024process all recursive dependencies annotated in the Maven pom.xml
     1025graph.
     1026
     1027\subsection{Directly Instructing Maven to Download JVM Artifacts}
     1028
     1029Bypassing \textsc{ASDF}, one can directly issue requests for the Maven
    10001030artifacts to be downloaded
    10011031
    10021032\begin{listing-lisp}
    1003     CL-USER> (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user")
    1004     WARNING: Using LATEST for unspecified version.
    1005     "/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"
    1006 \end{listing-lisp}
    1007 
    1008 To actually load the dependency, use the JAVA:ADD-TO-CLASSPATH generic
     1033CL-USER> (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user")
     1034WARNING: Using LATEST for unspecified version.
     1035"/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"
     1036\end{listing-lisp}
     1037
     1038To actually load the dependency, use the \code{JAVA:ADD-TO-CLASSPATH} generic
    10091039function:
    10101040
    10111041\begin{listing-lisp}
    1012     CL-USER> (java:add-to-classpath (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user"))
     1042CL-USER> (java:add-to-classpath (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user"))
    10131043\end{listing-lisp}
    10141044
     
    10161046locally from the network as well.
    10171047
    1018 
    10191048\section{asdf-jar}
    10201049
    1021 ASDF-JAR provides a system for packaging ASDF systems into jar
    1022 archives for ABCL.  Given a running ABCL image with loadable ASDF
     1050The asdf-jar contrib provides a system for packaging ASDF systems into
     1051jar archives for ABCL.  Given a running ABCL image with loadable ASDF
    10231052systems the code in this package will recursively package all the
    10241053required source and fasls in a jar archive.
    10251054
    10261055\section{jss}
    1027 \label{sec:jss}
    1028 
    1029 To one used to a syntax that can construct macros, the Java syntax
    1030 sucks, so we introduce the \#" macro.
     1056\label{section:jss}
     1057
     1058To one used to a syntax that can construct macros the Java syntax
     1059may be said to suck, so we introduce the \#" macro.
    10311060
    10321061\subsection{JSS usage}
     
    10351064
    10361065\begin{listing-lisp}
    1037   CL-USER> (require 'jss)
    1038 
    1039   CL-USER) (#"getProperties" 'java.lang.System)
    1040 
    1041   CL-USER) (#"propertyNames" (#"getProperties" 'java.lang.System))
     1066CL-USER> (require 'jss)
     1067
     1068CL-USER) (#"getProperties" 'java.lang.System)
     1069
     1070CL-USER) (#"propertyNames" (#"getProperties" 'java.lang.System))
    10421071\end{listing-lisp}
    10431072
    10441073\section{asdf-install}
    10451074
    1046 An implementation of ASDF-INSTALL.  Superseded by Quicklisp (qv.)
     1075The asdf-install contrib provides an implementation of ASDF-INSTALL.
     1076Superseded by Quicklisp (qv.)
    10471077
    10481078\chapter{History}
    10491079
    1050 ABCL was originally the extension language for the J editor, which was
     1080\textsc{ABCL} was originally the extension language for the J editor, which was
    10511081started in 1998 by Peter Graves.  Sometime in 2003, a whole lot of
    10521082code that had previously not been released publically was suddenly
     
    10631093
    10641094On October 22, 2011, with the publication of this Manual explicitly
    1065 stating the conformance of Armed Bear Common Lisp to ANSI, we released
     1095stating the conformance of Armed Bear Common Lisp to \textsc{ANSI}, we released
    10661096abcl-1.0.0.
    1067 
    1068 
    10691097
    10701098
Note: See TracChangeset for help on using the changeset viewer.