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,
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">
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>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
+ considered to be the global database, and will be modified by default by
+ <literal>ghc-pkg</literal>. The intention here is that
+ <literal>GHC_PACKAGE_PATH</literal> can be used to create a virtual
+ package environment into which Cabal packages can be installed without
+ setting anything other than <literal>GHC_PACKAGE_PATH</literal>.</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
<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
<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
<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>
projects / ghc-hetmet.git / blobdiff