The cabal-doctest package

[Tags:bsd3, library]

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]

Properties

Versions 1, 1.0.1, 1.0.2
Change log ChangeLog.md
Dependencies base (>=4.3 && <4.11), Cabal (>=1.10 && <2.1), directory, filepath [details]
License BSD3
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 repository head: git clone https://github.com/phadej/cabal-doctest
Uploaded Tue May 16 13:13:33 UTC 2017 by phadej
Distributions Arch:1.0.2, LTSHaskell:1.0.2, NixOS:1.0.2, Stackage:1.0.2, Tumbleweed:1.0.2
Downloads 24277 total (7200 in the last 30 days)
Votes
1 []
Status Docs available [build log]
Last success reported on 2017-05-16 [all 1 reports]
Hackage Matrix CI

Modules

[Index]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees

Readme for cabal-doctest

Readme for cabal-doctest-1.0.2

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](https://github.com/commercialhaskell/stack/issues/2094))

* There is [an issue in the Cabal issue tracker](https://github.com/haskell/cabal/issues/2327)
  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](https://github.com/phadej/cabal-doctest/issues/5) 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
---------

Copyright 2017 Oleg Grenrus.

Available under the BSD 3-clause license.