Document ghc-pkg find-module, substring matching, and multi-field selection

[ghc-hetmet.git] / docs / users_guide / packages.xml

diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml
index f209d57..8f8f880 100644 (file)
--- a/docs/users_guide/packages.xml
+++ b/docs/users_guide/packages.xml
@@ -5,9 +5,12 @@ Packages
  </title>
   <indexterm><primary>packages</primary></indexterm>
   
  </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
 
   <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

@@ -30,8 +33,9 @@ Packages
     <indexterm><primary>packages</primary>
       <secondary>using</secondary></indexterm>
     
     <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</literal> command:</para>

 
 <screen>
 $ ghc-pkg list
 
 <screen>
 $ ghc-pkg list

@@ -44,19 +48,16 @@ $ ghc-pkg list
     (hssource-1.0), rts-1.0
       </screen>
 
     (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
+    <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>) in the output above.  Command-line flags, described below, allow you to expose a hidden package
+      or hide an exposed one.
+      Only modules from exposed packages may be imported by your Haskell code; if

       you try to import a module from a hidden package, GHC will emit an error
       message.</para>
 
       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>
+    <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
     
 <screen>
 $ ghc-pkg field network exposed-modules

@@ -67,12 +68,6 @@ exposed-modules: Network.BSD,
                  Network
 </screen>
 
                  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>
     <para>The GHC command line options that control packages are:</para>
 
     <variablelist>

@@ -82,24 +77,36 @@ exposed-modules: Network.BSD,
          <indexterm><primary><option>-package</option></primary></indexterm>
        </term>
        <listitem>
          <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>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>
 
          <para>The <option>-package <replaceable>P</replaceable></option>

-           option also causes package <replaceable>P</replaceable> to be
-           linked into the resulting executable.  In
-           <option>&ndash;&ndash;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>
+           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>&ndash;&ndash;make</option> mode
+           and <option>&ndash;&ndash;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
 
          <para>For example, to link a program consisting of objects
            <filename>Foo.o</filename> and <filename>Main.o</filename>, where

@@ -111,18 +118,7 @@ exposed-modules: Network.BSD,
            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>
-
-           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>
-
-         <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>
+<screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen></para>

        </listitem>
       </varlistentry>
       
        </listitem>
       </varlistentry>
       

@@ -180,9 +176,42 @@ exposed-modules: Network.BSD,
            useful.</para>
        </listitem>
       </varlistentry>
            useful.</para>
        </listitem>
       </varlistentry>

+
+      <varlistentry>
+       <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 identifier for the package,
+            that is it should include the version number.  For example:
+            <literal>-package mypkg-1.2</literal>.</para>
+       </listitem>
+      </varlistentry>

     </variablelist>
   </sect2>
 
     </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
+___stginit_ZCMain
+</programlisting>
+</para>
+
+  </sect2>
+

   <sect2 id="package-overlaps">
     <title>Consequences of packages</title>
 
   <sect2 id="package-overlaps">
     <title>Consequences of packages</title>
 

@@ -243,7 +272,7 @@ exposed-modules: Network.BSD,
       database will override those of the same name in the global
       database.</para> 
 
       database will override those of the same name in the global
       database.</para> 
 

-    <para>You can control the loading of package databses using the following
+    <para>You can control the loading of package databases using the following

       GHC options:</para> 
 
     <variablelist>
       GHC options:</para> 
 
     <variablelist>

@@ -320,87 +349,86 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
       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>
     
       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>
     <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
+      <listitem><para>Building a static library is done by using the

          <literal>ar</literal> tool, like so:</para>
 
          <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>
+<screen>ar cqs libHSfoo-1.0.a A.o B.o C.o ...</screen>

 
 

-       <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
+         <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
          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>
+         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 &ndash;&ndash;whole-archive -o HSfoo.o libHSfoo.a</screen>
 
        <para>(replace
 
 <screen>ld -r &ndash;&ndash;whole-archive -o HSfoo.o libHSfoo.a</screen>
 
        <para>(replace

-          <literal>&ndash;&ndash;--whole-archive</literal> with
-          <literal>&ndash;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>
+         <literal>&ndash;&ndash;whole-archive</literal> with
+         <literal>&ndash;all_load</literal> on MacOS X)</para>
+      </listitem>
+      <listitem>
+       <para>When building the package as shared object, GHC wraps
+         out the underlying linker so that the user gets 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>
       </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>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>Failure to use the <literal>-package-name</literal> option
+     <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>
+    
+     <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
       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

@@ -408,8 +436,8 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
       same as the package name stored in the <literal>.hi</literal>
       file.</para>
 
       same as the package name stored in the <literal>.hi</literal>
       file.</para>
 

-    <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
+    <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>
       indirection, intra-package references are cheaper than
       inter-package references. Of course, this applies to the
       <filename>main</filename> package as well.</para>

@@ -441,6 +469,13 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
       options are given, the rightmost one is used as the database to act
       upon.</para>
 
       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) 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>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

@@ -501,6 +536,15 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
       </varlistentry>
 
       <varlistentry>
       </varlistentry>
 
       <varlistentry>

+       <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 hide <replaceable>P</replaceable></literal></term>
        <listitem>
          <para>Sets the <literal>exposed</literal> flag for package
        <term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
        <listitem>
          <para>Sets the <literal>exposed</literal> flag for package

@@ -534,6 +578,26 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
       </varlistentry>
 
       <varlistentry>
       </varlistentry>
 
       <varlistentry>

+       <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 latest <replaceable>P</replaceable></literal></term>
        <listitem>
          <para>Prints the latest available version of package
        <term><literal>ghc-pkg latest <replaceable>P</replaceable></literal></term>
        <listitem>
          <para>Prints the latest available version of package

@@ -553,14 +617,42 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
       </varlistentry>
 
       <varlistentry>
       </varlistentry>
 
       <varlistentry>

-       <term><literal>ghc-pkg field <replaceable>P</replaceable> <replaceable>field</replaceable></literal></term>
+       <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
        <listitem>
          <para>Show just a single field of the installed package description

-           for <literal>P</literal>.</para>
+      for <literal>P</literal>. Multiple fields can be selected by separating 
+      them with commas</para>

        </listitem>
       </varlistentry>
     </variablelist>
 
        </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>
 
     <para>Additionally, the following flags are accepted by
       <literal>ghc-pkg</literal>:</para>
 

@@ -603,7 +695,7 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
            databases.  Additionally, <replaceable>file</replaceable> will
            also be the database modified by a <literal>register</literal>,
            <literal>unregister</literal>, <literal>expose</literal> or
            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
+           <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>
            <option>--package-conf</option>, <option>--user</option> or
            <option>--global</option> option.</para>
        </listitem>