[lmi-commits] [lmi] odd/multiarch e95d62e 02/10: Improve documentation

[Greg Chicares]

branch: odd/multiarch
commit e95d62eee8cf0b48f70de718fef3e6fd2ae01df8
Author: Gregory W. Chicares <address@hidden>
Commit: Gregory W. Chicares <address@hidden>

    Improve documentation
---
 set_arch.sh | 36 +++++++++++++++++++++++-------------
 1 file changed, 23 insertions(+), 13 deletions(-)

diff --git a/set_arch.sh b/set_arch.sh
index f9707b5..eabb9b6 100755
--- a/set_arch.sh
+++ b/set_arch.sh
@@ -1,6 +1,6 @@
 #!/bin/sh this-script-must-be-sourced-not-run
 
-# Set $PATH, $WINEPATH, and $PERFORM based on $LMI_HOST. [revise this]
+# Set $PATH, $WINEPATH, and $PERFORM based on $LMI_COMPILER and $LMI_TRIPLET.
 
 # Copyright (C) 2019 Gregory W. Chicares.
 #
@@ -21,17 +21,18 @@
 # email: <address@hidden>
 # snail: Chicares, 186 Belle Woods Drive, Glastonbury CT 06033, USA
 
-# What about "$mingw_bin_dir"?
-
 # Invoke as ". ./set_arch.sh" without the quotes.
 #
-# $LMI_HOST can be overridden at the command line, e.g.:
-#   LMI_HOST="whatever" . ./set_arch.sh
-# That command doesn't alter the value of $LMI_HOST in the environment
-# because there's an obvious alternative that does so:
-#   LMI_HOST="whatever"; . ./set_arch.sh
+# $LMI_COMPILER and $LMI_TRIPLET can be overridden at the command
+# line, e.g.:
+#
+#   export LMI_COMPILER
+#   export LMI_TRIPLET
+#   LMI_COMPILER=gcc ; LMI_TRIPLET=i686-w64-mingw32 ; . ./set_arch.sh
+#   LMI_COMPILER=gcc ; LMI_TRIPLET=x86_64-w64-mingw32 ; . ./set_arch.sh
 #
-# Perhaps $prefix should be similarly overridable.
+# where the 'export' commands need be run only once, presumably in a
+# shell startup file.
 #
 # Implemented as a function that runs and then erases itself, so that
 # sourcing this script changes the environment only as intended. This
@@ -42,10 +43,19 @@
 # it's used here, and its 'shellcheck' warning is disabled:
 # shellcheck disable=SC2039
 
+# Unimplemented alternative: Variables such as $prefix could be made
+# similarly overridable, along with other directories--perhaps even
+# platform-specific ones like $mingw_bin_dir.
+
 # Unimplemented alternative: use symlinks, e.g:
-#   ln --symbolic --force --no-dereference 
/opt/lmi/"${LMI_COMPILER}_${LMI_TRIPLET}"/bin /opt/lmi/bin
-# and likewise for /opt/lmi/local etc.
+#   ln --symbolic --force --no-dereference \
+#   /opt/lmi/"${LMI_COMPILER}_${LMI_TRIPLET}"/bin /opt/lmi/bin
+# and likewise for all other directories. Depending on symlinks
+# didn't seem like a good idea.
 
+# This alternative for future consideration trades some complexity of
+# implementation for mitigation of confusion and convenience of use.
+#
 # To cross-build autotoolized libraries, configure with:
 #   --host=$LMI_TRIPLET
 #   --exec_prefix=$prefix/$LMI_TOOLCHAIN
@@ -70,7 +80,7 @@
 #   https://wiki.debian.org/Multiarch/Tuples#Why_not_use_GNU_triplets.3F
 # The main reason for lmi to establish its own is that the official
 # triplets for msw are so poor. For example, "i686-w64-mingw32" has
-# substrings "64" and "32". Both seem to suggest the CPU's word size
+# substrings "64" and "32". Both seem to specify the CPU's word size
 # (contradicting each other), but actually neither does--the word size
 # is determined by the "i686" field. See:
 #   https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=622276
@@ -91,7 +101,7 @@ local  winebindir="$prefix"/third_party/bin
 # would cause $PATH to grow without bound, and the result would be
 # unreliable because setting paths for "i686..." and then, due to
 # mistyping, to "x64_86" would find 32-bit binaries where 64-bit
-# binaries were wanted.
+# binaries were hoped for.
 #
 # The default non-lmi portion of this $PATH is, as always, debatable;
 # debian's default in '/etc/login.defs' adds silly 'games' directories