Changes between Version 4 and Version 5 of SourceGuide

Show
Ignore:
Timestamp:
01/26/08 07:27:52 (5 years ago)
Author:
duncan
Comment:

add source and doc links and improve sections

Legend:

Unmodified
Added
Removed
Modified

  • SourceGuide

    v4 v5  
    1616  They are concerned with actually doing things like configuring, building and installing packages. These modules live under `Distribution.Simple.*`. 
    1717 
    18 === Declarative modules === 
     18== Declarative modules == 
    1919 
    20 A couple really dull modules 
     20=== A few really dull modules === 
    2121 
    22  `Distribution/GetOpt.hs`:: 
     22 `Distribution/GetOpt.hs` ([http://darcs.haskell.org/cabal/Distribution/GetOpt.hs source]) (no docs - hidden module):: 
    2323  This should live under Compat/ it's just a bundled version of the standard !GetOpt. Not very interesting. 
    2424 
    25  `Distribution/Setup.hs`:: 
     25 `Distribution/Setup.hs` ([http://darcs.haskell.org/cabal/Distribution/Setup.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Setup.html docs]):: 
    2626  This is a deprecated module here just so that old `Setup.hs` scripts do not break. Ignore it. 
    2727 
    28  `Distribution/Extension.hs`:: 
     28 `Distribution/Extension.hs` ([http://darcs.haskell.org/cabal/Distribution/Extension.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Extension.html docs]):: 
    2929  This is also a deprecated module here just so that old code does not break. The module got renamed to `Language.Haskell.Extension`. 
    3030 
    31 Some simple data types: 
     31=== Some simple data types === 
    3232 
    33  `Distribution/Version.hs`:: 
     33 `Distribution/Version.hs` ([http://darcs.haskell.org/cabal/Distribution/Version.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Version.html docs]):: 
    3434  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 
    3535  `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". 
    3636 
    37  `Distribution/Package.hs`:: 
     37 `Distribution/Package.hs` ([http://darcs.haskell.org/cabal/Distribution/Package.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Package.html docs]):: 
    3838  defines a package identifier along with a parser and pretty printer for it. `PackageIdentifier`s consist of a name and an exact version 
    3939 (exact version as opposed to a dependency like above that uses a version range). 
    4040 
    41  `Distribution/Verbosity.hs`:: 
     41 `Distribution/Verbosity.hs` ([http://darcs.haskell.org/cabal/Distribution/Verbosity.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Verbosity.html docs]):: 
    4242  a simple `Verbosity` type with associated utilities. There are 4 standard verbosity levels from `Silent`, `Normal`,  `Verbose` up to `Deafening`. 
    4343  This is used for deciding what logging messages to print in the active parts. 
    44  `Distribution/Compiler.hs`:: 
     44 
     45 `Distribution/Compiler.hs` ([http://darcs.haskell.org/cabal/Distribution/Compiler.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Compiler.html docs]):: 
    4546  This has an enumeration of the various compilers that Cabal knows about. It also specifies the default compiler. Sadly you'll often see code  
    4647  that does case analysis on this compiler flavour enumeration like: 
    … …  
    5556  moment we just have to live with this deffeciency. If you're interested, see ticket #50. 
    5657 
    57  `Distribution/System.hs`:: 
     58 `Distribution/System.hs` ([http://darcs.haskell.org/cabal/Distribution/System.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-System.html docs]):: 
    5859  Cabal often needs to do slightly different things on specific platforms. You probably know about the `System.Info.os :: String` however using 
    5960  that is very inconvenient because it is a string and different Haskell implementations do not agree on using the same strings for the same 
    … …  
    6162  enumeration. 
    6263 
    63  `Distribution/License.hs`:: 
     64 `Distribution/License.hs` ([http://darcs.haskell.org/cabal/Distribution/License.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-License.html docs]):: 
    6465  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 
    6566  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 
    6667  license itself in the `.cabal` file from a short enumeration defined in this module. It includes `GPL`, `LGPL` and `BSD3` licenses. 
    6768 
    68  `Distribution/ParseUtils.hs`:: 
     69=== The package description data types === 
     70 
     71 `Distribution/ParseUtils.hs` ([http://darcs.haskell.org/cabal/Distribution/ParseUtils.hs source]) (no docs - hidden module):: 
    6972  The `.cabal` file format is not trivial, especially with the introduction of configurations and the section syntax that goes with that. 
    7073  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 
    7174  also little parsers for many of the formats we get in various `.cabal` file fields, like module names, comma separated lists etc. 
    7275 
    73  `Distribution/PackageDescription.hs`:: 
     76 `Distribution/PackageDescription.hs` ([http://darcs.haskell.org/cabal/Distribution/PackageDescription.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-PackageDescription.html docs]):: 
    7477  This is a big one. It defines the data structure for the `.cabal` file format. There are several parts to this structure. It has top level info 
    7578  and then `Library` and `Executable` sections each of which have associated `BuildInfo` data that's used to build the library or exe. To further 
    … …  
    8285  translate into the newer structure. 
    8386 
    84  `Distribution/Configuration.hs`:: 
     87 `Distribution/Configuration.hs` ([http://darcs.haskell.org/cabal/Distribution/Configuration.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Configuration.html docs]):: 
    8588  This is about the [CabalConfigurations cabal configurations] feature. It has code for working with the tree of conditions and resolving or 
    8689  flattening conditions. This is used by `finalizePackageDescription` and `flattenPackageDescription`. 
    8790 
    88  `Distribution/InstalledPackageInfo.hs`:: 
     91 `Distribution/InstalledPackageInfo.hs` ([http://darcs.haskell.org/cabal/Distribution/InstalledPackageInfo.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-InstalledPackageInfo.html docs]):: 
    8992  The `.cabal` file format is for describing a package that is not yet installed. It has a lot of flexibility like conditionals and dependency 
    9093  ranges. As such that format is not at all suitable for describing a package that has already been built and installed. By the time we get to 
    … …  
    9497  understands. 
    9598 
    96 === Active modules === 
     99== Active modules == 
    97100 
    98 Useful internal abstractions 
     101=== Useful internal abstractions === 
    99102 
    100  `Distribution/Simple/Program.hs`:: 
    101  `Distribution/Simple/Command.hs`:: 
    102  `Distribution/Simple/InstallDirs.hs`:: 
    103  `Distribution/Simple/Compiler.hs`:: 
    104  `Distribution/Simple/PreProcess.hs`:: 
     103 `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]):: 
    105104 
    106  `Distribution/Simple/Utils.hs`:: 
     105 `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]):: 
    107106 
    108  `Distribution/Simple/LocalBuildInfo.hs`:: 
     107 `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]):: 
    109108 
    110 Particular phases or actions within the build process 
     109 `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]):: 
    111110 
    112  `Distribution/Simple/Configure.hs`:: 
    113  `Distribution/Simple/Build.hs`:: 
    114  `Distribution/Simple/Install.hs`:: 
    115  `Distribution/Simple/Haddock.hs`:: 
    116  `Distribution/Simple/Register.hs`:: 
    117  `Distribution/Simple/SrcDist.hs`:: 
     111 `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]):: 
    118112 
    119 Compiler-specific modules 
     113 `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]):: 
    120114 
    121  `Distribution/Simple/GHC.hs`:: 
    122  `Distribution/Simple/Hugs.hs`:: 
    123  `Distribution/Simple/JHC.hs`:: 
    124  `Distribution/Simple/NHC.hs`:: 
     115 `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]):: 
    125116 
    126 Stuff related to the front end 
     117=== Particular phases or actions within the build process === 
    127118 
    128  `Distribution/Simple/UserHooks.hs`:: 
    129  `Distribution/Simple/Setup.hs`:: 
     119 `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]):: 
    130120 
    131  `Distribution/Simple/SetupWrapper.hs`:: 
     121 `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]):: 
    132122 
    133 Command line front ends 
     123 `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]):: 
    134124 
    135  `Distribution/Simple.hs`:: 
     125 `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]):: 
    136126 
    137  `Distribution/Make.hs`:: 
     127 `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]):: 
     128 
     129 `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]):: 
     130 
     131=== Compiler-specific modules === 
     132 
     133 `Distribution/Simple/GHC.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/GHC.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-GHC.html docs]):: 
     134 
     135 `Distribution/Simple/Hugs.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/Hugs.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-Hugs.html docs]):: 
     136 
     137 `Distribution/Simple/JHC.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/JHC.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-JHC.html docs]):: 
     138 
     139 `Distribution/Simple/NHC.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/NHC.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-NHC.html docs]):: 
     140 
     141=== Stuff related to the front end === 
     142 
     143 `Distribution/Simple/UserHooks.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/UserHooks.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-UserHooks.html docs]):: 
     144 
     145 `Distribution/Simple/UserHooks.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/UserHooks.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-UserHooks.html docs]):: 
     146 
     147 `Distribution/Simple/SetupWrapper.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple/SetupWrapper.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple-SetupWrapper.html docs]):: 
     148 
     149 `Distribution/Simple.hs` ([http://darcs.haskell.org/cabal/Distribution/Simple.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Simple.html docs]):: 
     150 
     151 `Distribution/Make.hs` ([http://darcs.haskell.org/cabal/Distribution/Make.hs source]) ([http://www.haskell.org/cabal/release/latest/doc/API/Cabal/Distribution-Make.html docs])::