From 1ad0f550b10d4adfc2d3a22828fd264b1c5f15e1 Mon Sep 17 00:00:00 2001 From: Colin Dean Date: Thu, 13 Feb 2025 19:50:10 +0000 Subject: [PATCH 1/5] Adds post-installation steps to installation with extend version in tips Inspired by @jvns' [post][1], I realized that I've had this problem on multiple teams, where someone missed the step at the end and didn't know how to recover. Typically, I've provided a version like what I've added to the Tips 'n' Tricks page so that I didn't have to think about what OS-arch pair my users are using. I've tested the loader added to tips and tricks with both bash and zsh and it passes both shellcheck and shfmt in posix mode. [1]: https://mastodon.social/@b0rk@jvns.ca/113997565198024027 --- docs/Installation.md | 22 ++++++++++++++++++++++ docs/Tips-N'-Tricks.md | 39 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) diff --git a/docs/Installation.md b/docs/Installation.md index 959585a1189e8..eeeb5817f567b 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -93,6 +93,28 @@ Make sure you avoid installing into: Create a Homebrew installation wherever you extract the tarball. Whichever `brew` command is called is where the packages will be installed. You can use this as you see fit, e.g. to have a system set of libs in the default prefix and tweaked formulae for development in `~/homebrew`. +## Post-installation steps + +Before completing installation, Homebrew installer will provide some required "Next steps" instructions. +These instructions configure your shell to evaluate the output of `brew shellenv`, +which will load `brew` into your shell environment for use. + +While it's difficult to document the precise path for every shell, +typically, what follows must be in your shell's `rc` or `profile` file: + +```sh +eval "${HOMEBREW_PREFIX}/bin/brew shellenv)" +``` + +where `${HOMEBREW_PREFIX}` is the Homebrew installation directory. +Replace this with the installation directory on your system. + +For more insight, re-run the installer or inspect [the installer's source](https://github.com/Homebrew/install/blob/deacfa6a6e62e5f4002baf9e1fac7a96e9aa5d41/install.sh#L1072-L1088) +to see how the installer constructs the path it recommends. + +See [Tips N' Tricks > Loading Homebrew from the same dotfiles on different operating systems](Tips-N'-Tricks.md#Loading-Homebrew-from-the-same-dotfiles-on-different-operating-systems) +for another way to handle this across multiple operating systems. + ## Uninstallation Uninstallation is documented in the [FAQ](FAQ.md#how-do-i-uninstall-homebrew). diff --git a/docs/Tips-N'-Tricks.md b/docs/Tips-N'-Tricks.md index 85dde92c8629d..9606d37b0e20a 100644 --- a/docs/Tips-N'-Tricks.md +++ b/docs/Tips-N'-Tricks.md @@ -140,3 +140,42 @@ export HOMEBREW_ARTIFACT_DOMAIN=https://artifacts.example.com/artifactory/homebr export HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK=1 export HOMEBREW_DOCKER_REGISTRY_BASIC_AUTH_TOKEN="$(printf 'anonymous:' | base64)" ``` + +## Loading Homebrew from the same dotfiles on different operating systems + +Some users may want to use the same shell initialization files on macOS and Linux. +Use this to detect the likely Homebrew installation directory and load Homebrew when it's found. +You may need to adapt this to your particular shell or other particulars of your environment. + +```sh +# Execute only if brew isn't already available. +if ! [ -x "$(command -v brew)" ]; then + OS="$(uname)" + UNAME_MACHINE="$(uname -m)" + if [ "${OS}" = "Linux" ]; then + # Linux + HOMEBREW_PREFIX="/home/linuxbrew/.linuxbrew" + elif [ "${OS}" = "Darwin" ]; then + if [ "${UNAME_MACHINE}" = "arm64" ]; then + # M-series ARM64 macOS + HOMEBREW_PREFIX="/opt/homebrew" + else + # Intel macOS + HOMEBREW_PREFIX="/usr/local" + fi + fi + + if [ -d "${HOMEBREW_PREFIX}" ]; then + BREW_BIN="${HOMEBREW_PREFIX}/bin/brew" + if [ -x "${BREW_BIN}" ]; then + eval "\$(${BREW_BIN} shellenv)" + else + >&2 printf "Homebrew possibly found at %s but %s is not executable. Check the permissions.\n" "${HOMEBREW_PREFIX}" "${BREW_BIN}" + fi + else + >&2 printf "Homebrew not found where expected in %s on %s %s\n" "${HOMEBREW_PREFIX}" "${OS}" "${UNAME_MACHINE}" + >&2 printf "Double-check that it's installed or run the following command to install it\n\n\t%s\n" \ + '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"' + fi +fi +``` From 33fde6faec1ba55a5fb08a7a54c1f24ff6ca60ac Mon Sep 17 00:00:00 2001 From: Colin Dean Date: Thu, 13 Feb 2025 15:12:03 -0500 Subject: [PATCH 2/5] Lowercases a link fragment to satisfy checks --- docs/Installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Installation.md b/docs/Installation.md index eeeb5817f567b..1a33e19a5458e 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -112,7 +112,7 @@ Replace this with the installation directory on your system. For more insight, re-run the installer or inspect [the installer's source](https://github.com/Homebrew/install/blob/deacfa6a6e62e5f4002baf9e1fac7a96e9aa5d41/install.sh#L1072-L1088) to see how the installer constructs the path it recommends. -See [Tips N' Tricks > Loading Homebrew from the same dotfiles on different operating systems](Tips-N'-Tricks.md#Loading-Homebrew-from-the-same-dotfiles-on-different-operating-systems) +See [Tips N' Tricks > Loading Homebrew from the same dotfiles on different operating systems](Tips-N'-Tricks.md#loading-homebrew-from-the-same-dotfiles-on-different-operating-systems) for another way to handle this across multiple operating systems. ## Uninstallation From 1733a78133b6d455738308db6455f66a5d37b984 Mon Sep 17 00:00:00 2001 From: Colin Dean Date: Fri, 14 Feb 2025 10:25:32 -0500 Subject: [PATCH 3/5] Prevent copying w/o reading by removing valid envvars and noting dirs Co-authored-by: Eric Knibbe --- docs/Installation.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/Installation.md b/docs/Installation.md index 1a33e19a5458e..56910eea632df 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -103,11 +103,12 @@ While it's difficult to document the precise path for every shell, typically, what follows must be in your shell's `rc` or `profile` file: ```sh -eval "${HOMEBREW_PREFIX}/bin/brew shellenv)" +eval "/bin/brew shellenv)" ``` where `${HOMEBREW_PREFIX}` is the Homebrew installation directory. Replace this with the installation directory on your system. +See the [FAQ about default installation locations](FAQ.md#why-should-i-install-homebrew-in-the-default-location). For more insight, re-run the installer or inspect [the installer's source](https://github.com/Homebrew/install/blob/deacfa6a6e62e5f4002baf9e1fac7a96e9aa5d41/install.sh#L1072-L1088) to see how the installer constructs the path it recommends. From eab6e9f7f3c37ec21401471e951bf1b9f299eee4 Mon Sep 17 00:00:00 2001 From: Colin Dean Date: Tue, 18 Feb 2025 12:08:21 -0500 Subject: [PATCH 4/5] Use suggested post-installation steps Thanks, @jvns! --- docs/Installation.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/Installation.md b/docs/Installation.md index 56910eea632df..cf90ebed016a5 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -95,20 +95,17 @@ Create a Homebrew installation wherever you extract the tarball. Whichever `brew ## Post-installation steps -Before completing installation, Homebrew installer will provide some required "Next steps" instructions. -These instructions configure your shell to evaluate the output of `brew shellenv`, -which will load `brew` into your shell environment for use. +When you install Homebrew, it prints some directions for updating your shell's config. +If you don't follow those directions, Homebrew will not work. -While it's difficult to document the precise path for every shell, -typically, what follows must be in your shell's `rc` or `profile` file: +You need to update your shell's config file (which file exactly depends on your shell, for example `~/.bashrc` or `~/.zshrc`) to include this: ```sh eval "/bin/brew shellenv)" ``` -where `${HOMEBREW_PREFIX}` is the Homebrew installation directory. -Replace this with the installation directory on your system. -See the [FAQ about default installation locations](FAQ.md#why-should-i-install-homebrew-in-the-default-location). +Replace `` with the directory where Homebrew is installed on your system. +You can find Homebrew's default install location [in this FAQ entry](https://docs.brew.sh/FAQ#why-should-i-install-homebrew-in-the-default-location). For more insight, re-run the installer or inspect [the installer's source](https://github.com/Homebrew/install/blob/deacfa6a6e62e5f4002baf9e1fac7a96e9aa5d41/install.sh#L1072-L1088) to see how the installer constructs the path it recommends. From dfbc9317696b7cd540018f800a47d207802023f7 Mon Sep 17 00:00:00 2001 From: Colin Dean Date: Wed, 19 Feb 2025 11:58:07 -0500 Subject: [PATCH 5/5] Recommend abbreviated multi-platform loader Co-authored-by: Mike McQuaid --- docs/Tips-N'-Tricks.md | 32 ++------------------------------ 1 file changed, 2 insertions(+), 30 deletions(-) diff --git a/docs/Tips-N'-Tricks.md b/docs/Tips-N'-Tricks.md index 9606d37b0e20a..ea2ce64612758 100644 --- a/docs/Tips-N'-Tricks.md +++ b/docs/Tips-N'-Tricks.md @@ -148,34 +148,6 @@ Use this to detect the likely Homebrew installation directory and load Homebrew You may need to adapt this to your particular shell or other particulars of your environment. ```sh -# Execute only if brew isn't already available. -if ! [ -x "$(command -v brew)" ]; then - OS="$(uname)" - UNAME_MACHINE="$(uname -m)" - if [ "${OS}" = "Linux" ]; then - # Linux - HOMEBREW_PREFIX="/home/linuxbrew/.linuxbrew" - elif [ "${OS}" = "Darwin" ]; then - if [ "${UNAME_MACHINE}" = "arm64" ]; then - # M-series ARM64 macOS - HOMEBREW_PREFIX="/opt/homebrew" - else - # Intel macOS - HOMEBREW_PREFIX="/usr/local" - fi - fi - - if [ -d "${HOMEBREW_PREFIX}" ]; then - BREW_BIN="${HOMEBREW_PREFIX}/bin/brew" - if [ -x "${BREW_BIN}" ]; then - eval "\$(${BREW_BIN} shellenv)" - else - >&2 printf "Homebrew possibly found at %s but %s is not executable. Check the permissions.\n" "${HOMEBREW_PREFIX}" "${BREW_BIN}" - fi - else - >&2 printf "Homebrew not found where expected in %s on %s %s\n" "${HOMEBREW_PREFIX}" "${OS}" "${UNAME_MACHINE}" - >&2 printf "Double-check that it's installed or run the following command to install it\n\n\t%s\n" \ - '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"' - fi -fi +command -v brew || export PATH="/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/local/bin" +command -v brew && eval "$(brew shellenv)" ```