Give classgraph-plugin-flag.sh a real --help

The previous -h/--help ran a sed that quit at the first lone '#' (line 2),
so it printed nothing. Replace it with a usage() that documents every option
(--dir, --cabal, --package, -h/--help), the CLASSGRAPH_SO env var, the
stdout/stderr split, .so discovery + re-run caveat, and examples. Unknown
args now report to stderr with a '--help' hint and exit 2.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

diff --git a/classgraph-plugin-flag.sh b/classgraph-plugin-flag.sh
index 7dee35e63a05fbab8fcf9a63726a63cf9cd453db..68f182f00c1d4e8ee50af0a5c7b7be4ec771f03a 100755 (executable)
--- a/classgraph-plugin-flag.sh
+++ b/classgraph-plugin-flag.sh
@@ -33,6 +33,51 @@ set -euo pipefail
 
 cd "$(dirname "$(readlink -f "$0")")"
 
+PROG=${0##*/}
+
+usage() {
+  cat <<EOF
+$PROG — print a -fplugin-library= flag (or cabal stanza) that lets a
+downstream package load the classgraph GHC plugin WITHOUT adding classgraph
+to its build-depends, so the plugin's dependency bounds don't leak into the
+consumer's build plan.
+
+Usage:
+  $PROG [--dir DIR] [--cabal [--package PKG]]
+  $PROG -h | --help
+
+Options:
+  --dir DIR       Directory the plugin writes its per-module JSON dumps to
+                  (emitted as the plugin option dir=DIR). Relative to the
+                  consumer package's build cwd. Default: .classgraph
+  --cabal         Emit a ready-to-append cabal.project(.local) stanza instead
+                  of the bare flag. Without --package this is a global
+                  'program-options' block (applies to every package); with
+                  --package it is a 'package PKG' block.
+  --package PKG   Scope the --cabal stanza to the single package PKG. Only
+                  meaningful together with --cabal.
+  -h, --help      Show this help and exit.
+
+Environment:
+  CLASSGRAPH_SO   Absolute path to the plugin .so to use, bypassing discovery
+                  entirely (and the chooser prompt below).
+
+Output goes to stdout; any prompts/diagnostics go to stderr, so the result is
+safe to redirect (e.g. '$PROG --cabal >> cabal.project.local').
+
+The plugin .so is discovered from ./dist-newstyle and the cabal store. If
+more than one candidate is found you are prompted to pick one. Re-run this
+script after rebuilding classgraph itself — the package id baked into the .so
+path changes on each build.
+
+Examples:
+  $PROG                                   # bare flag, dumps to ./.classgraph
+  $PROG --dir build/classgraph            # bare flag, custom output dir
+  $PROG --cabal >> cabal.project.local    # global stanza, appended
+  $PROG --cabal --package ouroboros-consensus
+EOF
+}
+
 DIR=.classgraph
 EMIT=raw      # raw | cabal
 PACKAGE=
@@ -41,10 +86,11 @@ while [ $# -gt 0 ]; do
     --dir)     DIR=$2; shift 2 ;;
     --cabal)   EMIT=cabal; shift ;;
     --package) PACKAGE=$2; shift 2 ;;
-    -h|--help)
-      sed -n '/^#$/q;/^# /{s/^# \?//;p;}' "$0"
-      exit 0 ;;
-    *) echo "unknown argument: $1" >&2; exit 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *)
+      echo "$PROG: unknown argument: $1" >&2
+      echo "Try '$PROG --help'." >&2
+      exit 2 ;;
   esac
 done