From a9d0665bbba528efcce56333a9a58d18ffb3a108 Mon Sep 17 00:00:00 2001
From: Ed Maste <emaste@FreeBSD.org>
Date: Wed, 5 Apr 2023 11:21:26 -0400
Subject: [PATCH] src.conf.5: Expand WITH_LLVM_BINUTILS description

List the specific tools that are controlled by WITH_LLVM_BINUTILS, and
mention the tools that are always or never taken from LLVM.  Tools come
from one of three sources (LLVM, ELF Tool Chain, bespoke base system)
and it is useful to be explicit.

Reviewed by:	markj
Sponsored by:	The FreeBSD Foundation
Differential Revision: https://reviews.freebsd.org/D39428
---
 share/man/man5/src.conf.5              | 19 ++++++++++++++++++-
 tools/build/options/WITH_LLVM_BINUTILS | 19 ++++++++++++++++++-
 2 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/share/man/man5/src.conf.5 b/share/man/man5/src.conf.5
index 565d551c849..ff287a5b017 100644
--- a/share/man/man5/src.conf.5
+++ b/share/man/man5/src.conf.5
@@ -906,7 +906,24 @@ some other way.
 .It Va WITHOUT_LLVM_ASSERTIONS
 Disable debugging assertions in LLVM.
 .It Va WITH_LLVM_BINUTILS
-Install LLVM's binutils (ar, addr2line, nm, etc.) instead of ELF Tool Chain's.
+Install LLVM's binutils (without an llvm- prefix),
+instead of ELF Tool Chain's tools.
+This includes
+.Xr addr2line 1 ,
+.Xr ar 1 ,
+.Xr nm 1 ,
+.Xr objcopy 1 ,
+.Xr ranlib 1 ,
+.Xr readelf 1 ,
+.Xr size 1 ,
+and
+.Xr strip 1 .
+Regardless of this setting, LLVM tools are used for
+.Xr c++filt 1
+and
+.Xr objdump 1 .
+.Xr strings 1
+is always provided by ELF Tool Chain.
 .It Va WITHOUT_LLVM_COV
 Do not build the
 .Xr llvm-cov 1
diff --git a/tools/build/options/WITH_LLVM_BINUTILS b/tools/build/options/WITH_LLVM_BINUTILS
index 8fa2c55f31a..f60b1ebac0e 100644
--- a/tools/build/options/WITH_LLVM_BINUTILS
+++ b/tools/build/options/WITH_LLVM_BINUTILS
@@ -1,2 +1,19 @@
 .\" $FreeBSD$
-Install LLVM's binutils (ar, addr2line, nm, etc.) instead of ELF Tool Chain's.
+Install LLVM's binutils (without an llvm- prefix),
+instead of ELF Tool Chain's tools.
+This includes
+.Xr addr2line 1 ,
+.Xr ar 1 ,
+.Xr nm 1 ,
+.Xr objcopy 1 ,
+.Xr ranlib 1 ,
+.Xr readelf 1 ,
+.Xr size 1 ,
+and
+.Xr strip 1 .
+Regardless of this setting, LLVM tools are used for
+.Xr c++filt 1
+and
+.Xr objdump 1 .
+.Xr strings 1
+is always provided by ELF Tool Chain.