source: trunk/abcl/doc/packaging-abcl.org

Last change on this file was 15213, checked in by Mark Evenson, 2 years ago

doc: document the issues in packaging ABCL in a single jar

File size: 3.4 KB
Line 
1#+TITLE: Notes Packaging ABCL for Distribution
2
3
4* abcl-aio
5
6The standard ABCL build process as described in the ~build.xml~ file
7and executed by the Ant build tool results in two artifacts:
8~abcl.jar~ and ~abcl-contrib.jar~.  ~abcl.jar~ contains all the Java
9and Common Lisp code necessary that constitute the ANSI conforming
10implementation runtime. The ~abcl-contrib.jar~ (aka "contrib")
11artifact contains additional Common Lisp-only code that extends the
12implementation in useful manners. 
13
14We create two separate jar artifacts in order to:
15
161. To place an upper bound of size of ~abcl.jar~ regardless of what we
17   package in ~abcl-contrib.jar~.
18
192. Clearly mark which parts of the code-base are covered under
20   GPLv2+classpath from those that may have other licensing terms.  By
21   making the loading of "contrib" a dynamic operation, we defer
22   possible infringement to the User who redistributes the resulting
23   jar artifact. 
24
25Users often want to simply package both artifacts in a single jar for
26deployment convenience.  abcl-1.5.0 introduced the build machinery to
27create such an "all-in-one" artifact via the [[https://github.com/armedbear/abcl/blob/master/build.xml#L517][~abcl-aio.jar~]] target.
28Upon invoking the ~abcl-aio.jar~ target
29
30#+begin_src shell
31ant -f build.xml abcl-aio.jar
32#+end_src
33
34the resulting artifact contains both the core implementation and the
35ABCL contrib which may be run as usual via
36#+begin_src shell
37java -jar dist/abcl-aio.jar
38#+end_src
39
40* abcl-jar contrib
41
42The ABCL-JAR contrib provides a mechanism for package ASDF systems and
43their recursive dependencies in a jar archive. 
44
45An example of using this to package the CL-PPCRE system from Quicklisp
46
47#+begin_src lisp
48;;
49(require :abcl-contrib)
50(require :quicklisp-abcl)
51(ql:quickload :cl-ppcre)
52
53(require :asdf-jar)
54(asdf-jar:package :cl-ppcre)
55#+end_src
56
57results in a jar archive at something like
58~#P"/var/tmp/cl-ppcre-all-2.1.1.jar"~.
59
60This jar archive may be loaded in a version of the implementation via
61
62#+begin_src lisp
63(require :abcl-contrib)
64(require :asdf-jar)
65(setf *load-verbose* t) ;; so we can verify where the load is coming from
66(asdf-jar:add-to-asdf #P"/var/tmp/cl-ppcre-all-2.1.1.jar")
67(asdf:load-system :cl-ppcre)
68#+end_src
69
70=asdf-jar= uses all items declared in the ASDF definitions so it won't
71work well for:
72
731. An ASDF system which depends on artifacts that are not declared as
74   existing on the file-system via an explicit reference within the
75   ASDF source reference mechanism.
76
772. Libraries such as CFFI which depend on items to be have been make
78   available via an operating system packaging mechanism.
79
80* Current hack
81
82Ideally, we would like allow the AIO mechanism to include additional
83ASDF systems in the single jar artifact. 
84
85Currently one can hack this together by:
86
871.  Manually extracting the ~abcl-aio.jar~ artifact to a file-system.
88
892.  Placing the necessary ASDF systems in the resulting "contrib"
90   directory.
91
923.  Recreating the single archive from the file-system contents.
93
94* TODO Future directions
95
96Obviously, we could packaging ABCL applications as single archives
97much more convenient.  Rather than mucking around in the Ant build
98system, I would rather that we add the necessary machinery
99=ABCL-BUILD= contrib as it will make customization much easier for
100those who know Common Lisp.
101
102
103
104
105* Colophon
106  #+begin_example
107  Mark <evenson.not.org@gmail.com>
108  Created: <2019-11-25 Mon>
109  Revised: <2019-11-25 Mon 14:07>
110  #+end_example
111
112 
113
Note: See TracBrowser for help on using the repository browser.