jacobin

A more than minimal JVM written in Go and capable of running Java 17 classes.

View the Project on GitHub platypusguy/jacobin

Welcome to Jacobin JVM

Jacobin is an implementation of the JVM specification for Java 21. It is written entirely in Go with no non-Go dependencies.

The goal is to provide a more-than-minimal implementation of the JVM that can run most class files and JARs and deliver the same results as the OpenJDK-based JVMs (that is, the majority of JVM implementations today). A paramount consideration in the design and implementation of Jacobin is the codebase: making it cohesive and containing clear code. The cohesiveness, extensive commenting, and large test suite enable professionals who want to know more about how the JVM works to find the information quickly and in an easily accessible setting. Additional information on the Jacobin wiki provides more background and insight.

Eventually, we hope to enable developers to run their code and have a UI that shows the bytecodes executing, along with the contents of the various JVM stacks, heap, and counters. If you want to see how your Java code executes, this end product will show you in real time. (This is difficult to do with OpenJDK-based JVMs because of the size of the codebase, which is written in multiple languages.)

Due to our desire for a strong, reliable product, Jacobin is heavily tested during development. As of September 2024, the test code is 233% the size of the production code and consists of more than 850 tests. We’re committed to increasing these numbers. When Jacobin advances some more, we intend to run the OpenJDK test suites against it.

Current Status

The current status is shown here. Updates are also posted in realtime on the Jacobin Twitter account.There are currently no packaged releases of Jacobin available (although you can always compile the code). We’ll issue releases when Jacobin is mature enough for beta testers to be able to run classes as expected.

At present, all tasks and defects are logged in an instance of JetBrains’ YouTrack (kindly provided at no cost). The task numbers appear at the start of the comment for every commit and push. The GitHub ‘issues’ facility is used strictly for issues posted by users. This design allows users to find solutions without needing to dig through numerous unrelated matters.

Contents

As we progress, we post short explanations of project decisions and explanations of how the JVM works. Current material can be found below:

Project Posts

Jacobin at the 3-year mark

Jacobin at 30 months

Jacobin at the 2-year mark

Jacobin at 18 months

Jacobin status at the 1-year mark

Why was Go chosen for this project?

How the Jacobin JVM works

Command-line processing

Inside Java class files: the constant pool

Inside the JVM: Arrays

Inside the JVM: How fields are handled

The Team (and Thanks)

Jacobin is presently being developed by Andrew Binstock (platypusguy) and Richard Elkins, with significant early contributions by Spencer Uresk. Contributors are more than welcome and on our wiki, we’ve provided copious information on the project structure to help contributors get aboard. If you can’t contribute code but would like to show support, we’d love a GitHub star or for you to follow the project.

This project could not have been possible without Github (for the excellent platform), JetBrains (for superb tools), Oracle’s Java team (for the great technology and best-in-class documentation), and these JVM experts: Ben Evans, Aleksey Shipilev, Chris Newland, and Bill Venners who have written helpful, in-depth articles on the machinery of the JVM. A big thanks to all!