From: simonpj@microsoft.com Date: Fri, 22 Dec 2006 14:15:51 +0000 (+0000) Subject: Improve documentation about packages X-Git-Tag: 2007-02-05~165 X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=6dcff14bc5a7b394cf77f98b369d6f93c030cb36 Improve documentation about packages --- diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml index f209d57..7c934a2 100644 --- a/docs/users_guide/packages.xml +++ b/docs/users_guide/packages.xml @@ -30,49 +30,15 @@ Packages packages using - To see which packages are installed, use the - ghc-pkg command: + GHC only knows about packages that are installed. - -$ ghc-pkg list -/usr/lib/ghc-6.4/package.conf: - base-1.0, haskell98-1.0, template-haskell-1.0, mtl-1.0, unix-1.0, - Cabal-1.0, haskell-src-1.0, parsec-1.0, network-1.0, - QuickCheck-1.0, HUnit-1.1, fgl-1.0, X11-1.1, HGL-3.1, OpenGL-2.0, - GLUT-2.0, stm-1.0, readline-1.0, (lang-1.0), (concurrent-1.0), - (posix-1.0), (util-1.0), (data-1.0), (text-1.0), (net-1.0), - (hssource-1.0), rts-1.0 - - - Packages are either exposed or hidden. Only - modules from exposed packages may be imported by your Haskell code; if + An installed package is either exposed or hidden + by default. Command-line flags, described below, allow you to expose a hidden package + or hide an exposed one. + Only modules from exposed packages may be imported by your Haskell code; if you try to import a module from a hidden package, GHC will emit an error message. - Each package has an exposed flag, which says whether it is exposed by - default or not. Packages hidden by default are listed in - parentheses (eg. (lang-1.0)) in the output from - ghc-pkg list. To expose a package which is hidden by - default, use the - flag (see below). - - To see which modules are exposed by a package: - - -$ ghc-pkg field network exposed-modules -exposed-modules: Network.BSD, - Network.CGI, - Network.Socket, - Network.URI, - Network - - - In general, packages containing hierarchical modules are usually - exposed by default. However, it is possible for two packages to contain - the same module: in this case, only one of the packages should be - exposed. It is an error to import a module that belongs to more than one - exposed package. - The GHC command line options that control packages are: @@ -82,7 +48,7 @@ exposed-modules: Network.BSD, - This option causes package P to be + This option causes the installed package P to be exposed. The package P can be specified in full with its version number (e.g. network-1.0) or the version number can be @@ -180,7 +146,81 @@ exposed-modules: Network.BSD, useful. + + + foo + + + + Tells GHC the the module being compiled forms part of + package foo. + If this flag is omitted (a very common case) then the + default package main is assumed. + Note: the argument to + should be the full package identifier for the package, + that is it should include the version number. For example: + -package mypkg-1.2. + + + + + To see which packages are installed, use the + ghc-pkg command: + + +$ ghc-pkg list +/usr/lib/ghc-6.4/package.conf: + base-1.0, haskell98-1.0, template-haskell-1.0, mtl-1.0, unix-1.0, + Cabal-1.0, haskell-src-1.0, parsec-1.0, network-1.0, + QuickCheck-1.0, HUnit-1.1, fgl-1.0, X11-1.1, HGL-3.1, OpenGL-2.0, + GLUT-2.0, stm-1.0, readline-1.0, (lang-1.0), (concurrent-1.0), + (posix-1.0), (util-1.0), (data-1.0), (text-1.0), (net-1.0), + (hssource-1.0), rts-1.0 + + + Packages hidden by default are listed in + parentheses (eg. (lang-1.0)) in the output above. + To expose a package which is hidden by + default, use the + flag (see above). + + When a package is exposed, it makes available for import the exposed modules + of the package. To see which modules are exposed by a package use the + ghc-pkg command (see ): + + +$ ghc-pkg field network exposed-modules +exposed-modules: Network.BSD, + Network.CGI, + Network.Socket, + Network.URI, + Network + + + In general, packages containing hierarchical modules are usually + exposed by default. However, it is possible for two packages to contain + the same module: in this case, only one of the packages should be + exposed. It is an error to import a module that belongs to more than one + exposed package. + + + + + The main package + + Every complete Haskell program must define main in + module Main + in package main. (Omitting the flag compiles + code for package main.) Failure to do so leads to a somewhat obscure + link-time error of the form: + +/usr/bin/ld: Undefined symbols: +_ZCMain_main_closure +___stginit_ZCMain + + + @@ -243,7 +283,7 @@ exposed-modules: Network.BSD, database will override those of the same name in the global database. - You can control the loading of package databses using the following + You can control the loading of package databases using the following GHC options: @@ -379,28 +419,8 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf: To compile a module which is to be part of a new package, - use the -package-name option: - - - - - -package-name - option - - This option is added to the command line when - compiling a module that is destined to be part of package - foo. If this flag is omitted then the - default package main is assumed. - - Note: the argument to - should be the full package identifier for the package, - that is it should include the version number. For example: - -package mypkg-1.2. - - - - - Failure to use the -package-name option + use the -package-name option (). + Failure to use the -package-name option when compiling a package will probably result in disaster, but you will only discover later when you attempt to import modules from the package. At this point GHC will complain that the