Commit 6738a873 authored by Mark Evenson's avatar Mark Evenson Committed by GitHub

Merge pull request #126 from easye/easye/doc

Easye/doc
parents 4d16d099 236859fd
......@@ -77,10 +77,11 @@ test suite.
Armed Bear Common Lisp (\textsc{ABCL}) is an implementation of
\textsc{Common Lisp} that runs on the Java Virtual Machine
(\textsc{JVM}). \textsc{ABCL} compiles \textsc{Common Lisp} to
\textsc{Java} byte-code\footnote{The class file version is ``49.0''.},
with an efficiency that varies upon the hosting JVM implementation.
\textsc{ABCL} supports running on the Java 6, Java 7, Java 8, and Java
11 \textsc{JVM} implementations.
\textsc{Java} byte-code\footnote{The class files produced by the
compiler have a bytecode version of ``49.0''.}, with an efficiency
that varies upon the hosting JVM implementation. \textsc{ABCL}
supports running on the Java 6, Java 7, Java 8, and Java 11
\textsc{JVM} implementations.
Armed Bear provides the following integration methods for interfacing
with Java code and libraries:
......@@ -910,12 +911,20 @@ implementation, \textsc{ABCL} endeavors to include extensions beyond the ANSI
specification which are either widely adopted or are especially useful
in working with the hosting \textsc{JVM}.
\section{Compiler to Java 5 Bytecode}
\section{Compiler to Java Virtual Machine Bytecode}
The \code{CL:COMPILE-FILE} interface emits a packed fasl format whose
Pathname has the type ``abcl''. These fasls are operating system neutral
byte archives packaged by the zip compression format which contain
artifacts whose loading \code{CL:LOAD} understands.
The \code{CL:COMPILE-FILE} interface emits a packed fasl\footnote{The
term ``fasl'' is short for ``fast loader'', which in \textsc{Common
Lisp} implementations refers} format whose \code{CL:PATHNAME} has
the \code{TYPE} ``abcl''. Structurally, \textsc{ABCL}'s fasls are an
operating system neutral byte archives packaged in the zip compression
format which contain artifacts whose loading \code{CL:LOAD}
understands. Internally, our fasls contain a piece of Lisp that
\code{CL:LOAD} interprets as instructions to load the Java classes
emitted by the \textsc{ABCL} Lisp compiler. These ``synthetic''
classes have a JVM class file version of ``49.0''.
% TODO check on what the compiler is currently emitting
\subsection{Compiler Diagnostics}
......
#+TITLE: Notes Packaging ABCL for Distribution
* abcl-aio
The standard ABCL build process as described in the ~build.xml~ file
and executed by the Ant build tool results in two artifacts:
~abcl.jar~ and ~abcl-contrib.jar~. ~abcl.jar~ contains all the Java
and Common Lisp code necessary that constitute the ANSI conforming
implementation runtime. The ~abcl-contrib.jar~ (aka "contrib")
artifact contains additional Common Lisp-only code that extends the
implementation in useful manners.
We create two separate jar artifacts in order to:
1. To place an upper bound of size of ~abcl.jar~ regardless of what we
package in ~abcl-contrib.jar~.
2. Clearly mark which parts of the code-base are covered under
GPLv2+classpath from those that may have other licensing terms. By
making the loading of "contrib" a dynamic operation, we defer
possible infringement to the User who redistributes the resulting
jar artifact.
Users often want to simply package both artifacts in a single jar for
deployment convenience. abcl-1.5.0 introduced the build machinery to
create such an "all-in-one" artifact via the [[https://github.com/armedbear/abcl/blob/master/build.xml#L517][~abcl-aio.jar~]] target.
Upon invoking the ~abcl-aio.jar~ target
#+begin_src shell
ant -f build.xml abcl-aio.jar
#+end_src
the resulting artifact contains both the core implementation and the
ABCL contrib which may be run as usual via
#+begin_src shell
java -jar dist/abcl-aio.jar
#+end_src
* abcl-jar contrib
The ABCL-JAR contrib provides a mechanism for package ASDF systems and
their recursive dependencies in a jar archive.
An example of using this to package the CL-PPCRE system from Quicklisp
#+begin_src lisp
;;
(require :abcl-contrib)
(require :quicklisp-abcl)
(ql:quickload :cl-ppcre)
(require :asdf-jar)
(asdf-jar:package :cl-ppcre)
#+end_src
results in a jar archive at something like
~#P"/var/tmp/cl-ppcre-all-2.1.1.jar"~.
This jar archive may be loaded in a version of the implementation via
#+begin_src lisp
(require :abcl-contrib)
(require :asdf-jar)
(setf *load-verbose* t) ;; so we can verify where the load is coming from
(asdf-jar:add-to-asdf #P"/var/tmp/cl-ppcre-all-2.1.1.jar")
(asdf:load-system :cl-ppcre)
#+end_src
=asdf-jar= uses all items declared in the ASDF definitions so it won't
work well for:
1. An ASDF system which depends on artifacts that are not declared as
existing on the file-system via an explicit reference within the
ASDF source reference mechanism.
2. Libraries such as CFFI which depend on items to be have been make
available via an operating system packaging mechanism.
* Current hack
Ideally, we would like allow the AIO mechanism to include additional
ASDF systems in the single jar artifact.
Currently one can hack this together by:
1. Manually extracting the ~abcl-aio.jar~ artifact to a file-system.
2. Placing the necessary ASDF systems in the resulting "contrib"
directory.
3. Recreating the single archive from the file-system contents.
* TODO Future directions
Obviously, we could packaging ABCL applications as single archives
much more convenient. Rather than mucking around in the Ant build
system, I would rather that we add the necessary machinery
=ABCL-BUILD= contrib as it will make customization much easier for
those who know Common Lisp.
* Colophon
#+begin_example
Mark <evenson.not.org@gmail.com>
Created: <2019-11-25 Mon>
Revised: <2019-11-25 Mon 14:07>
#+end_example
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment