Leave some notes

projects/bazelshim/src/bazelshim/__main__.py

@@ -1,10 +1,31 @@
 #!/usr/bin/env python3
 
-# A Bazel wrapper
+"""
-#
+A Bazel wrapper
-# This script exists to allow for the setting of environment viariables and other context flags to
+===============
-# Bazel on behalf of the user. Consequently it has some magical (partial) knowledge of Bazel's CLI
+
-# options since it's really a CLI shim.
+This script exists to allow for the setting of environment viariables and other context flags to
+Bazel on behalf of the user. Consequently it has some magical (partial) knowledge of Bazel's CLI
+options since it's really a CLI shim. This allows for user(s) to define their own Bazel CLI
+middleware machinery while using structured and testable parsing rather than BASH nonsense.
+
+It's important that this script stands "alone" because it needs to be usable mostly in isolation
+with a non-hermetic interpreter before we can do Bazel builds.
+
+For instance this script could be used as a basis to define custom Bazel tasks such as 'repl' (run
+with some magic) or 'watch' as an alias for punting to ibazel/bazel-watcher.
+
+Such a middleware can also be used to provide configurations which are hard to autodetect from
+within Bazel in an appropriately structured way such as
+  `--action_env=GLIBC_VERSION=$(ldd --version)`
+or
+  `--action_env=PLATFORM_FEATURE_POSTGRESQL=$(which pg_ctl >/dev/null 2>&1 && echo 'true' || echo 'false')`
+
+I suggest using a `bazel` and maybe `bazelisk` shim script on your $PATH like
+  exec "${SOURCE}/projects/bazelshim/src/bazelshim/__main__.py" \
+    --bazelshim_exclude="$(dirname $(realpath $0))" \
+    "$@"
+"""
 
 # Since this can't run under Bazel, we have to set up the sys.path ourselves
 import os
@@ -15,6 +36,7 @@ if (p := str(Path(sys.argv[0]).absolute().parent.parent)) not in sys.path:
     sys.path.pop(0)  # Remove '.' / ''
     sys.path.insert(0, p)  # Insert the bazelshim root
 
+# Now that's out of the way...
 from dataclasses import dataclass
 from shlex import quote, split as shlex
 import sys
@@ -23,6 +45,7 @@ from typing import List, Optional
 from itertools import chain
 
 
+# FIXME: Allow user-defined extensions here
 VERBS = [
     "aquery",
     "build",
@@ -187,6 +210,7 @@ class BazelCli:
         return "\\\n".join(lines)
 
 
+# FIXME: Use some sort of plugin model here to implement interceptors
 def middleware(cli):
     return cli