∟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

 About This Book

 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 Runtime Data Areas

 JVM Stack, Frame and Stack Overflow

 Thread Testing Program and Result

 CPU Impact of Multi-Thread Applications

 I/O Impact of Multi-Thread Applications

 CDS (Class Data Sharing)

 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

 OpenJ9 by Eclipse Foundation

 JRockit JVM 28.2.7 by Oracle Corporation

 JVM Bytecode and Instruction Set

►JVM Assembler/Disassembler Tools

 What Is JVM Assembler

 What Is Jasmin

 Compare HelloWorld.j with "javap" Output

 Jasmin Assembly Statements

 Jasmin Example - Empty.j

 Jasmin Example - Calculator.j

 What Is JASM

 JASM Assembly Statements

 JASM Example - Calculator.jasm

 JASM Disassembler: "jasm -d"

 What Is AsmTools

 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"

►What Is Lilac

 Lilac Assembly Statements

 Lilac Macro Example - HelloWorldMacro.jasm

 Lilac Disassembler: "jdasm"

 Archived Tutorials

 References

 Index

 Full Version in PDF/EPUB