Skip to content

Latest commit

 

History

History
 
 

truffle

README.md

The Truffle Language Implementation Framework

Introduction

Truffle is an Open Source library for building programming language 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.

A growing body of shared implementation code and services reduces language implementation effort significantly, but leads to competitive runtime performance that matches or exceeds the competition. The value of the platform is further increased by support for low-overhead language interoperation, as well as a general instrumentation framework that supports multi-language debugging and other external developer tools.

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

Using Truffle

Information on how to get starting building your language can be found in the Truffle language implementation tutorial. The reference API documentation is available as part of the Truffle javadoc. Truffle comes prebuilt with Graal and several language implementations as as part of GraalVM.

The 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.30</version> <!-- or any later version -->
</dependency>
<dependency>
    <groupId>com.oracle.truffle</groupId>
    <artifactId>truffle-dsl-processor</artifactId>
    <version>0.30</version>
    <scope>provided</scope>
</dependency>

If you want to implement your own Truffle guest language, a good way to start is to fork the SimpleLanguage project and start hacking. SimpleLanguage is well documented and designed to demonstrate most of the Truffle features.

To learn more:

  • Start with a new subclass of TruffleLanguage for your own language implementation.
  • Start with a new subclass of TruffleInstrument for your own instrumentation/tool.
  • Fork SimpleLanguage, a toy language that demonstrates how to use most Truffle features.
  • Get inspired by looking at code of one of existing open source Truffle language implementations and experiments here.
  • Embed Truffle languages in Java host applications using the Polyglot API.
  • Read The Graal/Truffle publications
  • Verify that your language is a valid polyglot citizen using the Polyglot TCK.

Compatibility

The Truffle API is evolved in a backwards compatible manner from one version to the next. When API is deprecated, then it will stay deprecated for at least two Truffle releases and a minimum of one month 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, fix deprecation warnings to continue with 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.

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.30-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.30-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).