Packages
</title>
<indexterm><primary>packages</primary></indexterm>
-
- <para>A package is a library of Haskell modules known to the compiler. GHC
- comes with several packages: see the accompanying
- <ulink url="../libraries/index.html">library documentation</ulink>.</para>
+
+ <para>A package is a library of Haskell modules known to the
+ compiler. GHC comes with several packages: see the accompanying
+ <ulink url="../libraries/index.html">library
+ documentation</ulink>. More packages to install can be obtained
+ from <ulink
+ url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>.</para>
<para>Using a package couldn't be simpler: if you're using
- <option>--make</option> or GHCi, then most of the installed packages will be
+ <option>––make</option> 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 <xref
linkend="using-packages" />.</para>
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
<ulink url="../Cabal/index.html">Cabal documentation</ulink>
- for details, and also the Cabal libraries (<ulink url="../libraries/Cabal/Distribution-Simple.html">Distribution.Simple</ulink>,
+ for details, and also the Cabal libraries (<ulink url="&libraryCabalLocation;/Distribution-Simple.html">Distribution.Simple</ulink>,
for example).</para>
<sect2 id="using-packages">
</title>
<indexterm><primary>packages</primary>
<secondary>using</secondary></indexterm>
-
- <para>To see which packages are installed, use the
- <literal>ghc-pkg</literal> command:</para>
+
+ <para>GHC only knows about packages that are
+ <emphasis>installed</emphasis>. To see which packages are installed, use
+ the <literal>ghc-pkg list</literal> command:</para>
<screen>
$ 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
- </screen>
-
- <para>Packages are either exposed or hidden. 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.</para>
-
- <para>Each package has an exposed flag, which says whether it is exposed by
- default or not. Packages hidden by default are listed in
- parentheses (eg. <literal>(lang-1.0)</literal>) in the output from
- <literal>ghc-pkg list</literal>. To expose a package which is hidden by
- default, use the <option>-package</option>
- flag (see below).</para>
-
- <para>To see which modules are exposed by a package:</para>
-
+/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
+</screen>
+
+ <para>An installed package is either <emphasis>exposed</emphasis>
+ or <emphasis>hidden</emphasis> by default. Packages hidden by
+ default are listed in parentheses
+ (eg. <literal>(lang-1.0)</literal>), or possibly in blue if your
+ terminal supports colour, in the output of <literal>ghc-pkg
+ list</literal>. 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.
+ </para>
+
+ <para>
+ 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 <literal>.cabal</literal> specification. The
+ exposed/hidden status of packages is only relevant when
+ using <literal>ghc</literal> or <literal>ghci</literal>
+ directly.
+ </para>
+
+ <para>To see which modules are provided by a package use the
+ <literal>ghc-pkg</literal> command (see <xref linkend="package-management"/>):</para>
+
<screen>
$ ghc-pkg field network exposed-modules
exposed-modules: Network.BSD,
Network
</screen>
- <para>In general, packages containing hierarchical modules are usually
- exposed by default. However, it is possible for two packages to contain
- the same module: in this case, only one of the packages should be
- exposed. It is an error to import a module that belongs to more than one
- exposed package.</para>
-
<para>The GHC command line options that control packages are:</para>
<variablelist>
<varlistentry>
- <term>
- <option>-package <replaceable>P</replaceable></option>
- <indexterm><primary><option>-package</option></primary></indexterm>
- </term>
- <listitem>
- <para>This option causes package <replaceable>P</replaceable> to be
- exposed. The package <replaceable>P</replaceable> can be specified
- in full with its version number
- (e.g. <literal>network-1.0</literal>) or the version number can be
- omitted if there is only one version of the package
- installed.</para>
-
- <para>If there are multiple versions of <replaceable>P</replaceable>
- installed, then all other versions will become hidden.</para>
-
- <para>The <option>-package <replaceable>P</replaceable></option>
- option also causes package <replaceable>P</replaceable> to be
- linked into the resulting executable. In
- <option>––make</option> 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
- <option>-package</option> options must be given when linking.</para>
-
- <para>For example, to link a program consisting of objects
- <filename>Foo.o</filename> and <filename>Main.o</filename>, where
- we made use of the <literal>network</literal> package, we need to
- give GHC the <literal>-package</literal> flag thus:
+ <term>
+ <option>-package <replaceable>P</replaceable></option>
+ <indexterm><primary><option>-package</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>This option causes the installed
+ package <replaceable>P</replaceable> to be exposed. The
+ package <replaceable>P</replaceable> can be specified in
+ full with its version number
+ (e.g. <literal>network-1.0</literal>) or the version
+ number can be omitted if there is only one version of the
+ package installed. If there are multiple versions
+ of <replaceable>P</replaceable> installed, then all other
+ versions will become hidden.</para>
+
+ <para>The <option>-package <replaceable>P</replaceable></option>
+ option also causes package <replaceable>P</replaceable> 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 <option>-static</option>/<option>-dynamic</option>.</para>
+
+ <para>In <option>––make</option> mode
+ and <option>––interactive</option> mode (see
+ <xref linkend="modes" />), 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
+ <option>-package</option> options must be given when linking. The one other time you might need to use
+ <option>-package</option> 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.</para>
+
+ <para>For example, to link a program consisting of objects
+ <filename>Foo.o</filename> and <filename>Main.o</filename>, where
+ we made use of the <literal>network</literal> package, we need to
+ give GHC the <literal>-package</literal> flag thus:
<screen>$ ghc -o myprog Foo.o Main.o -package network</screen>
- 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:
+
+<screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen></para>
+ </listitem>
+ </varlistentry>
-<screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen>
+ <varlistentry>
+ <term>
+ <option>-package-id <replaceable>P</replaceable></option>
+ <indexterm><primary><option>-package-id</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>
+ Exposes a package like <option>-package</option>, 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 <option>-package-id</option> flags to GHC.
+ </para>
+ </listitem>
+ </varlistentry>
- In <literal>--make</literal> and <literal>--interactive</literal>
- modes (<xref linkend="modes" />), however, GHC figures out the
- packages required for linking without further assistance.</para>
+ <varlistentry>
+ <term><option>-hide-all-packages</option>
+ <indexterm><primary><option>-hide-package</option></primary>
+ </indexterm></term>
+ <listitem>
+ <para>Ignore the exposed flag on installed packages, and hide them
+ all by default. If you use
+ this flag, then any packages you require (including
+ <literal>base</literal>) need to be explicitly exposed using
+ <option>-package</option> options.</para>
+
+ <para>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
+ <option>-hide-all-packages</option> flag to GHC, for
+ exactly this reason.</para>
+ </listitem>
+ </varlistentry>
- <para>The one other time you might need to use
- <option>-package</option> 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.</para>
- </listitem>
+ <varlistentry>
+ <term><option>-hide-package</option> <replaceable>P</replaceable>
+ <indexterm><primary><option>-hide-package</option></primary>
+ </indexterm></term>
+ <listitem>
+ <para>This option does the opposite of <option>-package</option>: it
+ causes the specified package to be <firstterm>hidden</firstterm>,
+ which means that none of its modules will be available for import
+ by Haskell <literal>import</literal> directives.</para>
+
+ <para>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.</para>
+ </listitem>
</varlistentry>
-
+
<varlistentry>
- <term><option>-hide-all-packages</option>
- <indexterm><primary><option>-hide-package</option></primary>
- </indexterm></term>
- <listitem>
- <para>Ignore the exposed flag on installed packages, and hide them
- all by default. If you use
- this flag, then any packages you require (including
- <literal>base</literal>) need to be explicitly exposed using
- <option>-package</option> options.</para>
-
- <para>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
- <option>-hide-all-packages</option> flag to GHC, for
- exactly this reason.</para>
- </listitem>
+ <term><option>-ignore-package</option> <replaceable>P</replaceable>
+ <indexterm><primary><option>-ignore-package</option></primary>
+ </indexterm></term>
+ <listitem>
+ <para>Causes the compiler to behave as if package
+ <replaceable>P</replaceable>, and any packages that depend on
+ <literal>P</literal>, are not installed at all.</para>
+
+ <para>Saying <literal>-ignore-package P</literal> is the same as
+ giving <literal>-hide-package</literal> flags for
+ <literal>P</literal> and all the packages that depend on
+ <literal>P</literal>. Sometimes we don't know ahead of time which
+ packages will be installed that depend on <literal>P</literal>,
+ which is when the <literal>-ignore-package</literal> flag can be
+ useful.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><option>-hide-package</option> <replaceable>P</replaceable>
- <indexterm><primary><option>-hide-package</option></primary>
- </indexterm></term>
- <listitem>
- <para>This option does the opposite of <option>-package</option>: it
- causes the specified package to be <firstterm>hidden</firstterm>,
- which means that none of its modules will be available for import
- by Haskell <literal>import</literal> directives.</para>
-
- <para>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.</para>
- </listitem>
+ <term><option>-no-auto-link-packages</option>
+ <indexterm><primary><option>-no-auto-link-packages</option></primary>
+ </indexterm></term>
+ <listitem>
+ <para>By default, GHC will automatically link in the
+ <literal>haskell98</literal> package. This flag disables that
+ behaviour.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><option>-ignore-package</option> <replaceable>P</replaceable>
- <indexterm><primary><option>-ignore-package</option></primary>
- </indexterm></term>
- <listitem>
- <para>Causes the compiler to behave as if package
- <replaceable>P</replaceable>, and any packages that depend on
- <literal>P</literal>, are not installed at all.</para>
-
- <para>Saying <literal>-ignore-package P</literal> is the same as
- giving <literal>-hide-package</literal> flags for
- <literal>P</literal> and all the packages that depend on
- <literal>P</literal>. Sometimes we don't know ahead of time which
- packages will be installed that depend on <literal>P</literal>,
- which is when the <literal>-ignore-package</literal> flag can be
- useful.</para>
- </listitem>
+ <term><option>-package-name</option> <replaceable>foo</replaceable>
+ <indexterm><primary><option>-package-name</option></primary>
+ </indexterm></term>
+ <listitem>
+ <para>Tells GHC the the module being compiled forms part of
+ package <replaceable>foo</replaceable>.
+ If this flag is omitted (a very common case) then the
+ default package <literal>main</literal> is assumed.</para>
+ <para>Note: the argument to <option>-package-name</option>
+ should be the full
+ package <literal>name-version</literal> for the package.
+ For example:
+ <literal>-package mypkg-1.2</literal>.</para>
+ </listitem>
</varlistentry>
</variablelist>
</sect2>
+ <sect2 id="package-main">
+ <title>The main package</title>
+
+ <para>Every complete Haskell program must define <literal>main</literal> in
+ module <literal>Main</literal>
+ in package <literal>main</literal>. (Omitting the <option>-package-name</option> flag compiles
+ code for package <literal>main</literal>.) Failure to do so leads to a somewhat obscure
+ link-time error of the form:
+<programlisting>
+/usr/bin/ld: Undefined symbols:
+_ZCMain_main_closure
+</programlisting>
+</para>
+
+ </sect2>
+
<sect2 id="package-overlaps">
- <title>Consequences of packages</title>
+ <title>Consequences of packages for the Haskell language</title>
<para>It is possible that by using packages you might end up with
a program that contains two modules with the same name: perhaps
<sect2 id="package-databases">
<title>Package Databases</title>
-
- <para>A package database is a file, normally called
- <literal>package.conf</literal> which contains descriptions of installed
- packages. GHC usually knows about two package databases:</para>
+
+ <para>
+ A package database is where the details about installed packages
+ are stored. It is a directory, usually
+ called <literal>package.conf.d</literal>, that contains a file
+ for each package, together with a binary cache of the package
+ data in the file <literal>package.cache</literal>. 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 <literal>ghc-pkg</literal> tool (see
+ <xref linkend="package-management" />).
+ </para>
+
+ <para>
+ GHC knows about two package databases in particular:
+ </para>
<itemizedlist>
<listitem>
- <para>The global package database, which comes with your GHC
- installation.</para>
+ <para>The global package database, which comes with your GHC
+ installation,
+ e.g. <filename>/usr/lib/ghc-6.12.1/package.conf.d</filename>.</para>
</listitem>
<listitem>
- <para>A package database private to each user. On Unix
- systems this will be
- <filename>$HOME/.ghc/<replaceable>arch</replaceable>-<replaceable>os</replaceable>-<replaceable>version</replaceable>/package.conf</filename>, and on
- Windows it will be something like
- <filename>C:\Documents And Settings\<replaceable>user</replaceable>\ghc</filename>.
- The <literal>ghc-pkg</literal> tool knows where this file should be
- located, and will create it if it doesn't exist (see <xref linkend="package-management" />).</para>
+ <para>A package database private to each user. On Unix
+ systems this will be
+ <filename>$HOME/.ghc/<replaceable>arch</replaceable>-<replaceable>os</replaceable>-<replaceable>version</replaceable>/package.conf.d</filename>, and on
+ Windows it will be something like
+ <filename>C:\Documents And Settings\<replaceable>user</replaceable>\ghc\package.conf.d</filename>.
+ The <literal>ghc-pkg</literal> tool knows where this file should be
+ located, and will create it if it doesn't exist (see <xref linkend="package-management" />).</para>
</listitem>
</itemizedlist>
<para>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 <option>-v</option>
- flag.</para>
+ flag.</para>
- <para>Package databases may overlap: for example, packages in the user
- database will override those of the same name in the global
- database.</para>
+ <para>Package databases may overlap: for example, packages in the
+ user database will override (<emphasis>shadow</emphasis>) those
+ of the same name and version in the global database.</para>
- <para>You can control the loading of package databses using the following
- GHC options:</para>
+ <para>You can control the loading of package databases using the following
+ GHC options:</para>
<variablelist>
<varlistentry>
- <term>
- <option>-package-conf <replaceable>file</replaceable></option>
- <indexterm><primary><option>-package-conf</option></primary></indexterm>
- </term>
- <listitem>
- <para>Read in the package configuration file
- <replaceable>file</replaceable> 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.</para>
- </listitem>
+ <term>
+ <option>-package-conf <replaceable>file</replaceable></option>
+ <indexterm><primary><option>-package-conf</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Read in the package configuration file
+ <replaceable>file</replaceable> 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.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><option>-no-user-package-conf</option>
- <indexterm><primary><option>-no-user-package-conf</option></primary>
- </indexterm>
- </term>
- <listitem>
- <para>Prevent loading of the user's local package database.</para>
- </listitem>
+ <term><option>-no-user-package-conf</option>
+ <indexterm><primary><option>-no-user-package-conf</option></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>Prevent loading of the user's local package database.</para>
+ </listitem>
</varlistentry>
</variablelist>
- <para>To create a new package database, just create
- a new file and put the string
- <quote><literal>[]</literal></quote> in it. Packages can be
- added to the file using the
- <literal>ghc-pkg</literal> tool, described in <xref
- linkend="package-management"/>.</para>
-
<sect3 id="ghc-package-path">
<title>The <literal>GHC_PACKAGE_PATH</literal> environment variable</title>
<indexterm><primary>Environment variable</primary><secondary><literal>GHC_PACKAGE_PATH</literal></secondary>
</indexterm>
<indexterm><primary><literal>GHC_PACKAGE_PATH</literal></primary></indexterm>
<para>The <literal>GHC_PACKAGE_PATH</literal> environment variable may be
- set to a <literal>:</literal>-separated (<literal>;</literal>-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 <literal>PATH</literal> environment variable; think of
- it as a list of package databases that are searched left-to-right for
- packages.</para>
+ set to a <literal>:</literal>-separated (<literal>;</literal>-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 <literal>PATH</literal> environment variable; think of
+ it as a list of package databases that are searched left-to-right for
+ packages.</para>
<para>If <literal>GHC_PACKAGE_PATH</literal> 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):
<screen>
$ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
- (use <literal>;</literal> instead of <literal>:</literal> on
- Windows).</para>
+ (use <literal>;</literal> instead of <literal>:</literal> on
+ Windows).</para>
<para>To check whether your <literal>GHC_PACKAGE_PATH</literal> setting
- is doing the right thing, <literal>ghc-pkg list</literal> will list all
- the databases in use, in the reverse order they are searched.</para>
-
+ is doing the right thing, <literal>ghc-pkg list</literal> will list all
+ the databases in use, in the reverse order they are searched.</para>
+
</sect3>
</sect2>
- <sect2 id="building-packages">
- <title>Building a package from Haskell source</title>
- <indexterm><primary>packages</primary>
- <secondary>building</secondary></indexterm>
-
- <para>We don't recommend building packages the hard way. Instead, use the
- <ulink url="../Cabal/index.html">Cabal</ulink> 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.</para>
-
- <itemizedlist>
- <listitem>
- <para>You need to build an "installed package info" file for
- passing to <literal>ghc-pkg</literal> when installing your
- package. The contents of this file are described in <xref
- linkend="installed-pkg-info" />.</para>
- </listitem>
-
- <listitem>
- <para>The Haskell code in a package may be built into one or
- more archive libraries
- (e.g. <filename>libHSfoo.a</filename>), or a single DLL on
- Windows (e.g. <filename>HSfoo.dll</filename>). 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). <emphasis>Building packages as DLLs doesn't
- work at the moment; see <xref linkend="win32-dlls-create"/>
- for the gory details.</emphasis>
- </para>
-
- <para>Building a static library is done by using the
- <literal>ar</literal> tool, like so:</para>
-
-<screen>ar cqs libHSfoo.a A.o B.o C.o ...</screen>
-
- <para>where <filename>A.o</filename>,
- <filename>B.o</filename> and so on are the compiled Haskell
- modules, and <filename>libHSfoo.a</filename> is the library
- you wish to create. The syntax may differ slightly on your
- system, so check the documentation if you run into
- difficulties.</para>
-
- <para>Versions of the Haskell libraries for use with GHCi
- may also be included: GHCi cannot load <literal>.a</literal>
- files directly, instead it will look for an object file
- called <filename>HSfoo.o</filename> and load that. On some
- systems, the <literal>ghc-pkg</literal> tool can
- automatically build the GHCi version of each library, see
- <xref linkend="package-management"/>. To build these
- libraries by hand from the <literal>.a</literal> archive, it
- is possible to use GNU <command>ld</command> as
- follows:</para>
-
-<screen>ld -r ––whole-archive -o HSfoo.o libHSfoo.a</screen>
+ <sect2 id="package-ids">
+ <title>Package IDs, dependencies, and broken packages</title>
+
+ <para>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 <literal>ghc-pkg
+ list -v</literal>:</para>
+
+ <screen>
+$ 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)
+ ...
+</screen>
- <para>(replace
- <literal>––--whole-archive</literal> with
- <literal>–all_load</literal> on MacOS X)</para>
-
- <para>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.</para>
- </listitem>
- </itemizedlist>
-
- <para>To compile a module which is to be part of a new package,
- use the <literal>-package-name</literal> option:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>-package-name <replaceable>foo</replaceable></option>
- <indexterm><primary><literal>-package-name</literal></primary>
- <secondary>option</secondary></indexterm></term>
- <listitem>
- <para>This option is added to the command line when
- compiling a module that is destined to be part of package
- <literal>foo</literal>. If this flag is omitted then the
- default package <literal>main</literal> is assumed.</para>
+ <para>
+ 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 <literal>haskell98</literal>
+ package:
+ </para>
+
+ <screen>
+$ 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
+</screen>
- <para>Note: the argument to <option>-package-name</option>
- should be the full package identifier for the package,
- that is it should include the version number. For example:
- <literal>-package mypkg-1.2</literal>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <para>
+ 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 <literal>ghc-pkg list</literal> output either in red (if
+ possible) or otherwise surrounded by braces. In the following
+ example, we have recompiled and reinstalled
+ the <literal>filepath</literal> package, and this has caused
+ various dependencies including <literal>Cabal</literal> to
+ break:</para>
+
+ <screen>
+$ 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 ...
+</screen>
- <para>Failure to use the <literal>-package-name</literal> 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 <literal>.hi</literal>
- file.</para>
+ <para>
+ Additionally, <literal>ghc-pkg list</literal> reminds you that
+ there are broken packages and suggests <literal>ghc-pkg
+ check</literal>, which displays more information about the
+ nature of the failure:
+ </para>
+
+ <screen>
+$ 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
+</screen>
- <para>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
- <filename>main</filename> package as well.</para>
- </sect2>
+ <para>
+ To fix the problem, you need to recompile the broken packages
+ against the new dependencies. The easiest way to do this is to
+ use <literal>cabal-install</literal>, or download the packages
+ from <ulink
+ url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>
+ and build and install them as normal.</para>
+
+ <para>Be careful not to recompile any packages that GHC itself
+ depends on, as this may render the <literal>ghc</literal>
+ package itself broken, and <literal>ghc</literal> cannot be
+ simply recompiled. The only way to recover from this would be
+ to re-install GHC.</para>
+ </sect2>
<sect2 id="package-management">
<title>Package management (the <literal>ghc-pkg</literal> command)</title>
<indexterm><primary>packages</primary>
<secondary>management</secondary></indexterm>
-
- <para>The <literal>ghc-pkg</literal> 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.</para>
-
- <para>To see what package databases are in use, say
+
+ <para>The <literal>ghc-pkg</literal> tool is for querying and
+ modifying package databases. To see what package databases are
+ in use, use
<literal>ghc-pkg list</literal>. The stack of databases that
<literal>ghc-pkg</literal> knows about can be modified using the
<literal>GHC_PACKAGE_PATH</literal> environment variable (see <xref
- linkend="ghc-package-path" />, and using
- <literal>--package-conf</literal> options on the
- <literal>ghc-pkg</literal> command line.</para>
+ linkend="ghc-package-path" />, and using
+ <literal>--package-conf</literal> options on the
+ <literal>ghc-pkg</literal> command line.</para>
<para>When asked to modify a database, <literal>ghc-pkg</literal> modifies
the global database by default. Specifying <option>--user</option>
options are given, the rightmost one is used as the database to act
upon.</para>
+ <para>Commands that query the package database (list, latest,
+ describe, field, dot) operate on the list of databases specified by
+ the flags <option>--user</option>, <option>--global</option>, and
+ <option>--package-conf</option>. If none of these flags are
+ given, the default is <option>--global</option>
+ <option>--user</option>.</para>
+
<para>If the environment variable <literal>GHC_PACKAGE_PATH</literal> is
set, and its value does not end in a separator (<literal>:</literal> on
Unix, <literal>;</literal> on Windows), then the last database is
<para>The <literal>ghc-pkg</literal> 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. <literal>network-1.0</literal>), 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
<variablelist>
<varlistentry>
- <term><literal>ghc-pkg register <replaceable>file</replaceable></literal></term>
- <listitem>
- <para>Reads a package specification from
- <replaceable>file</replaceable> (which may be “<literal>-</literal>”
- to indicate standard input),
- and adds it to the database of installed packages. The syntax of
- <replaceable>file</replaceable> is given in <xref
- linkend="installed-pkg-info" />.</para>
-
- <para>The package specification must be a package that isn't already
- installed.</para>
- </listitem>
+ <term><literal>ghc-pkg init <replaceable>path</replaceable></literal></term>
+ <listitem>
+ <para>Creates a new, empty, package database
+ at <replaceable>path</replaceable>, which must not already
+ exist.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ghc-pkg register <replaceable>file</replaceable></literal></term>
+ <listitem>
+ <para>Reads a package specification from
+ <replaceable>file</replaceable> (which may be “<literal>-</literal>”
+ to indicate standard input),
+ and adds it to the database of installed packages. The syntax of
+ <replaceable>file</replaceable> is given in <xref
+ linkend="installed-pkg-info" />.</para>
+
+ <para>The package specification must be a package that isn't already
+ installed.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><literal>ghc-pkg update <replaceable>file</replaceable></literal></term>
- <listitem>
- <para>The same as <literal>register</literal>, except that if a
- package of the same name is already installed, it is
- replaced by the new one.</para>
- </listitem>
+ <term><literal>ghc-pkg update <replaceable>file</replaceable></literal></term>
+ <listitem>
+ <para>The same as <literal>register</literal>, except that if a
+ package of the same name is already installed, it is
+ replaced by the new one.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><literal>ghc-pkg unregister <replaceable>P</replaceable></literal></term>
- <listitem>
- <para>Remove the specified package from the database.</para>
- </listitem>
+ <term><literal>ghc-pkg unregister <replaceable>P</replaceable></literal></term>
+ <listitem>
+ <para>Remove the specified package from the database.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><literal>ghc-pkg expose <replaceable>P</replaceable></literal></term>
- <listitem>
- <para>Sets the <literal>exposed</literal> flag for package
- <replaceable>P</replaceable> to <literal>True</literal>.</para>
- </listitem>
+ <term><literal>ghc-pkg expose <replaceable>P</replaceable></literal></term>
+ <listitem>
+ <para>Sets the <literal>exposed</literal> flag for package
+ <replaceable>P</replaceable> to <literal>True</literal>.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
- <listitem>
- <para>Sets the <literal>exposed</literal> flag for package
- <replaceable>P</replaceable> to <literal>False</literal>.</para>
- </listitem>
+ <term><literal>ghc-pkg check</literal></term>
+ <listitem>
+ <para>Check consistency of dependencies in the package
+ database, and report packages that have missing
+ dependencies.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><literal>ghc-pkg list [<replaceable>P</replaceable>] [<option>--simple-output</option>]</literal></term>
- <listitem>
- <para>This option displays the currently installed
- packages, for each of the databases known to
- <literal>ghc-pkg</literal>. That includes the global database, the
- user's local database, and any further files specified using the
- <option>-f</option> option on the command line.</para>
-
- <para>Hidden packages (those for which the <literal>exposed</literal>
- flag is <literal>False</literal>) are shown in parentheses in the
- list of packages.</para>
-
- <para>If an optional package identifier <replaceable>P</replaceable>
- is given, then only packages matching that identifier are
- shown.</para>
-
- <para>If the option <option>--simple-output</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 <literal>ghc-pkg list</literal> using
- a script.</para>
- </listitem>
+ <term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
+ <listitem>
+ <para>Sets the <literal>exposed</literal> flag for package
+ <replaceable>P</replaceable> to <literal>False</literal>.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><literal>ghc-pkg latest <replaceable>P</replaceable></literal></term>
- <listitem>
- <para>Prints the latest available version of package
- <replaceable>P</replaceable>.</para>
- </listitem>
+ <term><literal>ghc-pkg list [<replaceable>P</replaceable>] [<option>--simple-output</option>]</literal></term>
+ <listitem>
+ <para>This option displays the currently installed
+ packages, for each of the databases known to
+ <literal>ghc-pkg</literal>. That includes the global database, the
+ user's local database, and any further files specified using the
+ <option>-f</option> option on the command line.</para>
+
+ <para>Hidden packages (those for which the <literal>exposed</literal>
+ flag is <literal>False</literal>) are shown in parentheses in the
+ list of packages.</para>
+
+ <para>If an optional package identifier <replaceable>P</replaceable>
+ is given, then only packages matching that identifier are
+ shown.</para>
+
+ <para>If the option <option>--simple-output</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 <literal>ghc-pkg list</literal> using
+ a script.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><literal>ghc-pkg describe <replaceable>P</replaceable></literal></term>
- <listitem>
- <para>Emit the full description of the specified package. The
- description is in the form of an
- <literal>InstalledPackageInfo</literal>, the same as the input file
- format for <literal>ghc-pkg register</literal>. See <xref
- linkend="installed-pkg-info" /> for details.</para>
- </listitem>
+ <term><literal>ghc-pkg find-module <replaceable>M</replaceable> [<option>--simple-output</option>]</literal></term>
+ <listitem>
+ <para>This option lists registered packages exposing module
+ <replaceable>M</replaceable>. Examples:</para>
+<screen>
+$ 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
+</screen>
+ <para>Otherwise, it behaves like <literal>ghc-pkg list</literal>,
+ including options.</para>
+ </listitem>
</varlistentry>
+
<varlistentry>
- <term><literal>ghc-pkg field <replaceable>P</replaceable> <replaceable>field</replaceable></literal></term>
- <listitem>
- <para>Show just a single field of the installed package description
- for <literal>P</literal>.</para>
- </listitem>
+ <term><literal>ghc-pkg latest <replaceable>P</replaceable></literal></term>
+ <listitem>
+ <para>Prints the latest available version of package
+ <replaceable>P</replaceable>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ghc-pkg describe <replaceable>P</replaceable></literal></term>
+ <listitem>
+ <para>Emit the full description of the specified package. The
+ description is in the form of an
+ <literal>InstalledPackageInfo</literal>, the same as the input file
+ format for <literal>ghc-pkg register</literal>. See <xref
+ linkend="installed-pkg-info" /> for details.</para>
+
+ <para>If the pattern matches multiple packages, the
+ description for each package is emitted, separated by the
+ string <literal>---</literal> on a line by itself.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ghc-pkg field <replaceable>P</replaceable> <replaceable>field</replaceable>[,<replaceable>field</replaceable>]*</literal></term>
+ <listitem>
+ <para>Show just a single field of the installed package description
+ for <literal>P</literal>. Multiple fields can be selected by separating
+ them with commas</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ghc-pkg dot</literal></term>
+ <listitem>
+ <para>
+ Generate a graph of the package dependencies in a form
+ suitable for input for the <ulink url="http://www.graphviz.org/">graphviz</ulink> tools. For example,
+ to generate a PDF of the dependency graph:</para>
+<screen>
+ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf
+</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ghc-pkg dump</literal></term>
+ <listitem>
+ <para>Emit the full description of every package, in the
+ form of an <literal>InstalledPackageInfo</literal>.
+ Multiple package descriptions are separated by the
+ string <literal>---</literal> on a line by itself.</para>
+
+ <para>This is almost the same as <literal>ghc-pkg describe '*'</literal>, except that <literal>ghc-pkg dump</literal>
+ is intended for use by tools that parse the results, so
+ for example where <literal>ghc-pkg describe '*'</literal>
+ will emit an error if it can't find any packages that
+ match the pattern, <literal>ghc-pkg dump</literal> will
+ simply emit nothing.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ghc-pkg recache</literal></term>
+ <listitem>
+ <para>
+ Re-creates the binary cache
+ file <filename>package.cache</filename> for the selected
+ database. This may be necessary if the cache has somehow
+ become out-of-sync with the contents of the database
+ (<literal>ghc-pkg</literal> will warn you if this might be
+ the case).</para>
+
+ <para>
+ The other time when <literal>ghc-pkg recache</literal> 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 <literal>ghc-pkg recache</literal> to update the
+ cache. This method of registering packages may be more
+ convenient for automated packaging systems.
+ </para>
+ </listitem>
</varlistentry>
</variablelist>
+ <para>
+ Substring matching is supported for <replaceable>M</replaceable> in
+ <literal>find-module</literal> and for <replaceable>P</replaceable> in
+ <literal>list</literal>, <literal>describe</literal>, and
+ <literal>field</literal>, where a <literal>'*'</literal> indicates open
+ substring ends (<literal>prefix*</literal>, <literal>*suffix</literal>,
+ <literal>*infix*</literal>). Examples (output omitted):
+ </para>
+ <screen>
+ -- 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 '*'
+</screen>
+
<para>Additionally, the following flags are accepted by
<literal>ghc-pkg</literal>:</para>
<variablelist>
<varlistentry>
- <term>
- <option>––auto-ghci-libs</option><indexterm><primary><option>––auto-ghci-libs</option></primary>
- </indexterm>
- </term>
- <listitem>
- <para>Automatically generate the GHCi
- <filename>.o</filename> version of each
- <filename>.a</filename> Haskell library, using GNU ld (if
- that is available). Without this option,
- <literal>ghc-pkg</literal> will warn if GHCi versions of
- any Haskell libraries in the package don't exist.</para>
-
- <para>GHCi <literal>.o</literal> libraries don't
- necessarily have to live in the same directory as the
- corresponding <literal>.a</literal> library. However,
- this option will cause the GHCi library to be created in
- the same directory as the <literal>.a</literal>
- library.</para>
- </listitem>
+ <term>
+ <option>––auto-ghci-libs</option><indexterm><primary><option>––auto-ghci-libs</option></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>Automatically generate the GHCi
+ <filename>.o</filename> version of each
+ <filename>.a</filename> Haskell library, using GNU ld (if
+ that is available). Without this option,
+ <literal>ghc-pkg</literal> will warn if GHCi versions of
+ any Haskell libraries in the package don't exist.</para>
+
+ <para>GHCi <literal>.o</literal> libraries don't
+ necessarily have to live in the same directory as the
+ corresponding <literal>.a</literal> library. However,
+ this option will cause the GHCi library to be created in
+ the same directory as the <literal>.a</literal>
+ library.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>
- <option>-f</option> <replaceable>file</replaceable>
- <indexterm><primary><option>-f</option></primary>
- </indexterm>
- </term>
- <term>
- <option>-package-conf</option> <replaceable>file</replaceable>
- <indexterm><primary><option>-package-conf</option></primary>
- </indexterm>
- </term>
- <listitem>
- <para>Adds <replaceable>file</replaceable> to the stack of package
- databases. Additionally, <replaceable>file</replaceable> will
- also be the database modified by a <literal>register</literal>,
- <literal>unregister</literal>, <literal>expose</literal> or
- <literal>hide</literal> command, unless it is overriden by a later
- <option>--package-conf</option>, <option>--user</option> or
- <option>--global</option> option.</para>
- </listitem>
+ <term>
+ <option>-f</option> <replaceable>file</replaceable>
+ <indexterm><primary><option>-f</option></primary>
+ </indexterm>
+ </term>
+ <term>
+ <option>-package-conf</option> <replaceable>file</replaceable>
+ <indexterm><primary><option>-package-conf</option></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>Adds <replaceable>file</replaceable> to the stack of package
+ databases. Additionally, <replaceable>file</replaceable> will
+ also be the database modified by a <literal>register</literal>,
+ <literal>unregister</literal>, <literal>expose</literal> or
+ <literal>hide</literal> command, unless it is overridden by a later
+ <option>--package-conf</option>, <option>--user</option> or
+ <option>--global</option> option.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>
- <option>––force</option>
- <indexterm><primary>
- <option>––force</option>
- </primary></indexterm>
- </term>
- <listitem>
- <para>Causes <literal>ghc-pkg</literal> 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.</para>
- </listitem>
+ <term>
+ <option>––force</option>
+ <indexterm><primary>
+ <option>––force</option>
+ </primary></indexterm>
+ </term>
+ <listitem>
+ <para>Causes <literal>ghc-pkg</literal> 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.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>
- <option>––global</option><indexterm><primary><option>––global</option></primary>
- </indexterm>
- </term>
- <listitem>
- <para>Operate on the global package database (this is the default).
- This flag affects the <literal>register</literal>,
- <literal>update</literal>, <literal>unregister</literal>,
- <literal>expose</literal>, and <literal>hide</literal>
- commands.</para>
- </listitem>
+ <term>
+ <option>––global</option><indexterm><primary><option>––global</option></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>Operate on the global package database (this is the default).
+ This flag affects the <literal>register</literal>,
+ <literal>update</literal>, <literal>unregister</literal>,
+ <literal>expose</literal>, and <literal>hide</literal>
+ commands.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>
- <option>––help</option><indexterm><primary><option>––help</option></primary>
- </indexterm>
- </term>
- <term>
- <option>-?</option><indexterm><primary><option>-?</option></primary>
- </indexterm>
- </term>
- <listitem>
- <para>Outputs the command-line syntax.</para>
- </listitem>
+ <term>
+ <option>––help</option><indexterm><primary><option>––help</option></primary>
+ </indexterm>
+ </term>
+ <term>
+ <option>-?</option><indexterm><primary><option>-?</option></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>Outputs the command-line syntax.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>
- <option>––user</option><indexterm><primary><option>––user</option></primary>
- </indexterm>
- </term>
- <listitem>
- <para>Operate on the current user's local package database.
- This flag affects the <literal>register</literal>,
- <literal>update</literal>, <literal>unregister</literal>,
- <literal>expose</literal>, and <literal>hide</literal>
- commands.</para>
- </listitem>
+ <term>
+ <option>––user</option><indexterm><primary><option>––user</option></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>Operate on the current user's local package database.
+ This flag affects the <literal>register</literal>,
+ <literal>update</literal>, <literal>unregister</literal>,
+ <literal>expose</literal>, and <literal>hide</literal>
+ commands.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>
- <option>-V</option><indexterm><primary><option>-V</option></primary>
- </indexterm>
- </term>
- <term>
- <option>––version</option><indexterm><primary><option>––version</option></primary>
- </indexterm>
- </term>
- <listitem>
- <para>Output the <literal>ghc-pkg</literal> version number.</para>
- </listitem>
+ <term>
+ <option>-v</option><optional><replaceable>n</replaceable></optional><indexterm><primary><option>-v</option></primary><secondary>ghc-pkg
+ option</secondary></indexterm>
+ </term>
+ <term>
+ <option>--verbose</option><optional>=<replaceable>n</replaceable></optional><indexterm><primary><option>--verbose</option></primary><secondary>ghc-pkg option</secondary></indexterm>
+ </term>
+ <listitem>
+ <para>
+ Control verbosity. Verbosity levels range from 0-2, where
+ the default is 1, and <option>-v</option> alone selects
+ level 2.
+ </para>
+ </listitem>
</varlistentry>
- </variablelist>
- <para>When modifying the package database
- <replaceable>file</replaceable>, a copy of the original file is
- saved in <replaceable>file</replaceable><literal>.old</literal>,
- so in an emergency you can always restore the old settings by
- copying the old file back again.</para>
+ <varlistentry>
+ <term>
+ <option>-V</option><indexterm><primary><option>-V</option></primary>
+ </indexterm>
+ </term>
+ <term>
+ <option>––version</option><indexterm><primary><option>––version</option></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>Output the <literal>ghc-pkg</literal> version number.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</sect2>
-
+
+ <sect2 id="building-packages">
+ <title>Building a package from Haskell source</title>
+ <indexterm><primary>packages</primary>
+ <secondary>building</secondary></indexterm>
+
+ <para>We don't recommend building packages the hard way. Instead, use the
+ <ulink url="../Cabal/index.html">Cabal</ulink> 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.</para>
+
+ <para>You need to build an "installed package info" file for
+ passing to <literal>ghc-pkg</literal> when installing your
+ package. The contents of this file are described in
+ <xref linkend="installed-pkg-info" />.</para>
+
+ <para>The Haskell code in a package may be built into one or more
+ archive libraries (e.g. <filename>libHSfoo.a</filename>), or a
+ single shared object
+ (e.g. <filename>libHSfoo.dll/.so/.dylib</filename>). 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).</para>
+ <itemizedlist>
+ <listitem><para>Building a static library is done by using the
+ <literal>ar</literal> tool, like so:</para>
+
+<screen>ar cqs libHSfoo-1.0.a A.o B.o C.o ...</screen>
+
+ <para>where <filename>A.o</filename>,
+ <filename>B.o</filename> and so on are the compiled Haskell
+ modules, and <filename>libHSfoo.a</filename> is the library you
+ wish to create. The syntax may differ slightly on your system,
+ so check the documentation if you run into difficulties.</para>
+ </listitem>
+ <listitem>
+ <para>Versions of the Haskell libraries for use with GHCi may also
+ abe included: GHCi cannot load <literal>.a</literal> files
+ directly, instead it will look for an object file
+ called <filename>HSfoo.o</filename> and load that. On some
+ systems, the <literal>ghc-pkg</literal> tool can automatically
+ build the GHCi version of each library, see
+ <xref linkend="package-management"/>. To build these libraries
+ by hand from the <literal>.a</literal> archive, it is possible
+ to use GNU <command>ld</command> as follows:</para>
+
+<screen>ld -r ––whole-archive -o HSfoo.o libHSfoo.a</screen>
+
+ <para>(replace
+ <literal>––whole-archive</literal> with
+ <literal>–all_load</literal> on MacOS X)</para>
+ </listitem>
+ <listitem>
+ <para>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 <option>-static</option>/<option>-dynamic</option> flags
+ work, see <xref linkend="options-linker" />.</para>
+
+<screen>ghc -shared libHSfoo-1.0-ghc<replaceable>GHCVersion</replaceable>.so A.o B.o C.o</screen>
+ <para>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 <literal>ghc --numeric-version</literal> and use
+ its output in place
+ of <replaceable>GHCVersion</replaceable>. See also
+ <xref linkend="options-codegen" /> on how object files must
+ be prepared for shared object linking.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>To compile a module which is to be part of a new package,
+ use the <literal>-package-name</literal> option (<xref linkend="using-packages"/>).
+ Failure to use the <literal>-package-name</literal> 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 <literal>.hi</literal>
+ file.</para>
+
+ <para>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
+ <filename>main</filename> package as well.</para>
+ </sect2>
+
<sect2 id="installed-pkg-info">
<title>
<literal>InstalledPackageInfo</literal>: a package specification
<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
<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
<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>
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
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.
<!-- Emacs stuff:
;;; Local Variables: ***
- ;;; mode: xml ***
;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
;;; End: ***
-->
projects / ghc-hetmet.git / blobdiff