Truffle is a framework for writing and executing interpreters. In case you want to execute already written interpreters from your Java application, start at {@link com.oracle.truffle.api.vm.PolyglotEngine}. In case you'd like to write your own Truffle based language, start at {@link com.oracle.truffle.api.TruffleLanguage}.

To get the best speed out of your Truffle system, make sure you are running on top of Graal virtual machine. The easiest way to get binaries of the virtual machine is to download the OTN technology preview.

Using Truffle

You can embed any Truffle language into your existing Java program. The central class to start at is {@link com.oracle.truffle.api.vm.PolyglotEngine}. Once you have an instance of {@link com.oracle.truffle.api.vm.PolyglotEngine}, you can {@link com.oracle.truffle.api.vm.PolyglotEngine#eval evaluate} {@link com.oracle.truffle.api.source.Source sources} written in any language the {@link com.oracle.truffle.api.vm.PolyglotEngine} understands. The set of supported languages is determined by putting their JAR files on a classpath of your application. Some languages are available in central Maven repository. To include them, modify your pom.xml file (if using Maven) dependency section:

<dependency>
    <groupId>org.jruby</groupId>
    <artifactId>jruby-truffle</artifactId>
    <version>9.1.2.0</version>
</dependency>

Other languages may be prepackaged in your virtual machine. For example when using the OTN Graal VM one can start the java executable with parameter -polyglot and the FastR, JavaScript and TruffleRuby languages will be made available automatically.

Learning Truffle

Our typical sample language is called the SimpleLanguage. A good entry point for exploring SimpleLanguage is the SLLanguage class.

There is an excellent tutorial Add Graal JIT Compilation to Your JVM Language written by Stefan Marr which gives real example of turning an existing language into Truffle based one:

Step 1: Setting a Goal and Choosing a Benchmark
Step 2: Adding Bits Operations
Step 3: Interpreting a Simple Fibonacci Function
Step 4: Complete Support for Mandelbrot
Step 5: Optimizing the Interpreter for Compilation

The posts cover not only basics, and API usage, but also description of available tools for analyzing the performance and optimizing it.

References

Truffle on Github
Graal on Github
Tutorials and publications on Truffle
Tutorials and publications on Graal
Graal VM on the Oracle Technology Network

Keeping Compatibility

The Truffle API values work of its adopters and as such it is developed with compatibility in mind. Methods and features are not removed and renamed randomly, without a notice and there is a binary compatibility testing framework in place to verify that.

On the other hand the Truffle project is still young and needs a way to refine and change previously taken decisions. To balance the need between compatibility and give us a way to remove things from the API we following these rules:

Rather than removing/renaming or changing an API element (class, method, field), mark it deprecated.
Make sure usage of such element can be replaced by non-deprecated ways
Keep such element working until next release
If possible provide automatic migration using Jackpot's META-INF/upgrade/ files
When new (major) release is out, remove it

By deprecating parts of API while keeping them functional we are giving users of the Truffle API time to adjust to required changes and (under the assumption they pay attention to warnings in the code base) easily identify and migrate to more modern API alternatives.