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.

Fairway

Aren't the options in the config file pretty much the same as the command-line flags accepted by cabal install? – Spearmint

I'm not sure what you what to do. Maybe this helps: you can install multiple ghc into different dir, the packages in .cabal dir put installed package into different sub-dirs like 'parsec-3.1.1/ghc-7.0.4/' just change 'PATH' to use different ghcs. – Downtime

@Wu Xingbo: I'm assuming the goal is to use cabal install to install packages, but there's a single location for the config file so even with multiple copies of Cabal, there's no simple way to select a configuration. – Spearmint

@Wu Xinggbo: That would probably work, but I don't want to have multiple config files if possible. I already have a shell function for switching PATHs, but I would like to have it work for installed documentation as well. – Fairway

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.

Eocene

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.

Brazzaville