Cabal-1.24.1.0: A framework for packaging Haskell software

Portabilityportable
Maintainercabal-devel@haskell.org
Safe HaskellNone

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

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

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_ :: Last' 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.

configProf :: Flag Bool

Enable profiling in the library and executables.

configProfDetail :: Flag ProfDetailLevel

Profiling detail level in the library and executables.

configProfLibDetail :: Flag ProfDetailLevel

Profiling detail level in the library

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

configExtraFrameworkDirs :: [FilePath]

path to search for extra frameworks (OS X only)

configExtraIncludeDirs :: [FilePath]

path to search for header files

configIPID :: Flag String

explicit IPID to be used

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, UnitId)]

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.

configAllowNewer :: Maybe AllowNewer

Ignore upper bounds on all or some dependencies. Wrapped in Maybe to distinguish between default and explicitly disabled.

Instances

emptyConfigFlags :: ConfigFlags

defaultConfigFlags :: ProgramConfiguration -> ConfigFlags

configureCommand :: ProgramConfiguration -> CommandUI ConfigFlags

configPrograms :: ConfigFlags -> ProgramConfiguration

More convenient version of configPrograms. Results in an error if internal invariant is violated.

data AllowNewer

Policy for relaxing upper bounds in dependencies. For example, given 'build-depends: array >= 0.3 && < 0.5', are we allowed to relax the upper bound and choose a version of array that is greater or equal to 0.5? By default the upper bounds are always strictly honored.

Constructors

AllowNewerNone

Default: honor the upper bounds in all dependencies, never choose versions newer than allowed.

AllowNewerSome [AllowNewerDep]

Ignore upper bounds in dependencies on the given packages.

AllowNewerAll

Ignore upper bounds in dependencies on all packages.

Instances

data AllowNewerDep

Dependencies can be relaxed either for all packages in the install plan, or only for some packages.

Constructors

AllowNewerDep PackageName 
AllowNewerDepScoped PackageName PackageName 

Instances

isAllowNewer :: AllowNewer -> Bool

Convert AllowNewer to a boolean.

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

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

emptyInstallFlags :: InstallFlags

defaultInstallFlags :: InstallFlags

installCommand :: CommandUI InstallFlags

data HaddockTarget

When we build haddock documentation, there are two cases:

  1. We build haddocks only for the current development version, intended for local use and not for distribution. In this case, we store the generated documentation in distdochtml/name.
  2. We build haddocks for intended for uploading them to hackage. In this case, we need to follow the layout that hackage expects from documentation tarballs, and we might also want to use different flags than for development builds, so in this case we store the generated documentation in distdochtml/id-docs.

Constructors

ForHackage 
ForDevelopment 

Instances

data HaddockFlags

Constructors

HaddockFlags 

Fields

haddockProgramPaths :: [(String, FilePath)]
 
haddockProgramArgs :: [(String, [String])]
 
haddockHoogle :: Flag Bool
 
haddockHtml :: Flag Bool
 
haddockHtmlLocation :: Flag String
 
haddockForHackage :: Flag HaddockTarget
 
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

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

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

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

defaultReplFlags :: ReplFlags

replCommand :: ProgramConfiguration -> CommandUI ReplFlags

data CleanFlags

Constructors

CleanFlags 

Fields

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

Instances

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

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

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

emptyTestFlags :: TestFlags

defaultTestFlags :: TestFlags

testCommand :: CommandUI TestFlags

data TestShowDetails

Constructors

Never 
Failures 
Always 
Streaming 
Direct 

Instances

data BenchmarkFlags

Constructors

BenchmarkFlags 

Fields

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

Instances

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.

splitArgs :: String -> [String]

Helper function to split a string into a list of arguments. It's supposed to handle quoted things sensibly, eg: 

 splitArgs "--foo=\"C:\Program Files\Bar\" --baz"
   = ["--foo=C:\Program Files\Bar", "--baz"]

defaultDistPref :: FilePath

optionDistPref :: (flags -> Flag FilePath) -> (Flag FilePath -> flags -> flags) -> ShowOrParseArgs -> OptionField flags

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) 
Semigroup (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

readPToMaybe :: ReadP a a -> String -> Maybe a