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:
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:
This will compile SOMns, but also the Kómpos Web Debugger, which can also be
compiled by invoking the target directly:
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.
For development, we also need to setup all Eclipse projects:
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:
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.
A brief list of steps:
Install software dependencies: Ant, git, Java 10, Eclipse 2021-03 (or later), VS Code 1.21 (or later), Node.js, NPM, Graal JIT compiler
Create Truffle Eclipse projects:
Import Eclipse projects
antfrom 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¶
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 ## 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
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:
You can enable the additional interpreter output by setting
in the file