From: Simon Marlow Date: Wed, 23 Sep 2009 09:46:39 +0000 (+0000) Subject: Document -package-id, and use the term "package ID" consistently X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=34a54b005658f88d27c064bfe7961f28d04a2ce1 Document -package-id, and use the term "package ID" consistently --- diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml index dbc0ea9..409d9d0 100644 --- a/docs/users_guide/packages.xml +++ b/docs/users_guide/packages.xml @@ -168,6 +168,22 @@ exposed-modules: Network.BSD, + + + + + + + Exposes a package like , but the + package is named by its ID rather than by name. This is a + more robust way to name packages, and can be used to + select packages that would otherwise be shadowed. Cabal + passes flags to GHC. + + + + + @@ -232,8 +248,9 @@ exposed-modules: Network.BSD, 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: + should be the full + package name-version for the package. + For example: -package mypkg-1.2. @@ -389,13 +406,15 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf: - - Dependencies and broken packages + + Package IDs, dependencies, and broken packages - 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: + Each installed package has a unique identifier (the + “installed package ID”, or just “package + ID” for short) , which distinguishes it from all other + installed packages on the system. To see the package IDs + associated with each installed package, use ghc-pkg + list -v: $ ghc-pkg list -v @@ -409,13 +428,13 @@ using cache: /usr/lib/ghc-6.12.1/package.conf.d/package.cache - 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: + The string in parentheses after the package name is the package + ID: 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 package + IDs, rather than just packages and versions. For example, take + a look at the dependencies of the haskell98 + package: @@ -430,23 +449,23 @@ depends: array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d - 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: + The purpose of the package ID 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 package IDs, a recompiled + package will have a different package ID 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: $ ghc-pkg list @@ -1137,8 +1156,8 @@ haddock-html: /usr/share/doc/ghc/html/libraries/unix idpackage specification - The package's unique identifier. It is up to you to - choose a suitable one. + The package ID. It is up to you to choose a suitable + one.