Skip to content

Latest commit

 

History

History
155 lines (125 loc) · 7 KB

development.md

File metadata and controls

155 lines (125 loc) · 7 KB

Development

Active development is done in the main branch. Please feel free to open a pull request if you'd like to contribute a bug-fix, documentation, or a new feature. In addition to the issues, the TODOs and the test map are good starting points if you'd like to contribute to TruffleSqueak.

Building from Source

mkdir trufflesqueak-build
cd trufflesqueak-build
git clone https://github.com/graalvm/mx
git clone https://github.com/hpi-swa/trufflesqueak
cd trufflesqueak
echo "JAVA_HOME=/path/to/a/jvmci-enabled-JDK" > mx.trufflesqueak/env
../mx/mx --env trufflesqueak-jvm build
export GRAALVM_HOME=$(../mx/mx --env trufflesqueak-jvm graalvm-home)
$GRAALVM_HOME/bin/trufflesqueak path/to/a/squeaksmalltalk.image

../mx/mx --help

It is recommended to create a dedicated directory (named trufflesqueak-build in the above) to develop and build TruffleSqueak. TruffleSqueak requires the mx build tool, which will clone all dependencies (e.g. Truffle and the Graal compiler) in the parent directory of your local TruffleSqueak checkout. Using the trufflesqueak-jvm environment file ensures that the Graal compiler is built with TruffleSqueak and enabled by default. For this, however, you must use a JVMCI-enabled JDK, such as the JDK11-based LabsJDK. The environment file also instructs mx to build an installable component for the GraalVM Updater, which can be installed with:

$GRAALVM_HOME/bin/gu install -f -L \
   "$(../mx/mx --env trufflesqueak-svm paths SMALLTALK_INSTALLABLE_SVM_JAVA11)"

Development With Other GraalVM Languages

If you need access to other GraalVM languages during development, there are two options:

First, you can download the latest GraalVM dev build and install additional GraalVM languages and components using gu (e.g., gu install python). To install TruffleSqueak, follow these steps:

  1. Build TruffleSqueak via mx --env trufflesqueak-jvm build
  2. Run mx --env trufflesqueak-jvm paths SMALLTALK_INSTALLABLE_JAVA11 to find the path to the installable
  3. Install it via $GRAALVM_HOME/bin/gu install -f -L path/to/the/trufflesqueak-installable.jar
  4. Run $GRAALVM_HOME/bin/trufflesqueak

Or second, you can build other languages from source. For this, please refer to the instructions for building custom GraalVM distributions. As an example, here is how to build a GraalVM with the Graal compiler, TruffleSqueak, the GraalVM Updater, and GraalVM's Node.js runtime:

cd trufflesqueak/../graal/vm
mx --dy trufflesqueak,/graal-nodejs,/compiler build
mx --dy trufflesqueak,/graal-nodejs,/compiler graalvm-home # print path to $GRAALVM_HOME

Setting Up A New Development Environment

It is recommended to use Eclipse with the Eclipse Checkstyle Plugin for development, but note that mx also supports IntelliJ and NetBeans.

  1. Run mx eclipseinit in TruffleSqueak's root directory to create all project files for Eclipse.
  2. Import all projects from the graal repository which mx should have already cloned into the parent directory of your TruffleSqueak checkout during the build process.
  3. Import all projects from TruffleSqueak's root directory.
  4. Run TruffleSqueakLauncher to start TruffleSqueak, or continue to use mx to build and run it.

Testing

TruffleSqueak is continuously tested on different platforms and in different settings using GitHub actions. You may find the ci.yml interesting. As part of the SqueakSUnitTest test case, TruffleSqueak runs the tests of a test image and checks the results against this test map.

Debugging

To start TruffleSqueak in debug mode, you can run the following and connect your preferred Java debugger to the process:

$GRAALVM_HOME/bin/trufflesqueak \
   --vm.agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000 \
   your.image

The following runs the ArrayTest>>testAtWrap SUnit test from Squeak/Smalltalk using mx's unittest command in debug mode:

mx -d --env trufflesqueak-jvm unittest -Xss64M \
   -DsqueakTests="ArrayTest>>testAtWrap" \
   SqueakSUnitTest --very-verbose --enable-timing --color

If you want to debug an installed TruffleSqueak component, you can run the following:

trufflesqueak --vm.Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=y your.image

To list additional command-line flags for debugging, run:

trufflesqueak --help
trufflesqueak --help:languages
trufflesqueak --help:languages --help:internal

The following, for example, runs TruffleSqueak in headless mode executing 1 tinyBenchmarks with compilation traces enabled and dumps Truffle and Graal graphs for further inspection with the Ideal Graph Visualizer (igv).

trufflesqueak --code "1 tinyBenchmarks" --engine.TraceCompilation --vm.Dgraal.Dump=Truffle:1

Furthermore, TruffleSqueak comes with various infrastructures for different debugging and tracing purposes (e.g. DebugUtils and loggers). You may also find the Truffle docs useful. For additional help, feel free to join the #trufflesqueak channel on the GraalVM Slack.