The Truffle Language Implementation Framework

Introduction

Truffle is a framework for implementing languages as simple interpreters. Together with the Graal compiler, Truffle interpreters are automatically just-in-time compiled and programs running on top of them can reach performance of normal Java.

The Truffle framework provides the basic foundation for building abstract-syntax-tree (AST) interpreters that perform self-optimizations at runtime. The included TruffleDSL provides a convenient way to express such optimizations.

Truffle is developed and maintained by Oracle Labs and the Institute for System Software of the Johannes Kepler University Linz.

Using Truffle

Truffle official documentation is part of Truffle javadoc. It includes description of common use-cases, references to various tutorials, code snippets and more. In case you want to embedded Truffle into your application or write your own high speed language interpreter, start here.

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

<dependency>
    <groupId>com.oracle.truffle</groupId>
    <artifactId>truffle-api</artifactId>
    <version>0.11</version> <!-- or any later version -->
</dependency>
<dependency>
    <groupId>com.oracle.truffle</groupId>
    <artifactId>truffle-dsl-processor</artifactId>
    <version>0.11</version>
    <scope>provided</scope>
</dependency>

Our typicial sample language is called the SimpleLanguage. A good entry point for exploring SimpleLanguage is the SLLanguage class. In addition to that here are links to presentations, FAQs and papers about Graal and Truffle:

• Truffle Tutorials and Presentations
• Truffle FAQ and Guidelines
• Graal VM and Truffle/JS on the Oracle Technology Network
• Papers on Truffle
• Papers on Graal

Hacking Truffle

Truffle and Graal use the MX build tool, which needs to be installed before using this repository. To do so execute in a clean directory:

$ git clone https://github.com/graalvm/mx.git/
$ mx/mx

the mx/mx command is a wrapper around Python script that serves as our build tool. Make sure you put it onto your ''PATH'' and then you can work with Truffle sources from a command line:

$ mx clean
$ mx build
$ mx unittest

The created ./build directory contains all necessary jars and source bundles.

• truffle-api.jar contains the framework
• truffle-dsl-processor.jar contains the TruffleDSL annotation processor

You can open Truffle sources in your favorite Java IDE by invoking:

$ mx ideinit

the necessary IDE metadata will then be generated into truffle subdirectory and its folders.

mx supports Maven integration. To register prebuilt binaries into local Maven repository you can invoke:

$ mx build
$ mx maven-install

and then it is possible to include the artifacts as dependencies to a pom.xml:

<dependency>
    <groupId>com.oracle.truffle</groupId>
    <artifactId>truffle-api</artifactId>
    <version>0.12-SNAPSHOT</version> <!-- or whether version got installed by mx maven-install -->
</dependency>
<dependency>
    <groupId>com.oracle.truffle</groupId>
    <artifactId>truffle-dsl-processor</artifactId>
    <version>0.12-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>

Contributing

You can contact the Truffle developers at [email protected] mailing list. To contribute a change, verify it using

$ mx gate

and start a pull request. Detailed info can be found in the contributing document.

License

The Truffle framework is licensed under the GPL 2 with Classpath exception. The SimpleLanguage is licensed under the Universal Permissive License (UPL).