Cabal/Distribution/Simple/UserHooks.hs

   1 {-# LANGUAGE FlexibleContexts #-}
   2 {-# LANGUAGE RankNTypes #-}
   3
   4 -----------------------------------------------------------------------------
   5 -- |
   6 -- Module      :  Distribution.Simple.UserHooks
   7 -- Copyright   :  Isaac Jones 2003-2005
   8 -- License     :  BSD3
   9 --
  10 -- Maintainer  :  cabal-devel@haskell.org
  11 -- Portability :  portable
  12 --
  13 -- This defines the API that @Setup.hs@ scripts can use to customise the way
  14 -- the build works. This module just defines the 'UserHooks' type. The
  15 -- predefined sets of hooks that implement the @Simple@, @Make@ and @Configure@
  16 -- build systems are defined in "Distribution.Simple". The 'UserHooks' is a big
  17 -- record of functions. There are 3 for each action, a pre, post and the action
  18 -- itself. There are few other miscellaneous hooks, ones to extend the set of
  19 -- programs and preprocessors and one to override the function used to read the
  20 -- @.cabal@ file.
  21 --
  22 -- This hooks type is widely agreed to not be the right solution. Partly this
  23 -- is because changes to it usually break custom @Setup.hs@ files and yet many
  24 -- internal code changes do require changes to the hooks. For example we cannot
  25 -- pass any extra parameters to most of the functions that implement the
  26 -- various phases because it would involve changing the types of the
  27 -- corresponding hook. At some point it will have to be replaced.
  28
  29 module Distribution.Simple.UserHooks (
  30         UserHooks(..), Args,
  31         emptyUserHooks,
  32   ) where
  33
  34 import Prelude ()
  35 import Distribution.Compat.Prelude
  36
  37 import Distribution.PackageDescription
  38 import Distribution.Simple.Program
  39 import Distribution.Simple.Command
  40 import Distribution.Simple.PreProcess
  41 import Distribution.Simple.Setup
  42 import Distribution.Simple.LocalBuildInfo
  43
  44 type Args = [String]
  45
  46 -- | Hooks allow authors to add specific functionality before and after a
  47 -- command is run, and also to specify additional preprocessors.
  48 --
  49 -- * WARNING: The hooks interface is under rather constant flux as we try to
  50 -- understand users needs. Setup files that depend on this interface may
  51 -- break in future releases.
  52 data UserHooks = UserHooks {
  53
  54     -- | Used for @.\/setup test@
  55     runTests :: Args -> Bool -> PackageDescription -> LocalBuildInfo -> IO (),
  56     -- | Read the description file
  57     readDesc :: IO (Maybe GenericPackageDescription),
  58     -- | Custom preprocessors in addition to and overriding 'knownSuffixHandlers'.
  59     hookedPreProcessors :: [ PPSuffixHandler ],
  60     -- | These programs are detected at configure time.  Arguments for them are
  61     -- added to the configure command.
  62     hookedPrograms :: [Program],
  63
  64     -- |Hook to run before configure command
  65     preConf  :: Args -> ConfigFlags -> IO HookedBuildInfo,
  66     -- |Over-ride this hook to get different behavior during configure.
  67     confHook :: (GenericPackageDescription, HookedBuildInfo)
  68             -> ConfigFlags -> IO LocalBuildInfo,
  69     -- |Hook to run after configure command
  70     postConf :: Args -> ConfigFlags -> PackageDescription -> LocalBuildInfo -> IO (),
  71
  72     -- |Hook to run before build command.  Second arg indicates verbosity level.
  73     preBuild  :: Args -> BuildFlags -> IO HookedBuildInfo,
  74
  75     -- |Over-ride this hook to get different behavior during build.
  76     buildHook :: PackageDescription -> LocalBuildInfo -> UserHooks -> BuildFlags -> IO (),
  77     -- |Hook to run after build command.  Second arg indicates verbosity level.
  78     postBuild :: Args -> BuildFlags -> PackageDescription -> LocalBuildInfo -> IO (),
  79
  80     -- |Hook to run before repl command.  Second arg indicates verbosity level.
  81     preRepl  :: Args -> ReplFlags -> IO HookedBuildInfo,
  82     -- |Over-ride this hook to get different behavior during interpretation.
  83     replHook :: PackageDescription -> LocalBuildInfo -> UserHooks -> ReplFlags -> [String] -> IO (),
  84     -- |Hook to run after repl command.  Second arg indicates verbosity level.
  85     postRepl :: Args -> ReplFlags -> PackageDescription -> LocalBuildInfo -> IO (),
  86
  87     -- |Hook to run before clean command.  Second arg indicates verbosity level.
  88     preClean  :: Args -> CleanFlags -> IO HookedBuildInfo,
  89     -- |Over-ride this hook to get different behavior during clean.
  90     cleanHook :: PackageDescription -> () -> UserHooks -> CleanFlags -> IO (),
  91     -- |Hook to run after clean command.  Second arg indicates verbosity level.
  92     postClean :: Args -> CleanFlags -> PackageDescription -> () -> IO (),
  93
  94     -- |Hook to run before copy command
  95     preCopy  :: Args -> CopyFlags -> IO HookedBuildInfo,
  96     -- |Over-ride this hook to get different behavior during copy.
  97     copyHook :: PackageDescription -> LocalBuildInfo -> UserHooks -> CopyFlags -> IO (),
  98     -- |Hook to run after copy command
  99     postCopy :: Args -> CopyFlags -> PackageDescription -> LocalBuildInfo -> IO (),
 100
 101     -- |Hook to run before install command
 102     preInst  :: Args -> InstallFlags -> IO HookedBuildInfo,
 103
 104     -- |Over-ride this hook to get different behavior during install.
 105     instHook :: PackageDescription -> LocalBuildInfo -> UserHooks -> InstallFlags -> IO (),
 106     -- |Hook to run after install command.  postInst should be run
 107     -- on the target, not on the build machine.
 108     postInst :: Args -> InstallFlags -> PackageDescription -> LocalBuildInfo -> IO (),
 109
 110     -- |Hook to run before sdist command.  Second arg indicates verbosity level.
 111     preSDist  :: Args -> SDistFlags -> IO HookedBuildInfo,
 112     -- |Over-ride this hook to get different behavior during sdist.
 113     sDistHook :: PackageDescription -> Maybe LocalBuildInfo -> UserHooks -> SDistFlags -> IO (),
 114     -- |Hook to run after sdist command.  Second arg indicates verbosity level.
 115     postSDist :: Args -> SDistFlags -> PackageDescription -> Maybe LocalBuildInfo -> IO (),
 116
 117     -- |Hook to run before register command
 118     preReg  :: Args -> RegisterFlags -> IO HookedBuildInfo,
 119     -- |Over-ride this hook to get different behavior during registration.
 120     regHook :: PackageDescription -> LocalBuildInfo -> UserHooks -> RegisterFlags -> IO (),
 121     -- |Hook to run after register command
 122     postReg :: Args -> RegisterFlags -> PackageDescription -> LocalBuildInfo -> IO (),
 123
 124     -- |Hook to run before unregister command
 125     preUnreg  :: Args -> RegisterFlags -> IO HookedBuildInfo,
 126     -- |Over-ride this hook to get different behavior during unregistration.
 127     unregHook :: PackageDescription -> LocalBuildInfo -> UserHooks -> RegisterFlags -> IO (),
 128     -- |Hook to run after unregister command
 129     postUnreg :: Args -> RegisterFlags -> PackageDescription -> LocalBuildInfo -> IO (),
 130
 131     -- |Hook to run before hscolour command.  Second arg indicates verbosity level.
 132     preHscolour  :: Args -> HscolourFlags -> IO HookedBuildInfo,
 133     -- |Over-ride this hook to get different behavior during hscolour.
 134     hscolourHook :: PackageDescription -> LocalBuildInfo -> UserHooks -> HscolourFlags -> IO (),
 135     -- |Hook to run after hscolour command.  Second arg indicates verbosity level.
 136     postHscolour :: Args -> HscolourFlags -> PackageDescription -> LocalBuildInfo -> IO (),
 137
 138     -- |Hook to run before doctest command.  Second arg indicates verbosity level.
 139     preDoctest  :: Args -> DoctestFlags -> IO HookedBuildInfo,
 140     -- |Over-ride this hook to get different behavior during doctest.
 141     doctestHook :: PackageDescription -> LocalBuildInfo -> UserHooks -> DoctestFlags -> IO (),
 142     -- |Hook to run after doctest command.  Second arg indicates verbosity level.
 143     postDoctest :: Args -> DoctestFlags -> PackageDescription -> LocalBuildInfo -> IO (),
 144
 145     -- |Hook to run before haddock command.  Second arg indicates verbosity level.
 146     preHaddock  :: Args -> HaddockFlags -> IO HookedBuildInfo,
 147     -- |Over-ride this hook to get different behavior during haddock.
 148     haddockHook :: PackageDescription -> LocalBuildInfo -> UserHooks -> HaddockFlags -> IO (),
 149     -- |Hook to run after haddock command.  Second arg indicates verbosity level.
 150     postHaddock :: Args -> HaddockFlags -> PackageDescription -> LocalBuildInfo -> IO (),
 151
 152     -- |Hook to run before test command.
 153     preTest :: Args -> TestFlags -> IO HookedBuildInfo,
 154     -- |Over-ride this hook to get different behavior during test.
 155     testHook :: Args -> PackageDescription -> LocalBuildInfo -> UserHooks -> TestFlags -> IO (),
 156     -- |Hook to run after test command.
 157     postTest :: Args -> TestFlags -> PackageDescription -> LocalBuildInfo -> IO (),
 158
 159     -- |Hook to run before bench command.
 160     preBench :: Args -> BenchmarkFlags -> IO HookedBuildInfo,
 161     -- |Over-ride this hook to get different behavior during bench.
 162     benchHook :: Args -> PackageDescription -> LocalBuildInfo -> UserHooks -> BenchmarkFlags -> IO (),
 163     -- |Hook to run after bench command.
 164     postBench :: Args -> BenchmarkFlags -> PackageDescription -> LocalBuildInfo -> IO ()
 165   }
 166
 167 {-# DEPRECATED runTests "Please use the new testing interface instead!" #-}
 168 {-# DEPRECATED preSDist  "SDist hooks violate the invariants of new-sdist. Use 'autogen-modules' and 'build-tool-depends' instead." #-}
 169 {-# DEPRECATED sDistHook "SDist hooks violate the invariants of new-sdist. Use 'autogen-modules' and 'build-tool-depends' instead." #-}
 170 {-# DEPRECATED postSDist "SDist hooks violate the invariants of new-sdist. Use 'autogen-modules' and 'build-tool-depends' instead." #-}
 171
 172 -- |Empty 'UserHooks' which do nothing.
 173 emptyUserHooks :: UserHooks
 174 emptyUserHooks
 175   = UserHooks {
 176       runTests  = ru,
 177       readDesc  = return Nothing,
 178       hookedPreProcessors = [],
 179       hookedPrograms      = [],
 180       preConf   = rn',
 181       confHook  = (\_ _ -> return (error "No local build info generated during configure. Over-ride empty configure hook.")),
 182       postConf  = ru,
 183       preBuild  = rn',
 184       buildHook = ru,
 185       postBuild = ru,
 186       preRepl   = \_ _ -> return emptyHookedBuildInfo,
 187       replHook  = \_ _ _ _ _ -> return (),
 188       postRepl  = ru,
 189       preClean  = rn,
 190       cleanHook = ru,
 191       postClean = ru,
 192       preCopy   = rn',
 193       copyHook  = ru,
 194       postCopy  = ru,
 195       preInst   = rn,
 196       instHook  = ru,
 197       postInst  = ru,
 198       preSDist  = rn,
 199       sDistHook = ru,
 200       postSDist = ru,
 201       preReg    = rn',
 202       regHook   = ru,
 203       postReg   = ru,
 204       preUnreg  = rn,
 205       unregHook = ru,
 206       postUnreg = ru,
 207       preHscolour  = rn,
 208       hscolourHook = ru,
 209       postHscolour = ru,
 210       preDoctest   = rn,
 211       doctestHook  = ru,
 212       postDoctest  = ru,
 213       preHaddock   = rn',
 214       haddockHook  = ru,
 215       postHaddock  = ru,
 216       preTest  = rn',
 217       testHook = \_ -> ru,
 218       postTest = ru,
 219       preBench = rn',
 220       benchHook = \_ -> ru,
 221       postBench = ru
 222     }
 223     where rn  args _ = noExtraFlags args >> return emptyHookedBuildInfo
 224           rn' _    _ = return emptyHookedBuildInfo
 225           ru _ _ _ _ = return ()