jclass makes it easy to generate and analyze Java class files in Common Lisp. Build a compiler backend or a JVM bytecode analyzer with jclass!
Java classes, fields, methods, annotations, and more are represented as Lisp objects for easy analysis and manipulation. jclass also automatically builds the constant pool for you (but you can still make the pool manually if you want!)
It's also possible to create custom class attributes with jclass. An attribute description DSL makes it easy to add new attributes. Great for targeting custom JVMs or experimental features.
jclass is feature complete and the API is mostly stable. jclass will be updated
with new JVM features whenever they are released, so do not (:use #:jclass) in
your packages.
For in-depth information, see the manual.
;; Build the main method
(defparameter *main*
(make-instance 'jclass:method-info
:flags '(:public :static)
:name "main"
:descriptor "([Ljava/lang/String;)V" ; void (String[])
:attributes
(list
(make-instance 'jclass:code
:max-stack 2
:max-locals 1
:bytecode
`((:getstatic "java/lang/System" "out" "Ljava/io/PrintStream;")
(:ldc ,(jclass:make-string-info "Hello, world!"))
(:invokevirtual "java/io/PrintStream" "println" "(Ljava/lang/String;)V")
:return)
:exceptions '()
:attributes '()))))
;; Generate the class file
(with-open-file (stream "./Hello.class"
:direction :output
:element-type '(unsigned-byte 8))
(write-sequence
(jclass:java-class-bytes
(make-instance 'jclass:java-class
;; version 55.0 = Java 11
:major-version 55
:minor-version 0
:flags '(:public)
:name "Hello"
:parent "java/lang/Object"
:interfaces '()
:fields '()
:methods (list *main*)
:attributes '()))
stream))The class file executes as expected:
$ java Hello
Hello, world!Output from javap:
$ javap -v Hello.class
Classfile Hello.class
Last modified Aug 22, 2021; size 281 bytes
MD5 checksum b1d5aa6684ec1b281718b3cb249f21a0
public class Hello
minor version: 0
major version: 55
flags: (0x0001) ACC_PUBLIC
this_class: #1 // Hello
super_class: #2 // java/lang/Object
interfaces: 0, fields: 0, methods: 1, attributes: 0
Constant pool:
#1 = Class #9 // Hello
#2 = Class #10 // java/lang/Object
#3 = Utf8 main
#4 = Utf8 ([Ljava/lang/String;)V
#5 = Fieldref #11.#13 // java/lang/System.out:Ljava/io/PrintStream;
#6 = String #16 // Hello, world!
#7 = Methodref #17.#19 // java/io/PrintStream.println:(Ljava/lang/String;)V
#8 = Utf8 Code
#9 = Utf8 Hello
#10 = Utf8 java/lang/Object
#11 = Class #12 // java/lang/System
#12 = Utf8 java/lang/System
#13 = NameAndType #14:#15 // out:Ljava/io/PrintStream;
#14 = Utf8 out
#15 = Utf8 Ljava/io/PrintStream;
#16 = Utf8 Hello, world!
#17 = Class #18 // java/io/PrintStream
#18 = Utf8 java/io/PrintStream
#19 = NameAndType #20:#21 // println:(Ljava/lang/String;)V
#20 = Utf8 println
#21 = Utf8 (Ljava/lang/String;)V
{
public static void main(java.lang.String[]);
descriptor: ([Ljava/lang/String;)V
flags: (0x0009) ACC_PUBLIC, ACC_STATIC
Code:
stack=3, locals=1, args_size=1
0: getstatic #5 // Field java/lang/System.out:Ljava/io/PrintStream;
3: ldc #6 // String Hello, world!
5: invokevirtual #7 // Method java/io/PrintStream.println:(Ljava/lang/String;)V
8: return
}
jclass is currently not in Quicklisp or Ultralisp.
Install by cloning to your ~/common-lisp/ or quicklisp/local-projects/
directories.
Then run the following:
(ql:register-local-projects)
(asdf:load-system "jclass")If you have Roswell, you can install from Github.
$ ros install davidsun0/jclassjclass should work on conforming Common Lisps with the following features:
char-codeandcode-charmust work with Unicode code points.- If not working with Unicode, the functions must use ASCII values.
Incompatibility with an implementation that meets these requirements should be considered a bug. Please report any issues.
Since jclass works at the binary level, it only performs structural validation, not semantic validation. For example, certain attributes and flags are incompatible. Some features may only work with certain class file versions. jclass does not ensure that a JVM will accept a generated class.
It is up to the user to correctly match class file features.
- 4.1 The ClassFile Structure
- 4.4 The Constant Pool
- 4.5 Fields
- 4.6 Methods
- 4.7 Attributes
- 4.7.2 ConstantValue
- 4.7.3 Code
- 4.7.4 StackMapTable
- 4.7.5 Exceptions
- 4.7.6 InnerClasses
- 4.7.7 EnclosingMethod
- 4.7.8 Synthetic
- 4.7.9 Signature
- 4.7.10 SourceFile
- 4.7.11 SourceDebugExtension
- 4.7.12 LineNumberTable
- 4.7.13 LocalVariableTable
- 4.7.14 LocalVariableTypeTable
- 4.7.15 Deprecated
- 4.7.16 RuntimeVisibleAnnotations
- 4.7.17 RuntimeInvisibleAnnotations
- 4.7.18 RuntimeVisibleParameterAnnotations
- 4.7.19 RuntimeInvisibleParameterAnnotations
- 4.7.20 RuntimeVisibleTypeAnnotaions
- 4.7.21 RuntimeInvisibleTypeAnnotations
- 4.7.22 AnnotationDefault
- 4.7.23 BootstrapMethods
- 4.7.24 MethodParameters
- 4.7.25 Module
- 4.7.26 ModulePackages
- 4.7.27 ModuleMainClass
- 4.7.28 NestHost
- 4.7.29 NestMembers
- 4.7.30 Record
- 4.7.31 PermittedSublcasses
- Bytecode instructions (205 / 205)
- Constants (21 / 21)
- Loads (33 / 33)
- Stores (33 / 33)
- Stack (9 / 9)
- Math (37 / 37)
- Conversions (15 / 15)
- Comparisons (19 / 19)
- References (18 / 18)
- Control (11 / 11)
- Extended (6 / 6)
- Reserved (3 / 3)
jclass is based off of the Java Virtual Machine Specification, and not the
Java Programming Language. As such, it can generate code that uses the
invokedynamic instruction or use special characters in names.
The class file is represented as a tree of objects. Every named structure in the JVM Specification has an equivalent Lisp object.
There are functions to assemble and disassemble a java-class object to
and from a .class file. As fields, methods, and attributes are part of a
class, they cannot be serialized independently.
MIT