diff --git a/Cabal/src/Distribution/Simple/Setup/Benchmark.hs b/Cabal/src/Distribution/Simple/Setup/Benchmark.hs index f33e374c15d28540bfc7654bccde3cb65be568df..79dfe88e79f86882de94378caf835bbff6c22331 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 8b700841ad11758eca09b2db9f34072bd6a1ad7c..1a7e6691bab01554c1ea00a5698c41210eb0a30d 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 6e5da7d7643744984e047cae055d640b7ae6c718..9c65097c3546d0fa46f484416bba8c0f0164fd9f 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 7f0b37ac48f3564ccad33bd499d40b49fcf2f97b..22f1a9089a6a2a9ab865f9f28e5bd942cdb99232 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 0807ddf2aa47f02745db036dc49549a98f0465d6..970439e748de7c1edd31b06113a4f518f1cfa5de 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