Mercurial > hg > truffle
annotate README.md @ 22422:30644770899d
Testing identity behavior for String values
author | Jaroslav Tulach <jaroslav.tulach@oracle.com> |
---|---|
date | Mon, 30 Nov 2015 15:13:33 +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). |