Introduction to SimpleLanguage

We found the easiest way to get started to implement your own language in Truffle is by extending an existing simple language. 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 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 importing of SimpleLanguage described below as an example.

Eclipse

The SimpleLanguage teaching project has been tested with Eclipse Neon.2 Release 4.6.2 and Eclipse Oxygen.1. 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 2016.3.4. Open IntelliJ IDEA and, from the main menu bar, select File -> New -> Project from existing Sources -> Select simplelanguage folder -> Check “Create module groups for multi-module Maven projects” -> Finish. All dependencies will be included automatically.

Running

To run a simple language 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.