[docs] Improve documentation of -B and --gcc-toolchain

[MaskRay]

Summary

And add tests: when both --prefix(-B) and --gcc-toolchain are specified, the GCC
installation with the largest version wins. This just documents the
current behavior.

[MaskRay]

This is motivated by Linux kernel folks' confusion on --gcc-toolchain https://lore.kernel.org/linux-kbuild/[e-mail]/
(it confused me, even if I had stared at this piece code a few times before!)

The command line option documentation is currently a bit messy, and lacks much information.
We probably need something similar to include/clang/Basic/AttrDocs.td by @aaron.ballman

I choose to add it inline before the infrastructure is available.

I understand --gcc-toolchain as a replacement for configure-time replacement for GCC_INSTALL_PREFIX. This option probably should not have existed:(

[nickdesaulniers]

clang/docs/ClangCommandLineReference.rst

23

I like how --gcc-toolchain references -B; can -B also reference --gcc-toolchain? That way developers also understand their options when looking at either? Or should we move --gcc-toolchain to be closer to -B, since they're slightly similar?

259

Add whitespace after periods.

clang/include/clang/Driver/Options.td

603

s/includes/includes,/

[nickdesaulniers]

Thanks for the patch! It is a much needed clarification!

[MaskRay]

comments

clang/docs/ClangCommandLineReference.rst

23

clang-tblgen -I ../llvm/include -I include/clang/Driver -gen-opt-docs include/clang/Driver/ClangOptionDocs.td sorts the options alphabetically so it is not easy to move them together...

[nickdesaulniers]

clang/docs/ClangCommandLineReference.rst

23

Ok. Can we still refer to --gcc-toolchain from here?

259

Looks like there's another instance of this comment on this line.

[MaskRay]

Add more information to --gcc-toolchain.
Reference --gcc-toolchain in --prefix

[manojgupta]

thanks, this is much needed documentation.

[MaskRay]

Rebase on D97993

clang/docs/ClangCommandLineReference.rst

 Introduction
 ============
 
 This page lists the command line arguments currently supported by the
 GCC-compatible ``clang`` and ``clang++`` drivers.
 
 
 .. program:: clang
-.. option:: -B<dir>, --prefix <arg>, --prefix=<arg>
+.. option:: -B<prefix>, --prefix <arg>, --prefix=<arg>
 
-Add <dir> to search path for binaries and object files used implicitly
+Search $prefix/$triple-$file and $prefix$file for executables, libraries, includes, and data files used by the compiler. If $prefix is a directory, the directory is used to search for GCC installation on targets which commonly use GCC. The directory usually contains 'include' and 'lib'. Note: sysroot is also used to search for GCC installation and the largest version wins. Specify --gcc-toolchain to suppress sysroot. If $prefix is not a directory, the GCC installation detection is skipped but $prefix can still be used to find executables, typically for -nostdinc -nostdlib compiles
 
 .. option:: -F<arg>
 
 Add directory to framework include search path
 
 .. option:: -ObjC
 
 Treat source input files as Objective-C inputs

 Path to system blacklist file for sanitizers
 
 .. option:: -fsystem-module
 
 Build this module as a system module. Only used with -emit-module
 
 .. option:: --gcc-toolchain=<arg>, -gcc-toolchain <arg>
 
-Use the gcc toolchain at the given directory
+Search for GCC installation in the specified directory, similar to -B<dir>. The directory usually contains 'lib' and 'include'. If specified, sysroot is skipped for GCC detection. Note: executables (e.g. ld) used by the compiler are not overridden by the selected GCC installation
 
 .. option:: -gcodeview
 
 Generate CodeView debug information
 
 .. option:: -gcodeview-ghash, -gno-codeview-ghash
 
 Emit type record hashes in a .debug$H section

clang/include/clang/Driver/Options.td

 
 // Standard Options
 
 def _HASH_HASH_HASH : Flag<["-"], "###">, Flags<[NoXarchOption, CoreOption, FlangOption]>,
     HelpText<"Print (but do not run) the commands to run for this compilation">;
 def _DASH_DASH : Option<["--"], "", KIND_REMAINING_ARGS>,
     Flags<[NoXarchOption, CoreOption]>;
 def A : JoinedOrSeparate<["-"], "A">, Flags<[RenderJoined]>, Group<gfortran_Group>;
-def B : JoinedOrSeparate<["-"], "B">, MetaVarName<"<dir>">,
-    HelpText<"Add <dir> to search path for binaries and object files used implicitly">;
+def B : JoinedOrSeparate<["-"], "B">, MetaVarName<"<prefix>">,
+    HelpText<"Search $prefix/$triple-$file and $prefix$file for executables, libraries, "
+    "includes, and data files used by the compiler. If $prefix is a directory, the "
+    "directory is used to search for GCC installation on targets which commonly use GCC. "
+    "The directory usually contains 'include' and 'lib'. Note: sysroot is also used to "
+    "search for GCC installation and the largest version wins. Specify --gcc-toolchain "
+    "to suppress sysroot. If $prefix is not a directory, the GCC installation detection "
+    "is skipped but $prefix can still be used to find executables, typically for -nostdinc "
+    "-nostdlib compiles">;
+def gcc_toolchain : Joined<["--"], "gcc-toolchain=">, Flags<[NoXarchOption]>,
+  HelpText<"Search for GCC installation in the specified directory, similar to -B<dir>. "
+  "The directory usually contains 'lib' and 'include'. If specified, sysroot is skipped "
+  "for GCC detection. Note: executables (e.g. ld) used by the compiler are not overridden "
+  "by the selected GCC installation">;
 def CC : Flag<["-"], "CC">, Flags<[CC1Option]>, Group<Preprocessor_Group>,
     HelpText<"Include comments from within macros in preprocessed output">,
     MarshallingInfoFlag<PreprocessorOutputOpts<"ShowMacroComments">>;
 def C : Flag<["-"], "C">, Flags<[CC1Option]>, Group<Preprocessor_Group>,
     HelpText<"Include comments in preprocessed output">,
     MarshallingInfoFlag<PreprocessorOutputOpts<"ShowComments">>;
 def D : JoinedOrSeparate<["-"], "D">, Group<Preprocessor_Group>,
     Flags<[CC1Option, FlangOption, FC1Option]>, MetaVarName<"<macro>=<value>">,
def target : Joined<["--"], "target=">, Flags<[NoXarchOption, CoreOption]>,
   HelpText<"Generate code for the given target">;
 def print_supported_cpus : Flag<["-", "--"], "print-supported-cpus">,
   Group<CompileOnly_Group>, Flags<[CC1Option, CoreOption]>,
   HelpText<"Print supported cpu models for the given target (if target is not specified,"
            " it will print the supported cpus for the default target)">,
   MarshallingInfoFlag<FrontendOpts<"PrintSupportedCPUs">>;
 def mcpu_EQ_QUESTION : Flag<["-"], "mcpu=?">, Alias<print_supported_cpus>;
 def mtune_EQ_QUESTION : Flag<["-"], "mtune=?">, Alias<print_supported_cpus>;
-def gcc_toolchain : Joined<["--"], "gcc-toolchain=">, Flags<[NoXarchOption]>,
-  HelpText<"Use the gcc toolchain at the given directory">;
 def time : Flag<["-"], "time">,
   HelpText<"Time individual commands">;
 def traditional_cpp : Flag<["-", "--"], "traditional-cpp">, Flags<[CC1Option]>,
   HelpText<"Enable some traditional CPP emulation">,
   MarshallingInfoFlag<LangOpts<"TraditionalCPP">>;
 def traditional : Flag<["-", "--"], "traditional">;
 def trigraphs : Flag<["-", "--"], "trigraphs">, Alias<ftrigraphs>,
   HelpText<"Process trigraph sequences">;

clang/test/Driver/gcc-toolchain.cpp

 //
 // Test for linker toolchain detection. Note that only the '-L' flags will use
 // the same precise formatting of the path as the '-internal-system' flags
 // above, so we just blanket wildcard match the 'crtbegin.o'.
 // CHECK: "{{[^"]*}}ld{{(.exe)?}}"
 // CHECK: "{{[^"]*}}/usr/lib/i386-linux-gnu/gcc/i686-linux-gnu/4.5{{/|\\\\}}crtbegin.o"
 // CHECK: "-L[[TOOLCHAIN]]/usr/lib/i386-linux-gnu/gcc/i686-linux-gnu/4.5"
 // CHECK: "-L[[TOOLCHAIN]]/usr/lib/i386-linux-gnu/gcc/i686-linux-gnu/4.5/../../../.."
+//
+// RUN: %clangxx -no-canonical-prefixes %s -### -o %t 2>&1 \
+// RUN:     --target=x86_64-linux-gnu -stdlib=libstdc++ \
+// RUN:     --gcc-toolchain=%S/Inputs/ubuntu_13.04_multiarch_tree/usr \
+// RUN:     --sysroot= | FileCheck %s --check-prefix=UBUNTU13
+
+/// If both --prefix and --gcc-toolchain are specified, the GCC installation with a larger version wins.
+// RUN: %clangxx -no-canonical-prefixes %s -### -o %t 2>&1 \
+// RUN:     --target=i386-unknown-linux -stdlib=libstdc++ \
+// RUN:     --prefix=%S/Inputs/ubuntu_13.04_multiarch_tree/usr \
+// RUN:     --gcc-toolchain=%S/Inputs/ubuntu_11.04_multiarch_tree/usr \
+// RUN:     --sysroot= | FileCheck %s --check-prefix=UBUNTU13
+
+// RUN: %clangxx -no-canonical-prefixes %s -### -o %t 2>&1 \
+// RUN:     --target=i386-unknown-linux -stdlib=libstdc++ \
+// RUN:     --prefix=%S/Inputs/ubuntu_11.04_multiarch_tree/usr \
+// RUN:     --gcc-toolchain=%S/Inputs/ubuntu_13.04_multiarch_tree/usr \
+// RUN:     --sysroot= | FileCheck %s --check-prefix=UBUNTU13
+
+// UBUNTU13: {{.*}}/ubuntu_13.04_multiarch_tree/usr/lib/gcc/x86_64-linux-gnu/4.7