Using `gu.bat` on Microsoft Windows (deprecated) ↩

TruffleSqueak is a Squeak/Smalltalk implementation for the GraalVM.
This document presents gu.bat, a batch file we wrote as a substitute for Oracle's GraalVM Updater on a Windows machine.

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

Installing TruffleSqueak on Windows
Using gu.bat on Windows (deprecated) ▼
Building TruffleSqueak on Windows

Project dependencies

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

Git 2.45 (release notes)
GraalVM Community Edition 22.3 LTS (release notes)

For instance our development environment looks as follows (July 2024) ¹:

C:\opt\Git\                      (358 MB)
C:\opt\graalvm-ce-java1-22.3.0\  (360 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:

bin\gu.bat
docs\
examples\README.md
BUILD.md
GU.md
README.md
setenv.bat

where

(deprecated) file bin\gu.bat is the batch script for installing the TruffleSqueak component on a Windows machine.
directory docs\ contains several 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.
(deprecated) file GU.md is the Markdown document for this page.
file README.md is the Markdown document presenting the installation of the TruffleSqueak component.
file setenv.bat is the batch script for setting up our environment.

We also define a virtual drive Q: 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 Q: %USERPROFILE%\workspace\trufflesqueak-examples

In the next section we give a brief overview of batch file gu.bat.

`gu.bat` overview

We wrote batch command gu.bat as a substitute for Oracle's GraalVM Updater on a Windows machine ^[2].

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

In short gu.bat:

implements a subset of the commands featured by Oracle's GraalVM Updater.
works properly given one the following two requirements is met:
- the environment variable GRAAL_HOME is defined or
- gu.bat is located in directory <graalvm-dir>\bin\.
contains ~850 lines of batch code including a few lines of PowerShell code.

Command gu -h (or gu --help) prints the following help message:

> where gu
Q:\bin\gu.bat
 
> gu -h
Usage: gu command {<option>} {<param>}
 
  Commands:
    available [-l] <expr>            List components in the component catalog.
    info [-cL] <param>               Print component information (from file, URL or catalog).
    install [-0AcfiLnoru] {<param>}  Install specified components (from file, URL or catalog).
    list [-cl] <expr>                List installed components.
    rebuild-images                   Rebuild native images.
    remove [-0fx] <id>               Remove component (ID).
    update [-x][<ver>][<param>]      Upgrade to the recent GraalVM version.
 
  Options supported by all commands:
    -d, --debug                      Show commands executed by this script.
    -h, --help                       Display this help message or a command specific help message.
    -v, --verbose                    Display progress messages.
 
  Options:
    -0, --dry-run                    Dry run. Do not change any files.
    -A, --auto-yes                   Say YES or ACCEPT to a question.
    -c, --catalog                    Treat parameters as component IDs from catalog. This is the default.
    -f, --force                      Disable (un-)installation checks.
    -i, --fail-existing              Fail if the to be installed component already exists.
    -L, --local-file                 Treat parameters as local filenames.
    -l, --list-files                 List files.
    -n, --no-progress                Do not display download progress.
    -o, --overwrite                  Silently overwrite already existing component.
    -p, --paths                      Display full paths in lists.
    -r, --replace                    Replace different files.
    -u, --url                        Treat parameters as URLs.
    -x, --ignore                     Do not terminate uninstall on failed file deletions.

🔎 The definition of the above commands and options is based on the following documentation:

Oracle GraalVM EE 19 Guide : GraalVM Updater.

GraalVM Reference Manual : GraalVM Updater.

Oracle's GraalVM Updater features seven commands and supports both long and short options ("switches").

In the next section we present usage examples of commands currently implemented in gu.bat.

`gu.bat` commands ^_▲

`gu.bat available`

Command gu.bat available with not argument displays components available from the GraalVM Catalog ^[4] which fit in our environment. For instance we get the following output with a GraalVM 21.2.0 installation on a Unix machine:

> gu available
Downloading: Component catalog
Component.21.2.0_linux_amd64.org.graalvm.llvm_toolchain-Bundle-Name=LLVM.org toolchain
Component.21.2.0_linux_amd64.org.graalvm.native_image-Bundle-Name=Native Image
Component.21.2.0_linux_amd64.org.graalvm.python-Bundle-Name=Graal.Python
Component.21.2.0_linux_amd64.org.graalvm.r-Bundle-Name=FastR
Component.21.2.0_linux_amd64.org.graalvm.ruby-Bundle-Name=TruffleRuby

🔎 The address of the GraalVM Catalog is stored in file %GRAAL_HOME%\release :
> type %GRAAL_HOME%\release | findstr /b component_catalog
component_catalog=https://www.graalvm.org/component-catalog/graal-updater-component-catalog.properties

Command gu.bat available python r with arguments python and r displays components available from the GraalVM Catalog which fit our environment:

> gu available python r
Downloading: Component catalog
Component.21.2.0_linux_amd64.org.graalvm.python-Bundle-Name=Graal.Python
Component.21.2.0_linux_amd64.org.graalvm.r-Bundle-Name=FastR

Command gu.bat available -l python r with option -l instead displays their URL addresses:

> gu available -l python r
Downloading: Component catalog
https://github.com/graalvm/graalpython/releases/download/vm-21.2.0/python-installable-svm-java8-linux-amd64-21.2.0.jar
https://github.com/oracle/fastr/releases/download/vm-21.2.0/r-installable-java8-linux-amd64-21.2.0.jar

`gu.bat info`

Command gu.bat info prints component information from file, URL or catalog.

> gu info -h
Usage: gu info [-cdhlLprstuv] {<param>}
Print component information from file, URL or catalog.
 
  Options:
    -c, --catalog     Treat parameters as component IDs from catalog. This is the default.
    -d, --debug       Show commands executed by this script.
    -h, --help        Display this help message.
    -L, --local-file  Treat parameters as local filenames of packaged components.
    -u, --url         Treat parameters as URLs.
    -v, --verbose     Enable verbose output.

Command gu.bat info -L ruby displays component information for the installed component ruby:

> gu info -L ruby
Component: ruby
   characterMimeType.0=application/x-ruby
   className=org.truffleruby.RubyLanguage
   defaultMimeType=application/x-ruby
   dependentLanguage.0=llvm
   fileTypeDetector0=org.truffleruby.RubyFileTypeDetector
   implementationName=TruffleRuby
   interactive=true
   internal=false
   name=Ruby
   version=2.6.2
   OS_NAME=linux
   OS_ARCH=amd64
   GRAALVM_VERSION=22.3.0

`gu.bat install`

Command gu.bat install installs GraalVM installable components from three different sources, namely:

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

🔎 Options -c, -L and -u are mutual exclusive:

> gu install -cL python
Error: --catalog(-c), --local-file(-L) and --url(-u) options are mutual exclusive

> gu install -h
Usage: gu install [-0cdfhiLnorv] {<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 (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.

Installation from a catalog

Command gu.bat -v install python adds the GraalPython component to our GraalVM environment:

> gu install -v python
Downloading: Component catalog graal-updater-component-catalog.properties
Processing component archive: Component python
Downloading: Component python-installable-svm-linux-amd64-22.3.0.jar
Install remote component python-installable-svm-linux-amd64-22.3.0.jar
Extract GraalVM component into directory %TEMP%\graal-updater\tmp
Create file %TEMP%\graal-updater\tmp\bin\graalpython.cmd
Create file %TEMP%\graal-updater\tmp\jre\bin\graalpython.cmd
Component ready to be installed in c:\opt\graalvm-ce-java11-22.3.0
Do you really want to add the component into directory c:\opt\graalvm-ce-java11-22.3.0 (y/*)? y
Install GraalVM component into directory c:\opt\graalvm-ce-java11-22.3.0

🔎 In the above output path %TEMP%\graal-updater is the working directory used by command gu.bat:

> dir /a-d %TEMP%\graal-updater | findstr /r /c:"^[^ ]"
23.10.2019  14:51           133 318 graal-updater-component-catalog.properties
23.10.2019  09:43        65 156 656 python-installable-svm-linux-amd64-22.3.0.jar

Installation from a local component archive

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

> echo %GRAAL_HOME%
C:\opt\graalvm-ce-java11-22.3.0
 
> curl -sL -o trufflesqueak-component.jar https://github.com/hpi-swa/trufflesqueak/releases/download/22.3.0/trufflesqueak-installable-svm-java11-windows-amd64-22.3.0.jar
 
> gu install -L trufflesqueak-component.jar
Install local component trufflesqueak-component.jar
Do you really want to add the component into directory C:\opt\graalvm-ce-java11-22.3.0 (y/*)? y

Adding option -A skips user confirmation before proceeding with the installation:

> gu install -AL trufflesqueak-component.jar
Install local component trufflesqueak-component.jar

Installation from a remote component archive

Command gu.bat install -uv https://../trufflesqueak-component-1.0.0-rc9-for-GraalVM-20.2.1.jar adds the TruffleSqueak component to our GraalVM environment.

> gu install -u trufflesqueak-installable-java8-windows-amd64-22.3.0.jar
Install remote component trufflesqueak-installable-java8-windows-amd64-22.3.0.jar
Do you really want to add the component into directory C:\opt\graalvm-ce-java8-22.3.0 (y/*)? y
Install GraalVM component into directory C:\opt\graalvm-ce-java8-22.3.0

`gu.bat list`

Command gu.bat list prints the components installed in our GraalVM environment:

> echo %GRAAL_HOME%
C:\opt\graalvm-ce-java11-22.3.0
 
> gu list
component graalpython
   OS_NAME=linux
   OS_ARCH=amd64
   SOURCE="graalpython:712a86dcc68db59113297a4d95ff640b75a0dc4f"
   GRAALVM_VERSION=22.3.0
component fastr
   OS_NAME=linux
   OS_ARCH=amd64
   SOURCE="fastr:3aa5dacd30b8d0862e91a5d19bf3b59d94365500"
   GRAALVM_VERSION=22.3.0
component truffleruby
   OS_NAME=linux
   OS_ARCH=amd64
   SOURCE="truffleruby:3b698b1a4bf9b168891f1f795858eb550c258bc7"
   GRAALVM_VERSION=22.3.0
component trufflesqueak
   OS_NAME=windows
   OS_ARCH=amd64
   SOURCE="trufflesqueak:b414a22e8e70e97674232fc30c15aac7a3853929"
   GRAALVM_VERSION=22.3.0

Command gu.bat list -c is equivalent to gu.bat available; it displays components available from the GraalVM Catalog ^[4] which fit in our environment.

`gu.bat rebuild-images`

We have no further plans to implement command gu.bat rebuild-images.

> gu.bat rebuild-images
Command rebuild-images not yet implemented
(current GraalVM version: "22.3.0")

`gu.bat remove`

Command gu remove removes the installed component specified by its component ID.

> gu remove -h
Usage: gu remove [-0dfhxv] <param>
Remove component (ID).

  Options:
    -0, --dry-run     Dry run. Do not change any files.
    -d, --debug       Show commands executed by this script.
    -f, --force       Disable uninstallation checks (eg. non-matching versions).
    -h, --help        Display this help message.
    -x, --ignore      Do not terminate uninstall on failed file deletions.
    -v, --verbose     Enable verbose output.

We have no further plans to implement command gu.bat remove.

> gu remove
Command remove not yet implemented
(current GraalVM version: "22.3.0")

`gu.bat update`

Command gu update upgrades our environment to the specified GraalVM version.

> gu update -h
Usage: gu update [-dhvx] [<ver>] [<param>]
Upgrade to the recent GraalVM version.

  Options:
    -d, --debug       Show commands executed by this script.
    -h, --help        Display this help message.
    -v, --verbose     Enable verbose output.
    -x, --ignore      Do not terminate uninstall on failed file deletions.

We have no further plans to implement command gu.bat update.

> gu update
Command update not yet implemented
(current GraalVM version: "22.3.0")

License

gu.bat is released under the MIT License.

Footnotes

[1] Downloads ↩

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

trufflesqueak-installable-svm-java11-windows-amd64-22.3.0.jar  (35 MB)
graalvm-ce-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)

[2] GraalVM Updater ↩

Command gu is not yet supported on Microsoft Windows, so we currently run our own (stripped down) command bin\gu.bat to add the TruffleSqueak component (e.g. archive file trufflesqueak-component.jar) to our GraalVM environment (e.g. c:\opt\graalvm-ce-java8-22.3.0\).

[3] Preinstalled components ↩

Component GraalJS is preinstalled in the GraalVM environment. It is a ECMAScript 2019 compliant Javascript implementation built on GraalVM (with Polyglot language interoperability support).

> where /r c:\opt\graalvm-ce-java11-22.3.0 js.cmd
c:\opt\graalvm-ce-java11-22.3.0\bin\js.cmd
c:\opt\graalvm-ce-java11-22.3.0\jre\bin\js.cmd
 
> js --version
GraalVM JavaScript (GraalVM CE Native 22.3.0)

[4] GraalVM Catalog ↩

At the time of writing the GraalVM Catalog contains no component for the Windows platform.
Components currently available are:

ID	Version(s)	Supported platform(s)
`llvm_toolchain`	19.3 20.0, 20.1, 20.2, 21.0, 21.1, 22.1	`linux_amd64`, `macos_amd64`
`native_image`	19.0, 19.1, 19.2 20.0, 20.1, 21.1, 22.1	`linux_amd64`, `macos_amd64`, `windows` (20.0+)
`python`	19.0, 19.1, 19.2 19.3, 20.0, 20.1, 21.1	`linux_amd64`, `macos_amd64`
`r`	19.0, 19.1, 19.2 19.3, 20.0, 20.1, 20.2, 21.0	`linux_amd64`, `macos_amd64`
`ruby`	19.0, 19.1, 19.2, 19.3 20.0, 20.1, 21.1	`linux_amd64`, `macos_amd64`
`wasm`	20.0, 20.1, 20.2, 21.0, 21.1	`linux_amd64`, `macos_amd64`

mics/July 2024 ▲

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GU.md

GU.md

Using `gu.bat` on Microsoft Windows (deprecated) ↩

Project dependencies

Directory structure

`gu.bat` overview

`gu.bat` commands ^_▲

`gu.bat available`

`gu.bat info`

`gu.bat install`

`gu.bat list`

`gu.bat rebuild-images`

`gu.bat remove`

`gu.bat update`

License

Footnotes

Files

GU.md

Latest commit

History

GU.md

File metadata and controls

Using gu.bat on Microsoft Windows (deprecated) ↩

Project dependencies

Directory structure

gu.bat overview

gu.bat commands ▲

gu.bat available

gu.bat info

gu.bat install

gu.bat list

gu.bat rebuild-images

gu.bat remove

gu.bat update

License

Footnotes

Using `gu.bat` on Microsoft Windows (deprecated) ↩

`gu.bat` overview

`gu.bat` commands ^_▲

`gu.bat available`

`gu.bat info`

`gu.bat install`

`gu.bat list`

`gu.bat rebuild-images`

`gu.bat remove`

`gu.bat update`