X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fpackages.sgml;h=e6f0b7b2b440109eb8a1c80bdce5e48c116bbdab;hb=af76ab6142576b7cc4af11c4883c387e96b18f73;hp=6faac0aaf6248c74e2a75a099578ab5ae06f5cba;hpb=7bcdfdba58be3bd3159a87ca8413c28e3c64d147;p=ghc-hetmet.git
diff --git a/ghc/docs/users_guide/packages.sgml b/ghc/docs/users_guide/packages.sgml
index 6faac0a..e6f0b7b 100644
--- a/ghc/docs/users_guide/packages.sgml
+++ b/ghc/docs/users_guide/packages.sgml
@@ -25,8 +25,16 @@
packagesusing
- To use a package, add the -package flag
- to the GHC command line:
+ Some packages are automatically available: you don't need
+ to specify any extra flags to use them (except in certain
+ circumstances; see below). All the packages which contain
+ hierarchical libraries fall into this category.
+
+ Some other packages are not
+ automatically available: those are normally the packages
+ containing old non-hierarchical libraries. To gain access to a
+ non-auto package, use the command-line
+ flag:
@@ -42,6 +50,20 @@
+ There's one case where you need to use the
+ option even for auto packages: when
+ linking a program in batch modeThis is because
+ GHC can't figure out from the object files which packages are
+ required; in mode and in
+ GHCi the compiler has more information available to figure out
+ the package dependencies. We might try to lift this restriction
+ in the future.. For example, to link a
+ program consisting of objects Foo.o and
+ Main.o, where we made use of the
+ network package:
+
+$ ghc -o myprog Foo.o Main.o -package network
+
Some packages depend on other packages, for example the
text package makes use of some of the modules
in the lang package. The package system
@@ -101,31 +123,45 @@
A package has a name
- (e.g. std)
+ (e.g. base)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 that 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.
+ 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
+ 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.
+
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
- called HSfoo.o and load that. 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:
+ 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:
ld -r ––whole-archive -o HSfoo.o libHSfoo.a
@@ -240,11 +276,18 @@
- Use file instead of the
- default package configuration file. This, in conjunction
- with GHC's option, allows
- a user to have a local set of packages in addition to the
- system-wide installed set.
+ Use file as an additional
+ package configuration file. This is used to modify
+ configuration files for use with GHC's
+ option.
+
+ There may be any number of configuration files named
+ on the command line; files mentioned later on the
+ command-line override those mentioned earlier. The
+ last configuration file mentioned on
+ the command-line is the only one that is actually modified
+ by ghc-pkg.
+
@@ -254,23 +297,44 @@
This option displays the list of currently installed
- packages.
+ packages, including those in extra configuration files
+ specified with the
+ option.
$ ghc-pkg ––list-packages
- gmp, rts, std, lang, concurrent, data, net, posix, text, util
+ /usr/local/lib/ghc-5.05/package.conf:
+ hdirect, readline, lang, concurrent, posix, util, data, text, net,
+ hssource, rts, haskell98, network, haskell-src, unix, base
Note that your GHC installation might have a
slightly different set of packages installed.
- The gmp and
- rts packages are always present, and
- represent the multi-precision integer and runtime system
- libraries respectively. The std
- package contains the Haskell prelude and standard
- libraries. The rest of the packages are optional
- libraries.
+ The rts package is always
+ present, and represents the runtime system library. The
+ base package contains the Haskell
+ prelude and basic hierarchical libraries, and the
+ haskell98 package contains the Haskell
+ 98 standard libraries. The rest of the packages are
+ optional libraries.
+
+
+
+
+
+
+
+
+ Displays the list of packages installed in the
+ topmost configuration file only: that will be the
+ configuration file specified using on
+ the command line, or the system configuration file
+ otherwise.
+
+ This option may be more convenient than
+ when the output needs to be parsed by
+ a script.
@@ -321,6 +385,7 @@
Package {
name = "mypkg",
+ auto = True,
import_dirs = ["${installdir}/imports/mypkg"],
source_dirs = [],
library_dirs = ["${installdir}"],
@@ -352,12 +417,34 @@
+ auto
+ auto
+ package specification
+
+
+ Set to True if the package should
+ be automatically available (see ). This is normally set to
+ True for packages which contain
+ hierarchical libraries, because in that case there is no
+ danger of polluting the module namespace.
+
+
+
+ import_dirsimport_dirspackage specificationA list of directories containing interface files
(.hi files) for this package.
+
+ If the package contains profiling libraries, then
+ the interface files for those library modules should have
+ the suffix .p_hi. So the package can
+ contain both normal and profiling versions of the same
+ library without conflict (see also
+ library_dirs below).
@@ -408,7 +495,9 @@
libHSfoo.a
- The name of the library on Unix
+ The name of the library on Unix and Windows
+ (mingw) systems. Note that we don't support
+ building dynamic libraries of Haskell code on Unix
systems.
@@ -416,7 +505,7 @@
HSfoo.dllThe name of the dynamic library on Windows
- systems.
+ systems (optional).
@@ -452,6 +541,12 @@
for libraries in
extra_libraries.
+ The libraries listed in
+ extra_libraries may be any libraries
+ supported by your system's linker, including dynamic
+ libraries (.so on Unix,
+ .DLL on Windows).
+
Also, extra_libraries are placed
on the linker command line after the
hs_libraries for the same package. If
@@ -523,8 +618,9 @@
extra_ld_optspackage specification
- Extra arguments to be added to the gcc command line
- (for linking) when this package is being used.
+ Extra arguments to be added to the
+ gcc command line (for linking) when
+ this package is being used.