Page MenuHomePhabricator

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

Authored by MaskRay on Mar 3 2021, 6:05 PM.

Details

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.

Diff Detail

Event Timeline

MaskRay created this revision.Mar 3 2021, 6:05 PM
MaskRay requested review of this revision.Mar 3 2021, 6:05 PM
Herald added a project: Restricted Project. · View Herald TranscriptMar 3 2021, 6:05 PM
Herald added a subscriber: cfe-commits. · View Herald Transcript
MaskRay added a subscriber: aaron.ballman.EditedMar 3 2021, 6:09 PM

This is motivated by Linux kernel folks' confusion on --gcc-toolchain https://lore.kernel.org/linux-kbuild/20210303230708.l6pbk5o5nc2qa5of@google.com/
(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 added inline comments.Mar 4 2021, 9:46 AM
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,/

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

MaskRay updated this revision to Diff 328220.Mar 4 2021, 9:59 AM
MaskRay marked 2 inline comments as done.

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...

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 updated this revision to Diff 328227.Mar 4 2021, 10:15 AM

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

nickdesaulniers accepted this revision.Mar 4 2021, 10:16 AM
This revision is now accepted and ready to land.Mar 4 2021, 10:16 AM

thanks, this is much needed documentation.

MaskRay updated this revision to Diff 331738.Thu, Mar 18, 6:07 PM
MaskRay retitled this revision from [Driver] Clarify --gcc-toolchain to [docs] Improve documentation of -B and --gcc-toolchain.

Rebase on D97993

MaskRay marked 3 inline comments as done.Thu, Mar 18, 6:08 PM
nickdesaulniers accepted this revision.Thu, Mar 18, 6:45 PM
This revision was automatically updated to reflect the committed changes.