Commit 0c993c84 authored by Duncan Coutts's avatar Duncan Coutts

Update module headers

Use cabal-devel@haskell.org as the maintainer in most cases except for
a few which were pre-existing modules copied from elsewhere or modules
like L.H.Extension which really belong to libraries@haskell.org
Remove the useless stability module. We have more detailed information
on stability elsewhere (in the version number and user guide).
Add more top level module documentation, taken from the source guide.
parent f4e1e67a
......@@ -5,7 +5,6 @@
-- License : BSD-style (see the file libraries/base/LICENSE)
--
-- Maintainer : libraries@haskell.org
-- Stability : provisional
-- Portability : portable
--
-- This is a library of parser combinators, originally written by Koen Claessen.
......
......@@ -3,11 +3,23 @@
-- Module : Distribution.Compiler
-- Copyright : Isaac Jones 2003-2004
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Haskell compiler flavors
-- 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 deficiency. If you're interested, see
-- ticket #50.
{- All rights reserved.
......
......@@ -5,7 +5,6 @@
-- License : BSD-style (see the file libraries/base/LICENSE)
--
-- Maintainer : libraries@haskell.org
-- Stability : experimental
-- Portability : portable
--
-- This library provides facilities for parsing the command-line options
......
......@@ -4,14 +4,23 @@
-- Copyright : (c) The University of Glasgow 2004
--
-- Maintainer : libraries@haskell.org
-- Stability : alpha
-- Portability : portable
--
-- This is the information about an /installed/ package that
-- is communicated to the @hc-pkg@ program in order to register
-- a package. @ghc-pkg@ now consumes this package format (as of verison
-- 6.4). This is specific to GHC at the moment.
--
-- The @.cabal@ file format is for describing a package that is not yet
-- installed. It has a lot of flexibility like conditionals and dependency
-- 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 that stage
-- we have resolved all conditionals and resolved dependency version
-- constraints to exact versions of dependent packages. So this module defines
-- the 'InstalledPackageInfo' data structure that contains all the info we keep
-- about an installed package. There is a parser and pretty printer. The
-- textual format is rather simpler than the @.cabal@ format, there are no
-- sections for example.
{- All rights reserved.
......
......@@ -3,17 +3,18 @@
-- Module : Distribution.License
-- Copyright : Isaac Jones 2003-2005
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- The License datatype. For more information about these and other
-- open-source licenses, you may visit <http://www.opensource.org/>.
--
-- I am not a lawyer, but as a general guideline, most Haskell
-- software seems to be released under a BSD3 license, which is very
-- open and free. If you don't want to restrict the use of your
-- software or its source code, use BSD3 or PublicDomain.
-- 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.
{- All rights reserved.
......
......@@ -3,10 +3,18 @@
-- Module : Distribution.Make
-- Copyright : Martin Sj&#xF6;gren 2004
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- This is an alternative build system that delegates everything to the @make@
-- program. All the commands just end up calling @make@ with appropriate
-- arguments. The intention was to allow preexisting packages that used
-- makefiles to be wrapped into Cabal packages. In practice essentially all
-- such packages were converted over to the \"Simple\" build system instead.
-- Consequently this module is not used much and it certainly only sees cursory
-- maintenance and no testing. Perhaps at some point we should stop pretending
-- that it works.
--
-- Uses the parsed command-line from Distribution.Setup in order to build
-- Haskell tools using a backend build system based on make. Obviously we
-- assume that there is a configure script, and that after the ConfigCmd has
......
......@@ -3,11 +3,10 @@
-- Module : Distribution.ModuleName
-- Copyright : Duncan Coutts 2008
--
-- Maintainer : Duncan Coutts <duncan@haskell.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Haskell module names
-- Data type for Haskell module names.
{- All rights reserved.
......
......@@ -3,11 +3,13 @@
-- Module : Distribution.Package
-- Copyright : Isaac Jones 2003-2004
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Packages are fundamentally just a name and a version.
-- Defines a package identifier along with a parser and pretty printer for it.
-- 'PackageIdentifier's consist of a name and an exact version. It also defines
-- a 'Dependency' data type. A dependency is a package name and a version
-- range, like @\"foo >= 1.2 && < 2\"@.
{- All rights reserved.
......
......@@ -3,11 +3,21 @@
-- Module : Distribution.PackageDescription
-- Copyright : Isaac Jones 2003-2005
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Package description and parsing.
-- This defines the data structure for the @.cabal@ file format. There are
-- several parts to this structure. It has top level info and then 'Library'
-- and 'Executable' sections each of which have associated 'BuildInfo' data
-- that's used to build the library or exe. To further complicate things there
-- is both a 'PackageDescription' and a 'GenericPackageDescription'. This
-- distinction relates to cabal configurations. When we initially read a
-- @.cabal@ file we get a 'GenericPackageDescription' which has all the
-- conditional sections. Before actually building a package we have to decide
-- on each conditional. Once we've done that we get a 'PackageDescription'.
-- It was done this way initially to avoid breaking too much stuff when the
-- feature was introduced. It could probably do with being rationalised at some
-- point to make it simpler.
{- All rights reserved.
......
......@@ -3,11 +3,21 @@
-- Module : Distribution.PackageDescription.Check
-- Copyright : Lennart Kolmodin 2008
--
-- Maintainer : Lennart Kolmodin <kolmodin@gentoo.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- This module provides functionality to check for common mistakes.
-- This has code for checking for various problems in packages. There is one
-- set of checks that just looks at a 'PackageDescription' in isolation and
-- another set of checks that also looks at files in the package. Some of the
-- checks are basic sanity checks, others are portability standards that we'd
-- like to encourage. There is a 'PackageCheck' type that distinguishes the
-- different kinds of check so we can see which ones are appropriate to report
-- in different situations. This code gets uses when configuring a package when
-- we consider only basic problems. The higher standard is uses when when
-- preparing a source tarball and by hackage when uploading new packages. The
-- reason for this is that we want to hold packages that are expected to be
-- distributed to a higher standard than packages that are only ever expected
-- to be used on the author's own environment.
{- All rights reserved.
......
......@@ -9,11 +9,14 @@
-- Module : Distribution.Configuration
-- Copyright : Thomas Schilling, 2007
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Configurations
-- This is about the cabal configurations feature. It exports
-- 'finalizePackageDescription' and 'flattenPackageDescription' which are
-- functions for converting 'GenericPackageDescription's down to
-- 'PackageDescription's. It has code for working with the tree of conditions
-- and resolving or flattening conditions.
{- All rights reserved.
......
......@@ -3,11 +3,13 @@
-- Module : Distribution.PackageDescription.Parse
-- Copyright : Isaac Jones 2003-2005
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Package description and parsing.
-- This defined parsers and partial pretty printers for the @.cabal@ format.
-- Some of the complexity in this module is due to the fact that we have to be
-- backwards compatible with old @.cabal@ files, so there's code to translate
-- into the newer structure.
{- All rights reserved.
......
......@@ -3,12 +3,17 @@
-- Module : Distribution.ParseUtils
-- Copyright : (c) The University of Glasgow 2004
--
-- Maintainer : libraries@haskell.org
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Utilities for parsing PackageDescription and InstalledPackageInfo.
-- Utilities for parsing 'PackageDescription' and 'InstalledPackageInfo'.
--
-- 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.
{- All rights reserved.
......
......@@ -3,8 +3,7 @@
-- Module : Distribution.ReadE
-- Copyright : Jose Iborra 2008
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Simple parsing with failure
......
......@@ -3,18 +3,26 @@
-- Module : Distribution.Simple
-- Copyright : Isaac Jones 2003-2005
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Explanation: Simple build system; basically the interface for
-- Distribution.Simple.\* modules. When given the parsed command-line
-- args and package information, is able to perform basic commands
-- like configure, build, install, register, etc.
-- This is the command line front end to the Simple build system. When given
-- the parsed command-line args and package information, is able to perform
-- basic commands like configure, build, install, register, etc.
--
-- This module exports the main functions that Setup.hs scripts use. It
-- re-exports the 'UserHooks' type, the standard entry points like
-- 'defaultMain' and 'defaultMainWithHooks' and the predefined sets of
-- 'UserHooks' that custom @Setup.hs@ scripts can extend to add their own
-- behaviour.
--
-- This module isn't called \"Simple\" because it's simple. Far from
-- it. It's called \"Simple\" because it does complicated things to
-- simple software.
--
-- The original idea was that there could be different build systems that all
-- presented the same compatible command line interfaces. There is still a
-- "Distribution.Make" system but in practice no packages use it.
{- All rights reserved.
......
......@@ -3,12 +3,23 @@
-- Module : Distribution.Simple.Build
-- Copyright : Isaac Jones 2003-2005
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Invokes the "Distribution.Compiler"s to build the library and
-- executables in this package.
-- 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 @makefiles@ 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.
{- Copyright (c) 2003-2005, Isaac Jones
All rights reserved.
......
......@@ -4,8 +4,7 @@
-- Copyright : Isaac Jones 2003-2004,
-- Duncan Coutts 2008
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- A bunch of dirs, paths and file names used for intermediate build steps.
......
......@@ -3,12 +3,16 @@
-- Module : Distribution.Simple.Command
-- Copyright : Duncan Coutts 2007
--
-- Maintainer : Duncan Coutts <duncan@haskell.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Explanation: Data types and parser for the standard command-line
-- setup.
-- 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
-- 'CommandUI' abstraction represents one of these sub-commands, with a name,
-- description, a set of flags. Commands 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 @cabal-install@.
{- All rights reserved.
......
......@@ -3,11 +3,19 @@
-- Module : Distribution.Simple.Compiler
-- Copyright : Isaac Jones 2003-2004
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Haskell implementations.
-- 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 fully support this latter feature.
{- All rights reserved.
......
......@@ -3,12 +3,22 @@
-- Module : Distribution.Simple.Configure
-- Copyright : Isaac Jones 2003-2005
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Explanation: Perform the \"@.\/setup configure@\" action.
-- Outputs the @dist\/setup-config@ file.
-- 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 the @dist\/setup-config@ file. It also displays various details to
-- the user, the amount of information displayed depending on the verbosity
-- level.
{- All rights reserved.
......
......@@ -3,13 +3,34 @@
-- Module : Distribution.Simple.GHC
-- Copyright : Isaac Jones 2003-2007
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Build and Install implementations for GHC. See
-- 'Distribution.Simple.GHC.PackageConfig.GHCPackageConfig' for
-- registration-related stuff.
-- This is a fairly large module. It contains most of the GHC-specific code for
-- configuring, building and installing packages. It also exports a function
-- for finding out what packages are already installed. Configuring involves
-- finding the @ghc@ and @ghc-pkg@ programs, finding what language extensions
-- this version of ghc supports and returning a 'Compiler' value.
--
-- 'getInstalledPackages' involves calling the @ghc-pkg@ program to find out
-- what packages are installed.
--
-- Building is somewhat complex as there is quite a bit of information to take
-- into account. We have to build libs and programs, possibly for profiling and
-- shared libs. We have to support building libraries that will be usable by
-- GHCi and also ghc's @-split-objs@ feature. We have to compile any C files
-- using ghc. Linking, especially for @split-objs@ is remarkably complex,
-- partly because there tend to be 1,000's of @.o@ files and this can often be
-- more than we can pass to the @ld@ or @ar@ programs in one go.
--
-- There is also some code for generating @Makefiles@ but the less said about
-- that the better.
--
-- Installing for libs and exes involves finding the right files and copying
-- them to the right places. One of the more tricky things about this module is
-- remembering the layout of files in the build directory (which is not
-- explicitly documented) and thus what search dirs are used for various kinds
-- of files.
{- Copyright (c) 2003-2005, Isaac Jones
All rights reserved.
......
......@@ -3,8 +3,7 @@
-- Module : Distribution.Simple.GHC.IPI641
-- Copyright : (c) The University of Glasgow 2004
--
-- Maintainer : libraries@haskell.org
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
......
......@@ -3,8 +3,7 @@
-- Module : Distribution.Simple.GHC.IPI642
-- Copyright : (c) The University of Glasgow 2004
--
-- Maintainer : libraries@haskell.org
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
......
......@@ -3,13 +3,18 @@
-- Module : Distribution.Simple.Haddock
-- Copyright : Isaac Jones 2003-2005
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Invokes haddock to generate api documentation for libraries and optinally
-- executables in this package. Also has support for generating
-- syntax-highlighted source with HsColour and linking the haddock docs to it.
-- 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 @-DHADDOCK@ for any source code that uses @cpp@. It
-- uses information about installed packages (from @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.
{- All rights reserved.
......
......@@ -3,11 +3,11 @@
-- Module : Distribution.Simple.Hugs
-- Copyright : Isaac Jones 2003-2006
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Build and install functionality for Hugs.
-- This module contains most of the NHC-specific code for configuring, building
-- and installing packages.
{- Copyright (c) 2003-2005, Isaac Jones
All rights reserved.
......
......@@ -3,13 +3,13 @@
-- Module : Distribution.Simple.Install
-- Copyright : Isaac Jones 2003-2004
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Explanation: Perform the \"@.\/setup install@\" and \"@.\/setup
-- copy@\" actions. Move files into place based on the prefix
-- argument.
-- This is the entry point into installing a built package. Performs the
-- \"@.\/setup install@\" and \"@.\/setup copy@\" actions. It moves files into
-- place based on the prefix argument. It does the generic bits and then calls
-- compiler-specific functions to do the rest.
{- All rights reserved.
......
......@@ -9,15 +9,17 @@
-- Module : Distribution.Simple.InstallDirs
-- Copyright : Isaac Jones 2003-2004
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Definition of the 'LocalBuildInfo' data type. This is basically
-- the information that is gathered by the end of the configuration
-- step which could include package information from ghc-pkg, flags
-- the user passed to configure, and the location of tools in the
-- PATH.
-- 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.
{- All rights reserved.
......
......@@ -3,11 +3,11 @@
-- Module : Distribution.Simple.JHC
-- Copyright : Isaac Jones 2003-2006
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Build and install functionality for the JHC compiler.
-- This module contains most of the JHC-specific code for configuring, building
-- and installing packages.
{- Copyright (c) 2003-2005, Isaac Jones
All rights reserved.
......
......@@ -3,15 +3,16 @@
-- Module : Distribution.Simple.LocalBuildInfo
-- Copyright : Isaac Jones 2003-2004
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Definition of the 'LocalBuildInfo' data type. This is basically
-- the information that is gathered by the end of the configuration
-- step which could include package information from ghc-pkg, flags
-- the user passed to configure, and the location of tools in the
-- PATH.
-- 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.
{- All rights reserved.
......
......@@ -3,10 +3,11 @@
-- Module : Distribution.Simple.NHC
-- Copyright : Isaac Jones 2003-2006
--
-- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
-- Stability : alpha
-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- This module contains most of the NHC-specific code for configuring, building
-- and installing packages.
{- Copyright (c) 2003-2005, Isaac Jones
All rights reserved.
......