10 files changed, 43 insertions, 11 deletions

diff --git a/tools/build/options/WITHOUT_BINUTILS b/tools/build/options/WITHOUT_BINUTILS
index 62a614e94d0e..5270bd7fd851 100644
--- a/tools/build/options/WITHOUT_BINUTILS
+++ b/tools/build/options/WITHOUT_BINUTILS
@@ -1,7 +1,7 @@
 .\" $FreeBSD$
-Set to not install binutils (as, c++-filt, gconv,
-ld, nm, objcopy, objdump, readelf, size and strip).
-.Bf -symbolic
-The option does not generally work for build targets, unless some alternative
-toolchain is enabled.
-.Ef
+Set to not build or install binutils (as, c++-filt, gconv,
+ld, nm, objcopy, objdump, readelf, size and strip) as part
+of the normal system build.
+The resulting system cannot build programs from source.
+
+
diff --git a/tools/build/options/WITHOUT_BINUTILS_BOOTSTRAP b/tools/build/options/WITHOUT_BINUTILS_BOOTSTRAP
new file mode 100644
index 000000000000..84ae1a1706f2
--- /dev/null
+++ b/tools/build/options/WITHOUT_BINUTILS_BOOTSTRAP
@@ -0,0 +1,8 @@
+.\" $FreeBSD$
+Set to not build binutils (as, c++-filt, gconv,
+ld, nm, objcopy, objdump, readelf, size and strip)
+as part of the bootstrap process.
+.Bf -symbolic
+The option does not work for build targets unless some alternative
+toolchain is provided.
+.Ef
diff --git a/tools/build/options/WITHOUT_CLANG b/tools/build/options/WITHOUT_CLANG
index 62a90bab215e..51c9c514e68b 100644
--- a/tools/build/options/WITHOUT_CLANG
+++ b/tools/build/options/WITHOUT_CLANG
@@ -1,2 +1,2 @@
 .\" $FreeBSD$
-Set to not build the Clang C/C++ compiler.
+Set to not build the Clang C/C++ compiler during the regular phase of the build.
diff --git a/tools/build/options/WITHOUT_CLANG_BOOTSTRAP b/tools/build/options/WITHOUT_CLANG_BOOTSTRAP
new file mode 100644
index 000000000000..a22046d19248
--- /dev/null
+++ b/tools/build/options/WITHOUT_CLANG_BOOTSTRAP
@@ -0,0 +1,5 @@
+.\" $FreeBSD$
+Set to not build the Clang C/C++ compiler during the bootstrap phase of the build.
+You must enable wither gcc or clang bootstrap to be able to build the system,
+unless an alternative compiiler is provided via
+XCC.
diff --git a/tools/build/options/WITHOUT_CROSS_COMPILER b/tools/build/options/WITHOUT_CROSS_COMPILER
index 1ded25b06573..ab1bd235bb05 100644
--- a/tools/build/options/WITHOUT_CROSS_COMPILER
+++ b/tools/build/options/WITHOUT_CROSS_COMPILER
@@ -1,3 +1,13 @@
 .\" $FreeBSD$
-Set to not build a cross compiler in the cross-tools stage of
-buildworld, buildkernel, etc.
+Set to not build any cross compiler in the cross-tools stage of buildworld.
+If you are compiling a different version of
+.Fx 
+than what is installed on the system, you will need to provide an alternate
+compiler with XCC to ensure success.
+If you are compiling with an identical version of
+.Fx 
+to the host, this option may be safely used.
+This option may also be safe when the host version of
+.Fx 
+is close to the sources being built, but all bets are off if there have
+been any changes to the toolchain between the versions.
diff --git a/tools/build/options/WITHOUT_GCC b/tools/build/options/WITHOUT_GCC
index 7bb21f8b8375..c746d16dc076 100644
--- a/tools/build/options/WITHOUT_GCC
+++ b/tools/build/options/WITHOUT_GCC
@@ -1,2 +1,2 @@
 .\" $FreeBSD$
-Set to not build and install gcc and g++.
+Set to not build and install gcc and g++ as part of the normal build process.
diff --git a/tools/build/options/WITHOUT_GCC_BOOTSTRAP b/tools/build/options/WITHOUT_GCC_BOOTSTRAP
new file mode 100644
index 000000000000..668ff14496a0
--- /dev/null
+++ b/tools/build/options/WITHOUT_GCC_BOOTSTRAP
@@ -0,0 +1,5 @@
+.\" $FreeBSD$
+Set to not build gcc and g++ as part of the bootstrap process.
+You must enable wither gcc or clang bootstrap to be able to build the system,
+unless an alternative compiiler is provided via
+XCC.
diff --git a/tools/build/options/WITH_CLANG b/tools/build/options/WITH_CLANG
index b0e300a488b1..0174b4db4e38 100644
--- a/tools/build/options/WITH_CLANG
+++ b/tools/build/options/WITH_CLANG
@@ -1,2 +1,2 @@
 .\" $FreeBSD$
-Set to build the Clang C/C++ compiler.
+Set to build the Clang C/C++ compiler during the normal phase of the build.
diff --git a/tools/build/options/WITH_CLANG_BOOTSTRAP b/tools/build/options/WITH_CLANG_BOOTSTRAP
new file mode 100644
index 000000000000..792512d57e93
--- /dev/null
+++ b/tools/build/options/WITH_CLANG_BOOTSTRAP
@@ -0,0 +1,2 @@
+.\" $FreeBSD$
+Set to build the Clang C/C++ compiler during the bootstrap phase of the build.
diff --git a/tools/build/options/WITH_GCC_BOOTSTRAP b/tools/build/options/WITH_GCC_BOOTSTRAP
new file mode 100644
index 000000000000..8e04b11fb483
--- /dev/null
+++ b/tools/build/options/WITH_GCC_BOOTSTRAP
@@ -0,0 +1,2 @@
+.\" $FreeBSD$
+Set to build gcc and g++ as part of the bootstrap process.