From 72735aef175bf7ddb74728e75ad3a0dc5961c5f3 Mon Sep 17 00:00:00 2001
From: Afnan Enayet <afnan.enayet@gmail.com>
Date: Thu, 5 Jul 2018 17:25:19 -0400
Subject: [PATCH] Update documentation and generate manpage
* update references in `--cc` flag, using modern gcc examples
* note that issues should not be filed if `--cc` flag is used
* remove reference to `HOMEBREW_CC` as it should not be exposed to users
* generate manpages using `brew man` with these changes
---
Library/Homebrew/cmd/install.rb | 11 ++++++-----
Library/Homebrew/manpages/brew.1.md.erb | 9 ---------
docs/Custom-GCC-and-cross-compilers.md | 10 +++++-----
docs/Manpage.md | 20 ++++++--------------
manpages/brew.1 | 6 +-----
5 files changed, 18 insertions(+), 38 deletions(-)
diff --git a/Library/Homebrew/cmd/install.rb b/Library/Homebrew/cmd/install.rb
index 841567fb4d..1ef8f929c3 100644
--- a/Library/Homebrew/cmd/install.rb
+++ b/Library/Homebrew/cmd/install.rb
@@ -21,11 +21,12 @@
#:
#: If `--cc=`<compiler> is passed, attempt to compile using <compiler>.
#: <compiler> should be the name of the compiler's executable, for instance
-#: `gcc-4.2` for Apple's GCC 4.2, or `gcc-4.9` for a Homebrew-provided GCC
-#: 4.9. In order to use LLVM's clang, use `llvm_clang`. To specify the
-#: Apple-provided clang, use `clang`. This parameter will only accept
-#: compilers that are provided by Homebrew. Note that this will override
-#: the value set by the `$HOMEBREW_CC` environment variable.
+#: `gcc-8` for gcc 8, `gcc-4.2` for Apple's GCC 4.2, or `gcc-4.9` for a
+#: Homebrew-provided GCC 4.9. In order to use LLVM's clang, use
+#: `llvm_clang`. To specify the Apple-provided clang, use `clang`. This
+#: parameter will only accept compilers that are provided by Homebrew or
+#: bundled with MacOS. Please do not file issues if you encounter errors
+#: while using this flag.
#:
#: If `--build-from-source` (or `-s`) is passed, compile the specified <formula> from
#: source even if a bottle is provided. Dependencies will still be installed
diff --git a/Library/Homebrew/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb
index 43a34d8040..902d6bde5b 100644
--- a/Library/Homebrew/manpages/brew.1.md.erb
+++ b/Library/Homebrew/manpages/brew.1.md.erb
@@ -138,15 +138,6 @@ Note that environment variables must have a value set to be detected. For exampl
*Default:* `~/Library/Caches/Homebrew`.
- * `HOMEBREW_CC`:
- If set, instructs Homebrew to used the specified compiler to build a
- package from source. In order to specify the Apple-provided clang,
- set `clang`. For the clang provided from the LLVM package, use
- `llvm_clang`. For versions of gcc, use the names of the executables from
- the packages that Homebrew provides, e.g. for gcc 4.9, `gcc-4.9`, or for
- gcc 8, `gcc-8`. Note that this variable can only be set to compilers that
- are provided by Homebrew.
-
* `HOMEBREW_CURLRC`:
If set, Homebrew will not pass `-q` when invoking `curl`(1) (which disables
the use of `curlrc`).
diff --git a/docs/Custom-GCC-and-cross-compilers.md b/docs/Custom-GCC-and-cross-compilers.md
index b92482baa2..9352460422 100644
--- a/docs/Custom-GCC-and-cross-compilers.md
+++ b/docs/Custom-GCC-and-cross-compilers.md
@@ -14,9 +14,9 @@ Rather than merging in brews for either of these cases at this time, we're
listing them on this page. If you come up with a formula for a new version of
GCC or cross-compiler suite, please link it in here.
-* Homebrew provides a `gcc` formula for use with Xcode 4.2+ or when needing
+- Homebrew provides a `gcc` formula for use with Xcode 4.2+ or when needing
C++11 support on earlier versions.
-* Homebrew provides older GCC formulae, e.g. `gcc@4.8` and `gcc@6`.
-* Homebrew provides the LLVM clang, which is bundled with the `llvm` formula.
-* [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V
- toolchain including binutils and GCC.
\ No newline at end of file
+- Homebrew provides older GCC formulae, e.g. `gcc@4.9` and `gcc@6`.
+- Homebrew provides the LLVM clang, which is bundled with the `llvm` formula.
+- [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V
+ toolchain including binutils and GCC.
diff --git a/docs/Manpage.md b/docs/Manpage.md
index 15a736059d..fac6875943 100644
--- a/docs/Manpage.md
+++ b/docs/Manpage.md
@@ -239,11 +239,12 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
If `--cc=``compiler` is passed, attempt to compile using `compiler`.
`compiler` should be the name of the compiler's executable, for instance
- `gcc-4.2` for Apple's GCC 4.2, or `gcc-4.9` for a Homebrew-provided GCC
- 4.9. In order to use LLVM's clang, use `llvm_clang`. To specify the
- Apple-provided clang, use `clang`. This parameter will only accept
- compilers that are provided by Homebrew. Note that this will override
- the value set by the `$HOMEBREW_CC` environment variable.
+ `gcc-8` for gcc 8, `gcc-4.2` for Apple's GCC 4.2, or `gcc-4.9` for a
+ Homebrew-provided GCC 4.9. In order to use LLVM's clang, use
+ `llvm_clang`. To specify the Apple-provided clang, use `clang`. This
+ parameter will only accept compilers that are provided by Homebrew or
+ bundled with MacOS. Please do not file issues if you encounter errors
+ while using this flag.
If `--build-from-source` (or `-s`) is passed, compile the specified `formula` from
source even if a bottle is provided. Dependencies will still be installed
@@ -1125,15 +1126,6 @@ Note that environment variables must have a value set to be detected. For exampl
*Default:* `~/Library/Caches/Homebrew`.
- * `HOMEBREW_CC`:
- If set, instructs Homebrew to used the specified compiler to build a
- package from source. In order to specify the Apple-provided clang,
- set `clang`. For the clang provided from the LLVM package, use
- `llvm_clang`. For versions of gcc, use the names of the executables from
- the packages that Homebrew provides, e.g. for gcc 4.9, `gcc-4.9`, or for
- gcc 8, `gcc-8`. Note that this variable can only be set to compilers that
- are provided by Homebrew.
-
* `HOMEBREW_CURLRC`:
If set, Homebrew will not pass `-q` when invoking `curl`(1) (which disables
the use of `curlrc`).
diff --git a/manpages/brew.1 b/manpages/brew.1
index 0cbd60f257..8137c4ad15 100644
--- a/manpages/brew.1
+++ b/manpages/brew.1
@@ -227,7 +227,7 @@ If \fB\-\-ignore\-dependencies\fR is passed, skip installing any dependencies of
If \fB\-\-only\-dependencies\fR is passed, install the dependencies with specified options but do not install the specified formula\.
.
.IP
-If \fB\-\-cc=\fR\fIcompiler\fR is passed, attempt to compile using \fIcompiler\fR\. \fIcompiler\fR should be the name of the compiler\'s executable, for instance \fBgcc\-4\.2\fR for Apple\'s GCC 4\.2, or \fBgcc\-4\.9\fR for a Homebrew\-provided GCC 4\.9\. In order to use LLVM\'s clang, use \fBllvm_clang\fR\. To specify the Apple\-provided clang, use \fBclang\fR\. This parameter will only accept compilers that are provided by Homebrew\. Note that this will override the value set by the \fB$HOMEBREW_CC\fR environment variable\.
+If \fB\-\-cc=\fR\fIcompiler\fR is passed, attempt to compile using \fIcompiler\fR\. \fIcompiler\fR should be the name of the compiler\'s executable, for instance \fBgcc\-8\fR for gcc 8, \fBgcc\-4\.2\fR for Apple\'s GCC 4\.2, or \fBgcc\-4\.9\fR for a Homebrew\-provided GCC 4\.9\. In order to use LLVM\'s clang, use \fBllvm_clang\fR\. To specify the Apple\-provided clang, use \fBclang\fR\. This parameter will only accept compilers that are provided by Homebrew or bundled with MacOS\. Please do not file issues if you encounter errors while using this flag\.
.
.IP
If \fB\-\-build\-from\-source\fR (or \fB\-s\fR) is passed, compile the specified \fIformula\fR from source even if a bottle is provided\. Dependencies will still be installed from bottles if they are available\.
@@ -1069,10 +1069,6 @@ If set, instructs Homebrew to use the given directory as the download cache\.
\fIDefault:\fR \fB~/Library/Caches/Homebrew\fR\.
.
.TP
-\fBHOMEBREW_CC\fR
-If set, instructs Homebrew to used the specified compiler to build a package from source\. In order to specify the Apple\-provided clang, set \fBclang\fR\. For the clang provided from the LLVM package, use \fBllvm_clang\fR\. For versions of gcc, use the names of the executables from the packages that Homebrew provides, e\.g\. for gcc 4\.9, \fBgcc\-4\.9\fR, or for gcc 8, \fBgcc\-8\fR\. Note that this variable can only be set to compilers that are provided by Homebrew\.
-.
-.TP
\fBHOMEBREW_CURLRC\fR
If set, Homebrew will not pass \fB\-q\fR when invoking \fBcurl\fR(1) (which disables the use of \fBcurlrc\fR)\.
.
--
GitLab