documentation for cabal-install configuration file

Question

The ~/.cabal/config stores configuration which cabal-install uses. I wanted to do some hackery on it. (Specifically, having multiple GHC versions installed, I wish to have separate documentation indexes).

I couldn't, however, find any documentation about its' syntax or variables except for what is included in default file. Is there any documentation available?

Edit: I've stated the goal above, but let me add some details: If the same package (eg. GTK) is installed in two versions of GHC they end up in the same documentation index file. I wan't that local documentation index to be separate for each GHC installation. I believe it is possible in some way using documentation directory setting, but there has to be a variable for currently used GHC version. If there isn't one there might be some workarounds available, but I won't be able to say that unless I see the documentation.

Answer 1

This seems to work, although I've only tested it with one version of GHC:

documentation: True
doc-index-file: $datadir/doc/$compiler/index.html

install-dirs user
    docdir: $datadir/doc/$compiler/$pkgid

With the other options left at the default, this generates documentation in .cabal/share/doc/<ghc-version>/<package-name>, and the index in .cabal/share/doc/<ghc-version>/index.html.

Answer 2

There appears to be very little online - not even the haddocks for the cabal-install code. So your best bet may be to puzzle it out from the source. cabal unpack cabal-install, or view the cabal-install repo online. Look at SavedConfig in Distribution/Client/Config.hs. As an example, it imports GlobalFlags from Setup.hs; the individual flags, eg globalCacheDir, are associated with their config-file syntax (which is also the command-line syntax) in the globalCommand function below, remote-repo-cache in this case.

You should also ask dcoutts in the #haskell channel on irc.freenode.net, in case he has new docs available.