Changes between Version 9 and Version 10 of SourceGuide

Timestamp:

01/28/08 05:53:27 (5 years ago)

Author:

duncan

Comment:

document install, register, haddock and srcdist modules

SourceGuide

@@ -183 +183 @@
 
  `Distribution/Simple/Install.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/Install.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-Install.html docs])::
+  This is the entry point into installing a built package. It does the generic bits and then calls compiler-specific functions to do
+  the rest.
 
  `Distribution/Simple/Haddock.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/Haddock.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-Haddock.html docs])::
+  This module deals with the haddock and hscolour commands. Sadly this is a rather complicated module. It deals with two versions
+  of haddock (0.x and 2.x). It has to do pre-processing for haddock 0.x which involves 'unlit'ing and using -D__HADDOCK__ for any
+  source code that uses cpp. It has to call ghc-pkg to find the locations of documentation for dependent packages, so it can create
+  links. The hscolour support allows generating html versions of the original source, with coloured syntax highlighting.
 
  `Distribution/Simple/Register.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/Register.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-Register.html docs])::
+  This module deals with registering and unregistering packages. There are a couple ways it can do this, one is to do it directly.
+  Another is to generate a script that can be run later to do it. The idea here being that the user is shielded from the details of
+  what command to use for package registration for a particular compiler. In practice this aspect was not especially popular so we
+  also provide a way to simply generate the package registration file which then must be manually passed to ghc-pkg. It is possible
+  to generate registration information for where the package is to be installed, or alternatively to register the package inplace
+  in the build tree. The latter is occasionally handy, and will become more important when we try to build multi-package systems.
+  This module does not delegate anything to the per-compiler modules but just mixes it all in in this module, which is rather
+  unsatisfactory. The script generation and the unregister feature are not well used or tested.
 
  `Distribution/Simple/SrcDist.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/SrcDist.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-SrcDist.html docs])::
+  This handles the `sdist` command. The module exports an `sdist` action but also some of the phases that make it up so that other
+  tools can use just the bits they need. In particular the preparation of the tree of files to go into the source tarball is separated
+  from actually building the source tarball. The `createArchive` action uses the external `tar` program and assumes that it accepts
+  the `-z` flag. Neither of these assumptions are valid on Windows (see ticket #40).
+  The `sdist` action now also does some distribution QA checks.
 
 === Compiler-specific modules ===