Useful documentation was: Truffle repository conversion

[Thomas Wuerthinger]

This looks like a good start! Maybe it is best to commit the file to the Truffle repository and then gradually complete there.

- thomas


> On 09 Jul 2015, at 22:52, Stefan Marr <java at stefan-marr.de> wrote:
> 
> Hi:
> 
> 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](http://github.com/OracleLabs/GraalVM),
> 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](http://dx.doi.org/10.1145/2384577.2384587) 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](https://bitbucket.org/allr/mxtool2),
> which is part of this repository. To build Truffle execute:
> 
> ```bash
> ./mx.sh 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`:
> 
> ```xml
> <dependency>
>  <groupId>com.oracle</groupId>
>  <artifactId>truffle</artifactId>
>  <version>0.7</version>
> </dependency>
> <dependency>
>  <groupId>com.oracle</groupId>
>  <artifactId>truffle-dsl-processor</artifactId>
>  <version>0.7</version>
>  <scope>provided</scope>
> </dependency>
> ```
> 
> ## 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](https://github.com/OracleLabs/Truffle/blob/master/truffle/com.oracle.truffle.sl/src/com/oracle/truffle/sl/SLLanguage.java).
> 
>  - [Truffle Tutorials and Presentations](https://wiki.openjdk.java.net/display/Graal/Publications+and+Presentations)
>  - [Truffle FAQ and Guidelines](https://wiki.openjdk.java.net/display/Graal/Truffle+FAQ+and+Guidelines)
>  - [Graal VM and Truffle/JS](http://www.oracle.com/technetwork/oracle-labs/program-languages/overview/index-2301583.html) on the Oracle Technology Network
>  - [Papers on Truffle](http://ssw.jku.at/Research/Projects/JVM/Truffle.html)
>  - [Papers on Graal](http://ssw.jku.at/Research/Projects/JVM/Graal.html)
> 
> ## Contributing
> 
> TODO
> 
> 
> ## License
> 
> The Truffle framework is licensed under the [GPL 2 with Classpath exception](https://github.com/OracleLabs/Truffle/blob/master/LICENSE).
> The SimpleLanguage is licensed under the [Universal Permissive License (UPL)](TODO).
> 
> —————————
> 
> 
> Best regards
> Stefan
> 
>> On 30 Jun 2015, at 10:50, Stefan Marr <java at stefan-marr.de> wrote:
>> 
>> Hi Jaroslav:
>> 
>>> On 30 Jun 2015, at 09:18, Jaroslav Tulach <jaroslav.tulach at oracle.com> 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
>> http://lafo.ssw.uni-linz.ac.at/hg/truffle/file/4858c5e074e9/README.md
>> 
>> 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: http://ssw.jku.at/Research/Projects/JVM/Truffle.html
>> as well as the FAQ: https://wiki.openjdk.java.net/display/Graal/Truffle+FAQ+and+Guidelines
>> And perhaps the OTN one: http://www.oracle.com/technetwork/oracle-labs/program-languages/overview/index-2301583.html
>> 
>> 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
>> http://stefan-marr.de/research/
>> 
>> 
>> 
> 
> -- 
> Stefan Marr
> Johannes Kepler Universität Linz
> http://stefan-marr.de/research/
> 
> 
>