From 530ced58cd18b165d03b6f62ff513c83c4fa4718 Mon Sep 17 00:00:00 2001 From: Simon Marlow Date: Tue, 15 Sep 2009 16:10:24 +0000 Subject: [PATCH] Update and improve packages documentation --- docs/users_guide/packages.xml | 588 ++++++++++++++++++++++++++++------------- 1 file changed, 408 insertions(+), 180 deletions(-) diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml index 8d668f9..dbc0ea9 100644 --- a/docs/users_guide/packages.xml +++ b/docs/users_guide/packages.xml @@ -13,7 +13,7 @@ Packages url="http://hackage.haskell.org/packages/hackage.html">HackageDB. Using a package couldn't be simpler: if you're using - or GHCi, then most of the installed packages will be + or GHCi, then most of the installed packages will be automatically available to your program without any further options. The exceptions to this rule are covered below in . @@ -35,26 +35,71 @@ Packages GHC only knows about packages that are installed. To see which packages are installed, use - the ghc-pkg command: + the ghc-pkg list 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 - - - 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. +/usr/lib/ghc-6.12.1/package.conf.d: + Cabal-1.7.4 + array-0.2.0.1 + base-3.0.3.0 + base-4.2.0.0 + bin-package-db-0.0.0.0 + binary-0.5.0.1 + bytestring-0.9.1.4 + containers-0.2.0.1 + directory-1.0.0.2 + (dph-base-0.4.0) + (dph-par-0.4.0) + (dph-prim-interface-0.4.0) + (dph-prim-par-0.4.0) + (dph-prim-seq-0.4.0) + (dph-seq-0.4.0) + extensible-exceptions-0.1.1.0 + ffi-1.0 + filepath-1.1.0.1 + (ghc-6.12.1) + ghc-prim-0.1.0.0 + haskeline-0.6.2 + haskell98-1.0.1.0 + hpc-0.5.0.2 + integer-gmp-0.1.0.0 + mtl-1.1.0.2 + old-locale-1.0.0.1 + old-time-1.0.0.1 + pretty-1.0.1.0 + process-1.0.1.1 + random-1.0.0.1 + rts-1.0 + syb-0.1.0.0 + template-haskell-2.4.0.0 + terminfo-0.3.1 + time-1.1.4 + unix-2.3.1.0 + utf8-string-0.3.4 + + + An installed package is either exposed + or hidden by default. Packages hidden by + default are listed in parentheses + (eg. (lang-1.0)), or possibly in blue if your + terminal supports colour, in the output of ghc-pkg + list. 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. + + + + Note: if you're using Cabal, then the exposed or hidden status + of a package is irrelevant: the available packages are instead + determined by the dependencies listed in + your .cabal specification. The + exposed/hidden status of packages is only relevant when + using ghc or ghci + directly. + To see which modules are provided by a package use the ghc-pkg command (see ): @@ -213,7 +258,7 @@ ___stginit_ZCMain - Consequences of packages + Consequences of packages for the Haskell language It is possible that by using packages you might end up with a program that contains two modules with the same name: perhaps @@ -243,21 +288,34 @@ ___stginit_ZCMain Package Databases - A package database is a file, normally called - package.conf which contains descriptions of installed - packages. GHC usually knows about two package databases: + + A package database is where the details about installed packages + are stored. It is a directory, usually + called package.conf.d, that contains a file + for each package, together with a binary cache of the package + data in the file package.cache. Normally + you won't need to look at or modify the contents of a package + database directly; all management of package databases can be + done through the ghc-pkg tool (see + ). + + + + GHC knows about two package databases in particular: + The global package database, which comes with your GHC - installation. + installation, + e.g. /usr/lib/ghc-6.12.1/package.conf.d. A package database private to each user. On Unix systems this will be - $HOME/.ghc/arch-os-version/package.conf, and on + $HOME/.ghc/arch-os-version/package.conf.d, and on Windows it will be something like - C:\Documents And Settings\user\ghc. + C:\Documents And Settings\user\ghc\package.conf.d. The ghc-pkg tool knows where this file should be located, and will create it if it doesn't exist (see ). @@ -268,9 +326,9 @@ ___stginit_ZCMain see GHC's package table by running GHC with the flag. - Package databases may overlap: for example, packages in the user - database will override those of the same name in the global - database. + Package databases may overlap: for example, packages in the + user database will override (shadow) those + of the same name and version in the global database. You can control the loading of package databases using the following GHC options: @@ -301,13 +359,6 @@ ___stginit_ZCMain - To create a new package database, just create - a new file and put the string - [] in it. Packages can be - added to the file using the - ghc-pkg tool, described in . - The <literal>GHC_PACKAGE_PATH</literal> environment variable Environment variableGHC_PACKAGE_PATH @@ -338,124 +389,130 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf: - - Building a package from Haskell source - packages - building + + Dependencies and broken packages - We don't recommend building packages the hard way. Instead, use the - Cabal infrastructure - if possible. If your package is particularly complicated or requires a - 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 - . + Each installed package has a unique identifier, which + distinguishes it from all other installed packages on the + system. To see the identifiers associated with each installed + package, use ghc-pkg list -v: - 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). - - Building a static library is done by using the - ar tool, like so: + +$ ghc-pkg list -v +using cache: /usr/lib/ghc-6.12.1/package.conf.d/package.cache +/usr/lib/ghc-6.12.1/package.conf.d + Cabal-1.7.4 (Cabal-1.7.4-48f5247e06853af93593883240e11238) + array-0.2.0.1 (array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d) + base-3.0.3.0 (base-3.0.3.0-6cbb157b9ae852096266e113b8fac4a2) + base-4.2.0.0 (base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c) + ... + -ar cqs libHSfoo-1.0.a A.o B.o C.o ... + + The string in parentheses after the package name is the unique + identifier: it normally begins with the package name and + version, and ends in a hash string derived from the compiled + package. Dependencies between packages are expressed in terms + of these unique identifiers, rather than just packages and + versions. For example, take a look at the dependencies of + the haskell98 package: + - 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: + +$ ghc-pkg field haskell98 depends +depends: array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d + base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c + directory-1.0.0.2-f51711bc872c35ce4a453aa19c799008 + old-locale-1.0.0.1-d17c9777c8ee53a0d459734e27f2b8e9 + old-time-1.0.0.1-1c0d8ea38056e5087ef1e75cb0d139d1 + process-1.0.1.1-d8fc6d3baf44678a29b9d59ca0ad5780 + random-1.0.0.1-423d08c90f004795fd10e60384ce6561 + -ld -r ––whole-archive -o HSfoo.o libHSfoo.a + + The purpose of the unique package identifier is to detect + problems caused by re-installing a package without also + recompiling the packages that depend on it. Recompiling + dependencies is necessary, because the newly compiled package + may have a differnt ABI (Application Binary Interface) than the + previous version, even if both packages were built from the same + source code using the same compiler. With unique package + identifiers, a recompiled package will have a different unique + identifer from the previous version, so packages that depended + on the previous version are now orphaned - one of their + dependencies is not satisfied. Packages that are broken in this + way are shown in the ghc-pkg list output + either in red (if possible) or otherwise surrounded by + braces. In the following example, we have recompiled and + reinstalled the filepath package, and this + has caused various dependencies + including Cabal to break: - (replace - ––whole-archive with - –all_load on MacOS X) - - - When building the package as shared library, GHC can be used to - perform the link step. This hides some of the details - out the underlying linker and provides 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-pkg list +WARNING: there are broken packages. Run 'ghc-pkg check' for more details. +/usr/lib/ghc-6.12.1/package.conf.d: + {Cabal-1.7.4} + array-0.2.0.1 + base-3.0.3.0 + ... etc ... + -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. - - + + Additionally, ghc-pkg list reminds you that + there are broken packages and suggests ghc-pkg + check, which displays more information about the + nature of the failure: + - 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. - - 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. + +$ ghc-pkg check +There are problems in package ghc-6.12.1: + dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist +There are problems in package haskeline-0.6.2: + dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist +There are problems in package Cabal-1.7.4: + dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist +There are problems in package process-1.0.1.1: + dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist +There are problems in package directory-1.0.0.2: + dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist + +The following packages are broken, either because they have a problem +listed above, or because they depend on a broken package. +ghc-6.12.1 +haskeline-0.6.2 +Cabal-1.7.4 +process-1.0.1.1 +directory-1.0.0.2 +bin-package-db-0.0.0.0 +hpc-0.5.0.2 +haskell98-1.0.1.0 + - 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. - + + To fix the problem, you need to recompile the broken packages + against the new dependencies. The easiest way to do this is to + use cabal-install, or download the packages + from HackageDB + and build and install them as normal. + + Be careful not to recompile any packages that GHC itself + depends on, as this may render the ghc + package itself broken, and ghc cannot be + simply recompiled. The only way to recover from this would be + to re-install GHC. + Package management (the <literal>ghc-pkg</literal> command) packages management - The ghc-pkg tool allows packages to be - added or removed from a package database. By default, - the system-wide package database is modified, but alternatively - the user's local package database or another specified - file can be used. - - To see what package databases are in use, say + The ghc-pkg tool is for querying and + modifying package databases. To see what package databases are + in use, use ghc-pkg list. The stack of databases that ghc-pkg knows about can be modified using the GHC_PACKAGE_PATH environment variable (see upon. Commands that query the package database (list, latest, - describe, field) operate on the list of databases specified by + describe, field, dot) operate on the list of databases specified by the flags , , and . If none of these flags are given, the default is @@ -498,6 +555,15 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf: + ghc-pkg init path + + Creates a new, empty, package database + at path, which must not already + exist. + + + + ghc-pkg register file Reads a package specification from @@ -631,6 +697,19 @@ c:/fptools/validate/ghc/driver/package.conf.inplace: + ghc-pkg dot + + + Generate a graph of the package dependencies in a form + suitable for input for the graphviz tools. For example, + to generate a PDF of the dependency graph: + +ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf + + + + + ghc-pkg dump Emit the full description of every package, in the @@ -646,6 +725,29 @@ c:/fptools/validate/ghc/driver/package.conf.inplace: simply emit nothing. + + + ghc-pkg recache + + + Re-creates the binary cache + file package.cache for the selected + database. This may be necessary if the cache has somehow + become out-of-sync with the contents of the database + (ghc-pkg will warn you if this might be + the case). + + + The other time when ghc-pkg recache is + useful is for registering packages manually: it is + possible to register a package by simply putting the + appropriate file in the package database directory and + invoking ghc-pkg recache to update the + cache. This method of registering packages may be more + convenient for automated packaging systems. + + + @@ -673,7 +775,7 @@ c:/fptools/validate/ghc/driver/package.conf.inplace: ghc-pkg field '*' haddock-html -- dump the whole database ghc-pkg describe '*' - + Additionally, the following flags are accepted by ghc-pkg: @@ -782,6 +884,23 @@ c:/fptools/validate/ghc/driver/package.conf.inplace: + + nghc-pkg + option + + + =nghc-pkg option + + + + Control verbosity. Verbosity levels range from 0-2, where + the default is 1, and alone selects + level 2. + + + + + @@ -796,14 +915,109 @@ c:/fptools/validate/ghc/driver/package.conf.inplace: - When modifying the package database - 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. - + + Building a package from Haskell source + packages + building + + We don't recommend building packages the hard way. Instead, use the + Cabal infrastructure + if possible. If your package is particularly complicated or requires a + 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). + + Building a static library is done by using the + ar tool, like so: + +ar cqs libHSfoo-1.0.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 + 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: + +ld -r ––whole-archive -o HSfoo.o libHSfoo.a + + (replace + ––whole-archive with + –all_load on MacOS X) + + + When building the package as shared library, GHC can be used to + perform the link step. This hides some of the details + out the underlying linker and provides 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. + + + + 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. + + <literal>InstalledPackageInfo</literal>: a package specification @@ -823,46 +1037,51 @@ c:/fptools/validate/ghc/driver/package.conf.inplace: <screen> $ ghc-pkg describe unix name: unix -version: 1.0 +version: 2.3.1.0 +id: unix-2.3.1.0-de7803f1a8cd88d2161b29b083c94240 license: BSD3 copyright: maintainer: libraries@haskell.org stability: homepage: package-url: -description: -category: +description: This package gives you access to the set of operating system + services standardised by POSIX 1003.1b (or the IEEE Portable + Operating System Interface for Computing Environments - + IEEE Std. 1003.1). + . + The package is not supported under Windows (except under Cygwin). +category: System author: exposed: True -exposed-modules: System.Posix, - System.Posix.DynamicLinker.Module, - System.Posix.DynamicLinker.Prim, - System.Posix.Directory, - System.Posix.DynamicLinker, - System.Posix.Env, - System.Posix.Error, - System.Posix.Files, - System.Posix.IO, - System.Posix.Process, - System.Posix.Resource, - System.Posix.Temp, - System.Posix.Terminal, - System.Posix.Time, - System.Posix.Unistd, - System.Posix.User, - System.Posix.Signals.Exts -import-dirs: /usr/lib/ghc-6.4/libraries/unix -library-dirs: /usr/lib/ghc-6.4/libraries/unix -hs-libraries: HSunix -extra-libraries: HSunix_cbits, dl -include-dirs: /usr/lib/ghc-6.4/libraries/unix/include -includes: HsUnix.h -depends: base-1.0 +exposed-modules: System.Posix System.Posix.DynamicLinker.Module + System.Posix.DynamicLinker.Prim System.Posix.Directory + System.Posix.DynamicLinker System.Posix.Env System.Posix.Error + System.Posix.Files System.Posix.IO System.Posix.Process + System.Posix.Process.Internals System.Posix.Resource + System.Posix.Temp System.Posix.Terminal System.Posix.Time + System.Posix.Unistd System.Posix.User System.Posix.Signals + System.Posix.Signals.Exts System.Posix.Semaphore + System.Posix.SharedMem +hidden-modules: +import-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0 +library-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0 +hs-libraries: HSunix-2.3.1.0 +extra-libraries: rt util dl +extra-ghci-libraries: +include-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0/include +includes: HsUnix.h execvpe.h +depends: base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c +hugs-options: +cc-options: +ld-options: +framework-dirs: +frameworks: +haddock-interfaces: /usr/share/doc/ghc/html/libraries/unix/unix.haddock +haddock-html: /usr/share/doc/ghc/html/libraries/unix </screen> - <para>The full <ulink url="../Cabal/index.html">Cabal documentation</ulink> - is still in preparation (at time of writing), so in the meantime - here is a brief description of the syntax of this file:</para> + <para>Here is a brief description of the syntax of this file:</para> <para>A package description consists of a number of field/value pairs. A field starts with the field name in the left-hand column followed by a @@ -914,6 +1133,17 @@ depends: base-1.0 <varlistentry> <term> + <literal>id</literal> + <indexterm><primary><literal>id</literal></primary><secondary>package specification</secondary></indexterm> + </term> + <listitem> + <para>The package's unique identifier. It is up to you to + choose a suitable one.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>version</literal> <indexterm><primary><literal>version</literal></primary><secondary>package specification</secondary></indexterm> </term> @@ -1214,10 +1444,8 @@ depends: base-1.0 <indexterm><primary><literal>depends</literal></primary><secondary>package specification</secondary></indexterm> </term> <listitem> - <para>(package name list) Packages on which this package depends. This field contains - packages with explicit versions are required, except that when - submitting a package to <literal>ghc-pkg register</literal>, the - versions will be filled in if they are unambiguous.</para> + <para>(package id list) Packages on which this package + depends.</para> </listitem> </varlistentry> -- 1.7.10.4