<IndexTerm><Primary>separate compilation</Primary></IndexTerm>
<IndexTerm><Primary>recompilation checker</Primary></IndexTerm>
<IndexTerm><Primary>make and recompilation</Primary></IndexTerm>
-</Para>
-
-<Para>
This section describes how GHC supports separate compilation.
</Para>
</VarListEntry>
<VarListEntry>
-<Term><Option>-syslib <lib></Option></Term>
+<Term><Option>-package <lib></Option></Term>
<ListItem>
<Para>
-<IndexTerm><Primary>-syslib <lib> option</Primary></IndexTerm>
+<IndexTerm><Primary>-package <lib> option</Primary></IndexTerm>
If you are using a system-supplied non-Prelude library (e.g., the
-POSIX library), just use a <Option>-syslib posix</Option> option (for
+POSIX library), just use a <Option>-package posix</Option> option (for
example). The right interface files should then be available. The
accompanying HsLibs document lists the libraries available by this
mechanism.
<IndexTerm><Primary><option>-recomp</option> option</Primary></IndexTerm>
<ListItem>
<Para>
-Turn on recompilation checking. This will stop compilation early,
-leaving an existing <filename>.o</filename> file in place, if it can
-be determined that the module does not need to be recompiled.
+(On by default) Turn on recompilation checking. This will stop
+compilation early, leaving an existing <filename>.o</filename> file in
+place, if it can be determined that the module does not need to be
+recompiled.
+</Para>
+</ListItem>
+</VarListEntry>
+<VarListEntry>
+<Term><Option>-no-recomp</Option></Term>
+<IndexTerm><Primary><option>-recomp</option> option</Primary></IndexTerm>
+<ListItem>
+<Para>
+Turn off recompilation checking.
</Para>
</ListItem>
</VarListEntry>
</Para>
<Para>
-GHC <Emphasis>only</Emphasis> keeps detailed dependency information
-for “user” modules, not for “library” modules.
-It distinguishes the two by a hack: a module whose
-<Filename>.hi</Filename> file has an absolute path name is considered
-a library module, while a relative path name indicates a user module.
-So if you have a multi-directory application, use
-<Emphasis>relative</Emphasis> path names in your <Option>-i</Option>
-path, to force GHC to record detailed dependency information. Use
-absolute path names only for directories containing slowly-changing
-library modules.
+Patrick Sansom had a workshop paper about how all this is done (though
+the details have changed quite a bit). <ULink URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a copy.
</Para>
+<Sect3 id="packages">
+<Title>Packages</Title>
+
<Para>
-A path is considered “absolute” if it starts with
-“<Filename>/</Filename>”, or
-“<Filename>A:/</Filename>”, or
-“<Filename>A:\</Filename>” (or
-“<Filename>B:/</Filename>”,
-“<Filename>B:\</Filename>” etc).
+<IndexTerm><Primary>packages</Primary></IndexTerm>
+To simplify organisation and compilation, GHC keeps libraries in <Emphasis>packages</Emphasis>. Packages are also compiled into single libraries on Unix, and DLLs on Windows. The term ``package'' can be used pretty much synonymously with ``library'', except that an application also forms a package, the Main package.
</Para>
+<ItemizedList>
+<ListItem>
<Para>
-Patrick Sansom had a workshop paper about how all this is done (though
-the details have changed quite a bit). <ULink URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a copy.
+A package is a group of modules. It may span many directories, or many packages may exist in a single directory. Packages may not be mutually recursive.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+A package has a name (e.g. <Filename>std</Filename>)
</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+Each package is built into a single library (Unix; e.g. <Filename>libHSfoo.a</Filename>), or a single DLL (Windows; e.g. <Filename>HSfoo.dll</Filename>)
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+The <Option>-package-name foo</Option> flag tells GHC that the module being compiled is destined for package <Filename>foo</Filename>. If this is omitted, the default package, <Filename>Main</Filename>, is assumed.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+The <Option>-package foo</Option> flag tells GHC to make available modules
+from package <Filename>foo</Filename>. It replaces <Option>-syslib foo</Option>, which is now deprecated.
+</Para>
+</ListItem>
+
+<ListItem>
+<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>
+All of this tidies up the Prelude enormously. The Prelude and
+Standard Libraries are built into a single package called <Filename>std</Filename>. (This
+is a change; the library is now called <Filename>libHSstd.a</Filename> instead of <Filename>libHS.a</Filename>).
+</Para>
+
+<Para>
+It is worth noting that on Windows, because each package is built as a DLL, and 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. This is not normally the case on most Unices.
+</Para>
+
+</Sect3>
</Sect2>
+
<Sect2 id="using-make">
<Title>Using <Command>make</Command>
</Title>
</Para>
<Para>
-It is reasonably straightforward to set up a <Filename>Makefile</Filename> to use with
-GHC, assuming you name your source files the same as your modules.
+It is reasonably straightforward to set up a <Filename>Makefile</Filename> to use with GHC, assuming you name your source files the same as your modules.
Thus:
</Para>
SRCS = Main.lhs Foo.lhs Bar.lhs
OBJS = Main.o Foo.o Bar.o
-.SUFFIXES : .o .hi .lhs .hc .s
+.SUFFIXES : .o .hs .hi .lhs .hc .s
cool_pgm : $(OBJS)
rm $@
nicely.
</Para>
-<Para>
-Putting inter-dependencies of the form <Literal>Foo.o : Bar.hi</Literal> into your
-<Filename>Makefile</Filename> by hand is rather error-prone. Don't worry—never fear,
-<Command>mkdependHS</Command> is here! (and is distributed as part of GHC) Add the
-following to your <Filename>Makefile</Filename>:
-</Para>
+ </sect2>
-<Para>
+ <sect2 id="sec-makefile-dependencies">
+ <title>Dependency generation</title>
+ <indexterm><primary>dependencies in Makefiles</primary></indexterm>
+ <indexterm><primary>Makefile dependencies</primary></indexterm>
+
+ <para>Putting inter-dependencies of the form <Literal>Foo.o :
+ Bar.hi</Literal> into your <Filename>Makefile</Filename> by hand
+ is rather error-prone. Don't worry, GHC has support for
+ automatically generating the required dependencies. Add the
+ following to your <Filename>Makefile</Filename>:</para>
<ProgramListing>
depend :
- mkdependHS -- $(HC_OPTS) -- $(SRCS)
+ ghc -M $(HC_OPTS) $(SRCS)
</ProgramListing>
-</Para>
-
-<Para>
-Now, before you start compiling, and any time you change the <Literal>imports</Literal>
-in your program, do <Command>make depend</Command> before you do <Command>make cool_pgm</Command>.
-<Command>mkdependHS</Command> will append the needed dependencies to your <Filename>Makefile</Filename>.
-<Command>mkdependHS</Command> is fully described in <XRef LinkEnd="mkdependHS">.
-</Para>
-
-<Para>
-A few caveats about this simple scheme:
-</Para>
-
-<Para>
-
-<ItemizedList>
-<ListItem>
-
-<Para>
- You may need to compile some modules explicitly to create their
-interfaces in the first place (e.g., <Command>make Bar.o</Command> to create <Filename>Bar.hi</Filename>).
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- You may have to type <Command>make</Command> more than once for the dependencies
-to have full effect. However, a <Command>make</Command> run that does nothing
-<Emphasis>does</Emphasis> mean “everything's up-to-date.”
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- This scheme will work with mutually-recursive modules but,
-again, it may take multiple iterations to “settle.”
-
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
+ <para>Now, before you start compiling, and any time you change
+ the <Literal>imports</Literal> in your program, do <Command>make
+ depend</Command> before you do <Command>make
+ cool_pgm</Command>. <Command>ghc -M</Command> will append
+ the needed dependencies to your
+ <Filename>Makefile</Filename>.</Para>
+
+ <para>In general, if module <Literal>A</Literal> contains the
+ line
+
+<programlisting>
+import B ...blah...
+</programlisting>
+
+ then <command>ghc -M</command> will generate a dependency
+ line of the form:
+
+<programlisting>
+A.o : B.hi
+</programlisting>
+
+ If module <literal>A</literal> contains the line
+
+<programlisting>
+import {-# SOURCE #-} B ...blah...
+</programlisting>
+
+ then <command>ghc -M</command> will generate a dependency
+ line of the form:
+
+<programlisting>
+A.o : B.hi-boot
+</programlisting>
+
+ (See <xref linkend="hi-files"> for details of interface files.)
+ If <literal>A</literal> imports multiple modules, then there
+ will be multiple lines with <filename>A.o</filename> as the
+ target.</para>
+
+ <para>By default, <Command>ghc -M</Command> generates all the
+ dependencies, and then concatenates them onto the end of
+ <Filename>makefile</Filename> (or <Filename>Makefile</Filename>
+ if <Filename>makefile</Filename> doesn't exist) bracketed by the
+ lines "<Literal># DO NOT DELETE: Beginning of Haskell
+ dependencies</Literal>" and "<Literal># DO NOT DELETE: End
+ of Haskell dependencies</Literal>". If these lines already
+ exist in the <Filename>makefile</Filename>, then the old
+ dependencies are deleted first.</para>
+
+ <para>Internally, GHC uses a script to generate the
+ dependencies, called <command>mkdependHS</command>. This script
+ has some options of its own, which you might find useful.
+ Options can be passed directly to <command>mkdependHS</command>
+ with GHC's <literal>-optdep</literal> option. For example, to
+ generate the dependencies into a file called
+ <literal>.depend</literal> instead of
+ <literal>Makefile</literal>:</para>
+
+<screen>
+ghc -M -optdep-f optdep.depend ...
+</screen>
+
+ <para>The full list of options accepted by
+ <command>mkdependHS</command> is:</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-w</option></term>
+ <listitem>
+ <para>Turn off warnings about interface file shadowing.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-f blah</option></term>
+ <listitem>
+ <para>Use <Filename>blah</Filename> as the makefile,
+ rather than <Filename>makefile</Filename> or
+ <Filename>Makefile</Filename>. If
+ <Filename>blah</Filename> doesn't exist,
+ <Command>mkdependHS</Command> creates it. We often use
+ <Option>-f .depend</Option> to put the dependencies in
+ <Filename>.depend</Filename> and then
+ <Command>include</Command> the file
+ <Filename>.depend</Filename> into
+ <Filename>Makefile</Filename>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-o <osuf></option></term>
+ <listitem>
+ <para>Use <Filename>.<osuf></Filename> as the
+ "target file" suffix ( default: <Literal>o</Literal>).
+ Multiple <Option>-o</Option> flags are permitted (GHC2.05
+ onwards). Thus "<Option>-o hc -o o</Option>" will
+ generate dependencies for <Filename>.hc</Filename> and
+ <Filename>.o</Filename> files.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-s <suf></option></term>
+ <listitem>
+ <para>Make extra dependencies that declare that files with
+ suffix
+ <Filename>.<suf>_<osuf></Filename>
+ depend on interface files with suffix
+ <Filename>.<suf>_hi</Filename>, or (for
+ <Literal>{-# SOURCE #-}</Literal>
+ imports) on <Filename>.hi-boot</Filename>. Multiple
+ <Option>-s</Option> flags are permitted. For example,
+ <Option>-o hc -s a -s b</Option> will make dependencies
+ for <Filename>.hc</Filename> on <Filename>.hi</Filename>,
+ <Filename>.a_hc</Filename> on
+ <Filename>.a_hi</Filename>, and
+ <Filename>.b_hc</Filename> on
+ <Filename>.b_hi</Filename>. (Useful in conjunction
+ with NoFib "ways".)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--exclude-module=<file></option></term>
+ <listitem>
+ <para>Regard <Filename><file></Filename> as
+ "stable"; i.e., exclude it from having dependencies on
+ it.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-x</option></term>
+ <listitem>
+ <para>same as <option>--exclude-module</option></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--exclude-directory=<dirs></option></term>
+ <listitem>
+ <para>Regard the colon-separated list of directories
+ <Filename><dirs></Filename> as containing stable,
+ don't generate any dependencies on modules therein.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-xdirs</option></term>
+ <listitem>
+ <para>same as <Option>--exclude-directory</Option>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--include-module=<file></option></term>
+ <listitem>
+ <para>Regard <Filename><file></Filename> as not
+ "stable"; i.e., generate dependencies on it (if any). This
+ option is normally used in conjunction with the
+ <Option>--exclude-directory</Option> option.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--include-prelude</option></term>
+ <listitem>
+ <para>Regard prelude libraries as unstable, i.e., generate
+ dependencies on the prelude modules used (including
+ <Literal>Prelude</Literal>). This option is normally only
+ used by the various system libraries. If a
+ <Option>-package</Option> option is used, dependencies will
+ also be generated on the library's interfaces.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</Sect2>
<VarListEntry>
<Term>No <Option>-O*</Option>-type option specified:</Term>
+<IndexTerm><Primary>-O* not specified</Primary></IndexTerm>
<ListItem>
<Para>
-<IndexTerm><Primary>-O* not specified</Primary></IndexTerm>
This is taken to mean: “Please compile quickly; I'm not over-bothered
about compiled-code quality.” So, for example: <Command>ghc -c Foo.hs</Command>
</Para>
</VarListEntry>
<VarListEntry>
<Term><Option>-O</Option> or <Option>-O1</Option>:</Term>
-<ListItem>
-<Para>
<IndexTerm><Primary>-O option</Primary></IndexTerm>
<IndexTerm><Primary>-O1 option</Primary></IndexTerm>
-<IndexTerm><Primary>optimise normally</Primary></IndexTerm>
-Means: “Generate good-quality code without taking too long about it.”
-Thus, for example: <Command>ghc -c -O Main.lhs</Command>
+<IndexTerm><Primary>optimise</Primary><secondary>normally</secondary></IndexTerm>
+<ListItem>
+<Para>
+Means: “Generate good-quality code without taking too long about
+it.” Thus, for example: <Command>ghc -c -O Main.lhs</Command>
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-O2</Option>:</Term>
+<IndexTerm><Primary>-O2 option</Primary></IndexTerm>
+<IndexTerm><Primary>optimise</Primary><secondary>aggressively</secondary></IndexTerm>
<ListItem>
<Para>
-<IndexTerm><Primary>-O2 option</Primary></IndexTerm>
-<IndexTerm><Primary>optimise aggressively</Primary></IndexTerm>
Means: “Apply every non-dangerous optimisation, even if it means
significantly longer compile times.”
</Para>
</VarListEntry>
<VarListEntry>
<Term><Option>-O2-for-C</Option>:</Term>
-<ListItem>
-<Para>
<IndexTerm><Primary>-O2-for-C option</Primary></IndexTerm>
<IndexTerm><Primary>gcc, invoking with -O2</Primary></IndexTerm>
-</Para>
-
+<ListItem>
<Para>
Says to run GCC with <Option>-O2</Option>, which may be worth a few percent in
execution speed. Don't forget <Option>-fvia-C</Option>, lest you use the native-code
</VarListEntry>
<VarListEntry>
<Term><Option>-Onot</Option>:</Term>
-<ListItem>
-<Para>
<IndexTerm><Primary>-Onot option</Primary></IndexTerm>
<IndexTerm><Primary>optimising, reset</Primary></IndexTerm>
-</Para>
-
+<ListItem>
<Para>
-This option will make GHC “forget” any <Option>-O</Option>ish options it has seen so
-far. Sometimes useful; for example: <Command>make all EXTRA_HC_OPTS=-Onot</Command>.
+This option will make GHC “forget” any
+<Option>-O</Option>ish options it has seen so far. Sometimes useful;
+for example: <Command>make all
+EXTRA_HC_OPTS=-Onot</Command>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-Ofile <file></Option>:</Term>
-<ListItem>
-<Para>
<IndexTerm><Primary>-Ofile <file> option</Primary></IndexTerm>
<IndexTerm><Primary>optimising, customised</Primary></IndexTerm>
-</Para>
-
+<ListItem>
<Para>
-For those who need <Emphasis>absolute</Emphasis> control over <Emphasis>exactly</Emphasis>
-what options are used (e.g., compiler writers, sometimes :-), a list
-of options can be put in a file and then slurped in with <Option>-Ofile</Option>.
+For those who need <Emphasis>absolute</Emphasis> control over
+<Emphasis>exactly</Emphasis> what options are used (e.g., compiler
+writers, sometimes :-), a list of options can be put in a file and
+then slurped in with <Option>-Ofile</Option>.
</Para>
<Para>
-In that file, comments are of the <Literal>#</Literal>-to-end-of-line variety; blank
-lines and most whitespace is ignored.
+In that file, comments are of the
+<Literal>#</Literal>-to-end-of-line variety; blank lines and most
+whitespace is ignored.
</Para>
<Para>
</Para>
<Para>
-Compile via C, and don't use the native-code generator. (There are
-many cases when GHC does this on its own.) You might pick up a little
-bit of speed by compiling via C. If you use <Function>_ccall_gc_</Function>s or
-<Function>_casm_</Function>s, you probably <Emphasis>have</Emphasis> to use <Option>-fvia-C</Option>.
+Compile via C, and don't use the native-code generator. (There are many
+cases when GHC does this on its own.) You might pick up a little bit of
+speed by compiling via C (e.g. for floating-point intensive code on Intel).
+If you use <Function>_casm_</Function>s (which are utterly
+deprecated), you probably <Emphasis>have</Emphasis> to use
+<Option>-fvia-C</Option>.
</Para>
<Para>
</Para>
<Para>
-If you are compiling with lots of <Literal>ccalls</Literal>, etc., you may need to
+If you are compiling with lots of foreign calls, you may need to
tell the C compiler about some <Literal>#include</Literal> files. There is no real
pretty way to do this, but you can use this hack from the
command-line:
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Option>-syslib <name></Option>:</Term>
+<Term><Option>-package <name></Option>:</Term>
<ListItem>
<Para>
-<IndexTerm><Primary>-syslib <name> option</Primary></IndexTerm>
+<IndexTerm><Primary>-package <name> option</Primary></IndexTerm>
</Para>
<Para>
If you are using a Haskell “system library” (e.g., the POSIX
-library), just use the <Option>-syslib posix</Option> option, and the correct code
+library), just use the <Option>-package posix</Option> option, and the correct code
should be linked in.
</Para>
</ListItem>
</Sect1>
-<Sect1>
+<Sect1 id="sec-using-concurrent">
<Title>Using Concurrent Haskell</Title>
<Para>
GHC (as of version 4.00) supports Concurrent Haskell by default,
without requiring a special option or libraries compiled in a certain
way. To get access to the support libraries for Concurrent Haskell
-(i.e. <Literal>Concurrent</Literal> and friends), use the <Option>-syslib concurrent</Option> option.
+(i.e. <Literal>Concurrent</Literal> and friends), use the
+<Option>-package concurrent</Option> option.
</Para>
<Para>
Three RTS options are provided for modifying the behaviour of the
-threaded runtime system. See the descriptions of <Option>-C[<us>]</Option>, <Option>-q</Option>,
-and <Option>-t<num></Option> in <XRef LinkEnd="parallel-rts-opts">.
+threaded runtime system. See the descriptions of
+<Option>-C[<us>]</Option>, <Option>-q</Option>, and
+<Option>-t<num></Option> in <XRef LinkEnd="parallel-rts-opts">.
</Para>
<Para>
-Concurrent Haskell is described in more detail in <XRef LinkEnd="concurrent-and-parallel">.
+Concurrent Haskell is described in more detail in <XRef
+LinkEnd="sec-Concurrent">.
</Para>
</Sect1>
-<Sect1>
+<Sect1 id="sec-using-parallel">
<Title>Using Parallel Haskell</Title>
<Para>
<Para>
To compile a Haskell program for parallel execution under PVM, use the
-<Option>-parallel</Option> option,<IndexTerm><Primary>-parallel option</Primary></IndexTerm> both when compiling
-<Emphasis>and linking</Emphasis>. You will probably want to <Literal>import Parallel</Literal>
-into your Haskell modules.
+<Option>-parallel</Option> option,<IndexTerm><Primary>-parallel
+option</Primary></IndexTerm> both when compiling <Emphasis>and
+linking</Emphasis>. You will probably want to <Literal>import
+Parallel</Literal> into your Haskell modules.
</Para>
<Para>
-To run your parallel program, once PVM is going, just invoke it “as
-normal”. The main extra RTS option is <Option>-N<n></Option>, to say how many
-PVM “processors” your program to run on. (For more details of
-all relevant RTS options, please see <XRef LinkEnd="parallel-rts-opts">.)
+To run your parallel program, once PVM is going, just invoke it
+“as normal”. The main extra RTS option is
+<Option>-N<n></Option>, to say how many PVM
+“processors” your program to run on. (For more details of
+all relevant RTS options, please see <XRef
+LinkEnd="parallel-rts-opts">.)
</Para>
<Para>
&debug
</Chapter>
+
+<!-- Emacs stuff:
+ ;;; Local Variables: ***
+ ;;; mode: sgml ***
+ ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
+ ;;; End: ***
+ -->
projects / ghc-hetmet.git / blobdiff