Re #6540 Document stack-shim-<hash>.hs online

mpilgrem · mpilgrem · commit a4ec6adef3d6 · 2024-03-30T20:12:03.000Z
diff --git a/doc/stack_root.md b/doc/stack_root.md
@@ -221,6 +221,23 @@ that Stack uses to build the executable.
 If the contents of the directory are deleted, and Stack needs the executable,
 Stack will recreate them.
 
+The hash in the names of the source files is a hash of arguments passed to GHC
+when building the executable and the contents of the two source files.
+
+The content of the `setup-<hash>.hs` file is the familiar:
+
+~~~haskell
+import Distribution.Simple
+main = defaultMain
+~~~
+
+The content of the `setup-shim-<hash>.hs` file uses `main` except when the
+executable is called with arguments `repl` and `stack-initial-build-steps`. Then
+Stack makes use of Cabal's `defaultMainWithHooks` and `replHook` field to create
+the autogenerated files for every configured component; the `replHook` function
+is provided with the information that `initialBuildSteps` needs. Stack's
+`stack ghci` or `stack repl` commands call the executable with those arguments.
+
 ### `snapshots` directory
 
 This contains a directory for each snapshot that Stack creates when building
