gistfile1.txt

New summary by @ezyang.

The goal of this task is to add a new command `Setup doctest`, which runs the doctest command on all of the modules of each component in a package, in much the same way `Setup haddock` runs `haddock` on all the modules of each component in a package.

There are a number of steps to implementing this:

1. You have to add the boilerplate for setting doctest up as a new command. Grepping for occurrences of haddock should give you an idea for what you have to edit; the key files are `Cabal/Distribution/Simple/Setup.hs`, adding a case to `defaultMainHelper` in `Cabal/Distribution/Simple.hs`, and a new file to actually contain the logic. I'd recommend against putting too many flags into `DoctestFlags` when starting off.

2. The overall logic of the driver should be something like this:

```
 withAllComponentsInBuildOrder pkg_descr lbi $ \component clbi -> do
   componentInitialBuildSteps (flag haddockDistPref) pkg_descr lbi clbi verbosity
   preprocessComponent pkg_descr component lbi clbi False verbosity suffixes
   -- Do the actual invocation of doctest
```

   Between component, lbi and clbi, you will have all the information necessary to invoke doctest.

3. How should doctest actually be invoked? The arguments doctest accepts are identical to those that GHC accepts, so one reasonable approach is to find out where Cabal invokes GHC during a normal build and use that code. This code lives in https://github.com/haskell/cabal/blob/master/Cabal/Distribution/Simple/GHC.hs#L509 and 

1. Look at https://github.com/haskell/cabal/blob/master/Cabal/Distribution/Simple/GHC.hs#L509 which has the core logic for computing what flags we will 

Useful resources:

* https://github.com/haskell/cabal/blob/master/Cabal/Distribution/Simple/Haddock.hs is the existing code for Haddock. The code is somewhat crufty but should demonstrate many of the key APIs you may have to make use of when implementing doctest.

* https://github.com/phadej/cabal-doctest contains code to be used by Custom Setup scripts to add doctest support. In principle, one way you could implement this feature is to simply include all of the code from this extension into Cabal and wire up the extension to work. However, there may be opportunities to make changes to the Cabal library to support things more directly; for example, it may be wise to refactor the logic in https://github.com/haskell/cabal/blob/master/Cabal/Distribution/Simple/Build.hs for computing build arguments instead of reproducing it as it is in the custom. @phadej may be able to comment in this respect.