From 51e1817dec9980d0d204a051fc3c4dc981c3d027 Mon Sep 17 00:00:00 2001
From: Tom Smeding <tomsmeding@users.noreply.github.com>
Date: Sat, 26 Apr 2025 22:37:58 +0200
Subject: [PATCH] Clarify splitting/passing behaviour for --*-option(s)
arguments (#10792)
* Clarify splitting/passing behaviour for --*-option(s) arguments
* Further clarify precise quote parsing behaviour of --*-options options
* Use OPTS, not FLAG, for --repl-options
* Fix typo
* Fix formatting
* Use clearer notation for single and double quotes in docs
This handles geekosaur's review.
* Minor wording change in docs
Co-authored-by: brandon s allbery kf8nh <allbery.b@gmail.com>
---------
Co-authored-by: brandon s allbery kf8nh <allbery.b@gmail.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
---
.../Distribution/Simple/Setup/Benchmark.hs | 5 ++--
Cabal/src/Distribution/Simple/Setup/Common.hs | 9 ++++--
Cabal/src/Distribution/Simple/Setup/Test.hs | 5 ++--
doc/cabal-commands.rst | 14 ++++++----
doc/setup-commands.rst | 28 +++++++++++++------
5 files changed, 42 insertions(+), 19 deletions(-)
diff --git a/Cabal/src/Distribution/Simple/Setup/Benchmark.hs b/Cabal/src/Distribution/Simple/Setup/Benchmark.hs
index f33e374c15..79dfe88e79 100644
--- a/Cabal/src/Distribution/Simple/Setup/Benchmark.hs
+++ b/Cabal/src/Distribution/Simple/Setup/Benchmark.hs
@@ -118,7 +118,8 @@ benchmarkOptions' showOrParseArgs =
[]
["benchmark-options"]
( "give extra options to benchmark executables "
- ++ "(name templates can use $pkgid, $compiler, "
+ ++ "(split on spaces, use \"\" to prevent splitting; "
+ ++ "name templates can use $pkgid, $compiler, "
++ "$os, $arch, $benchmark)"
)
benchmarkOptions
@@ -132,7 +133,7 @@ benchmarkOptions' showOrParseArgs =
[]
["benchmark-option"]
( "give extra option to benchmark executables "
- ++ "(no need to quote options containing spaces, "
+ ++ "(passed directly as a single argument; "
++ "name template can use $pkgid, $compiler, "
++ "$os, $arch, $benchmark)"
)
diff --git a/Cabal/src/Distribution/Simple/Setup/Common.hs b/Cabal/src/Distribution/Simple/Setup/Common.hs
index 8b700841ad..1a7e6691ba 100644
--- a/Cabal/src/Distribution/Simple/Setup/Common.hs
+++ b/Cabal/src/Distribution/Simple/Setup/Common.hs
@@ -275,7 +275,9 @@ programDbOption progDb showOrParseArgs get set =
[prog ++ "-option"]
( "give an extra option to "
++ prog
- ++ " (no need to quote options containing spaces)"
+ ++ " (passed directly to "
+ ++ prog
+ ++ " as a single argument)"
)
get
set
@@ -312,7 +314,10 @@ programDbOptions progDb showOrParseArgs get set =
option
""
[prog ++ "-options"]
- ("give extra options to " ++ prog)
+ ( "give extra options to "
+ ++ prog
+ ++ " (split on spaces, use \"\" to prevent splitting)"
+ )
get
set
(reqArg' "OPTS" (\args -> [(prog, splitArgs args)]) (const []))
diff --git a/Cabal/src/Distribution/Simple/Setup/Test.hs b/Cabal/src/Distribution/Simple/Setup/Test.hs
index 6e5da7d764..9c65097c35 100644
--- a/Cabal/src/Distribution/Simple/Setup/Test.hs
+++ b/Cabal/src/Distribution/Simple/Setup/Test.hs
@@ -245,7 +245,8 @@ testOptions' showOrParseArgs =
[]
["test-options"]
( "give extra options to test executables "
- ++ "(name templates can use $pkgid, $compiler, "
+ ++ "(split on spaces, use \"\" to prevent splitting; "
+ ++ "name templates can use $pkgid, $compiler, "
++ "$os, $arch, $test-suite)"
)
testOptions
@@ -259,7 +260,7 @@ testOptions' showOrParseArgs =
[]
["test-option"]
( "give extra option to test executables "
- ++ "(no need to quote options containing spaces, "
+ ++ "(passed directly as a single argument; "
++ "name template can use $pkgid, $compiler, "
++ "$os, $arch, $test-suite)"
)
diff --git a/doc/cabal-commands.rst b/doc/cabal-commands.rst
index 7f0b37ac48..22f1a9089a 100644
--- a/doc/cabal-commands.rst
+++ b/doc/cabal-commands.rst
@@ -1060,13 +1060,17 @@ Examples:
Configuration flags can be specified on the command line and these extend the project
configuration from the 'cabal.project', 'cabal.project.local' and other files.
-.. option:: --repl-options=FLAG
+.. option:: --repl-options=OPTS
To avoid ``ghci``-specific flags from triggering unneeded global rebuilds, these
- flags are stripped from the internal configuration. As a result,
- ``--ghc-options`` will no longer (reliably) work to pass flags to ``ghci`` (or
- other REPLs). Instead, you should use the ``--repl-options`` flag to
- specify these options to the invoked REPL.
+ flags are stripped from the internal configuration when using
+ ``--ghc-option`` or ``--ghc-options``. As a result, ``--ghc-options`` will
+ not (reliably) work to pass flags to ``ghci`` (or other REPLs).
+ ``--repl-options`` bypasses this and allows you to specify options to the
+ invoked REPL without influencing the build configuration for other packages.
+
+ Note: ``--repl-options`` does not accept double quotes (``""``) to pass options
+ containing spaces to the REPL.
.. option:: --repl-no-load
diff --git a/doc/setup-commands.rst b/doc/setup-commands.rst
index 0807ddf2aa..970439e748 100644
--- a/doc/setup-commands.rst
+++ b/doc/setup-commands.rst
@@ -210,19 +210,31 @@ files of a package:
to Cabal can be used in place of *prog*. For example:
``--alex-options="--template=mytemplatedir/"``. The *options* is
split into program options based on spaces. Any options containing
- embedded spaced need to be quoted, for example
- ``--foo-options='--bar="C:\Program File\Bar"'``. As an alternative
- that takes only one option at a time but avoids the need to quote,
- use :option:`--PROG-option` instead.
+ embedded spaces need to be quoted with double quotes (``""``), for example
+ ``--foo-options='--bar="C:\Program Files\Bar"'``. (The single quotes
+ (``''``) are for your shell, the ``"double"`` quotes are passed to Cabal.)
+ For an alternative that takes only one option at a time but avoids the need
+ to quote, use :option:`--PROG-option` instead.
+
+ Note: if *prog* is ``ghc``, then options that do not affect build
+ artifacts, such as warning flags, are dropped. This is because
+ ``--ghc-options`` applies to GHC for the entire build plan, not just the
+ current package, and recompiling the entire dependency tree is probably
+ unintended. If you want to apply some options to ``cabal repl`` only, pass
+ ``--repl-options`` to ``cabal repl``.
.. option:: --PROG-option=OPT
- Specify a single additional option to the program *prog*. For
+ Specify a single additional option to the program *prog*. The option is
+ passed to *prog* as a single argument, without any splitting. For
passing an option that contains embedded spaces, such as a file name
with embedded spaces, using this rather than :option:`--PROG-options`
means you do not need an additional level of quoting. Of course if you
are using a command shell you may still need to quote, for example
- ``--foo-options="--bar=C:\Program File\Bar"``.
+ ``--foo-options="--bar=C:\Program Files\Bar"``.
+
+ The same note regarding dropping flags as for :option:`--PROG-options`
+ applies to ``--PROG-option`` as well.
All of the options passed with either :option:`--PROG-options`
or :option:`--PROG-option` are passed in the order they were
@@ -1443,11 +1455,11 @@ Flags for repl:
.. option:: --PROG-option=OPT
- Give an extra option to PROG (no need to quote options containing spaces).
+ Give an extra option to PROG (passed directly to PROG as a single argument).
.. option:: --PROG-options=OPTS
- Give extra options to PROG.
+ Give extra options to PROG (split on spaces, use "" to prevent splitting).
.. option:: --repl-no-load
--
GitLab