diff --git a/Cabal/src/Distribution/GetOpt.hs b/Cabal/src/Distribution/GetOpt.hs index 25c980a28ba..a6b5f71e5d7 100644 --- a/Cabal/src/Distribution/GetOpt.hs +++ b/Cabal/src/Distribution/GetOpt.hs @@ -38,6 +38,8 @@ module Distribution.GetOpt import Distribution.Compat.Prelude import Prelude () +import Data.List (stripPrefix) + -- | What to do with options following non-options data ArgOrder a = -- | no option processing after first non-option @@ -170,21 +172,36 @@ fmtLong (OptArg _ ad) lo = let opt = "--" ++ lo in opt ++ "[=" ++ ad ++ "]" +-- | Wrap text to the given width. Each line of the input is wrapped on its +-- own, so a description written with explicit line breaks, such as a list of +-- allowed values, keeps those breaks. A line that starts with a @- @ list +-- marker gets a hanging indent, so its continuation lines align with the text +-- after the marker. wrapText :: Int -> String -> [String] -wrapText width = map unwords . wrap 0 [] . words +wrapText width = concatMap wrapLine . lines where - wrap :: Int -> [String] -> [String] -> [[String]] - wrap 0 [] (w : ws) - | length w + 1 > width = - wrap (length w) [w] ws - wrap col line (w : ws) - | col + length w + 1 > width = - reverse line : wrap 0 [] (w : ws) - wrap col line (w : ws) = + wrapLine line = case stripPrefix listMarker line of + Just item -> + zipWith (++) (listMarker : repeat listIndent) (wrapWords (width - length listMarker) item) + Nothing -> wrapWords width line + + listMarker = "- " + listIndent = map (const ' ') listMarker + + wrapWords w = map unwords . wrap w 0 [] . words + + wrap :: Int -> Int -> [String] -> [String] -> [[String]] + wrap width' 0 [] (w : ws) + | length w + 1 > width' = + wrap width' (length w) [w] ws + wrap width' col line (w : ws) + | col + length w + 1 > width' = + reverse line : wrap width' 0 [] (w : ws) + wrap width' col line (w : ws) = let col' = col + length w + 1 - in wrap col' (w : line) ws - wrap _ [] [] = [] - wrap _ line [] = [reverse line] + in wrap width' col' (w : line) ws + wrap _ _ [] [] = [] + wrap _ _ line [] = [reverse line] -- | -- Process the command-line, and return the list of values that matched diff --git a/Cabal/src/Distribution/Simple/Command.hs b/Cabal/src/Distribution/Simple/Command.hs index d3cff2db4e8..a92cc1b019c 100644 --- a/Cabal/src/Distribution/Simple/Command.hs +++ b/Cabal/src/Distribution/Simple/Command.hs @@ -340,10 +340,10 @@ commandGetOpts -> CommandUI flags -> [GetOpt.OptDescr (flags -> flags)] commandGetOpts showOrParse command = - concatMap viewAsGetOpt (commandOptions command showOrParse) + concatMap (viewAsGetOpt showOrParse) (commandOptions command showOrParse) -viewAsGetOpt :: OptionField a -> [GetOpt.OptDescr (a -> a)] -viewAsGetOpt (OptionField _n aa) = concatMap optDescrToGetOpt aa +viewAsGetOpt :: ShowOrParseArgs -> OptionField a -> [GetOpt.OptDescr (a -> a)] +viewAsGetOpt showOrParse (OptionField _n aa) = concatMap optDescrToGetOpt aa where optDescrToGetOpt (ReqArg d (cs, ss) arg_desc set _) = [GetOpt.Option cs ss (GetOpt.ReqArg (runReadE set) arg_desc) d] @@ -358,10 +358,27 @@ viewAsGetOpt (OptionField _n aa) = concatMap optDescrToGetOpt aa [GetOpt.Option sfT lfT (GetOpt.NoArg (set True)) d] optDescrToGetOpt (BoolOpt d ([], []) (sfF, lfF) set _) = [GetOpt.Option sfF lfF (GetOpt.NoArg (set False)) d] - optDescrToGetOpt (BoolOpt d (sfT, lfT) (sfF, lfF) set _) = - [ GetOpt.Option sfT lfT (GetOpt.NoArg (set True)) ("Enable " ++ d) - , GetOpt.Option sfF lfF (GetOpt.NoArg (set False)) ("Disable " ++ d) - ] + optDescrToGetOpt (BoolOpt d trueFlags@(sfT, lfT) falseFlags@(sfF, lfF) set _) = + case showOrParse of + ShowArgs + | Just groupedLongFlag <- mkGroupedBoolLongFlag trueFlags falseFlags -> + [ GetOpt.Option [] [groupedLongFlag] (GetOpt.NoArg (set True)) ("Toggle " ++ d) + ] + _ -> + [ GetOpt.Option sfT lfT (GetOpt.NoArg (set True)) ("Enable " ++ d) + , GetOpt.Option sfF lfF (GetOpt.NoArg (set False)) ("Disable " ++ d) + ] + + mkGroupedBoolLongFlag :: OptFlags -> OptFlags -> Maybe String + mkGroupedBoolLongFlag ([], [longA]) ([], [longB]) = + checkPair longA longB <|> checkPair longB longA + where + checkPair longEnable longDisable = do + suffixEnable <- List.stripPrefix "enable-" longEnable + suffixDisable <- List.stripPrefix "disable-" longDisable + guard (suffixEnable == suffixDisable) + pure ("[enable|disable]-" ++ suffixEnable) + mkGroupedBoolLongFlag _ _ = Nothing getCurrentChoice :: OptDescr a -> a -> [String] getCurrentChoice (ChoiceOpt alts) a = diff --git a/Cabal/src/Distribution/Simple/Configure.hs b/Cabal/src/Distribution/Simple/Configure.hs index 53c3b35caa0..d724e605fd4 100644 --- a/Cabal/src/Distribution/Simple/Configure.hs +++ b/Cabal/src/Distribution/Simple/Configure.hs @@ -73,6 +73,7 @@ module Distribution.Simple.Configure import Control.Monad import Distribution.Compat.Prelude +import GHC.Stack (HasCallStack) import Prelude () import Distribution.Backpack.Configure @@ -81,7 +82,6 @@ import Distribution.Backpack.DescribeUnitId import Distribution.Backpack.Id import Distribution.Backpack.PreExistingComponent import qualified Distribution.Compat.Graph as Graph -import Distribution.Compat.Stack import Distribution.Compiler import Distribution.InstalledPackageInfo (InstalledPackageInfo) import qualified Distribution.InstalledPackageInfo as IPI @@ -253,7 +253,8 @@ instance Exception ConfigStateFileError -- missing, if the file cannot be read, or if the file was created by an older -- version of Cabal. getConfigStateFile - :: Maybe (SymbolicPath CWD (Dir Pkg)) + :: HasCallStack + => Maybe (SymbolicPath CWD (Dir Pkg)) -> SymbolicPath Pkg File -- ^ The file path of the @setup-config@ file. -> IO LocalBuildInfo @@ -279,8 +280,6 @@ getConfigStateFile mbWorkDir setupConfigFile = do throwIO $ ConfigStateFileBadVersion cabalId compId eResult | otherwise = act deferErrorIfBadVersion getStoredValue - where - _ = callStack -- TODO: attach call stack to exception -- | Read the 'localBuildInfoFile', returning either an error or the local build -- info. diff --git a/Cabal/src/Distribution/Simple/Setup/Config.hs b/Cabal/src/Distribution/Simple/Setup/Config.hs index 40bcd24b46c..de781ec7dd6 100644 --- a/Cabal/src/Distribution/Simple/Setup/Config.hs +++ b/Cabal/src/Distribution/Simple/Setup/Config.hs @@ -542,9 +542,7 @@ configureOptions showOrParseArgs = , option "" ["profiling-detail"] - ( "Profiling detail level for executable and library (default, " - ++ "none, exported-functions, toplevel-functions, all-functions, late)." - ) + ("Profiling detail level for executable and library.\n" ++ profDetailLevelsHelp) configProfDetail (\v flags -> flags{configProfDetail = v}) ( reqArg' @@ -555,7 +553,7 @@ configureOptions showOrParseArgs = , option "" ["library-profiling-detail"] - "Profiling detail level for libraries only." + ("Profiling detail level for libraries only.\n" ++ profDetailLevelsHelp) configProfLibDetail (\v flags -> flags{configProfLibDetail = v}) ( reqArg' @@ -912,6 +910,20 @@ showProfDetailLevelFlag :: Flag ProfDetailLevel -> [String] showProfDetailLevelFlag NoFlag = [] showProfDetailLevelFlag (Flag dl) = [showProfDetailLevel dl] +-- | Help text listing the known profiling detail levels, one per line with +-- any aliases, so that the option descriptions stay in step with +-- 'knownProfDetailLevels'. +profDetailLevelsHelp :: String +profDetailLevelsHelp = + unlines ("Allowed values:" : punctuate [item primary aliases | (primary, aliases, _) <- knownProfDetailLevels]) + where + item primary [] = "- " ++ primary + item primary aliases = "- " ++ primary ++ " (or " ++ intercalate ", " aliases ++ ")" + + punctuate [] = [] + punctuate [x] = [x ++ "."] + punctuate (x : xs) = (x ++ ",") : punctuate xs + parsecPromisedComponent :: ParsecParser PromisedComponent parsecPromisedComponent = do pn <- parsec diff --git a/Cabal/src/Distribution/Simple/Setup/Test.hs b/Cabal/src/Distribution/Simple/Setup/Test.hs index 5a1563f2b70..00b8121e98f 100644 --- a/Cabal/src/Distribution/Simple/Setup/Test.hs +++ b/Cabal/src/Distribution/Simple/Setup/Test.hs @@ -194,16 +194,19 @@ testOptions' showOrParseArgs = , option [] ["show-details"] - ( "'always': always show results of individual test cases. " - ++ "'never': never show results of individual test cases. " - ++ "'failures': show results of failing test cases. " - ++ "'streaming': show results of test cases in real time." - ++ "'direct': send results of test cases in real time; no log file." + ( unlines + [ "Allowed values:" + , "- always: always show results of individual test cases," + , "- never: never show results of individual test cases," + , "- failures: show results of failing test cases," + , "- streaming: show results of test cases in real time," + , "- direct: send results of test cases in real time; no log file." + ] ) testShowDetails (\v flags -> flags{testShowDetails = v}) ( reqArg - "FILTER" + "always|never|failures|streaming|direct" ( parsecToReadE ( \_ -> "--show-details flag expects one of " diff --git a/bootstrap/linux-9.10.3.json b/bootstrap/linux-9.10.3.json index 140b38d0f40..46e358dd1a2 100644 --- a/bootstrap/linux-9.10.3.json +++ b/bootstrap/linux-9.10.3.json @@ -116,7 +116,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" }, { "cabal_sha256": "b74eed77eb3237c4ab6a39f08bcce4712b4486b091712ee20e92c8864f1e80a0", @@ -140,7 +140,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" }, { "cabal_sha256": null, @@ -150,7 +150,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18" + "version": "3.19" }, { "cabal_sha256": "39b25fd929b02b01a3fe59fec7ca8b2da6f0f9e282276b7a84e63a4702c4d725", @@ -210,6 +210,38 @@ "src_sha256": "d2a33bc281327d8f20afee18287c2e3f923f0cd86bac40dcba120ca3d2014f9b", "version": "4000.5.0" }, + { + "cabal_sha256": "613dc8d5f6e51babe57398a742ab8d5c2964fa98b773f3bf6e6a72b7e87f1c6e", + "component": "lib:colour", + "flags": [], + "package": "colour", + "revision": 0, + "source": "hackage", + "src_sha256": "1f3b1055675abe4e3362800cc9bf7ab9b92dfdf21a1f6c82b252611270be9680", + "version": "2.3.7" + }, + { + "cabal_sha256": "1d6061eceaf35a9ed269b81177dd4c8c60403a499526f7f68fdffa4ec7842e7f", + "component": "lib:ansi-terminal-types", + "flags": [], + "package": "ansi-terminal-types", + "revision": 0, + "source": "hackage", + "src_sha256": "9fc9ce2157f1889bd99a4d22c9f1c64589590be0f797c3efe71c8fa17a11a689", + "version": "1.1.3" + }, + { + "cabal_sha256": "408d9232e5304efead718f96138d6d7eb2da608c6121c5c0dc6a71a833b14320", + "component": "lib:ansi-terminal", + "flags": [ + "-example" + ], + "package": "ansi-terminal", + "revision": 0, + "source": "hackage", + "src_sha256": "9cf083cef2e2ba88a425f132c8a82bfa931eb4b0c38232b2017f8fcea2e23073", + "version": "1.1.5" + }, { "cabal_sha256": "140fc5adad166f7b527567cbd26ff481e8da4a66bdfc84be3ddf28dbeb66f275", "component": "lib:hashable", @@ -324,7 +356,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" }, { "cabal_sha256": "0e9de2ccce261e7a5b027e842f6f47f50eb0e6059a0de98a5479f75aa8164107", @@ -445,7 +477,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "0.1" + "version": "3.19" }, { "cabal_sha256": "0dc8dc33b9bba0e025e444355f6c2d806f62a4656446961c3647165f80f0d278", @@ -459,6 +491,61 @@ "src_sha256": "1066e286615e39ef43f7e7437a4644775246e264c33b4d259b4858cff0985f0b", "version": "0.5.1.0" }, + { + "cabal_sha256": "e3a802ea939d465b2e37b9fa09d8e5bb88b5775d6d62dd2ec6ca32b63416656d", + "component": "lib:prettyprinter", + "flags": [ + "-buildreadme", + "+text" + ], + "package": "prettyprinter", + "revision": 0, + "source": "hackage", + "src_sha256": "f04eb6fd865512ad8672da1e8bfcea1c384509fc2f662c41b7ac39d7898706ee", + "version": "1.7.2" + }, + { + "cabal_sha256": "5184ba6002a650de3307547347eaba19bdc9b82eb68e943f406818caa215ce4f", + "component": "lib:prettyprinter-ansi-terminal", + "flags": [ + "+text" + ], + "package": "prettyprinter-ansi-terminal", + "revision": 0, + "source": "hackage", + "src_sha256": "912cd340d5c2583111e2eaeb9aa03b87551ca2e3dd78bbfd346756b9f1e6c9fe", + "version": "1.1.4" + }, + { + "cabal_sha256": "044fb9955f63ee138fcebedfdcbe54afe741f2d5892a2d0bdf3a8052bd342643", + "component": "lib:transformers-compat", + "flags": [ + "-five", + "+five-three", + "-four", + "+generic-deriving", + "+mtl", + "-three", + "-two" + ], + "package": "transformers-compat", + "revision": 0, + "source": "hackage", + "src_sha256": "b62c7304c9f3cbc9463d0739aa85cb9489f217ea092b9d625d417514fbcc9d6a", + "version": "0.7.2" + }, + { + "cabal_sha256": "f30973861ac7e7ebff05ff8c7c3d1e4d283a1f3850e1cc14106b0693ec1b6d82", + "component": "lib:optparse-applicative", + "flags": [ + "+process" + ], + "package": "optparse-applicative", + "revision": 1, + "source": "hackage", + "src_sha256": "63811ab4fd26e829b8868364325a88be3acc79819f5bb5005b2dd3b961ecc491", + "version": "0.18.1.0" + }, { "cabal_sha256": "d6c0c6d1136f5046207a331114ff4130e70640452096de7719bf03e3fceb7c7b", "component": "lib:regex-base", @@ -525,7 +612,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" }, { "cabal_sha256": null, @@ -539,7 +626,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" } ] } diff --git a/bootstrap/linux-9.12.4.json b/bootstrap/linux-9.12.4.json index 2b2203ec259..b737ceca0d5 100644 --- a/bootstrap/linux-9.12.4.json +++ b/bootstrap/linux-9.12.4.json @@ -120,7 +120,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" }, { "cabal_sha256": "b74eed77eb3237c4ab6a39f08bcce4712b4486b091712ee20e92c8864f1e80a0", @@ -144,7 +144,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" }, { "cabal_sha256": null, @@ -154,7 +154,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18" + "version": "3.19" }, { "cabal_sha256": "39b25fd929b02b01a3fe59fec7ca8b2da6f0f9e282276b7a84e63a4702c4d725", @@ -214,6 +214,38 @@ "src_sha256": "d2a33bc281327d8f20afee18287c2e3f923f0cd86bac40dcba120ca3d2014f9b", "version": "4000.5.0" }, + { + "cabal_sha256": "613dc8d5f6e51babe57398a742ab8d5c2964fa98b773f3bf6e6a72b7e87f1c6e", + "component": "lib:colour", + "flags": [], + "package": "colour", + "revision": 0, + "source": "hackage", + "src_sha256": "1f3b1055675abe4e3362800cc9bf7ab9b92dfdf21a1f6c82b252611270be9680", + "version": "2.3.7" + }, + { + "cabal_sha256": "1d6061eceaf35a9ed269b81177dd4c8c60403a499526f7f68fdffa4ec7842e7f", + "component": "lib:ansi-terminal-types", + "flags": [], + "package": "ansi-terminal-types", + "revision": 0, + "source": "hackage", + "src_sha256": "9fc9ce2157f1889bd99a4d22c9f1c64589590be0f797c3efe71c8fa17a11a689", + "version": "1.1.3" + }, + { + "cabal_sha256": "408d9232e5304efead718f96138d6d7eb2da608c6121c5c0dc6a71a833b14320", + "component": "lib:ansi-terminal", + "flags": [ + "-example" + ], + "package": "ansi-terminal", + "revision": 0, + "source": "hackage", + "src_sha256": "9cf083cef2e2ba88a425f132c8a82bfa931eb4b0c38232b2017f8fcea2e23073", + "version": "1.1.5" + }, { "cabal_sha256": "140fc5adad166f7b527567cbd26ff481e8da4a66bdfc84be3ddf28dbeb66f275", "component": "lib:hashable", @@ -328,7 +360,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" }, { "cabal_sha256": "0e9de2ccce261e7a5b027e842f6f47f50eb0e6059a0de98a5479f75aa8164107", @@ -436,7 +468,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "0.1" + "version": "3.19" }, { "cabal_sha256": "0dc8dc33b9bba0e025e444355f6c2d806f62a4656446961c3647165f80f0d278", @@ -450,6 +482,61 @@ "src_sha256": "1066e286615e39ef43f7e7437a4644775246e264c33b4d259b4858cff0985f0b", "version": "0.5.1.0" }, + { + "cabal_sha256": "e3a802ea939d465b2e37b9fa09d8e5bb88b5775d6d62dd2ec6ca32b63416656d", + "component": "lib:prettyprinter", + "flags": [ + "-buildreadme", + "+text" + ], + "package": "prettyprinter", + "revision": 0, + "source": "hackage", + "src_sha256": "f04eb6fd865512ad8672da1e8bfcea1c384509fc2f662c41b7ac39d7898706ee", + "version": "1.7.2" + }, + { + "cabal_sha256": "5184ba6002a650de3307547347eaba19bdc9b82eb68e943f406818caa215ce4f", + "component": "lib:prettyprinter-ansi-terminal", + "flags": [ + "+text" + ], + "package": "prettyprinter-ansi-terminal", + "revision": 0, + "source": "hackage", + "src_sha256": "912cd340d5c2583111e2eaeb9aa03b87551ca2e3dd78bbfd346756b9f1e6c9fe", + "version": "1.1.4" + }, + { + "cabal_sha256": "044fb9955f63ee138fcebedfdcbe54afe741f2d5892a2d0bdf3a8052bd342643", + "component": "lib:transformers-compat", + "flags": [ + "-five", + "+five-three", + "-four", + "+generic-deriving", + "+mtl", + "-three", + "-two" + ], + "package": "transformers-compat", + "revision": 0, + "source": "hackage", + "src_sha256": "b62c7304c9f3cbc9463d0739aa85cb9489f217ea092b9d625d417514fbcc9d6a", + "version": "0.7.2" + }, + { + "cabal_sha256": "f30973861ac7e7ebff05ff8c7c3d1e4d283a1f3850e1cc14106b0693ec1b6d82", + "component": "lib:optparse-applicative", + "flags": [ + "+process" + ], + "package": "optparse-applicative", + "revision": 1, + "source": "hackage", + "src_sha256": "63811ab4fd26e829b8868364325a88be3acc79819f5bb5005b2dd3b961ecc491", + "version": "0.18.1.0" + }, { "cabal_sha256": "d6c0c6d1136f5046207a331114ff4130e70640452096de7719bf03e3fceb7c7b", "component": "lib:regex-base", @@ -516,7 +603,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" }, { "cabal_sha256": null, @@ -530,7 +617,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" } ] } diff --git a/bootstrap/linux-9.6.7.json b/bootstrap/linux-9.6.7.json index 842d5572401..99b16caaca5 100644 --- a/bootstrap/linux-9.6.7.json +++ b/bootstrap/linux-9.6.7.json @@ -108,7 +108,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" }, { "cabal_sha256": "b74eed77eb3237c4ab6a39f08bcce4712b4486b091712ee20e92c8864f1e80a0", @@ -132,7 +132,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" }, { "cabal_sha256": null, @@ -142,7 +142,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18" + "version": "3.19" }, { "cabal_sha256": "39b25fd929b02b01a3fe59fec7ca8b2da6f0f9e282276b7a84e63a4702c4d725", @@ -202,6 +202,38 @@ "src_sha256": "d2a33bc281327d8f20afee18287c2e3f923f0cd86bac40dcba120ca3d2014f9b", "version": "4000.5.0" }, + { + "cabal_sha256": "613dc8d5f6e51babe57398a742ab8d5c2964fa98b773f3bf6e6a72b7e87f1c6e", + "component": "lib:colour", + "flags": [], + "package": "colour", + "revision": 0, + "source": "hackage", + "src_sha256": "1f3b1055675abe4e3362800cc9bf7ab9b92dfdf21a1f6c82b252611270be9680", + "version": "2.3.7" + }, + { + "cabal_sha256": "1d6061eceaf35a9ed269b81177dd4c8c60403a499526f7f68fdffa4ec7842e7f", + "component": "lib:ansi-terminal-types", + "flags": [], + "package": "ansi-terminal-types", + "revision": 0, + "source": "hackage", + "src_sha256": "9fc9ce2157f1889bd99a4d22c9f1c64589590be0f797c3efe71c8fa17a11a689", + "version": "1.1.3" + }, + { + "cabal_sha256": "408d9232e5304efead718f96138d6d7eb2da608c6121c5c0dc6a71a833b14320", + "component": "lib:ansi-terminal", + "flags": [ + "-example" + ], + "package": "ansi-terminal", + "revision": 0, + "source": "hackage", + "src_sha256": "9cf083cef2e2ba88a425f132c8a82bfa931eb4b0c38232b2017f8fcea2e23073", + "version": "1.1.5" + }, { "cabal_sha256": "c0663f5f428108680f4aae0f67b7b357c1bb5954281c7fbe941c50c58cd79f18", "component": "lib:os-string", @@ -326,7 +358,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" }, { "cabal_sha256": "0e9de2ccce261e7a5b027e842f6f47f50eb0e6059a0de98a5479f75aa8164107", @@ -447,7 +479,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "0.1" + "version": "3.19" }, { "cabal_sha256": "0dc8dc33b9bba0e025e444355f6c2d806f62a4656446961c3647165f80f0d278", @@ -461,6 +493,61 @@ "src_sha256": "1066e286615e39ef43f7e7437a4644775246e264c33b4d259b4858cff0985f0b", "version": "0.5.1.0" }, + { + "cabal_sha256": "e3a802ea939d465b2e37b9fa09d8e5bb88b5775d6d62dd2ec6ca32b63416656d", + "component": "lib:prettyprinter", + "flags": [ + "-buildreadme", + "+text" + ], + "package": "prettyprinter", + "revision": 0, + "source": "hackage", + "src_sha256": "f04eb6fd865512ad8672da1e8bfcea1c384509fc2f662c41b7ac39d7898706ee", + "version": "1.7.2" + }, + { + "cabal_sha256": "5184ba6002a650de3307547347eaba19bdc9b82eb68e943f406818caa215ce4f", + "component": "lib:prettyprinter-ansi-terminal", + "flags": [ + "+text" + ], + "package": "prettyprinter-ansi-terminal", + "revision": 0, + "source": "hackage", + "src_sha256": "912cd340d5c2583111e2eaeb9aa03b87551ca2e3dd78bbfd346756b9f1e6c9fe", + "version": "1.1.4" + }, + { + "cabal_sha256": "044fb9955f63ee138fcebedfdcbe54afe741f2d5892a2d0bdf3a8052bd342643", + "component": "lib:transformers-compat", + "flags": [ + "-five", + "+five-three", + "-four", + "+generic-deriving", + "+mtl", + "-three", + "-two" + ], + "package": "transformers-compat", + "revision": 0, + "source": "hackage", + "src_sha256": "b62c7304c9f3cbc9463d0739aa85cb9489f217ea092b9d625d417514fbcc9d6a", + "version": "0.7.2" + }, + { + "cabal_sha256": "f30973861ac7e7ebff05ff8c7c3d1e4d283a1f3850e1cc14106b0693ec1b6d82", + "component": "lib:optparse-applicative", + "flags": [ + "+process" + ], + "package": "optparse-applicative", + "revision": 1, + "source": "hackage", + "src_sha256": "63811ab4fd26e829b8868364325a88be3acc79819f5bb5005b2dd3b961ecc491", + "version": "0.18.1.0" + }, { "cabal_sha256": "d6c0c6d1136f5046207a331114ff4130e70640452096de7719bf03e3fceb7c7b", "component": "lib:regex-base", @@ -527,7 +614,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" }, { "cabal_sha256": null, @@ -541,7 +628,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" } ] } diff --git a/bootstrap/linux-9.8.4.json b/bootstrap/linux-9.8.4.json index 56be7837098..17b0e926116 100644 --- a/bootstrap/linux-9.8.4.json +++ b/bootstrap/linux-9.8.4.json @@ -108,7 +108,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" }, { "cabal_sha256": "b74eed77eb3237c4ab6a39f08bcce4712b4486b091712ee20e92c8864f1e80a0", @@ -132,7 +132,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" }, { "cabal_sha256": null, @@ -142,7 +142,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18" + "version": "3.19" }, { "cabal_sha256": "39b25fd929b02b01a3fe59fec7ca8b2da6f0f9e282276b7a84e63a4702c4d725", @@ -202,6 +202,38 @@ "src_sha256": "d2a33bc281327d8f20afee18287c2e3f923f0cd86bac40dcba120ca3d2014f9b", "version": "4000.5.0" }, + { + "cabal_sha256": "613dc8d5f6e51babe57398a742ab8d5c2964fa98b773f3bf6e6a72b7e87f1c6e", + "component": "lib:colour", + "flags": [], + "package": "colour", + "revision": 0, + "source": "hackage", + "src_sha256": "1f3b1055675abe4e3362800cc9bf7ab9b92dfdf21a1f6c82b252611270be9680", + "version": "2.3.7" + }, + { + "cabal_sha256": "1d6061eceaf35a9ed269b81177dd4c8c60403a499526f7f68fdffa4ec7842e7f", + "component": "lib:ansi-terminal-types", + "flags": [], + "package": "ansi-terminal-types", + "revision": 0, + "source": "hackage", + "src_sha256": "9fc9ce2157f1889bd99a4d22c9f1c64589590be0f797c3efe71c8fa17a11a689", + "version": "1.1.3" + }, + { + "cabal_sha256": "408d9232e5304efead718f96138d6d7eb2da608c6121c5c0dc6a71a833b14320", + "component": "lib:ansi-terminal", + "flags": [ + "-example" + ], + "package": "ansi-terminal", + "revision": 0, + "source": "hackage", + "src_sha256": "9cf083cef2e2ba88a425f132c8a82bfa931eb4b0c38232b2017f8fcea2e23073", + "version": "1.1.5" + }, { "cabal_sha256": "c0663f5f428108680f4aae0f67b7b357c1bb5954281c7fbe941c50c58cd79f18", "component": "lib:os-string", @@ -326,7 +358,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" }, { "cabal_sha256": "0e9de2ccce261e7a5b027e842f6f47f50eb0e6059a0de98a5479f75aa8164107", @@ -447,7 +479,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "0.1" + "version": "3.19" }, { "cabal_sha256": "0dc8dc33b9bba0e025e444355f6c2d806f62a4656446961c3647165f80f0d278", @@ -461,6 +493,61 @@ "src_sha256": "1066e286615e39ef43f7e7437a4644775246e264c33b4d259b4858cff0985f0b", "version": "0.5.1.0" }, + { + "cabal_sha256": "e3a802ea939d465b2e37b9fa09d8e5bb88b5775d6d62dd2ec6ca32b63416656d", + "component": "lib:prettyprinter", + "flags": [ + "-buildreadme", + "+text" + ], + "package": "prettyprinter", + "revision": 0, + "source": "hackage", + "src_sha256": "f04eb6fd865512ad8672da1e8bfcea1c384509fc2f662c41b7ac39d7898706ee", + "version": "1.7.2" + }, + { + "cabal_sha256": "5184ba6002a650de3307547347eaba19bdc9b82eb68e943f406818caa215ce4f", + "component": "lib:prettyprinter-ansi-terminal", + "flags": [ + "+text" + ], + "package": "prettyprinter-ansi-terminal", + "revision": 0, + "source": "hackage", + "src_sha256": "912cd340d5c2583111e2eaeb9aa03b87551ca2e3dd78bbfd346756b9f1e6c9fe", + "version": "1.1.4" + }, + { + "cabal_sha256": "044fb9955f63ee138fcebedfdcbe54afe741f2d5892a2d0bdf3a8052bd342643", + "component": "lib:transformers-compat", + "flags": [ + "-five", + "+five-three", + "-four", + "+generic-deriving", + "+mtl", + "-three", + "-two" + ], + "package": "transformers-compat", + "revision": 0, + "source": "hackage", + "src_sha256": "b62c7304c9f3cbc9463d0739aa85cb9489f217ea092b9d625d417514fbcc9d6a", + "version": "0.7.2" + }, + { + "cabal_sha256": "f30973861ac7e7ebff05ff8c7c3d1e4d283a1f3850e1cc14106b0693ec1b6d82", + "component": "lib:optparse-applicative", + "flags": [ + "+process" + ], + "package": "optparse-applicative", + "revision": 1, + "source": "hackage", + "src_sha256": "63811ab4fd26e829b8868364325a88be3acc79819f5bb5005b2dd3b961ecc491", + "version": "0.18.1.0" + }, { "cabal_sha256": "d6c0c6d1136f5046207a331114ff4130e70640452096de7719bf03e3fceb7c7b", "component": "lib:regex-base", @@ -527,7 +614,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" }, { "cabal_sha256": null, @@ -541,7 +628,7 @@ "revision": null, "source": "local", "src_sha256": null, - "version": "3.18.1.0" + "version": "3.19.0.0" } ] } diff --git a/cabal-install/cabal-install.cabal b/cabal-install/cabal-install.cabal index 83628ab03d1..5c9b2396c40 100644 --- a/cabal-install/cabal-install.cabal +++ b/cabal-install/cabal-install.cabal @@ -106,6 +106,7 @@ library Distribution.Client.CmdClean Distribution.Client.CmdConfigure Distribution.Client.CmdErrorMessages + Distribution.Client.Cmd.UI Distribution.Client.CmdExec Distribution.Client.CmdFreeze Distribution.Client.CmdHaddock @@ -256,6 +257,7 @@ library , HTTP >= 4000.1.5 && < 4000.6 , mtl >= 2.0 && < 2.4 , network-uri >= 2.6.2.0 && < 2.7 + , optparse-applicative >= 0.18 && < 0.19 , pretty >= 1.1 && < 1.2 , process >= 1.6.29.0 && < 1.7 , random >= 1.2 && < 1.4 diff --git a/cabal-install/src/Distribution/Client/Cmd/UI.hs b/cabal-install/src/Distribution/Client/Cmd/UI.hs new file mode 100644 index 00000000000..b091bf12827 --- /dev/null +++ b/cabal-install/src/Distribution/Client/Cmd/UI.hs @@ -0,0 +1,747 @@ +{-# LANGUAGE LambdaCase #-} +{-# LANGUAGE OverloadedStrings #-} + +module Distribution.Client.Cmd.UI + ( -- * Converting CommandUI options to optparse-applicative parsers + optionFieldFlagParsers + , optionFieldParser + , optDescrParser + , optionMods + , flagMods + + -- * Converting CommandUI options to GetOpt descriptions + , optionFieldToGetOpt + , optDescrToGetOpt + + -- * Command data types + , Examples + , ReplaceCommandAlias + , CmdItem (..) + , ParsedCommand (..) + , parsedCommandParser + , cmdItemParser + , cmdOptionParsers + , cmdSpec + , cmdListOptions + , commandNames + , NamedCommandParser (..) + , commandParserByName + , parseCommandWithOptparse + , parseCommandWithOptparseMany + , parseCommand + , replaceCommandAlias + , helpDescriptionOrSynopsis + , parserInfo + + -- * Help text layout helpers + , renderOptionRows + , getOptToColumns + , wrapDescription + , capitalizeDescription + , helpText + , HelpColor (..) + + -- * Option grouping helpers + , groupPredicates + , groupSequentially + ) where + +import Distribution.Client.Compat.Prelude +import Prelude () + +import Data.Char (isLower) +import Data.List (mapAccumL, stripPrefix) +import Data.Monoid (Endo (..)) +import qualified Data.Text as T +import qualified System.Console.GetOpt as GetOpt + +import Distribution.Client.NixStyleOptions + ( NixStyleFlags (..) + , keepBenchOptions + , keepCompilerOptions + , keepConfigureOptions + , keepCoverageOptions + , keepDeprecatedOptions + , keepExeOptions + , keepHaddockOptions + , keepIncludeOptions + , keepInstallOptions + , keepIrrelevantOptions + , keepLibOptions + , keepLoggingOptions + , keepOutputOptions + , keepPhaseOptions + , keepProfilingOptions + , keepProgOptions + , keepSolvingOptions + , keepTestOptions + , keepUnsupportedOptions + ) +import Distribution.ReadE (runReadE) +import Distribution.Simple.Command + ( CommandParse (..) + , CommandSpec (..) + , CommandType (NormalCommand) + , CommandUI (..) + , OptDescr (..) + , OptionField (..) + , ShowOrParseArgs (..) + , commandAddAction + , commandParseArgs + ) + +import Options.Applicative + ( ParserInfo + , ParserResult (..) + , asum + , defaultPrefs + , execParserPure + , flag' + , footer + , fullDesc + , header + , help + , helper + , info + , long + , metavar + , progDesc + , renderFailure + , strArgument + , (<**>) + ) +import qualified Options.Applicative as O + +helpDescriptionOrSynopsis :: CommandUI flags -> String +helpDescriptionOrSynopsis x = + case commandDescription x of + Nothing -> commandSynopsis x + Just mkDescription -> mkDescription "cabal" + +data CmdItem a + = CmdItemFlag (Endo (NixStyleFlags a)) + | CmdItemTarget String + | CmdItemListOptions + +data ParsedCommand a = ParsedCommand + { parsedFlagEdits :: Endo (NixStyleFlags a) + , parsedTargets :: [String] + , parsedListOptions :: Bool + } + +-- | Examples text for a command, given the program name and command name. +type Examples = + String + -- ^ program name + -> String + -- ^ command name + -> String + -- ^ examples text + +-- | Replacements for v2- prefixed commands, such as; +-- +-- * v2-build -> new-build or +-- * v2-build -> build. +type ReplaceCommandAlias = + String + -- ^ the new prefix + -> String + -- ^ the command + -> String + -- ^ the command name with the prefix replaced + +-- | Given a v2- prefixed command name, returns a function for replacing that +-- prefix with a new prefix. +replaceCommandAlias :: String -> ReplaceCommandAlias +replaceCommandAlias = replaceText + +-- SEE: generic-sop-lens.hs +replaceText :: String -> String -> String -> String +replaceText needle replacement = go + where + go [] = [] + go input@(char : rest) + | Just remainder <- stripPrefix needle input = replacement ++ go remainder + | otherwise = char : go rest + +-- | Puts a prefix before a bare command name. +affixVersionPrefix :: String -> String -> String +affixVersionPrefix = replaceText "v2-" + +-- | Removes the v2- prefix from a command name, leaving the bare command name. +stripVersionPrefix :: String -> String +stripVersionPrefix = affixVersionPrefix "" + +-- | Assuming a v2- prefix for a command name, for the 'commandName' of the +-- given command, makes a list that includes the bare name, the new- prefixed +-- name, and the v2- prefixed name. +commandNames :: CommandUI flags -> [String] +commandNames command = + [ stripVersionPrefix name + , affixVersionPrefix "new-" name + , name + ] + where + name = commandName command + +-- | Register a command under each of its names (see 'commandNames'), so that +-- the global help and the command registry list @build@, @new-build@ and +-- @v2-build@ alike, as "Distribution.Client.CmdLegacy" does for the other +-- commands. +cmdSpec + :: CommandUI flags + -> (flags -> [String] -> action) + -> [CommandSpec action] +cmdSpec command action = + [ CommandSpec (renamed name) (`commandAddAction` action) NormalCommand + | name <- commandNames command + ] + where + renamed name = + let rename = replaceCommandAlias (commandName command) name + in command + { commandName = name + , commandUsage = rename . commandUsage command + , commandDescription = (rename .) <$> commandDescription command + , commandNotes = (rename .) <$> commandNotes command + } + +cmdListOptions :: CommandUI flags -> [String] +cmdListOptions command = + case commandParseArgs command False ["--list-options"] of + CommandList opts -> opts + _ -> [] + +parseCommand + :: HelpColor + -> Examples + -> CommandUI (NixStyleFlags a) + -> (NixStyleFlags a -> [String] -> action) + -> String + -> [String] + -> CommandParse action +parseCommand helpColor examples cmdui action invokedName cmdArgs = + case execParserPure defaultPrefs pInfo (supplyOptArgDefaults optionFields cmdArgs) of + Success parsed -> + if parsedListOptions parsed + then CommandList (cmdListOptions cmdui) + else + let flags = appEndo (parsedFlagEdits parsed) (commandDefaultFlags cmdui) + in CommandReadyToGo (action flags (parsedTargets parsed)) + Failure failure -> + let (msg, exitCode) = renderFailure failure ("cabal " ++ invokedName) + in if exitCode == ExitSuccess + then CommandHelp (helpText helpColor (replaceCommandAlias (commandName cmdui)) cmdui invokedName) + else CommandErrors [msg] + CompletionInvoked _ -> + CommandErrors ["Shell completion is not supported by this parser path."] + where + pInfo = parserInfo invokedName examples flagParsers cmdui + optionFields = commandOptions cmdui ParseArgs + flagParsers = cmdOptionParsers optionFields + +-- | Insert an empty argument after each bare occurrence of an +-- optional-argument option, so that @--allow-newer@ and @-j@ keep their +-- GetOpt meaning: the option's default, with the next word left as a +-- positional argument. Attached forms such as @--allow-newer=base@ and +-- @-j4@ are left alone, as is everything after @--@. +supplyOptArgDefaults :: [OptionField flags] -> [String] -> [String] +supplyOptArgDefaults fields = go + where + go [] = [] + go ("--" : rest) = "--" : rest + go (arg : rest) + | arg `elem` bareForms = arg : "" : go rest + | otherwise = arg : go rest + + bareForms = + [ form + | OptionField _ descrs <- fields + , OptArg _ (shortFlags, longFlags) _ _ _ _ <- descrs + , form <- map (\c -> ['-', c]) shortFlags ++ map ("--" ++) longFlags + ] + +parseCommandWithOptparse + :: CommandUI globalFlags + -> (String -> Maybe (String -> [String] -> CommandParse action)) + -> [String] + -> Maybe (CommandParse (globalFlags, CommandParse action)) +parseCommandWithOptparse globalCommand parserForCommand argv = + case commandParseArgs globalCommand True argv of + CommandReadyToGo (mkGlobalFlags, cmdArgs0) -> do + cmdName : cmdArgs <- pure cmdArgs0 + cmdParser <- parserForCommand cmdName + let globalFlags = mkGlobalFlags (commandDefaultFlags globalCommand) + pure $ CommandReadyToGo (globalFlags, cmdParser cmdName cmdArgs) + _ -> Nothing + +-- | A parser for one or more command names. +data NamedCommandParser action = NamedCommandParser + { namedCommandNames :: [String] + -- ^ The command name and its aliases. + , namedCommandParser :: String -> [String] -> CommandParse action + } + +-- | Wrap a command's optparse parser together with the names it should match. +commandParserByName + :: HelpColor + -> Examples + -> CommandUI (NixStyleFlags flags) + -> (NixStyleFlags flags -> [String] -> action) + -> NamedCommandParser action +commandParserByName helpColor examples command action = + NamedCommandParser + { namedCommandNames = commandNames command + , namedCommandParser = \name args -> parseCommand helpColor examples command action name args + } + +-- | Parse a command using a list of name/parser associations, picking the first +-- match in the list. +parseCommandWithOptparseMany + :: CommandUI globalFlags + -> [NamedCommandParser action] + -> [String] + -> Maybe (CommandParse (globalFlags, CommandParse action)) +parseCommandWithOptparseMany globalCommand commands argv = + case commandParseArgs globalCommand True argv of + CommandReadyToGo (mkGlobalFlags, cmdArgs0) -> do + cmdName : cmdArgs <- pure cmdArgs0 + parser <- find ((cmdName `elem`) . namedCommandNames) commands + let globalFlags = mkGlobalFlags (commandDefaultFlags globalCommand) + pure $ CommandReadyToGo (globalFlags, namedCommandParser parser cmdName cmdArgs) + _ -> Nothing + +parserInfo :: String -> Examples -> [O.Parser (CmdItem a)] -> CommandUI flags -> ParserInfo (ParsedCommand a) +parserInfo invokedName examples flagParsers cmdui = + info + (parsedCommandParser flagParsers <**> helper) + ( fullDesc + <> progDesc (helpDescriptionOrSynopsis cmdui) + <> header ("cabal " ++ invokedName) + <> footer (examples "cabal" invokedName) + ) + +parsedCommandParser :: [O.Parser (CmdItem a)] -> O.Parser (ParsedCommand a) +parsedCommandParser flagParsers = toParsed <$> many (cmdItemParser flagParsers) + where + toParsed items = + let edits = [e | CmdItemFlag e <- items] + targets = [t | CmdItemTarget t <- items] + listOptionsSeen = any isListOptions items + in ParsedCommand + { -- Apply edits in command-line order, first to last, so that a + -- later option overrides an earlier one and list options + -- accumulate in the order given. @Endo f <> Endo g@ applies + -- @g@ first, so the list is reversed before being combined. + parsedFlagEdits = mconcat (reverse edits) + , parsedTargets = targets + , parsedListOptions = listOptionsSeen + } + + isListOptions CmdItemListOptions = True + isListOptions _ = False + +cmdItemParser :: [O.Parser (CmdItem a)] -> O.Parser (CmdItem a) +cmdItemParser flags = + asum + ( flags + ++ [ CmdItemListOptions + <$ flag' + () + (long "list-options" <> help "Print a list of command line flags") + , CmdItemTarget <$> strArgument (metavar "TARGET") + ] + ) + +cmdOptionParsers :: [OptionField (NixStyleFlags a)] -> [O.Parser (CmdItem a)] +cmdOptionParsers fields = (fmap . fmap) CmdItemFlag (optionFieldFlagParsers fields) + +optionFieldFlagParsers :: [OptionField flags] -> [O.Parser (Endo flags)] +optionFieldFlagParsers = concatMap optionFieldParser + +optionFieldParser :: OptionField flags -> [O.Parser (Endo flags)] +optionFieldParser (OptionField _ descrs) = concatMap optDescrParser descrs + +optDescrParser :: OptDescr flags -> [O.Parser (Endo flags)] +optDescrParser = \case + ReqArg desc optFlags placeHolder reader _show -> + [ Endo + <$> O.option + (O.eitherReader (runReadE reader)) + (optionMods optFlags <> O.metavar placeHolder <> O.help desc) + ] + OptArg desc optFlags placeHolder reader defaultFn _show -> + -- optparse-applicative has no optional-argument options: an option + -- either always takes an argument or never does, and a bare @-j@ would + -- swallow the next word as its value. 'supplyOptArgDefaults' gives each + -- bare occurrence an empty argument instead, which the reader maps to the + -- option's default. An explicit @--jobs=@ therefore also means the default. + [ Endo + <$> O.option + (O.eitherReader readOrDefault) + (optionMods optFlags <> O.metavar placeHolder <> O.help desc) + ] + where + readOrDefault "" = Right defaultFn + readOrDefault s = runReadE reader s + ChoiceOpt choices -> + [ Endo setFn + <$ O.flag' () (flagMods optFlags <> O.help desc) + | (desc, optFlags, setFn, _get) <- choices + ] + BoolOpt desc trueFlags falseFlags setFn _get -> + [ Endo (setFn True) + <$ O.flag' () (flagMods trueFlags <> O.help desc) + , Endo (setFn False) + <$ O.flag' () (flagMods falseFlags <> O.help desc) + ] + +optionMods :: (String, [String]) -> O.Mod O.OptionFields a +optionMods (shortFlags, longFlags) = + mconcat (map O.short shortFlags) <> mconcat (map O.long longFlags) + +flagMods :: (String, [String]) -> O.Mod O.FlagFields a +flagMods (shortFlags, longFlags) = + mconcat (map O.short shortFlags) <> mconcat (map O.long longFlags) + +optionFieldToGetOpt :: OptionField flags -> [GetOpt.OptDescr ()] +optionFieldToGetOpt (OptionField _ descrs) = concatMap optDescrToGetOpt descrs + +optDescrToGetOpt :: OptDescr flags -> [GetOpt.OptDescr ()] +optDescrToGetOpt = \case + ReqArg desc (shortFlags, longFlags) placeHolder _reader _showFlag -> + [GetOpt.Option shortFlags longFlags (GetOpt.ReqArg (const ()) placeHolder) desc] + OptArg desc (shortFlags, longFlags) placeHolder _reader _defaultFn _showFlag -> + [GetOpt.Option shortFlags longFlags (GetOpt.OptArg (const ()) placeHolder) desc] + ChoiceOpt choices -> + [ GetOpt.Option shortFlags longFlags (GetOpt.NoArg ()) desc + | (desc, (shortFlags, longFlags), _setFn, _getFn) <- choices + ] + BoolOpt desc trueFlags@(shortTrue, longTrue) falseFlags@(shortFalse, longFalse) _setFn _getFn + | null shortFalse && null longFalse -> + [GetOpt.Option shortTrue longTrue (GetOpt.NoArg ()) desc] + | null shortTrue && null longTrue -> + [GetOpt.Option shortFalse longFalse (GetOpt.NoArg ()) desc] + | Just groupedLongFlag <- mkGroupedBoolLongFlag trueFlags falseFlags -> + [GetOpt.Option [] [groupedLongFlag] (GetOpt.NoArg ()) ("Toggle " <> desc)] + | otherwise -> + [ GetOpt.Option shortTrue longTrue (GetOpt.NoArg ()) ("Enable " <> desc) + , GetOpt.Option shortFalse longFalse (GetOpt.NoArg ()) ("Disable " <> desc) + ] + +mkGroupedBoolLongFlag :: (String, [String]) -> (String, [String]) -> Maybe String +mkGroupedBoolLongFlag ([], [longA]) ([], [longB]) = + checkPair longA longB <|> checkPair longB longA + where + checkPair longEnable longDisable = do + suffixEnable <- stripPrefix "enable-" longEnable + suffixDisable <- stripPrefix "disable-" longDisable + guard (suffixEnable == suffixDisable) + pure ("[enable|disable]-" <> suffixEnable) +mkGroupedBoolLongFlag _ _ = Nothing + +renderOptionRows :: (String -> String) -> Int -> Int -> Int -> [GetOpt.OptDescr ()] -> (String, [String]) +renderOptionRows colorizeWarning maxFlagColumnWidth descColumn helpOutputWidth options = + let rendered = [renderOption (index == 0) opt | (index, opt) <- zip [0 :: Int ..] options] + in (concatMap fst rendered, concatMap snd rendered) + where + descriptionMarker = "# " + markerPadding = replicate (length descriptionMarker) ' ' + descriptionIndent = replicate (length flagIndent + descColumn) ' ' + descriptionWidth = max 20 (helpOutputWidth - (length flagIndent + descColumn) - length descriptionMarker) + + renderOption isFirstInGroup opt = + let (flagColumn, description) = getOptToColumns opt + (capitalizedDescription, wasAutoCapitalized) = capitalizeDescription description + wrappedDescription = wrapDescription descriptionWidth capitalizedDescription + displayDescription = + if wasAutoCapitalized + then colorizeFirstAlpha wrappedDescription + else wrappedDescription + isStacked = length flagColumn > maxFlagColumnWidth + spacer = if isStacked && not isFirstInGroup then "\n" else "" + warning = ["Auto-capitalized help text for " <> flagColumn | wasAutoCapitalized] + renderedRow = + spacer + <> if isStacked + then renderStacked flagColumn displayDescription + else renderInline flagColumn displayDescription + in (renderedRow, warning) + + colorizeFirstAlpha :: [String] -> [String] + colorizeFirstAlpha = go + where + go [] = [] + go (line : rest) = + case colorizeFirstAlphaInLine line of + Nothing -> line : go rest + Just colored -> colored : rest + + colorizeFirstAlphaInLine :: String -> Maybe String + colorizeFirstAlphaInLine = scan [] + where + scan _ [] = Nothing + scan acc (ch : cs) + | isAlpha ch = Just (reverse acc <> colorizeWarning [ch] <> cs) + | otherwise = scan (ch : acc) cs + + renderInline flagColumn descriptionLines = + let padding = max 1 (descColumn - length flagColumn) + in case descriptionLines of + [] -> flagIndent <> flagColumn <> "\n" + firstLineText : continuation -> + let firstLine = flagIndent <> flagColumn <> replicate padding ' ' <> descriptionMarker <> firstLineText <> "\n" + continuationLines = [descriptionIndent <> markerPadding <> line <> "\n" | line <- continuation] + in firstLine <> concat continuationLines + + renderStacked flagColumn descriptionLines = + case descriptionLines of + [] -> flagIndent <> flagColumn <> "\n" + firstLineText : continuation -> + flagIndent + <> flagColumn + <> "\n" + <> descriptionIndent + <> descriptionMarker + <> firstLineText + <> "\n" + <> concat [descriptionIndent <> markerPadding <> line <> "\n" | line <- continuation] + +-- | Wrap a description to the given width, one paragraph per input line. A +-- paragraph that starts with a @- @ list marker gets a hanging indent, so its +-- continuation lines align with the text after the marker. +wrapDescription :: Int -> String -> [String] +wrapDescription width description = + case concatMap wrapParagraph (lines description) of + [] -> [""] + wrapped -> wrapped + where + wrapParagraph paragraph = + case stripPrefix listMarker paragraph of + Just item -> + zipWith (<>) (listMarker : repeat listIndent) (wrapWords (width - length listMarker) item) + Nothing -> wrapWords width paragraph + + listMarker = "- " + listIndent = map (const ' ') listMarker + + wrapWords w paragraph + | null ws = [""] + | otherwise = reverse (foldl' step [""] ws) + where + ws = words paragraph + + step (current : previous) word + | null current = word : previous + | length current + 1 + length word <= w = (current <> " " <> word) : previous + | otherwise = word : current : previous + step [] _ = [] + +capitalizeDescription :: String -> (String, Bool) +capitalizeDescription = go [] + where + go acc [] = (reverse acc, False) + go acc (ch : rest) + | isAlpha ch = + if isLower ch + then (reverse acc <> (toUpper ch : rest), True) + else (reverse acc <> (ch : rest), False) + | otherwise = go (ch : acc) rest + +getOptToColumns :: GetOpt.OptDescr () -> (String, String) +getOptToColumns (GetOpt.Option shortFlags longFlags argDescr description) = + (intercalate ", " (renderShortFlags ++ renderLongFlags), description) + where + renderShortFlags = map renderShortFlag shortFlags + + renderShortFlag shortFlag = + case argDescr of + GetOpt.NoArg _ -> "-" <> [shortFlag] + GetOpt.ReqArg _ metaVar -> "-" <> [shortFlag] <> " " <> metaVar + GetOpt.OptArg _ metaVar -> "-" <> [shortFlag] <> "[" <> metaVar <> "]" + + renderLongFlags = map renderLongFlag longFlags + + renderLongFlag longFlag = + case argDescr of + GetOpt.NoArg _ -> "--" <> longFlag + GetOpt.ReqArg _ metaVar -> "--" <> longFlag <> "=" <> metaVar + GetOpt.OptArg _ metaVar -> "--" <> longFlag <> "[=" <> metaVar <> "]" + +groupSequentially :: [a] -> [(groupName, a -> Bool)] -> ([(groupName, [a])], [a]) +groupSequentially options groupingSpecs = + let step remaining (groupName, keepPred) = + let (groupMembers, leftovers) = partition keepPred remaining + in (leftovers, (groupName, groupMembers)) + (leftoverOptions, groupedBuckets) = mapAccumL step options groupingSpecs + in (groupedBuckets, leftoverOptions) + +data OptionGroupKey + = DeprecatedOptions + | UnsupportedOptions + | InstallLayoutOptions + | IrrelevantOptions + | HaddockOptions + | TestOptions + | BenchmarkOptions + | ProfilingOptions + | DependencySolvingOptions + | ExecutableBuildOptions + | LibraryBuildOptions + | CoverageOptions + | OutputAndArtifactOptions + | ConfigurePhaseOptions + | BuildPhaseControlOptions + | CompilerAndParallelismOptions + | LoggingAndReportingOptions + | IncludeAndLinkerPathOptions + | ProgramOverrideOptions + deriving (Eq) + +instance Show OptionGroupKey where + show DeprecatedOptions = "Deprecated options" + show UnsupportedOptions = "Unsupported options" + show InstallLayoutOptions = "Install layout options" + show IrrelevantOptions = "Irrelevant options" + show HaddockOptions = "Haddock options" + show TestOptions = "Test options" + show BenchmarkOptions = "Benchmark options" + show ProfilingOptions = "Profiling options" + show DependencySolvingOptions = "Dependency solving options" + show ExecutableBuildOptions = "Executable build options" + show LibraryBuildOptions = "Library build options" + show CoverageOptions = "Coverage options" + show OutputAndArtifactOptions = "Output and artifact options" + show ConfigurePhaseOptions = "Configure-phase options" + show BuildPhaseControlOptions = "Build phase control options" + show CompilerAndParallelismOptions = "Compiler and parallelism options" + show LoggingAndReportingOptions = "Logging and reporting options" + show IncludeAndLinkerPathOptions = "Include and linker path options" + show ProgramOverrideOptions = "Program override options" + +groupPredicates :: [(OptionGroupKey, OptionField a -> Bool)] +groupPredicates = + [ (DeprecatedOptions, keepDeprecatedOptions) + , (UnsupportedOptions, keepUnsupportedOptions) + , (InstallLayoutOptions, keepInstallOptions) + , (IrrelevantOptions, keepIrrelevantOptions) + , (HaddockOptions, keepHaddockOptions) + , (TestOptions, keepTestOptions) + , (BenchmarkOptions, keepBenchOptions) + , (ProfilingOptions, keepProfilingOptions) + , (DependencySolvingOptions, keepSolvingOptions) + , (ExecutableBuildOptions, keepExeOptions) + , (LibraryBuildOptions, keepLibOptions) + , (CoverageOptions, keepCoverageOptions) + , (OutputAndArtifactOptions, keepOutputOptions) + , (ConfigurePhaseOptions, keepConfigureOptions) + , (BuildPhaseControlOptions, keepPhaseOptions) + , (CompilerAndParallelismOptions, keepCompilerOptions) + , (LoggingAndReportingOptions, keepLoggingOptions) + , (IncludeAndLinkerPathOptions, keepIncludeOptions) + , (ProgramOverrideOptions, keepProgOptions) + ] + +helpText :: HelpColor -> ReplaceCommandAlias -> CommandUI (NixStyleFlags a) -> String -> String -> String +helpText helpColor replaceBuildAlias buildCommand invokedName pname = + commandSynopsis buildCommand + <> "\n\n" + <> colorizeUsageHeader helpColor (replaceBuildAlias invokedName (commandUsage buildCommand pname)) + <> maybe "" (('\n' :) . ($ pname)) (commandDescription buildCommand) + <> "\n" + <> colorizeHeader helpColor ("Flags for " <> replaceBuildAlias invokedName (commandName buildCommand) <> ":") + <> "\n" + <> ungroupedRows + <> groupedRows + <> warningSection + <> maybe "" (('\n' :) . colorizeExamplesHeader helpColor . replaceBuildAlias invokedName . ($ pname)) (commandNotes buildCommand) + where + commonHelpOptions :: [GetOpt.OptDescr ()] + commonHelpOptions = + [GetOpt.Option ['h'] ["help"] (GetOpt.NoArg ()) "Show this help text"] + + -- Match the column layout of 'Distribution.GetOpt.usageInfo', which the + -- other commands still use: after the one-space indent, flags are padded + -- to 28 columns so the description marker lands in column 30, and flags + -- wider than that are stacked above their description. + maxFlagColumnWidth :: Int + maxFlagColumnWidth = 28 + + descColumn :: Int + descColumn = maxFlagColumnWidth + 1 + + -- The legacy layout wraps descriptions to stay strictly under 47 + -- columns, so its lines reach column 78 at most; wrapping at 78 here + -- reproduces the same line breaks. + helpOutputWidth :: Int + helpOutputWidth = 78 + + (ungroupedRows, ungroupedWarnings) = + renderOptionRows + (colorizeWarningHeader helpColor) + maxFlagColumnWidth + descColumn + helpOutputWidth + (commonHelpOptions ++ concatMap optionFieldToGetOpt optsUngrouped) + + renderGroupToWidth = renderGroup helpColor maxFlagColumnWidth descColumn helpOutputWidth + renderedGroups = map renderGroupToWidth optsGrouped + + groupedRows = concatMap fst renderedGroups + + groupedWarnings = concatMap snd renderedGroups + + warningSection = + case ungroupedWarnings ++ groupedWarnings of + [] -> "" + warnings -> + "\n" + <> colorizeWarningHeader helpColor "Warnings:" + <> "\n" + <> concat [" - " <> warning <> "\n" | warning <- warnings] + + (optsGrouped, optsUngrouped) = + groupSequentially (commandOptions buildCommand ShowArgs) groupPredicates + +renderGroup :: HelpColor -> Int -> Int -> Int -> (OptionGroupKey, [OptionField a]) -> (String, [String]) +renderGroup helpColor maxFlagColumnWidth descColumn helpOutputWidth (title, options) + | null options = ("", []) + | otherwise = + let (rows, warnings) = + renderOptionRows + (colorizeWarningHeader helpColor) + maxFlagColumnWidth + descColumn + helpOutputWidth + (concatMap optionFieldToGetOpt options) + in ( "\n" + <> colorizeHeader helpColor (show title <> ":") + <> "\n" + <> rows + , warnings + ) + +-- | Leading indent of each flag row. +flagIndent :: String +flagIndent = " " + +-- | Whether command help is rendered with ANSI colour codes. Colour is for +-- terminals only; redirected output such as the generated docs is plain text. +data HelpColor = HelpColor | HelpPlain + deriving (Eq, Show) + +colorize :: HelpColor -> String -> String -> String +colorize HelpPlain _ text = text +colorize HelpColor code text = "\ESC[" <> code <> "m" <> text <> "\ESC[0m" + +colorizeHeader :: HelpColor -> String -> String +colorizeHeader helpColor = colorize helpColor "32" + +colorizeWarningHeader :: HelpColor -> String -> String +colorizeWarningHeader helpColor = colorize helpColor "31" + +colorizeUsageHeader :: HelpColor -> String -> String +colorizeUsageHeader helpColor = T.unpack . T.replace (T.pack "Usage:") (T.pack $ colorizeHeader helpColor "Usage:") . T.pack + +colorizeExamplesHeader :: HelpColor -> String -> String +colorizeExamplesHeader helpColor = T.unpack . T.replace (T.pack "Examples:") (T.pack $ colorizeHeader helpColor "Examples:") . T.pack diff --git a/cabal-install/src/Distribution/Client/CmdBuild.hs b/cabal-install/src/Distribution/Client/CmdBuild.hs index 7314187b815..0d7ad3f607b 100644 --- a/cabal-install/src/Distribution/Client/CmdBuild.hs +++ b/cabal-install/src/Distribution/Client/CmdBuild.hs @@ -1,8 +1,11 @@ +{-# LANGUAGE OverloadedStrings #-} + -- | cabal-install CLI command: build module Distribution.Client.CmdBuild - ( -- * The @build@ CLI and action + ( -- * The @build@ CLI command UI and action buildCommand , buildAction + , examples , BuildFlags (..) , defaultBuildFlags @@ -38,23 +41,44 @@ import Distribution.Client.ScriptUtils , updateContextAndWriteProjectFile , withContextAndSelectors ) -import Distribution.Client.Setup - ( GlobalFlags - , yesNoOpt - ) +import Distribution.Client.Setup (GlobalFlags, yesNoOpt) import Distribution.Simple.Command ( CommandUI (..) , option , usageAlternatives ) import Distribution.Simple.Flag (Flag, fromFlag, toFlag) -import Distribution.Simple.Utils - ( dieWithException - , wrapText - ) -import Distribution.Verbosity - ( normal - ) +import Distribution.Simple.Utils (dieWithException, wrapText) +import Distribution.Verbosity (normal) + +description :: String +description = + "Build one or more targets from within the project. The available " + ++ "targets are the packages in the project as well as individual " + ++ "components within those packages, including libraries, executables, " + ++ "test-suites or benchmarks. Targets can be specified by name or " + ++ "location. If no target is specified then the default is to build " + ++ "the package in the current directory.\n\n" + ++ "Dependencies are built or rebuilt as necessary. Additional " + ++ "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." + +examples :: String -> String -> String +examples pname invokedName = + unlines + [ "Examples:" + , "- " <> pname <> " " <> invokedName + , " Build the package in the current directory or all packages in the project" + , "- " <> pname <> " " <> invokedName <> " pkgname" + , " Build the package named pkgname in the project" + , "- " <> pname <> " " <> invokedName <> " ./pkgfoo" + , " Build the package in the ./pkgfoo directory" + , "- " <> pname <> " " <> invokedName <> " cname" + , " Build the component named cname in the project" + , "- " <> pname <> " " <> invokedName <> " cname --enable-profiling" + , " Build the component in profiling mode (including dependencies as needed)" + ] buildCommand :: CommandUI (NixStyleFlags BuildFlags) buildCommand = @@ -62,42 +86,8 @@ buildCommand = { commandName = "v2-build" , commandSynopsis = "Compile targets within the project." , commandUsage = usageAlternatives "v2-build" ["[TARGETS] [FLAGS]"] - , commandDescription = Just $ \_ -> - wrapText $ - "Build one or more targets from within the project. The available " - ++ "targets are the packages in the project as well as individual " - ++ "components within those packages, including libraries, executables, " - ++ "test-suites or benchmarks. Targets can be specified by name or " - ++ "location. If no target is specified then the default is to build " - ++ "the package in the current directory.\n\n" - ++ "Dependencies are built or rebuilt as necessary. Additional " - ++ "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." - , commandNotes = Just $ \pname -> - "Examples:\n" - ++ " " - ++ pname - ++ " v2-build\n" - ++ " Build the package in the current directory " - ++ "or all packages in the project\n" - ++ " " - ++ pname - ++ " v2-build pkgname\n" - ++ " Build the package named pkgname in the project\n" - ++ " " - ++ pname - ++ " v2-build ./pkgfoo\n" - ++ " Build the package in the ./pkgfoo directory\n" - ++ " " - ++ pname - ++ " v2-build cname\n" - ++ " Build the component named cname in the project\n" - ++ " " - ++ pname - ++ " v2-build cname --enable-profiling\n" - ++ " Build the component in profiling mode " - ++ "(including dependencies as needed)\n" + , commandDescription = Just $ \_ -> wrapText description + , commandNotes = Just $ \pname -> examples pname "v2-build" , commandDefaultFlags = defaultNixStyleFlags defaultBuildFlags , commandOptions = removeIgnoreProjectOption diff --git a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs index 2b0caff2262..a828cef6f23 100644 --- a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs +++ b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs @@ -133,7 +133,7 @@ haddockProjectAction flags _extraArgs globalFlags = do verbosity RejectNoTargets Nothing - (commandDefaultFlags CmdBuild.buildCommand) + buildDefaultFlags ["all"] globalFlags HaddockCommand @@ -199,7 +199,7 @@ haddockProjectAction flags _extraArgs globalFlags = do when localStyle $ CmdBuild.buildAction - (commandDefaultFlags CmdBuild.buildCommand) + buildDefaultFlags ["all"] globalFlags @@ -362,6 +362,7 @@ haddockProjectAction flags _extraArgs globalFlags = do where -- build all packages with appropriate haddock flags commonFlags = haddockProjectCommonFlags flags + buildDefaultFlags = NixStyleOptions.defaultNixStyleFlags CmdBuild.defaultBuildFlags verbosity = mkVerbosity defaultVerbosityHandles $ @@ -413,7 +414,7 @@ haddockProjectAction flags _extraArgs globalFlags = do (commandDefaultFlags CmdHaddock.haddockCommand) { NixStyleOptions.haddockFlags = haddockFlags , NixStyleOptions.configFlags = - (NixStyleOptions.configFlags (commandDefaultFlags CmdBuild.buildCommand)) + (NixStyleOptions.configFlags buildDefaultFlags) { configCommonFlags = commonFlags } } diff --git a/cabal-install/src/Distribution/Client/CmdInstall.hs b/cabal-install/src/Distribution/Client/CmdInstall.hs index 1215af9fc7b..a516d78fc87 100644 --- a/cabal-install/src/Distribution/Client/CmdInstall.hs +++ b/cabal-install/src/Distribution/Client/CmdInstall.hs @@ -4,9 +4,10 @@ -- | cabal-install CLI command: install module Distribution.Client.CmdInstall - ( -- * The @install@ CLI and action + ( -- * The @install@ CLI command UI and action installCommand , installAction + , examples -- * Internals exposed for testing , selectPackageTargets @@ -119,6 +120,7 @@ import Distribution.Simple.BuildPaths ) import Distribution.Simple.Command ( CommandUI (..) + , OptionField (..) , optionName , usageAlternatives ) @@ -187,7 +189,7 @@ import Distribution.System , Platform , buildOS ) -import Distribution.Types.InstalledPackageInfo +import qualified Distribution.Types.InstalledPackageInfo as IPI ( InstalledPackageInfo (..) ) import Distribution.Types.PackageId @@ -285,42 +287,39 @@ data InstallExe = InstallExe -- store. } +description :: String +description = + "Installs one or more packages. This is done by installing them " + ++ "in the store and symlinking or copying the executables in the directory " + ++ "specified by the --installdir flag (`~/.local/bin/` by default). " + ++ "If you want the installed executables to be available globally, " + ++ "make sure that the PATH environment variable contains that directory. " + ++ "\n\n" + ++ "If TARGET is a library and --lib (provisional) is used, " + ++ "it will be added to the global environment. " + ++ "When doing this, cabal will try to build a plan that includes all " + ++ "the previously installed libraries. This is currently not implemented." + +examples :: String -> String -> String +examples pname invokedName = + unlines + [ "Examples:" + , "- " <> pname <> " " <> invokedName + , " Install the package in the current directory" + , "- " <> pname <> " " <> invokedName <> " pkgname" + , " Install the package named pkgname (fetching it from hackage if necessary)" + , "- " <> pname <> " " <> invokedName <> " ./pkgfoo" + , " Install the package in the ./pkgfoo directory" + ] + installCommand :: CommandUI (NixStyleFlags ClientInstallFlags) installCommand = CommandUI { commandName = "v2-install" , commandSynopsis = "Install packages." - , commandUsage = - usageAlternatives - "v2-install" - ["[TARGETS] [FLAGS]"] - , commandDescription = Just $ \_ -> - wrapText $ - "Installs one or more packages. This is done by installing them " - ++ "in the store and symlinking or copying the executables in the directory " - ++ "specified by the --installdir flag (`~/.local/bin/` by default). " - ++ "If you want the installed executables to be available globally, " - ++ "make sure that the PATH environment variable contains that directory. " - ++ "\n\n" - ++ "If TARGET is a library and --lib (provisional) is used, " - ++ "it will be added to the global environment. " - ++ "When doing this, cabal will try to build a plan that includes all " - ++ "the previously installed libraries. This is currently not implemented." - , commandNotes = Just $ \pname -> - "Examples:\n" - ++ " " - ++ pname - ++ " v2-install\n" - ++ " Install the package in the current directory\n" - ++ " " - ++ pname - ++ " v2-install pkgname\n" - ++ " Install the package named pkgname" - ++ " (fetching it from hackage if necessary)\n" - ++ " " - ++ pname - ++ " v2-install ./pkgfoo\n" - ++ " Install the package in the ./pkgfoo directory\n" + , commandUsage = usageAlternatives "v2-install" ["[TARGETS] [FLAGS]"] + , commandDescription = Just $ \_ -> wrapText description + , commandNotes = Just $ \pname -> examples pname "v2-install" , commandOptions = \x -> filter notInstallDirOpt $ nixStyleOptions clientInstallOptions x , commandDefaultFlags = defaultNixStyleFlags defaultClientInstallFlags } @@ -956,7 +955,7 @@ prepareExeInstall installLibraries :: Verbosity -> ProjectBuildContext - -> PI.PackageIndex InstalledPackageInfo + -> PI.PackageIndex IPI.InstalledPackageInfo -> Compiler -> PackageDBStackCWD -> FilePath @@ -989,7 +988,7 @@ installLibraries . sortBy (comparing (Down . fst)) . PI.lookupPackageName installedIndex globalLatest = concatMap getLatest globalPackages - globalEntries = GhcEnvFilePackageId . installedUnitId <$> globalLatest + globalEntries = GhcEnvFilePackageId . IPI.installedUnitId <$> globalLatest baseEntries = GhcEnvFileClearPackageDbStack : fmap GhcEnvFilePackageDb packageDbs pkgEntries = @@ -1078,7 +1077,7 @@ environmentFileToSpecifiers environmentFileToSpecifiers ipi = foldMap $ \case (GhcEnvFilePackageId unitId) | Just - InstalledPackageInfo + IPI.InstalledPackageInfo { sourcePackageId = PackageIdentifier{..} , installedUnitId } <- diff --git a/cabal-install/src/Distribution/Client/Main.hs b/cabal-install/src/Distribution/Client/Main.hs index 2dd8fed4a4a..3d9fe006c74 100644 --- a/cabal-install/src/Distribution/Client/Main.hs +++ b/cabal-install/src/Distribution/Client/Main.hs @@ -182,6 +182,12 @@ import Distribution.PackageDescription , buildable ) +import Distribution.Client.Cmd.UI + ( HelpColor (..) + , cmdSpec + , commandParserByName + , parseCommandWithOptparseMany + ) import Distribution.Client.Errors import Distribution.Compat.ResponseFile import Distribution.PackageDescription.PrettyPrint @@ -271,7 +277,7 @@ import System.Directory ( doesFileExist , withCurrentDirectory ) -import System.Environment (getEnvironment, getExecutablePath, getProgName) +import System.Environment (getEnvironment, getExecutablePath, getProgName, lookupEnv) import System.FilePath ( dropExtension , splitExtension @@ -281,6 +287,7 @@ import System.FilePath ) import System.IO ( BufferMode (LineBuffering) + , hIsTerminalDevice , hPutStrLn , hSetBuffering , stderr @@ -345,7 +352,7 @@ warnIfAssertionsAreEnabled = mainWorker :: [String] -> IO () mainWorker args = do topHandler (isUserException (Proxy @(VerboseException CabalInstallException))) $ do - command <- commandsRunWithFallback (globalCommand commands) commands delegateToExternal args + command <- commandsParse args case command of CommandHelp help -> printGlobalHelp help CommandList opts -> printOptionsList opts @@ -377,6 +384,29 @@ mainWorker args = do warnIfAssertionsAreEnabled action globalFlags where + -- Tries to parse the command line arguments with optparse-applicative + -- first, and if that fails, falls back to the standard command registry. + commandsParse :: [String] -> IO (CommandParse (GlobalFlags, CommandParse Action)) + commandsParse argv = do + helpColor <- helpColorMode + case parseCommandWithOptparseMany globalCmd (parsersByName helpColor) argv of + Just parsed -> pure parsed + Nothing -> commandsRunWithFallback globalCmd commands delegateToExternal argv + + parsersByName helpColor = + [ commandParserByName helpColor CmdBuild.examples CmdBuild.buildCommand CmdBuild.buildAction + , commandParserByName helpColor CmdInstall.examples CmdInstall.installCommand CmdInstall.installAction + ] + + -- Colour the command help only when writing to a terminal and the user + -- has not opted out with NO_COLOR, so that redirected output such as the + -- generated docs stays plain text. + helpColorMode :: IO HelpColor + helpColorMode = do + isTerminal <- hIsTerminalDevice stdout + noColor <- lookupEnv "NO_COLOR" + pure $ if isTerminal && maybe True null noColor then HelpColor else HelpPlain + delegateToExternal :: [Command Action] -> String @@ -455,6 +485,8 @@ mainWorker args = do | cabalGitInfo == cabalInstallGitInfo = "(in-tree)" | otherwise = cabalGitInfo + globalCmd = globalCommand commands + commands = map commandFromSpec commandSpecs commandSpecs = [ regularCmd listCommand listAction @@ -477,14 +509,14 @@ mainWorker args = do ++ concat [ newCmd CmdConfigure.configureCommand CmdConfigure.configureAction , newCmd CmdUpdate.updateCommand CmdUpdate.updateAction - , newCmd CmdBuild.buildCommand CmdBuild.buildAction + , cmdSpec CmdBuild.buildCommand CmdBuild.buildAction , newCmd CmdRepl.replCommand CmdRepl.replAction , newCmd CmdFreeze.freezeCommand CmdFreeze.freezeAction , newCmd CmdHaddock.haddockCommand CmdHaddock.haddockAction , newCmd CmdHaddockProject.haddockProjectCommand CmdHaddockProject.haddockProjectAction - , newCmd CmdInstall.installCommand CmdInstall.installAction + , cmdSpec CmdInstall.installCommand CmdInstall.installAction , newCmd CmdRun.runCommand CmdRun.runAction , newCmd CmdTest.testCommand CmdTest.testAction , newCmd CmdBench.benchCommand CmdBench.benchAction diff --git a/cabal-install/src/Distribution/Client/NixStyleOptions.hs b/cabal-install/src/Distribution/Client/NixStyleOptions.hs index 6201df0d316..c6eda25bda8 100644 --- a/cabal-install/src/Distribution/Client/NixStyleOptions.hs +++ b/cabal-install/src/Distribution/Client/NixStyleOptions.hs @@ -1,3 +1,5 @@ +{-# LANGUAGE ViewPatterns #-} + -- | Command line options for nix-style / v2 commands. -- -- The commands take a lot of the same options, which affect how install plan @@ -8,6 +10,27 @@ module Distribution.Client.NixStyleOptions , defaultNixStyleFlags , updNixStyleCommonSetupFlags , cfgVerbosity + + -- * Option filtering/grouping predicates + , keepDeprecatedOptions + , keepUnsupportedOptions + , keepInstallOptions + , keepIrrelevantOptions + , keepHaddockOptions + , keepTestOptions + , keepBenchOptions + , keepProfilingOptions + , keepSolvingOptions + , keepExeOptions + , keepLibOptions + , keepCoverageOptions + , keepOutputOptions + , keepConfigureOptions + , keepPhaseOptions + , keepCompilerOptions + , keepLoggingOptions + , keepIncludeOptions + , keepProgOptions ) where import Distribution.Client.Compat.Prelude @@ -40,6 +63,7 @@ import Distribution.Client.Setup , liftOptions , testOptions ) +import Distribution.Simple.Utils (isInfixOf) import Distribution.Verbosity (VerbosityFlags, defaultVerbosityHandles, mkVerbosity) data NixStyleFlags a = NixStyleFlags @@ -162,3 +186,137 @@ cfgVerbosity :: VerbosityFlags -> NixStyleFlags a -> Verbosity cfgVerbosity v flags = mkVerbosity defaultVerbosityHandles $ fromFlagOrDefault v (setupVerbosity . configCommonFlags $ configFlags flags) + +keepDeprecatedOptions :: OptionField a -> Bool +keepDeprecatedOptions (optionName -> o) = "prefer-oldest" == o + +keepUnsupportedOptions :: OptionField a -> Bool +keepUnsupportedOptions (optionName -> o) = "root-cmd" == o || "allow-boot-library-installs" == o + +keepInstallOptions :: OptionField a -> Bool +keepInstallOptions (optionName -> o) = + "dir" `isSuffixOf` o + || "reinstall" `isInfixOf` o + || "run-tests" == o + || "root-cmd" == o + || "allow-boot-library-installs" == o + || "program-prefix" == o + || "program-suffix" == o + || "ipid" == o + || "cid" == o + || "user" == o + || "global" == o + || "prefix" == o + +keepIrrelevantOptions :: OptionField a -> Bool +keepIrrelevantOptions (optionName -> o) = "per-component" `isSuffixOf` o + +keepHaddockOptions :: OptionField a -> Bool +keepHaddockOptions (optionName -> o) = + "haddock" `isPrefixOf` o + || "documentation" `isSuffixOf` o + || "doc-index-file" == o + +keepTestOptions :: OptionField a -> Bool +keepTestOptions (optionName -> o) = "test" `isPrefixOf` o + +keepBenchOptions :: OptionField a -> Bool +keepBenchOptions (optionName -> o) = "bench" `isPrefixOf` o + +keepProfilingOptions :: OptionField a -> Bool +keepProfilingOptions (optionName -> o) = "profiling" `isInfixOf` o + +keepSolvingOptions :: OptionField a -> Bool +keepSolvingOptions (optionName -> o) = + "max-backjumps" == o + || "conflicts" `isInfixOf` o + || "goals" `isInfixOf` o + || "index-state" == o + || "upgrade-dependencies" == o + || "reject-unconstrained-dependencies" == o + || "prefer-oldest" == o + || "allow-older" == o + || "allow-newer" == o + || "preference" == o + || "shadow-installed-packages" == o + || "ignore-build-tools" == o + || "solver" == o + || "only-dependencies" == o + || "dependencies-only" == o + || "minimize-conflict-set" == o + || "allow-depending-on-private-libs" == o + +keepExeOptions :: OptionField a -> Bool +keepExeOptions (optionName -> o) = + "executable" `isInfixOf` o + || "split" `isInfixOf` o + || "stripping" `isInfixOf` o + +keepLibOptions :: OptionField a -> Bool +keepLibOptions (optionName -> o) = + "vanilla" `isSuffixOf` o + || "shared" `isSuffixOf` o + || "static" `isSuffixOf` o + || "bytecode" `isSuffixOf` o + || "ghci" `isSuffixOf` o + +keepCoverageOptions :: OptionField a -> Bool +keepCoverageOptions (optionName -> o) = + "coverage" `isSuffixOf` o + || "coverage" `isPrefixOf` o + +keepOutputOptions :: OptionField a -> Bool +keepOutputOptions (optionName -> o) = + "build-info" `isSuffixOf` o + || "debug-info" `isSuffixOf` o + || "deterministic" `isSuffixOf` o + || "relocatable" `isSuffixOf` o + || "write-ghc-environment-files" == o + +keepConfigureOptions :: OptionField a -> Bool +keepConfigureOptions (optionName -> o) = + "append" `isSuffixOf` o + || "backup" `isSuffixOf` o + || "configure-option" == o + +keepPhaseOptions :: OptionField a -> Bool +keepPhaseOptions (optionName -> o) = + "only-configure" == o + || "only-download" == o + || "dry-run" == o + +keepCompilerOptions :: OptionField a -> Bool +keepCompilerOptions (optionName -> o) = + "ghc" == o + || "ghcjs" == o + || "uhc" == o + || "with-compiler" == o + || "cabal-lib-version" == o + || "optimization" `isSuffixOf` o + || "semaphore" == o + || "jobs" == o + || "keep-going" == o + || "offline" == o + +keepLoggingOptions :: OptionField a -> Bool +keepLoggingOptions (optionName -> o) = + "verbose" == o + || "keep-temp-files" == o + || "build-summary" == o + || "build-log" == o + || "build-timings" == o + || "remote-build-reporting" == o + || "report-planning-failure" == o + +keepIncludeOptions :: OptionField a -> Bool +keepIncludeOptions (optionName -> o) = + "extra-include-dirs" == o + || "extra-lib-dirs" == o + || "extra-framework-dirs" == o + || "extra-prog-path" == o + || "disable-response-files" == o + +keepProgOptions :: OptionField a -> Bool +keepProgOptions (optionName -> o) = + "with-PROG" == o + || "PROG-option" `isPrefixOf` o diff --git a/cabal-install/src/Distribution/Client/Setup.hs b/cabal-install/src/Distribution/Client/Setup.hs index c1dd499eeac..b878c0629e7 100644 --- a/cabal-install/src/Distribution/Client/Setup.hs +++ b/cabal-install/src/Distribution/Client/Setup.hs @@ -524,10 +524,10 @@ globalCommand commands = , option [] ["http-transport"] - "Set a transport for http(s) requests. Accepts 'curl', 'wget', 'powershell', and 'plain-http'. (default: 'curl')" + "Set a transport for http(s) requests (default: curl)." globalHttpTransport (\v flags -> flags{globalHttpTransport = v}) - (reqArgFlag "HttpTransport") + (reqArgFlag "curl|wget|powershell|plain-http") , option [] ["store-dir", "storedir"] @@ -1955,11 +1955,14 @@ getCommand = , option [] ["index-state"] - ( "Use source package index state as it existed at a previous time. " - ++ "Accepts unix-timestamps (e.g. '@1474732068'), ISO8601 UTC timestamps " - ++ "(e.g. '2016-09-24T17:47:48Z'), or 'HEAD' (default: 'HEAD'). " - ++ "This determines which package versions are available as well as " - ++ ".cabal file revision is selected (unless --pristine is used)." + ( unlines + [ "Use source package index state as it existed at a previous time. Accepts:" + , "- a unix timestamp, e.g. '@1474732068'," + , "- an ISO8601 UTC timestamp, e.g. '2016-09-24T17:47:48Z'," + , "- 'HEAD', the default." + , "This determines which package versions are available as well as " + ++ ".cabal file revision is selected (unless --pristine is used)." + ] ) getIndexState (\v flags -> flags{getIndexState = v}) @@ -2685,9 +2688,12 @@ installOptions showOrParseArgs = , option [] ["index-state"] - ( "Use source package index state as it existed at a previous time. " - ++ "Accepts unix-timestamps (e.g. '@1474732068'), ISO8601 UTC timestamps " - ++ "(e.g. '2016-09-24T17:47:48Z'), or 'HEAD' (default: 'HEAD')." + ( unlines + [ "Use source package index state as it existed at a previous time. Accepts:" + , "- a unix timestamp, e.g. '@1474732068'," + , "- an ISO8601 UTC timestamp, e.g. '2016-09-24T17:47:48Z'," + , "- 'HEAD', the default." + ] ) installIndexState (\v flags -> flags{installIndexState = v}) @@ -2739,11 +2745,17 @@ installOptions showOrParseArgs = , option [] ["remote-build-reporting"] - "Generate build reports to send to a remote server (none, anonymous or detailed)." + ( unlines + [ "Generate build reports to send to a remote server:" + , "- none: do not report," + , "- anonymous: report without identifying information," + , "- detailed: report with full details." + ] + ) installBuildReports (\v flags -> flags{installBuildReports = v}) ( reqArg - "LEVEL" + "none|anonymous|detailed" ( parsecToReadE ( const $ "report level must be 'none', " @@ -3024,8 +3036,8 @@ initOptions _ = [ option ['i'] ["interactive"] - ( "Interactive mode. Creates a prompt tree for project creation. \n" - ++ "If -n/--non-interactive is issued, a simple project with inferred defaults \n" + ( "Interactive mode. Creates a prompt tree for project creation. " + ++ "If -n/--non-interactive is issued, a simple project with inferred defaults " ++ "is created. If --simple is issued, then sensible defaults will be chosen as well." ) IT.interactive @@ -3461,7 +3473,7 @@ actAsSetupCommand = actAsSetupBuildType (\v flags -> flags{actAsSetupBuildType = v}) ( reqArg - "BUILD-TYPE" + placeholder ( parsecToReadE ("Cannot parse build type: " ++) (fmap toFlag parsec) @@ -3470,6 +3482,9 @@ actAsSetupCommand = ) ] } + where + placeholder = intercalate "|" $ map show setupBuildTypes + setupBuildTypes = [Simple, Configure] -- ------------------------------------------------------------ @@ -3691,7 +3706,13 @@ optionSolverFlags , option [] ["prefer-version"] - "Select which version of a package that the solver should prefer. Oldest is useful to determine lower bounds in build-depends section. Latest will prefer the latest version. Installed-or-latest will prefer installed versions and the latest version otherwise." + ( unlines + [ "Select which version of a package that the solver should prefer:" + , "- oldest: useful to determine lower bounds in the build-depends section," + , "- latest: prefer the latest version," + , "- installed-or-latest: prefer installed versions and the latest version otherwise." + ] + ) getpo setpo ( reqArg diff --git a/cabal.project b/cabal.project index 76b4dccb6c9..725c5053f9d 100644 --- a/cabal.project +++ b/cabal.project @@ -19,3 +19,6 @@ package semaphore-compat if os(windows) package zlib flags: -pkg-config +bundled-c-zlib + +package cabal-testsuite + ghc-options: -Wno-unused-packages diff --git a/doc/cmd-v1-help/configure.txt b/doc/cmd-v1-help/configure.txt index 7059ef5d400..dea830c8b9f 100644 --- a/doc/cmd-v1-help/configure.txt +++ b/doc/cmd-v1-help/configure.txt @@ -41,34 +41,42 @@ Flags for v1-configure: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -79,27 +87,20 @@ Flags for v1-configure: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -120,9 +121,8 @@ Flags for v1-configure: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -140,30 +140,21 @@ Flags for v1-configure: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -182,13 +173,9 @@ Flags for v1-configure: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, diff --git a/doc/cmd-v1-help/freeze.txt b/doc/cmd-v1-help/freeze.txt index 2357900bdf0..bac680cc6c5 100644 --- a/doc/cmd-v1-help/freeze.txt +++ b/doc/cmd-v1-help/freeze.txt @@ -16,14 +16,10 @@ Flags for v1-freeze: verbosity level is 1) --dry-run # Do not freeze anything, only print what would be frozen - --enable-tests # Enable freezing of the dependencies of any + --[enable|disable]-tests # Toggle freezing of the dependencies of any tests suites in the package description file. - --disable-tests # Disable freezing of the dependencies of any - tests suites in the package description file. - --enable-benchmarks # Enable freezing of the dependencies of any - benchmarks suites in the package description - file. - --disable-benchmarks # Disable freezing of the dependencies of any + --[enable|disable]-benchmarks + # Toggle freezing of the dependencies of any benchmarks suites in the package description file. --solver=SOLVER # Select dependency solver to use (default: @@ -56,12 +52,12 @@ Flags for v1-freeze: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. diff --git a/doc/cmd-v1-help/install.txt b/doc/cmd-v1-help/install.txt index b4937a719cc..dd50fa62976 100644 --- a/doc/cmd-v1-help/install.txt +++ b/doc/cmd-v1-help/install.txt @@ -52,34 +52,42 @@ Flags for v1-install: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -90,27 +98,20 @@ Flags for v1-install: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -131,9 +132,8 @@ Flags for v1-install: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -151,30 +151,21 @@ Flags for v1-install: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -193,13 +184,9 @@ Flags for v1-install: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, @@ -215,8 +202,8 @@ Flags for v1-install: --write-ghc-environment-files=always|never|ghc8.4.4+ # Whether to create a .ghc.environment file after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation + --[enable|disable]-documentation + # Toggle building of documentation --doc-index-file=TEMPLATE # A central index of haddock API documentation (template cannot use $pkgid) --dry-run # Do not install anything, only print what would @@ -251,12 +238,12 @@ Flags for v1-install: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -283,10 +270,11 @@ Flags for v1-install: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --symlink-bindir=DIR # Add symlinks to installed executables into this directory. @@ -294,14 +282,18 @@ Flags for v1-install: can use $pkgid, $compiler, $os, $arch) --build-log=TEMPLATE # Log all builds to file (name template can use $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL + --remote-build-reporting=none|anonymous|detailed # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible + --[enable|disable]-per-component + # Toggle Per-component builds when possible --run-tests # Run package test suites during installation. --semaphore # Use a semaphore so GHC can compile components in parallel @@ -344,13 +336,18 @@ Flags for v1-install: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v1-help/reconfigure.txt b/doc/cmd-v1-help/reconfigure.txt index 15d821d1358..8985ae78414 100644 --- a/doc/cmd-v1-help/reconfigure.txt +++ b/doc/cmd-v1-help/reconfigure.txt @@ -40,34 +40,42 @@ Flags for v1-reconfigure: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -78,27 +86,20 @@ Flags for v1-reconfigure: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -119,9 +120,8 @@ Flags for v1-reconfigure: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -139,30 +139,21 @@ Flags for v1-reconfigure: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -181,13 +172,9 @@ Flags for v1-reconfigure: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, diff --git a/doc/cmd-v1-help/test.txt b/doc/cmd-v1-help/test.txt index 6732042f66a..2c1e85409e3 100644 --- a/doc/cmd-v1-help/test.txt +++ b/doc/cmd-v1-help/test.txt @@ -42,13 +42,18 @@ Flags for v1-test: --machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --fail-when-no-test-suites # Exit with failure when no test suites are diff --git a/doc/cmd-v2-help/bench.txt b/doc/cmd-v2-help/bench.txt index c5ba5a99f02..13a2c0b5ac0 100644 --- a/doc/cmd-v2-help/bench.txt +++ b/doc/cmd-v2-help/bench.txt @@ -45,34 +45,42 @@ Flags for bench: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -83,27 +91,20 @@ Flags for bench: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -124,9 +125,8 @@ Flags for bench: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -144,30 +144,21 @@ Flags for bench: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -186,13 +177,9 @@ Flags for bench: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, @@ -208,8 +195,8 @@ Flags for bench: --write-ghc-environment-files=always|never|ghc8.4.4+ # Whether to create a .ghc.environment file after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation + --[enable|disable]-documentation + # Toggle building of documentation --doc-index-file=TEMPLATE # A central index of haddock API documentation (template cannot use $pkgid) --dry-run # Do not install anything, only print what would @@ -244,12 +231,12 @@ Flags for bench: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -276,23 +263,28 @@ Flags for bench: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) --build-log=TEMPLATE # Log all builds to file (name template can use $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL + --remote-build-reporting=none|anonymous|detailed # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible + --[enable|disable]-per-component + # Toggle Per-component builds when possible --run-tests # Run package test suites during installation. --semaphore # Use a semaphore so GHC can compile components in parallel @@ -335,13 +327,18 @@ Flags for bench: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/build.txt b/doc/cmd-v2-help/build.txt index c4d2f57a62f..5955c7fb42e 100644 --- a/doc/cmd-v2-help/build.txt +++ b/doc/cmd-v2-help/build.txt @@ -14,17 +14,65 @@ configuration from the 'cabal.project', 'cabal.project.local' and other files. Flags for build: -h, --help # Show this help text - -v[n], --verbose[=n] # Control verbosity (n is 0--3, default - verbosity level is 1) - --builddir=DIR # The directory where Cabal puts generated build - files (default dist) - --keep-temp-files # Keep temporary files. -g, --ghc # Compile with GHC --ghcjs # Compile with GHCJS --uhc # Compile with UHC - -w PATH or -wPATH, --with-compiler=PATH - # Give the path to a particular compiler --with-hc-pkg=PATH # Give the path to the package tool + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS, --flags=FLAGS # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + + -c CONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + --project-file-parser=PARSER # Set the parser to use for the project file + +Deprecated options: + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + +Unsupported options: + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --root-cmd=COMMAND # (No longer supported, do not use.) + +Install layout options: + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) --prefix=DIR # Bake this prefix in preparation of installation --bindir=DIR # Installation directory for executables @@ -45,158 +93,152 @@ Flags for build: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries - -p, --enable-library-profiling - # Enable Library profiling - --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) - --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). - --library-profiling-detail=level - # Profiling detail level for libraries only. - -O[n], --enable-optimization[=n] - # Build with optimization (n is 0--2, default is - 1) - --disable-optimization # Build without optimization - --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) - --disable-debug-info # Don't emit debug info - --enable-build-info # Enable build information generation during - project building - --disable-build-info # Disable build information generation during - project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded - definitions can be dropped from the final - executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to - reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to - reduce binary sizes - --configure-option=OPT # Extra option for configure - --user # Enable doing a per-user installation - --global # Disable doing a per-user installation - --package-db=DB # Append the given package database to the list - of package databases used (to satisfy - dependencies and register into). May be a - specific file, 'global' or 'user'. The initial - list is ['global'], ['global', 'user'], or - ['global', $sandbox], depending on context. - Use 'clear' to reset the list to empty. See - the user guide for details. - -f FLAGS or -fFLAGS, --flags=FLAGS - # Force values for the given flags in Cabal - conditionals in the .cabal file. E.g., - --flags="debug -usebytestrings" forces the - flag "debug" to true and "usebytestrings" to - false. - --extra-include-dirs=PATH # A list of directories to search for header - files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible - (used by the test suite) --ipid=IPID # Installed package ID to compile this package as --cid=CID # Installed component ID to compile this component as - --extra-lib-dirs=PATH # A list of directories to search for external - libraries - --extra-lib-dirs-static=PATH # A list of directories to search for external - libraries when linking fully static - executables - --extra-framework-dirs=PATH # A list of directories to search for external - frameworks (OS X only) - --extra-prog-path=PATH # A list of directories to search for required - programs (in addition to the normal search - locations) - --instantiate-with=NAME=MOD # A mapping of signature names to concrete - module instantiations. - --enable-tests # Enable dependency checking and compilation for + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --run-tests # Run package test suites during installation. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --project-dir=DIR # Set the path of the project directory + +Irrelevant options: + --[enable|disable]-per-component + # Toggle Per-component builds when possible + +Haddock options: + --[enable|disable]-documentation + # Toggle building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + + --haddock-hyperlink-source, --haddock-hyperlink-sources, --haddock-hyperlinked-source + # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-use-unicode # Pass --use-unicode option to haddock + +Test options: + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program - Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + +Benchmark options: + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. - (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) - --disable-response-files # Enable workaround for old versions of programs - like "ar" that do not support @file arguments + + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + +Profiling options: + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --[enable|disable]-profiling # Toggle Executable and library profiling + + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). + + --library-profiling-detail=level + # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). + +Dependency solving options: --allow-depending-on-private-libs # Allow depending on private libraries. If set, the library visibility check MUST be done externally. - --coverage-for=UNITID # A list of unit-ids of libraries to include in - the Haskell Program Coverage report. --ignore-build-tools # Ignore build tool dependencies. If set, declared build tools needn't be found for compilation to proceed. - --with-PROG=PATH # Give the path to PROG - --PROG-option=OPT # Give an extra option to PROG (passed directly - to PROG as a single argument) - --PROG-options=OPTS # Give extra options to PROG (split on spaces, - use "" to prevent splitting) - --cabal-lib-version=VERSION # Select which version of the Cabal lib to use - to build packages (useful for testing). - --enable-append # Enable appending the new config to the old - config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before - any alterations - -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT - # Specify constraints on a package (version, - installed/source, flags) --preference=CONSTRAINT # Specify preferences (soft constraints) on the version of a package --solver=SOLVER # Select dependency solver to use (default: @@ -205,17 +247,6 @@ Flags for build: DEPS --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or DEPS - --write-ghc-environment-files=always|never|ghc8.4.4+ - # Whether to create a .ghc.environment file - after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation - --doc-index-file=TEMPLATE # A central index of haddock API documentation - (template cannot use $pkgid) - --dry-run # Do not install anything, only print what would - be installed. - --only-download # Do not build anything, only fetch the - packages. --max-backjumps=NUM # Maximum number of backjumps allowed while solving (default: 4000). Use a negative number to enable unlimited backtracking. Use 0 to @@ -238,37 +269,14 @@ Flags for build: independent. If several goals depend on the same package, different versions can be chosen. - --prefer-oldest # Prefer the oldest (instead of the latest) - versions of packages available. Useful to - determine lower bounds in the build-depends - section. - --prefer-version=oldest|latest|installed-or-latest - # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. - --strong-flags # Do not defer flag choices (this used to be the - default in cabal-install <= 1.20). - --allow-boot-library-installs - # Allow cabal to install base, ghc-prim, - integer-simple, integer-gmp, and - template-haskell. + --reject-unconstrained-dependencies=none|all # Require these packages to have constraints on them if they are to be selected (default: none). - --reinstall # Install even if it means installing the same - version again. - --avoid-reinstalls # Do not select versions that would - destructively overwrite installed packages. - --force-reinstalls # Reinstall packages even if they will most - likely break other installed packages. --upgrade-dependencies # Pick the latest version for all dependencies, rather than trying to pick an installed version. @@ -276,110 +284,163 @@ Flags for build: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). - --root-cmd=COMMAND # (No longer supported, do not use.) + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. + +Executable build options: + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + + --[enable|disable]-executable-static + # Toggle Executable fully static linking + + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + + --[enable|disable]-split-objs + # Toggle split library into smaller objects to + reduce binary sizes (GHC 6.6+) + + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to + reduce binary sizes + + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to + reduce binary sizes + +Library build options: + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + + --[enable|disable]-library-bytecode + # Toggle Bytecode library + + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + +Coverage options: + --[enable|disable]-coverage # Toggle build package with Haskell Program + Coverage. (GHC only) + + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + +Output and artifact options: + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible + (used by the test suite) + + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. + (GHC only) + + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + +Configure-phase options: + --configure-option=OPT # Extra option for configure + --[enable|disable]-append # Toggle appending the new config to the old + config file + --[enable|disable]-backup # Toggle the backup of the config file before + any alterations + +Build phase control options: + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --only-configure # Instead of performing a full build just run + the configure step + +Compiler and parallelism options: + -w PATH, --with-compiler=PATH + # Give the path to a particular compiler + + -O[n], --enable-optimization[=n], --enable-optimisation[=n] + # Build with optimization (n is 0--2, default is + 1) + + --disable-optimization, --disable-optimisation + # Build without optimization + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + +Logging and reporting options: + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --keep-temp-files # Keep temporary files. --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) --build-log=TEMPLATE # Log all builds to file (name template can use $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL + + --remote-build-reporting=none|anonymous|detailed # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible - --run-tests # Run package test suites during installation. - --semaphore # Use a semaphore so GHC can compile components - in parallel - -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no - NUM is given). - --keep-going # After a build failure, continue to build other - unaffected packages. - --offline # Don't download packages from the Internet. --build-timings # Print elapsed time for each build phase. - --haddock-hoogle # Generate a hoogle database - --haddock-html # Generate HTML documentation (the default) - --haddock-html-location=URL # Location of HTML documentation for - pre-requisite packages - --haddock-for-hackage # Collection of flags to generate documentation - suitable for upload to hackage - --haddock-executables # Run haddock for Executables targets - --haddock-tests # Run haddock for Test Suite targets - --haddock-benchmarks # Run haddock for Benchmark targets - --haddock-all # Run haddock for all targets - --haddock-internal # Run haddock for internal modules and include - all symbols - --haddock-css=PATH # Use PATH as the haddock stylesheet - --haddock-hyperlink-source # Hyperlink the documentation to the source code - --haddock-quickjump # Generate an index for interactive - documentation navigation - --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet - --haddock-contents-location=URL - # Bake URL in as the location for the contents - page - --haddock-base-url=URL # Base URL for static files. - --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files - --haddock-output-dir=DIR # Generate haddock documentation into this - directory. This flag is provided as a - technology preview and is subject to change in - the next releases. - --haddock-use-unicode # Pass --use-unicode option to haddock - --test-log=TEMPLATE # Log all test suite results to file (name - template can use $pkgid, $compiler, $os, - $arch, $test-suite, $result) - --test-machine-log=TEMPLATE # Produce a machine-readable log file (name - template can use $pkgid, $compiler, $os, - $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. - --test-keep-tix-files # Keep .tix files for HPC between test runs - --test-wrapper=FILE # Run test through a wrapper. - --test-fail-when-no-test-suites - # Exit with failure when no test suites are - found. - --test-options=TEMPLATES # Give extra options to test executables (split - on spaces, use "" to prevent splitting; name - templates can use $pkgid, $compiler, $os, - $arch, $test-suite) - --test-option=TEMPLATE # Give extra option to test executables (passed - directly as a single argument; name template - can use $pkgid, $compiler, $os, $arch, - $test-suite) - --benchmark-options=TEMPLATES - # Give extra options to benchmark executables - (split on spaces, use "" to prevent splitting; - name templates can use $pkgid, $compiler, $os, - $arch, $benchmark) - --benchmark-option=TEMPLATE # Give extra option to benchmark executables - (passed directly as a single argument; name - template can use $pkgid, $compiler, $os, - $arch, $benchmark) - --project-dir=DIR # Set the path of the project directory - --project-file=FILE # Set the path of the cabal.project file - (relative to the project directory when - relative) - --project-file-parser=PARSER # Set the parser to use for the project file - --only-configure # Instead of performing a full build just run - the configure step + +Include and linker path options: + --extra-include-dirs=PATH # A list of directories to search for header + files + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + +Program override options: + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) Examples: - cabal build +- cabal build Build the package in the current directory or all packages in the project - cabal build pkgname +- cabal build pkgname Build the package named pkgname in the project - cabal build ./pkgfoo +- cabal build ./pkgfoo Build the package in the ./pkgfoo directory - cabal build cname +- cabal build cname Build the component named cname in the project - cabal build cname --enable-profiling +- cabal build cname --enable-profiling Build the component in profiling mode (including dependencies as needed) diff --git a/doc/cmd-v2-help/configure.txt b/doc/cmd-v2-help/configure.txt index c97f66063b1..583fb24bf8d 100644 --- a/doc/cmd-v2-help/configure.txt +++ b/doc/cmd-v2-help/configure.txt @@ -58,34 +58,42 @@ Flags for configure: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -96,27 +104,20 @@ Flags for configure: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -137,9 +138,8 @@ Flags for configure: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -157,30 +157,21 @@ Flags for configure: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -199,13 +190,9 @@ Flags for configure: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, @@ -221,8 +208,8 @@ Flags for configure: --write-ghc-environment-files=always|never|ghc8.4.4+ # Whether to create a .ghc.environment file after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation + --[enable|disable]-documentation + # Toggle building of documentation --doc-index-file=TEMPLATE # A central index of haddock API documentation (template cannot use $pkgid) --dry-run # Do not install anything, only print what would @@ -257,12 +244,12 @@ Flags for configure: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -289,23 +276,28 @@ Flags for configure: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) --build-log=TEMPLATE # Log all builds to file (name template can use $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL + --remote-build-reporting=none|anonymous|detailed # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible + --[enable|disable]-per-component + # Toggle Per-component builds when possible --run-tests # Run package test suites during installation. --semaphore # Use a semaphore so GHC can compile components in parallel @@ -348,13 +340,18 @@ Flags for configure: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/exec.txt b/doc/cmd-v2-help/exec.txt index ea4368e9cd8..631207aa0cb 100644 --- a/doc/cmd-v2-help/exec.txt +++ b/doc/cmd-v2-help/exec.txt @@ -47,34 +47,42 @@ Flags for exec: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -85,27 +93,20 @@ Flags for exec: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -126,9 +127,8 @@ Flags for exec: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -146,30 +146,21 @@ Flags for exec: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -188,13 +179,9 @@ Flags for exec: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, @@ -210,8 +197,8 @@ Flags for exec: --write-ghc-environment-files=always|never|ghc8.4.4+ # Whether to create a .ghc.environment file after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation + --[enable|disable]-documentation + # Toggle building of documentation --doc-index-file=TEMPLATE # A central index of haddock API documentation (template cannot use $pkgid) --dry-run # Do not install anything, only print what would @@ -246,12 +233,12 @@ Flags for exec: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -278,23 +265,28 @@ Flags for exec: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) --build-log=TEMPLATE # Log all builds to file (name template can use $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL + --remote-build-reporting=none|anonymous|detailed # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible + --[enable|disable]-per-component + # Toggle Per-component builds when possible --run-tests # Run package test suites during installation. --semaphore # Use a semaphore so GHC can compile components in parallel @@ -337,13 +329,18 @@ Flags for exec: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/fetch.txt b/doc/cmd-v2-help/fetch.txt index b66044ab234..1143a7d4b0a 100644 --- a/doc/cmd-v2-help/fetch.txt +++ b/doc/cmd-v2-help/fetch.txt @@ -13,18 +13,13 @@ Flags for fetch: --no-dependencies # Ignore dependencies --dry-run # Do not install anything, only print what would be installed. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. --solver=SOLVER # Select dependency solver to use (default: modular). Choices: modular. --max-backjumps=NUM # Maximum number of backjumps allowed while @@ -55,12 +50,12 @@ Flags for fetch: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. diff --git a/doc/cmd-v2-help/freeze.txt b/doc/cmd-v2-help/freeze.txt index 64269ce7f8e..6c24c8c411f 100644 --- a/doc/cmd-v2-help/freeze.txt +++ b/doc/cmd-v2-help/freeze.txt @@ -50,34 +50,42 @@ Flags for freeze: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -88,27 +96,20 @@ Flags for freeze: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -129,9 +130,8 @@ Flags for freeze: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -149,30 +149,21 @@ Flags for freeze: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -191,13 +182,9 @@ Flags for freeze: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, @@ -213,8 +200,8 @@ Flags for freeze: --write-ghc-environment-files=always|never|ghc8.4.4+ # Whether to create a .ghc.environment file after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation + --[enable|disable]-documentation + # Toggle building of documentation --doc-index-file=TEMPLATE # A central index of haddock API documentation (template cannot use $pkgid) --dry-run # Do not install anything, only print what would @@ -249,12 +236,12 @@ Flags for freeze: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -281,23 +268,28 @@ Flags for freeze: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) --build-log=TEMPLATE # Log all builds to file (name template can use $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL + --remote-build-reporting=none|anonymous|detailed # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible + --[enable|disable]-per-component + # Toggle Per-component builds when possible --run-tests # Run package test suites during installation. --semaphore # Use a semaphore so GHC can compile components in parallel @@ -340,13 +332,18 @@ Flags for freeze: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/gen-bounds.txt b/doc/cmd-v2-help/gen-bounds.txt index 8764aac5bda..3aabfa33349 100644 --- a/doc/cmd-v2-help/gen-bounds.txt +++ b/doc/cmd-v2-help/gen-bounds.txt @@ -36,34 +36,42 @@ Flags for gen-bounds: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -74,27 +82,20 @@ Flags for gen-bounds: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -115,9 +116,8 @@ Flags for gen-bounds: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -135,30 +135,21 @@ Flags for gen-bounds: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -177,13 +168,9 @@ Flags for gen-bounds: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, @@ -199,8 +186,8 @@ Flags for gen-bounds: --write-ghc-environment-files=always|never|ghc8.4.4+ # Whether to create a .ghc.environment file after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation + --[enable|disable]-documentation + # Toggle building of documentation --doc-index-file=TEMPLATE # A central index of haddock API documentation (template cannot use $pkgid) --dry-run # Do not install anything, only print what would @@ -235,12 +222,12 @@ Flags for gen-bounds: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -267,23 +254,28 @@ Flags for gen-bounds: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) --build-log=TEMPLATE # Log all builds to file (name template can use $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL + --remote-build-reporting=none|anonymous|detailed # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible + --[enable|disable]-per-component + # Toggle Per-component builds when possible --run-tests # Run package test suites during installation. --semaphore # Use a semaphore so GHC can compile components in parallel @@ -326,13 +318,18 @@ Flags for gen-bounds: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/get.txt b/doc/cmd-v2-help/get.txt index 8f4331e5cf4..f90e5de9c21 100644 --- a/doc/cmd-v2-help/get.txt +++ b/doc/cmd-v2-help/get.txt @@ -17,13 +17,14 @@ Flags for get: # Copy the package's source repository (ie git clone, darcs get, etc as appropriate). --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). This determines which - package versions are available as well as - .cabal file revision is selected (unless - --pristine is used). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. + This determines which package versions are + available as well as .cabal file revision is + selected (unless --pristine is used). --only-package-description # Unpack only the package description file. --package-description-only # A synonym for --only-package-description. --pristine # Unpack the original pristine tarball, rather diff --git a/doc/cmd-v2-help/haddock.txt b/doc/cmd-v2-help/haddock.txt index 2e5046e47f7..59182dfdb63 100644 --- a/doc/cmd-v2-help/haddock.txt +++ b/doc/cmd-v2-help/haddock.txt @@ -50,34 +50,42 @@ Flags for haddock: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -88,27 +96,20 @@ Flags for haddock: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -129,9 +130,8 @@ Flags for haddock: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -149,30 +149,21 @@ Flags for haddock: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -191,13 +182,9 @@ Flags for haddock: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, @@ -213,8 +200,8 @@ Flags for haddock: --write-ghc-environment-files=always|never|ghc8.4.4+ # Whether to create a .ghc.environment file after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation + --[enable|disable]-documentation + # Toggle building of documentation --doc-index-file=TEMPLATE # A central index of haddock API documentation (template cannot use $pkgid) --dry-run # Do not install anything, only print what would @@ -249,12 +236,12 @@ Flags for haddock: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -281,23 +268,28 @@ Flags for haddock: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) --build-log=TEMPLATE # Log all builds to file (name template can use $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL + --remote-build-reporting=none|anonymous|detailed # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible + --[enable|disable]-per-component + # Toggle Per-component builds when possible --run-tests # Run package test suites during installation. --semaphore # Use a semaphore so GHC can compile components in parallel @@ -340,13 +332,18 @@ Flags for haddock: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/help.txt b/doc/cmd-v2-help/help.txt index dba7ffe6948..f4044a696c5 100644 --- a/doc/cmd-v2-help/help.txt +++ b/doc/cmd-v2-help/help.txt @@ -105,10 +105,9 @@ Global flags: --config-file=FILE # Set an alternate location for the config file --ignore-expiry # Ignore expiry dates on signed metadata (use only in exceptional circumstances) - --http-transport=HttpTransport - # Set a transport for http(s) requests. Accepts - 'curl', 'wget', 'powershell', and - 'plain-http'. (default: 'curl') + --http-transport=curl|wget|powershell|plain-http + # Set a transport for http(s) requests (default: + curl). --store-dir=DIR # The location of the build store --active-repositories=REPOS # The active package repositories (set to ':none' to disable all repositories) diff --git a/doc/cmd-v2-help/install.txt b/doc/cmd-v2-help/install.txt index 8850a2a2890..ec185361f04 100644 --- a/doc/cmd-v2-help/install.txt +++ b/doc/cmd-v2-help/install.txt @@ -15,80 +15,10 @@ implemented. Flags for install: -h, --help # Show this help text - -v[n], --verbose[=n] # Control verbosity (n is 0--3, default - verbosity level is 1) - --builddir=DIR # The directory where Cabal puts generated build - files (default dist) - --keep-temp-files # Keep temporary files. -g, --ghc # Compile with GHC --ghcjs # Compile with GHCJS --uhc # Compile with UHC - -w PATH or -wPATH, --with-compiler=PATH - # Give the path to a particular compiler --with-hc-pkg=PATH # Give the path to the package tool - --program-prefix=PREFIX # Prefix to be applied to installed executables - --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries - -p, --enable-library-profiling - # Enable Library profiling - --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) - --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). - --library-profiling-detail=level - # Profiling detail level for libraries only. - -O[n], --enable-optimization[=n] - # Build with optimization (n is 0--2, default is - 1) - --disable-optimization # Build without optimization - --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) - --disable-debug-info # Don't emit debug info - --enable-build-info # Enable build information generation during - project building - --disable-build-info # Disable build information generation during - project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded - definitions can be dropped from the final - executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to - reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to - reduce binary sizes - --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation --global # Disable doing a per-user installation --package-db=DB # Append the given package database to the list @@ -99,192 +29,95 @@ Flags for install: ['global', $sandbox], depending on context. Use 'clear' to reset the list to empty. See the user guide for details. - -f FLAGS or -fFLAGS, --flags=FLAGS - # Force values for the given flags in Cabal + -f FLAGS, --flags=FLAGS # Force values for the given flags in Cabal conditionals in the .cabal file. E.g., --flags="debug -usebytestrings" forces the flag "debug" to true and "usebytestrings" to false. - --extra-include-dirs=PATH # A list of directories to search for header - files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible - (used by the test suite) - --ipid=IPID # Installed package ID to compile this package - as - --cid=CID # Installed component ID to compile this - component as - --extra-lib-dirs=PATH # A list of directories to search for external - libraries - --extra-lib-dirs-static=PATH # A list of directories to search for external - libraries when linking fully static - executables - --extra-framework-dirs=PATH # A list of directories to search for external - frameworks (OS X only) - --extra-prog-path=PATH # A list of directories to search for required - programs (in addition to the normal search - locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for - test suites listed in the package description - file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program - Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for - benchmarks listed in the package description - file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. - (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments - --allow-depending-on-private-libs - # Allow depending on private libraries. If set, - the library visibility check MUST be done - externally. - --coverage-for=UNITID # A list of unit-ids of libraries to include in - the Haskell Program Coverage report. - --ignore-build-tools # Ignore build tool dependencies. If set, - declared build tools needn't be found for - compilation to proceed. - --with-PROG=PATH # Give the path to PROG - --PROG-option=OPT # Give an extra option to PROG (passed directly - to PROG as a single argument) - --PROG-options=OPTS # Give extra options to PROG (split on spaces, - use "" to prevent splitting) - --cabal-lib-version=VERSION # Select which version of the Cabal lib to use - to build packages (useful for testing). - --enable-append # Enable appending the new config to the old - config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before - any alterations - -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + + -c CONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, installed/source, flags) - --preference=CONSTRAINT # Specify preferences (soft constraints) on the - version of a package - --solver=SOLVER # Select dependency solver to use (default: - modular). Choices: modular. - --allow-older[=DEPS] # Ignore lower bounds in all dependencies or - DEPS - --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or - DEPS - --write-ghc-environment-files=always|never|ghc8.4.4+ - # Whether to create a .ghc.environment file - after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation - --doc-index-file=TEMPLATE # A central index of haddock API documentation - (template cannot use $pkgid) - --dry-run # Do not install anything, only print what would - be installed. - --only-download # Do not build anything, only fetch the - packages. - --max-backjumps=NUM # Maximum number of backjumps allowed while - solving (default: 4000). Use a negative number - to enable unlimited backtracking. Use 0 to - disable backtracking completely. - --reorder-goals # Try to reorder goals according to certain - heuristics. Slows things down on average, but - may make backtracking faster for some - packages. - --count-conflicts # Try to speed up solving by preferring goals - that are involved in a lot of conflicts - (default). - --fine-grained-conflicts # Skip a version of a package if it does not - resolve the conflicts encountered in the last - version, as a solver optimization (default). - --minimize-conflict-set # When there is no solution, try to improve the - error message by finding a minimal conflict - set (default: false). May increase run time - significantly. - --independent-goals # Treat several goals on the command line as - independent. If several goals depend on the - same package, different versions can be - chosen. - --prefer-oldest # Prefer the oldest (instead of the latest) - versions of packages available. Useful to - determine lower bounds in the build-depends - section. + --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. - --shadow-installed-packages # If multiple package instances of the same - version are installed, treat all but one as - shadowed. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --strong-flags # Do not defer flag choices (this used to be the default in cabal-install <= 1.20). + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + -z, --ignore-project # Ignore local project configuration (unless + --project-dir or --project-file is also set) + --project-file-parser=PARSER # Set the parser to use for the project file + --lib # Install libraries rather than executables from + the target package (provisional, see + https://github.com/haskell/cabal/issues/6481 + for more information). + --package-env=ENV, --env=ENV # Set the environment file that may be modified. + + --overwrite-policy=always|never|prompt + # How to handle already existing symlinks. + + --install-method=default|copy|symlink + # How to install the executables. + +Deprecated options: + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + +Unsupported options: --allow-boot-library-installs # Allow cabal to install base, ghc-prim, integer-simple, integer-gmp, and template-haskell. - --reject-unconstrained-dependencies=none|all - # Require these packages to have constraints on - them if they are to be selected (default: - none). + --root-cmd=COMMAND # (No longer supported, do not use.) + +Install layout options: + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as --reinstall # Install even if it means installing the same version again. --avoid-reinstalls # Do not select versions that would destructively overwrite installed packages. --force-reinstalls # Reinstall packages even if they will most likely break other installed packages. - --upgrade-dependencies # Pick the latest version for all dependencies, - rather than trying to pick an installed - version. - --only-dependencies # Install only the dependencies necessary to - build the given packages - --dependencies-only # A synonym for --only-dependencies - --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). - --root-cmd=COMMAND # (No longer supported, do not use.) - --build-summary=TEMPLATE # Save build summaries to file (name template - can use $pkgid, $compiler, $os, $arch) - --build-log=TEMPLATE # Log all builds to file (name template can use - $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL - # Generate build reports to send to a remote - server (none, anonymous or detailed). - --report-planning-failure # Generate build reports when the dependency - solver fails. This is used by the Hackage - build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible --run-tests # Run package test suites during installation. - --semaphore # Use a semaphore so GHC can compile components - in parallel - -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no - NUM is given). - --keep-going # After a build failure, continue to build other - unaffected packages. - --offline # Don't download packages from the Internet. - --build-timings # Print elapsed time for each build phase. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --project-dir=DIR # Set the path of the project directory + --installdir=DIR # Where to install (by symlinking or copying) + the executables in. + +Irrelevant options: + --[enable|disable]-per-component + # Toggle Per-component builds when possible + +Haddock options: + --[enable|disable]-documentation + # Toggle building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) --haddock-hoogle # Generate a hoogle database --haddock-html # Generate HTML documentation (the default) --haddock-html-location=URL # Location of HTML documentation for @@ -298,35 +131,45 @@ Flags for install: --haddock-internal # Run haddock for internal modules and include all symbols --haddock-css=PATH # Use PATH as the haddock stylesheet - --haddock-hyperlink-source # Hyperlink the documentation to the source code + + --haddock-hyperlink-source, --haddock-hyperlink-sources, --haddock-hyperlinked-source + # Hyperlink the documentation to the source code --haddock-quickjump # Generate an index for interactive documentation navigation --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL # Bake URL in as the location for the contents page --haddock-base-url=URL # Base URL for static files. - --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files - --haddock-output-dir=DIR # Generate haddock documentation into this - directory. This flag is provided as a - technology preview and is subject to change in - the next releases. --haddock-use-unicode # Pass --use-unicode option to haddock + +Test options: + --[enable|disable]-tests # Toggle dependency checking and compilation for + test suites listed in the package description + file. --test-log=TEMPLATE # Log all test suite results to file (name template can use $pkgid, $compiler, $os, $arch, $test-suite, $result) --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites # Exit with failure when no test suites are found. @@ -338,6 +181,13 @@ Flags for install: directly as a single argument; name template can use $pkgid, $compiler, $os, $arch, $test-suite) + +Benchmark options: + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for + benchmarks listed in the package description + file. + --benchmark-options=TEMPLATES # Give extra options to benchmark executables (split on spaces, use "" to prevent splitting; @@ -347,29 +197,242 @@ Flags for install: (passed directly as a single argument; name template can use $pkgid, $compiler, $os, $arch, $benchmark) - --project-dir=DIR # Set the path of the project directory - --project-file=FILE # Set the path of the cabal.project file - (relative to the project directory when - relative) - -z, --ignore-project # Ignore local project configuration (unless - --project-dir or --project-file is also set) - --project-file-parser=PARSER # Set the parser to use for the project file - --lib # Install libraries rather than executables from - the target package (provisional, see - https://github.com/haskell/cabal/issues/6481 - for more information). - --package-env=ENV # Set the environment file that may be modified. - --overwrite-policy=always|never|prompt - # How to handle already existing symlinks. - --install-method=default|copy|symlink - # How to install the executables. - --installdir=DIR # Where to install (by symlinking or copying) - the executables in. + +Profiling options: + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --[enable|disable]-profiling # Toggle Executable and library profiling + + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). + + --library-profiling-detail=level + # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). + +Dependency solving options: + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. + +Executable build options: + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + + --[enable|disable]-executable-static + # Toggle Executable fully static linking + + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + + --[enable|disable]-split-objs + # Toggle split library into smaller objects to + reduce binary sizes (GHC 6.6+) + + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to + reduce binary sizes + + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to + reduce binary sizes + +Library build options: + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + + --[enable|disable]-library-bytecode + # Toggle Bytecode library + + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + +Coverage options: + --[enable|disable]-coverage # Toggle build package with Haskell Program + Coverage. (GHC only) + + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + +Output and artifact options: + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible + (used by the test suite) + + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. + (GHC only) + + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + +Configure-phase options: + --configure-option=OPT # Extra option for configure + --[enable|disable]-append # Toggle appending the new config to the old + config file + --[enable|disable]-backup # Toggle the backup of the config file before + any alterations + +Build phase control options: + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + +Compiler and parallelism options: + -w PATH, --with-compiler=PATH + # Give the path to a particular compiler + + -O[n], --enable-optimization[=n], --enable-optimisation[=n] + # Build with optimization (n is 0--2, default is + 1) + + --disable-optimization, --disable-optimisation + # Build without optimization + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + +Logging and reporting options: + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --keep-temp-files # Keep temporary files. + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + + --remote-build-reporting=none|anonymous|detailed + # Generate build reports to send to a remote + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --build-timings # Print elapsed time for each build phase. + +Include and linker path options: + --extra-include-dirs=PATH # A list of directories to search for header + files + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + +Program override options: + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) Examples: - cabal install +- cabal install Install the package in the current directory - cabal install pkgname +- cabal install pkgname Install the package named pkgname (fetching it from hackage if necessary) - cabal install ./pkgfoo +- cabal install ./pkgfoo Install the package in the ./pkgfoo directory diff --git a/doc/cmd-v2-help/list-bin.txt b/doc/cmd-v2-help/list-bin.txt index 3b8b8f01156..8bcec28f4ef 100644 --- a/doc/cmd-v2-help/list-bin.txt +++ b/doc/cmd-v2-help/list-bin.txt @@ -37,34 +37,42 @@ Flags for list-bin: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -75,27 +83,20 @@ Flags for list-bin: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -116,9 +117,8 @@ Flags for list-bin: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -136,30 +136,21 @@ Flags for list-bin: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -178,13 +169,9 @@ Flags for list-bin: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, @@ -200,8 +187,8 @@ Flags for list-bin: --write-ghc-environment-files=always|never|ghc8.4.4+ # Whether to create a .ghc.environment file after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation + --[enable|disable]-documentation + # Toggle building of documentation --doc-index-file=TEMPLATE # A central index of haddock API documentation (template cannot use $pkgid) --dry-run # Do not install anything, only print what would @@ -236,12 +223,12 @@ Flags for list-bin: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -268,23 +255,28 @@ Flags for list-bin: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) --build-log=TEMPLATE # Log all builds to file (name template can use $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL + --remote-build-reporting=none|anonymous|detailed # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible + --[enable|disable]-per-component + # Toggle Per-component builds when possible --run-tests # Run package test suites during installation. --semaphore # Use a semaphore so GHC can compile components in parallel @@ -327,13 +319,18 @@ Flags for list-bin: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/outdated.txt b/doc/cmd-v2-help/outdated.txt index 85a07dd7493..8e67dde02aa 100644 --- a/doc/cmd-v2-help/outdated.txt +++ b/doc/cmd-v2-help/outdated.txt @@ -38,34 +38,42 @@ Flags for outdated: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -76,27 +84,20 @@ Flags for outdated: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -117,9 +118,8 @@ Flags for outdated: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -137,30 +137,21 @@ Flags for outdated: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -179,13 +170,9 @@ Flags for outdated: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, @@ -201,8 +188,8 @@ Flags for outdated: --write-ghc-environment-files=always|never|ghc8.4.4+ # Whether to create a .ghc.environment file after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation + --[enable|disable]-documentation + # Toggle building of documentation --doc-index-file=TEMPLATE # A central index of haddock API documentation (template cannot use $pkgid) --dry-run # Do not install anything, only print what would @@ -237,12 +224,12 @@ Flags for outdated: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -269,23 +256,28 @@ Flags for outdated: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) --build-log=TEMPLATE # Log all builds to file (name template can use $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL + --remote-build-reporting=none|anonymous|detailed # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible + --[enable|disable]-per-component + # Toggle Per-component builds when possible --run-tests # Run package test suites during installation. --semaphore # Use a semaphore so GHC can compile components in parallel @@ -328,13 +320,18 @@ Flags for outdated: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/path.txt b/doc/cmd-v2-help/path.txt index 74f4a3b3355..47bd6156ccf 100644 --- a/doc/cmd-v2-help/path.txt +++ b/doc/cmd-v2-help/path.txt @@ -39,34 +39,42 @@ Flags for path: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -77,27 +85,20 @@ Flags for path: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -118,9 +119,8 @@ Flags for path: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -138,30 +138,21 @@ Flags for path: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -180,13 +171,9 @@ Flags for path: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, @@ -202,8 +189,8 @@ Flags for path: --write-ghc-environment-files=always|never|ghc8.4.4+ # Whether to create a .ghc.environment file after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation + --[enable|disable]-documentation + # Toggle building of documentation --doc-index-file=TEMPLATE # A central index of haddock API documentation (template cannot use $pkgid) --dry-run # Do not install anything, only print what would @@ -238,12 +225,12 @@ Flags for path: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -270,23 +257,28 @@ Flags for path: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) --build-log=TEMPLATE # Log all builds to file (name template can use $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL + --remote-build-reporting=none|anonymous|detailed # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible + --[enable|disable]-per-component + # Toggle Per-component builds when possible --run-tests # Run package test suites during installation. --semaphore # Use a semaphore so GHC can compile components in parallel @@ -329,13 +321,18 @@ Flags for path: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/repl.txt b/doc/cmd-v2-help/repl.txt index 2913c652167..0e37b24f047 100644 --- a/doc/cmd-v2-help/repl.txt +++ b/doc/cmd-v2-help/repl.txt @@ -48,34 +48,42 @@ Flags for repl: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -86,27 +94,20 @@ Flags for repl: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -127,9 +128,8 @@ Flags for repl: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -147,30 +147,21 @@ Flags for repl: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -189,13 +180,9 @@ Flags for repl: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, @@ -211,8 +198,8 @@ Flags for repl: --write-ghc-environment-files=always|never|ghc8.4.4+ # Whether to create a .ghc.environment file after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation + --[enable|disable]-documentation + # Toggle building of documentation --doc-index-file=TEMPLATE # A central index of haddock API documentation (template cannot use $pkgid) --dry-run # Do not install anything, only print what would @@ -247,12 +234,12 @@ Flags for repl: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -279,23 +266,28 @@ Flags for repl: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) --build-log=TEMPLATE # Log all builds to file (name template can use $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL + --remote-build-reporting=none|anonymous|detailed # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible + --[enable|disable]-per-component + # Toggle Per-component builds when possible --run-tests # Run package test suites during installation. --semaphore # Use a semaphore so GHC can compile components in parallel @@ -338,13 +330,18 @@ Flags for repl: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites @@ -385,8 +382,8 @@ Flags for repl: presented to GHCi. --no-transitive-deps # Don't automatically include transitive dependencies of requested packages. - --enable-multi-repl # Enable multi-component repl sessions - --disable-multi-repl # Disable multi-component repl sessions + --[enable|disable]-multi-repl + # Toggle multi-component repl sessions Examples, open an interactive session: cabal repl diff --git a/doc/cmd-v2-help/run.txt b/doc/cmd-v2-help/run.txt index f8dd2b32a58..e66fff36895 100644 --- a/doc/cmd-v2-help/run.txt +++ b/doc/cmd-v2-help/run.txt @@ -51,34 +51,42 @@ Flags for run: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -89,27 +97,20 @@ Flags for run: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -130,9 +131,8 @@ Flags for run: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -150,30 +150,21 @@ Flags for run: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -192,13 +183,9 @@ Flags for run: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, @@ -214,8 +201,8 @@ Flags for run: --write-ghc-environment-files=always|never|ghc8.4.4+ # Whether to create a .ghc.environment file after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation + --[enable|disable]-documentation + # Toggle building of documentation --doc-index-file=TEMPLATE # A central index of haddock API documentation (template cannot use $pkgid) --dry-run # Do not install anything, only print what would @@ -250,12 +237,12 @@ Flags for run: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -282,23 +269,28 @@ Flags for run: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) --build-log=TEMPLATE # Log all builds to file (name template can use $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL + --remote-build-reporting=none|anonymous|detailed # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible + --[enable|disable]-per-component + # Toggle Per-component builds when possible --run-tests # Run package test suites during installation. --semaphore # Use a semaphore so GHC can compile components in parallel @@ -341,13 +333,18 @@ Flags for run: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/target.txt b/doc/cmd-v2-help/target.txt index 6dddae62364..a7fe5175746 100644 --- a/doc/cmd-v2-help/target.txt +++ b/doc/cmd-v2-help/target.txt @@ -67,34 +67,42 @@ Flags for target: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -105,27 +113,20 @@ Flags for target: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -146,9 +147,8 @@ Flags for target: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -166,30 +166,21 @@ Flags for target: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -208,13 +199,9 @@ Flags for target: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, @@ -230,8 +217,8 @@ Flags for target: --write-ghc-environment-files=always|never|ghc8.4.4+ # Whether to create a .ghc.environment file after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation + --[enable|disable]-documentation + # Toggle building of documentation --doc-index-file=TEMPLATE # A central index of haddock API documentation (template cannot use $pkgid) --dry-run # Do not install anything, only print what would @@ -266,12 +253,12 @@ Flags for target: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -298,23 +285,28 @@ Flags for target: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) --build-log=TEMPLATE # Log all builds to file (name template can use $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL + --remote-build-reporting=none|anonymous|detailed # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible + --[enable|disable]-per-component + # Toggle Per-component builds when possible --run-tests # Run package test suites during installation. --semaphore # Use a semaphore so GHC can compile components in parallel @@ -357,13 +349,18 @@ Flags for target: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/test.txt b/doc/cmd-v2-help/test.txt index 00c529d1a3b..6bb158db666 100644 --- a/doc/cmd-v2-help/test.txt +++ b/doc/cmd-v2-help/test.txt @@ -47,34 +47,42 @@ Flags for test: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -85,27 +93,20 @@ Flags for test: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -126,9 +127,8 @@ Flags for test: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -146,30 +146,21 @@ Flags for test: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -188,13 +179,9 @@ Flags for test: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, @@ -210,8 +197,8 @@ Flags for test: --write-ghc-environment-files=always|never|ghc8.4.4+ # Whether to create a .ghc.environment file after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation + --[enable|disable]-documentation + # Toggle building of documentation --doc-index-file=TEMPLATE # A central index of haddock API documentation (template cannot use $pkgid) --dry-run # Do not install anything, only print what would @@ -246,12 +233,12 @@ Flags for test: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -278,23 +265,28 @@ Flags for test: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) --build-log=TEMPLATE # Log all builds to file (name template can use $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL + --remote-build-reporting=none|anonymous|detailed # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible + --[enable|disable]-per-component + # Toggle Per-component builds when possible --run-tests # Run package test suites during installation. --semaphore # Use a semaphore so GHC can compile components in parallel @@ -337,13 +329,18 @@ Flags for test: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/unpack.txt b/doc/cmd-v2-help/unpack.txt index 415b4eb007d..d7e9e291bec 100644 --- a/doc/cmd-v2-help/unpack.txt +++ b/doc/cmd-v2-help/unpack.txt @@ -17,13 +17,14 @@ Flags for unpack: # Copy the package's source repository (ie git clone, darcs get, etc as appropriate). --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). This determines which - package versions are available as well as - .cabal file revision is selected (unless - --pristine is used). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. + This determines which package versions are + available as well as .cabal file revision is + selected (unless --pristine is used). --only-package-description # Unpack only the package description file. --package-description-only # A synonym for --only-package-description. --pristine # Unpack the original pristine tarball, rather diff --git a/doc/cmd-v2-help/update.txt b/doc/cmd-v2-help/update.txt index cc4e6a3ea26..469912962c2 100644 --- a/doc/cmd-v2-help/update.txt +++ b/doc/cmd-v2-help/update.txt @@ -37,34 +37,42 @@ Flags for update: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -75,27 +83,20 @@ Flags for update: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to - reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -116,9 +117,8 @@ Flags for update: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -136,30 +136,21 @@ Flags for update: locations) --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program - Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs @@ -178,13 +169,9 @@ Flags for update: use "" to prevent splitting) --cabal-lib-version=VERSION # Select which version of the Cabal lib to use to build packages (useful for testing). - --enable-append # Enable appending the new config to the old + --[enable|disable]-append # Toggle appending the new config to the old config file - --disable-append # Disable appending the new config to the old - config file - --enable-backup # Enable the backup of the config file before - any alterations - --disable-backup # Disable the backup of the config file before + --[enable|disable]-backup # Toggle the backup of the config file before any alterations -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT # Specify constraints on a package (version, @@ -200,8 +187,8 @@ Flags for update: --write-ghc-environment-files=always|never|ghc8.4.4+ # Whether to create a .ghc.environment file after a successful build (v2-build only) - --enable-documentation # Enable building of documentation - --disable-documentation # Disable building of documentation + --[enable|disable]-documentation + # Toggle building of documentation --doc-index-file=TEMPLATE # A central index of haddock API documentation (template cannot use $pkgid) --dry-run # Do not install anything, only print what would @@ -236,12 +223,12 @@ Flags for update: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -268,23 +255,28 @@ Flags for update: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) --build-log=TEMPLATE # Log all builds to file (name template can use $pkgid, $compiler, $os, $arch) - --remote-build-reporting=LEVEL + --remote-build-reporting=none|anonymous|detailed # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. - --enable-per-component # Enable Per-component builds when possible - --disable-per-component # Disable Per-component builds when possible + --[enable|disable]-per-component + # Toggle Per-component builds when possible --run-tests # Run package test suites during installation. --semaphore # Use a semaphore so GHC can compile components in parallel @@ -327,13 +319,18 @@ Flags for update: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-hidden-help/act-as-setup.txt b/doc/cmd-v2-hidden-help/act-as-setup.txt index 8a369fe706e..96352b2c7b4 100644 --- a/doc/cmd-v2-hidden-help/act-as-setup.txt +++ b/doc/cmd-v2-hidden-help/act-as-setup.txt @@ -4,4 +4,5 @@ Usage: cabal act-as-setup Flags for act-as-setup: -h, --help # Show this help text - --build-type=BUILD-TYPE # Use the given build type. + --build-type=Simple|Configure + # Use the given build type. diff --git a/doc/setup-help/configure.txt b/doc/setup-help/configure.txt index a5b3587cdd3..ee0449a4687 100644 --- a/doc/setup-help/configure.txt +++ b/doc/setup-help/configure.txt @@ -41,34 +41,42 @@ Flags for configure: --sysconfdir=DIR # Installation directory for configuration files --program-prefix=PREFIX # Prefix to be applied to installed executables --program-suffix=SUFFIX # Suffix to be applied to installed executables - --enable-library-vanilla # Enable Vanilla libraries - --disable-library-vanilla # Disable Vanilla libraries + --[enable|disable]-library-vanilla + # Toggle Vanilla libraries -p, --enable-library-profiling # Enable Library profiling --disable-library-profiling # Disable Library profiling - --enable-shared # Enable Shared library - --disable-shared # Disable Shared library - --enable-static # Enable Static library - --disable-static # Disable Static library - --enable-library-bytecode # Enable Bytecode library - --disable-library-bytecode # Disable Bytecode library - --enable-executable-dynamic # Enable Executable dynamic linking - --disable-executable-dynamic # Disable Executable dynamic linking - --enable-executable-static # Enable Executable fully static linking - --disable-executable-static # Disable Executable fully static linking - --enable-profiling # Enable Executable and library profiling - --disable-profiling # Disable Executable and library profiling - --enable-profiling-shared # Enable Build profiling shared libraries - --disable-profiling-shared # Disable Build profiling shared libraries - --enable-executable-profiling - # Enable Executable profiling (DEPRECATED) - --disable-executable-profiling - # Disable Executable profiling (DEPRECATED) + --[enable|disable]-shared # Toggle Shared library + --[enable|disable]-static # Toggle Static library + --[enable|disable]-library-bytecode + # Toggle Bytecode library + --[enable|disable]-executable-dynamic + # Toggle Executable dynamic linking + --[enable|disable]-executable-static + # Toggle Executable fully static linking + --[enable|disable]-profiling # Toggle Executable and library profiling + --[enable|disable]-profiling-shared + # Toggle Build profiling shared libraries + --[enable|disable]-executable-profiling + # Toggle Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -79,27 +87,20 @@ Flags for configure: project building --disable-build-info # Disable build information generation during project building - --enable-library-for-ghci # Enable compile library for use with GHCi - --disable-library-for-ghci # Disable compile library for use with GHCi - --enable-split-sections # Enable compile library code such that unneeded + --[enable|disable]-library-for-ghci + # Toggle compile library for use with GHCi + --[enable|disable]-split-sections + # Toggle compile library code such that unneeded definitions can be dropped from the final executable (GHC 7.8+) - --disable-split-sections # Disable compile library code such that - unneeded definitions can be dropped from the - final executable (GHC 7.8+) - --enable-split-objs # Enable split library into smaller objects to + --[enable|disable]-split-objs + # Toggle split library into smaller objects to reduce binary sizes (GHC 6.6+) - --disable-split-objs # Disable split library into smaller objects to - reduce binary sizes (GHC 6.6+) - --enable-executable-stripping - # Enable strip executables upon installation to - reduce binary sizes - --disable-executable-stripping - # Disable strip executables upon installation to - reduce binary sizes - --enable-library-stripping # Enable strip libraries upon installation to + --[enable|disable]-executable-stripping + # Toggle strip executables upon installation to reduce binary sizes - --disable-library-stripping # Disable strip libraries upon installation to + --[enable|disable]-library-stripping + # Toggle strip libraries upon installation to reduce binary sizes --configure-option=OPT # Extra option for configure --user # Enable doing a per-user installation @@ -120,9 +121,8 @@ Flags for configure: false. --extra-include-dirs=PATH # A list of directories to search for header files - --enable-deterministic # Enable Try to be as deterministic as possible - (used by the test suite) - --disable-deterministic # Disable Try to be as deterministic as possible + --[enable|disable]-deterministic + # Toggle Try to be as deterministic as possible (used by the test suite) --ipid=IPID # Installed package ID to compile this package as @@ -148,32 +148,23 @@ Flags for configure: --promised-dependency="void-0.5.8=void-0.5.8-177d5cdf20962d0581fe2e4932a6c309" --instantiate-with=NAME=MOD # A mapping of signature names to concrete module instantiations. - --enable-tests # Enable dependency checking and compilation for + --[enable|disable]-tests # Toggle dependency checking and compilation for test suites listed in the package description file. - --disable-tests # Disable dependency checking and compilation - for test suites listed in the package - description file. - --enable-coverage # Enable build package with Haskell Program - Coverage. (GHC only) - --disable-coverage # Disable build package with Haskell Program + --[enable|disable]-coverage # Toggle build package with Haskell Program Coverage. (GHC only) - --enable-library-coverage # Enable build package with Haskell Program - Coverage. (GHC only) (DEPRECATED) - --disable-library-coverage # Disable build package with Haskell Program + --[enable|disable]-library-coverage + # Toggle build package with Haskell Program Coverage. (GHC only) (DEPRECATED) --exact-configuration # All direct dependencies and flags are provided on the command line. - --enable-benchmarks # Enable dependency checking and compilation for + --[enable|disable]-benchmarks + # Toggle dependency checking and compilation for benchmarks listed in the package description file. - --disable-benchmarks # Disable dependency checking and compilation - for benchmarks listed in the package - description file. - --enable-relocatable # Enable building a package that is relocatable. + --[enable|disable]-relocatable + # Toggle building a package that is relocatable. (GHC only) - --disable-relocatable # Disable building a package that is - relocatable. (GHC only) --disable-response-files # Enable workaround for old versions of programs like "ar" that do not support @file arguments --allow-depending-on-private-libs diff --git a/doc/setup-help/install.txt b/doc/setup-help/install.txt index 4aa64d05a4f..1cec92d8c76 100644 --- a/doc/setup-help/install.txt +++ b/doc/setup-help/install.txt @@ -17,9 +17,8 @@ Flags for install: --inplace # install the package in the install subdirectory of the dist prefix, so it can be used without being installed - --enable-shell-wrappers # Enable using shell script wrappers around - executables - --disable-shell-wrappers # Disable using shell script wrappers around + --[enable|disable]-shell-wrappers + # Toggle using shell script wrappers around executables --user # upon configuration register this package in the user's local package database diff --git a/doc/setup-help/test.txt b/doc/setup-help/test.txt index 3ebe170302e..7100bb87bae 100644 --- a/doc/setup-help/test.txt +++ b/doc/setup-help/test.txt @@ -25,13 +25,18 @@ Flags for test: --machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --fail-when-no-test-suites # Exit with failure when no test suites are