the <ulink url="http://www.haskell.org/cabal/">Cabal</ulink> infrastructure which
automates the process of configuring, building, installing and distributing
a package. All you need to do is write a simple configuration file, put a
- few files in the right places, and you have a package. See the Cabal
- documentation for details, and also the Cabal libraries (<ulink url="../libraries/Cabal/Distribution.Simple.html">Distribution.Simple</ulink>,
+ 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 example).</para>
<sect2 id="using-packages">
<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>
</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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-hide-package</option> <replaceable>P</replaceable>
<indexterm><primary><option>-hide-package</option></primary>
</indexterm></term>
</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>
<secondary>building</secondary></indexterm>
<para>We don't recommend building packages the hard way. Instead, use the
- <ulink url="http://www.haskell.org/cabal/">Cabal</ulink> infrastructure
+ <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>
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
<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 used, but alternatively
+ the system-wide package database is modified, but alternatively
the user's local package database or another specified
file can be used.</para>
- <para>The <literal>ghc-pkg</literal> program may be run in the following
- ways. Where a package name is required, the package can be named either
- in full including the version number
- (e.g. <literal>network-1.0</literal>), or without the version number if
- that is unambiguous.</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>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.
+ 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, and any further files
- specified using the <option>-f</option> option on the command
- line.</para>
+ 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>
<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>
</term>
<listitem>
<para>Operate on the package database in
- <replaceable>file</replaceable>.
- This flag affects the <literal>register</literal>,
- <literal>update</literal>, <literal>unregister</literal>,
- <literal>expose</literal>, and <literal>hide</literal>
- commands.</para>
+ <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 takes precedence. When listing packages
- with <literal>ghc-pkg list</literal>, the contents of all the
- databases specified on the command-line are listed.</para>
+ one on the command-line is the one that will be modified.</para>
</listitem>
</varlistentry>
<para>A package specification is a Haskell record; in particular, it is the
record <ulink
- url="../libraries/Cabal/Distribution.InstalledPackageInfo#%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
</screen>
- <para>The full Cabal documentation 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>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>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
<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