Skip to content

Extending Cabal

Jump to bottom
benmachine edited this page Mar 26, 2013 · 4 revisions

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.

Configure

  • Distribution/PackageDescription.hs (source) (docs): The first step is to make the necessary additions to PackageDescription. However, a PackageDescription is really the ultimate product of the configure stage. In order for configuration to proceed correctly, GenericPackageDescription must 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 PackageDescription and proper flag settings from a GenericPackageDescription. Also important is flattenPackageDescription, which naively transforms a PackageDescription into 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/Setup.hs (source) (docs): If your extension requires additional options to cabal configure, add them here. This file contains the declarations of all Cabal's command-line options.

  • 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 PackageDescription or LocalBuildInfo.

Build

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.

Test

Or, if not tests, then benchmarks or whatever it is that your extension does. I can't really help you here!

Sdist

  • 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!
Clone this wiki locally