Useful documentation was: Truffle repository conversion

Stefan Marr java at
Thu Jul 9 20:52:33 UTC 2015


To make a first step towards a useful README for the Truffle project, what do you think of the following?

# 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.

## Building and Using Truffle

Truffle and Graal use the [MX build tool](,
which is part of this repository. To build Truffle execute:

./ build

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

### Maven

For Maven based projects, prebuilt binaries can be included into a project by
adding the following dependencies to a `pom.xml`:


## Resources and Documentation

This repository contains the SimpleLanguage, which comes with JavaDoc
documentation to demonstrate how Truffle is used. A good entry point for
exploring SimpleLanguage is the [SLLanguage class](

  - [Truffle Tutorials and Presentations](
  - [Truffle FAQ and Guidelines](
  - [Graal VM and Truffle/JS]( on the Oracle Technology Network
  - [Papers on Truffle](
  - [Papers on Graal](

## Contributing


## License

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


Best regards

> On 30 Jun 2015, at 10:50, Stefan Marr <java at> wrote:
> Hi Jaroslav:
>> On 30 Jun 2015, at 09:18, Jaroslav Tulach <jaroslav.tulach at> wrote:
>> On Monday, June 29, 2015 08:32:54 PM Stefan Marr wrote:
>>> I could lend a hand with that.
>> That would be more than welcomed. A fix to API documentation is at least as 
>> important as fix to the actual code.
> At the moment, I was just thinking about the README.
> See
> Might be valid for Graal and for Truffle, but more specifically for the Truffle repo, because that one is the one I am interested in from a language’s research/implementer perspective.
> When I try to think of what I want from a repo README, then the following would be useful:
> - brief intro what it is
> - instructions how to build and use it (only the basics)
> - pointers to further resources such as
>   - a link to the main/official website
>   - documentation, tutorials, or if that’s absent links to projects using it
>   - where to find the community, and a note on how to interact/contribute
> - license information
> When pointing people to Truffle, I am always a little torn what a good entry point is.
> Currently we got the SSW site:
> as well as the FAQ:
> And perhaps the OTN one:
> Currently, none of the URLs answer all the questions above. OTN gets close, but only links to the Graal OpenJDK project, and from there, you won’t find Truffle at the moment, I think.
> A related practical matter, what would be the desired URL you guys would like to see on slides?
> Would be nice if there could be a high-level ‘Hello, Welcome, This is What I am’ kind of page or README I could use for the slides for the Truffle workshop.
> Best regards
> Stefan
> -- 
> Stefan Marr
> Johannes Kepler Universität Linz

Stefan Marr
Johannes Kepler Universität Linz

More information about the graal-dev mailing list