source: trunk/abcl/contrib/abcl-asdf/README.markdown

Last change on this file was 15084, checked in by mevenson, 2 weeks ago

Miscellaneous fixups to source locations and documentation

Build 1.6.0-SNAPSHOT via Maven.

Fix various ABCL-CONTRIB documentation quirks.

Move Netbeans/Ant? integration into a subdirectory.

File size: 6.1 KB
Line 
1ABCL-ASDF
2=========
3
4To use:
5
6    CL-USER> (require :abcl-contrib)
7
8    CL-USER> (require :abcl-asdf)
9   
10   
11ABCL specific contributions to ASDF system definition mainly concerned
12with finding JVM artifacts such as jar archives to be dynamically loaded.
13
14Example 1
15---------
16
17For the following ASDF definition stored in a file named "log4j.asd"
18that can be loaded:
19
20    ;;;; -*- Mode: LISP -*-
21    (in-package :asdf)
22
23    (defsystem log4j
24      :components ((:mvn "log4j/log4j/1.2.13")))
25
26After issuing
27
28    CL-USER> (asdf:make :log4j)
29   
30all the Log4j libraries would be dynamically added to the classpath so
31that the following code would
32
33    (let ((logger (#"getLogger" 'log4j.Logger (symbol-name (gensym)))))
34      (#"trace" logger "Kilroy wuz here."))
35 
36output the message "Kilroy wuz here" to the Log4j logging system.
37     
38
39API
40---
41
42We define an API within the ASDF package consisting of the following
43ASDF classes derived from ASDF:COMPONENT:
44
45    JAR-DIRECTORY, JAR-FILE, and CLASS-FILE-DIRECTORY for JVM artifacts
46    that have a currently valid pathname representation (i.e. they exist
47    on the local filesystem).
48
49    The MVN and IRI classes descend from ASDF-COMPONENT, but do not
50    directly have a filesystem location.
51
52    The IRI component is currently unused, but serves as a point to base
53    the inheritance of the MVN component while allowing other forms of
54    uri-like resources to be encapsulated in the future.
55
56The MVN component should specify a [Maven URI][mvn-uri] as its PATH.
57A Maven URI has a namestring of the form
58"GROUP-ID/ARTIFACT-ID/VERSION" which specifies the dependency to be
59satisfied for this component by resolution through the Maven
60distributed dependency graph.  The scheme (the initial "mvn://" in a
61Maven URI) is implied, and usually omitted for brevity.  If a VERSION
62is not specified (i.e. by a namestring like "GROUP-ID/ARTIFACT-ID" for
63the MVN component), then the latest available version of the artifact
64will be retrieved from the network.
65
66[mvn-uri]: http://team.ops4j.org/wiki/display/paxurl/Mvn+Protocol
67
68The MVN component may specify a CLASSNAME which if present in the
69current jvm, inhibits further loading from the network.  This may be
70used to bypass the invocation of Maven.  Since classnames are not
71unique to jar archives, this mechanism may not have the desired result
72in all cases, but it is surpisingly, like the rest of Java, "good
73enough" for everyday use.
74
75The MVN component may specify an ALTERNATE-URI which will be added to
76the jvm classpath if Maven cannot be located.  Since a Maven URI may
77refer to more than one binary artifact, this may not work in all cases.
78
79For use outside of ASDF, we currently define the generic function
80ABCL-ASDF:RESOLVE which locates, downloads, caches, and then loads
81into the currently executing JVM process all recursive dependencies
82annotated in the ditributed Maven pom.xml graph.
83
84One can muffle the verbosity of the Maven Aether resolver by setting
85CL:*load-VERBOSE* to NIL.
86
87Example 2
88---------
89
90Bypassing ASDF, one can directly issue requests for the Maven
91artifacts to be downloaded
92
93    CL-USER> (abcl-asdf:resolve "com.google.gwt:gwt-user")
94    WARNING: Using LATEST for unspecified version.
95    "/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"
96
97Notice that all recursive dependencies have been located and installed
98as well.
99
100ABCL-ASDF:RESOLVE does not added the resolved dependencies to the
101current JVM classpath.  Use JAVA:ADD-TO-CLASSPATH as follows to do
102that:
103
104    CL-USER> (java:add-to-classpath (abcl-asdf:as-classpath (abcl-asdf:resolve "com.google.gwt:gwt-user")))
105
106Example 3
107---------
108
109For a filesystem of jar archives:
110
111    ./lib/ext/flora2-reasoner/XSBFlora.jar
112    ./lib/ext/iris-reasoner/iris/iris-0.58.jar
113    ./lib/ext/iris-reasoner/jgrapht/jgrapht-jdk1.5-0.7.1.jar
114    ./lib/ext/log4j/log4j-1.2.14.jar
115    ./lib/ext/mandrax-reasoner/commons-collections-2.1.jar
116    ./lib/ext/mandrax-reasoner/jdom-b10.jar
117    ./lib/ext/mandrax-reasoner/log4j-1.2.8.jar
118    ./lib/ext/mandrax-reasoner/mandarax-3.4.jar
119    ./lib/ext/mins-reasoner/mins-v0_3.jar
120    ./lib/ext/pellet-reasoner/aterm/1.6/aterm-java-1.6.jar
121    ./lib/ext/pellet-reasoner/commons-logging/1.1/commons-logging-1.1.jar
122    ./lib/ext/pellet-reasoner/kaon/1.2.9/rdfapi.jar
123    ./lib/ext/pellet-reasoner/owl-api/1.4.3/abstractparser.jar
124    ./lib/ext/pellet-reasoner/owl-api/1.4.3/io.jar
125    ./lib/ext/pellet-reasoner/owl-api/1.4.3/rdfparser.jar
126    ./lib/ext/pellet-reasoner/owl-api/1.4.3/validation.jar
127    ./lib/ext/pellet-reasoner/owl-api/owl-api-econn/2006-04-27/api.jar
128    ./lib/ext/pellet-reasoner/owl-api/owl-api-econn/2006-04-27/impl.jar
129    ./lib/ext/pellet-reasoner/pellet/pellet.jar
130    ./lib/ext/pellet-reasoner/relaxng/1.0/relaxngDatatype.jar
131    ./lib/ext/pellet-reasoner/xsdlib/xsdlib.jar
132    ./lib/ext/wsmo/WSML-grammar-20081202.jar
133    ./lib/ext/wsmo/wsmo-api-0.6.2.jar
134    ./lib/ext/wsmo/wsmo4j-0.6.2.jar
135    ./lib/ext/xsb-system/interprolog.jar
136
137The following ASDF defintion loads enough JVM artifacts to use the
138[IRIS reasoner][iris-reasoner]:
139
140    (defsystem :wsml2reasoner-jars
141      :version "0.6.4"  ;; last sync with SVN
142      :defsystem-depends-on (abcl-contrib abcl-asdf) :components
143    ((:module wsml2reasoner
144      :pathname "lib/" :components
145      ((:jar-file "wsml2reasoner")))
146      (:module iris-libs
147        :pathname "lib/ext/iris-reasoner/iris/" :components
148      ((:jar-file "iris-0.58")))
149      (:module jgrapht-libs
150      :pathname "lib/ext/iris-reasoner/jgrapht/" :components
151      ((:jar-file "jgrapht-jdk1.5-0.7.1")))
152      (:module wsmo-libs
153      :pathname "lib/ext/wsmo/" :components
154      ((:jar-file "WSML-grammar-20081202")
155       (:jar-file "wsmo-api-0.6.2")
156       (:jar-file "wsmo4j-0.6.2")))
157      (:module log4j-libs
158         :pathname "lib/ext/log4j/" :components
159       ((:jar-file "log4j-1.2.14")))))
160
161[iris-reasoner]:  http://www.iris-reasoner.org/
162
163#### Colophon
164
165    Mark <evenson.not.org@gmail.com>
166   
167    Created: 2011-01-01
168    Revised: 2017-06-13
169   
Note: See TracBrowser for help on using the repository browser.