X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fpackages.xml;h=7c934a2f45f77eaa93976f7a59efa83ac8a78fbd;hb=3de26aa3d728b06ee7bf658fec6a09855822d492;hp=3bd65c66ce8c2c19ae837a20a5acf3fb59e7e309;hpb=0065d5ab628975892cea1ec7303f968c3338cbe1;p=ghc-hetmet.git
diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml
index 3bd65c6..7c934a2 100644
--- a/docs/users_guide/packages.xml
+++ b/docs/users_guide/packages.xml
@@ -30,49 +30,15 @@ Packages
packagesusing
- 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
@@ -137,9 +103,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 +146,109 @@ 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
+
+
+
- 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 +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:
@@ -371,11 +418,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.