truffle: README.md annotate

annotate README.md @ 22404:23d2b5513c83

Fixing API error: GraphPrintVisitor shouldn't expose internal API class in an API method. When at it deprecating all protected methods, as GraphPrintVisitor usages don't indicate somebody should be subclassing it at all.

author	Jaroslav Tulach <jaroslav.tulach@oracle.com>
date	Fri, 20 Nov 2015 17:27:42 +0100
parents	df57bc2fcdbd
children

rev	line source
21995 811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	1 # The Truffle Language Implementation Framework
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	2
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	3
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	4 ## Introduction
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	5
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	6 Truffle is a framework for implementing languages as simple interpreters.
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	7 Together with the [Graal compiler](http://github.com/OracleLabs/GraalVM),
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	8 Truffle interpreters are automatically just-in-time compiled and programs
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	9 running on top of them can reach performance of normal Java.
13962 258a09b6449b Change AUTHORS, CHANGELOG, and README file from HTML to Markdown. Thomas Wuerthinger <thomas.wuerthinger@oracle.com> parents: diff changeset	10
21995 811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	11 The Truffle framework provides the basic foundation for building
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	12 abstract-syntax-tree (AST) interpreters that perform
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	13 [self-optimizations](http://dx.doi.org/10.1145/2384577.2384587) at runtime. The
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	14 included TruffleDSL provides a convenient way to express such optimizations.
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	15
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	16 Truffle is developed and maintained by Oracle Labs and the Institute for System
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	17 Software of the Johannes Kepler University Linz.
13962 258a09b6449b Change AUTHORS, CHANGELOG, and README file from HTML to Markdown. Thomas Wuerthinger <thomas.wuerthinger@oracle.com> parents: diff changeset	18
22208 df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	19 ## Using Truffle
21995 811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	20
22208 df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	21 Truffle official documentation is part of [Truffle javadoc](http://lafo.ssw.uni-linz.ac.at/javadoc/truffle/latest/).
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	22 It includes description of common use-cases, references to various tutorials,
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	23 code snippets and more. In case you want to embedded Truffle into your
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	24 application or write your own high speed language interpreter, start
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	25 [here](http://lafo.ssw.uni-linz.ac.at/javadoc/truffle/latest/).
13962 258a09b6449b Change AUTHORS, CHANGELOG, and README file from HTML to Markdown. Thomas Wuerthinger <thomas.wuerthinger@oracle.com> parents: diff changeset	26
22208 df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	27 Our typicial sample language is called the SimpleLanguage. A good entry point for
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	28 exploring SimpleLanguage is the [SLLanguage class](https://github.com/graalvm/Truffle/blob/master/truffle/com.oracle.truffle.sl/src/com/oracle/truffle/sl/SLLanguage.java).
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	29 In addition to that here are links to presentations, FAQs and papers about
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	30 Graal and Truffle:
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	31
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	32 - [Truffle Tutorials and Presentations](https://wiki.openjdk.java.net/display/Graal/Publications+and+Presentations)
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	33 - [Truffle FAQ and Guidelines](https://wiki.openjdk.java.net/display/Graal/Truffle+FAQ+and+Guidelines)
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	34 - [Graal VM and Truffle/JS](http://www.oracle.com/technetwork/oracle-labs/program-languages/overview/index-2301583.html) on the Oracle Technology Network
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	35 - [Papers on Truffle](http://ssw.jku.at/Research/Projects/JVM/Truffle.html)
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	36 - [Papers on Graal](http://ssw.jku.at/Research/Projects/JVM/Graal.html)
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	37
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	38 ## Hacking Truffle
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	39
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	40 Truffle and Graal use the [MX build tool](https://bitbucket.org/allr/mx),
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	41 which needs to be installed before using this repository. To do so execute
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	42 in a clean directory:
21995 811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	43
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	44 ```bash
22208 df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	45 $ hg clone https://bitbucket.org/allr/mx
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	46 $ mx/mx
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	47 ```
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	48
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	49 the mx/mx command is a wrapper around Python script that serves as our build tool.
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	50 Make sure you put it onto your ''PATH'' and then you can work with Truffle
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	51 sources from a command line:
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	52
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	53 ```bash
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	54 $ mx clean
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	55 $ mx build
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	56 $ mx unittest
13962 258a09b6449b Change AUTHORS, CHANGELOG, and README file from HTML to Markdown. Thomas Wuerthinger <thomas.wuerthinger@oracle.com> parents: diff changeset	57 ```
258a09b6449b Change AUTHORS, CHANGELOG, and README file from HTML to Markdown. Thomas Wuerthinger <thomas.wuerthinger@oracle.com> parents: diff changeset	58
21995 811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	59 The created `./build` directory contains all necessary jars and source bundles.
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	60
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	61 - `truffle-api.jar` contains the framework
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	62 - `truffle-dsl-processor.jar` contains the TruffleDSL annotation processor
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	63
22208 df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	64 You can open Truffle sources in your favorite Java IDE by invoking:
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	65
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	66 ```bash
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	67 $ mx ideinit
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	68 ```
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	69
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	70 the necessary IDE metadata will then be generated into truffle subdirectory
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	71 and its folders.
21995 811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	72
22208 df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	73 mx supports Maven integration. To register prebuilt binaries into local Maven
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	74 repository you can invoke:
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	75
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	76 ```bash
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	77 $ mx build
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	78 $ mx maven-install
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	79 ```
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	80
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	81 and then it is possible to include the artifacts as dependencies to a `pom.xml`:
13962 258a09b6449b Change AUTHORS, CHANGELOG, and README file from HTML to Markdown. Thomas Wuerthinger <thomas.wuerthinger@oracle.com> parents: diff changeset	82
21995 811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	83 ```xml
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	84 <dependency>
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	85 <groupId>com.oracle</groupId>
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	86 <artifactId>truffle</artifactId>
21999 8ec8f7831ab4 0.8 version will soon be out Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21997 diff changeset	87 <version>0.8</version>
21995 811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	88 </dependency>
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	89 <dependency>
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	90 <groupId>com.oracle</groupId>
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	91 <artifactId>truffle-dsl-processor</artifactId>
21999 8ec8f7831ab4 0.8 version will soon be out Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21997 diff changeset	92 <version>0.8</version>
21995 811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	93 <scope>provided</scope>
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	94 </dependency>
13962 258a09b6449b Change AUTHORS, CHANGELOG, and README file from HTML to Markdown. Thomas Wuerthinger <thomas.wuerthinger@oracle.com> parents: diff changeset	95 ```
258a09b6449b Change AUTHORS, CHANGELOG, and README file from HTML to Markdown. Thomas Wuerthinger <thomas.wuerthinger@oracle.com> parents: diff changeset	96
21995 811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	97 ## Contributing
13962 258a09b6449b Change AUTHORS, CHANGELOG, and README file from HTML to Markdown. Thomas Wuerthinger <thomas.wuerthinger@oracle.com> parents: diff changeset	98
22208 df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	99 You can contact the Truffle developers at graal-dev@openjdk.java.net mailing
df57bc2fcdbd Bringing the README.md up-to-date and providing references to Javadoc which should be the primary source of information. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21999 diff changeset	100 list.
13962 258a09b6449b Change AUTHORS, CHANGELOG, and README file from HTML to Markdown. Thomas Wuerthinger <thomas.wuerthinger@oracle.com> parents: diff changeset	101
21995 811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	102 ## License
811b97893a84 First draft of Truffle README.md Stefan Marr <stefan.marr@jku.at> parents: 21154 diff changeset	103
21997 c07e64ecb528 Update SL copyright headers to use UPL Gilles Duboscq <gilles.m.duboscq@oracle.com> parents: 21995 diff changeset	104 The Truffle framework is licensed under the [GPL 2 with Classpath exception](http://openjdk.java.net/legal/gplv2+ce.html).
c07e64ecb528 Update SL copyright headers to use UPL Gilles Duboscq <gilles.m.duboscq@oracle.com> parents: 21995 diff changeset	105 The SimpleLanguage is licensed under the [Universal Permissive License (UPL)](http://opensource.org/licenses/UPL).

Mercurial > hg > truffle

annotate README.md @ 22404:23d2b5513c83