diff options
Diffstat (limited to 'docs/users_guide/packages.xml')
| -rw-r--r-- | docs/users_guide/packages.xml | 1193 |
1 files changed, 1193 insertions, 0 deletions
diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml new file mode 100644 index 0000000000..3bd65c66ce --- /dev/null +++ b/docs/users_guide/packages.xml @@ -0,0 +1,1193 @@ +<?xml version="1.0" encoding="iso-8859-1"?> + <sect1 id="packages"> + <title> +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>Using a package couldn't be simpler: if you're using + <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> + + <para>Building your own packages is also quite straightforward: we provide + 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 + <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"> + <title>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> + +<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> + +<screen> +$ ghc-pkg field network exposed-modules +exposed-modules: Network.BSD, + Network.CGI, + Network.Socket, + Network.URI, + 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: + +<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: + +<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> + </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.</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> + </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> + </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> + + <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> + + <itemizedlist> + <listitem> + <para>The global package database, which comes with your GHC + installation.</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> + </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> + + <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>You can control the loading of package databses 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> + </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> + </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> + + <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"> + <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> + + <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>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> + + <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 + <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 + 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> + <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> + </varlistentry> + + <varlistentry> + <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> + </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> + </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> + </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> + + <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> + </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> + </varlistentry> + </variablelist> + + <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> + </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> + </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> + </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> + </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> + </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> + </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> + </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> + + </sect2> + + <sect2 id="installed-pkg-info"> + <title> + <literal>InstalledPackageInfo</literal>: a package specification + </title> + + <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> + + <para>An <literal>InstalledPackageInfo</literal> has a human + readable/writable syntax. The functions + <literal>parseInstalledPackageInfo</literal> and + <literal>showInstalledPackageInfo</literal> read and write this syntax + respectively. Here's an example of the + <literal>InstalledPackageInfo</literal> for the <literal>unix</literal> package:</para> + +<screen> +$ ghc-pkg describe unix +name: unix +version: 1.0 +license: BSD3 +copyright: +maintainer: libraries@haskell.org +stability: +homepage: +package-url: +description: +category: +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 +</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>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 + “<literal>:</literal>”, and the value continues until the next line that begins in the + left-hand column, or the end of file.</para> + + <para>The syntax of the value depends on the field. The various field + types are:</para> + + <variablelist> + <varlistentry> + <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> + </varlistentry> + <varlistentry> + <term>string list</term> + <listitem> + <para>A sequence of strings, separated by commas. The sequence may + be empty.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>In addition, there are some fields with special syntax (e.g. package + 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> + </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> + </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> + </varlistentry> + + <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> + <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> + + <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> + + <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> + <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> + + <varlistentry> + <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> + <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> + + <varlistentry> + <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> + <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> + + <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> + + <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> + + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + + <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> + <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> + <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> + <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> + <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> + <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> + </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 + environment variables occurring in input package specifications. + So, if the <literal>mypkg</literal> was added to the package + database as follows: + </para> +<screen> + $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg +</screen> + + <para> + The occurrence of <literal>${installdir}</literal> is replaced + 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. + </para> + + <para>For examples of more package specifications, take a look + at the <literal>package.conf</literal> in your GHC + installation.</para> + +--> + + </sect2> + </sect1> + +<!-- Emacs stuff: + ;;; Local Variables: *** + ;;; mode: xml *** + ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** + ;;; End: *** + --> |