cabal-doctest-1.0.12: A Setup.hs helper for running doctests

Safe Haskell | None
Language | Haskell2010

Distribution.Extra.Doctest

Description

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`.

Synopsis

- type TestSuiteName = String
- defaultMainWithDoctests :: TestSuiteName -> IO ()
- defaultMainAutoconfWithDoctests :: TestSuiteName -> IO ()
- addDoctestsUserHook :: TestSuiteName -> UserHooks -> UserHooks
- doctestsUserHooks :: TestSuiteName -> UserHooks
- generateBuildModule :: TestSuiteName -> BuildFlags -> PackageDescription -> LocalBuildInfo -> IO ()

# Documentation

type TestSuiteName = String Source #

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

defaultMainWithDoctests :: TestSuiteName -> IO () Source #

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`.

defaultMainAutoconfWithDoctests :: TestSuiteName -> IO () Source #

Like `defaultMainWithDoctests`, but for packages with `build-type: Configure`.

Since: 1.0.2

addDoctestsUserHook :: TestSuiteName -> UserHooks -> UserHooks Source #

Compose `generateBuildModule` into Cabal's `UserHooks` (prepending the action).

This is exported for advanced custom Setup-s.

Since: 1.0.2

doctestsUserHooks :: TestSuiteName -> UserHooks Source #

`simpleUserHooks` with `generateBuildModule` already wired-in.

generateBuildModule :: TestSuiteName -> BuildFlags -> PackageDescription -> LocalBuildInfo -> IO () Source #

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
        }