-- 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 cabal doctest command.
--   Yet, to properly work, doctest needs plenty of configuration.
--   This library provides the common bits for writing a custom
--   Setup.hs.
@package cabal-doctest
@version 1.0.12

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

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

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

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

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

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

-- | Generate a build module for the test suite.
--   
--   
--   import Distribution.Simple
--          (defaultMainWithHooks, UserHooks(..), simpleUserHooks)
--   import Distribution.Extra.Doctest
--          (generateBuildModule)
--   
--   main :: IO ()
--   main = defaultMainWithHooks simpleUserHooks
--       { buildHook = pkg lbi hooks flags -> do
--           generateBuildModule "doctests" flags pkg lbi
--           buildHook simpleUserHooks pkg lbi hooks flags
--       }
--   
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
