A Complete Development Setup

The Basic User Setup gives a brief set of instructions to be able to run SOMns programs. However, it does not include the setup of Node.js, which is needed for the Kómpos Web Debugger.

On Ubuntu, the necessary software can be installed with:

## First, register the Node.js package repository
curl -sL https://deb.nodesource.com/setup_9.x | sudo -E bash -
sudo apt install npm nodejs

With Homebrew, it can be installed with:

brew install node

With this being completed, the default target of Ant should complete successfully:

ant

This will compile SOMns, but also the Kómpos Web Debugger, which can also be compiled by invoking the target directly: ant kompos

Eclipse Project outline
Eclipse Project outline.

Using Eclipse to Develop the Interpreter

SOMns is currently developed with Eclipse. While other Java IDEs can also be used, for brevity, we'll focus on Eclipse only.

At the time of writing, I am using Eclipse Oxygen 4.7. Please also install the Eclipse Checkstyle Plugin from the Eclipse Marketplace.

For development, we also need to setup all Eclipse projects:

ant ideinit

After the Eclipse projects for the Truffle library were generated by this step, we can import the existing projects into Eclipse with File -> Import... -> Existing Projects into Workspace and pointing Eclipse to the SOMns folder.

I like to import the Truffle projects into a separate Truffle working set. This makes working in Eclipse with many projects easier.

The result should be looking roughly, but not exactly like in the screenshot on the right.

For debugging the interpreter with Eclipse, create a Eclipse run configuration for the SOMns project. The main class is som.VM. To run for instance the Mandelbrot benchmark, add the following as program arguments:

core-lib/Benchmarks/Harness.ns Mandelbrot 2 0 500

In VM arguments, enable assertions with:

-ea -esa

I personally start the various SOMns programs from the command line:

./som -d -G core-lib/Benchmarks/Harness.ns Mandelbrot 2 0 500

For this approach, we need a Remote Java Application debug configuration in Eclipse. After starting SOMns, it should tell you that it is waiting on port 8000, which is used as the port in the Eclipse debug configuration.

Summary

A brief list of steps:

  1. Install software dependencies: Ant, git, Java 10, Eclipse 4.7 (or later), VS Code 1.21 (or later), Node.js, NPM, Graal JIT compiler

  2. Create Truffle Eclipse projects: ant ideinit

  3. Import Eclipse projects

  4. Run ant from the command line or Eclipse

Setting up and using the Kómpos Debugger

Kómpos is a web-based debugger to work with SOMns' advanced concurrency features.

Build SOMns and Kómpos Debugger

The ant command from the command line allows to build not only SOMns but also Kómpos. Previously, we showed ant compile which does not build Kómpos. To build it, we use ant kompos or ant compile-all:

ant compile     ## does not include the Kómpos build, only SOMns build
ant kompos      ## includes only Kómpos build
ant compile-all ## includes the Kómpos and SOMns build

Run Kómpos Debugger

To debug a SOMns program, you can run from the command line the command ./som -G -wd pathToFile. The -wd indicates that we want to use the "web debugger", i.e., Kómpos. For example, we can run a simple ping/pong actor program from the SOMns folder:

cd SOMns
./som  -G  -wd tools/kompos/tests/pingpong.ns

The terminal indicates that the debugger has started with the following log:

[DEBUGGER] Initialize HTTP and WebSocket Server for Debugger
[DEBUGGER] Started WebSocket Servers
[DEBUGGER]   Message Handler: 7977
[DEBUGGER]   Trace Handler:   7978
[DEBUGGER] Started HTTP Server
[DEBUGGER]   URL: http://localhost:8888/index.html
[DEBUGGER] Waiting for debugger to connect.
[DEBUGGER] Debugger connected.

To open Kómpos we access the following URL in the browser: http://localhost:8888/index.html

To have the debugger stop automatically, we can add 1 halt. in the source code before running Kómpos. We can add it for instance in the benchmark method like this:

public benchmark = (
  | ping pong completionPP p |
  1 halt.
  completionPP:: actors createPromisePair.

  (* ... *)
)

Run tests for Kómpos Debugger

To run the existing Typescript tests for Kómpos you need to go to tools/kompos folder and execute the following npm command:

npm test

You can enable the additional interpreter output by setting PRINT_SOM_OUTPUT in the file tools/kompos/test-setup.ts to true.