Add a doctest-% pattern target

[philderbeast]

Fixes #11798. Adds a make help item doctest-PACKAGENAME and targets for running doctests for a single package using a doctest-% pattern rule.

$ make help
...
doctest-PACKAGENAME            Run doctests for a single package (replace PACKAGENAME).
doctest-install                Install doctest tool needed for running doctests.
doctest                        Run doctests in all packages.

$ make doctest-PACKAGENAME
Please use one of the following targets:
doctest-Cabal
doctest-Cabal-described
doctest-Cabal-syntax
doctest-cabal-install
doctest-cabal-install-solver
doctest-cabal-testsuite

Note

There were doctests in cabal-testsuite. These weren't being run before and cannot be run with cd cabal-testsuite && cabal doctest so these use REPL_WITH_DOCTEST. I renamed DOCTEST to CABAL_DOCTEST.

---

• Patches conform to the coding conventions.
• Is this a PR that fixes CI? If so, it will need to be backported to older cabal release branches (ask maintainers for directions).

[ulysses4ever]

thanks for the split but the PR title is still far from what is actually done because of how much is done. I think adding convenience targets and switching between cabal doctest and cabal repl should be different PRs. The latter is highly questionable for me while the former is a no brainer (well, if not for the metaprogramming).

[sol]

There were doctests in cabal-testsuite. These weren't being run before and cannot be run with cd cabal-testsuite && cabal doctest so these use REPL_WITH_DOCTEST. I renamed DOCTEST to CABAL_DOCTEST.

Is this still the case with cabal doctest 0.25.0?

If yes, what is the exact error you are encountering?

[philderbeast]

Is this still the case with cabal doctest 0.25.0?

I saw a different error with doctest-0.24.3 but for doctest-0.25.0 I'm seeing this error using cabal doctest to test cabal-testsuite with ghc-9.12.4:

$ make doctest-cabal-testsuite
...
Configuring cabal-testsuite-3...
unrecognized 'repl' option `--keep-temp-files'
Error: [Cabal-7125]
repl failed for cabal-testsuite-3.
make: *** [Makefile:171: doctest-cabal-testsuite] Error 1

And with cabal repl --with-compiler=doctest, I'm seeing this error with doctest-0.25.0:

$ make doctest-cabal-testsuite
Running doctests for cabal-testsuite:
doctest: unrecognized option `--make'
Try `doctest --help' for more information.
Error: [Cabal-7125]
Failed to build Cabal-syntax-3.17.0.0 (which is required by cabal-testsuite-3).
make: *** [Makefile:171: doctest-cabal-testsuite] Error 1

[sol]

How am I supposed to build the test suite?

$ git rev-parse HEAD
a51c4ee1556d816ad86e90db7e6330dd51b0b6e7
$ cd cabal-testsuite
$ cabal build .
Resolving dependencies...
Error: [Cabal-7107]
Could not resolve dependencies:
[__0] trying: cabal-testsuite-3 (user goal)
[__1] unknown package: Cabal-tests (dependency of cabal-testsuite)
[__1] fail (backjumping, conflict set: Cabal-tests, cabal-testsuite)
After searching the rest of the dependency tree exhaustively, these were the goals I've had most trouble fulfilling: cabal-testsuite, Cabal-tests

[philderbeast]

How am I supposed to build the test suite?

- $ cabal build .
+ $ cabal build . --project-dir=..

[ulysses4ever]

cabal is supposed to detect project files up the directory tree though. This is a strange error.

[sol]

-- This intercepting project is here to avoid tests picking up a cabal.project
-- from a parent directory, such as the one in the root of the `haskell/cabal`
-- project itself. Having `optional-packages: .` avoids the following warning
-- being added to the `.out` file:
--   Warning: There are no packages or optional-packages in the project
optional-packages: .

Does cabal have anything akin to -C, if yes, I think setting that to a temporary directory would be a better approach. If you don't need parallel test execution, then changing the working directory also would work.

[sol]

$ cd cabal-testsuite/
$ rm cabal.project
$ mkdir -p foo && cabal repl --keep-temp-files --repl-multi-file foo
Configuration is affected by cabal.project at
'/home/sol/projects/haskell/cabal'.
Build profile: -w ghc-9.14.1 -O1
In order, the following will be built (use -v for more details):
 - cabal-testsuite-3 (interactive) (file /home/sol/projects/haskell/cabal/dist-newstyle/build/x86_64-linux/ghc-9.14.1/Cabal-tests-3/cache/build changed)
unrecognized 'repl' option `--keep-temp-files'
Error: [Cabal-7125]
repl failed for cabal-testsuite-3.

Does anybody know what's wrong with this cabal invocation?

If this doesn't work, cabal doctest can't possibly work.