Reintroduce and adapt commit 49aceb152.

     Account for differences between upstream versions 1.9.3 and 3.2.12 (the
latter being the latest stable one upstream as of this commit,) namely with
respect to how argument parsing is implemented.

---

Summary of old changes prior to manual rebase/adaptation:

brew.rb:  Undeprecate `HOMEBREW_BUILD_FROM_SOURCE`.

     Partially revert Homebrew#5477.

---

Additionally, restore and/or add documentation relevant to this environment va-
riable.

**IMPORTANT NOTE!!!**:  _Neither this commit nor the one it's based on restores
or restored the funcitonality which setting `HOMEBREW_BUILD_FROM_SOURCE` trig-
gered before that got removed later!_  This shortcoming will be addressed in the
future in one or more commits.

Library/Homebrew/cmd/install.rb

@@ -27,6 +27,10 @@ def install_args
         Install a <formula> or <cask>. Additional options specific to a <formula> may be
         appended to the command.
 
+        If `HOMEBREW_BUILD_FROM_SOURCE` is set, then both <formula> and any dependencies installed while
+        installing it are built from source even if bottles are available for them, regardless of whether
+        `--build-from-source` was passed or not.
+
         Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for
         the installed formulae or, every 30 days, for all formulae.
       EOS

Library/Homebrew/cmd/reinstall.rb

@@ -26,6 +26,10 @@ def reinstall_args
         Uninstall and then reinstall a <formula> or <cask> using the same options it was
         originally installed with, plus any appended options specific to a <formula>.
 
+        If `HOMEBREW_BUILD_FROM_SOURCE` is set, then both <formula> and any dependencies reinstalled while
+        reinstalling it are built from source even if bottles are available for them, regardless of whether
+        `--build-from-source` was passed or not.
+
         Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for the
         reinstalled formulae or, every 30 days, for all formulae.
       EOS

Library/Homebrew/cmd/upgrade.rb

@@ -23,6 +23,10 @@ def upgrade_args
         installed with, plus any appended brew formula options. If <cask> or <formula> are specified,
         upgrade only the given <cask> or <formula> kegs (unless they are pinned; see `pin`, `unpin`).
 
+        If `HOMEBREW_BUILD_FROM_SOURCE` is set, then both <formula> and any dependencies upgraded while
+        upgrading it are built from source even if bottles are available for them, regardless of whether
+        `--build-from-source` was passed or not.
+
         Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for the
         upgraded formulae or, every 30 days, for all formulae.
       EOS

Library/Homebrew/env_config.rb

@@ -58,7 +58,13 @@ module EnvConfig
         description:  "Use this as the browser when opening project homepages.",
         default_text: "`$BROWSER` or the OS's default browser.",
       },
-      HOMEBREW_CACHE:                             {
+      HOMEBREW_BUILD_FROM_SOURCE:             {
+        description:  "If set, then all supplied formulae, along with their (recursive) dependencies, are built " \
+                      "from source even if bottles are available for them, regardless of whether " \
+                      "`--build-from-source` was passed or not.",
+        boolean:      true,
+      },
+      HOMEBREW_CACHE:                         {
         description:  "Use this directory as the download cache.",
         default_text: "macOS: `$HOME/Library/Caches/Homebrew`, " \
                       "Linux: `$XDG_CACHE_HOME/Homebrew` or `$HOME/.cache/Homebrew`.",

docs/FAQ.md

@@ -72,6 +72,7 @@ following conditions:
 will use a bottled version of the formula, but
 `brew install --enable-bar <formula>` will trigger a source build.
 * The `--build-from-source` option is invoked.
+* The environement variable `HOMEBREW_BUILD_FROM_SOURCE` is set.
 * The machine is not running a supported version of macOS as all
 bottled builds are generated only for supported macOS versions.
 * Homebrew is installed to a prefix other than the default

docs/Manpage.md

@@ -297,6 +297,10 @@ If a *`formula`* or *`cask`* is provided, show summary of information about it.
 Install a *`formula`* or *`cask`*. Additional options specific to a *`formula`* may be
 appended to the command.
 
+If `HOMEBREW_BUILD_FROM_SOURCE` is set, then both *`formula`* and any dependencies installed while
+installing it are built from source even if bottles are available for them, regardless of whether
+`--build-from-source` was passed or not.
+
 Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for
 the installed formulae or, every 30 days, for all formulae.
 
@@ -499,6 +503,10 @@ all items or checking if any current formulae/casks have Ruby issues.
 Uninstall and then reinstall a *`formula`* or *`cask`* using the same options it was
 originally installed with, plus any appended options specific to a *`formula`*.
 
+If `HOMEBREW_BUILD_FROM_SOURCE` is set, then both *`formula`* and any dependencies reinstalled while
+reinstalling it are built from source even if bottles are available for them, regardless of whether
+`--build-from-source` was passed or not.
+
 Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for the
 reinstalled formulae or, every 30 days, for all formulae.
 
@@ -671,6 +679,10 @@ Upgrade outdated casks and outdated, unpinned formulae using the same options th
 installed with, plus any appended brew formula options. If *`cask`* or *`formula`* are specified,
 upgrade only the given *`cask`* or *`formula`* kegs (unless they are pinned; see `pin`, `unpin`).
 
+If `HOMEBREW_BUILD_FROM_SOURCE` is set, then both *`formula`* and any dependencies upgraded while
+upgrading it are built from source even if bottles are available for them, regardless of whether
+`--build-from-source` was passed or not.
+
 Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for the
 upgraded formulae or, every 30 days, for all formulae.
 
@@ -1908,6 +1920,9 @@ example, run `export HOMEBREW_NO_INSECURE_REDIRECT=1` rather than just
 
   *Default:* `$BROWSER` or the OS's default browser.
 
+  * `HOMEBREW_BUILD_FROM_SOURCE`:
+    If set, then all supplied formulae, along with their (recursive) dependencies, are built from source even if bottles are available for them, regardless of whether `--build-from-source` was passed or not.
+
 - `HOMEBREW_CACHE`
   <br>Use this directory as the download cache.
 

manpages/brew.1

@@ -381,6 +381,9 @@ Treat all named arguments as casks\.
 Install a \fIformula\fR or \fIcask\fR\. Additional options specific to a \fIformula\fR may be appended to the command\.
 .
 .P
+If \fBHOMEBREW_BUILD_FROM_SOURCE\fR is set, then both \fIformula\fR and any dependencies installed while installing it are built from source even if bottles are available for them, regardless of whether \fB\-\-build\-from\-source\fR was passed or not\.
+.
+.P
 Unless \fBHOMEBREW_NO_INSTALL_CLEANUP\fR is set, \fBbrew cleanup\fR will then be run for the installed formulae or, every 30 days, for all formulae\.
 .
 .TP
@@ -675,6 +678,9 @@ Syntax\-check all of Homebrew\'s Ruby files (if no \fB<tap>\fR is passed)\.
 Uninstall and then reinstall a \fIformula\fR or \fIcask\fR using the same options it was originally installed with, plus any appended options specific to a \fIformula\fR\.
 .
 .P
+If \fBHOMEBREW_BUILD_FROM_SOURCE\fR is set, then both \fIformula\fR and any dependencies reinstalled while reinstalling it are built from source even if bottles are available for them, regardless of whether \fB\-\-build\-from\-source\fR was passed or not\.
+.
+.P
 Unless \fBHOMEBREW_NO_INSTALL_CLEANUP\fR is set, \fBbrew cleanup\fR will then be run for the reinstalled formulae or, every 30 days, for all formulae\.
 .
 .TP
@@ -909,6 +915,9 @@ Fetch and reset Homebrew and all tap repositories (or any specified \fIrepositor
 Upgrade outdated casks and outdated, unpinned formulae using the same options they were originally installed with, plus any appended brew formula options\. If \fIcask\fR or \fIformula\fR are specified, upgrade only the given \fIcask\fR or \fIformula\fR kegs (unless they are pinned; see \fBpin\fR, \fBunpin\fR)\.
 .
 .P
+If \fBHOMEBREW_BUILD_FROM_SOURCE\fR is set, then both \fIformula\fR and any dependencies upgraded while upgrading it are built from source even if bottles are available for them, regardless of whether \fB\-\-build\-from\-source\fR was passed or not\.
+.
+.P
 Unless \fBHOMEBREW_NO_INSTALL_CLEANUP\fR is set, \fBbrew cleanup\fR will then be run for the upgraded formulae or, every 30 days, for all formulae\.
 .
 .TP
@@ -2700,6 +2709,10 @@ Use this as the browser when opening project homepages\.
 \fIDefault:\fR \fB$BROWSER\fR or the OS\'s default browser\.
 .
 .TP
+\fBHOMEBREW_BUILD_FROM_SOURCE\fR
+If set, then all supplied formulae, along with their (recursive) dependencies, are built from source even if bottles are available for them, regardless of whether \fB\-\-build\-from\-source\fR was passed or not\.
+.
+.TP
 \fBHOMEBREW_CACHE\fR
 .
 .br