cabal-doctest-1.0.12: A Setup.hs helper for running doctests
Safe HaskellSafe-Inferred
LanguageHaskell2010

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

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
    }