[GR-65257] Espresso: Add note for macOS in README

PullRequest: graal/20885

Author: lewurm

docs/reference-manual/java-on-truffle/README.md

@@ -33,15 +33,22 @@ Espresso passes the Java Compatibility Kit (JCK or TCK for Java SE).
 Espresso is available as a standalone distribution that provides a Java 21 environment.
 You can download a standalone based on Oracle GraalVM or GraalVM Community Edition.
 
-1. Download the Espresso 24.2 standalone for your operating system:
+1. Download the Espresso 24.2.1 standalone for your operating system:
 
-   * [Linux x64](https://gds.oracle.com/download/espresso/archive/espresso-java21-24.2.0-linux-amd64.tar.gz)
-   * [Linux AArch64](https://gds.oracle.com/download/espresso/archive/espresso-java21-24.2.0-linux-aarch64.tar.gz)
-   * [macOS x64](https://gds.oracle.com/download/espresso/archive/espresso-java21-24.2.0-macos-amd64.tar.gz)
-   * [macOS AArch64](https://gds.oracle.com/download/espresso/archive/espresso-java21-24.2.0-macos-aarch64.tar.gz)
-   * [Windows x64](https://gds.oracle.com/download/espresso/archive/espresso-java21-24.2.0-windows-amd64.zip)
+   * [Linux x64](https://gds.oracle.com/download/espresso/archive/espresso-java21-24.2.1-linux-amd64.tar.gz)
+   * [Linux AArch64](https://gds.oracle.com/download/espresso/archive/espresso-java21-24.2.1-linux-aarch64.tar.gz)
+   * [macOS x64](https://gds.oracle.com/download/espresso/archive/espresso-java21-24.2.1-macos-amd64.tar.gz)
+   * [macOS AArch64](https://gds.oracle.com/download/espresso/archive/espresso-java21-24.2.1-macos-aarch64.tar.gz)
+   * [Windows x64](https://gds.oracle.com/download/espresso/archive/espresso-java21-24.2.1-windows-amd64.zip)
 
 2. Unzip the archive:
+
+   > Note: If you are using macOS Catalina and later you may need to remove the quarantine attribute:
+    ```shell
+    sudo xattr -r -d com.apple.quarantine <archive>.tar.gz
+    ```
+
+   Extract:
     ```shell
     tar -xzf <archive>.tar.gz
     ```

espresso/docs/hacking.md

@@ -82,7 +82,7 @@ $ cd ../vm
 $ mx --dy /espresso,/sulong maven-deploy --tags=public --all-suites --all-distribution-types --version-suite=sdk --suppress-javadoc
 ```
 
-You can now depend on the jars using a version like `24.2.0-SNAPSHOT`.
+You can now depend on the jars using a version like `24.2.1-SNAPSHOT`.
 
 ## `mx espresso-embedded ...`
 
@@ -113,12 +113,43 @@ $ mx espresso --java.JavaHome=/path/to/java/11/home -version
 
 ## Limitations
 
+### Linux
+
 Espresso relies on glibc's [dlmopen](https://man7.org/linux/man-pages/man3/dlopen.3.html) to run on HotSpot, but this approach has limitations that lead to crashes e.g. `libnio.so: undefined symbol: fstatat64` . Some of these limitations can be by avoided by defining `LD_DEBUG=unused` e.g.
 
 ```bash
 $ LD_DEBUG=unused mx espresso -cp mxbuild/dists/jdk1.8/espresso-playground.jar com.oracle.truffle.espresso.playground.Tetris
 ```
 
+### macOS
+
+On macOS there is nothing like `dlmopen` available, therefore `jvm-ce` does not work. However, there is another mode available where libraries can be executed via Sulong (internally called `nfi-llvm`). This requires the OpenJDK libraries to be compiled with the Sulong toolchain, such builds are available through `mx fetch-jdk` with a `-llvm` suffix. Unfortunately this mode is only supported on `darwin-amd64`, so on an Apple Silicon machine the `x86_64` emulator Rosetta 2 must be used:
+
+```bash
+$ arch -arch x86_64 zsh
+
+$ export MX_PYTHON=`xcode-select -p`/usr/bin/python3
+$ file $MX_PTYHON
+/Applications/Xcode16.2.app/Contents/Developer/usr/bin/python3: Mach-O universal binary with 2 architectures: [x86_64:Mach-O 64-bit executable x86_64] [arm64:Mach-O 64-bit executable arm64]
+/Applications/Xcode16.2.app/Contents/Developer/usr/bin/python3 (for architecture x86_64):	Mach-O 64-bit executable x86_64
+/Applications/Xcode16.2.app/Contents/Developer/usr/bin/python3 (for architecture arm64):	Mach-O 64-bit executable arm64
+
+$ # the important part above is that there is also a Mach-O included for x86_64
+
+$ cd $graal/espresso
+$ mx fetch-jdk # fetch JDK latest, 21 and 21-llvm
+
+$ export ESPRESSO_JAVA_HOME=<JDK21 path for amd64>
+$ export LLVM_JAVA_HOME=<JDK21-llvm path for amd64>
+$ export JAVA_HOME=<JDK-latest path for amd64>
+
+$ # Note: ESPRESSO_JAVA_HOME and LLVM_JAVA_HOME must match regarding version.
+
+$ mx --env jvm-ce-llvm build
+
+```
+
+
 ## _Espressoⁿ_ Java-ception
 
 Espresso can run itself. **Self-hosting requires a Linux distribution with an up-to-date glibc.**