cabal-doctest 1.0.9 → 1.0.10
raw patch · 5 files changed
+234/−171 lines, 5 filesdep ~Cabaldep ~basedep ~directorynew-uploaderPVP ok
version bump matches the API change (PVP)
Dependency ranges changed: Cabal, base, directory, filepath
API changes (from Hackage documentation)
Files
- ChangeLog.md +0/−50
- README.md +121/−76
- cabal-doctest.cabal +31/−27
- changelog.md +58/−0
- src/Distribution/Extra/Doctest.hs +24/−18
− ChangeLog.md
@@ -1,50 +0,0 @@-# 1.0.9 -- 2021-11-07--* Support `GHC-9.2`, `base-4.16`, and `Cabal-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`, and `Cabal-3.0`.--# 1.0.6 -- 2018-01-28--* Hook `haddock` build too. Fixes issue when `haddock` fails, as- `Build_doctests` isn't generated.--# 1.0.5 -- 2018-01-26--* Add a hack so `Build_doctests` module is automatically added to- to `other-modules` and `autogen-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 the `README` for more details.--# 1.0.3 -- 2017-11-02--* Add an explicit `Prelude` import to `Build_doctests`.--# 1.0.2 -- 2017-05-16--* Add `defaultMainAutoconfWithDoctests` and `addDoctestsUserHook`.-* Add support for `.hsc` and other preprocessed files- ([#8](https://github.com/phadej/cabal-doctest/issues/8)).-* Add support for `x-doctest-source-dirs` and `x-doctest-modules`.--# 1.0.1 -- 2017-05-05--* Add support for `x-doctest-options` cabal-file field.-* Proper support for `GHC-8.2.1` and `Cabal-2.0.0.0`.-* Add support to `default-extensions` in library.--# 1 -- 2017-01-31--* First version. Released on an unsuspecting world.
README.md view
@@ -1,72 +1,74 @@ cabal-doctest ============= -[](https://hackage.haskell.org/package/cabal-doctest) [](https://github.com/haskellari/cabal-doctest/actions/workflows/haskell-ci.yml)+[](https://hackage.haskell.org/package/cabal-doctest) [](https://github.com/ulidtko/cabal-doctest/actions/workflows/haskell-ci.yml) -A `Setup.hs` helper for running `doctests`.+A `Setup.hs` helper for running [doctests][]. +[doctests]: https://github.com/sol/doctest#readme+ Simple example -------------- -For the typical use case, namely a `.cabal` file with a single library containing-doctests, adapting the [simple example](https://github.com/phadej/cabal-doctest/tree/master/simple-example)-will be sufficient.+[simple example]: https://github.com/ulidtko/cabal-doctest/tree/master/simple-example+[simple-example.cabal]: https://github.com/ulidtko/cabal-doctest/tree/master/simple-example/simple-example.cabal -To use this library in your `Setup.hs`, you should specify a `custom-setup`-section in your `.cabal` file. For example:+Follow [simple example][] for the common case of a single-library `.cabal` package with doctests. -```-custom-setup- setup-depends:- base >= 4 && <5,- Cabal,- cabal-doctest >= 1 && <1.1-```+To recap the example's code: -_Note:_ The `Cabal` dependency is only needed for `cabal-install < 2.4`-(see issue [haskell/cabal#4288](https://github.com/haskell/cabal/issues/4288)).+1. specify `build-type: Custom` in your `.cabal` file; -You'll also need to specify `build-type: Custom` at the top of the `.cabal`-file. Now put this into your `Setup.hs` file:+2. declare dependencies of `Setup.hs`: -```haskell-module Main where+ ```+ custom-setup+ setup-depends:+ base >= 4 && <5,+ cabal-doctest >= 1 && <1.1+ ``` -import Distribution.Extra.Doctest (defaultMainWithDoctests)+ See [Notes](#notes) below for a caveat with cabal-install < 2.4. -main :: IO ()-main = defaultMainWithDoctests "doctests"-```+3. Populate `Setup.hs` like so: -When you build your project, this `Setup` will generate a `Build_doctests`-module. To use it in a testsuite, simply do this:+ ```haskell+ module Main where -```haskell-module Main where+ import Distribution.Extra.Doctest (defaultMainWithDoctests) -import Build_doctests (flags, pkgs, module_sources)-import Data.Foldable (traverse_)-import System.Environment.Compat (unsetEnv)-import Test.DocTest (doctest)+ main :: IO ()+ main = defaultMainWithDoctests "doctests"+ ``` -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-```+ Assuming your test-suite is called `doctests`, this `Setup` will generate a `Build_doctests`+ module during package build. If your test-suite goes by name `foo`,+ `defaultMainWithDoctests "foo"` creates a `Build_foo` module. -(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.)+4. Use the generated module in a testsuite, simply like so: -Example with multiple .cabal components----------------------------------------+ ```haskell+ module Main where + import Build_doctests (flags, pkgs, module_sources)+ import Data.Foldable (traverse_)+ import System.Environment (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+ ```++Ultimately, `cabal test` or `stack test` should run the doctests of your package.++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: @@ -79,7 +81,7 @@ 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:+The simplest approach is to use `x-doctest-components` field in `.cabal`: ``` x-doctest-components: lib lib:internal exe:example ```@@ -91,7 +93,7 @@ import Build_doctests (Component (..), components) import Data.Foldable (for_)-import System.Environment.Compat (unsetEnv)+import System.Environment (unsetEnv) import Test.DocTest (doctest) main :: IO ()@@ -104,12 +106,10 @@ 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`).+There is also a more explicit approach: if you have an executable named `foo`, then+`Build_doctest` will contain `flags_exe_foo`, `pkgs_exe_foo`, and `module_sources_exe_foo`.+If the name has hyphens in it (e.g., `my-exe`), `cabal-doctest` will convert them to+underscores (e.g., you'd get `flags_my_exe`, `pkgs_my_exe`, `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:@@ -121,7 +121,7 @@ (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 System.Environment (unsetEnv) import Test.DocTest main :: IO ()@@ -139,14 +139,15 @@ exeArgs = flags_exe_my_exe ++ pkgs_exe_my_exe ++ module_sources_exe_my_exe ``` -See-[this example](https://github.com/phadej/cabal-doctest/tree/master/multiple-components-example)-for more details.+See the [multiple-components-example][]. +[multiple-components-example]: https://github.com/ulidtko/cabal-doctest/tree/master/multiple-components-example++ Additional configuration ------------------------ -The `cabal-doctest` based `Setup.hs` supports few extensions fields+The `cabal-doctest` based `Setup.hs` supports a few extensions fields in `pkg.cabal` files to customise the `doctest` runner behaviour, without customising the default `doctest.hs`. @@ -156,28 +157,27 @@ 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).+ have `doctest` in test or executables (i.e not default library component). * `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+* If support for cabal-install < 2.4 is required, you'll have to+ add `Cabal` to `setup-depends`; see issue [haskell/cabal#4288][].++* Some versions of `Cabal` (for instance, 2.0) can choose to build a package's `doctest` test suite _before_ the library. However, in order for `cabal-doctest` to work correctly, the library _must_ be built first, as `doctest` relies on the presence of generated files that are only created- when the library is built. See- [#19](https://github.com/phadej/cabal-doctest/issues/19).+ 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](https://github.com/phadej/cabal-doctest/blob/master/simple-example/simple-example.cabal)+ `doctests` test suite. See [simple-example.cabal][] 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.)@@ -187,9 +187,14 @@ 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))+ you have to use `explicit-setup-deps` setting in your `stack.yaml`;+ [stack#2094][]. +* With base < 4.7 (GHC < 7.8, pre-2014), `System.Environment.unsetEnv` function+ will need to be imported from `base-compat` library. It is already in transitive+ dependencies of `doctest`. Simply declare the dependency upon `base-compat`, and+ then `import System.Environment.Compat (unsetEnv)` if you need that old GHC.+ * You can use `x-doctest-options` field in `test-suite doctests` to pass additional flags to the `doctest`. @@ -211,22 +216,22 @@ to the `doctest` command. This way, `QuickCheck` and `template-haskell` are available to `doctest`, otherwise you'll get errors like: -```+ ``` Variable not in scope: mkName :: [Char] -> template-haskell-2.11.1.0:Language.Haskell.TH.Syntax.Name-```+ ``` -or+ 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+* From version 2, Stack sets the `GHC_ENVIRONMENT` variable, and GHC (as invoked by `doctest`) 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@@ -240,9 +245,49 @@ failures, try manually unsetting `GHC_ENVIRONMENT` before invoking `doctest`. + * If you are on Nix. `doctest` will not pick up your version of GHC if you+ don't point it towards it, and therefore will result in "cannot satisfy -package-id" errors.+ You will need to set `NIX_GHC` and `NIX_GHC_LIBDIR` within your environment in order+ for doctest to pick up your GHC. Put the following in `shell.nix` and run `nix-shell`.++ ```nix+ # shell.nix+ { pkgs ? import <nixpkgs> {} }:+ let+ myHaskell = (pkgs.haskellPackages.ghcWithHoogle (p: with p; [+ # Put your dependencies here+ containers+ hslogger+ ]));+ in+ pkgs.mkShell {+ name = "myPackage";++ # These environment variables are important. Without these,+ # doctest doesn't pick up nix's version of ghc, and will fail+ # claiming it can't find your dependencies+ shellHook = ''+ export NIX_GHC=${myHaskell}/bin/ghc+ export NIX_GHC_LIBDIR=${myHaskell}/lib/ghc-8.10.7+ '';+ buildInputs = with pkgs; [+ myHaskell+ ];+ }+ ```++[#19]: https://github.com/ulidtko/cabal-doctest/issues/19+[haskell/cabal#4288]: https://github.com/haskell/cabal/issues/4288+[stack#2094]: https://github.com/commercialhaskell/stack/issues/2094+ Copyright --------- Copyright 2017 Oleg Grenrus.++With contributions from:+ * Ryan Scott+ * Andreas Abel+ * Max Ulidtko Available under the BSD 3-clause license.
cabal-doctest.cabal view
@@ -1,58 +1,62 @@ name: cabal-doctest-version: 1.0.9+version: 1.0.10+-- x-revision: 0 synopsis: A Setup.hs helper for running doctests description: As of now (end of 2021), there isn't @cabal doctest@ command. Yet, to properly work, @doctest@ needs plenty of configuration. This library provides the common bits for writing a custom @Setup.hs@. -homepage: https://github.com/haskellari/cabal-doctest+homepage: https://github.com/ulidtko/cabal-doctest license: BSD3 license-file: LICENSE author: Oleg Grenrus <oleg.grenrus@iki.fi>-maintainer: Andreas Abel-copyright: (c) 2017 Oleg Grenrus+maintainer: Max Ulidtko <ulidtko@gmail.com>+copyright: (c) 2017-2020 Oleg Grenrus, 2020- package maintainers category: Distribution build-type: Simple cabal-version: >=1.10 extra-source-files:- ChangeLog.md+ changelog.md README.md tested-with:- GHC == 7.0.4- GHC == 7.2.2- GHC == 7.4.2- GHC == 7.6.3- GHC == 7.8.4- GHC == 7.10.3- GHC == 8.0.2- GHC == 8.2.2- GHC == 8.4.4- GHC == 8.6.5- GHC == 8.8.4+ GHC == 9.10.1+ GHC == 9.8.2+ GHC == 9.6.5+ GHC == 9.4.8+ GHC == 9.2.8+ GHC == 9.0.2 GHC == 8.10.7- GHC == 9.0.1- GHC == 9.2.1+ GHC == 8.8.4+ GHC == 8.6.5+ GHC == 8.4.4+ GHC == 8.2.2+ GHC == 8.0.2+ -- 2023-10-14: Dropped CI support for GHC 7.x source-repository head type: git- location: https://github.com/haskellari/cabal-doctest+ location: https://github.com/ulidtko/cabal-doctest library exposed-modules: Distribution.Extra.Doctest other-modules: other-extensions: build-depends:- base >=4.3 && <4.17- , Cabal >=1.10 && <3.8- , directory- , filepath+ -- NOTE: contrary to PVP, some upper-bounds are intentionally set to major-major.+ -- This is to increase signal-to-noise ratio of CI failures. "Too tight bounds"+ -- is an extremely boring (and practically guaranteed, repeatedly) failure mode.+ -- OTOH, genuine build failures due to breaking changes in dependencies are:+ -- 1) unlikely to occur, as this package is so small, moreso regularly;+ -- 2) best caught in CI pipelines that don't induce alert fatigue.+ -- In any case, revisions may set tighter bounds afterwards, if exceptional+ -- circumstances would warrant that.+ base >=4.9 && <5+ , Cabal >=1.10 && <3.14+ , directory >=1.3 && <2+ , filepath >=1.4 && <2 hs-source-dirs: src default-language: Haskell2010 ghc-options: -Wall-- if !impl(ghc >=7.2)- -- Work around a pattern-match coverage checking bug in GHC 7.0- ghc-options: -fno-warn-overlapping-patterns
+ changelog.md view
@@ -0,0 +1,58 @@+# 1.0.10 -- 2024-06-26++* Maintainership hand-over. See [cabal-doctest#79][].+* Support GHC 9.4, 9.6, 9.8, 9.10.+* Drop support & CI for GHC < 8.0.++[cabal-doctest#79]: https://github.com/ulidtko/cabal-doctest/issues/79++# 1.0.9 -- 2021-11-07++* Support `GHC-9.2`, `base-4.16`, and `Cabal-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`, and `Cabal-3.0`.++# 1.0.6 -- 2018-01-28++* Hook `haddock` build too. Fixes issue when `haddock` fails, as+ `Build_doctests` isn't generated.++# 1.0.5 -- 2018-01-26++* Add a hack so `Build_doctests` module is automatically added to+ to `other-modules` and `autogen-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 the `README` for more details.++# 1.0.3 -- 2017-11-02++* Add an explicit `Prelude` import to `Build_doctests`.++# 1.0.2 -- 2017-05-16++* Add `defaultMainAutoconfWithDoctests` and `addDoctestsUserHook`.+* Add support for `.hsc` and other preprocessed files+ ([#8](https://github.com/phadej/cabal-doctest/issues/8)).+* Add support for `x-doctest-source-dirs` and `x-doctest-modules`.++# 1.0.1 -- 2017-05-05++* Add support for `x-doctest-options` cabal-file field.+* Proper support for `GHC-8.2.1` and `Cabal-2.0.0.0`.+* Add support to `default-extensions` in library.++# 1 -- 2017-01-31++* First version. Released on an unsuspecting world.
src/Distribution/Extra/Doctest.hs view
@@ -1,26 +1,30 @@ {-# LANGUAGE CPP #-} {-# LANGUAGE OverloadedStrings #-}--- | The provided 'generateBuildModule' generates 'Build_doctests' module.--- That module exports enough configuration, so your doctests could be simply+-- | See cabal-doctest README for full-fledged recipes & caveats. --+-- The provided 'generateBuildModule' generates a @Build_{suffix}@ module, with+-- caller-chosen @suffix@ that is usually @"doctests"@ -- module @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 Data.Foldable (traverse_) -- import Test.Doctest (doctest) -- -- main :: IO ()--- main = do--- traverse_ putStrLn args -- optionally print arguments--- doctest args+-- main = doctest args -- where -- args = flags ++ pkgs ++ module_sources -- @ ----- To use this library in the @Setup.hs@, you should specify a @custom-setup@--- section in the cabal file, for example:+-- 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:@@ -28,8 +32,8 @@ -- cabal-doctest >= 1 && <1.1 -- @ ----- /Note:/ you don't need to depend on @Cabal@ if you use only--- 'defaultMainWithDoctests' in the @Setup.hs@.+-- Finally, simple shortcuts are provided to avoid an explicit dependency on @Cabal@+-- from @setup-depends@: 'defaultMainWithDoctests' and 'defaultMainAutoconfWithDoctests'. -- module Distribution.Extra.Doctest ( defaultMainWithDoctests,@@ -125,7 +129,7 @@ (libraryNameString) #endif -#if MIN_VERSION_Cabal(3,6,0)+#if MIN_VERSION_Cabal(3,5,0) import Distribution.Utils.Path (getSymbolicPath) #endif@@ -160,7 +164,7 @@ -- Mains ------------------------------------------------------------------------------- --- | A default main with doctests:+-- | A default @Setup.hs@ main with doctests: -- -- @ -- import Distribution.Extra.Doctest@@ -174,7 +178,7 @@ -> IO () defaultMainWithDoctests = defaultMainWithHooks . doctestsUserHooks --- | Like 'defaultMainWithDoctests', for 'build-type: Configure' packages.+-- | Like 'defaultMainWithDoctests', but for packages with @build-type: Configure@. -- -- @since 1.0.2 defaultMainAutoconfWithDoctests@@ -183,24 +187,26 @@ defaultMainAutoconfWithDoctests n = defaultMainWithHooks (addDoctestsUserHook n autoconfUserHooks) --- | 'simpleUserHooks' with 'generateBuildModule' prepended to the 'buildHook'.+-- | 'simpleUserHooks' with 'generateBuildModule' already wired-in. doctestsUserHooks :: String -- ^ doctests test-suite name -> UserHooks doctestsUserHooks testsuiteName = addDoctestsUserHook testsuiteName simpleUserHooks --- |+-- | Compose 'generateBuildModule' into Cabal's 'UserHooks' (prepending the action). --+-- This is exported for advanced custom Setup-s.+-- -- @since 1.0.2 addDoctestsUserHook :: String -> UserHooks -> UserHooks addDoctestsUserHook testsuiteName uh = uh { buildHook = \pkg lbi hooks flags -> do generateBuildModule testsuiteName flags pkg lbi buildHook uh pkg lbi hooks flags- -- We use confHook to add "Build_Doctests" to otherModules and autogenModules.+ -- We use confHook to add "Build_doctests" to otherModules and autogenModules. --- -- We cannot use HookedBuildInfo as it let's alter only the library and executables.+ -- We cannot use HookedBuildInfo as it lets alter only the library and executables. , confHook = \(gpd, hbi) flags -> confHook uh (amendGPD testsuiteName gpd, hbi) flags , haddockHook = \pkg lbi hooks flags -> do@@ -331,7 +337,7 @@ <- mapM makeAbsolute $ compAutogenDir -- autogenerated files : (distPref ++ "/build") -- preprocessed files (.hsc -> .hs); "build" is hardcoded in Cabal.-#if MIN_VERSION_Cabal(3,6,0)+#if MIN_VERSION_Cabal(3,5,0) : map getSymbolicPath (hsSourceDirs compBI) #else : hsSourceDirs compBI