Cabal-1.22.5.0: A framework for packaging Haskell software

Copyright | Isaac Jones 2003-2004 Duncan Coutts 2007
License | BSD3
Maintainer | cabal-devel@haskell.org
Portability | portable
Safe Haskell | None
Language | Haskell98

Distribution.Simple.Setup

Description

This is a big module, but not very complicated. The code is very regular and repetitive. It defines the command line interface for all the Cabal commands. For each command (like `configure`, `build` etc) it defines a type that holds all the flags, the default set of flags and a `CommandUI` that maps command line flags to and from the corresponding flags type.

All the flags types are instances of `Monoid`, see http://www.haskell.org/pipermail/cabal-devel/2007-December/001509.html for an explanation.

The types defined here get used in the front end and especially in `cabal-install` which has to do quite a bit of manipulating sets of command line flags.

This is actually relatively nice, it works quite well. The main change it needs is to unify it with the code for managing sets of fields that can be read and written from files. This would allow us to save configure flags in config files.

Synopsis

- data GlobalFlags = GlobalFlags {
  - globalVersion :: Flag Bool
  - globalNumericVersion :: Flag Bool
  }
- emptyGlobalFlags :: GlobalFlags
- defaultGlobalFlags :: GlobalFlags
- globalCommand :: [Command action] -> CommandUI GlobalFlags
- data ConfigFlags = ConfigFlags {
  - configPrograms :: ProgramConfiguration
  - configProgramPaths :: [(String, FilePath)]
  - configProgramArgs :: [(String, [String])]
  - configProgramPathExtra :: NubList FilePath
  - configHcFlavor :: Flag CompilerFlavor
  - configHcPath :: Flag FilePath
  - configHcPkg :: Flag FilePath
  - configVanillaLib :: Flag Bool
  - configProfLib :: Flag Bool
  - configSharedLib :: Flag Bool
  - configDynExe :: Flag Bool
  - configProfExe :: Flag Bool
  - configConfigureArgs :: [String]
  - configOptimization :: Flag OptimisationLevel
  - configProgPrefix :: Flag PathTemplate
  - configProgSuffix :: Flag PathTemplate
  - configInstallDirs :: InstallDirs (Flag PathTemplate)
  - configScratchDir :: Flag FilePath
  - configExtraLibDirs :: [FilePath]
  - configExtraIncludeDirs :: [FilePath]
  - configDistPref :: Flag FilePath
  - configVerbosity :: Flag Verbosity
  - configUserInstall :: Flag Bool
  - configPackageDBs :: [Maybe PackageDB]
  - configGHCiLib :: Flag Bool
  - configSplitObjs :: Flag Bool
  - configStripExes :: Flag Bool
  - configStripLibs :: Flag Bool
  - configConstraints :: [Dependency]
  - configDependencies :: [(PackageName, InstalledPackageId)]
  - configInstantiateWith :: [(ModuleName, (InstalledPackageId, ModuleName))]
  - configConfigurationsFlags :: FlagAssignment
  - configTests :: Flag Bool
  - configBenchmarks :: Flag Bool
  - configCoverage :: Flag Bool
  - configLibCoverage :: Flag Bool
  - configExactConfiguration :: Flag Bool
  - configFlagError :: Flag String
  - configRelocatable :: Flag Bool
  - configDebugInfo :: Flag DebugInfoLevel
  }
- emptyConfigFlags :: ConfigFlags
- defaultConfigFlags :: ProgramConfiguration -> ConfigFlags
- configureCommand :: ProgramConfiguration -> CommandUI ConfigFlags
- configAbsolutePaths :: ConfigFlags -> IO ConfigFlags
- readPackageDbList :: String -> [Maybe PackageDB]
- showPackageDbList :: [Maybe PackageDB] -> [String]
- data CopyFlags = CopyFlags {
  - copyDest :: Flag CopyDest
  - copyDistPref :: Flag FilePath
  - copyVerbosity :: Flag Verbosity
  }
- emptyCopyFlags :: CopyFlags
- defaultCopyFlags :: CopyFlags
- copyCommand :: CommandUI CopyFlags
- data InstallFlags = InstallFlags {
  - installPackageDB :: Flag PackageDB
  - installDistPref :: Flag FilePath
  - installUseWrapper :: Flag Bool
  - installInPlace :: Flag Bool
  - installVerbosity :: Flag Verbosity
  }
- emptyInstallFlags :: InstallFlags
- defaultInstallFlags :: InstallFlags
- installCommand :: CommandUI InstallFlags
- data HaddockFlags = HaddockFlags {
  - haddockProgramPaths :: [(String, FilePath)]
  - haddockProgramArgs :: [(String, [String])]
  - haddockHoogle :: Flag Bool
  - haddockHtml :: Flag Bool
  - haddockHtmlLocation :: Flag String
  - haddockExecutables :: Flag Bool
  - haddockTestSuites :: Flag Bool
  - haddockBenchmarks :: Flag Bool
  - haddockInternal :: Flag Bool
  - haddockCss :: Flag FilePath
  - haddockHscolour :: Flag Bool
  - haddockHscolourCss :: Flag FilePath
  - haddockContents :: Flag PathTemplate
  - haddockDistPref :: Flag FilePath
  - haddockKeepTempFiles :: Flag Bool
  - haddockVerbosity :: Flag Verbosity
  }
- emptyHaddockFlags :: HaddockFlags
- defaultHaddockFlags :: HaddockFlags
- haddockCommand :: CommandUI HaddockFlags
- data HscolourFlags = HscolourFlags {
  - hscolourCSS :: Flag FilePath
  - hscolourExecutables :: Flag Bool
  - hscolourTestSuites :: Flag Bool
  - hscolourBenchmarks :: Flag Bool
  - hscolourDistPref :: Flag FilePath
  - hscolourVerbosity :: Flag Verbosity
  }
- emptyHscolourFlags :: HscolourFlags
- defaultHscolourFlags :: HscolourFlags
- hscolourCommand :: CommandUI HscolourFlags
- data BuildFlags = BuildFlags {
  - buildProgramPaths :: [(String, FilePath)]
  - buildProgramArgs :: [(String, [String])]
  - buildDistPref :: Flag FilePath
  - buildVerbosity :: Flag Verbosity
  - buildNumJobs :: Flag (Maybe Int)
  - buildArgs :: [String]
  }
- emptyBuildFlags :: BuildFlags
- defaultBuildFlags :: BuildFlags
- buildCommand :: ProgramConfiguration -> CommandUI BuildFlags
- buildVerbose :: BuildFlags -> Verbosity
- data ReplFlags = ReplFlags {
  - replProgramPaths :: [(String, FilePath)]
  - replProgramArgs :: [(String, [String])]
  - replDistPref :: Flag FilePath
  - replVerbosity :: Flag Verbosity
  - replReload :: Flag Bool
  }
- defaultReplFlags :: ReplFlags
- replCommand :: ProgramConfiguration -> CommandUI ReplFlags
- data CleanFlags = CleanFlags {
  - cleanSaveConf :: Flag Bool
  - cleanDistPref :: Flag FilePath
  - cleanVerbosity :: Flag Verbosity
  }
- emptyCleanFlags :: CleanFlags
- defaultCleanFlags :: CleanFlags
- cleanCommand :: CommandUI CleanFlags
- data RegisterFlags = RegisterFlags {
  - regPackageDB :: Flag PackageDB
  - regGenScript :: Flag Bool
  - regGenPkgConf :: Flag (Maybe FilePath)
  - regInPlace :: Flag Bool
  - regDistPref :: Flag FilePath
  - regPrintId :: Flag Bool
  - regVerbosity :: Flag Verbosity
  }
- emptyRegisterFlags :: RegisterFlags
- defaultRegisterFlags :: RegisterFlags
- registerCommand :: CommandUI RegisterFlags
- unregisterCommand :: CommandUI RegisterFlags
- data SDistFlags = SDistFlags {
  - sDistSnapshot :: Flag Bool
  - sDistDirectory :: Flag FilePath
  - sDistDistPref :: Flag FilePath
  - sDistListSources :: Flag FilePath
  - sDistVerbosity :: Flag Verbosity
  }
- emptySDistFlags :: SDistFlags
- defaultSDistFlags :: SDistFlags
- sdistCommand :: CommandUI SDistFlags
- data TestFlags = TestFlags {
  - testDistPref :: Flag FilePath
  - testVerbosity :: Flag Verbosity
  - testHumanLog :: Flag PathTemplate
  - testMachineLog :: Flag PathTemplate
  - testShowDetails :: Flag TestShowDetails
  - testKeepTix :: Flag Bool
  - testOptions :: [PathTemplate]
  }
- emptyTestFlags :: TestFlags
- defaultTestFlags :: TestFlags
- testCommand :: CommandUI TestFlags
- data TestShowDetails
  - = Never
  - | Failures
  - | Always
  - | Streaming
- data BenchmarkFlags = BenchmarkFlags {
  - benchmarkDistPref :: Flag FilePath
  - benchmarkVerbosity :: Flag Verbosity
  - benchmarkOptions :: [PathTemplate]
  }
- emptyBenchmarkFlags :: BenchmarkFlags
- defaultBenchmarkFlags :: BenchmarkFlags
- benchmarkCommand :: CommandUI BenchmarkFlags
- data CopyDest
  - = NoCopyDest
  - | CopyTo FilePath
- configureArgs :: Bool -> ConfigFlags -> [String]
- configureOptions :: ShowOrParseArgs -> [OptionField ConfigFlags]
- configureCCompiler :: Verbosity -> ProgramConfiguration -> IO (FilePath, [String])
- configureLinker :: Verbosity -> ProgramConfiguration -> IO (FilePath, [String])
- buildOptions :: ProgramConfiguration -> ShowOrParseArgs -> [OptionField BuildFlags]
- haddockOptions :: ShowOrParseArgs -> [OptionField HaddockFlags]
- installDirsOptions :: [OptionField (InstallDirs (Flag PathTemplate))]
- programConfigurationOptions :: ProgramConfiguration -> ShowOrParseArgs -> (flags -> [(String, [String])]) -> ([(String, [String])] -> flags -> flags) -> [OptionField flags]
- programConfigurationPaths' :: (String -> String) -> ProgramConfiguration -> ShowOrParseArgs -> (flags -> [(String, FilePath)]) -> ([(String, FilePath)] -> flags -> flags) -> [OptionField flags]
- defaultDistPref :: FilePath
- data Flag a
  - = Flag a
  - | NoFlag
- toFlag :: a -> Flag a
- fromFlag :: Flag a -> a
- fromFlagOrDefault :: a -> Flag a -> a
- flagToMaybe :: Flag a -> Maybe a
- flagToList :: Flag a -> [a]
- boolOpt :: SFlags -> SFlags -> MkOptDescr (a -> Flag Bool) (Flag Bool -> a -> a) a
- boolOpt' :: OptFlags -> OptFlags -> MkOptDescr (a -> Flag Bool) (Flag Bool -> a -> a) a
- trueArg :: MkOptDescr (a -> Flag Bool) (Flag Bool -> a -> a) a
- falseArg :: MkOptDescr (a -> Flag Bool) (Flag Bool -> a -> a) a
- optionVerbosity :: (flags -> Flag Verbosity) -> (Flag Verbosity -> flags -> flags) -> OptionField flags
- optionNumJobs :: (flags -> Flag (Maybe Int)) -> (Flag (Maybe Int) -> flags -> flags) -> OptionField flags

# Documentation

data GlobalFlags

Flags that apply at the top level, not to any sub-command.

Constructors

GlobalFlags |

Fields

globalVersion :: Flag Bool
globalNumericVersion :: Flag Bool

Instances

Monoid GlobalFlags |

emptyGlobalFlags :: GlobalFlags

defaultGlobalFlags :: GlobalFlags

globalCommand :: [Command action] -> CommandUI GlobalFlags

data ConfigFlags

Flags to `configure` command.

IMPORTANT: every time a new flag is added, `filterConfigureFlags` should be updated.

Constructors

ConfigFlags |

Fields

configPrograms :: ProgramConfiguration

  All programs that cabal may run

configProgramPaths :: [(String, FilePath)]

  user specified programs paths

configProgramArgs :: [(String, [String])]

  user specified programs args

configProgramPathExtra :: NubList FilePath

  Extend the $PATH

configHcFlavor :: Flag CompilerFlavor

  The "flavor" of the compiler, such as GHC or JHC.

configHcPath :: Flag FilePath

  given compiler location

configHcPkg :: Flag FilePath

  given hc-pkg location

configVanillaLib :: Flag Bool

  Enable vanilla library

configProfLib :: Flag Bool

  Enable profiling in the library

configSharedLib :: Flag Bool

  Build shared library

configDynExe :: Flag Bool

  Enable dynamic linking of the executables.

configProfExe :: Flag Bool

  Enable profiling in the executables.

configConfigureArgs :: [String]

  Extra arguments to `configure`

configOptimization :: Flag OptimisationLevel

  Enable optimization.

configProgPrefix :: Flag PathTemplate

  Installed executable prefix.

configProgSuffix :: Flag PathTemplate

  Installed executable suffix.

configInstallDirs :: InstallDirs (Flag PathTemplate)

  Installation paths

configScratchDir :: Flag FilePath
configExtraLibDirs :: [FilePath]

  path to search for extra libraries

configExtraIncludeDirs :: [FilePath]

  path to search for header files

configDistPref :: Flag FilePath

  "dist" prefix

configVerbosity :: Flag Verbosity

  verbosity level

configUserInstall :: Flag Bool

  The --user/--global flag

configPackageDBs :: [Maybe PackageDB]

  Which package DBs to use

configGHCiLib :: Flag Bool

  Enable compiling library for GHCi

configSplitObjs :: Flag Bool

  Enable -split-objs with GHC

configStripExes :: Flag Bool

  Enable executable stripping

configStripLibs :: Flag Bool

  Enable library stripping

configConstraints :: [Dependency]

  Additional constraints for dependencies.

configDependencies :: [(PackageName, InstalledPackageId)]
configInstantiateWith :: [(ModuleName, (InstalledPackageId, ModuleName))]

  The packages depended on.

configConfigurationsFlags :: FlagAssignment
configTests :: Flag Bool

  Enable test suite compilation

configBenchmarks :: Flag Bool

  Enable benchmark compilation

configCoverage :: Flag Bool

  Enable program coverage

configLibCoverage :: Flag Bool

  Enable program coverage (deprecated)

configExactConfiguration :: Flag Bool

  All direct dependencies and flags are provided on the command line by the user via the '--dependency' and '--flags' options.

configFlagError :: Flag String

  Halt and show an error message indicating an error in flag assignment

configRelocatable :: Flag Bool

  Enable relocatable package built

configDebugInfo :: Flag DebugInfoLevel

  Emit debug info.

Instances

Read ConfigFlags |
Show ConfigFlags |
Generic ConfigFlags |
Monoid ConfigFlags |
Binary ConfigFlags |
type Rep ConfigFlags |

emptyConfigFlags :: ConfigFlags

defaultConfigFlags :: ProgramConfiguration -> ConfigFlags

configureCommand :: ProgramConfiguration -> CommandUI ConfigFlags

configAbsolutePaths :: ConfigFlags -> IO ConfigFlags

readPackageDbList :: String -> [Maybe PackageDB]

showPackageDbList :: [Maybe PackageDB] -> [String]

data CopyFlags

Flags to `copy`: (destdir, copy-prefix (backwards compat), verbosity)

Constructors

CopyFlags |

Fields

copyDest :: Flag CopyDest
copyDistPref :: Flag FilePath
copyVerbosity :: Flag Verbosity

Instances

Show CopyFlags |
Monoid CopyFlags |

emptyCopyFlags :: CopyFlags

defaultCopyFlags :: CopyFlags

copyCommand :: CommandUI CopyFlags

data InstallFlags

Flags to `install`: (package db, verbosity)

Constructors

InstallFlags |

Fields

installPackageDB :: Flag PackageDB
installDistPref :: Flag FilePath
installUseWrapper :: Flag Bool
installInPlace :: Flag Bool
installVerbosity :: Flag Verbosity

Instances

Show InstallFlags |
Monoid InstallFlags |

emptyInstallFlags :: InstallFlags

defaultInstallFlags :: InstallFlags

installCommand :: CommandUI InstallFlags

data HaddockFlags

Constructors

HaddockFlags |

Fields

haddockProgramPaths :: [(String, FilePath)]
haddockProgramArgs :: [(String, [String])]
haddockHoogle :: Flag Bool
haddockHtml :: Flag Bool
haddockHtmlLocation :: Flag String
haddockExecutables :: Flag Bool
haddockTestSuites :: Flag Bool
haddockBenchmarks :: Flag Bool
haddockInternal :: Flag Bool
haddockCss :: Flag FilePath
haddockHscolour :: Flag Bool
haddockHscolourCss :: Flag FilePath
haddockContents :: Flag PathTemplate
haddockDistPref :: Flag FilePath
haddockKeepTempFiles :: Flag Bool
haddockVerbosity :: Flag Verbosity

Instances

Show HaddockFlags |
Monoid HaddockFlags |

emptyHaddockFlags :: HaddockFlags

defaultHaddockFlags :: HaddockFlags

haddockCommand :: CommandUI HaddockFlags

data HscolourFlags

Constructors

HscolourFlags |

Fields

hscolourCSS :: Flag FilePath
hscolourExecutables :: Flag Bool
hscolourTestSuites :: Flag Bool
hscolourBenchmarks :: Flag Bool
hscolourDistPref :: Flag FilePath
hscolourVerbosity :: Flag Verbosity

Instances

Show HscolourFlags |
Monoid HscolourFlags |

emptyHscolourFlags :: HscolourFlags

defaultHscolourFlags :: HscolourFlags

hscolourCommand :: CommandUI HscolourFlags

data BuildFlags

Constructors

BuildFlags |

Fields

buildProgramPaths :: [(String, FilePath)]
buildProgramArgs :: [(String, [String])]
buildDistPref :: Flag FilePath
buildVerbosity :: Flag Verbosity
buildNumJobs :: Flag (Maybe Int)
buildArgs :: [String]

Instances

Show BuildFlags |
Monoid BuildFlags |

emptyBuildFlags :: BuildFlags

defaultBuildFlags :: BuildFlags

buildCommand :: ProgramConfiguration -> CommandUI BuildFlags

buildVerbose :: BuildFlags -> Verbosity

Deprecated: Use buildVerbosity instead

data ReplFlags

Constructors

ReplFlags |

Fields

replProgramPaths :: [(String, FilePath)]
replProgramArgs :: [(String, [String])]
replDistPref :: Flag FilePath
replVerbosity :: Flag Verbosity
replReload :: Flag Bool

Instances

Show ReplFlags |
Monoid ReplFlags |

defaultReplFlags :: ReplFlags

replCommand :: ProgramConfiguration -> CommandUI ReplFlags

data CleanFlags

Constructors

CleanFlags |

Fields

cleanSaveConf :: Flag Bool
cleanDistPref :: Flag FilePath
cleanVerbosity :: Flag Verbosity

Instances

Show CleanFlags |
Monoid CleanFlags |

emptyCleanFlags :: CleanFlags

defaultCleanFlags :: CleanFlags

cleanCommand :: CommandUI CleanFlags

data RegisterFlags

Flags to `register` and `unregister`: (user package, gen-script, in-place, verbosity)

Constructors

RegisterFlags |

Fields

regPackageDB :: Flag PackageDB
regGenScript :: Flag Bool
regGenPkgConf :: Flag (Maybe FilePath)
regInPlace :: Flag Bool
regDistPref :: Flag FilePath
regPrintId :: Flag Bool
regVerbosity :: Flag Verbosity

Instances

Show RegisterFlags |
Monoid RegisterFlags |

emptyRegisterFlags :: RegisterFlags

defaultRegisterFlags :: RegisterFlags

registerCommand :: CommandUI RegisterFlags

unregisterCommand :: CommandUI RegisterFlags

data SDistFlags

Flags to `sdist`: (snapshot, verbosity)

Constructors

SDistFlags |

Fields

sDistSnapshot :: Flag Bool
sDistDirectory :: Flag FilePath
sDistDistPref :: Flag FilePath
sDistListSources :: Flag FilePath
sDistVerbosity :: Flag Verbosity

Instances

Show SDistFlags |
Monoid SDistFlags |

emptySDistFlags :: SDistFlags

defaultSDistFlags :: SDistFlags

sdistCommand :: CommandUI SDistFlags

data TestFlags

Constructors

TestFlags |

Fields

testDistPref :: Flag FilePath
testVerbosity :: Flag Verbosity
testHumanLog :: Flag PathTemplate
testMachineLog :: Flag PathTemplate
testShowDetails :: Flag TestShowDetails
testKeepTix :: Flag Bool
testOptions :: [PathTemplate]

Instances

Monoid TestFlags |

emptyTestFlags :: TestFlags

defaultTestFlags :: TestFlags

testCommand :: CommandUI TestFlags

data TestShowDetails

Constructors

Never |
Failures |
Always |
Streaming |

Instances

Bounded TestShowDetails |
Enum TestShowDetails |
Eq TestShowDetails |
Ord TestShowDetails |
Show TestShowDetails |
Monoid TestShowDetails |
Text TestShowDetails |

data BenchmarkFlags

Constructors

BenchmarkFlags |

Fields

benchmarkDistPref :: Flag FilePath
benchmarkVerbosity :: Flag Verbosity
benchmarkOptions :: [PathTemplate]

Instances

Monoid BenchmarkFlags |

emptyBenchmarkFlags :: BenchmarkFlags

defaultBenchmarkFlags :: BenchmarkFlags

benchmarkCommand :: CommandUI BenchmarkFlags

data CopyDest

The location prefix for the copy command.

Constructors

NoCopyDest |
CopyTo FilePath |

Instances

Eq CopyDest |
Show CopyDest |

configureArgs :: Bool -> ConfigFlags -> [String]

Arguments to pass to a `configure` script, e.g. generated by `autoconf`.

configureOptions :: ShowOrParseArgs -> [OptionField ConfigFlags]

configureCCompiler :: Verbosity -> ProgramConfiguration -> IO (FilePath, [String])

configureLinker :: Verbosity -> ProgramConfiguration -> IO (FilePath, [String])

buildOptions :: ProgramConfiguration -> ShowOrParseArgs -> [OptionField BuildFlags]

haddockOptions :: ShowOrParseArgs -> [OptionField HaddockFlags]

installDirsOptions :: [OptionField (InstallDirs (Flag PathTemplate))]

programConfigurationOptions :: ProgramConfiguration -> ShowOrParseArgs -> (flags -> [(String, [String])]) -> ([(String, [String])] -> flags -> flags) -> [OptionField flags]

For each known program `PROG` in `progConf`, produce a `PROG-options` `OptionField`.

programConfigurationPaths' :: (String -> String) -> ProgramConfiguration -> ShowOrParseArgs -> (flags -> [(String, FilePath)]) -> ([(String, FilePath)] -> flags -> flags) -> [OptionField flags]

Like `programConfigurationPaths`, but allows to customise the option name.

defaultDistPref :: FilePath

data Flag a

All flags are monoids, they come in two flavours:

1. list flags eg

    --ghc-option=foo --ghc-option=bar

gives us all the values ["foo", "bar"]

1. singular value flags, eg:

    --enable-foo --disable-foo

gives us Just False So this Flag type is for the latter singular kind of flag. Its monoid instance gives us the behaviour where it starts out as `NoFlag` and later flags override earlier ones.

Constructors

Flag a |
NoFlag |

Instances

Functor Flag |
Bounded a => Bounded (Flag a) |
Enum a => Enum (Flag a) |
Eq a => Eq (Flag a) |
Read a => Read (Flag a) |
Show a => Show (Flag a) |
Generic (Flag a) |
Monoid (Flag a) |
Binary a => Binary (Flag a) |
type Rep (Flag a) |

toFlag :: a -> Flag a

fromFlag :: Flag a -> a

fromFlagOrDefault :: a -> Flag a -> a

flagToMaybe :: Flag a -> Maybe a

flagToList :: Flag a -> [a]

boolOpt :: SFlags -> SFlags -> MkOptDescr (a -> Flag Bool) (Flag Bool -> a -> a) a

boolOpt' :: OptFlags -> OptFlags -> MkOptDescr (a -> Flag Bool) (Flag Bool -> a -> a) a

trueArg :: MkOptDescr (a -> Flag Bool) (Flag Bool -> a -> a) a

falseArg :: MkOptDescr (a -> Flag Bool) (Flag Bool -> a -> a) a

optionVerbosity :: (flags -> Flag Verbosity) -> (Flag Verbosity -> flags -> flags) -> OptionField flags

optionNumJobs :: (flags -> Flag (Maybe Int)) -> (Flag (Maybe Int) -> flags -> flags) -> OptionField flags