This documentation is for the unreleased GraalVM version.Download Early Access Builds from GitHub.

Truffle Language Implementation Framework

The Truffle language implementation framework (Truffle) is an open source library for building tools and programming languages implementations as interpreters for self-modifying Abstract Syntax Trees. Together with the open source Graal compiler, Truffle represents a significant step forward in programming language implementation technology in the current era of dynamic languages.

The Truffle artifacts are uploaded to Maven central. You can use them from your pom.xml file as:

<dependency>
    <groupId>org.graalvm.truffle</groupId>
    <artifactId>truffle-api</artifactId>
    <version>24.0.2</version> <!-- or any later version -->
</dependency>
<dependency>
    <groupId>org.graalvm.truffle</groupId>
    <artifactId>truffle-dsl-processor</artifactId>
    <version>24.0.2</version>
    <scope>provided</scope>
</dependency>

Implement Your Language #

The Truffle framework allows you to run programming languages efficiently on GraalVM. It simplifies language implementation by automatically deriving high-performance code from interpreters.

Getting Started #

We provide extensive Truffle API documentation. Start by looking at the TruffleLanguage class, which you should subclass to start developing a language. Truffle comes with the Graal Compiler and several language implementations as part of GraalVM.

A good way to start implementing your language with Truffle is to fork the SimpleLanguage project and start hacking. SimpleLanguage is a relatively small language implementation, well-documented, and designed to demonstrate most of the Truffle features. You could also try by looking at code in one of the existing open source languages implementations and experiments.

Advanced Topics #

Implementing a language using Truffle offers a way to interoperate with other “Truffle” languages. To estimate if your language is a valid polyglot citizen, read about using the Polyglot API-based Test Compatibility Kit. Somewhat related topics worth exploring are Truffle Libraries, as well as how to use them to implement a language interoperability. Languages implemented with Truffle can also be embedded in Java host applications using the Polyglot API.

To better understand how to improve the performance of your language, see the documentation on Profiling Truffle Interpreters and Optimizing Truffle Interpreters. Also, to better understand how to use Truffle’s automated monomorphization feature (for example, splitting), look at the related documentation.

Implement Your Tool #

With the Truffle framework, you can develop language-agnostic tools such as debuggers, profilers, and other instrumentations. Start with looking at the TruffleInstrument class, which – similar to TruffleLanguage – one should subclass to start developing a tool.

If you want to implement your own “Truffle” tool, a good way to start is to fork the SimpleTool project – like the SimpleLanguage project described above – and start hacking. SimpleTool is a well-documented, minimalistic code-coverage tool designed to be a starting point for understanding the tool development process using Truffle.

Since tools, developed with Truffle, instrument the language using the same AST-node-based approach, most of the techniques available to language developers, in terms of improving performance, are available to the tool developers as well. This is why it is recommended that you understand how Truffle works from a language developer’s perspective to get the maximum out of your tool.

Compatibility #

The Truffle API is evolved in a backwards-compatible manner from one version to the next. When an API is deprecated, then it will stay deprecated for at least two GraalVM releases before it will be removed.

As a best practice it is recommended to upgrade Truffle only one version at a time. This way you can increment the version and fix deprecation warnings before continuing to the next version. The deprecated Javadoc tags on the deprecated APIs are designed to be a guide on how to upgrade.

The latest additions and changes can be seen in the changelog.

Modifying Truffle #

To understand how to modify Truffle, check this file. If you would like to contribute to Truffle, consult the contribution documentation.