From dfad7a4e25170327bab8886e68493c334ffeaa13 Mon Sep 17 00:00:00 2001
From: Joshua Horton <joshua_horton@sil.org>
Date: Mon, 19 May 2025 12:29:23 +0700
Subject: [PATCH] maint: update macOS env setup + documentation

Fixes: #13177

We now need to install sdkmanager through a different Homebrew package /
"cask".  This does get us `sdkmanager`, but it has a new default location
for its Android SDK, while our builds still refer to the old location
under the home directory.  The build script thus needs a bit of tweaking
to force `sdkmanager` to operate based on the location we've previously
referred to.

Additionally, macOS machines typically default to the zsh terminal these
days, so the old profile auto-config doesn't work.  This adds and
documents example profile script that can be used to configure a macOS
dev machine's terminal environment.
---
 docs/build/macos.md                        | 36 +++++++++++++++++++---
 resources/devbox/macos/keyman.macos.env.sh |  4 +--
 resources/devbox/macos/macos.sh            | 15 ++++++---
 3 files changed, 44 insertions(+), 11 deletions(-)

diff --git a/docs/build/macos.md b/docs/build/macos.md
index f961942070..99041ffede 100644
--- a/docs/build/macos.md
+++ b/docs/build/macos.md
@@ -50,10 +50,38 @@ The remaining dependencies can be installed via script:
 This script will also update your environment to the values in:
   `resources/devbox/macos/keyman.macos.env.sh`
 
-It will also add these environment settings to your `~/.bashrc`.
-
 These dependencies are also listed below if you'd prefer to install manually.
 
+### Example shell profile script
+
+`keyman.macos.env.sh` may be `source`d within your `~/.bashrc` / `~/.zprofile` in
+order to regularly apply its path settings to the terminal during local development.
+
+For a `.zprofile`...
+
+```zsh
+# Adds homebrew-managed dependencies to $PATH
+eval "$(/opt/homebrew/bin/brew shellenv)"
+
+# Replace right-hand side with the path to your local copy of the repo
+export KEYMAN_ROOT=~/keymanapp/keyman
+
+# May be called to apply build-path settings, such as those allowing
+# direct call of npm scripts without `npm run`.
+set_keyman_standard_build_path() {
+  PATH="${KEYMAN_ROOT}/node_modules/.bin:$PATH"
+}
+
+# builder-script tab autocompletion
+autoload -Uz compinit && compinit
+autoload bashcompinit
+bashcompinit
+source "${KEYMAN_ROOT}/resources/builder_completion.sh"
+
+# environment variable initialization
+source "${KEYMAN_ROOT}/resources/devbox/macos/keyman.macos.env.sh"
+```
+
 ## Shared Dependencies
 
 * HomeBrew, Bash 5.0+, jq, Python 2.7, Python 3, Meson, Ninja, coreutils, Pandoc
@@ -155,10 +183,10 @@ brew install carthage cocoapods
 
 ## Keyman for Android Dependencies
 
-* openjdk 11, Android SDK, Android Studio, Ant, Gradle, Maven
+* openjdk 21, Android SDK, Android Studio, Ant, Gradle, Maven
 
 ```shell
-brew install openjdk@11 android-sdk android-studio ant gradle maven
+brew install openjdk@21 android-sdk android-studio ant gradle maven
 # update path
 source ../resources/devbox/macos/keyman.macos.env.sh
 # optionally install sdk images
diff --git a/resources/devbox/macos/keyman.macos.env.sh b/resources/devbox/macos/keyman.macos.env.sh
index 5250856f9c..5ffb36eaaf 100755
--- a/resources/devbox/macos/keyman.macos.env.sh
+++ b/resources/devbox/macos/keyman.macos.env.sh
@@ -20,8 +20,8 @@ if [ -z "$HOMEBREW_PREFIX" ]; then
 fi
 
 export PATH="$HOMEBREW_PREFIX/opt/coreutils/libexec/gnubin:$PATH"
-export PATH="$HOMEBREW_PREFIX/opt/java11/bin:$PATH"
-export JAVA_HOME="$HOMEBREW_PREFIX/opt/java11"
+export PATH="$HOMEBREW_PREFIX/opt/openjdk@21/bin:$PATH"
+export JAVA_HOME="$HOMEBREW_PREFIX/opt/openjdk@21"
 
 # Python 2.7
 eval "$(pyenv init --path)"
diff --git a/resources/devbox/macos/macos.sh b/resources/devbox/macos/macos.sh
index 5a3914d9a7..68913942e7 100755
--- a/resources/devbox/macos/macos.sh
+++ b/resources/devbox/macos/macos.sh
@@ -148,7 +148,7 @@ BREW_ALL="bash jq python3 meson ninja coreutils pyenv"
 BREW_WEB="node emscripten"
 BREW_IOS="swiftlint carthage"
 BREW_MACOS="carthage cocoapods"
-BREW_ANDROID="openjdk@8 android-sdk android-studio ant gradle maven"
+BREW_ANDROID="openjdk@21 android-commandlinetools android-studio ant gradle maven"
 
 # Turn on verbosity
 set -x
@@ -169,16 +169,21 @@ pyenv global 2.7.18
 source "$THIS_DIR/keyman.macos.env.sh"
 
 $REQUIRE_ANDROID && (
-    mkdir -p .android && touch ~/.android/repositories.cfg
+    mkdir -p ~/.android && touch ~/.android/repositories.cfg
+    SDK_ROOT=~/.android
 
+    # installed via android-commandlinetools
     which sdkmanager || (
         echo "Please run Android Studio to install the Android SDK tools."
         read -p "Press ENTER to continue after installation"
         PATH="$HOME/Library/Android/sdk/tools/bin:$PATH"
     )
-    sdkmanager "system-images;android-30;google_apis_playstore;x86_64"
-    sdkmanager --update
-    sdkmanager --licenses
+
+    # android-commandlinetools default sdk_root location is elsewhere, as
+    # documented by https://formulae.brew.sh/cask/android-commandlinetools
+    sdkmanager --sdk_root=$SDK_ROOT "system-images;android-30;google_apis_playstore;x86_64"
+    sdkmanager --sdk_root=$SDK_ROOT --update
+    sdkmanager --sdk_root=$SDK_ROOT --licenses
 )
 
 # For now, we won't run this step automatically