From cd663495573dff2bcf2889e6971a859f818b190f Mon Sep 17 00:00:00 2001
From: Mel Zuser <mel@mzero.dev>
Date: Tue, 7 Dec 2021 12:20:10 -0500
Subject: [PATCH] Update documentation for better script support

Ready for review: #7851
May close: #7842, #6354, #6149
---
 .../src/Distribution/Client/ScriptUtils.hs    |  6 ++---
 doc/cabal-commands.rst                        | 25 +++++++++++++++++++
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/cabal-install/src/Distribution/Client/ScriptUtils.hs b/cabal-install/src/Distribution/Client/ScriptUtils.hs
index c18bc60ce85..314358886cd 100644
--- a/cabal-install/src/Distribution/Client/ScriptUtils.hs
+++ b/cabal-install/src/Distribution/Client/ScriptUtils.hs
@@ -93,7 +93,7 @@ import System.FilePath
 
 -- | Get the directory where script builds are cached.
 --
--- <cabalDir>/script-builds
+-- CABAL_DIR\/script-builds\/
 getScriptCacheDirectoryRoot :: IO FilePath
 getScriptCacheDirectoryRoot = do
   cabalDir <- getCabalDir
@@ -106,14 +106,14 @@ getScriptHash prefix script = showHashValue . hashValue . fromString . (prefix +
 -- | Get the directory for caching a script build.
 --
 -- The only identity of a script is it's absolute path, so append the
--- hashed path to <cabalDir>/script-builds/ to get the cache directory.
+-- hashed path to CABAL_DIR\/script-builds\/ to get the cache directory.
 getScriptCacheDirectory :: String -> FilePath -> IO FilePath
 getScriptCacheDirectory prefix script = (</>) <$> getScriptCacheDirectoryRoot <*> getScriptHash prefix script
 
 -- | Get the directory for caching a script build and ensure it exists.
 --
 -- The only identity of a script is it's absolute path, so append the
--- hashed path to <cabalDir>/script-builds/ to get the cache directory.
+-- hashed path to CABAL_DIR\/script-builds\/ to get the cache directory.
 ensureScriptCacheDirectory :: Verbosity -> String -> FilePath -> IO FilePath
 ensureScriptCacheDirectory verbosity prefix script = do
   cacheDir <- getScriptCacheDirectory prefix script
diff --git a/doc/cabal-commands.rst b/doc/cabal-commands.rst
index 250a2bfa04e..d9e0d0e52f9 100644
--- a/doc/cabal-commands.rst
+++ b/doc/cabal-commands.rst
@@ -236,6 +236,10 @@ A cabal command target can take any of the following forms:
 -  A filepath target: ``[package:][ctype:]filepath``, which specifies that the
    component of which the given filepath is a part of will be built.
 
+-  A script target: ``path/to/script``, which specifies the path to a script
+   file. This is supported by ``build``, ``repl``, ``run``, and ``clean``.
+   Script targets are not part of a package.
+
 cabal v2-build
 ---------------
 
@@ -262,6 +266,7 @@ Some example targets:
                                        # "app/Main.hs"
     $ cabal v2-build Lib               # build the library component to
                                        # which the module "Lib" belongs
+    $ cabal v2-build path/to/script    # build the script as an executable
 
 Beyond a list of targets, ``cabal v2-build`` accepts all the flags that
 ``cabal v2-configure`` takes. Most of these flags are only taken into
@@ -270,6 +275,9 @@ cause extra store packages to be built (for example,
 ``--enable-profiling`` will automatically make sure profiling libraries
 for all transitive dependencies are built and installed.)
 
+When building a script, the executable is cached under the cabal directory.
+See ``cabal v2-run`` for more information on the format for scripts.
+
 In addition ``cabal v2-build`` accepts these flags:
 
 - ``--only-configure``: When given we will forego performing a full build and
@@ -323,6 +331,17 @@ cannot be excluded for technical reasons).
 
     $ cabal v2-repl --build-depends vector --no-transitive-deps
 
+Scripts can be passing the path to the script as the target.
+
+::
+
+    $ cabal v2-repl script.hs
+
+If the name of the script matches another target, the other target is preferred.
+To load the script instead pass it as an explicit path: ./script.hs
+
+See ``cabal v2-run`` for more information on the format for scripts.
+
 cabal v2-run
 -------------
 
@@ -543,6 +562,12 @@ and caches if the ``--save-config`` option is given, in which case it only remov
 the build artefacts (``.hi``, ``.o`` along with any other temporary files generated
 by the compiler, along with the build output).
 
+``cabal v2-clean [FLAGS] path/to/script`` cleans up the temporary files and build
+artifacts for the script, which are stored under the .cabal/script-builds directory.
+
+In addition when clean is invoked it will remove all script build artifacts for
+which the corresponding script no longer exists.
+
 cabal v2-sdist
 ---------------