source: trunk/abcl/doc/manual/abcl.tex @ 13334

Last change on this file since 13334 was 13334, checked in by Mark Evenson, 10 years ago

Start outlining highlights of Lisp's interactions with Java.

File size: 3.2 KB
Line 
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}
15
16\begin{document}
17\title{A Manual for Armed Bear Common Lisp}
18\date{June 16, 2011}
19\author{Mark Evenson, Erik Huelsmann, Alessio Stallo, Ville Voutilainen}
20
21\section{Introduction}
22\subsection{Version}
23
24This manual corresponds to abcl-0.26.0, as yet unreleased.
25
26\section{Obtaining}
27
28\subsection{Requirements}
29
30java-1.5.xx, java-1.6.0_10+ recommended.
31
32\subsection{Building from Source}
33% TODO repeat install
34
35\subsection{Contributing}
36
37\section{Interaction with host JVM}
38
39% describe calling Java from Lisp, and calling Lisp from Java,
40% probably in two separate sections.  Presumably, we can partition our
41% audience into those who are more comfortable with Java, and those
42% that are more comforable with Lisp
43
44\subsection{Lisp to Java}
45
46ABCL offers a number of mechanisms to manipulate Java libraries from
47Lisp.
48
49\begin{itemize}
50\item Java values are accessible as objects of type JAVA:JAVA-OBJECT.
51\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.
59\item Java classes and libraries may be dynamically added to the
60  classpath at runtime (JAVA:ADD-TO-CLASSPATH).
61\end{itemize}
62
63\subsection{Lisp from Java}
64
65Manipulation of the Lisp API is currently lacking a stable interface,
66so what is documented here is subject to change. 
67
68\begin{itemize}
69\item All Lisp values are descendents of LispObject.java
70\item Lisp symbols are accessible via either directly referening the
71  Symbol.java instance or by dynamically introspecting the
72  corresponding Package.java instance.
73\item The Lisp dynamic envrionment may be saved via
74  LispThread.bindSpecial(BINDING) and restored via
75  LispThread.resetSpecialBindings(mark).
76\item Functions may be executed by invocation of the
77  Function.execute(args [...])
78\end{itemize}
79
80\subsection{JAVA}
81
82% include autogen docs for the JAVA package.
83
84\section{ANSI Common Lisp Conformance}
85
86ABCL is currently a non-conforming ANSI Common Lisp implementation due
87to the following (known) issues:
88
89\begin{itemize}
90  \item Lack of long form of DEFINE-METHOD-COMBINATION
91  \item Missing statement of conformance in accompanying documentation
92  \item Incomplete MOP
93    % TODO go through AMOP with symbols, starting by looking for
94    % matching function signature.
95\end{itemize}
96
97ABCL aims to be be a fully conforming ANSI Common Lisp
98implementation.  Any other behavior should be reported as a bug.
99
100\section{Extensions}
101
102% TODO document the EXTENSIONS package.
103
104\section{Multithreading}
105
106% TODO document the THREADS package.
107
108\section{History}
109
110\end{document}
Note: See TracBrowser for help on using the repository browser.