Copyright | Isaac Jones 2006 Duncan Coutts 2007-2009 |
---|---|
Maintainer | cabal-devel@haskell.org |
Portability | portable |
Safe Haskell | None |
Language | Haskell2010 |
Distribution.Simple.Program.Db
Description
This provides a
ProgramDb
type which holds configured and not-yet
configured programs. It is the parameter to lots of actions elsewhere in
Cabal that need to look up and run programs. If we had a Cabal monad,
the
ProgramDb
would probably be a reader or state component of it.
One nice thing about using it is that any program that is registered with Cabal will get some "configure" and ".cabal" helpers like --with-foo-args --foo-path= and extra-foo-args.
There's also a hook for adding programs in a Setup.lhs script. See
hookedPrograms in
UserHooks
. This gives a
hook user the ability to get the above flags and such so that they
don't have to write all the PATH logic inside Setup.lhs.
Synopsis
- data ProgramDb
- emptyProgramDb :: ProgramDb
- defaultProgramDb :: ProgramDb
- restoreProgramDb :: [ Program ] -> ProgramDb -> ProgramDb
- addKnownProgram :: Program -> ProgramDb -> ProgramDb
- addKnownPrograms :: [ Program ] -> ProgramDb -> ProgramDb
- lookupKnownProgram :: String -> ProgramDb -> Maybe Program
- knownPrograms :: ProgramDb -> [( Program , Maybe ConfiguredProgram )]
- getProgramSearchPath :: ProgramDb -> ProgramSearchPath
- setProgramSearchPath :: ProgramSearchPath -> ProgramDb -> ProgramDb
- modifyProgramSearchPath :: ( ProgramSearchPath -> ProgramSearchPath ) -> ProgramDb -> ProgramDb
- userSpecifyPath :: String -> FilePath -> ProgramDb -> ProgramDb
- userSpecifyPaths :: [( String , FilePath )] -> ProgramDb -> ProgramDb
- userMaybeSpecifyPath :: String -> Maybe FilePath -> ProgramDb -> ProgramDb
- userSpecifyArgs :: String -> [ ProgArg ] -> ProgramDb -> ProgramDb
- userSpecifyArgss :: [( String , [ ProgArg ])] -> ProgramDb -> ProgramDb
- userSpecifiedArgs :: Program -> ProgramDb -> [ ProgArg ]
- lookupProgram :: Program -> ProgramDb -> Maybe ConfiguredProgram
- updateProgram :: ConfiguredProgram -> ProgramDb -> ProgramDb
- configuredPrograms :: ProgramDb -> [ ConfiguredProgram ]
- configureProgram :: Verbosity -> Program -> ProgramDb -> IO ProgramDb
- configureAllKnownPrograms :: Verbosity -> ProgramDb -> IO ProgramDb
- unconfigureProgram :: String -> ProgramDb -> ProgramDb
- lookupProgramVersion :: Verbosity -> Program -> VersionRange -> ProgramDb -> IO ( Either String ( ConfiguredProgram , Version , ProgramDb ))
- reconfigurePrograms :: Verbosity -> [( String , FilePath )] -> [( String , [ ProgArg ])] -> ProgramDb -> IO ProgramDb
- requireProgram :: Verbosity -> Program -> ProgramDb -> IO ( ConfiguredProgram , ProgramDb )
- requireProgramVersion :: Verbosity -> Program -> VersionRange -> ProgramDb -> IO ( ConfiguredProgram , Version , ProgramDb )
- needProgram :: Verbosity -> Program -> ProgramDb -> IO ( Maybe ( ConfiguredProgram , ProgramDb ))
The collection of configured programs we can run
The configuration is a collection of information about programs. It contains information both about configured programs and also about programs that we are yet to configure.
The idea is that we start from a collection of unconfigured programs and one
by one we try to configure them at which point we move them into the
configured collection. For unconfigured programs we record not just the
Program
but also any user-provided arguments and location for the program.
Instances
Read ProgramDb Source # |
Note that this instance does not preserve the known
|
Show ProgramDb Source # |
Note that this instance does not preserve the known
|
Binary ProgramDb Source # |
Note that this instance does not preserve the known
|
Structured ProgramDb Source # | |
Defined in Distribution.Simple.Program.Db |
restoreProgramDb :: [ Program ] -> ProgramDb -> ProgramDb Source #
The
Read
/
Show
and
Binary
instances do not preserve all the
unconfigured
Programs
because
Program
is not in
Read
/
Show
because
it contains functions. So to fully restore a deserialised
ProgramDb
use
this function to add back all the known
Program
s.
-
It does not add the default programs, but you probably want them, use
builtinPrograms
in addition to any extra you might need.
Query and manipulate the program db
addKnownProgram :: Program -> ProgramDb -> ProgramDb Source #
Add a known program that we may configure later
knownPrograms :: ProgramDb -> [( Program , Maybe ConfiguredProgram )] Source #
getProgramSearchPath :: ProgramDb -> ProgramSearchPath Source #
Get the current
ProgramSearchPath
used by the
ProgramDb
.
This is the default list of locations where programs are looked for when
configuring them. This can be overridden for specific programs (with
userSpecifyPath
), and specific known programs can modify or ignore this
search path in their own configuration code.
setProgramSearchPath :: ProgramSearchPath -> ProgramDb -> ProgramDb Source #
Change the current
ProgramSearchPath
used by the
ProgramDb
.
This will affect programs that are configured from here on, so you
should usually set it before configuring any programs.
modifyProgramSearchPath :: ( ProgramSearchPath -> ProgramSearchPath ) -> ProgramDb -> ProgramDb Source #
Modify the current
ProgramSearchPath
used by the
ProgramDb
.
This will affect programs that are configured from here on, so you
should usually modify it before configuring any programs.
Arguments
:: String |
Program name |
-> FilePath |
user-specified path to the program |
-> ProgramDb | |
-> ProgramDb |
User-specify this path. Basically override any path information for this program in the configuration. If it's not a known program ignore it.
userSpecifyPaths :: [( String , FilePath )] -> ProgramDb -> ProgramDb Source #
Like
userSpecifyPath
but for a list of progs and their paths.
User-specify the arguments for this program. Basically override any args information for this program in the configuration. If it's not a known program, ignore it..
userSpecifyArgss :: [( String , [ ProgArg ])] -> ProgramDb -> ProgramDb Source #
Like
userSpecifyPath
but for a list of progs and their args.
userSpecifiedArgs :: Program -> ProgramDb -> [ ProgArg ] Source #
Get any extra args that have been previously specified for a program.
lookupProgram :: Program -> ProgramDb -> Maybe ConfiguredProgram Source #
Try to find a configured program
updateProgram :: ConfiguredProgram -> ProgramDb -> ProgramDb Source #
Update a configured program in the database.
configuredPrograms :: ProgramDb -> [ ConfiguredProgram ] Source #
List all configured programs.
Query and manipulate the program db
configureProgram :: Verbosity -> Program -> ProgramDb -> IO ProgramDb Source #
Try to configure a specific program. If the program is already included in the collection of unconfigured programs then we use any user-supplied location and arguments. If the program gets configured successfully it gets added to the configured collection.
Note that it is not a failure if the program cannot be configured. It's only a failure if the user supplied a location and the program could not be found at that location.
The reason for it not being a failure at this stage is that we don't know up
front all the programs we will need, so we try to configure them all.
To verify that a program was actually successfully configured use
requireProgram
.
configureAllKnownPrograms :: Verbosity -> ProgramDb -> IO ProgramDb Source #
Try to configure all the known programs that have not yet been configured.
unconfigureProgram :: String -> ProgramDb -> ProgramDb Source #
Unconfigure a program. This is basically a hack and you shouldn't
use it, but it can be handy for making sure a
requireProgram
actually reconfigures.
lookupProgramVersion :: Verbosity -> Program -> VersionRange -> ProgramDb -> IO ( Either String ( ConfiguredProgram , Version , ProgramDb )) Source #
Check that a program is configured and available to be run.
Additionally check that the program version number is suitable and return
it. For example you could require
AnyVersion
or
orLaterVersion
(
Version
[1,0] [])
It returns the configured program, its version number and a possibly updated
ProgramDb
. If the program could not be configured or the version is
unsuitable, it returns an error value.
reconfigurePrograms :: Verbosity -> [( String , FilePath )] -> [( String , [ ProgArg ])] -> ProgramDb -> IO ProgramDb Source #
reconfigure a bunch of programs given new user-specified args. It takes
the same inputs as
userSpecifyPath
and
userSpecifyArgs
and for all progs
with a new path it calls
configureProgram
.
requireProgram :: Verbosity -> Program -> ProgramDb -> IO ( ConfiguredProgram , ProgramDb ) Source #
Check that a program is configured and available to be run.
It raises an exception if the program could not be configured, otherwise it returns the configured program.
requireProgramVersion :: Verbosity -> Program -> VersionRange -> ProgramDb -> IO ( ConfiguredProgram , Version , ProgramDb ) Source #
Like
lookupProgramVersion
, but raises an exception in case of error
instead of returning 'Left errMsg'.