Champaca guides

Champaca runs Java bytecode inside a jolt process, so jolt code can call Java libraries as ordinary procedure calls. These pages cover using it, in roughly the order you'd need them. The project is a spike, and limitations lists what isn't there yet.

Using it

  • getting-started: what you need installed, the first call, and depending on champaca from your own project.
  • calling-java: construct, invoke, invoke-static and the field getters and setters, how an overload gets picked, jolt fns as Java interfaces, proxies, Java classes defined from jolt, threads, and what an exception looks like on the jolt side.
  • data-conversion: what jolt values turn into on the way in (arrays, collections, boxes) and how ->clj and ->java copy data across.
  • jars-and-modules: a classpath of jars and directories, and classes from JDK modules beyond java.base.
  • running-java-programs: running a compiled Java main straight from the command line, and Spring Boot and Quarkus applications in their packagings.
  • jvm-languages: Clojure, Groovy, Scala, Kawa, ABCL and Kotlin on champaca, their compilers included: the command for each, what's been checked against HotSpot, and how fast they start.
  • checking-a-port: champaca.portcheck, which runs a jolt function and the Java method it was written to replace on the same generated inputs and reports where they differ.
  • porting-a-class: jolt port, which writes a class's static methods out as jolt functions that need no JDK, checks each against its method, and says why it left the rest.
  • app-bundles: shipping a Java or jolt program as a directory that runs with no JDK installed, its cache warmed at build time and moving with it, or as one file that unpacks it.
  • a-command-line-tool: examples/hn, a jolt tool using a Kotlin library and a Java one, built into one file.

When it's slow or broken

  • performance: the startup cache, the call-site cache, what the generated code costs, and the pinned jolt build.
  • debugging: the CHAMPACA_* switches, Java stack traces, and the error kinds api.clj raises.

Background

  • compared-to-babashka: how champaca differs from babashka and GraalVM native-image, and when each fits.
  • compatibility: what behaves as on the JVM, area by area, with the test that checks each.
  • how-it-works: from a .class file to native code and how the JDK boots, with a table of the source files.
  • limitations: the shortcuts a real program will run into.

Working on champaca

  • contributing: how a change gets in, from its test against the JVM to the pull request, and the licensing rules for new code.
  • development: every task and CHAMPACA_* switch, the checks to run before a merge, and the metrics report.

The top-level README is the short version. For a second reference, read the files in examples/: they're tests that jolt test runs, each asserting what its calls return.