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]
Versions [faq] 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
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-05T16:15:22Z
Distributions Arch:1.0.8, Debian:1.0.6, Fedora:1.0.8, LTSHaskell:1.0.8, NixOS:1.0.8, Stackage:1.0.8, openSUSE:1.0.8
Downloads 80438 total (917 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2017-05-05 [all 1 reports]

Modules

[Index]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for cabal-doctest-1.0.1

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

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

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.

Copyright

Copyright 2017 Oleg Grenrus.

Available under the BSD 3-clause license.