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="../libraries/Cabal/Distribution-Simple.html">Distribution.Simple</ulink>,
for example).</para>
<sect2 id="using-packages">
<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>
-
+
+ <para>To see which modules are exposed by a package:</para>
+
<screen>
$ ghc-pkg field network exposed-modules
exposed-modules: Network.BSD,
<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 can be
- exposed. This might happen if you have two versions of the same package
- installed, for example. The general rule is:</para>
-
- <blockquote><para>There must be no overlaps in the modules provided by all
- of the exposed packages, and the packages they depend on, and so
- on.</para></blockquote>
+ 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>
</indexterm></term>
<listitem>
<para>Causes the compiler to behave as if package
- <replaceable>P</replaceable> is not installed at all. This is not
- the same as <option>-hide-package</option>, because under
- <option>-hide-package</option> the package might still be present
- in the program if another package depends on it.</para>
-
- <para><option>-ignore-package</option> <replaceable>P</replaceable>
- not only causes package <replaceable>P</replaceable> to be removed,
- but also everything that depends on <replaceable>P</replaceable>,
- and so on.</para>
-
- <para>Why do we need <option>-ignore-package</option>? Well, it is
- particularly useful when you're actually compiling package
- <replaceable>P</replaceable> itself. The compiler will refuse to
- compile module <replaceable>M</replaceable> if
- <replaceable>M</replaceable> is already part of a package. So we
- might try <option>-hide-package</option>
- <replaceable>P</replaceable>; but then if
- <replaceable>P</replaceable> is a dependency of another package
- <replaceable>P'</replaceable> we would have to
- <option>-hide-package</option> <replaceable>P'</replaceable> too;
- and the author of the code can't know in advance which packages are
- installed on the system and hence which
- <option>-hide-package</option> flags are required. So, we provide
- <option>-ignore-package</option> which does the Right Thing.</para>
+ <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>
</variablelist>
</sect2>
+ <sect2 id="package-overlaps">
+ <title>The module overlap restriction</title>
+
+ <para>The module names in a Haskell program must be distinct.
+ This doesn't sound like a severe restriction, but in a Haskell program
+ using multiple packages with interdependencies, difficulties can start to
+ arise. You should be aware of what the module overlap
+ restriction means, and how to avoid it.</para>
+
+ <para>GHC knows which packages are <emphasis>in use</emphasis> by your
+ program: a package is in use if you imported something from it, or if it
+ is a dependency of some other package in use. There must be no conflicts
+ between the packages in use; a conflict is when two packages contain
+ a module with the same name. If
+ GHC detects a conflict, it will issue a message stating which packages
+ are in conflict, and which modules are overlapping.</para>
+
+ <para>For example, a conflict might arise if you use two packages, say P
+ and Q, which respectively depend on two different versions of another
+ package, say <literal>R-1.0</literal> and <literal>R-2.0</literal>. The
+ two versions of <literal>R</literal> are likely to contain at least some
+ of the same modules, so this situation would be a conflict.</para>
+ </sect2>
+
<sect2 id="package-databases">
<title>Package Databases</title>
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>
+ located, and will create it if it doesn't exist (see <xref linkend="package-management" />).</para>
</listitem>
</itemizedlist>
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>
+
+ <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):
+<screen>
+$ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
+ (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>
+ </sect3>
</sect2>
<sect2 id="building-packages">
other packages the current module depends on, but not which
things within those imported things.</para>
</listitem>
-
- <listitem>
- <para>When compiling a Haskell module which is to be part of a new package
- <replaceable>P</replaceable>, use
- <option>-ignore-package</option> <replaceable>P</replaceable>.</para>
- </listitem>
</itemizedlist>
<para>It is worth noting that on Windows, when each package
the user's local package database or another specified
file can be used.</para>
- <para>Commands which only inspect the database (<literal>list</literal>,
- <literal>describe</literal>, <literal>field</literal>) will take into
- account the user's local package database too, unless the
- <literal>--global</literal> option is given. This matches the behaviour
- of GHC, which automatically reads the user's local database if it is
- available.</para>
+ <para>To see what package databases are in use, say
+ <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>
+
+ <para>When asked to modify a database, <literal>ghc-pkg</literal> modifies
+ the global database by default. Specifying <option>--user</option>
+ causes it to act on the user database, or <option>--package-conf</option>
+ can be used to act on another database entirely. When multiple of these
+ options are given, the rightmost one is used as the database to act
+ upon.</para>
<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
- (e.g. <literal>network-1.0</literal>), or without the version number if
- there is only a single version of that package installed. Additionally,
- the version may be given as <literal>*</literal>, which means “all
- versions”. For example, <literal>ghc-pkg hide network-*</literal>
- would hide all versions of the network package.</para>
+ (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
+ packages. A package specifier that matches all version of the package
+ can also be written <replaceable>pkg</replaceable><literal>-*</literal>,
+ to make it clearer that multiple packages are being matched.</para>
<variablelist>
<varlistentry>
</varlistentry>
<varlistentry>
- <term><literal>ghc-pkg list</literal></term>
+ <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 (if <option>--user</option> is given), and
- any further files specified using the <option>-f</option> option on
- the command line.</para>
+ 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 latest <replaceable>P</replaceable></literal></term>
+ <listitem>
+ <para>Prints the latest available version of package
+ <replaceable>P</replaceable>.</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry>
<term>
- <option>––auto-ghci-libs</option><indexterm><primary><option>––user</option></primary>
+ <option>––auto-ghci-libs</option><indexterm><primary><option>––auto-ghci-libs</option></primary>
</indexterm>
</term>
<listitem>
</indexterm>
</term>
<listitem>
- <para>Operate on the package database in
- <replaceable>file</replaceable>.</para>
-
- <para>When multiple <option>-f</option> options are given, or
- <option>-f</option> is used in conjunction with
- <option>--user</option> or <option>--global</option>, the last
- one on the command-line is the one that will be modified.</para>
+ <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>
</varlistentry>
<varlistentry>
<term>
- <option>––global</option><indexterm><primary><option>––user</option></primary>
+ <option>––global</option><indexterm><primary><option>––global</option></primary>
</indexterm>
</term>
<listitem>
<varlistentry>
<term>
- <option>––help</option><indexterm><primary><option>––user</option></primary>
+ <option>––help</option><indexterm><primary><option>––help</option></primary>
</indexterm>
</term>
<term>
</indexterm>
</term>
<term>
- <option>––version</option><indexterm><primary><option>––user</option></primary>
+ <option>––version</option><indexterm><primary><option>––version</option></primary>
</indexterm>
</term>
<listitem>
<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="../libraries/Cabal/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
import-dirs: /usr/lib/ghc-6.4/libraries/unix
library-dirs: /usr/lib/ghc-6.4/libraries/unix
hs-libraries: HSunix
-extra-libs: HSunix_cbits, dl
+extra-libraries: HSunix_cbits, dl
include-dirs: /usr/lib/ghc-6.4/libraries/unix/include
includes: HsUnix.h
depends: base-1.0
<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>
+ url="../libraries/Cabal/Distribution-License.html#t:License"><literal>License</literal></ulink> type.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>extra-libs</literal>
- <indexterm><primary><literal>extra-libs</literal></primary><secondary>package specification</secondary></indexterm>
+ <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-libs</literal> is that
+ <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
version. The suffix is added automatically by GHC for
<literal>hs-libraries</literal> only, no suffix is added
for libraries in
- <literal>extra-libs</literal>.</para>
+ <literal>extra-libraries</literal>.</para>
<para>The libraries listed in
- <literal>extra-libs</literal> may be any libraries
+ <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-libs</literal> are placed
+ <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-libs</literal> depends on
+ <literal>extra-libraries</literal> depends on
<literal>hs-libraries</literal>), and the libraries are
static, you might need to make two separate
packages.</para>
<varlistentry>
<term>
- <literal>extra-hugs-opts</literal>
- <indexterm><primary><literal>extra-hugs-opts</literal></primary><secondary>package specification</secondary></indexterm>
+ <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>
<varlistentry>
<term>
- <literal>extra-cc-opts</literal>
- <indexterm><primary><literal>extra-cc-opts</literal></primary><secondary>package specification</secondary></indexterm>
+ <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
<varlistentry>
<term>
- <literal>extra-ld-opts</literal>
- <indexterm><primary><literal>extra-ld-opts</literal></primary><secondary>package specification</secondary></indexterm>
+ <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
<varlistentry>
<term>
- <literal>extra-frameworks</literal>
- <indexterm><primary><literal>extra-frameworks</literal></primary><secondary>package specification</secondary></indexterm>
+ <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
projects / ghc-hetmet.git / blobdiff