The som Launcher Script

To document, simplify, and standardize how SOMns is started or debugged, we use a Python script to execute the actual Java program.

The Python script manages various command-line parameters and selects the JVM to be used for execution.

Below, we see that ./som --help supports a large set of options, of which we detail only a few.

The basic options include -d to allow us to attach a Java debugger, for instance from Eclipse, -dnu to print stack traces on a #doesNotUnderstand message, or -G to run without Graal-based JIT compilation. Generally, the options are designed to use upper-case shorthands when they disable a feature.

Further below, we see different categories of other options. This includes flags to investigate and understand how Graal executes the interpreter, options for various profiling tools, as well as tools for SOMns code coverage, dynamic execution metrics, or interactive debugging of SOMns code (currently called 'web debugger' -wd).

$ ./som --help
usage: som [-h] [-d] [-t THREADS] [-p SOM_PLATFORM] [-k SOM_KERNEL] [-dnu]
           [-i] [-if] [-io ONLY_IGV] [-l] [-ti] [-w] [-f] [-v] [-gp] [-ga]
           [-gi] [-gb] [-tp] [-td] [-wd] [-dm] [-at]
           [-atcfg ACTOR_TRACING_CFG] [-mt] [-tf TRACE_FILE] [-TF]
           [--coverage COVERAGE] [-o ONLY_COMPILE] [-A] [-B] [-C] [-G] [-X]
           [-T] [--no-graph-pe] [-vv] [--print-graal-options]
           [-D JAVA_PROPERTIES]
           ...

optional arguments:
  -h, --help                   show this help message and exit
  -d, --debug                  wait for debugger to attach
  -dnu, --stack-trace-on-dnu   print a stack trace on #doesNotUnderstand:
  -G, --interpreter            run without Graal

Investigate Execution
  -i, --igv                    dump compilation details to IGV
  -l, --low-level              enable low-level optimization output
  -v, --visual-vm              connect to VisualVM for profiling

Profile Execution
  -gp, --graal-profile         enable Graal-level profiling after warmup
  -tp, --truffle-profile       enable Graal-level profiling after warmup

Tools
  -td, --truffle-debugger      start Truffle debugger
  -wd, --web-debugger          start Web debugger
  -dm, --dynamic-metrics       capture Dynamic Metrics
  --coverage COVERAGE          determine code coverage and store in given file