X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fpackages.xml;h=b37e266d9fe82bfc8e7f76f9ea7ea65d3918e4e4;hb=5e04ae341a945ef430e9d941b34722b8de1f6aae;hp=3bd65c66ce8c2c19ae837a20a5acf3fb59e7e309;hpb=0065d5ab628975892cea1ec7303f968c3338cbe1;p=ghc-hetmet.git
diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml
index 3bd65c6..b37e266 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
packagesusing
- 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,24 +77,36 @@ exposed-modules: Network.BSD,
- This option causes 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
- omitted if there is only one version of the package
- installed.
-
- If there are multiple versions of P
- installed, then all other versions will become hidden.
+ 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 omitted if there is only one version of the
+ package installed. If there are multiple versions
+ of P installed, then all other
+ versions will become hidden.The
- option also causes package P to be
- linked into the resulting executable. In
- mode and GHCi, the compiler
- normally determines which packages are required by the current
- Haskell modules, and links only those. In batch mode however, the
- dependency information isn't available, and explicit
- options must be given when linking.
+ option also causes package P to
+ be linked into the resulting executable or shared
+ object. Whether a packages' library is linked statically
+ or dynamically is controlled by the flag
+ pair /.
+
+ In mode
+ and mode (see
+ ), the compiler normally
+ determines which packages are required by the current
+ Haskell modules, and links only those. In batch mode
+ however, the dependency information isn't available, and
+ explicit
+ options must be given when linking. The one other time you might need to use
+ to force linking a package is
+ when the package does not contain any Haskell modules (it
+ might contain a C library only, for example). In that
+ case, GHC will never discover a dependency on it, so it
+ has to be mentioned explicitly.For example, to link a program consisting of objects
Foo.o and Main.o, where
@@ -111,18 +118,7 @@ exposed-modules: Network.BSD,
The same flag is necessary even if we compiled the modules from
source, because GHC still reckons it's in batch mode:
-$ ghc -o myprog Foo.hs Main.hs -package network
-
- In --make and --interactive
- modes (), however, GHC figures out the
- packages required for linking without further assistance.
-
- The one other time you might need to use
- to force linking a package is when the
- package does not contain any Haskell modules (it might contain a C
- library only, for example). In that case, GHC
- will never discover a dependency on it, so it has to be mentioned
- explicitly.
+$ ghc -o myprog Foo.hs Main.hs -package network
@@ -137,9 +133,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 +176,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 +272,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:
@@ -313,69 +349,98 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:
lot of configuration, then you might have to fall back to the low-level
mechanisms, so a few hints for those brave souls follow.
+ You need to build an "installed package info" file for
+ passing to ghc-pkg when installing your
+ package. The contents of this file are described in
+ .
+
+ The Haskell code in a package may be built into one or more
+ archive libraries (e.g. libHSfoo.a), or a
+ single shared object
+ (e.g. libHSfoo.dll/.so/.dylib). The
+ restriction to a single shared object is because the package
+ system is used to tell the compiler when it should make an
+ inter-shared-object call rather than an intra-shared-object-call
+ call (inter-shared-object calls require an extra
+ indirection).
-
- You need to build an "installed package info" file for
- passing to ghc-pkg when installing your
- package. The contents of this file are described in .
-
-
-
- The Haskell code in a package may be built into one or
- more archive libraries
- (e.g. libHSfoo.a), or a single DLL on
- Windows (e.g. HSfoo.dll). The
- restriction to a single DLL on Windows is because the
- package system is used to tell the compiler when it should
- make an inter-DLL call rather than an intra-DLL call
- (inter-DLL calls require an extra
- indirection). Building packages as DLLs doesn't
- work at the moment; see
- for the gory details.
-
-
- Building a static library is done by using the
+ Building a static library is done by using the
ar tool, like so:
-ar cqs libHSfoo.a A.o B.o C.o ...
-
- where A.o,
- B.o and so on are the compiled Haskell
- modules, and libHSfoo.a is the library
- you wish to create. The syntax may differ slightly on your
- system, so check the documentation if you run into
- difficulties.
+ar cqs libHSfoo-1.0.a A.o B.o C.o ...
- Versions of the Haskell libraries for use with GHCi
- may also be included: GHCi cannot load .a
- files directly, instead it will look for an object file
+ where A.o,
+ B.o and so on are the compiled Haskell
+ modules, and libHSfoo.a is the library you
+ wish to create. The syntax may differ slightly on your system,
+ so check the documentation if you run into difficulties.
+
+
+ Versions of the Haskell libraries for use with GHCi may also
+ abe included: GHCi cannot load .a files
+ directly, instead it will look for an object file
called HSfoo.o and load that. On some
- systems, the ghc-pkg tool can
- automatically build the GHCi version of each library, see
- . To build these
- libraries by hand from the .a archive, it
- is possible to use GNU ld as
- follows:
+ systems, the ghc-pkg tool can automatically
+ build the GHCi version of each library, see
+ . To build these libraries
+ by hand from the .a archive, it is possible
+ to use GNU ld as follows:ld -r ––whole-archive -o HSfoo.o libHSfoo.a(replace
- ––--whole-archive with
- –all_load on MacOS X)
-
- GHC does not maintain detailed cross-package
- dependency information. It does remember which modules in
- other packages the current module depends on, but not which
- things within those imported things.
+ ––whole-archive with
+ –all_load on MacOS X)
+
+
+ When building the package as shared object, GHC wraps
+ out the underlying linker so that the user gets a common
+ interface to all shared object variants that are supported
+ by GHC (DLLs, ELF DSOs, and Mac OS dylibs). The shared
+ object must be named in specific way for two reasons: (1)
+ the name must contain the GHC compiler version, so that two
+ library variants don't collide that are compiled by
+ different versions of GHC and that therefore are most likely
+ incompatible with respect to calling conventions, (2) it
+ must be different from the static name otherwise we would
+ not be able to control the linker as precisely as necessary
+ to make
+ the / flags
+ work, see .
+
+ghc -shared libHSfoo-1.0-ghcGHCVersion.so A.o B.o C.o
+ Using GHC's version number in the shared object name
+ allows different library versions compiled by different GHC
+ versions to be installed in standard system locations,
+ e.g. under *nix /usr/lib. To obtain the version number of
+ GHC invoke ghc --numeric-version and use
+ its output in place
+ of GHCVersion. See also
+ on how object files must
+ be prepared for shared object linking.
+
+ GHC does not maintain detailed cross-package dependency
+ information. It does remember which modules in other packages
+ the current module depends on, but not which things within
+ those imported things.
- It is worth noting that on Windows, when each package
- is built as a DLL, since a reference to a DLL costs an extra
+ 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 with shared objects, when each package
+ is built as a single shared object file, since a reference to a shared object 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.
@@ -404,6 +469,13 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:
options are given, the rightmost one is used as the database to act
upon.
+ Commands that query the package database (list, latest,
+ describe, field) operate on the list of databases specified by
+ the flags , , and
+ . If none of these flags are
+ given, the default is
+ .
+
If the environment variable GHC_PACKAGE_PATH is
set, and its value does not end in a separator (: on
Unix, ; on Windows), then the last database is
@@ -464,6 +536,15 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:
+ ghc-pkg check
+
+ Check consistency of dependencies in the package
+ database, and report packages that have missing
+ dependencies.
+
+
+
+ ghc-pkg hide PSets the exposed flag for package
@@ -566,7 +647,7 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:
databases. Additionally, file will
also be the database modified by a register,
unregister, expose or
- hide command, unless it is overriden by a later
+ hide command, unless it is overridden by a later
, or
option.