-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A Setup.hs helper for running doctests
--   
--   As of now (end of 2024), there isn't <tt>cabal doctest</tt> command.
--   Yet, to properly work, <tt>doctest</tt> needs plenty of configuration.
--   This library provides the common bits for writing a custom
--   <tt>Setup.hs</tt>.
@package cabal-doctest
@version 1.0.12


-- | See cabal-doctest README for full-fledged recipes &amp; caveats.
--   
--   The provided <a>generateBuildModule</a> generates a module named
--   <tt>Build_doctests</tt>.
--   
--   That module exports just enough compiler flags, so that doctest could
--   be simply
--   
--   <pre>
--   module Main where
--   
--   import Build_doctests (flags, pkgs, module_sources)
--   import Test.Doctest (doctest)
--   
--   main :: IO ()
--   main = doctest args
--     where
--       args = flags ++ pkgs ++ module_sources
--   </pre>
--   
--   As this module-generation is done at build-time,
--   <a>generateBuildModule</a> must be invoked from <tt>Setup.hs</tt>,
--   which also necessarily means <tt>build-type: Custom</tt>.
--   
--   <tt>Setup.hs</tt> can use libraries, but they must be declared as
--   dependencies in the <tt>custom-setup</tt> stanza of the user's cabal
--   file. To use <tt>cabal-doctest</tt> then:
--   
--   <pre>
--   custom-setup
--    setup-depends:
--      base &gt;= 4 &amp;&amp; &lt;5,
--      cabal-doctest &gt;= 1 &amp;&amp; &lt;1.1
--   </pre>
--   
--   Finally, simple shortcuts are provided to avoid an explicit dependency
--   on <tt>Cabal</tt> from <tt>setup-depends</tt>:
--   <a>defaultMainWithDoctests</a> and
--   <a>defaultMainAutoconfWithDoctests</a>.
module Distribution.Extra.Doctest

-- | This type is a <a>String</a> which identifies a test-suite in your
--   cabal-file; the one you'll be running doctest from.
type TestSuiteName = String

-- | A default <tt>Setup.hs</tt> main with doctests:
--   
--   <pre>
--   import Distribution.Extra.Doctest
--          (defaultMainWithDoctests)
--   
--   main :: IO ()
--   main = defaultMainWithDoctests "doctests"
--   </pre>
--   
--   The argument <tt>"doctests"</tt> identifies a test-suite in your
--   cabal-file; the one you'll run doctest from. If you have
--   <tt>test-suite my-test</tt>, you should invoke
--   <tt>defaultMainWithDoctests "my-test"</tt> in Setup.hs.
--   
--   This argument does not change the generated module name imported from
--   the test-driver's <tt>Main</tt> -- that one always remains <tt>import
--   Build_doctests</tt>.
defaultMainWithDoctests :: TestSuiteName -> IO ()

-- | Like <a>defaultMainWithDoctests</a>, but for packages with
--   <tt>build-type: Configure</tt>.
defaultMainAutoconfWithDoctests :: TestSuiteName -> IO ()

-- | Compose <a>generateBuildModule</a> into Cabal's <a>UserHooks</a>
--   (prepending the action).
--   
--   This is exported for advanced custom Setup-s.
addDoctestsUserHook :: TestSuiteName -> UserHooks -> UserHooks

-- | <a>simpleUserHooks</a> with <a>generateBuildModule</a> already
--   wired-in.
doctestsUserHooks :: TestSuiteName -> UserHooks

-- | Generate a build module for the test suite.
--   
--   <pre>
--   import Distribution.Simple
--          (defaultMainWithHooks, UserHooks(..), simpleUserHooks)
--   import Distribution.Extra.Doctest
--          (generateBuildModule)
--   
--   main :: IO ()
--   main = defaultMainWithHooks simpleUserHooks
--       { buildHook = pkg lbi hooks flags -&gt; do
--           generateBuildModule "doctests" flags pkg lbi
--           buildHook simpleUserHooks pkg lbi hooks flags
--       }
--   </pre>
generateBuildModule :: TestSuiteName -> BuildFlags -> PackageDescription -> LocalBuildInfo -> IO ()
instance Distribution.Extra.Doctest.CompatSymPath GHC.Internal.IO.FilePath GHC.Internal.IO.FilePath
instance GHC.Classes.Eq Distribution.Extra.Doctest.Name
instance GHC.Internal.Show.Show Distribution.Extra.Doctest.Component
instance GHC.Internal.Show.Show Distribution.Extra.Doctest.Name
