Clone this wiki locally
Imported from Trac wiki; be wary of outdated information or markup mishaps.
Extending Cabal's Package Description Format
This page is intended to serve as a retrospective on the implementation of the new test suite interface, in the hope that this information will be useful to the effort to add a benchmark interface. This is a very broad overview now until I have a chance to fill in all the details.
Distribution/PackageDescription.hs (source) (docs): The first step is to make the necessary additions to
PackageDescription. However, a
PackageDescriptionis really the ultimate product of the configure stage. In order for configuration to proceed correctly,
GenericPackageDescriptionmust also be updated so that flags can be resolved correctly.
Distribution/PackageDescription/Parse.hs (source) (docs): Before Cabal can configure packages with the extended package description format, it needs to be able to parse it. Parsing starts in
parsePackageDescription. You can refer to the test suite stanza parser as an example, but the executable stanza parser is simpler to understand. (The test suite stanza parser is more complicated because it's impossible to tell if the stanza is syntactically correct until the entire stanza has been parsed.)
Distribution/PackageDescription/Configuration.hs (source) (docs): This module provides
finalizePackageDescription, which takes user flag settings and system information to produce a
PackageDescriptionand proper flag settings from a
GenericPackageDescription. Also important is
flattenPackageDescription, which naively transforms a
GenericPackageDescription. You will need to modify both to populate the new
PackageDescription. (TODO: This is a nontrivial step and deserves to be documented further.)
Distribution/Simple/Configure.hs (source) (docs): Configuration starts in
configure. The ultimate goal is to produce a
LocalBuildInfo. Each element of the
PackageDescription(library, executable, test suite, benchmark, etc.) should have an entry in the
LocalBuildInfo. If an element will not be built (e.g., test suites when tests are disabled), it should not be present in the final
The build phase is actually very simple compared to configuration.
- Distribution/Simple/Build.hs (source) (docs): The build phase begins here. Most of the work is actually delegated to compiler-specific code elsewhere. Chances are that whatever you are building is either a library or an executable, so start by trying to emulate one of those processes if possible.
Or, if not tests, then benchmarks or whatever it is that your extension does. I can't really help you here!
- Distribution/Simple/SrcDist.hs (source) (docs): The sdist phase is also pretty simple, just try to emulate Cabal's treatment of libraries or executables. Cabal packages each library or executable and the modules it depends upon. However, autogenerated modules must be removed from the list of depended-upon modules first!