Mercurial > hg > truffle

annotate README.md @ 22511:d7cc1f03d881 truffle-0.10

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Generating API snapshot as of release 0.10
author Jaroslav Tulach <jaroslav.tulach@oracle.com>
date Fri, 18 Dec 2015 11:04:11 +0100
parents df57bc2fcdbd
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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).