Cabal/src/Distribution/Simple/Program.hs

   1 {-# LANGUAGE FlexibleContexts #-}
   2 {-# LANGUAGE RankNTypes #-}
   3
   4 -----------------------------------------------------------------------------
   5
   6 -- |
   7 -- Module      :  Distribution.Simple.Program
   8 -- Copyright   :  Isaac Jones 2006, Duncan Coutts 2007-2009
   9 --
  10 -- Maintainer  :  cabal-devel@haskell.org
  11 -- Portability :  portable
  12 --
  13 -- This provides an abstraction which deals with configuring and running
  14 -- programs. A 'Program' is a static notion of a known program. A
  15 -- 'ConfiguredProgram' is a 'Program' that has been found on the current
  16 -- machine and is ready to be run (possibly with some user-supplied default
  17 -- args). Configuring a program involves finding its location and if necessary
  18 -- finding its version. There is also a 'ProgramDb' type which holds
  19 -- configured and not-yet configured programs. It is the parameter to lots of
  20 -- actions elsewhere in Cabal that need to look up and run programs. If we had
  21 -- a Cabal monad, the 'ProgramDb' would probably be a reader or
  22 -- state component of it.
  23 --
  24 -- The module also defines all the known built-in 'Program's and the
  25 -- 'defaultProgramDb' which contains them all.
  26 --
  27 -- One nice thing about using it is that any program that is
  28 -- registered with Cabal will get some \"configure\" and \".cabal\"
  29 -- helpers like --with-foo-args --foo-path= and extra-foo-args.
  30 --
  31 -- There's also good default behavior for trying to find \"foo\" in
  32 -- PATH, being able to override its location, etc.
  33 --
  34 -- There's also a hook for adding programs in a Setup.lhs script.  See
  35 -- hookedPrograms in 'Distribution.Simple.UserHooks'.  This gives a
  36 -- hook user the ability to get the above flags and such so that they
  37 -- don't have to write all the PATH logic inside Setup.lhs.
  38 module Distribution.Simple.Program
  39   ( -- * Program and functions for constructing them
  40     Program (..)
  41   , ProgramSearchPath
  42   , ProgramSearchPathEntry (..)
  43   , simpleProgram
  44   , findProgramOnSearchPath
  45   , defaultProgramSearchPath
  46   , findProgramVersion
  47
  48     -- * Configured program and related functions
  49   , ConfiguredProgram (..)
  50   , programPath
  51   , ProgArg
  52   , ProgramLocation (..)
  53   , runProgram
  54   , getProgramOutput
  55   , suppressOverrideArgs
  56
  57     -- * Program invocations
  58   , ProgramInvocation (..)
  59   , emptyProgramInvocation
  60   , simpleProgramInvocation
  61   , programInvocation
  62   , runProgramInvocation
  63   , getProgramInvocationOutput
  64   , getProgramInvocationLBS
  65
  66     -- * The collection of unconfigured and configured programs
  67   , builtinPrograms
  68
  69     -- * The collection of configured programs we can run
  70   , ProgramDb
  71   , defaultProgramDb
  72   , emptyProgramDb
  73   , restoreProgramDb
  74   , addKnownProgram
  75   , addKnownPrograms
  76   , lookupKnownProgram
  77   , knownPrograms
  78   , getProgramSearchPath
  79   , setProgramSearchPath
  80   , userSpecifyPath
  81   , userSpecifyPaths
  82   , userMaybeSpecifyPath
  83   , userSpecifyArgs
  84   , userSpecifyArgss
  85   , userSpecifiedArgs
  86   , lookupProgram
  87   , lookupProgramVersion
  88   , updateProgram
  89   , configureProgram
  90   , configureAllKnownPrograms
  91   , reconfigurePrograms
  92   , requireProgram
  93   , requireProgramVersion
  94   , needProgram
  95   , runDbProgram
  96   , getDbProgramOutput
  97
  98     -- * Programs that Cabal knows about
  99   , ghcProgram
 100   , ghcPkgProgram
 101   , ghcjsProgram
 102   , ghcjsPkgProgram
 103   , hmakeProgram
 104   , jhcProgram
 105   , uhcProgram
 106   , gccProgram
 107   , arProgram
 108   , stripProgram
 109   , happyProgram
 110   , alexProgram
 111   , hsc2hsProgram
 112   , c2hsProgram
 113   , cpphsProgram
 114   , hscolourProgram
 115   , doctestProgram
 116   , haddockProgram
 117   , greencardProgram
 118   , ldProgram
 119   , tarProgram
 120   , cppProgram
 121   , pkgConfigProgram
 122   , hpcProgram
 123   ) where
 124
 125 import Distribution.Compat.Prelude
 126 import Prelude ()
 127
 128 import Distribution.Simple.Errors
 129 import Distribution.Simple.Program.Builtin
 130 import Distribution.Simple.Program.Db
 131 import Distribution.Simple.Program.Find
 132 import Distribution.Simple.Program.Run
 133 import Distribution.Simple.Program.Types
 134 import Distribution.Simple.Utils
 135 import Distribution.Verbosity
 136
 137 -- | Runs the given configured program.
 138 runProgram
 139   :: Verbosity
 140   -- ^ Verbosity
 141   -> ConfiguredProgram
 142   -- ^ The program to run
 143   -> [ProgArg]
 144   -- ^ Any /extra/ arguments to add
 145   -> IO ()
 146 runProgram verbosity prog args =
 147   runProgramInvocation verbosity (programInvocation prog args)
 148
 149 -- | Runs the given configured program and gets the output.
 150 getProgramOutput
 151   :: Verbosity
 152   -- ^ Verbosity
 153   -> ConfiguredProgram
 154   -- ^ The program to run
 155   -> [ProgArg]
 156   -- ^ Any /extra/ arguments to add
 157   -> IO String
 158 getProgramOutput verbosity prog args =
 159   getProgramInvocationOutput verbosity (programInvocation prog args)
 160
 161 -- | Looks up the given program in the program database and runs it.
 162 runDbProgram
 163   :: Verbosity
 164   -- ^ verbosity
 165   -> Program
 166   -- ^ The program to run
 167   -> ProgramDb
 168   -- ^ look up the program here
 169   -> [ProgArg]
 170   -- ^ Any /extra/ arguments to add
 171   -> IO ()
 172 runDbProgram verbosity prog programDb args =
 173   case lookupProgram prog programDb of
 174     Nothing ->
 175       dieWithException verbosity $ ProgramNotFound (programName prog)
 176     Just configuredProg -> runProgram verbosity configuredProg args
 177
 178 -- | Looks up the given program in the program database and runs it.
 179 getDbProgramOutput
 180   :: Verbosity
 181   -- ^ verbosity
 182   -> Program
 183   -- ^ The program to run
 184   -> ProgramDb
 185   -- ^ look up the program here
 186   -> [ProgArg]
 187   -- ^ Any /extra/ arguments to add
 188   -> IO String
 189 getDbProgramOutput verbosity prog programDb args =
 190   case lookupProgram prog programDb of
 191     Nothing -> dieWithException verbosity $ ProgramNotFound (programName prog)
 192     Just configuredProg -> getProgramOutput verbosity configuredProg args