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

[ bsd3, deprecated, distribution, library ] [ Propose Tags ]
Deprecated

Currently (beginning of 2017), there isn't cabal doctest command. Yet, to properly work doctest needs plenty of configuration. This library provides the common bits for writing custom Setup.hs See Cabal/2327 for the progress of cabal doctest, i.e. whether this library is obsolete.


[Skip to Readme]

Modules

[Index]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 1, 1.0.1, 1.0.2, 1.0.3, 1.0.4, 1.0.5, 1.0.6, 1.0.7, 1.0.8, 1.0.9
Change log ChangeLog.md
Dependencies base (>=4.3 && <4.11), Cabal (>=1.10 && <2.1), directory, filepath [details]
License BSD-3-Clause
Copyright (c) 2017 Oleg Grenrus
Author Oleg Grenrus <oleg.grenrus@iki.fi>
Maintainer Oleg Grenrus <oleg.grenrus@iki.fi>
Category Distribution
Home page https://github.com/phadej/cabal-doctest
Source repo head: git clone https://github.com/phadej/cabal-doctest
Uploaded by phadej at 2017-05-16T13:13:33Z
Distributions Arch:1.0.9, Debian:1.0.8, Fedora:1.0.9, LTSHaskell:1.0.9, NixOS:1.0.9, Stackage:1.0.9, openSUSE:1.0.9
Reverse Dependencies 1 direct, 0 indirect [details]
Downloads 98186 total (238 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2017-05-16 [all 1 reports]

Readme for cabal-doctest-1.0.2

[back to package description]

cabal-doctest

Hackage Build Status

A Setup.hs helper for running doctests.

Example Usage

See [https://github.com/phadej/cabal-doctest/tree/master/example] for an example package. (Note that the example requires Cabal-1.24 or later, but you can relax this bound safely, although running doctests won't be supported on versions of Cabal older than 1.24.)

To use this library in your Setup.hs, you should specify a custom-setup section in your .cabal file. For example:

custom-setup
 setup-depends:
   base >= 4 && <5,
   Cabal,
   cabal-doctest >= 1 && <1.1

/Note:/ Cabal dependency is needed because of Cabal/GH-4288 bug.

You'll also need to specify build-type: Custom at the top of the .cabal file. Now put this into your Setup.hs file:

module Main where

import Distribution.Extra.Doctest (defaultMainWithDoctests)

main :: IO ()
main = defaultMainWithDoctests "doctests"

When you build your project, this Setup will generate a Build_doctests module. To use it in a testsuite, simply do this:

module Main where

import Build_doctests (flags, pkgs, module_sources)
import Data.Foldable (traverse_)
import Test.DocTest (doctest)

main :: IO ()
main = do
    traverse_ putStrLn args -- optionally print arguments
    doctest args
  where
    args = flags ++ pkgs ++ module_sources

Additional configuration

The cabal-doctest based Setup.hs supports few extensions fields in pkg.cabal files to customise the doctest runner behaviour, without customising the default doctest.hs.

test-suite doctests:
  if impl(ghc >= 8.0)
    x-doctest-options: -fdiagnostics-color=never
  x-doctest-source-dirs: test
  x-doctest-modules: Servant.Utils.LinksSpec

  ...
  • x-doctest-options Additional arguments passed into doctest command.
  • x-doctest-modules Additional modules to doctest. May be useful if you have doctest in test or executables (i.e not default library complonent).
  • x-doctest-src-dirs Additional source directories to look for the modules.

Notes

  • custom-setup section is supported starting from cabal-install-1.24. For older cabal-install's you have to install custom setup dependencies manually.

  • stack respects custom-setup starting from version 1.3.3. Before that you have to use explicit-setup-deps setting in your stack.yaml. (stack/GH-2094)

  • There is an issue in the Cabal issue tracker about adding cabal doctest command. After that command is implemented, this library will be deprecated.

  • If your library contains cbits, you might need to depend on the library itself in doctests test-suite. We aren't sure whether this a bug or not. See #5 issue for longer explanation.

  • You can use x-doctest-options field in test-suite doctests to pass additional flags to the doctest.

  • For build-type: Configure packages, you can use defaultMainAutoconfWithDoctests function to make custom Setup.hs script.

  • If you use the default . in hs-source-dirs, then running doctests might fail with weird errors (ambigious module errors). Workaround is to move sources under src/ or some non-top-level directory.

Copyright 2017 Oleg Grenrus.

Available under the BSD 3-clause license.