    {-# LANGUAGE DeriveDataTypeable #-}
    {-# LANGUAGE DeriveGeneric #-}

    module Distribution.Types.HookedBuildInfo (
        HookedBuildInfo,
        emptyHookedBuildInfo,
      ) where

    -- import Distribution.Compat.Prelude
    import Distribution.Types.BuildInfo
    import Distribution.Types.UnqualComponentName

    -- | 'HookedBuildInfo' is mechanism that hooks can use to
    -- override the 'BuildInfo's inside packages.  One example
    -- use-case (which is used in core libraries today) is as
    -- a way of passing flags which are computed by a configure
    -- script into Cabal.  In this case, the autoconf build type adds
    -- hooks to read in a textual 'HookedBuildInfo' format prior
    -- to doing any operations.
    --
    -- Quite honestly, this mechanism is a massive hack since we shouldn't
    -- be editing the 'PackageDescription' data structure (it's easy
    -- to assume that this data structure shouldn't change and
    -- run into bugs, see for example 1c20a6328579af9e37677d507e2e9836ef70ab9d).
    -- But it's a bit convenient, because there isn't another data
    -- structure that allows adding extra 'BuildInfo' style things.
    --
    -- In any case, a lot of care has to be taken to make sure the
    -- 'HookedBuildInfo' is applied to the 'PackageDescription'.  In
    -- general this process occurs in "Distribution.Simple", which is
    -- responsible for orchestrating the hooks mechanism.  The
    -- general strategy:
    --
    --      1. We run the pre-hook, which produces a 'HookedBuildInfo'
    --         (e.g., in the Autoconf case, it reads it out from a file).
    --      2. We sanity-check the hooked build info with
    --         'sanityCheckHookedBuildInfo'.
    --      3. We update our 'PackageDescription' (either freshly read
    --         or cached from 'LocalBuildInfo') with 'updatePackageDescription'.
    --
    --         In principle, we are also supposed to update the copy of
    --         the 'PackageDescription' stored in 'LocalBuildInfo'
    --         at 'localPkgDescr'.  Unfortunately, in practice, there
    --         are lots of Custom setup scripts which fail to update
    --         'localPkgDescr' so you really shouldn't rely on it.
    --         It's not DEPRECATED because there are legitimate uses
    --         for it, but... yeah.  Sharp knife.  See
    --         <https://github.com/haskell/cabal/issues/3606>
    --         for more information on the issue.
    --
    -- It is not well-specified whether or not a 'HookedBuildInfo' applied
    -- at configure time is persistent to the 'LocalBuildInfo'.  The
    -- fact that 'HookedBuildInfo' is passed to 'confHook' MIGHT SUGGEST
    -- that the 'HookedBuildInfo' is applied at this time, but actually
    -- since 9317b67e6122ab14e53f81b573bd0ecb388eca5a it has been ONLY used
    -- to create a modified package description that we check for problems:
    -- it is never actually saved to the LBI.  Since 'HookedBuildInfo' is
    -- applied monoidally to the existing build infos (and it is not an
    -- idempotent monoid), it could break things to save it, since we
    -- are obligated to apply any new 'HookedBuildInfo' and then we'd
    -- get the effect twice.  But this does mean we have to re-apply
    -- it every time. Hey, it's more flexibility.
    type HookedBuildInfo = (Maybe BuildInfo, [(UnqualComponentName, BuildInfo)])

    emptyHookedBuildInfo :: HookedBuildInfo
    emptyHookedBuildInfo = (Nothing, [])