You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: truffle/README.md
+21-35Lines changed: 21 additions & 35 deletions
Original file line number
Diff line number
Diff line change
@@ -1,69 +1,56 @@
1
-
# The Truffle Language Implementation Framework
1
+
# Truffle Language Implementation Framework
2
2
3
3
## Introduction
4
4
5
-
Truffle is an Open Source library for building programming language implementations as interpreters for self-modifying Abstract Syntax Trees.
6
-
Together with the Open Source [Graal Compiler](../compiler), Truffle represents a significant step
7
-
forward in programming language implementation technology in the current era of dynamic languages.
5
+
The Truffle language implementation framework (Truffle) is an open-source library for building programming language implementations as interpreters for self-modifying Abstract Syntax Trees.
6
+
Together with the open-source [Graal compiler](https://github.com/oracle/graal/tree/master/compiler), Truffle represents a significant step forward in programming language implementation technology in the current era of dynamic languages.
8
7
9
-
A growing body of shared implementation code and services
10
-
reduces language implementation effort significantly, but leads to competitive runtime
11
-
performance that matches or exceeds the competition. The value of the platform is further
12
-
increased by support for low-overhead language interoperability, as well as a general instrumentation
13
-
framework that supports multi-language debugging and other external developer tools.
8
+
A growing body of shared implementation code and services reduces language implementation effort significantly, but leads to runtime performance that matches or exceeds the competition.
9
+
The value of the platform is further increased by support for low-overhead language interoperability, as well as a general instrumentation framework that supports multilanguage debugging and other external developer tools.
14
10
15
-
Truffle is developed and maintained by Oracle Labs and the Institute for System
16
-
Software of the Johannes Kepler University Linz.
11
+
Truffle is developed and maintained by Oracle and the Institute for System Software of the Johannes Kepler University Linz.
17
12
18
13
## Using Truffle
19
14
20
15
If you are looking for documentation on how to use Truffle, please consult the documentation [here](docs/README.md) or [on the website](https://www.graalvm.org/graalvm-as-a-platform/language-implementation-framework/).
21
16
22
17
## Hacking Truffle
23
18
24
-
Truffle and Graal use the [MX build tool](https://github.com/graalvm/mx/),
25
-
which needs to be installed before using this repository. To do so execute
26
-
in a clean directory:
27
-
19
+
Truffle and the Graal compiler use the [MX build tool](https://github.com/graalvm/mx/), which needs to be installed before using this repository.
20
+
To install it, run these commands in a clean directory:
28
21
```bash
29
22
$ git clone https://github.com/graalvm/mx.git/
30
23
$ mx/mx
31
24
```
32
25
33
-
the mx/*mx* command is a wrapper around Python script that serves as our build tool.
34
-
Make sure you put it onto your `PATH` and then you can work with Truffle
35
-
sources from a command line:
36
-
26
+
The `mx` command is a wrapper around the Python script that serves as a build tool.
27
+
Make sure you put it onto your `PATH` and then you can work with Truffle sources from a command line:
37
28
```bash
38
29
$ mx clean
39
30
$ mx build
40
31
$ mx unittest
41
32
```
42
33
43
34
The created `./mxbuild/dists` directory contains all necessary jars and source bundles.
44
-
45
-
-`truffle-api.jar` contains the framework
46
-
-`truffle-dsl-processor.jar` contains the TruffleDSL annotation processor
35
+
-`truffle-api.jar` contains the framework
36
+
-`truffle-dsl-processor.jar` contains the TruffleDSL annotation processor
47
37
48
38
You can open Truffle sources in your favorite Java IDE by invoking:
49
-
50
39
```bash
51
40
$ mx ideinit
52
41
```
53
42
54
-
The necessary IDE metadata will then be generated into *truffle* subdirectory
55
-
and its folders.
56
-
57
-
The `mx` tool supports Maven integration. To register prebuilt binaries into local Maven
58
-
repository you can invoke:
43
+
The necessary IDE metadata will be generated into _truffle/_ subdirectory
44
+
and its directories.
59
45
46
+
The `mx` tool supports Maven integration.
47
+
To register prebuilt binaries into your local Maven repository, run:
60
48
```bash
61
49
$ mx build
62
50
$ mx maven-install
63
51
```
64
52
65
-
Then it is possible to include the artifacts as dependencies to a `pom.xml`:
66
-
53
+
Then it is possible to add Truffle artifacts as dependencies to the Maven configuration file, _pom.xml_:
67
54
```xml
68
55
<dependency>
69
56
<groupId>org.graalvm.truffle</groupId>
@@ -81,17 +68,16 @@ Then it is possible to include the artifacts as dependencies to a `pom.xml`:
81
68
## Contributing
82
69
83
70
To contribute a change, verify it using:
84
-
85
71
```bash
86
72
$ mx gate
87
73
```
88
-
Then start a [pull request](https://help.github.com/articles/using-pull-requests/).
89
-
Detailed info can be found in the [contributing document](CONTRIBUTING.md).
74
+
Then create a [pull request](https://help.github.com/articles/using-pull-requests/).
75
+
Detailed information can be found in the [contributing document](CONTRIBUTING.md).
90
76
91
77
## Community
92
78
93
-
To reach out to the Truffle community (as well as the wider GraalVM community) consider the information available at https://www.graalvm.org/community/.
94
-
There is a dedicated Truffle channel (`#truffle`) on the GraalVM community slack(https://www.graalvm.org/slack-invitation/).
79
+
To reach out to the Truffle community (as well as the wider GraalVM community) consider the information available at the [GraalVM website](https://www.graalvm.org/community/).
80
+
There is a dedicated Truffle channel (`#truffle`) on the [GraalVM community slack](https://www.graalvm.org/slack-invitation/).
<imgsrc="http://img.youtube.com/vi/FJY96_6Y3a4/0.jpg"alt="Youtube Video Player"width="854"height="480"border="10" />
15
-
</a>
12
+
A good way to start implementing your language is to:
13
+
* Look at the [TruffleLanguage](http://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/TruffleLanguage.html) class, and subclass it for your own language implementation.
14
+
* Fork the [SimpleLanguage](https://github.com/graalvm/simplelanguage) project and start hacking. SimpleLanguage is a relatively small language implementation, well-documented, and designed to demonstrate most of the Truffle features.
15
+
* Examine the [GraalVM Polyglot API](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/package-summary.html) that enables you to embed your Truffle language in Java.
* Start to subclass [TruffleLanguage](http://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/TruffleLanguage.html) for your own language implementation.
21
-
* Fork [SimpleLanguage](https://github.com/graalvm/simplelanguage), a toy language that demonstrates how to use many Truffle features.
22
-
* Embed Truffle languages in Java host applications using the [Polyglot API](../../docs/reference-manual/embedding/embed-languages.md).
We also recommend to watch this online seminar on [Dynamic Metacompilation with Truffle](https://www.youtube.com/watch?v=pksRrON5XfU) by Christian Humer from Oracle, to better understand Truffle concepts such as dynamic metacompilation, partial evaluation, polymorphic inlining, and so on.
Copy file name to clipboardExpand all lines: truffle/docs/Languages.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,7 @@ The following language implementations exist already (in alphabetical order):
11
11
*[Enso](https://github.com/enso-org/enso), an open source, visual language for data science that lets you design, prototype and develop any application by connecting visual elements together.
12
12
*[Espresso](https://github.com/oracle/graal/tree/master/espresso), a meta-circular Java bytecode interpreter. *
13
13
*[FastR](https://github.com/graalvm/fastr), an implementation of GNU R. *
14
-
*[Graal.js](https://github.com/graalvm/graaljs), an ECMAScript 2020 compliant JavaScript implementation. *
14
+
*[GraalJS](https://github.com/graalvm/graaljs), an ECMAScript-compliant JavaScript implementation. *
15
15
*[GraalPy](https://github.com/graalvm/graalpython), an early-stage implementation of Python. *
16
16
*[GraalWasm](https://github.com/oracle/graal/tree/master/wasm), a compliant WebAssembly implementation. *
17
17
*[grCUDA](https://github.com/NVIDIA/grcuda), a polyglot CUDA integration.
The Truffle language implementation framework (Truffle) is an open source library for building tools and programming languages implementations as interpreters for self-modifying Abstract Syntax Trees.
10
10
Together with the open source [Graal compiler](https://github.com/oracle/graal/tree/master/compiler), Truffle represents a significant step forward in programming language implementation technology in the current era of dynamic languages.
11
11
12
-
The Truffle bits are uploaded to [Maven central](https://mvnrepository.com/artifact/org.graalvm.truffle).
12
+
The Truffle artifacts are uploaded to [Maven central](https://mvnrepository.com/artifact/org.graalvm.truffle).
13
13
You can use them from your `pom.xml` file as:
14
14
15
15
```xml
16
16
<dependency>
17
17
<groupId>org.graalvm.truffle</groupId>
18
18
<artifactId>truffle-api</artifactId>
19
-
<version>22.1.0</version> <!-- or any later version -->
19
+
<version>24.0.2</version> <!-- or any later version -->
20
20
</dependency>
21
21
<dependency>
22
22
<groupId>org.graalvm.truffle</groupId>
23
23
<artifactId>truffle-dsl-processor</artifactId>
24
-
<version>22.1.0<</version>
24
+
<version>24.0.2</version>
25
25
<scope>provided</scope>
26
26
</dependency>
27
27
```
@@ -33,45 +33,39 @@ It simplifies language implementation by automatically deriving high-performance
33
33
34
34
### Getting Started
35
35
36
-
Information on how to get starting building your language can be found in the [Language Implementation Tutorial](./LanguageTutorial.md).
37
-
The reference API documentation is available as part of the [Truffle Javadoc](http://graalvm.org/truffle/javadoc/).
38
-
Start with looking at the [TruffleLanguage](http://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/TruffleLanguage.html) class, which one should subclass to start developing a language.
39
-
Truffle comes prebuilt with the Graal Compiler and several language implementations as part of GraalVM.
36
+
We provide extensive [Truffle API documentation](http://graalvm.org/truffle/javadoc/).
37
+
Start by looking at the [TruffleLanguage](http://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/TruffleLanguage.html) class, which you should subclass to start developing a language.
38
+
Truffle comes with the Graal Compiler and several language implementations as part of GraalVM.
40
39
41
40
A good way to start implementing your language with Truffle is to fork the [SimpleLanguage](https://github.com/graalvm/simplelanguage) project and start hacking.
42
41
SimpleLanguage is a relatively small language implementation, well-documented, and designed to demonstrate most of the Truffle features.
43
42
You could also try by looking at code in one of the existing open source languages [implementations and experiments](./Languages.md).
44
43
45
-
Consider reading [these publications](https://github.com/oracle/graal/blob/master/docs/Publications.md) for a very detailed view into how many of the aspects of Truffle work. However, as with any other software project, the source code is the ground truth.
46
-
47
44
### Advanced Topics
48
45
49
46
Implementing a language using Truffle offers a way to interoperate with other "Truffle" languages.
50
-
To learn more about verifying that your language is a valid polyglot citizen, read more about using the [Polyglot TCK](./TCK.md).
51
-
Somewhat related topics worth exploring are [Truffle Libraries](./TruffleLibraries.md), as well as how to use them to implement a language [interoperability](./InteropMigration.md).
47
+
To estimate if your language is a valid polyglot citizen, read about using the [Polyglot API-based Test Compatibility Kit](./TCK.md).
48
+
Somewhat related topics worth exploring are [Truffle Libraries](./TruffleLibraries.md), as well as how to use them to implement a [language interoperability](./InteropMigration.md).
52
49
Languages implemented with Truffle can also be embedded in Java host applications using the [Polyglot API](../../docs/reference-manual/embedding/embed-languages.md).
53
50
54
-
To better understand how to improve the performance of your language please consult the documentation on [profiling](./Profiling.md) and [optimizing](./Optimizing.md) your language.
55
-
Also, to better understand how to use Truffle's automated monomorphization feature (i.e., splitting), look at the [related documentation](./splitting/Monomorphization.md).
51
+
To better understand how to improve the performance of your language, see the documentation on [Profiling Truffle Interpreters](./Profiling.md) and [Optimizing Truffle Interpreters](./Optimizing.md).
52
+
Also, to better understand how to use Truffle's automated monomorphization feature (for example, splitting), look at the [related documentation](./splitting/Monomorphization.md).
56
53
57
54
## Implement Your Tool
58
55
59
-
GraalVM provides a framework for creating language-agnostic tools like debuggers, profilers, and other instrumentations.
60
-
In general, GraalVM provides a standardized way to express and run program code enabling cross-language research and the development of tools that can be developed once and then applied to any language.
61
-
62
-
The reference API documentation is available as part of the [Truffle Javadoc](http://graalvm.org/truffle/javadoc/).
56
+
With the Truffle framework, you can develop language-agnostic tools such as debuggers, profilers, and other instrumentations.
63
57
Start with looking at the [TruffleInstrument](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/instrumentation/TruffleInstrument.html) class, which -- similar to `TruffleLanguage` -- one should subclass to start developing a tool.
64
58
65
59
If you want to implement your own "Truffle" tool, a good way to start is to fork the [SimpleTool](https://github.com/graalvm/simpletool) project -- like the SimpleLanguage project described above -- and start hacking.
66
60
SimpleTool is a well-documented, minimalistic code-coverage tool designed to be a starting point for understanding the tool development process using Truffle.
67
61
68
-
Since tools, developed with Truffle, instrument the language using the same AST-node-based approach, most of the techniques available to language developers in terms of improving performance are available to the tool developers as well.
69
-
This is why it is recommended that you understand how Truffle works from a language developer's perspective, in order to get the maximum out of your tool.
62
+
Since tools, developed with Truffle, instrument the language using the same AST-node-based approach, most of the techniques available to language developers, in terms of improving performance, are available to the tool developers as well.
63
+
This is why it is recommended that you understand how Truffle works from a language developer's perspective to get the maximum out of your tool.
70
64
71
65
## Compatibility
72
66
73
67
The Truffle API is evolved in a backwards-compatible manner from one version to the next.
74
-
When an API is deprecated, then it will stay deprecated for at least [two GraalVM releases](https://www.graalvm.org/release-notes/version-roadmap/), and a minimum of one month, before it will be removed.
68
+
When an API is deprecated, then it will stay deprecated for at least [two GraalVM releases](https://www.graalvm.org/release-calendar/) before it will be removed.
75
69
76
70
As a best practice it is recommended to upgrade Truffle only one version at a time.
77
71
This way you can increment the version and fix deprecation warnings before continuing to the next version.
@@ -81,4 +75,5 @@ The latest additions and changes can be seen in the [changelog](https://github.c
81
75
82
76
## Modifying Truffle
83
77
84
-
To understand how to modify Truffle, consult [this file](https://github.com/oracle/graal/blob/master/truffle/README.md), and if you would like to contribute to Truffle, consult the [contribution documentation](https://github.com/oracle/graal/blob/master/truffle/CONTRIBUTING.md).
78
+
To understand how to modify Truffle, check [this file](https://github.com/oracle/graal/blob/master/truffle/README.md).
79
+
If you would like to contribute to Truffle, consult the [contribution documentation](https://github.com/oracle/graal/blob/master/truffle/CONTRIBUTING.md).
0 commit comments