cabal-doctest
A Setup.hs helper for running doctests
https://github.com/haskellari/cabal-doctest
Version on this page: | 1.0.9@rev:3 |
LTS Haskell 22.43: | 1.0.11 |
Stackage Nightly 2024-12-07: | 1.0.11 |
Latest on Hackage: | 1.0.11 |
cabal-doctest-1.0.9@sha256:6dea0dbd1457f43d96ce1cfb1bab8b9f55d4fb82940e2bfa5aad78e6e2260656,1517
Module documentation for 1.0.9
- Distribution
- Distribution.Extra
cabal-doctest
A Setup.hs
helper for running doctests
.
Simple example
For the typical use case, namely a .cabal
file with a single library containing
doctests, adapting the simple example
will be sufficient.
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: The Cabal
dependency is only needed for cabal-install < 2.4
(see issue haskell/cabal#4288).
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 System.Environment.Compat (unsetEnv)
import Test.DocTest (doctest)
main :: IO ()
main = do
traverse_ putStrLn args -- optionally print arguments
unsetEnv "GHC_ENVIRONMENT" -- see 'Notes'; you may not need this
doctest args
where
args = flags ++ pkgs ++ module_sources
(The System.Environment.Compat
module is from the base-compat
package. That’s already in the transitive closure of doctest
‘s
dependencies. System.Environment.unsetEnv
was added with GHC 7.8 so,
if you don’t need to support versions of GHC older than 7.8, you can
use System.Environment
from base
instead.)
Example with multiple .cabal components
cabal-doctest
also supports more exotic use cases where a .cabal
file
contains more components with doctests than just the main library, including:
- doctests in executables,
- doctests in internal libraries (if using
Cabal-2.0
or later).
Unlike the simple example shown above, these examples involve named
components. You don’t need to change the Setup.hs
script to support
this use case. However, in this scenario Build_doctests
will generate extra
copies of the flags
, pkgs
, and module_sources
values for each additional
named component.
Simplest approach is to use x-doctest-components
field, for example:
x-doctest-components: lib lib:internal exe:example
In that case, the test driver is generally:
module Main where
import Build_doctests (Component (..), components)
import Data.Foldable (for_)
import System.Environment.Compat (unsetEnv)
import Test.DocTest (doctest)
main :: IO ()
main = for_ components $ \(Component name flags pkgs sources) -> do
print name
putStrLn "----------------------------------------"
let args = flags ++ pkgs ++ sources
for_ args putStrLn
unsetEnv "GHC_ENVIRONMENT"
doctest args
There is also a more explicit approach: if you have an executable named foo
,
then separate values named flags_exe_foo
, pkgs_exe_foo
, and module_sources_exe_foo
will
be generated in Build_doctests
. If the name has hyphens in it
(e.g., my-exe
), then cabal-doctest
will convert those hyphens to
underscores (e.g., you’d get flags_my_exe
, pkgs_my_exe
, and
module_sources_my_exe
).
Internal library bar
values will have a _lib_bar
suffix.
An example testsuite driver for this use case might look like this:
module Main where
import Build_doctests
(flags, pkgs, module_sources,
flags_exe_my_exe, pkgs_exe_my_exe, module_sources_exe_my_exe)
import Data.Foldable (traverse_)
import System.Environment.Compat (unsetEnv)
import Test.DocTest
main :: IO ()
main = do
unsetEnv "GHC_ENVRIONMENT"
-- doctests for library
traverse_ putStrLn libArgs
doctest libArgs
-- doctests for executable
traverse_ putStrLn exeArgs
doctest exeArgs
where
libArgs = flags ++ pkgs ++ module_sources
exeArgs = flags_exe_my_exe ++ pkgs_exe_my_exe ++ module_sources_exe_my_exe
See this example for more details.
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 intodoctest
command.x-doctest-modules
Additional modules todoctest
. May be useful if you havedoctest
in test or executables (i.e not default library complonent).x-doctest-src-dirs
Additional source directories to look for the modules.
Notes
-
Recent versions of
Cabal
(for instance, 2.0) can choose to build a package’sdoctest
test suite before the library. However, in order forcabal-doctest
to work correctly, the library must be built first, asdoctest
relies on the presence of generated files that are only created when the library is built. See #19.A hacky workaround for this problem is to depend on the library itself in a
doctests
test suite. See the simple example’s .cabal file for a demonstration. (This assumes that the test suite has the ability to read build artifacts from the library, a separate build component. In practice, this assumption holds, which is why this library works at all.) -
custom-setup
section is supported starting fromcabal-install-1.24
. For oldercabal-install's
you have to install custom setup dependencies manually. -
stack
respectscustom-setup
starting from version 1.3.3. Before that you have to useexplicit-setup-deps
setting in yourstack.yaml
. (stack/GH-2094) -
You can use
x-doctest-options
field intest-suite doctests
to pass additional flags to thedoctest
. -
For
build-type: Configure
packages, you can usedefaultMainAutoconfWithDoctests
function to make customSetup.hs
script. -
If you use the default
.
inhs-source-dirs
, then runningdoctests
might fail with weird errors (ambiguous module errors). Workaround is to move sources undersrc/
or some non-top-level directory. -
The
extensions:
field isn’t supported. Upgrade your.cabal
file to use at leastcabal-version: >= 1.10
and usedefault-extensions
orother-extensions
. -
If you use QuickCheck properties (
prop>
) in your doctests, thetest-suite doctest
should depend onQuickCheck
andtemplate-haskell
. This is a little HACK: These dependencies aren’t needed to build thedoctests
test-suite executable. However, as we letCabal
resolve dependencies, we can pass the resolved (and installed!) package identifiers to to thedoctest
command. This way,QuickCheck
andtemplate-haskell
are available todoctest
, otherwise you’ll get errors like:
Variable not in scope:
mkName
:: [Char]
-> template-haskell-2.11.1.0:Language.Haskell.TH.Syntax.Name
or
Variable not in scope:
polyQuickCheck
:: Language.Haskell.TH.Syntax.Name -> Language.Haskell.TH.Lib.ExpQ
-
From version 2, Stack sets the
GHC_ENVRIONMENT
variable, and GHC (as invoked bydoctest
) will pick that up. This is undesirable:cabal-doctest
passes all the necessary information on the command line already, and can lead to ambiguous module errors as GHC will load the environment in addition to whatcabal-doctest
instructs it to.Hence,
cabal-doctest
tells GHC to ignore package environments altogether on the command line. However, this is only possible since GHC 8.2. If you are usingcabal-doctest
with Stack 2 and GHC 8.0 or earlier and seeing ambiguous module errors or other mysterious failures, try manually unsettingGHC_ENVIRONMENT
before invokingdoctest
.
Copyright
Copyright 2017 Oleg Grenrus.
Available under the BSD 3-clause license.
Changes
1.0.9 – 2021-11-07
- Support
GHC-9.2
,base-4.16
, andCabal-3.6
(thanks Alistair Burrowes).
1.0.8 – 2019-10-02
- Pass
-package-env=-
when compiler supports it. - Amend examples to
unsetEnv "GHC_ENVIRONMENT"
.
1.0.7 – 2019-08-26
- Make
Distribution.Extra.Doctest
-Wall
-clean. - Support
GHC-8.8
,base-4.13
, andCabal-3.0
.
1.0.6 – 2018-01-28
- Hook
haddock
build too. Fixes issue whenhaddock
fails, asBuild_doctests
isn’t generated.
1.0.5 – 2018-01-26
- Add a hack so
Build_doctests
module is automatically added to toother-modules
andautogen-modules
when compiled with Cabal-2.0. Thanks to that, we don’t get warnings because of-Wmissing-home-modules
.
1.0.4 – 2017-12-05
- Add support for doctests in executables and (with
Cabal-2.0
or later) internal libraries. Refer to theREADME
for more details.
1.0.3 – 2017-11-02
- Add an explicit
Prelude
import toBuild_doctests
.
1.0.2 – 2017-05-16
- Add
defaultMainAutoconfWithDoctests
andaddDoctestsUserHook
. - Add support for
.hsc
and other preprocessed files (#8). - Add support for
x-doctest-source-dirs
andx-doctest-modules
.
1.0.1 – 2017-05-05
- Add support for
x-doctest-options
cabal-file field. - Proper support for
GHC-8.2.1
andCabal-2.0.0.0
. - Add support to
default-extensions
in library.
1 – 2017-01-31
- First version. Released on an unsuspecting world.