Mercurial > hg > truffle

annotate truffle/overview.html @ 22381:d3facd428d1d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Removing no longer needed imports
author Jaroslav Tulach <jaroslav.tulach@oracle.com>
date Wed, 18 Nov 2015 12:37:32 +0100
parents ad67d348e361
children 55f59502cf31
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5700
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
2 <html>
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
3 <head>
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
4 <!--
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
5
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
6 Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
7 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
8
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
9 This code is free software; you can redistribute it and/or modify it
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
10 under the terms of the GNU General Public License version 2 only, as
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
11 published by the Free Software Foundation. Oracle designates this
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
12 particular file as subject to the "Classpath" exception as provided
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
13 by Oracle in the LICENSE file that accompanied this code.
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
14
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
15 This code is distributed in the hope that it will be useful, but WITHOUT
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
16 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
17 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
18 version 2 for more details (a copy is included in the LICENSE file that
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
19 accompanied this code).
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
20
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
21 You should have received a copy of the GNU General Public License version
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
22 2 along with this work; if not, write to the Free Software Foundation,
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
23 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
24
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
25 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
26 or visit www.oracle.com if you need additional information or have any
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
27 questions.
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
28 -->
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
29
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
30 </head>
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
31 <body>
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
32
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
33 <p>
22062
db705e8b5a35 Truffle specific overview
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
34 Truffle is a framework for writing and executing interpreters. In case
db705e8b5a35 Truffle specific overview
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
35 you want to execute already written interpreters from your Java application,
22172
b31dcacfc8ff Replacing more TruffleVM references in comments with the new PolyglotEngine name
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22062
diff changeset
36 start at {@link com.oracle.truffle.api.vm.PolyglotEngine}. In case you'd like
22062
db705e8b5a35 Truffle specific overview
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
37 to write your own Truffle based language, start at
db705e8b5a35 Truffle specific overview
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
38 {@link com.oracle.truffle.api.TruffleLanguage}.
5726
4e5828456c28 added link to OpenJDK Graal project site in generated javadoc
Doug Simon <doug.simon@oracle.com>
parents: 5707
diff changeset
39 <p>
22062
db705e8b5a35 Truffle specific overview
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
40 To get the best speed out of your Truffle system, make sure you are running
db705e8b5a35 Truffle specific overview
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
41 on top of
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: 22172
diff changeset
42 <a target="_blank" href="http://openjdk.java.net/projects/graal/">Graal</a>
22062
db705e8b5a35 Truffle specific overview
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
43 virtual machine.
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: 22172
diff changeset
44 <p>
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: 22172
diff changeset
45 Our typicial sample language is called the <em>SimpleLanguage</em>.
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: 22172
diff changeset
46 A good entry point for exploring <em>SimpleLanguage</em> is the
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: 22172
diff changeset
47 <a target="_blank" href="https://github.com/graalvm/Truffle/blob/master/truffle/com.oracle.truffle.sl/src/com/oracle/truffle/sl/SLLanguage.java">SLLanguage</a>
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: 22172
diff changeset
48 class.
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: 22172
diff changeset
49
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: 22172
diff changeset
50 <h4>Other References</h4>
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: 22172
diff changeset
51
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: 22172
diff changeset
52 <ul>
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: 22172
diff changeset
53 <li><a target="_blank" href="https://wiki.openjdk.java.net/display/Graal/Publications+and+Presentations">Truffle Tutorials and Presentations</a></li>
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: 22172
diff changeset
54 <li><a target="_blank" href="https://wiki.openjdk.java.net/display/Graal/Truffle+FAQ+and+Guidelines">Truffle FAQ and Guidelines</a></li>
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: 22172
diff changeset
55 <li><a target="_blank" href="http://www.oracle.com/technetwork/oracle-labs/program-languages/overview/index-2301583.html">Graal VM and Truffle/JS</a> on the Oracle Technology Network</li>
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: 22172
diff changeset
56 <li><a target="_blank" href="http://ssw.jku.at/Research/Projects/JVM/Truffle.html">Papers on Truffle</a></li>
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: 22172
diff changeset
57 <li><a target="_blank" href="http://ssw.jku.at/Research/Projects/JVM/Graal.html">Papers on Graal</a></li>
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: 22172
diff changeset
58 </ul>
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: 22172
diff changeset
59
22324
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
60 <h4>Keeping Compatibility</h4>
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
61
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
62 <p>
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
63 The <b>Truffle</b> API values work of its adopters and as such it is developed
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
64 with compatibility in mind. Methods and features are not removed and renamed
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
65 randomly, without a notice and there is a binary compatibility testing framework
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
66 in place to verify that.
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
67 </p>
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
68 <p>
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
69 On the other hand the <b>Truffle</b> project is still young and needs a way
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
70 to refine and change previously taken decisions. To balance the need between
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
71 compatibility and give us a way to remove things from the API we following
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
72 these rules:
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
73 </p>
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
74 <ul>
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
75 <li>Rather than removing/renaming or changing an API element (class, method,
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
76 field), mark it <em>deprecated</em>.</li>
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
77 <li>Make sure usage of such element can be replaced by non-deprecated ways</li>
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
78 <li>Keep such element working until next release</li>
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
79 <li>If possible provide automatic migration using Jackpot's META-INF/upgrade/ files</li>
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
80 <li>When new (major) release is out, remove it</li>
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
81 </ul>
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
82 <p>
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
83 By deprecating parts of API while keeping them functional we are giving
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
84 users of the <b>Truffle</b> API time to adjust to required
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
85 changes and (under the assumption they pay attention to warnings in the code
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
86 base) easily identify and migrate to more modern API alternatives.
ad67d348e361 Defining incompatible API change policy for development versions
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22208
diff changeset
87 </p>
5700
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
88 </body>
12a34d1bcaa2 added site command to generate a javadoc-based website
Doug Simon <doug.simon@oracle.com>
parents:
diff changeset
89 </html>