Introduction to SimpleLanguage

We found the easiest way to get started with implementing your own language byextending an existing SimpleLanguage.SimpleLanguage is a demonstrationlanguage built using the Truffle API.The SimpleLanguage project provides a showcase on how to use the Truffle APIsfor writing your own language. It aims to use most of the available Truffleframework features and documents their use extensively with inline sourcedocumentation.

To start, please ensure maven3 andGraalVM are available in yoursystem.

• Clone the SimpleLanguage repository using

$ git clone https://github.com/graalvm/simplelanguage

• Set the JAVA_HOME and PATH environment variables to the GraalVM home and bin folders using a command-line shell for Linux:

$ export JAVA_HOME=/path/to/graalvm
$ export PATH=/path/to/graalvm/bin:$PATH

and for macOS X:

$ export JAVA_HOME=/path/to/graalvm/Contents/Home
$ export PATH=/path/to/graalvm/Contents/Home/bin:$PATH

• Execute mvn package from SimpleLanguage folder to build the language.The command also builds a slnative executable in the simplelanguage/nativedirectory and sl-component.jar language component which later can be installedinto GraalVM using the GraalVMUpdater tool.Please verify if native-image plugin is available in your GraalVM distributionto avoid the build failure:

$ gu list
$ gu install native-image

You can disable the SimpleLanguage native image build during the packaging phase by running:

$ export SL_BUILD_NATIVE=false
$ mvn package

• Run in the simplelanguage root folder:

$ ./sl ./language/tests/HelloWorld.sl

The SimpleLanguage demonstration language is licensed under the Universal Permissive License (UPL).

IDE Setup

The Truffle Language Implementation framework provides language-agnostic infrastructure to realize standard IDE features by providing additional APIs. If you would like to experiment with your language and get the benefits of an IDE, consider the import of SimpleLanguage as an example.

Eclipse

The SimpleLanguage teaching project has been tested with Eclipse Neon.2 Release 4.6.2 and Eclipse Oxygen.3A. To import the project folder to the desirable Eclipse environment:

• Open Eclipse with a new workspace;
• Install m2e and m2e-apt plugins from the Eclipse marketplace (Help -> Eclipse Marketplace);
• Finally, import SimpleLanguage project from File -> Import -> Maven -> Existing Maven Projects -> browse to the simplelanguage folder -> Finish.

Netbeans

NetBeans provides GUI support for debugging arbitrary languages. In order to upload SimpleLanguage to NetBeans interface, proceed to File -> Open Project -> select simplelanguage folder -> check “Open Required Projects” -> open Project.

IntelliJ IDEA

SimpleLanguage project has been tested with IntelliJ IDEA 2018.3. Open IntelliJ IDEA and, from the main menu bar, select File -> Open -> Navigate to and select the simplelanguage folder -> Press “OK”. All dependencies will be included automatically.

Run SimpleLanguage

To run a SimpleLanguage source file, execute

$ ./sl language/tests/HelloWorld.sl

To see assembly code for Truffle compiled functions, run

$ ./sl -disassemble language/tests/SumPrint.sl

Dump Graphs

To investigate performance issues, we recommend the Ideal Graph Visualizer (hereand after “IGV”) – an essential tool for any language implementer building ontop of GraalVM Enterprise Edition.It is available as a separate download on Oracle Technology Network and requires accepting the Oracle Technology Network Developer License.

1.Unzip the downloaded package, enter the bin directory and start IGV:

$ cd idealgraphvisualizer/bin
$ idealgraphvisualizer

2.Execute the following from simplelanguage root folder to dump graphs to IGV:

$ ./sl -dump language/tests/SumPrint.sl

Debug

To start debugging the SimpleLanguage implementation with a Java debugger, pass the -debug option to the command-line launcher of your program:

$ ./sl -debug language/tests/HelloWorld.sl

Then attach a Java remote debugger (like Eclipse) on port 8000.

SimpleLanguage Component for GraalVM

Languages implemented with Truffle Language Implementation framework can be packaged as Components which later can be installed intoGraalVM using the GraalVM Updater.Running mvn package in the simplelanguage folder also builds asl-component.jar.This file is the SimpleLanguage component for GraalVM and can be installed byrunning:

$ gu -L install /path/to/sl-component.jar

SimpleLanguage Native Image

A language implemented with Truffle Language Implementation framework can be AOTcompiled using the GraalVM Native Image. Runningmvn package in the simplelanguage folder also builds a slnative executablein the native directory. This executable is the full SimpleLanguageimplementation as a single native application, and has no need for a GraalVM inorder to execute SimpleLanguage code. Besides this, a big advantage of using thenative image when compared to running on the GraalVM is the greatly fasterstartup time as shown bellow.

$ time ./sl language/tests/HelloWorld.sl
== running on org.graalvm.polyglot.Engine@2db0f6b2
Hello World!
real    0m0.405s
user    0m0.660s
sys     0m0.108s
$ time ./native/slnative
language/tests/HelloWorld.sl
== running on org.graalvm.polyglot.Engine@7fd046f06898
Hello World!
real    0m0.004s
user    0m0.000s
sys     0m0.000s

This snipped shows a timed execution of a “Hello World” program using the sllauncher script, which runs SimpleLanguage on GraalVM, and using the nativeimage. We can see that when running on GraalVM the execution takes 405ms. Sinceour SimpleLanguage program does just one print statement, we can conclude thatalmost all of this time is spent starting up GraalVM and initializing thelanguage itself. When using the native image we see that the execution takesonly 4ms, showing two orders of magnitude faster startup than running on theGraalVM.

For more information on the native-image tool consider reading the referencemanual.

Disable SimpleLanguage Native Image Build

Building the native image through maven is attached to the maven packagephase. Since the native image build can take a bit of time, we provide theoption to skip this build by setting the SL_BUILD_NATIVE environment variableto false like so:

$ export SL_BUILD_NATIVE=false
$ mvn package
...
[INFO]                                                                         
[INFO] ------------------------------------------------------------------------
[INFO] Building simplelanguage-graalvm-native
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] --- exec-maven-plugin:1.6.0:exec (make_native) @ simplelanguage-graalvm-native ---
Skipping the native image build because SL_BUILD_NATIVE is set to false.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
...

Run SimpleLanguage with the Newest Compiler Version

In the outstanding case that you need to execute SimpleLanguage with the newestversion of the GraalVM compiler, please follow these instructions:

• Download the latest JVMCI JDK 8 and point JAVA_HOME at it:

$ export JAVA_HOME=/path/to/openjdk1.8.0_212-jvmci-19.2-b01

• Clone the “Graal” repository from SimpleLanguage folder:

$ cd /path/to/simplelanguage
$ git clone https://github.com/oracle/graal.git

• Clone the mx repository:

$ git clone https://github.com/graalvm/mx.git

• Add mx to your path:

$ export PATH=/path/to/mx:$PATH

• Navigate to the compiler folder:

$ cd /path/to/graal/compiler

• Build the GraalVM compiler:

$ mx build

• Run SimpleLanguage using the mx command:

$ mx -v --jdk=jvmci vm -cp /path/to/simplelanguage/launcher/target/launcher-19.3.0.2-SNAPSHOT.jar:/path/to/simplelanguage/language/target/simplelanguage.jar com.oracle.truffle.sl.launcher.SLMain  /path/to/simplelanguage/language/tests/SlScript.sl

Run SimpleLanguage Using Command Line

Executing SimpleLanguage code is normally done with the sl script which setsup the necessary command line depending on whether JAVA_HOME points to theGraalVM or another JVM installation. The following subsections describe thecommand line for both cases.

GraalVM

Assuming JAVA_HOME points to the GraalVM installation and that the currentworking directory is the simplelanguage directory, to run SimpleLanguage oneshould execute the following command:

$ JAVA_HOME/bin/java \
    -cp launcher/target/launcher-19.3.0.2-SNAPSHOT.jar \
    -Dtruffle.class.path.append=language/target/simplelanguage.jar \
    com.oracle.truffle.sl.launcher.SLMain language/tests/Add.sl

In short, we place the launcher jar on the class path and execute its mainclass, but we inform GraalVM of the presence of SimpleLanguage by using the-Dtruffle.class.path.append option and providing it the path to the fatlanguage jar. Having the language on a separate class path ensures a strongseparation between the language implementation and its embedding context (inthis case, the launcher).

Disable Class Path Separation

NOTE! This should only be used during development.

If it is required to disable the class path separation and enable having thelanguage implementation on the application class path (for example, for testingthe internals of the language) you can add the -XX:-UseJVMCIClassLoaderoption. This disables the class path isolation, enabling the languageimplementation to be placed on the application class path. The command line canthen look like the following.

$ JAVA_HOME/bin/java \
    -XX:-UseJVMCIClassLoader \
    -cp launcher/target/launcher-19.3.0.2-SNAPSHOT.jar:language/target/simplelanguage.jar \
    com.oracle.truffle.sl.launcher.SLMain language/tests/Add.sl

Other JVM Implementations

Unlike GraalVM, which includes all the dependencies needed to run a languageimplemented with Truffle framework, other JVM implementations need additionaljars to be present on the class path. These are the Truffle API and GraalVM SDKjars available from Maven Central.

Assuming JAVA_HOME points to a Stock JDK installation, that the currentworking directory is the simplelanguage directory and the Truffle API andGraalVM SDK jars are present in that directory, one can execute SimpleLanguagewith the following command:

$ JAVA_HOME/bin/java \
    -cp graal-sdk-19.3.0.2.jar:truffle-api-19.3.0.2.jar:launcher/target/launcher-19.3.0.2-SNAPSHOT.jar:language/target/simplelanguage.jar \
    com.oracle.truffle.sl.launcher.SLMain language/tests/Add.sl