Introduction to SimpleLanguage

We found the easiest way to get started with implementing your own language by extending an existing SimpleLanguage. SimpleLanguage is a demonstration language built using the Truffle API. The SimpleLanguage project provides a showcase on how to use the Truffle APIs for writing your own language. It aims to use most of the available Truffle features and documents their use extensively with inline source documentation.

The reference documentation for Truffle can be found here.

Make sure your system meets the prerequisites:

  1. Ensure you set up GraalVM before you begin. See Get Started.
  2. Clone the SimpleLanguage repository using
    $ git clone https://github.com/graalvm/simplelanguage
    
  3. Set the environment variable JAVA_HOME to the GraalVM home folder using a command-line shell for Linux.
    $ export JAVA_HOME=/path/to/graalvm
    

    and for Mac OS X:

    $ export JAVA_HOME=/path/to/graalvm/Contents/Home
    
  4. Execute mvn package from SimpleLanguage folder to build the language.
  5. 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:

  1. Open Eclipse with a new workspace;
  2. Install m2e and m2e-apt plugins from the Eclipse marketplace (Help -> Eclipse Marketplace);
  3. 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.2. 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.

Running

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

IGV

To investigate SimpleLanguage performance issues, you need IGV. It is also known as the Ideal Graph Visualizer and is currently maintained as part of the Graal compiler.

  1. Download the Ideal Graph Visualizer and unpack the downloaded archive in the simplelanguage folder;
  2. Launch IGV with from simplelanguage folder:
    $ idealgraphvsiualizer/bin/idealgraphvsiualizer --jdkhome /path/to/graalvm
    
  3. Execute the following to dump graphs to IGV:
    $ ./sl -dump language/tests/SumPrint.sl
    

Debugging

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

Truffle languages can be packaged as components which can be installed into GraalVM using the Graal updater. Running mvn package in the simplelanguage folder also builds a sl-component.jar. This file is the SimpleLanguage component for GraalVM and can be installed by running:

$ /path/to/graalvm/bin/gu -F install /path/to/sl-component.jar

The SimpleLanguage native image

Truffle language implementations can be AOT compiled using the GraalVM native-image tool. Running mvn package in the simplelanguage folder also builds a slnative executable in the native directory. This executable is the full SimpleLanguage implementation as a single native application, and has no need for a GraalVM in order to execute SimpleLanguage code. Besides this, a big advantage of using the native image when compared to running on the GraalVM is the greatly faster startup 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 sl launcher script, which runs SimpleLanguage on GraalVM, and using the native image. We can see that when running on GraalVM the execution takes 405ms. Since our SimpleLanguage program does just one print statement, we can conclude that almost all of this time is spent starting up GraalVM and initializing the language itself. When using the native image we see that the execution takes only 4ms, showing two orders of magnitude faster startup than running on the GraalVM.

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

Disabling the SimpleLanguage native image build

Building the native image through maven is attached to the maven package phase. Since the native image build can take a bit of time, we provide the option to skip this build by setting the SL_BUILD_NATIVE environment variable to 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] ------------------------------------------------------------------------
[INFO] Total time: 0.514 s
[INFO] Finished at: 2018-07-16T11:23:56+02:00
[INFO] Final Memory: 22M/428M
[INFO] ------------------------------------------------------------------------
...

Running SimpleLanguage with the Newest Version of Graal Compiler

In the outstanding case that you need to execute SimpleLanguage with the newest version of Graal compiler, please follow these instructions:

  1. Download the latest JVMCI JDK 8 from Oracle Technology Network Downloads and point JAVA_HOME at it:
    $ export JAVA_HOME=/path/to/labsjdk1.8.0_172-jvmci-0.48
    
  2. Clone the Graal repository from SimpleLanguage folder:
    $ cd /path/to/simplelanguage
    $ git clone https://github.com/oracle/graal.git
    
  3. Clone the mx repository:
    $ git clone https://github.com/graalvm/mx.git
    
  4. Add mx to your path:
    $ export PATH=/path/to/mx:$PATH
    
  5. Navigate to the compiler folder in Graal repository:
    $ cd /path/to/graal/compiler
    
  6. Build the Graal compiler:
    $ mx build
    
  7. Run SimpleLanguage using the mx command:
    $ mx -v --jdk=jvmci vm -cp /path/to/simplelanguage/launcher/target/sl-launcher-1.0-SNAPSHOT.jar:/path/to/simplelanguage/language/target/simplelanguage-1.0-SNAPSHOT.jar com.oracle.truffle.sl.launcher.SLMain  /path/to/simplelanguage/language/tests/SlScript.sl