From 17dd64d89d5633095292d2655779defe30121953 Mon Sep 17 00:00:00 2001
From: Anmol Sethi <anmol@terrastruct.com>
Date: Sun, 20 Nov 2022 05:19:39 -0800
Subject: [PATCH 1/3] install.sh: Add brew integration and documentation

Updates #80
---
 README.md                          |   5 +-
 ci/release/_install.sh             | 247 ++++++++++++++++++---------
 ci/release/template/scripts/lib.sh |  13 +-
 ci/sub                             |   2 +-
 docs/INSTALL.md                    |  83 +++++++++
 install.sh                         | 260 +++++++++++++++++++----------
 lib/version/version.go             |   2 +-
 7 files changed, 441 insertions(+), 171 deletions(-)
 create mode 100644 docs/INSTALL.md

diff --git a/README.md b/README.md
index df9cd9564..7f31f52f5 100644
--- a/README.md
+++ b/README.md
@@ -58,6 +58,9 @@ A browser window will open with `out.svg` and live-reload on changes to `in.d2`.
 
 ## Install
 
+For more detailed installation docs with examples for if you do not wish to use the
+install script see [./doc/INSTALL.md](./doc/INSTALL.md).
+
 ### Install script
 
 The recommended way to install is to run our install script, which will figure out the
@@ -92,7 +95,7 @@ curl -fsSL https://d2lang.com/install.sh | sh -s -- --uninstall
 Alternatively, you can install from source:
 
 ```sh
-go install oss.terrastruct.com/d2
+go install oss.terrastruct.com/d2/cmd/d2@latest
 ```
 
 ## D2 as a library
diff --git a/ci/release/_install.sh b/ci/release/_install.sh
index 833f965f8..f1432a555 100755
--- a/ci/release/_install.sh
+++ b/ci/release/_install.sh
@@ -18,8 +18,11 @@ usage: $arg0 [--dry-run] [--version vX.X.X] [--edge] [--method detect] [--prefix
   [--tala latest] [--force] [--uninstall]
 
 install.sh automates the installation of D2 onto your system. It currently only supports
-the installation of standalone releases from GitHub. If you pass --edge, it will clone the
-source, build a release and install from it.
+the installation of standalone releases from GitHub and via Homebrew on macOS. See the
+docs for --detect below for more information
+
+If you pass --edge, it will clone the source, build a release and install from it.
+--edge is incompatible with --tala and currently unimplemented.
 
 Flags:
 
@@ -29,6 +32,8 @@ Flags:
 
 --version vX.X.X
   Pass to have install.sh install the given version instead of the latest version.
+  warn: The version may not be obeyed with package manager installations. Use
+        --method=standalone to enforce the version.
 
 --edge
   Pass to build and install D2 from source. This will still use --method if set to detect
@@ -36,14 +41,15 @@ Flags:
   if an unsupported package manager is used. To install from source like a dev would,
   use go install oss.terrastruct.com/d2
   note: currently unimplemented.
+  warn: incompatible with --tala as TALA is closed source.
 
---method [detect | standalone]
+--method [detect | standalone | homebrew ]
   Pass to control the method by which to install. Right now we only support standalone
   releases from GitHub but later we'll add support for brew, rpm, deb and more.
-  note: currently unimplemented.
 
-  - detect is currently unimplemented but would use your OS's package manager
-    automatically.
+  - detect will use your OS's package manager automatically.
+    So far it only detects macOS and automatically uses homebrew.
+  - homebrew uses https://brew.sh/ which is a macOS and Linux package manager.
   - standalone installs a standalone release archive into the unix hierarchy path
      specified by --prefix which defaults to /usr/local
      Ensure /usr/local/bin is in your \$PATH to use it.
@@ -51,16 +57,19 @@ Flags:
 --prefix /usr/local
   Controls the unix hierarchy path into which standalone releases are installed.
   Defaults to /usr/local. You may also want to use ~/.local to avoid needing sudo.
-  Remember that whatever you use, you must have the bin directory of your prefix
-  path in \$PATH to execute the d2 binary. For example, if my prefix directory is
+  We use ~/.local by default on arm64 macOS machines as SIP now disables access to
+  /usr/local. Remember that whatever you use, you must have the bin directory of your
+  prefix path in \$PATH to execute the d2 binary. For example, if my prefix directory is
   /usr/local then my \$PATH must contain /usr/local/bin.
 
 --tala [latest]
   Install Terrastruct's closed source TALA for improved layouts.
-  See https://github.com/terrastruct/TALA
+  See https://github.com/terrastruct/tala
   It optionally takes an argument of the TALA version to install.
   Installation obeys all other flags, just like the installation of d2. For example,
   the d2plugin-tala binary will be installed into /usr/local/bin/d2plugin-tala
+  warn: The version may not be obeyed with package manager installations. Use
+        --method=standalone to enforce the version.
 
 --force:
   Force installation over the existing version even if they match. It will attempt a
@@ -85,7 +94,6 @@ EOF
 }
 
 main() {
-  METHOD=standalone
   while flag_parse "$@"; do
     case "$FLAG" in
       h|help)
@@ -113,8 +121,6 @@ main() {
       method)
         flag_nonemptyarg && shift "$FLAGSHIFT"
         METHOD=$FLAGARG
-        echoerr "$FLAGRAW is currently unimplemented"
-        return 1
         ;;
       prefix)
         flag_nonemptyarg && shift "$FLAGSHIFT"
@@ -149,49 +155,75 @@ main() {
   PREFIX=${PREFIX:-/usr/local}
   CACHE_DIR=$(cache_dir)
   mkdir -p "$CACHE_DIR"
+  METHOD=${METHOD:-detect}
   INSTALL_DIR=$PREFIX/lib/d2
 
+  case $METHOD in
+    detect)
+      case "$OS" in
+        macos)
+          log "detected macOS, using homebrew for (un)installation"
+          METHOD=homebrew
+          ;;
+        *)
+          warn "unrecognized OS $OS, falling back to --method=standalone"
+          METHOD=standalone
+          ;;
+      esac
+      ;;
+    standalone) ;;
+    homebrew) ;;
+    *)
+      echoerr "unknown (un)installation method $METHOD"
+      return 1
+      ;;
+  esac
+
   if [ -n "${UNINSTALL-}" ]; then
     uninstall
-    return 0
+  else
+    install
   fi
-
-  VERSION=${VERSION:-latest}
-  if [ "$VERSION" = latest ]; then
-    header "fetching latest release info"
-    fetch_release_info
-  fi
-
-  install
 }
 
 install() {
-  install_d2
-  if [ -n "${TALA-}" ]; then
-    # Run in subshell to avoid overwriting VERSION.
-    TALA_VERSION="$( install_tala && echo "$VERSION" )"
-  fi
+  case $METHOD in
+    standalone)
+      install_d2_standalone
+      if [ -n "${TALA-}" ]; then
+        # Run in subshell to avoid overwriting VERSION.
+        TALA_VERSION="$( RELEASE_INFO= install_tala_standalone && echo "$VERSION" )"
+      fi
+      ;;
+    homebrew)
+      install_d2_brew
+      if [ -n "${TALA-}" ]; then install_tala_brew; fi
+      ;;
+  esac
 
-  FGCOLOR=2 header success
+  FGCOLOR=2 bigheader 'next steps'
+  case $METHOD in
+    standalone) install_post_standalone ;;
+    homebrew) install_post_brew ;;
+  esac
+}
+
+install_post_standalone() {
   log "d2-$VERSION-$OS-$ARCH has been successfully installed into $PREFIX"
   if [ -n "${TALA-}" ]; then
     log "tala-$TALA_VERSION-$OS-$ARCH has been successfully installed into $PREFIX"
   fi
-  log "Rerun this install script with --uninstall to uninstall"
+  log "Rerun this install script with --uninstall to uninstall."
+  log
   if ! echo "$PATH" | grep -qF "$PREFIX/bin"; then
     logcat >&2 <<EOF
-
-%%%%%%%%%%%%%%%%%%%%%%%%%
-NEXT STEPS
-%%%%%%%%%%%%%%%%%%%%%%%%%
-
 Extend your \$PATH to use d2:
   export PATH=$PREFIX/bin:\$PATH
 Then run:
   ${TALA+D2_LAYOUT=tala }d2 --help
 EOF
   else
-    log "  Run ${TALA+D2_LAYOUT=tala }d2 --help for usage."
+    log "Run ${TALA+D2_LAYOUT=tala }d2 --help for usage."
   fi
   if ! manpath | grep -qF "$PREFIX/share/man"; then
     logcat >&2 <<EOF
@@ -204,36 +236,61 @@ EOF
     log "  man d2plugin-tala"
   fi
   else
-    log "  Run man d2 for detailed docs."
+    log "Run man d2 for detailed docs."
     if [ -n "${TALA-}" ]; then
-      log "  Run man d2plugin-tala for detailed docs."
+      log "Run man d2plugin-tala for detailed TALA docs."
     fi
   fi
   logcat >&2 <<EOF
 
 Something not working? Please let us know:
-https://github.com/terrastruct/d2/issues/new
+https://github.com/terrastruct/d2/issues
+https://github.com/terrastruct/d2/discussions
+https://discord.gg/NF6X8K4eDq
 EOF
 }
 
-install_d2() {
+install_post_brew() {
+  log "d2 has been successfully installed with homebrew."
+  if [ -n "${TALA-}" ]; then
+    log "tala has been successfully installed with homebrew."
+  fi
+  log "Rerun this install script with --uninstall to uninstall."
+  log
+  log "Run ${TALA+D2_LAYOUT=tala }d2 --help for usage."
+  log "Run man d2 for detailed docs."
+  if [ -n "${TALA-}" ]; then
+    log "Run man d2plugin-tala for detailed TALA docs."
+  fi
+  logcat >&2 <<EOF
+
+Something not working? Please let us know:
+https://github.com/terrastruct/d2/issues
+https://github.com/terrastruct/d2/discussions
+https://discord.gg/NF6X8K4eDq
+EOF
+}
+
+install_d2_standalone() {
+  VERSION=${VERSION:-latest}
+  header "installing d2-$VERSION"
+
+  if [ "$VERSION" = latest ]; then
+    fetch_release_info
+  fi
+
   if command -v d2 >/dev/null; then
     INSTALLED_VERSION="$(d2 version)"
     if [ ! "${FORCE-}" -a "$VERSION" = "$INSTALLED_VERSION" ]; then
-      log "skipping installation as version $VERSION is already installed."
+      log "skipping installation as d2 $VERSION is already installed."
       return 0
     fi
-    log "uninstalling $INSTALLED_VERSION to install $VERSION"
-    if ! uninstall_d2; then
-      warn "failed to uninstall $INSTALLED_VERSION"
+    log "uninstalling d2 $INSTALLED_VERSION to install $VERSION"
+    if ! uninstall_d2_standalone; then
+      warn "failed to uninstall d2 $INSTALLED_VERSION"
     fi
   fi
 
-  header "installing d2-$VERSION"
-  install_standalone_d2
-}
-
-install_standalone_d2() {
   ARCHIVE="d2-$VERSION-$OS-$ARCH.tar.gz"
   log "installing standalone release $ARCHIVE from github"
 
@@ -252,19 +309,39 @@ install_standalone_d2() {
   "$sh_c" sh -c "'cd \"$INSTALL_DIR/d2-$VERSION\" && make install PREFIX=\"$PREFIX\"'"
 }
 
-install_tala() {
-  REPO="${REPO_TALA:-terrastruct/TALA}"
-  VERSION=$TALA
-  RELEASE_INFO=
-  fetch_release_info
-  header "installing tala-$VERSION"
-  install_standalone_tala
+install_d2_brew() {
+  header "installing d2 with homebrew"
+  sh_c brew tap terrastruct/d2
+  sh_c brew install d2
+  sh_c brew test d2
 }
 
-install_standalone_tala() {
+install_tala_standalone() {
+  REPO="${REPO_TALA:-terrastruct/tala}"
+  VERSION=$TALA
+
+  header "installing tala-$VERSION"
+
+  if [ "$VERSION" = latest ]; then
+    fetch_release_info
+  fi
+
+  if command -v d2plugin-tala >/dev/null; then
+    INSTALLED_VERSION="$(d2plugin-tala --version)"
+    if [ ! "${FORCE-}" -a "$VERSION" = "$INSTALLED_VERSION" ]; then
+      log "skipping installation as tala $VERSION is already installed."
+      return 0
+    fi
+    log "uninstalling tala $INSTALLED_VERSION to install $VERSION"
+    if ! uninstall_tala_standalone; then
+      warn "failed to uninstall tala $INSTALLED_VERSION"
+    fi
+  fi
+
   ARCHIVE="tala-$VERSION-$OS-$ARCH.tar.gz"
   log "installing standalone release $ARCHIVE from github"
 
+  fetch_release_info
   asset_line=$(sh_c 'cat "$RELEASE_INFO" | grep -n "$ARCHIVE" | cut -d: -f1 | head -n1')
   asset_url=$(sh_c 'sed -n $((asset_line-3))p "$RELEASE_INFO" | sed "s/^.*: \"\(.*\)\",$/\1/g"')
 
@@ -280,36 +357,43 @@ install_standalone_tala() {
   "$sh_c" sh -c "'cd \"$INSTALL_DIR/tala-$VERSION\" && make install PREFIX=\"$PREFIX\"'"
 }
 
+install_tala_brew() {
+  header "installing tala with homebrew"
+  sh_c brew tap terrastruct/d2
+  sh_c brew install tala
+  sh_c brew test tala
+}
+
 uninstall() {
+  # We uninstall tala first as package managers require that it be uninstalled before
+  # uninstalling d2 as TALA depends on d2.
+  if [ "${TALA-}" ]; then
+    if command -v d2plugin-tala >/dev/null; then
+      INSTALLED_VERSION="$(d2plugin-tala --version)"
+      header "uninstalling tala-$INSTALLED_VERSION"
+      case $METHOD in
+        standalone) uninstall_tala_standalone ;;
+        homebrew) uninstall_tala_brew ;;
+      esac
+    else
+      warn "no version of tala installed"
+    fi
+  fi
+
   if ! command -v d2 >/dev/null; then
     warn "no version of d2 installed"
     return 0
   fi
+
   INSTALLED_VERSION="$(d2 --version)"
-  if ! uninstall_d2; then
-    echoerr "failed to uninstall $INSTALLED_VERSION"
-    return 1
-  fi
-  if [ "${TALA-}" ]; then
-    if ! command -v d2plugin-tala >/dev/null; then
-      warn "no version of tala installed"
-      return 0
-    fi
-    INSTALLED_VERSION="$(d2plugin-tala --version)"
-    if ! uninstall_tala; then
-      echoerr "failed to uninstall tala $INSTALLED_VERSION"
-      return 1
-    fi
-  fi
-  return 0
-}
-
-uninstall_d2() {
   header "uninstalling d2-$INSTALLED_VERSION"
-  uninstall_standalone_d2
+  case $METHOD in
+    standalone) uninstall_d2_standalone ;;
+    homebrew) uninstall_d2_brew ;;
+  esac
 }
 
-uninstall_standalone_d2() {
+uninstall_d2_standalone() {
   log "uninstalling standalone release of d2-$INSTALLED_VERSION"
 
   if [ ! -e "$INSTALL_DIR/d2-$INSTALLED_VERSION" ]; then
@@ -327,12 +411,11 @@ uninstall_standalone_d2() {
   "$sh_c" rm -rf "$INSTALL_DIR/d2-$INSTALLED_VERSION"
 }
 
-uninstall_tala() {
-  header "uninstalling tala-$INSTALLED_VERSION"
-  uninstall_standalone_tala
+uninstall_d2_brew() {
+  sh_c brew remove d2
 }
 
-uninstall_standalone_tala() {
+uninstall_tala_standalone() {
   log "uninstalling standalone release tala-$INSTALLED_VERSION"
 
   if [ ! -e "$INSTALL_DIR/tala-$INSTALLED_VERSION" ]; then
@@ -350,6 +433,10 @@ uninstall_standalone_tala() {
   "$sh_c" rm -rf "$INSTALL_DIR/tala-$INSTALLED_VERSION"
 }
 
+uninstall_tala_brew() {
+  sh_c brew remove tala
+}
+
 is_prefix_writable() {
   sh_c "mkdir -p '$INSTALL_DIR' 2>/dev/null" || true
   # The reason for checking whether $INSTALL_DIR is writable is that on macOS you have
diff --git a/ci/release/template/scripts/lib.sh b/ci/release/template/scripts/lib.sh
index 9b2b4b7d7..61f7c1138 100644
--- a/ci/release/template/scripts/lib.sh
+++ b/ci/release/template/scripts/lib.sh
@@ -111,12 +111,11 @@ printfp() {(
   if [ -z "${FGCOLOR-}" ]; then
     FGCOLOR="$(get_rand_color "$prefix")"
   fi
+  should_color || true
   if [ $# -eq 0 ]; then
-    should_color || true
-    printf '%s' $(COLOR=${_COLOR-} setaf "$FGCOLOR" "$prefix")
+    printf '%s' "$(COLOR=${_COLOR-} setaf "$FGCOLOR" "$prefix")"
   else
-    should_color || true
-    printf '%s: %s\n' $(COLOR=${_COLOR-} setaf "$FGCOLOR" "$prefix") "$(printf "$@")"
+    printf '%s: %s\n' "$(COLOR=${_COLOR-} setaf "$FGCOLOR" "$prefix")" "$(printf "$@")"
   fi
 )}
 
@@ -219,6 +218,12 @@ header() {
   logp "/* $1 */"
 }
 
+bigheader() {
+  logp "/**
+ * $1
+ **/"
+}
+
 # humanpath replaces all occurrences of " $HOME" with " ~"
 # and all occurrences of '$HOME' with the literal '$HOME'.
 humanpath() {
diff --git a/ci/sub b/ci/sub
index 8f9a24045..55e97e541 160000
--- a/ci/sub
+++ b/ci/sub
@@ -1 +1 @@
-Subproject commit 8f9a24045546e76e39175ed148fdadd770c750ba
+Subproject commit 55e97e5416c5a63737c44d9123441340bc4b210b
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
new file mode 100644
index 000000000..38fa92748
--- /dev/null
+++ b/docs/INSTALL.md
@@ -0,0 +1,83 @@
+# install
+
+This file documents how the install.sh script installs d2 and how you can
+manually install yourself.
+
+<!-- toc -->
+
+- [install.sh](#installsh)
+- [Standalone](#standalone)
+- [macOS (Homebrew)](#macos-homebrew)
+
+<!-- tocstop -->
+
+## install.sh
+
+```sh
+# With --dry-run the install script will print the commands it will use
+# to install without actually installing so you know what it's going to do.
+curl -fsSL https://d2lang.com/install.sh | sh -s -- --dry-run
+# If things look good, install for real.
+curl -fsSL https://d2lang.com/install.sh | sh -s --
+```
+
+For help on the terminal run including the supported package managers
+and detection methods see:
+
+```sh
+curl -fsSL https://d2lang.com/install.sh | sh -s -- --help
+```
+
+## Standalone
+
+We publish standalone release archives with every release on github.
+Download the `.tar.gz` release for your OS/ARCH combination and then run:
+
+```sh
+make install
+```
+
+Inside the extracted directory to install.
+
+```sh
+make uninstall
+```
+
+To uninstall. You will be prompted for sudo/su/doas if root permissions
+are required for installation. You can control the unix hierarchy installation
+path with `PREFIX=`. For example:
+
+```
+# Install under ~/.local.
+# Binaries will be at ~/.local/bin
+# And manpages will be under ~/.local/share/man
+# And supporting data like icons and fonts at ~/.local/share/d2
+make install PREFIX=$HOME/.local
+```
+
+The install script places the standalone release into `$PREFIX/lib/d2/d2-<version>`
+and we recommend doing the same with manually installed releases so that you
+know where the release directory is for easy uninstall.
+
+We have releases with identical process for tala at https://github.com/terrastruct/TALA/releases
+
+## macOS (Homebrew)
+
+For macOS you may install as so:
+
+```sh
+brew tap terrastruct/d2
+brew install d2
+brew test d2
+```
+
+For closed source TALA [https://github.com/terrastruct/tala]:
+
+```sh
+brew tap terrastruct/d2
+brew install tala
+brew test tala
+```
+
+You don't have to run the `brew test` command but we recommend it to ensure d2 is
+functioning correctly after installation.
diff --git a/install.sh b/install.sh
index ff0742739..78c315935 100755
--- a/install.sh
+++ b/install.sh
@@ -117,12 +117,11 @@ printfp() {(
   if [ -z "${FGCOLOR-}" ]; then
     FGCOLOR="$(get_rand_color "$prefix")"
   fi
+  should_color || true
   if [ $# -eq 0 ]; then
-    should_color || true
-    printf '%s' $(COLOR=${_COLOR-} setaf "$FGCOLOR" "$prefix")
+    printf '%s' "$(COLOR=${_COLOR-} setaf "$FGCOLOR" "$prefix")"
   else
-    should_color || true
-    printf '%s: %s\n' $(COLOR=${_COLOR-} setaf "$FGCOLOR" "$prefix") "$(printf "$@")"
+    printf '%s: %s\n' "$(COLOR=${_COLOR-} setaf "$FGCOLOR" "$prefix")" "$(printf "$@")"
   fi
 )}
 
@@ -225,6 +224,12 @@ header() {
   logp "/* $1 */"
 }
 
+bigheader() {
+  logp "/**
+ * $1
+ **/"
+}
+
 # humanpath replaces all occurrences of " $HOME" with " ~"
 # and all occurrences of '$HOME' with the literal '$HOME'.
 humanpath() {
@@ -477,8 +482,11 @@ usage: $arg0 [--dry-run] [--version vX.X.X] [--edge] [--method detect] [--prefix
   [--tala latest] [--force] [--uninstall]
 
 install.sh automates the installation of D2 onto your system. It currently only supports
-the installation of standalone releases from GitHub. If you pass --edge, it will clone the
-source, build a release and install from it.
+the installation of standalone releases from GitHub and via Homebrew on macOS. See the
+docs for --detect below for more information
+
+If you pass --edge, it will clone the source, build a release and install from it.
+--edge is incompatible with --tala and currently unimplemented.
 
 Flags:
 
@@ -488,6 +496,8 @@ Flags:
 
 --version vX.X.X
   Pass to have install.sh install the given version instead of the latest version.
+  warn: The version may not be obeyed with package manager installations. Use
+        --method=standalone to enforce the version.
 
 --edge
   Pass to build and install D2 from source. This will still use --method if set to detect
@@ -495,14 +505,15 @@ Flags:
   if an unsupported package manager is used. To install from source like a dev would,
   use go install oss.terrastruct.com/d2
   note: currently unimplemented.
+  warn: incompatible with --tala as TALA is closed source.
 
---method [detect | standalone]
+--method [detect | standalone | homebrew ]
   Pass to control the method by which to install. Right now we only support standalone
   releases from GitHub but later we'll add support for brew, rpm, deb and more.
-  note: currently unimplemented.
 
-  - detect is currently unimplemented but would use your OS's package manager
-    automatically.
+  - detect will use your OS's package manager automatically.
+    So far it only detects macOS and automatically uses homebrew.
+  - homebrew uses https://brew.sh/ which is a macOS and Linux package manager.
   - standalone installs a standalone release archive into the unix hierarchy path
      specified by --prefix which defaults to /usr/local
      Ensure /usr/local/bin is in your \$PATH to use it.
@@ -510,16 +521,19 @@ Flags:
 --prefix /usr/local
   Controls the unix hierarchy path into which standalone releases are installed.
   Defaults to /usr/local. You may also want to use ~/.local to avoid needing sudo.
-  Remember that whatever you use, you must have the bin directory of your prefix
-  path in \$PATH to execute the d2 binary. For example, if my prefix directory is
+  We use ~/.local by default on arm64 macOS machines as SIP now disables access to
+  /usr/local. Remember that whatever you use, you must have the bin directory of your
+  prefix path in \$PATH to execute the d2 binary. For example, if my prefix directory is
   /usr/local then my \$PATH must contain /usr/local/bin.
 
 --tala [latest]
   Install Terrastruct's closed source TALA for improved layouts.
-  See https://github.com/terrastruct/TALA
+  See https://github.com/terrastruct/tala
   It optionally takes an argument of the TALA version to install.
   Installation obeys all other flags, just like the installation of d2. For example,
   the d2plugin-tala binary will be installed into /usr/local/bin/d2plugin-tala
+  warn: The version may not be obeyed with package manager installations. Use
+        --method=standalone to enforce the version.
 
 --force:
   Force installation over the existing version even if they match. It will attempt a
@@ -544,7 +558,6 @@ EOF
 }
 
 main() {
-  METHOD=standalone
   while flag_parse "$@"; do
     case "$FLAG" in
       h|help)
@@ -572,8 +585,6 @@ main() {
       method)
         flag_nonemptyarg && shift "$FLAGSHIFT"
         METHOD=$FLAGARG
-        echoerr "$FLAGRAW is currently unimplemented"
-        return 1
         ;;
       prefix)
         flag_nonemptyarg && shift "$FLAGSHIFT"
@@ -608,49 +619,75 @@ main() {
   PREFIX=${PREFIX:-/usr/local}
   CACHE_DIR=$(cache_dir)
   mkdir -p "$CACHE_DIR"
+  METHOD=${METHOD:-detect}
   INSTALL_DIR=$PREFIX/lib/d2
 
+  case $METHOD in
+    detect)
+      case "$OS" in
+        macos)
+          log "detected macOS, using homebrew for (un)installation"
+          METHOD=homebrew
+          ;;
+        *)
+          warn "unrecognized OS $OS, falling back to --method=standalone"
+          METHOD=standalone
+          ;;
+      esac
+      ;;
+    standalone) ;;
+    homebrew) ;;
+    *)
+      echoerr "unknown (un)installation method $METHOD"
+      return 1
+      ;;
+  esac
+
   if [ -n "${UNINSTALL-}" ]; then
     uninstall
-    return 0
+  else
+    install
   fi
-
-  VERSION=${VERSION:-latest}
-  if [ "$VERSION" = latest ]; then
-    header "fetching latest release info"
-    fetch_release_info
-  fi
-
-  install
 }
 
 install() {
-  install_d2
-  if [ -n "${TALA-}" ]; then
-    # Run in subshell to avoid overwriting VERSION.
-    TALA_VERSION="$( install_tala && echo "$VERSION" )"
-  fi
+  case $METHOD in
+    standalone)
+      install_d2_standalone
+      if [ -n "${TALA-}" ]; then
+        # Run in subshell to avoid overwriting VERSION.
+        TALA_VERSION="$( RELEASE_INFO= install_tala_standalone && echo "$VERSION" )"
+      fi
+      ;;
+    homebrew)
+      install_d2_brew
+      if [ -n "${TALA-}" ]; then install_tala_brew; fi
+      ;;
+  esac
 
-  FGCOLOR=2 header success
+  FGCOLOR=2 bigheader 'next steps'
+  case $METHOD in
+    standalone) install_post_standalone ;;
+    homebrew) install_post_brew ;;
+  esac
+}
+
+install_post_standalone() {
   log "d2-$VERSION-$OS-$ARCH has been successfully installed into $PREFIX"
   if [ -n "${TALA-}" ]; then
     log "tala-$TALA_VERSION-$OS-$ARCH has been successfully installed into $PREFIX"
   fi
-  log "Rerun this install script with --uninstall to uninstall"
+  log "Rerun this install script with --uninstall to uninstall."
+  log
   if ! echo "$PATH" | grep -qF "$PREFIX/bin"; then
     logcat >&2 <<EOF
-
-%%%%%%%%%%%%%%%%%%%%%%%%%
-NEXT STEPS
-%%%%%%%%%%%%%%%%%%%%%%%%%
-
 Extend your \$PATH to use d2:
   export PATH=$PREFIX/bin:\$PATH
 Then run:
   ${TALA+D2_LAYOUT=tala }d2 --help
 EOF
   else
-    log "  Run ${TALA+D2_LAYOUT=tala }d2 --help for usage."
+    log "Run ${TALA+D2_LAYOUT=tala }d2 --help for usage."
   fi
   if ! manpath | grep -qF "$PREFIX/share/man"; then
     logcat >&2 <<EOF
@@ -663,36 +700,61 @@ EOF
     log "  man d2plugin-tala"
   fi
   else
-    log "  Run man d2 for detailed docs."
+    log "Run man d2 for detailed docs."
     if [ -n "${TALA-}" ]; then
-      log "  Run man d2plugin-tala for detailed docs."
+      log "Run man d2plugin-tala for detailed TALA docs."
     fi
   fi
   logcat >&2 <<EOF
 
 Something not working? Please let us know:
-https://github.com/terrastruct/d2/issues/new
+https://github.com/terrastruct/d2/issues
+https://github.com/terrastruct/d2/discussions
+https://discord.gg/NF6X8K4eDq
 EOF
 }
 
-install_d2() {
+install_post_brew() {
+  log "d2 has been successfully installed with homebrew."
+  if [ -n "${TALA-}" ]; then
+    log "tala has been successfully installed with homebrew."
+  fi
+  log "Rerun this install script with --uninstall to uninstall."
+  log
+  log "Run ${TALA+D2_LAYOUT=tala }d2 --help for usage."
+  log "Run man d2 for detailed docs."
+  if [ -n "${TALA-}" ]; then
+    log "Run man d2plugin-tala for detailed TALA docs."
+  fi
+  logcat >&2 <<EOF
+
+Something not working? Please let us know:
+https://github.com/terrastruct/d2/issues
+https://github.com/terrastruct/d2/discussions
+https://discord.gg/NF6X8K4eDq
+EOF
+}
+
+install_d2_standalone() {
+  VERSION=${VERSION:-latest}
+  header "installing d2-$VERSION"
+
+  if [ "$VERSION" = latest ]; then
+    fetch_release_info
+  fi
+
   if command -v d2 >/dev/null; then
     INSTALLED_VERSION="$(d2 version)"
     if [ ! "${FORCE-}" -a "$VERSION" = "$INSTALLED_VERSION" ]; then
-      log "skipping installation as version $VERSION is already installed."
+      log "skipping installation as d2 $VERSION is already installed."
       return 0
     fi
-    log "uninstalling $INSTALLED_VERSION to install $VERSION"
-    if ! uninstall_d2; then
-      warn "failed to uninstall $INSTALLED_VERSION"
+    log "uninstalling d2 $INSTALLED_VERSION to install $VERSION"
+    if ! uninstall_d2_standalone; then
+      warn "failed to uninstall d2 $INSTALLED_VERSION"
     fi
   fi
 
-  header "installing d2-$VERSION"
-  install_standalone_d2
-}
-
-install_standalone_d2() {
   ARCHIVE="d2-$VERSION-$OS-$ARCH.tar.gz"
   log "installing standalone release $ARCHIVE from github"
 
@@ -711,19 +773,39 @@ install_standalone_d2() {
   "$sh_c" sh -c "'cd \"$INSTALL_DIR/d2-$VERSION\" && make install PREFIX=\"$PREFIX\"'"
 }
 
-install_tala() {
-  REPO="${REPO_TALA:-terrastruct/TALA}"
-  VERSION=$TALA
-  RELEASE_INFO=
-  fetch_release_info
-  header "installing tala-$VERSION"
-  install_standalone_tala
+install_d2_brew() {
+  header "installing d2 with homebrew"
+  sh_c brew tap terrastruct/d2
+  sh_c brew install d2
+  sh_c brew test d2
 }
 
-install_standalone_tala() {
+install_tala_standalone() {
+  REPO="${REPO_TALA:-terrastruct/tala}"
+  VERSION=$TALA
+
+  header "installing tala-$VERSION"
+
+  if [ "$VERSION" = latest ]; then
+    fetch_release_info
+  fi
+
+  if command -v d2plugin-tala >/dev/null; then
+    INSTALLED_VERSION="$(d2plugin-tala --version)"
+    if [ ! "${FORCE-}" -a "$VERSION" = "$INSTALLED_VERSION" ]; then
+      log "skipping installation as tala $VERSION is already installed."
+      return 0
+    fi
+    log "uninstalling tala $INSTALLED_VERSION to install $VERSION"
+    if ! uninstall_tala_standalone; then
+      warn "failed to uninstall tala $INSTALLED_VERSION"
+    fi
+  fi
+
   ARCHIVE="tala-$VERSION-$OS-$ARCH.tar.gz"
   log "installing standalone release $ARCHIVE from github"
 
+  fetch_release_info
   asset_line=$(sh_c 'cat "$RELEASE_INFO" | grep -n "$ARCHIVE" | cut -d: -f1 | head -n1')
   asset_url=$(sh_c 'sed -n $((asset_line-3))p "$RELEASE_INFO" | sed "s/^.*: \"\(.*\)\",$/\1/g"')
 
@@ -739,36 +821,43 @@ install_standalone_tala() {
   "$sh_c" sh -c "'cd \"$INSTALL_DIR/tala-$VERSION\" && make install PREFIX=\"$PREFIX\"'"
 }
 
+install_tala_brew() {
+  header "installing tala with homebrew"
+  sh_c brew tap terrastruct/d2
+  sh_c brew install tala
+  sh_c brew test tala
+}
+
 uninstall() {
+  # We uninstall tala first as package managers require that it be uninstalled before
+  # uninstalling d2 as TALA depends on d2.
+  if [ "${TALA-}" ]; then
+    if command -v d2plugin-tala >/dev/null; then
+      INSTALLED_VERSION="$(d2plugin-tala --version)"
+      header "uninstalling tala-$INSTALLED_VERSION"
+      case $METHOD in
+        standalone) uninstall_tala_standalone ;;
+        homebrew) uninstall_tala_brew ;;
+      esac
+    else
+      warn "no version of tala installed"
+    fi
+  fi
+
   if ! command -v d2 >/dev/null; then
     warn "no version of d2 installed"
     return 0
   fi
+
   INSTALLED_VERSION="$(d2 --version)"
-  if ! uninstall_d2; then
-    echoerr "failed to uninstall $INSTALLED_VERSION"
-    return 1
-  fi
-  if [ "${TALA-}" ]; then
-    if ! command -v d2plugin-tala >/dev/null; then
-      warn "no version of tala installed"
-      return 0
-    fi
-    INSTALLED_VERSION="$(d2plugin-tala --version)"
-    if ! uninstall_tala; then
-      echoerr "failed to uninstall tala $INSTALLED_VERSION"
-      return 1
-    fi
-  fi
-  return 0
-}
-
-uninstall_d2() {
   header "uninstalling d2-$INSTALLED_VERSION"
-  uninstall_standalone_d2
+  case $METHOD in
+    standalone) uninstall_d2_standalone ;;
+    homebrew) uninstall_d2_brew ;;
+  esac
 }
 
-uninstall_standalone_d2() {
+uninstall_d2_standalone() {
   log "uninstalling standalone release of d2-$INSTALLED_VERSION"
 
   if [ ! -e "$INSTALL_DIR/d2-$INSTALLED_VERSION" ]; then
@@ -786,12 +875,11 @@ uninstall_standalone_d2() {
   "$sh_c" rm -rf "$INSTALL_DIR/d2-$INSTALLED_VERSION"
 }
 
-uninstall_tala() {
-  header "uninstalling tala-$INSTALLED_VERSION"
-  uninstall_standalone_tala
+uninstall_d2_brew() {
+  sh_c brew remove d2
 }
 
-uninstall_standalone_tala() {
+uninstall_tala_standalone() {
   log "uninstalling standalone release tala-$INSTALLED_VERSION"
 
   if [ ! -e "$INSTALL_DIR/tala-$INSTALLED_VERSION" ]; then
@@ -809,6 +897,10 @@ uninstall_standalone_tala() {
   "$sh_c" rm -rf "$INSTALL_DIR/tala-$INSTALLED_VERSION"
 }
 
+uninstall_tala_brew() {
+  sh_c brew remove tala
+}
+
 is_prefix_writable() {
   sh_c "mkdir -p '$INSTALL_DIR' 2>/dev/null" || true
   # The reason for checking whether $INSTALL_DIR is writable is that on macOS you have
diff --git a/lib/version/version.go b/lib/version/version.go
index 34ab1a5bf..2f1ff62e5 100644
--- a/lib/version/version.go
+++ b/lib/version/version.go
@@ -1,4 +1,4 @@
 package version
 
 // Pre-built binaries will have version set during build time.
-var Version = "master (built from source)"
+var Version = "????"

From cd193e52c71f21bcb14df747b6480e5d26c97ec2 Mon Sep 17 00:00:00 2001
From: Anmol Sethi <anmol@terrastruct.com>
Date: Sun, 20 Nov 2022 19:45:18 -0800
Subject: [PATCH 2/3] ci/sub: Update

---
 ci/sub | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ci/sub b/ci/sub
index 55e97e541..f1f144c73 160000
--- a/ci/sub
+++ b/ci/sub
@@ -1 +1 @@
-Subproject commit 55e97e5416c5a63737c44d9123441340bc4b210b
+Subproject commit f1f144c738f3015f3cafc7d566666f83a0916320

From 7ecdc828248020ec59f2763401d8931f3b78bbc0 Mon Sep 17 00:00:00 2001
From: Anmol Sethi <anmol@terrastruct.com>
Date: Sun, 20 Nov 2022 20:16:29 -0800
Subject: [PATCH 3/3] install.sh: Improve brew integration and documentation

---
 ci/release/_install.sh | 22 ++++++++++++++++++----
 docs/CONTRIBUTING.md   |  3 +--
 docs/INSTALL.md        | 17 +----------------
 install.sh             | 22 ++++++++++++++++++----
 4 files changed, 38 insertions(+), 26 deletions(-)

diff --git a/ci/release/_install.sh b/ci/release/_install.sh
index f1432a555..524d317be 100755
--- a/ci/release/_install.sh
+++ b/ci/release/_install.sh
@@ -162,8 +162,13 @@ main() {
     detect)
       case "$OS" in
         macos)
-          log "detected macOS, using homebrew for (un)installation"
-          METHOD=homebrew
+          if command -v brew >/dev/null; then
+            log "detected macOS with homebrew, using homebrew for (un)installation"
+            METHOD=homebrew
+          else
+            warn "detected macOS without homebrew, falling back to --method=standalone"
+            METHOD=standalone
+          fi
           ;;
         *)
           warn "unrecognized OS $OS, falling back to --method=standalone"
@@ -181,8 +186,14 @@ main() {
 
   if [ -n "${UNINSTALL-}" ]; then
     uninstall
+    if [ -n "${DRY_RUN-}" ]; then
+      log "Rerun without --dry-run to execute printed commands and perform uninstall."
+    fi
   else
     install
+    if [ -n "${DRY_RUN-}" ]; then
+      log "Rerun without --dry-run to execute printed commands and perform install."
+    fi
   fi
 }
 
@@ -313,7 +324,6 @@ install_d2_brew() {
   header "installing d2 with homebrew"
   sh_c brew tap terrastruct/d2
   sh_c brew install d2
-  sh_c brew test d2
 }
 
 install_tala_standalone() {
@@ -361,7 +371,6 @@ install_tala_brew() {
   header "installing tala with homebrew"
   sh_c brew tap terrastruct/d2
   sh_c brew install tala
-  sh_c brew test tala
 }
 
 uninstall() {
@@ -492,4 +501,9 @@ fetch_gh() {
   sh_c mv "$file.inprogress" "$file"
 }
 
+brew() {
+  # Makes brew sane.
+  HOMEBREW_NO_INSTALL_CLEANUP=1 HOMEBREW_NO_AUTO_UPDATE=1 command brew "$@"
+}
+
 main "$@"
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 41c82f89a..bd8851e7b 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -65,8 +65,7 @@ language. Sometimes it gives controversial sentences -- don't use those.
 Script to generate one line of random text:
 ```
 ipsum1() {
-  fortune | head -n1 | sed 's/^ *//;s/ *$//' | tr -d '\n' | pbcopy
-  echo "$(pbpaste -Prefer txt)"
+  fortune | head -n1 | sed 's/^ *//;s/ *$//' | tr -d '\n' | tee /dev/stderr | pbcopy
 }
 ```
 
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 38fa92748..57828c04e 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -1,7 +1,6 @@
 # install
 
-This file documents how the install.sh script installs d2 and how you can
-manually install yourself.
+This file documents all the ways by which you can install d2.
 
 <!-- toc -->
 
@@ -59,8 +58,6 @@ The install script places the standalone release into `$PREFIX/lib/d2/d2-<versio
 and we recommend doing the same with manually installed releases so that you
 know where the release directory is for easy uninstall.
 
-We have releases with identical process for tala at https://github.com/terrastruct/TALA/releases
-
 ## macOS (Homebrew)
 
 For macOS you may install as so:
@@ -68,16 +65,4 @@ For macOS you may install as so:
 ```sh
 brew tap terrastruct/d2
 brew install d2
-brew test d2
 ```
-
-For closed source TALA [https://github.com/terrastruct/tala]:
-
-```sh
-brew tap terrastruct/d2
-brew install tala
-brew test tala
-```
-
-You don't have to run the `brew test` command but we recommend it to ensure d2 is
-functioning correctly after installation.
diff --git a/install.sh b/install.sh
index 78c315935..bce7507b5 100755
--- a/install.sh
+++ b/install.sh
@@ -626,8 +626,13 @@ main() {
     detect)
       case "$OS" in
         macos)
-          log "detected macOS, using homebrew for (un)installation"
-          METHOD=homebrew
+          if command -v brew >/dev/null; then
+            log "detected macOS with homebrew, using homebrew for (un)installation"
+            METHOD=homebrew
+          else
+            warn "detected macOS without homebrew, falling back to --method=standalone"
+            METHOD=standalone
+          fi
           ;;
         *)
           warn "unrecognized OS $OS, falling back to --method=standalone"
@@ -645,8 +650,14 @@ main() {
 
   if [ -n "${UNINSTALL-}" ]; then
     uninstall
+    if [ -n "${DRY_RUN-}" ]; then
+      log "Rerun without --dry-run to execute printed commands and perform uninstall."
+    fi
   else
     install
+    if [ -n "${DRY_RUN-}" ]; then
+      log "Rerun without --dry-run to execute printed commands and perform install."
+    fi
   fi
 }
 
@@ -777,7 +788,6 @@ install_d2_brew() {
   header "installing d2 with homebrew"
   sh_c brew tap terrastruct/d2
   sh_c brew install d2
-  sh_c brew test d2
 }
 
 install_tala_standalone() {
@@ -825,7 +835,6 @@ install_tala_brew() {
   header "installing tala with homebrew"
   sh_c brew tap terrastruct/d2
   sh_c brew install tala
-  sh_c brew test tala
 }
 
 uninstall() {
@@ -956,4 +965,9 @@ fetch_gh() {
   sh_c mv "$file.inprogress" "$file"
 }
 
+brew() {
+  # Makes brew sane.
+  HOMEBREW_NO_INSTALL_CLEANUP=1 HOMEBREW_NO_AUTO_UPDATE=1 command brew "$@"
+}
+
 main "$@"