X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;ds=sidebyside;f=ghc%2Fdocs%2Fusers_guide%2Fpackages.sgml;h=bf56e9644c28b342e2497c787e5fd18a3cd21dbb;hb=c7566eead75708b2072fc4bc4e8eb81c5ce66d0a;hp=e57b3f9c2f9faa1c58c26f3976f002e4bc4a999d;hpb=8cc2cb9316c8d8a30763f834f50b2a1d027088e4;p=ghc-hetmet.git
diff --git a/ghc/docs/users_guide/packages.sgml b/ghc/docs/users_guide/packages.sgml
index e57b3f9..bf56e96 100644
--- a/ghc/docs/users_guide/packages.sgml
+++ b/ghc/docs/users_guide/packages.sgml
@@ -13,8 +13,8 @@
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 to or removed
+ 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 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:
-
-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
@@ -177,8 +191,8 @@
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 or removed from a user-specified
- configuration file using the
+ 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 [].
@@ -187,9 +201,9 @@
-
+
-
+ Reads package specification from the input (see below),
and adds it to the database of installed packages. The
@@ -199,9 +213,9 @@
-
+
-
+ Read new package specifications from file
file. If a value of
@@ -213,9 +227,9 @@
-
+
-
+ Automatically generate the GHCi
@@ -235,9 +249,9 @@
-
+
-
+ Use file instead of the
@@ -249,15 +263,15 @@
-
+
-
+ This option displays the list of currently installed
packages.
- $ ghc-pkg --list-packages
+ $ ghc-pkg ––list-packages
gmp, rts, std, lang, concurrent, data, net, posix, text, util
@@ -275,15 +289,39 @@
-
+
-
+ 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.
+
+ When modifying the configuration file
@@ -297,9 +335,9 @@
Package {
name = "mypkg",
- import_dirs = ["/usr/local/lib/imports/mypkg"],
+ import_dirs = ["${installdir}/imports/mypkg"],
source_dirs = [],
- library_dirs = ["/usr/local/lib"],
+ library_dirs = ["${installdir}"],
hs_libraries = ["HSmypkg" ],
extra_libraries = ["HSmypkg_cbits"],
include_dirs = [],
@@ -322,7 +360,7 @@
The package's name, for use with
the -package flag and as listed in the
- --list-packages list.
+ ––list-packages list.
@@ -334,6 +372,13 @@
A 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).
@@ -384,7 +429,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.
@@ -392,7 +439,7 @@
HSfoo.dllThe name of the dynamic library on Windows
- systems.
+ systems (optional).
@@ -428,6 +475,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
@@ -503,7 +556,50 @@
(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