Mercurial > hg > truffle

comparison README.md @ 21995:811b97893a84

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
First draft of Truffle README.md
author Stefan Marr <stefan.marr@jku.at>
date Thu, 16 Jul 2015 14:57:45 +0200
parents 271eee87201c
children c07e64ecb528
comparison
equal deleted inserted replaced
21994:7f5cf6b167f1 21995:811b97893a84
1 ## Building Graal 1 # The Truffle Language Implementation Framework
2 2
3 There is a Python script in mxtool/mx.py that simplifies working with the code
4 base. It requires Python 2.7. While you can run this script by using an absolute path,
5 it's more convenient to add graal/mxtool to your PATH environment variable so that the
6 'mx' helper script can be used. The following instructions in this file assume this
7 setup.
8 3
9 Building both the Java and C++ source code comprising the Graal VM 4 ## Introduction
10 can be done with the following simple command.
11 5
12 ``` 6 Truffle is a framework for implementing languages as simple interpreters.
13 % mx build 7 Together with the [Graal compiler](http://github.com/OracleLabs/GraalVM),
8 Truffle interpreters are automatically just-in-time compiled and programs
9 running on top of them can reach performance of normal Java.
10
11 The Truffle framework provides the basic foundation for building
12 abstract-syntax-tree (AST) interpreters that perform
13 [self-optimizations](http://dx.doi.org/10.1145/2384577.2384587) at runtime. The
14 included TruffleDSL provides a convenient way to express such optimizations.
15
16 Truffle is developed and maintained by Oracle Labs and the Institute for System
17 Software of the Johannes Kepler University Linz.
18
19
20 ## Building and Using Truffle
21
22 Truffle and Graal use the [MX build tool](https://bitbucket.org/allr/mxtool2),
23 which is part of this repository. To build Truffle execute:
24
25 ```bash
26 ./mx.sh build
14 ``` 27 ```
15 28
16 There are a number of VM configurations supported by mx which can 29 The created `./build` directory contains all necessary jars and source bundles.
17 be explicitly specified using the --vm option. However, you'll typically
18 want one of these VM configurations:
19 30
20 1. The 'server' configuration is a standard HotSpot VM that includes the 31 - `truffle-api.jar` contains the framework
21 runtime support for Graal but uses the existing compilers for normal 32 - `truffle-dsl-processor.jar` contains the TruffleDSL annotation processor
22 compilation (e.g., when the interpreter threshold is hit for a method).
23 Compilation with Graal is only done by explicit requests to the
24 Graal API. This is how Truffle uses Graal.
25
26 2. The 'graal' configuration is a VM where normal compilations are performed
27 by Graal. By default tiered compilation is enabled and Graal will be used at
28 the last tier while C1 will be used for the first compiled tiers.
29 33
30 Unless you use the --vm option with the build command, you will be presented 34 ### Maven
31 with a dialogue to choose one of the above VM configurations for the build
32 as well as have the option to make it your default for subsequent commands
33 that need a VM specified.
34 35
35 To build the debug or fastdebug builds: 36 For Maven based projects, prebuilt binaries can be included into a project by
37 adding the following dependencies to a `pom.xml`:
36 38
37 ``` 39 ```xml
38 % mx --vmbuild debug build 40 <dependency>
39 % mx --vmbuild fastdebug build 41 <groupId>com.oracle</groupId>
42 <artifactId>truffle</artifactId>
43 <version>0.7</version>
44 </dependency>
45 <dependency>
46 <groupId>com.oracle</groupId>
47 <artifactId>truffle-dsl-processor</artifactId>
48 <version>0.7</version>
49 <scope>provided</scope>
50 </dependency>
40 ``` 51 ```
41 52
42 ## Running Graal 53 ## Resources and Documentation
43 54
44 To run the VM, use 'mx vm' in place of the standard 'java' command: 55 This repository contains the SimpleLanguage, which comes with JavaDoc
56 documentation to demonstrate how Truffle is used. A good entry point for
57 exploring SimpleLanguage is the [SLLanguage class](https://github.com/OracleLabs/Truffle/blob/master/truffle/com.oracle.truffle.sl/src/com/oracle/truffle/sl/SLLanguage.java).
45 58
46 ``` 59 - [Truffle Tutorials and Presentations](https://wiki.openjdk.java.net/display/Graal/Publications+and+Presentations)
47 % mx vm ... 60 - [Truffle FAQ and Guidelines](https://wiki.openjdk.java.net/display/Graal/Truffle+FAQ+and+Guidelines)
48 ``` 61 - [Graal VM and Truffle/JS](http://www.oracle.com/technetwork/oracle-labs/program-languages/overview/index-2301583.html) on the Oracle Technology Network
62 - [Papers on Truffle](http://ssw.jku.at/Research/Projects/JVM/Truffle.html)
63 - [Papers on Graal](http://ssw.jku.at/Research/Projects/JVM/Graal.html)
49 64
50 To select the fastdebug or debug builds of the VM: 65 ## Contributing
51 66
52 ``` 67 TODO
53 % mx --vmbuild fastdebug vm ...
54 % mx --vmbuild debug vm ...
55 ```
56 68
57 ## Other VM Configurations
58 69
59 In addition to the VM configurations described above, there are 70 ## License
60 VM configurations that omit all VM support for Graal:
61 71
62 ``` 72 The Truffle framework is licensed under the [GPL 2 with Classpath exception](https://github.com/OracleLabs/Truffle/blob/master/LICENSE).
63 % mx --vm server-nograal build 73 The SimpleLanguage is licensed under the [Universal Permissive License (UPL)](TODO).
64 % mx --vm server-nograal vm -version
65 java version "1.8.0_40"
66 Java(TM) SE Runtime Environment (build 1.8.0_40-b25)
67 OpenJDK 64-Bit Server VM (build 25.40-b25-internal, mixed mode)
68
69 ```
70
71 ```
72 % mx --vm client-nograal build
73 % mx --vm client-nograal vm -version
74 java version "1.8.0_40"
75 Java(TM) SE Runtime Environment (build 1.8.0_40-b25)
76 OpenJDK 64-Bit Client VM (build 25.40-b25-internal, mixed mode)
77 ```
78
79 These configurations aim to match as closely as possible the
80 VM(s) included in the OpenJDK binaries one can download.