X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fpackages.sgml;h=e6f0b7b2b440109eb8a1c80bdce5e48c116bbdab;hb=af76ab6142576b7cc4af11c4883c387e96b18f73;hp=1ef87cbb3970e5c85e1edb100a5c527b3c7c1b23;hpb=6ec7f45fd25a978c9f955f0c07790e1e42949d4b;p=ghc-hetmet.git
diff --git a/ghc/docs/users_guide/packages.sgml b/ghc/docs/users_guide/packages.sgml
index 1ef87cb..e6f0b7b 100644
--- a/ghc/docs/users_guide/packages.sgml
+++ b/ghc/docs/users_guide/packages.sgml
@@ -13,9 +13,9 @@
are also a good way to provide convenient access to a Haskell
layer over a C library.
- GHC comes with several packages (see ), and packages can be added/removed from an
- existing GHC installation, using the supplied
+ GHC comes with several packages (see the accompanying
+ library documentation), and packages can be added to or removed
+ from an existing GHC installation, using the supplied
ghc-pkgghc-pkg tool, described in .
@@ -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
@@ -50,6 +72,39 @@
automatically get -package lang too.
+
+ Maintaining a local set of packages
+
+ When GHC starts up, it automatically reads the default set
+ of packages from a configuration file, normally named
+ package.conf in your GHC installation
+ directory.
+
+ You can load in additional package configuration files
+ using the option:
+
+
+
+
+
+
+
+ Read in the package configuration file
+ file in addition to the system
+ default file. This allows the user to have a local set of
+ packages in addition to the system-wide ones.
+
+
+
+
+ To create your own package configuration file, just create
+ a new file and put the string
+ [] in it. Packages can be
+ added to the new configuration file using the
+ ghc-pkg tool, described in .
+
+
Building a package from Haskell sourcepackages
@@ -68,31 +123,47 @@
A package has a name
- (e.g. std)
+ (e.g. base)The Haskell code in a package may be built into one or
- more Unix 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).
+ 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 (the object suffix
- varies between platforms, as usual) and load that. An
- object file can be built from a .a
- archive as follows (using GNU ld on
- Unix):
-
-
-ld -r --whole-archive -o HSfoo.o libHSfoo.a
-
+ 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
@@ -127,8 +198,8 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a
bear in mind that we might add support for Unix shared libraries
at some point in the future.
- It is worth noting that on Windows, because each package
- is built as a DLL, and a reference to a DLL costs an extra
+ 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.
@@ -139,78 +210,185 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a
packagesmanagement
- GHC uses a package configuration file, called
- packages.conf, which can be found in your GHC
- install directory. This file isn't intended to be edited
- directly, instead packages can be added or removed using GHC's
- package management tool, ghc-pkg.
+ The ghc-pkg tool allows packages to be
+ added or removed from a package configuration file. By default,
+ the system-wide configuration file is used, but alternatively
+ packages can be added, updated or removed from a user-specified
+ configuration file using the
+ option. An empty package configuration file consists of the
+ string [].
+
+ The ghc-pkg program accepts the
+ following options:
-
+
+
+
+
+ Reads package specification from the input (see below),
+ and adds it to the database of installed packages. The
+ package specification must be a package that isn't already
+ installed.
+
+
+
+
+
+
+
+
+ Read new package specifications from file
+ file. If a value of
+ "-" is given, standard input is used.
+ If no is present on the command-line,
+ an input file of "-" is assumed.
+
+
+
+
+
+
+
+
+
+
+ Automatically generate the GHCi
+ .o version of each
+ .a Haskell library, using GNU ld (if
+ that is available). Without this option,
+ ghc-pkg will warn if GHCi versions of
+ any Haskell libraries in the package don't exist.
+
+ GHCi .o libraries don't
+ necessarily have to live in the same directory as the
+ corresponding .a library. However,
+ this option will cause the GHCi library to be created in
+ the same directory as the .a
+ library.
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+
-
+ 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
+ $ ghc-pkg ––list-packages
+ /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.
-
-
-
-
+
+
+
- Reads a package specification (see below) on stdin,
- and adds it to the database of installed packages. The
- package specification must be a package that isn't already
- installed.
+ 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.
-
+
-
+ Removes the specified package from the installed
configuration.
+
+
+
+
+
+ Reads package specification from the input, and
+ adds it to the database of installed packages. If a package
+ with the same name is already installed, its configuration
+ data is replaced with the new information. If the package
+ doesn't already exist, it's added.
+
+
+
+
+
+
+
+ Causes ghc-pkg to ignore missing
+ directories and libraries when adding a package, and just
+ go ahead and add it anyway. This might be useful if your
+ package installation system needs to add the package to
+ GHC before building and installing the files.
+
+
- In both cases, the old package configuration file is saved
- in packages.conf.old in your GHC install
- directory, so in an emergency you can always copy this file into
- package.conf to restore the old
- settings.
+ When modifying the configuration file
+ file, a copy of the original file is
+ saved in file.old,
+ so in an emergency you can always restore the old settings by
+ copying the old file back again.A package specification looks like this:
Package {
name = "mypkg",
- import_dirs = ["/usr/local/lib/imports/mypkg"],
+ auto = True,
+ import_dirs = ["${installdir}/imports/mypkg"],
source_dirs = [],
- library_dirs = ["/usr/local/lib"],
+ library_dirs = ["${installdir}"],
hs_libraries = ["HSmypkg" ],
extra_libraries = ["HSmypkg_cbits"],
include_dirs = [],
@@ -233,18 +411,40 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a
The package's name, for use with
the -package flag and as listed in the
- --list-packages list.
+ ––list-packages list.
+ 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).
@@ -277,7 +477,8 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a
A list of libraries containing Haskell code for this
package, with the .a or
- .dll suffix omitted. On Unix, the
+ .dll suffix omitted. When packages are
+ built as libraries, the
lib prefix is also omitted.For use with GHCi, each library should have an
@@ -294,7 +495,9 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a
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.
@@ -302,7 +505,7 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a
HSfoo.dllThe name of the dynamic library on Windows
- systems.
+ systems (optional).
@@ -338,6 +541,12 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a
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
@@ -409,11 +618,55 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a
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.
+
+
+
+
+ framework_dirs
+ framework_dirs
+ package specification
+
+ On Darwin/MacOS X, a list of directories containing frameworks for this
+ package. This corresponds to the option.
+ It is ignored on all other platforms.
+
+
+
+
+ extra_frameworks
+ extra_frameworks
+ package specification
+
+ On Darwin/MacOS X, a list of frameworks to link to. This corresponds to the
+ option. Take a look at Apple's developer documentation
+ to find out what frameworks actually are. This entry is ignored on all other platforms.
+
+
+ The ghc-pkg tool performs expansion of
+ environment variables occurring in input package specifications.
+ So, if the mypkg was added to the package
+ database as follows:
+
+
+ $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg
+
+
+
+ The occurrence of ${installdir} is replaced
+ with /usr/local/lib in the package data that
+ is added for mypkg.
+
+
+
+ This feature enables the distribution of package specification
+ files that can be easily configured when installing.
+ For examples of more package specifications, take a look
at the package.conf in your GHC