JVM Tutorials - Herong's Tutorial Examples - v5.14, by Herong Yang
What Is Lilac
This section provides a quick introduction on Lilac as a JVM assembler/disassembler tool with a tutorial on how to write a Lilac assembly program, compile it into bytecode file and run it on JVM.
What Is Lilac? Lilac is an assembler/disassembler for JVM bytecode developed by an anonymous author. Main features of Lilac are:
Here is what I did to download and install Lilac on my home computer.
1. Go to lilac.sourceforge.net/.
2. Click "Downloads" and download jasm-1.1.1.zip (Aug 7, 2016) file.
3. Unzip jasm-1.1.1.zip You will see jasm.jar and execution script files in jasm sub-directory. Run those script files on Linux systems, you need to update their permissions:
herong> chmod 744 jasm/*.sh
3. Set up the required environment variable, JASM_JAVA_HOME, to the JVM home directory. Here is an example on my macOS computer:
export JASM_JAVA_HOME=/Library/Java/jdk1.8.0_341.jdk/Contents/Home/
4. Try the script to run the compiler:
herong> ./jasm/jasm.sh
error: command line parsing failed.
Reason: Missing required options: input, output
usage: jasm
-classpath <classpath> class path entries (jars zips or dirs)
-D <property=value> configuration values
-enablelogging enables logging
-input <input> inputs (jars,zips, class files or
directories)
-logfile <log file name> the file to log into
-loglevel <log level> log level (error|warn|info|debug)
-output <output> output directory
Ok. Installation is done.
Now let's try to create a JASM program, compile and run it:
1. Copy the assembly example program from Lilac website, remove the package name org/jasm/examples/ and save it in a file called HelloWorld.jasm.
public super class {
version 52.0;
name ThisClass;
extends Object;
//Constants
const classref ThisClass ThisClass_name;
const utf8 ThisClass_name "HelloWorld";
const classref Object Object_name;
const utf8 Object_name "java/lang/Object";
const classref System System_name;
const utf8 System_name "java/lang/System";
const utf8 out_name "out";
const utf8 out_desc "Ljava/io/PrintStream;";
const nameandtype System.out_nat out_name,out_desc;
const fieldref System.out System,System.out_nat;
const classref PrintStream PrintStream_name;
const utf8 PrintStream_name "java/io/PrintStream";
const utf8 println_name "println";
const utf8 println_desc "(Ljava/lang/String;)V";
const nameandtype PrintStream.println_nat println_name,println_desc;
const methodref PrintStream.println PrintStream,PrintStream.println_nat;
const utf8 init0_name "<init>";
const utf8 init0_desc "()V";
const methodref Object.init0 Object, Object.init0_nat;
const nameandtype Object.init0_nat init0_name, init0_desc;
//This has to be declared if you have code
const utf8 Code_utf8 "Code";
const utf8 main_name "main";
const utf8 main_desc "([Ljava/lang/String;)V";
const utf8 helloworld_content "Hello World!";
const string helloworld helloworld_content;
//Constructor
public method {
name init0_name;
descriptor init0_desc;
//Variables
var object this;
//Instructions
aload this;
invokespecial Object.init0;
return;
}
//Main Method
public static method {
name main_name;
descriptor main_desc;
//Variables
var object args; //This is the method parameter
//Instructions
getstatic System.out;
ldc helloworld;
invokevirtual PrintStream.println;
return;
}
}
2. Compile HelloWorld.jasm into HelloWorld.class with the JASM compiler.
herong> mkdir src herong> mkdir cls herong> mv HelloWorld.jasm src herong> ./jasm/jasm.sh -input src -output cls Created 1 class files in 0 secs herong> ls -l cls -rw-r--r-- 1 herong staff 341 Nov 13 11:32 HelloWorld.class
3. Run HelloWorld.class on JVM.
herong> java -version java version "21.0.2" 2024-01-16 LTS herong> java -cp cls HelloWorld Hello World!
Cool, the compiled bytecode works on JVM 21!
If you don't have JVM 8 installed and want to run Lilac on newer JVM releases, you need to extract Java standard libraries out of Java module (.jmot) files. This is because Lilac needs to read standard class definitions from .jar or .class files and JVM 9+ replaced rt.jar with module files.
1. Reset the JASM_JAVA_HOME to JVM 21 home:
herong> export JASM_JAVA_HOME=/Library/Java/jdk-21.jdk/Contents/Home
2. Run Lilac assembler. I got the "class java/lang/Object not found" error.
herong> ./jasm/jasm.sh -input src -output cls warning: java runtime jar not found error: ./src/HelloWorld.jasm : line 4 class java/lang/Object not found Created 0 class files in 0 secs
3. Exact the class files out of java.base.jmod.
herong> $JASM_JAVA_HOME/bin/jmod extract --dir ./java.base \ $JASM_JAVA_HOME/jmods/java.base.jmod herong> ls -l java.base/classes/ drwxr-xr-x 3 herong staff 102 Nov 13 16:53 META-INF drwxr-xr-x 3 herong staff 102 Nov 13 16:53 apple drwxr-xr-x 3 herong staff 102 Nov 13 16:53 com drwxr-xr-x 11 herong staff 374 Nov 13 16:53 java drwxr-xr-x 5 herong staff 170 Nov 13 16:53 javax drwxr-xr-x 3 herong staff 102 Nov 13 16:53 jdk -rw-r--r-- 1 herong staff 12508 Nov 13 16:53 module-info.class drwxr-xr-x 11 herong staff 374 Nov 13 16:53 sun
4. Run Lilac assembler again with java.base class files provided in the -classpath option. I got the "java runtime jar not found" warning, but no errors.
herong> ./jasm/jasm.sh -input src -output cls \ -classpath ./java.base/classes warning: java runtime jar not found Created 1 class files in 0 secs
So Lilac can run on any JVM 8+ releases, as long as you can provide java.base class files in the -classpath option.
Table of Contents
JVM (Java Virtual Machine) Specification
Java HotSpot VM - JVM by Oracle/Sun
java.lang.Runtime Class - The JVM Instance
java.lang.System Class - The Operating System
ClassLoader Class - Class Loaders
Class Class - Class Reflections
JVM Stack, Frame and Stack Overflow
Thread Testing Program and Result
CPU Impact of Multi-Thread Applications
I/O Impact of Multi-Thread Applications
Micro Benchmark Runner and JVM Options
Micro Benchmark Tests on "int" Operations
Micro Benchmark Tests on "long" Operations
Micro Benchmark Tests in JIT Compilation Mode
Micro Benchmark Tests on "float" and "double" Operations
JRockit JVM 28.2.7 by Oracle Corporation
JVM Bytecode and Instruction Set
►JVM Assembler/Disassembler Tools
Compare HelloWorld.j with "javap" Output
JASM Example - Calculator.jasm
AsmTools/JASM Assembly Statements
AsmTools/JASM Example - Calculator.jasm
AsmTools/JASM Disassembler: "jdis"
AsmTools/JCOD Assembly File Format
AsmTools/JCOD Example - HelloWorld.jcod
AsmTools/JCOD Disassembler: "jdec"