Changes between Version 5 and Version 6 of SourceGuide

Timestamp:

01/26/08 08:55:34 (5 years ago)

Author:

duncan

Comment:

document the internal abstractions and a couple phases

SourceGuide

@@ -102 +102 @@
 
  `Distribution/Simple/Program.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/Program.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-Program.html docs])::
+  This provides an abstraction which deals with configuring and running programs. A `Program` is a static notion of a known program.
+  A `ConfiguredProgram` is a `Program` that has been found on the current machine and is ready to be run (possibly with some user-supplied
+  default args). Configuring a program involves finding its location and if necessary finding its version. There is also a `ProgramConfiguration`
+  type which holds configured and not-yet configured programs. It is the parameter to lots of actions elsewhere in Cabal that need to look up and
+  run programs. If we had a Cabal monad, the `ProgramConfiguration` would probably be a reader or state component of it.
+
+  The module also defines all the known built-in `Program`s and the `defaultProgramConfiguration` which contains them all.
 
  `Distribution/Simple/Command.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/Command.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-Command.html docs])::
+  This is to do with command line handling. The Cabal command line is organised into a number of named sub-commands (much like darcs).
+  The `Command` abstraction represents one of these sub-commands, with a name, description, a set of flags. `Command`s can be associated with
+  actions and run. It handles some common stuff automatically, like the `--help` and command line completion flags. It is designed to allow
+  other tools make derived commands. This feature is used heavily in CabalInstall.
 
  `Distribution/Simple/InstallDirs.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/InstallDirs.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-InstallDirs.html docs])::
+  This manages everything to do with where files get installed (though does not get involved with actually doing any installation). It provides an
+  `InstallDirs` type which is a set of directories for where to install things. It also handles the fact that we use templates in these install
+  dirs. For example most install dirs are relative to some `$prefix` and by changing the prefix all other dirs still end up changed appropriately.
+  So it provides a `PathTemplate` type and functions for substituting for these templates.
 
  `Distribution/Simple/Compiler.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/Compiler.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-Compiler.html docs])::
+  This should be a much more sophisticated abstraction than it is. Currently it's just a bit of data about the compiler, like it's flavour
+  and name and version. The reason it's just data is because currently it has to be in `Read` and `Show` so it can be saved along with the
+  `LocalBuildInfo`. The only interesting bit of info it contains is a mapping between language extensions and compiler command line flags.
+  This module also defines a `PackageDB` type which is used to refer to package databases. Most compilers only know about a single global
+  package collection but GHC has a global and per-user one and it lets you create arbitrary other package databases. We do not yet support
+  this latter feature very much.
 
  `Distribution/Simple/PreProcess.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/PreProcess.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-PreProcesshtml docs])::
+  This defines a `PreProcessor` abstraction which represents a pre-processor that can transform one kind of file into another.
+  There is also a `PPSuffixHandler` which is a combination of a file extension and a function for configuring a `PreProcessor`. It defines a
+  bunch of known built-in preprocessors like cpp, cpphs, c2hs, hsc2hs, happy, alex etc and lists them in `knownSuffixHandlers`.  On top of this
+  it provides a function for actually preprocessing some sources given a bunch of known suffix handlers. This module is not as good as it could
+  be, it could really do with a rewrite to address some of the problems we have with pre-processors.
 
  `Distribution/Simple/Utils.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/Utils.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-Utils.html docs])::
+  A large and somewhat miscellaneous collection of utility functions used throughout the rest of the Cabal lib and in other tools that use the
+  Cabal lib like CabalInstall. It has a very simple set of logging actions. It has low level functions for running programs, a bunch of wrappers
+  for various directory and file functions that do extra logging.
 
  `Distribution/Simple/LocalBuildInfo.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/LocalBuildInfo.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-LocalBuildInfo.html docs])::
+  Once a package has been configured we have resolved conditionals and dependencies, configured the compiler and other needed external programs.
+  The `LocalBuildInfo` is used to hold all this information. It holds the install dirs, the compiler, the exact package dependencies, the
+  configured programs, the package database to use and a bunch of miscellaneous configure flags. It gets saved and reloaded from a file
+  (`dist/setup-config`). It gets passed in to very many subsequent build actions.
 
 === Particular phases or actions within the build process ===
 
  `Distribution/Simple/Configure.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/Configure.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-Configure.html docs])::
+  This deals with the ''configure'' phase. It provides the `configure` action which is given the package description and configure flags. It then
+  tries to:
+   * configure the compiler
+   * resolves any conditionals in the package description
+   * resolve the package dependencies
+   * check if all the extensions used by this package are supported by the compiler
+   * check that all the build tools are available (including version checks if appropriate)
+   * checks for any required pkg-config packages (updating the `BuildInfo` with the results)
+  Then based on all this it saves the info in the `LocalBuildInfo` and writes it out to a file. It also displays various details to the user,
+  the amount of information displayed depending on the verbosity level.
 
  `Distribution/Simple/Build.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/Build.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-Build.html docs])::
+  This is the entry point to actually building the modules in a package. It doesn't actually do much itself, most of the work is delegated
+  to compiler-specific actions. It does do some non-compiler specific bits like running pre-processors. There's some stuff to do with generating
+  `makefile`s which is a well hidden feature that's used to build libraries inside the GHC build system but which we'd like to kill off and replace
+  with something better (doing our own dependency analysis properly).
+  
+  Half the module is dedicated to generating the `Paths_`''pkgname'' module. This is a module that Cabal generates for the benefit of packages.
+  It enables them to find their version number and find any installed data files at runtime. This code should probably be split off into another
+  module.
 
  `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])::