From 5b8c6958c4bcf2b0eb0d9e079cc413ff89c92c9d Mon Sep 17 00:00:00 2001
From: Curtis Rueden <ctrueden@wisc.edu>
Date: Sun, 25 Jun 2023 16:05:38 -0500
Subject: [PATCH] Update recommended openjdk version from 8 to 11

And add notes about how version 8 is broken for M1 Macs.

See #267.
---
 doc/Install.md         | 19 ++++++++++---------
 doc/Troubleshooting.md | 11 +++++++++++
 2 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/doc/Install.md b/doc/Install.md
index 6b1b8e12..d2f99d14 100644
--- a/doc/Install.md
+++ b/doc/Install.md
@@ -22,14 +22,15 @@ environments.
 
 2. Install PyImageJ into a new environment:
    ```
-   mamba create -n pyimagej pyimagej openjdk=8
+   mamba create -n pyimagej pyimagej openjdk=11
    ```
 
-   This command will install PyImageJ with OpenJDK 8. If you would rather use
-   OpenJDK 11, you can write `openjdk=11` instead, or even just leave off the
-   `openjdk` part altogether to get the latest version of OpenJDK. PyImageJ
-   has been tested most thoroughly with OpenJDK 8, but it is also known to
-   work with OpenJDK 11, and likely later OpenJDK versions as well.
+   This command will install PyImageJ with OpenJDK 11. PyImageJ requires a
+   minimum of OpenJDK 8. PyImageJ has been tested most thoroughly with OpenJDKs
+   8 and 11, but it is likely to work with later OpenJDK versions as well.
+
+   *Please note that openjdk=8 from conda-forge is broken on M1 Mac.*
+   If you are using an M1 Mac, you should use openjdk=11 or newer.
 
 3. Whenever you want to use PyImageJ, activate its environment:
    ```
@@ -83,7 +84,7 @@ It is possible to dynamically install PyImageJ from within a Jupyter notebook.
 For your first cell, write:
 ```
 import sys, os
-!mamba install --yes --prefix {sys.prefix} pyimagej openjdk=8
+!mamba install --yes --prefix {sys.prefix} pyimagej openjdk=11
 os.environ['JAVA_HOME'] = os.sep.join(sys.executable.split(os.sep)[:-2] + ['jre'])
 ```
 
@@ -119,7 +120,7 @@ on Google Colab with a wrapped local Fiji installation:
 
 3.  Install PyImageJ:
     ```python
-    !mamba install pyimagej openjdk=8
+    !mamba install pyimagej openjdk=11
     ```
     You can also install other deps here as well (scikit-image, opencv, etc).
 
@@ -166,7 +167,7 @@ RUN apt-get install -y wget unzip > /dev/null && rm -rf /var/lib/apt/lists/* > /
 RUN micromamba install -y -n base -c conda-forge \
         python=3.8\
         pyimagej  \
-        openjdk=8 && \
+        openjdk=11 && \
     micromamba clean --all --yes
 ENV JAVA_HOME="/usr/local"
 # Set MAMVA_DOCKERFILE_ACTIVATE (otherwise python will not be found)
diff --git a/doc/Troubleshooting.md b/doc/Troubleshooting.md
index 5639f7ea..095c1f93 100644
--- a/doc/Troubleshooting.md
+++ b/doc/Troubleshooting.md
@@ -145,6 +145,17 @@ This indicates the Maven executable wasn't found on your system.
 
 If you installed `maven` via conda/mamba on Windows, you may have gotten a version that was [briefly broken](https://github.com/conda-forge/maven-feedstock/issues/26). You should be able to simply update with `conda update -n pyimagej maven` (adjusted if you named your environment something other than `pyimagej`).
 
+### Command died with Signals.SIGKILL: 9
+
+If you see an error like:
+```
+subprocess.CalledProcessError: Command '['.../jre/bin/java', '-version']' died with <Signals.SIGKILL: 9>.
+```
+it might be that you are using an M1 Mac, and have OpenJDK 8 installed from conda-forge?
+Unfortunately, Version 8 of OpenJDK from conda-forge is known to be broken on Mac M1 machines.
+
+Try `mamba install openjdk=11` to update to version 11, and this problem should go away.
+
 ### Error in "mvn.CMD -B -f pom.xml" dependency:resolve: 1
 
 This indicates a problem running Maven on your system.