Documentation for build-tools

[ghost]

Is there documentation for the build-tools option of the cabal file? If so, where can I find it.

In particular I would like to know:
how to use build-tools, what programs (other than alex and happy) are legal arguments to the build-tools options, how and in what order the build-tools are run?
Some other questions I have are:
Do alex and happy (or any tools for that matter) need to be included in the build-depends argument list?
Do the AlexScannerFile.x and HappyParserFile.y need to be included somewhere in the cabal file?
Do the files generated by Alex and Happy -- the AlexScannerFile.hs and HappyParserFile.hs -- need to be in other-modules?

Thank you for your help!!

[23Skidoo]

There is some documentation here, but it could definitely be improved.

how to use build-tools, what programs (other than alex and happy) are legal arguments to the build-tools options, how and in what order the build-tools are run?

The programs known to Cabal are listed here. Tools that generate .hs sources are run before ghc.

Do alex and happy (or any tools for that matter) need to be included in the build-depends argument list?

No.

Do the AlexScannerFile.x and HappyParserFile.y need to be included somewhere in the cabal file?

You only need to list AlexScannerFile and HappyParserFile in other-modules or exposed-modules.

[gbaz]

Is this issue resolved by the current docs? http://cabal.readthedocs.io/en/latest/developing-packages.html?highlight=build-tools#pkg-field-build-tool-depends

[linearray]

Docs now list acceptable values in great detail, so I'm quite sure this is fixed.

[andreasabel]

Is this issue resolved by the current docs? http://cabal.readthedocs.io/en/latest/developing-packages.html?highlight=build-tools#pkg-field-build-tool-depends

This link does not point to a description of build-tools.

Here is a short reference: https://cabal.readthedocs.io/en/latest/cabal-package.html#pkg-field-build-tool-depends
However, I do not see how this explains how build tools work. How does the mere mention of the executables needed for the build explain which Haskell files they create from which sources? Where do I specify that by great build tool buildit creates a Haskell file for a .blit file? (Like happy creates a Haskell file from a .y file.)

[fgaz]

@andreasabel
The preprocessor section lists the extensions natively supported by Cabal.
Adding custom preprocessors is explained here, or can be done with the GHC -F flag.

Maybe we should cross-link those sections