From 0f32f8a600090c6325f8eb8cf045fc75d9ad634e Mon Sep 17 00:00:00 2001
From: Mike McQuaid <mike@mikemcquaid.com>
Date: Fri, 11 Sep 2026 19:35:53 +0100
Subject: [PATCH] Deprecate HOMEBREW_ARCH

---
 Library/Homebrew/env_config.rb           |  2 ++
 Library/Homebrew/test/env_config_spec.rb | 22 ++++++++++++++++++++++
 docs/Manpage.md                          |  7 -------
 manpages/brew.1                          |  7 -------
 4 files changed, 24 insertions(+), 14 deletions(-)

diff --git a/Library/Homebrew/env_config.rb b/Library/Homebrew/env_config.rb
index b68f272bab..94d9e23da1 100644
--- a/Library/Homebrew/env_config.rb
+++ b/Library/Homebrew/env_config.rb
@@ -68,6 +68,8 @@ module Homebrew
       HOMEBREW_ARCH:                             {
         description: "Linux only: Pass this value to a type name representing the compiler's `-march` option.",
         default:     "native",
+        replacement: "the default native CPU optimisation",
+        odeprecated: true,
       },
       HOMEBREW_ARTIFACT_DOMAIN:                  {
         description: "Prefix all download URLs, including those for bottles, with this value. " \
diff --git a/Library/Homebrew/test/env_config_spec.rb b/Library/Homebrew/test/env_config_spec.rb
index 9204595f6b..818f7e8ed3 100644
--- a/Library/Homebrew/test/env_config_spec.rb
+++ b/Library/Homebrew/test/env_config_spec.rb
@@ -97,6 +97,28 @@ RSpec.describe Homebrew::EnvConfig do
     end
   end
 
+  describe ".arch" do
+    it "deprecates overriding the compiler architecture" do
+      ENV["HOMEBREW_ARCH"] = "haswell"
+
+      expect { env_config.arch }
+        .to raise_error(MethodDeprecatedError, /HOMEBREW_ARCH.*deprecated.*native/)
+    end
+
+    it "preserves the default native architecture" do
+      ENV.delete("HOMEBREW_ARCH")
+
+      expect(env_config.arch).to eq("native")
+    end
+
+    it "preserves an explicit architecture during deprecation" do
+      ENV["HOMEBREW_ARCH"] = "haswell"
+      allow(env_config).to receive(:odeprecated)
+
+      expect(env_config.arch).to eq("haswell")
+    end
+  end
+
   describe ".non_default_variable?" do
     it "detects whether a variable has a non-default value" do
       ENV["HOMEBREW_CURL_RETRIES"] = "4"
diff --git a/docs/Manpage.md b/docs/Manpage.md
index e134e0987d..374b0fca84 100644
--- a/docs/Manpage.md
+++ b/docs/Manpage.md
@@ -4393,13 +4393,6 @@ command execution (e.g. `$(cat file)`).
   
   *Default:* `https://formulae.brew.sh/api`.
 
-`HOMEBREW_ARCH`
-
-: Linux only: Pass this value to a type name representing the compiler's
-  `-march` option.
-  
-  *Default:* `native`.
-
 `HOMEBREW_ARTIFACT_DOMAIN`
 
 : Prefix all download URLs, including those for bottles, with this value. For
diff --git a/manpages/brew.1 b/manpages/brew.1
index 46d591b788..36850b715c 100644
--- a/manpages/brew.1
+++ b/manpages/brew.1
@@ -2796,13 +2796,6 @@ Use this URL as the download mirror for Homebrew JSON API\. If metadata files at
 \fIDefault:\fP \fBhttps://formulae\.brew\.sh/api\fP\&\.
 .RE
 .TP
-\fBHOMEBREW_ARCH\fP
-Linux only: Pass this value to a type name representing the compiler\[u2019]s \fB\-march\fP option\.
-.RS
-.P
-\fIDefault:\fP \fBnative\fP\&\.
-.RE
-.TP
 \fBHOMEBREW_ARTIFACT_DOMAIN\fP
 Prefix all download URLs, including those for bottles, with this value\. For example, \fBexport HOMEBREW_ARTIFACT_DOMAIN=http://localhost:8080\fP will cause a formula with the URL \fBhttps://example\.com/foo\.tar\.gz\fP to instead download from \fBhttp://localhost:8080/https://example\.com/foo\.tar\.gz\fP\&\. Bottle URLs however, have their domain replaced with this prefix\. This results in e\.g\. \fBhttps://ghcr\.io/v2/homebrew/core/gettext/manifests/0\.21\fP to instead be downloaded from \fBhttp://localhost:8080/v2/homebrew/core/gettext/manifests/0\.21\fP\&\. If the value already contains a \fB/v2\fP path (e\.g\. an OCI registry proxying GitHub Packages under a repository prefix such as \fBhttps://mirror\.example\.com/v2/ghcr\-io\fP), the \fBv2\fP path is not duplicated, resulting in e\.g\. \fBhttps://mirror\.example\.com/v2/ghcr\-io/homebrew/core/gettext/manifests/0\.21\fP\&\.
 .TP