trufflesqueak: Instructions file for Codex

TruffleSqueak Agent Reference

Preflight Checks

Run these before spending time on build failures:

java --version
mx --version
python3 --version
cmake --version
python3 -c "import re; print(re.search(r'\"version\"\s*:\s*\"(\d+\.\d+\.\d+)', open('mx.trufflesqueak/suite.py').read()).group(1))"

The GraalVM version should match mx.trufflesqueak/suite.py.

Setup

Prefer the following manual setup below for local development:

# Install dependencies (Ubuntu 24.04)
sudo apt-get update
sudo apt-get install -y build-essential zlib1g-dev cmake python3-pip

# Install Oracle GraalVM matching the current suite version.
# If SDKMAN is available, this is the easiest option:
sdk install java <graalvm-version>-graal
sdk use java <graalvm-version>-graal
# Alternatively, use `mx fetch-jdk`.

# Install pre-commit hooks
python3 -m pip install --user pre-commit
pre-commit install

# Work from the parent directory of the TruffleSqueak checkout
export TS_WORKSPACE="$(cd .. && pwd)"

# Clone mx next to trufflesqueak and add it to PATH
git clone https://github.com/graalvm/mx.git "$TS_WORKSPACE/mx"
export PATH="$TS_WORKSPACE/mx:$PATH"

# Clone graal next to trufflesqueak and apply the checked-in patch
mx sforceimport
(cd "$TS_WORKSPACE/graal" && git apply "$TS_WORKSPACE/trufflesqueak/mx.trufflesqueak/graalvm-<graalvm-version>.patch")

Build and Run

Read mx.trufflesqueak/suite.py first. It is the quickest way to understand project names, imported suites, and distribution names.

# Build JVM standalone (faster to build) and find the target build directory
mx --env jvm build
mx --env jvm paths --output "TRUFFLESQUEAK_JVM_STANDALONE"

# Build native standalone (slower to build) and find the target build directory
mx --env native build --build-log important
mx --env native paths --output "TRUFFLESQUEAK_NATIVE_STANDALONE"

# Launch TruffleSqueak from the standalone's bin/ directory
trufflesqueak --headless --quiet -- --evaluate "<smalltalk code>"

# Run 10 iterations of the Towers benchmark from AWFY
trufflesqueak --headless --quiet -- --evaluate "AWFYHarness run: #('Towers' 10 1500)"

# Run TruffleSqueak tests
trufflesqueak --vm.ea --download-image trufflesqueak-test -- src/image-tests/runSqueakTests.st

# Run Cuis tests
trufflesqueak --vm.ea --download-image cuis-7.5-test -- -s src/image-tests/runCuisTests.st