Changes between Version 2 and Version 3 of SourceGuide

Timestamp:

01/25/08 09:26:29 (5 years ago)

Author:

duncan

Comment:

Add more content and use definition list syntax.

SourceGuide

@@ -7 +7 @@
 All the Cabal modules live under `Distribution.*`
 
-The modules can be roughly divided into to groups, the 'declarative' part and the 'active' part:
+The modules can be roughly divided into two groups:
 
- * The 'declarative' modules `Distribution.*` - they are mostly concerned with data structures like package descriptions.
+ The '''declarative''' modules::
+  They are mostly concerned with data structures like package descriptions. These modules live under `Distribution.*`.
+  Much of the code in these modules are utility functions for handling the data types and also functions for parsing and showing them.
 
- * The 'active' modules `Distribution.Simple.*` - they are concerned with actually doing things like configuring, building and installing packages.
+ The '''active''' modules::
+  They are concerned with actually doing things like configuring, building and installing packages. These modules live under `Distribution.Simple.*`.
 
 === 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.
+A couple really dull modules
 
- * 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 `VersionRange`s 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. `PackageIdentifier`s consist of a name and an exact version (exact as opposed to a dependency like above).
+ `Distribution/GetOpt.hs`::
+  This should live under Compat/ it's just a bundled version of the standard !GetOpt. Not very interesting.
 
- * 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/Setup.hs`::
+  This is a deprecated module here just so that old `Setup.hs` scripts do not break. Ignore it.
 
- * Distribution/ParseUtils.hs
+ `Distribution/Extension.hs`::
+  This is also a deprecated module here just so that old code does not break. The module got renamed to `Language.Haskell.Extension`.
+
+Some simple data types:
+
+ `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 `VersionRange`s 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. `PackageIdentifier`s consist of a name and an exact version
+ (exact version as opposed to a dependency like above that uses a version range).
+
+ `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`::
+  This has an enumeration of the various compilers that Cabal knows about. It also specifies the default compiler. Sadly you'll often see code 
+  that does case analysis on this compiler flavour enumeration like:
+  {{{
+  case compilerFlavor comp of
+    GHC -> GHC.getInstalledPackages verbosity packageDb progconf
+    JHC -> JHC.getInstalledPackages verbosity packageDb progconf
+
+  }}}
+  Obviously it would be better to use the proper `Compiler` abstraction because that would keep all the compiler-specific code together.
+  Unfortunately we cannot make this change yet without breaking the `UserHooks` api, which would break all custom `Setup.hs` files, so for the
+  moment we just have to live with this deffeciency. If you're interested, see ticket #50.
+
+ `Distribution/System.hs`::
+  Cabal often needs to do slightly different things on specific platforms. You probably know about the `System.Info.os :: String` however using
+  that is very inconvenient because it is a string and different Haskell implementations do not agree on using the same strings for the same
+  platforms! (In particular see the controversy over "windows" vs "ming32"). So to make it more consistent and easy to use we have an `OS`
+  enumeration.
+
+ `Distribution/License.hs`::
+  The `.cabal` file allows you to specify a license file. Of course you can use any license you like but people often pick common open source
+  licenses and it's useful if we can automatically recognise that (eg so we can display it on the hackage web pages). So you can also specify the
+  license itself in the `.cabal` file from a short enumeration defined in this module. It includes `GPL`, `LGPL` and `BSD3` licenses.
+
+ `Distribution/ParseUtils.hs`::
+  The `.cabal` file format is not trivial, especially with the introduction of configurations and the section syntax that goes with that.
+  This module has a bunch of parsing functions that is used by the `.cabal` parser and a couple others. It has the parsing framework code and
+  also little parsers for many of the formats we get in various `.cabal` file fields, like module names, comma separated lists etc.
+
  * Distribution/PackageDescription.hs
  * Distribution/Configuration.hs