Merge pull request #4398 from afnanenayet/update-compiler-docs

Update manpage with information about alternative compilers

Library/Homebrew/cmd/install.rb

@@ -21,8 +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
+#:    `gcc-8` for gcc 8, `gcc-4.2` for Apple's GCC 4.2, or `gcc-4.9` for a
-#:    4.9.
+#:    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

docs/Custom-GCC-and-cross-compilers.md

@@ -14,8 +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.
+  C++11 support on earlier versions.
-* Homebrew provides older GCC formulae, e.g. `gcc@4.8` and `gcc@6`.
+- Homebrew provides older GCC formulae, e.g. `gcc@4.9` and `gcc@6`.
-* [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V
+- Homebrew provides the LLVM clang, which is bundled with the `llvm` formula.
-toolchain including binutils and GCC.
+- [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V
+  toolchain including binutils and GCC.

docs/Manpage.md

@@ -239,8 +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
+    `gcc-8` for gcc 8, `gcc-4.2` for Apple's GCC 4.2, or `gcc-4.9` for a
-    4.9.
+    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

manpages/brew-cask.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW\-CASK" "1" "June 2018" "Homebrew" "brew-cask"
+.TH "BREW\-CASK" "1" "July 2018" "Homebrew" "brew-cask"
 .
 .SH "NAME"
 \fBbrew\-cask\fR \- a friendly binary installer for macOS

manpages/brew.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW" "1" "June 2018" "Homebrew" "brew"
+.TH "BREW" "1" "July 2018" "Homebrew" "brew"
 .
 .SH "NAME"
 \fBbrew\fR \- The missing package manager for macOS
@@ -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\.
+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\.