X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=docs%2Fusers_guide%2Fpackages.xml;h=86df5944b2382e2f9a710b9cee1b699c03977863;hp=1de51a93b455825441476b961e6f82292d8083b8;hb=a52ff7619e8b7d74a9d933d922eeea49f580bca8;hpb=1d708730ee5d0882c59f3d90422ff04fa0e5f39b diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml index 1de51a9..86df594 100644 --- a/docs/users_guide/packages.xml +++ b/docs/users_guide/packages.xml @@ -4,7 +4,7 @@ Packages packages - + A package is a library of Haskell modules known to the compiler. GHC comes with several packages: see the accompanying library @@ -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 . @@ -24,7 +24,7 @@ Packages a package. All you need to do is write a simple configuration file, put a few files in the right places, and you have a package. See the Cabal documentation - for details, and also the Cabal libraries (Distribution.Simple, + for details, and also the Cabal libraries (Distribution.Simple, for example). @@ -32,33 +32,78 @@ Packages packages using - + 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 ): - + $ ghc-pkg field network exposed-modules exposed-modules: Network.BSD, @@ -72,124 +117,153 @@ exposed-modules: Network.BSD, - - - - - - This option causes the installed package P to be - exposed. The package P can be specified - in full with its version number - (e.g. network-1.0) or the version number can be - omitted if there is only one version of the package - installed. - - If there are multiple versions of P - installed, then all other versions will become hidden. - - The - option also causes package P to be - linked into the resulting executable. In - mode and GHCi, the compiler - normally determines which packages are required by the current - Haskell modules, and links only those. In batch mode however, the - dependency information isn't available, and explicit - options must be given when linking. - - For example, to link a program consisting of objects - Foo.o and Main.o, where - we made use of the network package, we need to - give GHC the -package flag thus: + + + + + + This option causes the installed + package P to be exposed. The + package P can be specified in + full with its version number + (e.g. network-1.0) or the version + number can be omitted if there is only one version of the + package installed. If there are multiple versions + of P installed, then all other + versions will become hidden. + + The + option also causes package P to + be linked into the resulting executable or shared + object. Whether a packages' library is linked statically + or dynamically is controlled by the flag + pair /. + + In mode + and mode (see + ), the compiler normally + determines which packages are required by the current + Haskell modules, and links only those. In batch mode + however, the dependency information isn't available, and + explicit + options must be given when linking. The one other time you might need to use + to force linking a package is + when the package does not contain any Haskell modules (it + might contain a C library only, for example). In that + case, GHC will never discover a dependency on it, so it + has to be mentioned explicitly. + + For example, to link a program consisting of objects + Foo.o and Main.o, where + we made use of the network package, we need to + give GHC the -package flag thus: $ ghc -o myprog Foo.o Main.o -package network - The same flag is necessary even if we compiled the modules from - source, because GHC still reckons it's in batch mode: + The same flag is necessary even if we compiled the modules from + source, because GHC still reckons it's in batch mode: -$ ghc -o myprog Foo.hs Main.hs -package network +$ ghc -o myprog Foo.hs Main.hs -package network + + - In --make and --interactive - modes (), however, GHC figures out the - packages required for linking without further assistance. + + + + + + + + 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. + + + - The one other time you might need to use - to force linking a package is when the - package does not contain any Haskell modules (it might contain a C - library only, for example). In that case, GHC - will never discover a dependency on it, so it has to be mentioned - explicitly. - + + + + + + Ignore the exposed flag on installed packages, and hide them + all by default. If you use + this flag, then any packages you require (including + base) need to be explicitly exposed using + options. + + This is a good way to insulate your program from + differences in the globally exposed packages, and being + explicit about package dependencies is a Good Thing. + Cabal always passes the + flag to GHC, for + exactly this reason. + - + - - - - - Ignore the exposed flag on installed packages, and hide them - all by default. If you use - this flag, then any packages you require (including - base) need to be explicitly exposed using - options. - - This is a good way to insulate your program from - differences in the globally exposed packages, and being - explicit about package dependencies is a Good Thing. - Cabal always passes the - flag to GHC, for - exactly this reason. - + P + + + + This option does the opposite of : it + causes the specified package to be hidden, + which means that none of its modules will be available for import + by Haskell import directives. + + Note that the package might still end up being linked into the + final program, if it is a dependency (direct or indirect) of + another exposed package. + - P - - - - This option does the opposite of : it - causes the specified package to be hidden, - which means that none of its modules will be available for import - by Haskell import directives. - - Note that the package might still end up being linked into the - final program, if it is a dependency (direct or indirect) of - another exposed package. - + P + + + + Causes the compiler to behave as if package + P, and any packages that depend on + P, are not installed at all. + + Saying -ignore-package P is the same as + giving -hide-package flags for + P and all the packages that depend on + P. Sometimes we don't know ahead of time which + packages will be installed that depend on P, + which is when the -ignore-package flag can be + useful. + - P - - - - Causes the compiler to behave as if package - P, and any packages that depend on - P, are not installed at all. - - Saying -ignore-package P is the same as - giving -hide-package flags for - P and all the packages that depend on - P. Sometimes we don't know ahead of time which - packages will be installed that depend on P, - which is when the -ignore-package flag can be - useful. - + + + + + By default, GHC will automatically link in the + haskell98 package. This flag disables that + behaviour. + - foo - - - - Tells GHC the the module being compiled forms part of - package foo. - If this flag is omitted (a very common case) then the - default package main is assumed. + foo + + + + Tells GHC the the module being compiled forms part of + package foo. + 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. - + @@ -197,22 +271,21 @@ exposed-modules: Network.BSD, The main package - Every complete Haskell program must define main in - module Main + Every complete Haskell program must define main in + module Main in package main. (Omitting the flag compiles code for package main.) Failure to do so leads to a somewhat obscure link-time error of the form: /usr/bin/ld: Undefined symbols: _ZCMain_main_closure -___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 @@ -241,206 +314,240 @@ ___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. + The global package database, which comes with your GHC + 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 - Windows it will be something like - C:\Documents And Settings\user\ghc. - The ghc-pkg tool knows where this file should be - located, and will create it if it doesn't exist (see ). + A package database private to each user. On Unix + systems this will be + $HOME/.ghc/arch-os-version/package.conf.d, and on + Windows it will be something like + 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 ). When GHC starts up, it reads the contents of these two package databases, and builds up a list of the packages it knows about. You can see GHC's package table by running GHC with the - flag. + 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: + GHC options: - - - - - - Read in the package configuration file - file in addition to the system - default file and the user's local file. Packages in additional - files read this way will override those in the global and user - databases. - + + + + + + Read in the package configuration file + file in addition to the system + default file and the user's local file. Packages in additional + files read this way will override those in the global and user + databases. + - - - - - - Prevent loading of the user's local package database. - + + + + + + Prevent loading of the user's local package database. + - 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 GHC_PACKAGE_PATH The GHC_PACKAGE_PATH environment variable may be - set to a :-separated (;-separated - on Windows) list of files containing package databases. This list of - package databases is used by GHC and ghc-pkg, with earlier databases in - the list overriding later ones. This order was chosen to match the - behaviour of the PATH environment variable; think of - it as a list of package databases that are searched left-to-right for - packages. + set to a :-separated (;-separated + on Windows) list of files containing package databases. This list of + package databases is used by GHC and ghc-pkg, with earlier databases in + the list overriding later ones. This order was chosen to match the + behaviour of the PATH environment variable; think of + it as a list of package databases that are searched left-to-right for + packages. If GHC_PACKAGE_PATH ends in a separator, then - the default user and system package databases are appended, in that - order. e.g. to augment the usual set of packages with a database of - your own, you could say (on Unix): + the default user and system package databases are appended, in that + order. e.g. to augment the usual set of packages with a database of + your own, you could say (on Unix): $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf: - (use ; instead of : on - Windows). + (use ; instead of : on + Windows). To check whether your GHC_PACKAGE_PATH setting - is doing the right thing, ghc-pkg list will list all - the databases in use, in the reverse order they are searched. - + is doing the right thing, ghc-pkg list will list all + the databases in use, in the reverse order they are searched. + - - Building a package from Haskell source - packages - building + + Package IDs, dependencies, and broken packages + + 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 +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) + ... + - 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 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. 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: + + 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: + + + +$ 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 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 +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 ... + - (replace - ––whole-archive with - –all_load on MacOS X) - - 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. + + 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-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 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. - + + 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 , and using - --package-conf options on the - ghc-pkg command line. + linkend="ghc-package-path" />, and using + --package-conf options on the + ghc-pkg command line. When asked to modify a database, ghc-pkg modifies the global database by default. Specifying @@ -449,6 +556,13 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf: options are given, the rightmost one is used as the database to act upon. + Commands that query the package database (list, latest, + describe, field, dot) operate on the list of databases specified by + the flags , , and + . If none of these flags are + given, the default is + . + If the environment variable GHC_PACKAGE_PATH is set, and its value does not end in a separator (: on Unix, ; on Windows), then the last database is @@ -460,7 +574,7 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf: The ghc-pkg program may be run in the ways listed below. Where a package name is required, the package can be named in - full including the version number + full including the version number (e.g. network-1.0), or without the version number. Naming a package without the version number matches all versions of the package; the specified action will be applied to all the matching @@ -470,234 +584,469 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf: - ghc-pkg register file - - Reads a package specification from - file (which may be “-” - to indicate standard input), - and adds it to the database of installed packages. The syntax of - file is given in . - - The package specification must be a package that isn't already - installed. - + 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 + file (which may be “-” + to indicate standard input), + and adds it to the database of installed packages. The syntax of + file is given in . + + The package specification must be a package that isn't already + installed. + + + + + ghc-pkg update file + + The same as register, except that if a + package of the same name is already installed, it is + replaced by the new one. + + + + + ghc-pkg unregister P + + Remove the specified package from the database. + + + + + ghc-pkg expose P + + Sets the exposed flag for package + P to True. + + + + + ghc-pkg check + + Check consistency of dependencies in the package + database, and report packages that have missing + dependencies. + - ghc-pkg update file - - The same as register, except that if a - package of the same name is already installed, it is - replaced by the new one. - + ghc-pkg hide P + + Sets the exposed flag for package + P to False. + - ghc-pkg unregister P - - Remove the specified package from the database. - + ghc-pkg list [P] [] + + This option displays the currently installed + packages, for each of the databases known to + ghc-pkg. That includes the global database, the + user's local database, and any further files specified using the + option on the command line. + + Hidden packages (those for which the exposed + flag is False) are shown in parentheses in the + list of packages. + + If an optional package identifier P + is given, then only packages matching that identifier are + shown. + + If the option is given, then + the packages are listed on a single line separated by spaces, and + the database names are not included. This is intended to make it + easier to parse the output of ghc-pkg list using + a script. + - ghc-pkg expose P - - Sets the exposed flag for package - P to True. - + ghc-pkg find-module M [] + + This option lists registered packages exposing module + M. Examples: + +$ ghc-pkg find-module Var +c:/fptools/validate/ghc/driver/package.conf.inplace: + (ghc-6.9.20080428) + +$ ghc-pkg find-module Data.Sequence +c:/fptools/validate/ghc/driver/package.conf.inplace: + containers-0.1 + + Otherwise, it behaves like ghc-pkg list, + including options. + + - ghc-pkg hide P - - Sets the exposed flag for package - P to False. - + ghc-pkg latest P + + Prints the latest available version of package + P. + - ghc-pkg list [P] [] - - This option displays the currently installed - packages, for each of the databases known to - ghc-pkg. That includes the global database, the - user's local database, and any further files specified using the - option on the command line. - - Hidden packages (those for which the exposed - flag is False) are shown in parentheses in the - list of packages. - - If an optional package identifier P - is given, then only packages matching that identifier are - shown. - - If the option is given, then - the packages are listed on a single line separated by spaces, and - the database names are not included. This is intended to make it - easier to parse the output of ghc-pkg list using - a script. - + ghc-pkg describe P + + Emit the full description of the specified package. The + description is in the form of an + InstalledPackageInfo, the same as the input file + format for ghc-pkg register. See for details. + + If the pattern matches multiple packages, the + description for each package is emitted, separated by the + string --- on a line by itself. + - ghc-pkg latest P - - Prints the latest available version of package - P. - + ghc-pkg field P field[,field]* + + Show just a single field of the installed package description + for P. Multiple fields can be selected by separating + them with commas + - ghc-pkg describe P - - Emit the full description of the specified package. The - description is in the form of an - InstalledPackageInfo, the same as the input file - format for ghc-pkg register. See for details. - + 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 field P field - - Show just a single field of the installed package description - for P. - + ghc-pkg dump + + Emit the full description of every package, in the + form of an InstalledPackageInfo. + Multiple package descriptions are separated by the + string --- on a line by itself. + + This is almost the same as ghc-pkg describe '*', except that ghc-pkg dump + is intended for use by tools that parse the results, so + for example where ghc-pkg describe '*' + will emit an error if it can't find any packages that + match the pattern, ghc-pkg dump will + 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. + + + + Substring matching is supported for M in + find-module and for P in + list, describe, and + field, where a '*' indicates open + substring ends (prefix*, *suffix, + *infix*). Examples (output omitted): + + + -- list all regex-related packages + ghc-pkg list '*regex*' --ignore-case + -- list all string-related packages + ghc-pkg list '*string*' --ignore-case + -- list OpenGL-related packages + ghc-pkg list '*gl*' --ignore-case + -- list packages exporting modules in the Data hierarchy + ghc-pkg find-module 'Data.*' + -- list packages exporting Monad modules + ghc-pkg find-module '*Monad*' + -- list names and maintainers for all packages + ghc-pkg field '*' name,maintainer + -- list location of haddock htmls for all packages + ghc-pkg field '*' haddock-html + -- dump the whole database + ghc-pkg describe '*' + + Additionally, the following flags are accepted by ghc-pkg: - - - - - - 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. - + + + + + + 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. + - - file - - - - - file - - - - - Adds file to the stack of package - databases. Additionally, file will - also be the database modified by a register, - unregister, expose or - hide command, unless it is overriden by a later - , or - option. - + + file + + + + + file + + + + + Adds file to the stack of package + databases. Additionally, file will + also be the database modified by a register, + unregister, expose or + hide command, unless it is overridden by a later + , or + option. + - - - - - - - - Causes ghc-pkg to ignore missing - dependencies, directories and libraries when registering 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. - + + + + + + + + Causes ghc-pkg to ignore missing + dependencies, directories and libraries when registering 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. + - - - - - - Operate on the global package database (this is the default). - This flag affects the register, - update, unregister, - expose, and hide - commands. - + + + + + + Operate on the global package database (this is the default). + This flag affects the register, + update, unregister, + expose, and hide + commands. + - - - - - - - - - - Outputs the command-line syntax. - + + + + + + + + + + Outputs the command-line syntax. + - - - - - - Operate on the current user's local package database. - This flag affects the register, - update, unregister, - expose, and hide - commands. - + + + + + + Operate on the current user's local package database. + This flag affects the register, + update, unregister, + expose, and hide + commands. + - - - - - - - - - - Output the ghc-pkg version number. - + + nghc-pkg + option + + + =nghc-pkg option + + + + Control verbosity. Verbosity levels range from 0-2, where + the default is 1, and alone selects + level 2. + + - - 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. + + + + + + + + + + + Output the ghc-pkg version number. + + + - + + + 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 @@ -705,7 +1054,7 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen> <para>A package specification is a Haskell record; in particular, it is the record <ulink - url="../libraries/Cabal/Distribution-InstalledPackageInfo.html#%tInstalledPackageInfo">InstalledPackageInfo</ulink> in the module Distribution.InstalledPackageInfo, which is part of the Cabal package distributed with GHC.</para> + url="&libraryCabalLocation;/Distribution-InstalledPackageInfo.html#%tInstalledPackageInfo">InstalledPackageInfo</ulink> in the module Distribution.InstalledPackageInfo, which is part of the Cabal package distributed with GHC.</para> <para>An <literal>InstalledPackageInfo</literal> has a human readable/writable syntax. The functions @@ -717,46 +1066,51 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen> <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 @@ -768,25 +1122,25 @@ depends: base-1.0 <variablelist> <varlistentry> - <term>freeform</term> - <listitem> - <para>Any arbitrary string, no interpretation or parsing is - done.</para> - </listitem> + <term>freeform</term> + <listitem> + <para>Any arbitrary string, no interpretation or parsing is + done.</para> + </listitem> </varlistentry> <varlistentry> - <term>string</term> - <listitem> - <para>A sequence of non-space characters, or a sequence of arbitrary - characters surrounded by quotes <literal>"...."</literal>.</para> - </listitem> + <term>string</term> + <listitem> + <para>A sequence of non-space characters, or a sequence of arbitrary + characters surrounded by quotes <literal>"...."</literal>.</para> + </listitem> </varlistentry> <varlistentry> - <term>string list</term> - <listitem> - <para>A sequence of strings, separated by commas. The sequence may - be empty.</para> - </listitem> + <term>string list</term> + <listitem> + <para>A sequence of strings, separated by commas. The sequence may + be empty.</para> + </listitem> </varlistentry> </variablelist> @@ -794,411 +1148,420 @@ depends: base-1.0 names, version, dependencies).</para> <para>The allowed fields, with their types, are:</para> - + <variablelist> <varlistentry> - <term> - <literal>name</literal> - <indexterm><primary><literal>name</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>The package's name (without the version).</para> - </listitem> + <term> + <literal>name</literal> + <indexterm><primary><literal>name</literal></primary><secondary>package specification</secondary></indexterm> + </term> + <listitem> + <para>The package's name (without the version).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>id</literal> + <indexterm><primary><literal>id</literal></primary><secondary>package specification</secondary></indexterm> + </term> + <listitem> + <para>The package ID. 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> - <listitem> - <para>The package's version, usually in the form - <literal>A.B</literal> (any number of components are allowed).</para> - </listitem> + <term> + <literal>version</literal> + <indexterm><primary><literal>version</literal></primary><secondary>package specification</secondary></indexterm> + </term> + <listitem> + <para>The package's version, usually in the form + <literal>A.B</literal> (any number of components are allowed).</para> + </listitem> </varlistentry> - + <varlistentry> - <term> - <literal>license</literal> - <indexterm><primary><literal>auto</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(string) The type of license under which this package is distributed. - This field is a value of the <ulink - url="../libraries/Cabal/Distribution-License.html#t:License"><literal>License</literal></ulink> type.</para> - </listitem> + <term> + <literal>license</literal> + <indexterm><primary><literal>auto</literal></primary><secondary>package specification</secondary></indexterm> + </term> + <listitem> + <para>(string) The type of license under which this package is distributed. + This field is a value of the <ulink + url="&libraryCabalLocation;/Distribution-License.html#t:License"><literal>License</literal></ulink> type.</para> + </listitem> </varlistentry> - <varlistentry> - <term> + <varlistentry> + <term> <literal>license-file</literal> <indexterm><primary><literal>license-file</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(optional string) The name of a file giving detailed license - information for this package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(optional string) The name of a file giving detailed license + information for this package.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>copyright</literal> <indexterm><primary><literal>copyright</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(optional freeform) The copyright string.</para> - </listitem> - </varlistentry> + <listitem> + <para>(optional freeform) The copyright string.</para> + </listitem> + </varlistentry> - <varlistentry> - <term> + <varlistentry> + <term> <literal>maintainer</literal> <indexterm><primary><literal>maintainer</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(optinoal freeform) The email address of the package's maintainer.</para> - </listitem> - </varlistentry> + <listitem> + <para>(optinoal freeform) The email address of the package's maintainer.</para> + </listitem> + </varlistentry> - <varlistentry> - <term> + <varlistentry> + <term> <literal>stability</literal> <indexterm><primary><literal>stability</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(optional freeform) A string describing the stability of the package - (eg. stable, provisional or experimental).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(optional freeform) A string describing the stability of the package + (eg. stable, provisional or experimental).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>homepage</literal> <indexterm><primary><literal>homepage</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(optional freeform) URL of the package's home page.</para> - </listitem> - </varlistentry> + <listitem> + <para>(optional freeform) URL of the package's home page.</para> + </listitem> + </varlistentry> <varlistentry> - <term> + <term> <literal>package-url</literal> <indexterm><primary><literal>package-url</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(optional freeform) URL of a downloadable distribution for this - package. The distribution should be a Cabal package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(optional freeform) URL of a downloadable distribution for this + package. The distribution should be a Cabal package.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>description</literal> <indexterm><primary><literal>description</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(optional freeform) Description of the package.</para> - </listitem> - </varlistentry> + <listitem> + <para>(optional freeform) Description of the package.</para> + </listitem> + </varlistentry> <varlistentry> - <term> + <term> <literal>category</literal> <indexterm><primary><literal>category</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(optinoal freeform) Which category the package belongs to. This field - is for use in conjunction with a future centralised package - distribution framework, tentatively titled Hackage.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(optinoal freeform) Which category the package belongs to. This field + is for use in conjunction with a future centralised package + distribution framework, tentatively titled Hackage.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>author</literal> <indexterm><primary><literal>author</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(optional freeform) Author of the package.</para> - </listitem> - </varlistentry> + <listitem> + <para>(optional freeform) Author of the package.</para> + </listitem> + </varlistentry> - <varlistentry> - <term> + <varlistentry> + <term> <literal>exposed</literal> <indexterm><primary><literal>exposed</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(bool) Whether the package is exposed or not.</para> - </listitem> - </varlistentry> + <listitem> + <para>(bool) Whether the package is exposed or not.</para> + </listitem> + </varlistentry> - <varlistentry> - <term> + <varlistentry> + <term> <literal>exposed-modules</literal> <indexterm><primary><literal>exposed-modules</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(string list) modules exposed by this package.</para> - </listitem> - </varlistentry> + <listitem> + <para>(string list) modules exposed by this package.</para> + </listitem> + </varlistentry> - <varlistentry> - <term> + <varlistentry> + <term> <literal>hidden-modules</literal> <indexterm><primary><literal>hidden-modules</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(string list) modules provided by this package, - but not exposed to the programmer. These modules cannot be - imported, but they are still subject to the overlapping constraint: - no other package in the same program may provide a module of the - same name.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(string list) modules provided by this package, + but not exposed to the programmer. These modules cannot be + imported, but they are still subject to the overlapping constraint: + no other package in the same program may provide a module of the + same name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>import-dirs</literal> <indexterm><primary><literal>import-dirs</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(string list) A list of directories containing interface files - (<literal>.hi</literal> files) for this package.</para> - - <para>If the package contains profiling libraries, then - the interface files for those library modules should have - the suffix <literal>.p_hi</literal>. So the package can - contain both normal and profiling versions of the same - library without conflict (see also - <literal>library_dirs</literal> below).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(string list) A list of directories containing interface files + (<literal>.hi</literal> files) for this package.</para> + + <para>If the package contains profiling libraries, then + the interface files for those library modules should have + the suffix <literal>.p_hi</literal>. So the package can + contain both normal and profiling versions of the same + library without conflict (see also + <literal>library_dirs</literal> below).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>library-dirs</literal> <indexterm><primary><literal>library-dirs</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(string list) A list of directories containing libraries for this - package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(string list) A list of directories containing libraries for this + package.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>hs-libraries</literal> <indexterm><primary><literal>hs-libraries</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(string list) A list of libraries containing Haskell code for this - package, with the <literal>.a</literal> or - <literal>.dll</literal> suffix omitted. When packages are - built as libraries, the - <literal>lib</literal> prefix is also omitted.</para> - - <para>For use with GHCi, each library should have an - object file too. The name of the object file does - <emphasis>not</emphasis> have a <literal>lib</literal> - prefix, and has the normal object suffix for your - platform.</para> - - <para>For example, if we specify a Haskell library as - <filename>HSfoo</filename> in the package spec, then the - various flavours of library that GHC actually uses will be - called:</para> - <variablelist> - <varlistentry> - <term><filename>libHSfoo.a</filename></term> - <listitem> - <para>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.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>HSfoo.dll</filename></term> - <listitem> - <para>The name of the dynamic library on Windows - systems (optional).</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>HSfoo.o</filename></term> - <term><filename>HSfoo.obj</filename></term> - <listitem> - <para>The object version of the library used by - GHCi.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(string list) A list of libraries containing Haskell code for this + package, with the <literal>.a</literal> or + <literal>.dll</literal> suffix omitted. When packages are + built as libraries, the + <literal>lib</literal> prefix is also omitted.</para> + + <para>For use with GHCi, each library should have an + object file too. The name of the object file does + <emphasis>not</emphasis> have a <literal>lib</literal> + prefix, and has the normal object suffix for your + platform.</para> + + <para>For example, if we specify a Haskell library as + <filename>HSfoo</filename> in the package spec, then the + various flavours of library that GHC actually uses will be + called:</para> + <variablelist> + <varlistentry> + <term><filename>libHSfoo.a</filename></term> + <listitem> + <para>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.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>HSfoo.dll</filename></term> + <listitem> + <para>The name of the dynamic library on Windows + systems (optional).</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>HSfoo.o</filename></term> + <term><filename>HSfoo.obj</filename></term> + <listitem> + <para>The object version of the library used by + GHCi.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>extra-libraries</literal> <indexterm><primary><literal>extra-libraries</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(string list) A list of extra libraries for this package. The - difference between <literal>hs-libraries</literal> and - <literal>extra-libraries</literal> is that - <literal>hs-libraries</literal> normally have several - versions, to support profiling, parallel and other build - options. The various versions are given different - suffixes to distinguish them, for example the profiling - version of the standard prelude library is named - <filename>libHSbase_p.a</filename>, with the - <literal>_p</literal> indicating that this is a profiling - version. The suffix is added automatically by GHC for - <literal>hs-libraries</literal> only, no suffix is added - for libraries in - <literal>extra-libraries</literal>.</para> - - <para>The libraries listed in - <literal>extra-libraries</literal> may be any libraries - supported by your system's linker, including dynamic - libraries (<literal>.so</literal> on Unix, - <literal>.DLL</literal> on Windows).</para> - - <para>Also, <literal>extra-libraries</literal> are placed - on the linker command line after the - <literal>hs-libraries</literal> for the same package. If - your package has dependencies in the other direction (i.e. - <literal>extra-libraries</literal> depends on - <literal>hs-libraries</literal>), and the libraries are - static, you might need to make two separate - packages.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(string list) A list of extra libraries for this package. The + difference between <literal>hs-libraries</literal> and + <literal>extra-libraries</literal> is that + <literal>hs-libraries</literal> normally have several + versions, to support profiling, parallel and other build + options. The various versions are given different + suffixes to distinguish them, for example the profiling + version of the standard prelude library is named + <filename>libHSbase_p.a</filename>, with the + <literal>_p</literal> indicating that this is a profiling + version. The suffix is added automatically by GHC for + <literal>hs-libraries</literal> only, no suffix is added + for libraries in + <literal>extra-libraries</literal>.</para> + + <para>The libraries listed in + <literal>extra-libraries</literal> may be any libraries + supported by your system's linker, including dynamic + libraries (<literal>.so</literal> on Unix, + <literal>.DLL</literal> on Windows).</para> + + <para>Also, <literal>extra-libraries</literal> are placed + on the linker command line after the + <literal>hs-libraries</literal> for the same package. If + your package has dependencies in the other direction (i.e. + <literal>extra-libraries</literal> depends on + <literal>hs-libraries</literal>), and the libraries are + static, you might need to make two separate + packages.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>include-dirs</literal> <indexterm><primary><literal>include-dirs</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(string list) A list of directories containing C includes for this - package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(string list) A list of directories containing C includes for this + package.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>includes</literal> <indexterm><primary><literal>includes</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(string list) A list of files to include for via-C compilations - using this package. Typically the include file(s) will - contain function prototypes for any C functions used in - the package, in case they end up being called as a result - of Haskell functions from the package being - inlined.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(string list) A list of files to include for via-C compilations + using this package. Typically the include file(s) will + contain function prototypes for any C functions used in + the package, in case they end up being called as a result + of Haskell functions from the package being + inlined.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>depends</literal> <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> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(package id list) Packages on which this package + depends.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>hugs-options</literal> <indexterm><primary><literal>hugs-options</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(string list) Options to pass to Hugs for this package.</para> - </listitem> - </varlistentry> + <listitem> + <para>(string list) Options to pass to Hugs for this package.</para> + </listitem> + </varlistentry> - <varlistentry> - <term> + <varlistentry> + <term> <literal>cc-options</literal> <indexterm><primary><literal>cc-options</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(string list) Extra arguments to be added to the gcc command line - when this package is being used (only for via-C - compilations).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(string list) Extra arguments to be added to the gcc command line + when this package is being used (only for via-C + compilations).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>ld-options</literal> <indexterm><primary><literal>ld-options</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(string list) Extra arguments to be added to the - <command>gcc</command> command line (for linking) when - this package is being used.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(string list) Extra arguments to be added to the + <command>gcc</command> command line (for linking) when + this package is being used.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>framework-dirs</literal> <indexterm><primary><literal>framework-dirs</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(string list) On Darwin/MacOS X, a list of directories containing - frameworks for this package. This corresponds to the - <option>-framework-path</option> option. It is ignored on all other - platforms.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(string list) On Darwin/MacOS X, a list of directories containing + frameworks for this package. This corresponds to the + <option>-framework-path</option> option. It is ignored on all other + platforms.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>frameworks</literal> <indexterm><primary><literal>frameworks</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(string list) On Darwin/MacOS X, a list of frameworks to link to. This - corresponds to the <option>-framework</option> option. Take a look - at Apple's developer documentation to find out what frameworks - actually are. This entry is ignored on all other platforms.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(string list) On Darwin/MacOS X, a list of frameworks to link to. This + corresponds to the <option>-framework</option> option. Take a look + at Apple's developer documentation to find out what frameworks + actually are. This entry is ignored on all other platforms.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>haddock-interfaces</literal> <indexterm><primary><literal>haddock-interfaces</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(string list) A list of filenames containing <ulink - url="http://www.haskell.org/haddock/">Haddock</ulink> interface - files (<literal>.haddock</literal> files) for this package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> + <listitem> + <para>(string list) A list of filenames containing <ulink + url="http://www.haskell.org/haddock/">Haddock</ulink> interface + files (<literal>.haddock</literal> files) for this package.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>haddock-html</literal> <indexterm><primary><literal>haddock-html</literal></primary><secondary>package specification</secondary></indexterm> </term> - <listitem> - <para>(optional string) The directory containing the Haddock-generated HTML - for this package.</para> - </listitem> - </varlistentry> + <listitem> + <para>(optional string) The directory containing the Haddock-generated HTML + for this package.</para> + </listitem> + </varlistentry> </variablelist> - + <!-- This isn't true any more. I'm not sure if we still need it -SDM <para> The <literal>ghc-pkg</literal> tool performs expansion of @@ -1215,7 +1578,7 @@ depends: base-1.0 with <literal>/usr/local/lib</literal> in the package data that is added for <literal>mypkg</literal>. </para> - + <para> This feature enables the distribution of package specification files that can be easily configured when installing. @@ -1232,7 +1595,6 @@ depends: base-1.0 <!-- Emacs stuff: ;;; Local Variables: *** - ;;; mode: xml *** ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** ;;; End: *** -->