Clarify documentation regarding multi-arch support

1 files changed, 29 insertions, 11 deletions

diff --git a/doc/manual.cli b/doc/manual.cli
index 9a3b41f..557f652 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -153,21 +153,26 @@ Some examples of complete machine names:
 windows_10-msvc_14u3
 macos_10.12-clang_10.0
 linux_ubuntu_16.04-gcc_6.3
+aarch64_linux_debian_11-gcc_12.2
 \
 
 Similarly, the build configuration is encoded in a \i{configuration name}
-using the same format. As described in \l{#arch-controller Controller Logic},
-build configurations are generated from machine configurations. As a result,
-it usually makes sense to have the first component identify the operating
-systems and the second component \- the toolchain with the rest identifying a
-particular build configuration variant, for example, optimized, sanitized,
-etc. For example:
+using the same overall format. As described in \l{#arch-controller Controller
+Logic}, build configurations are generated from machine configurations. As a
+result, it usually makes sense to have the first component identify the
+operating systems and the second component \- the toolchain with the rest
+identifying a particular build configuration variant, for example, optimized,
+sanitized, etc. For example:
 
 \
 windows-vc_14-O2
 linux-gcc_6-O3_asan
 \
 
+While we can also specify the \c{<arch>} component in a build configuration,
+this information is best conveyed as part of \c{<target>} as described in
+\l{#arch-controller Controller Logic}.
+
 \h#arch-machine-header|Machine Header Manifest|
 
 @@ TODO: need ref to general manifest overview in bpkg, or, better yet,
@@ -1687,18 +1692,31 @@ testing its packages with this machine). If multiple machines match the same
 pattern, then only a single configuration using any of the machines is
 produced (meaning that this controller considers these machines equivalent).
 
-As an example, let's say we have a machine named \c{windows_10-vc_14u3}. If we
+As an example, let's say we have a machine named \c{windows_10-vc_14.3}. If we
 wanted to test both 32 and 64-bit as well as debug and optimized builds, then
 we could have generated the following configurations:
 
 \
-windows*-msvc_14* windows-msvc_14-32-Z7 i686-microsoft-win32-msvc14.0 \"all default msvc i686 debug\" config.cc.coptions=/Z7 config.cc.loptions=/DEBUG ~\"warning C4\d{3}: \"
+windows*-msvc_14* windows-msvc_14-Z7 i686-microsoft-win32-msvc14.0 \"all default msvc i686 debug\" config.cc.coptions=/Z7 config.cc.loptions=/DEBUG ~\"warning C4\d{3}: \"
+
+windows*-msvc_14* windows-msvc_14-O2 i686-microsoft-win32-msvc14.0 \"all default msvc i686 optimized\" config.cc.coptions=/O2 ~\"warning C4\d{3}: \"
+
+windows*-msvc_14* windows-msvc_14-Z7 x86_64-microsoft-win32-msvc14.0 \"all default msvc x86_64 debug\" config.cc.coptions=/Z7 config.cc.loptions=/DEBUG ~\"warning C4\d{3}: \"
+
+windows*-msvc_14* windows-msvc_14-O2 x86_64-microsoft-win32-msvc14.0 \"all default msvc x86_64 optimized\" config.cc.coptions=/O2 ~\"warning C4\d{3}: \"
+\
 
-windows*-msvc_14* windows-msvc_14-32-O2 i686-microsoft-win32-msvc14.0 \"all default msvc i686 optimized\" config.cc.coptions=/O2 ~\"warning C4\d{3}: \"
+In the above example we could handle both \c{i686} and \c{x86_64}
+architectures with the same machine but this may not always be possible
+and we may have to use different machines for different configuration/target
+combinations. For example:
+
+\
+x86_64_linux_debian_11*-gcc_12.2  linux_debian_11-gcc_12.2 i686-linux-gnu   ...
 
-windows*-msvc_14* windows-msvc_14-64-Z7 x86_64-microsoft-win32-msvc14.0 \"all default msvc x86_64 debug\" config.cc.coptions=/Z7 config.cc.loptions=/DEBUG ~\"warning C4\d{3}: \"
+x86_64_linux_debian_11*-gcc_12.2  linux_debian_11-gcc_12.2 x86_64-linux-gnu ...
 
-windows*-msvc_14* windows-msvc_14-64-O2 x86_64-microsoft-win32-msvc14.0 \"all default msvc x86_64 optimized\" config.cc.coptions=/O2 ~\"warning C4\d{3}: \"
+aarch64_linux_debian_11*-gcc_12.2 linux_debian_11-gcc_12.2 aarch64-linux-gnu ...
 \
 
 As another example, let's say we have \c{linux_fedora_25-gcc_6} and