X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fpackages.xml;h=621747f33d0cd42fffe7ce236a8dbb43cfc5ce9b;hb=b86f04619dd4c03f6c41448162ec0e338833b514;hp=3bd65c66ce8c2c19ae837a20a5acf3fb59e7e309;hpb=0065d5ab628975892cea1ec7303f968c3338cbe1;p=ghc-hetmet.git diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml index 3bd65c6..621747f 100644 --- a/docs/users_guide/packages.xml +++ b/docs/users_guide/packages.xml @@ -5,9 +5,12 @@ Packages packages - A package is a library of Haskell modules known to the compiler. GHC - comes with several packages: see the accompanying - library documentation. + A package is a library of Haskell modules known to the + compiler. GHC comes with several packages: see the accompanying + library + documentation. More packages to install can be obtained + from HackageDB. Using a package couldn't be simpler: if you're using or GHCi, then most of the installed packages will be @@ -30,8 +33,9 @@ Packages packages using - To see which packages are installed, use the - ghc-pkg command: + GHC only knows about packages that are + installed. To see which packages are installed, use + the ghc-pkg command: $ ghc-pkg list @@ -44,19 +48,16 @@ $ ghc-pkg list (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. Packages hidden by default are listed in + parentheses (eg. (lang-1.0)) in the output above. 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: + To see which modules are provided by a package use the + ghc-pkg command (see ): $ ghc-pkg field network exposed-modules @@ -67,12 +68,6 @@ exposed-modules: Network.BSD, 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 +77,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 @@ -137,9 +132,12 @@ exposed-modules: Network.BSD, base) need to be explicitly exposed using options. - This is a good way to insulate your program from differences - in the globally exposed packages, and being explicit about package - dependencies is a Good Thing. + This is a good way to insulate your program from + differences in the globally exposed packages, and being + explicit about package dependencies is a Good Thing. + Cabal always passes the + flag to GHC, for + exactly this reason. @@ -177,31 +175,68 @@ 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. + + + + 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 + + + + + - The module overlap restriction - - The module names in a Haskell program must be distinct. - This doesn't sound like a severe restriction, but in a Haskell program - using multiple packages with interdependencies, difficulties can start to - arise. You should be aware of what the module overlap - restriction means, and how to avoid it. - - GHC knows which packages are in use by your - program: a package is in use if you imported something from it, or if it - is a dependency of some other package in use. There must be no conflicts - between the packages in use; a conflict is when two packages contain - a module with the same name. If - GHC detects a conflict, it will issue a message stating which packages - are in conflict, and which modules are overlapping. - - For example, a conflict might arise if you use two packages, say P - and Q, which respectively depend on two different versions of another - package, say R-1.0 and R-2.0. The - two versions of R are likely to contain at least some - of the same modules, so this situation would be a conflict. + Consequences of packages + + It is possible that by using packages you might end up with + a program that contains two modules with the same name: perhaps + you used a package P that has a hidden module + M, and there is also a module M in your program. Or perhaps the + dependencies of packages that you used contain some overlapping + modules. Perhaps the program even contains multiple versions of a + certain package, due to dependencies from other packages. + + None of these scenarios gives rise to an error on its + ownit used to in GHC 6.4, but not since + 6.6, but they may have some interesting + consequences. For instance, if you have a type + M.T from version 1 of package + P, then this is not the + same as the type M.T from version 2 of package + P, and GHC will report an error if you try to + use one where the other is expected. + + Formally speaking, in Haskell 98, an entity (function, type + or class) in a program is uniquely identified by the pair of the + module name in which it is defined and its name. In GHC, an + entity is uniquely defined by a triple: package, module, and + name. @@ -236,7 +271,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: @@ -371,11 +406,21 @@ $ 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 (). + 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 + package name it was expecting the module to come from is not the + same as the package name stored in the .hi + file. + It is worth noting that on Windows, when each package is built as a DLL, since a reference to a DLL costs an extra indirection, intra-package references are cheaper than inter-package references. Of course, this applies to the - Main package as well. + main package as well.