[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

605

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. $prefix may or may not be a directory
 
 .. 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 on targets which commonly use GCC. The directory usually contains 'lib{,32,64}/gcc{,-cross}/$triple' 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. $prefix may or may not be a directory">;
+def gcc_toolchain : Joined<["--"], "gcc-toolchain=">, Flags<[NoXarchOption]>,
+  HelpText<"Search for GCC installation in the specified directory on targets which commonly use GCC. "
+  "The directory usually contains 'lib{,32,64}/gcc{,-cross}/$triple' 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">;