From 30a04f9b8b2649bc06e4c2d957060bfbf614836b Mon Sep 17 00:00:00 2001
From: micolous <micolous+gh@gmail.com>
Date: Thu, 3 Oct 2024 13:28:31 +1000
Subject: [PATCH] Add instructions for unlinking Homebrew Rust on macOS (#3085)

---
 book/src/installing_client_tools.md | 27 +++++++++++++++++++++++----
 1 file changed, 23 insertions(+), 4 deletions(-)

diff --git a/book/src/installing_client_tools.md b/book/src/installing_client_tools.md
index ae0552c0c..f92f97c6b 100644
--- a/book/src/installing_client_tools.md
+++ b/book/src/installing_client_tools.md
@@ -12,7 +12,7 @@ Kanidm currently is packaged for the following systems:
 
 - OpenSUSE Tumbleweed
 - OpenSUSE Leap 15.4/15.5/15.6
-- MacOS
+- macOS
 - Arch Linux
 - CentOS Stream 9
 - Debian
@@ -47,16 +47,35 @@ zypper ref
 zypper in kanidm-clients
 ```
 
-### MacOS - Brew
+### macOS - Homebrew
 
-[Homebrew](https://brew.sh/) allows addition of third party repositories for installing tools. On
-MacOS you can use this to install the Kanidm tools.
+[Kanidm provides a Homebrew cask](https://github.com/kanidm/homebrew-kanidm),
+which lets [Homebrew](https://brew.sh/) build and install the CLI client tools
+from source:
 
 ```bash
 brew tap kanidm/kanidm
 brew install kanidm
 ```
 
+> [!TIP]
+>
+> **Rust developers:** this formula will install a Rust toolchain with Homebrew,
+> and add it to your `PATH`. *This may interfere with any Rust toolchain
+> you've installed with [`rustup`](https://rustup.rs/).*
+>
+> You can unlink Homebrew's Rust toolchain (removing it from your `PATH`) with:
+>
+> ```sh
+> brew unlink rust
+> ```
+>
+> Homebrew will always use its version of Rust when building Rust packages, even
+> when it is unlinked.
+>
+> Alternatively, you may wish to [install the Kanidm CLI with `cargo`](#cargo)
+> instead – this will use whatever Rust toochain you've already installed.
+
 ### Arch Linux
 
 [Kanidm on AUR](https://aur.archlinux.org/packages?O=0&K=kanidm)