Guide to the Cabal source code

On first look the Cabal code seems large and intimidating. This page is intended to give you a head start in understanding it.

Structure

All the Cabal modules live under Distribution.*

The modules can be roughly divided into to groups, the 'declarative' part and the 'active' part:

• The 'declarative' modules Distribution.* - they are mostly concerned with data structures like package descriptions.

• The 'active' modules Distribution.Simple.* - they are concerned with actually doing things like configuring, building and installing packages.

Declarative modules

• Distribution/GetOpt.hs - This should live under Compat/ it's just a bundled version of the standard GetOpt?. Not very interesting.
• Distribution/Setup.hs - This is a deprecated module here just so that old Setup.hs scripts do not break. Ignore it.

• Distribution/Version.hs - exports the Version type along with a parser and pretty printer. A version is something like "1.3.3". It also defines VersionRanges and Dependency data types. Version ranges are like ">= 1.2 && < 2". A dependency is a package name and a version range, like "foo >= 1.2 && < 2".
• Distribution/Package.hs - defines a package identifier along with a parser and pretty printer for it. PackageIdentifiers consist of a name and an exact version (exact as opposed to a dependency like above).

• Distribution/Verbosity.hs - a simple Verbosity type with associated utilities. There are 4 standard verbosity levels from Silent, Normal, Verbose up to Deafening. This is used for deciding what logging messages to print in the active parts.
• Distribution/Compiler.hs
• Distribution/System.hs
• Distribution/Extension.hs
• Distribution/License.hs

• Distribution/ParseUtils.hs
• Distribution/PackageDescription.hs
• Distribution/Configuration.hs
• Distribution/InstalledPackageInfo.hs

Active modules

Useful internal abstractions

• Distribution/Simple/Program.hs
• Distribution/Simple/Command.hs
• Distribution/Simple/InstallDirs.hs
• Distribution/Simple/Compiler.hs
• Distribution/Simple/PreProcess.hs

• Distribution/Simple/Utils.hs

• Distribution/Simple/LocalBuildInfo.hs

Particular phases or actions within the build process

• Distribution/Simple/Configure.hs
• Distribution/Simple/Build.hs
• Distribution/Simple/Install.hs
• Distribution/Simple/Haddock.hs
• Distribution/Simple/Register.hs
• Distribution/Simple/SrcDist.hs

Compiler-specific modules

• Distribution/Simple/GHC.hs
• Distribution/Simple/Hugs.hs
• Distribution/Simple/JHC.hs
• Distribution/Simple/NHC.hs

Stuff related to the front end

• Distribution/Simple/UserHooks.hs
• Distribution/Simple/Setup.hs

• Distribution/Simple/SetupWrapper.hs

Command line front ends

• Distribution/Simple.hs
• Distribution/Make.hs