Playing with TruffleSqueak on Windows

This repository gathers Squeak code examples coming from various websites and books.
It also includes several batch files for experimenting with TruffleSqueak on a Windows machine.

This document is part of a series of topics related to TruffleSqueak on Windows:

Installing TruffleSqueak on Windows ▼
Building TruffleSqueak on Windows

Ada, Akka, C++, Dart, Deno, Flix, Golang, GraalVM, Haskell, Kafka, Kotlin, LLVM, Node.js, Rust, Scala 3, Spark, Spring and WiX Toolset are other trending topics we are continuously monitoring.

Project dependencies

This project depends on the following external software for the Microsoft Windows platform:

Optionally one may also install the following software:

Squeak 6.0 ¹

For instance our development environment looks as follows (June 2023) ²:

C:\opt\graalvm-ce-java11-22.3.0\³   (653 MB)
C:\opt\graalvm-ce-java17-22.3.0\    (447 MB)
C:\opt\Git-2.41.0\                  (314 MB)
C:\opt\Squeak-6.0\                  (130 MB)

☛ Installation policy
When possible we install software from a Zip archive rather than via a Windows installer. In our case we defined C:\opt\ as the installation directory for optional software tools (in reference to the /opt/ directory on Unix).

Directory structure

This project is organized as follows:

docs\
examples\README.md
BUILD.md
README.md
RESOURCES.md
setenv.bat

where

directory docs\ contains TruffleSqueak related papers/articles.
directory examples\ contains Squeak code examples (see examples\README.md).
file BUILD.md is the Markdown document presenting the generation of the TruffleSqueak component.
file README.md is the Markdown document for this page. $ file [RESOURCES.md] is the Markdown document presenting external resources.
file setenv.bat is the batch script for setting up our environment.

We also define a virtual drive T: in our working environment in order to reduce/hide the real path of our project directory (see article "Windows command prompt limitation" from Microsoft Support).

🔎 We use the Windows external command subst to create virtual drives; for instance:
> subst T: %USERPROFILE%\workspace\trufflesqueak-examples

In the next section we give a brief description of the batch files present in this project.

Batch commands ▴

We distinguish different sets of batch commands:

setenv.bat - This batch command makes external tools such as java.exe and git.exe directly available from the command prompt (see section Project dependencies).

 > setenv help
 Usage: setenv { <option> | <subcommand> }
  
   Options:
     -debug      show commands executed by this script
     -travis     start Git bash shell instead of Windows command prompt
     -verbose    display progress messages
  
   Subcommands:
     help        display this help message

In the next section we present usage examples of the batch files present in this project.

Usage examples

`setenv.bat`

Command setenv is executed once to setup our development environment; it makes external tools such as jar.exe and git.exe directly available from the command prompt:

> setenv
Tool versions:
   python 3.11.1, pylint 2.17.1, javac 11.0.18
   git 2.41.0.windows.1, bash 5.2.15(1)-release

> where git link
C:\opt\Git-2.41.0\bin\git.exe
C:\opt\Git-2.41.0\mingw64\bin\git.exe
C:\opt\Git-2.41.0\usr\bin\link.exe

Command setenv -verbose also displays the tool paths:

> setenv -verbose
Tool versions:
   python 3.11.1, pylint 2.17.1, javac 11.0.18
   git 2.41.0.windows.1, bash 5.2.15(1)-release
Tool paths:
   C:\opt\Python-3.11.1\python.exe
   C:\opt\Python-3.11.1\Scripts\pylint.exe
   C:\opt\graalvm-ce-java11-22.3.0\bin\javac.exe
   C:\opt\Git-2.41.0\bin\git.exe
   C:\opt\Git-2.41.0\mingw64\bin\git.exe
   C:\opt\Git-2.41.0\bin\bash.exe
Environment variables:
   "GIT_HOME=C:\opt\Git-2.41.0"
   "GRAALVM_HOME=C:\opt\graalvm-ce-java11-22.3.0"
   "JAVA_HOME=C:\opt\graalvm-ce-java11-22.3.0"
   "MSVC_HOME=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC"
   "MSVS_HOME=C:\Program Files (x86)\Microsoft Visual Studio\2019"
   "PYTHON_HOME=C:\opt\Python-3.11.1"

`gu.bat install` (deprecated)

☛ Starting with version 20.0 command gu.cmd is part of the GraalVM distribution; Windows users should use gu.cmd instead of gu.bat.

Command gu.bat install -h displays the help message for command install.

> gu install -h
Usage: gu install [-0cdfhiLnoruv] {<param>}
Install specified components from file, URL or catalog.
 
  Options:
    -0, --dry-run        Dry run. Do not change any files.
    -c, --catalog        Treat parameters as component IDs from catalog. This is the default.
    -d, --debug          Show commands executed by this script.
    -f, --force          Disable installation checks.
    -h, --help           Display this help message.
    -i, --fail-existing  Fail if the to be installed component already exists.
    -L, --local-file     Treat parameters as local filenames of packaged components.
    -n, --no-progress    Do not display download progress.
    -o, --overwrite      Silently overwrite previously installed component.
    -r, --replace        Replace different files.
    -u, --url            Treat parameters as URLs
    -v, --verbose        Enable verbose output.

Command gu.bat install can add GraalVM installable components in three different ways, namely:

from a catalog (default, option -c)
from a local component archive (option -L)
from a remote component archive (option -u)

We present below the installation from a local TruffleSqueak component archive; further usage examples are available in document GU.md.

Let's first download TruffleSqueak component archive from the TruffleSqueak repository:

> curl -sL -o trufflesqueak-installable.jar https://github.com/hpi-swa/trufflesqueak/releases/download/22.3.0/trufflesqueak-installable-java8-windows-amd64-22.3.0.jar

Command gu.bat install -L trufflesqueak-component.jar adds the TruffleSqueak component to our GraalVM environment.

> echo %GRAALVM_HOME%
C:\opt\graalvm-ce-java11-22.3.0
 
> gu install -L trufflesqueak-installable.jar
Processing Component archive: trufflesqueak-installable-java11-windows-amd64-22.3.0.jar
Installing new component: TruffleSqueak (org.graalvm.smalltalk, version 22.3.0)

The GraalVM installation directory looks as follows after adding the TruffleSqueak component:

> where /r c:\opt\graalvm-ce-java11-22.3.0 *squeak*
c:\opt\graalvm-ce-java11-22.3.0\bin\trufflesqueak-launcher.cmd
c:\opt\graalvm-ce-java11-22.3.0\bin\trufflesqueak.cmd
c:\opt\graalvm-ce-java11-22.3.0\languages\smalltalk\trufflesqueak-shared.jar
c:\opt\graalvm-ce-java11-22.3.0\languages\smalltalk\trufflesqueak-shared.src.zip
c:\opt\graalvm-ce-java11-22.3.0\languages\smalltalk\trufflesqueak.jar
c:\opt\graalvm-ce-java11-22.3.0\languages\smalltalk\trufflesqueak.src.zip
c:\opt\graalvm-ce-java11-22.3.0\languages\smalltalk\bin\trufflesqueak-launcher.exe
c:\opt\graalvm-ce-java11-22.3.0\languages\smalltalk\bin\trufflesqueak.cmd
c:\opt\graalvm-ce-java11-22.3.0\lib\graalvm\trufflesqueak-launcher.jar
c:\opt\graalvm-ce-java11-22.3.0\lib\graalvm\trufflesqueak-launcher.src.zip

🔎 In the above output both command files bin\trufflesqueak.cmd and jre\bin\trufflesqueak.cmd simply forward the call to command file jre\languages\smalltalk\bin\trufflesqueak.cmd (on Unix systems two symbolic links are created instead).
> type c:\opt\graalvm-ce-java11-22.3.0\bin\trufflesqueak.cmd
@echo off
 
call :getScriptLocation location
set "GRAALVM_ARGUMENT_VECTOR_PROGRAM_NAME=%~0"
"%location%..\languages\smalltalk\bin\trufflesqueak.cmd" %*
exit /b %errorlevel%
 
:: If this script is in `%PATH%` and called quoted without a full path (e.g., `"js"`), `%~dp0` is expanded to `cwd`
:: rather than the path to the script.
:: This does not happen if `%~dp0` is accessed in a subroutine.
:getScriptLocation variableName
    set "%~1=%~dp0"
    exit /b 0
 
> type c:\opt\graalvm-ce-java11-22.3.0\jre\bin\trufflesqueak.cmd
@echo off
 
call :getScriptLocation location
"%location%..\languages\smalltalk\bin\trufflesqueak.cmd" %*
goto :eof
...
Command file jre\languages\smalltalk\bin\trufflesqueak.cmd itself is copied from template file template.trufflesqueak.cmd during the generation of the TruffleSqueak component.

Squeak execution ▴

Command trufflesqueak.cmd --help prints the usage message:

> where trufflesqueak
C:\opt\graalvm-ce-java11-22.3.0\bin\trufflesqueak.cmd
 
> trufflesqueak.cmd --help
Usage: trufflesqueak [options]  [image arguments]

Basic options:
Jan 07, 2023 11:15:48 AM org.graalvm.shadowed.org.jline.utils.Log logr
WARNING: Unable to create a system terminal, creating a dumb terminal (enable debug logging for more information)
  --code "<code>", -c "<code>"                 Smalltalk code to be executed without display
  --enable-transcript-forwarding               Forward stdio to Smalltalk transcript
  --headless                                   Run without a display
  --print-image-path                           Print the path to default Squeak/Smalltalk image
  --quiet                                      Operate quietly

Runtime options:
  --polyglot                                   Run with all other guest languages accessible.
  --native                                     Run using the native launcher with limited access to Java libraries
                                               (default).
  --jvm                                        Run on the Java Virtual Machine with access to Java libraries.
  --vm.[option]                                Pass options to the host VM. To see available options, use '--help:vm'.
  --log.file=<String>                          Redirect guest languages logging into a given file.
  --log.[logger].level=<String>                Set language log level to OFF, SEVERE, WARNING, INFO, CONFIG, FINE,
                                               FINER, FINEST or ALL.
  --help                                       Print this help message.
  --help:vm                                    Print options for the host VM.
  --help:engine                                Print engine options.
  --help:all                                   Print all options.
  --version:graalvm                            Print GraalVM version information and exit.
  --show-version:graalvm                       Print GraalVM version information and continue execution.

Languages:
  [id]        [name]                  [website]
  java        Java                    https://www.graalvm.org/dev/reference-manual/java-on-truffle/
  smalltalk   Squeak/Smalltalk        https://github.com/hpi-swa/trufflesqueak

Tools:
  [id]        [name]                  [website]
  agentscript Agent Script
  coverage    Code Coverage           https://www.graalvm.org/tools/code-coverage/
  cpusampler  CPU Sampler             https://www.graalvm.org/tools/profiling/
  cputracer   CPU Tracer              https://www.graalvm.org/tools/profiling/
  dap         Debug Protocol Server   https://www.graalvm.org/tools/dap/
  heap        Heap Dump
  heapmonitor Heap Allocation Monitor
  insight     Insight                 https://www.graalvm.org/tools/graalvm-insight/
  inspect     Chrome Inspector        https://www.graalvm.org/tools/chrome-debugger/
  lsp         Language Server         https://www.graalvm.org/tools/lsp/
  memtracer   Memory Tracer           https://www.graalvm.org/tools/profiling/

  Use --help:[id] for component options.

See http://www.graalvm.org for more information.

Command trufflesqueak --version:graalvm prints the version of the installed languages and tools:

> %GRAALVM_HOME%\bin\trufflesqueak.cmd --version:graalvm
GraalVM CE JVM Polyglot Engine Version 22.3.0
Java Version 11.0.18
Java VM Version 11.0.18+8-jvmci-22.3-b08
GraalVM Home C:\opt\graalvm-ce-java11-22.3.0
  Installed Languages:
    Java             version 22.3.0
    Squeak/Smalltalk version 22.3.0
  Installed Tools:
    Agent Script            version 1.2
    Code Coverage           version 0.1.0
    CPU Sampler             version 0.5.0
    CPU Tracer              version 0.3.0
    Debug Protocol Server   version 0.1
    Heap Dump               version 22.3.0
    Heap Allocation Monitor version 0.1.0
    Insight                 version 1.2
    Chrome Inspector        version 0.1
    Language Server         version 0.1
    Memory Tracer           version 0.2

Command trufflesqueak (with no argument) opens a dialog window for selecting a Squeak image before starting the Squeak IDE.

🔎 We have the choice between two Squeak images:

TruffleSqueak project : TruffleSqueakImage-<version>.image.

Squeak project : Squeak<version>-64bit.image.

Command trufflesqueak TruffleSqueak-22.3.0.image ⁴ starts the Squeak IDE and loads the provided Squeak image.

(Click to enlarge)

Code examples are presented in document examples\README.md.

Footnotes ▴

[1] Squeak image ↩

A Squeak image is required to run/test the TruffleSqueak installable component. Concretely we can either install the full Squeak distribution (32 MB) or we can just download the Squeak image (18 MB).

[2] Downloads ↩

In our case we downloaded the following installation files (see section 1):

trufflesqueak-installable-svm-java11-windows-amd64-22.3.0.jar  (  5 MB)
trufflesqueak-installable-svm-java17-windows-amd64-22.3.0.jar  (  5 MB)
graalvm-ce-java11-windows-amd64-22.3.0.zip          (154 MB)
graalvm-ce-java17-windows-amd64-22.3.0.zip          (154 MB)
PortableGit-2.41.0-64-bit.7z.exe                    ( 41 MB)
Squeak6.0-22104-64bit-202206021410-Windows-x64.zip  ( 33 MB)

[3] GraalVM and Java 8 ↩

Starting with version 21.3 GraalVM distributions are targeting Java 11 and Java 17; Java 8 users need to stay with GraalVM version 21.2.

[4] TruffleSqueak-22.3.0.image ↩

> curl -sL -o TruffleSqueakImage-22.3.0.zip https://github.com/hpi-swa/trufflesqueak/releases/download/22.3.0/TruffleSqueakImage-22.3.0.zip
 
> unzip -qo TruffleSqueakImage-22.3.0.zip
  
> trufflesqueak.cmd TruffleSqueak-22.3.0.image

The contents of downloaded archive file TruffleSqueakImage.zip looks as follows:

> unzip -l TruffleSqueakImage-22.3.0.zip
Archive:  archives_LOCAL\TruffleSqueakImage-22.3.0.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
 68641096  10/29/2022 22:36   TruffleSqueak-22.3.0.image
 24188653  10/29/2022 22:36   TruffleSqueak-22.3.0.changes
 35184983  02/06/2017 09:21   SqueakV50.sources
---------                     -------
128014732                     3 filesdir

mics/June 2023 ▲

michelou / trufflesqueak-examples

Playing with TruffleSqueak on Windows

Project dependencies

Directory structure

Batch commands ▴

Usage examples

`setenv.bat`

`gu.bat install` (deprecated)

Squeak execution ▴

Footnotes ▴

About

Languages

Playing with TruffleSqueak on Windows

Project dependencies

Directory structure

Batch commands ▴

Usage examples

setenv.bat

gu.bat install (deprecated)

Squeak execution ▴

Footnotes ▴

About

Languages

`setenv.bat`

`gu.bat install` (deprecated)