Skip to content
Snippets Groups Projects
Commit 8f320598 authored by Simon Marlow's avatar Simon Marlow
Browse files

[project @ 2000-06-12 11:41:00 by simonmar] 

Update docs on mkdependHS: it isn't a separate utility, so document it
under "Using GHC".

Also update section on Happy.
parent 8ab22d1d
No related merge requests found
Hide whitespace changes
Inline Side-by-side
ghc/docs/users_guide/using.sgml
+ 188
− 53
View file @ 8f320598
......@@ -1147,65 +1147,200 @@ a rule to do so; one of the preceding suffix rules does the job
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&mdash;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><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&lowbar;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 &ldquo;everything's up-to-date.&rdquo;
</Para>
</ListItem>
<ListItem>
<Para>
This scheme will work with mutually-recursive modules but,
again, it may take multiple iterations to &ldquo;settle.&rdquo;
</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&lowbar;pgm</Command>. <Command>GHC</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>mkdependHS</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>mkdependHS</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</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>&num; DO NOT DELETE: Beginning of Haskell
dependencies</Literal>" and "<Literal>&num; 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 &lt;osuf&gt;</option></term>
<listitem>
<para>Use <Filename>.&lt;osuf&gt;</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 &lt;suf&gt;</option></term>
<listitem>
<para>Make extra dependencies that declare that files with
suffix
<Filename>.&lt;suf&gt;&lowbar;&lt;osuf&gt;</Filename>
depend on interface files with suffix
<Filename>.&lt;suf&gt;&lowbar;hi</Filename>, or (for
<Literal>&lcub;-&num; SOURCE &num;-&rcub;</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&lowbar;hc</Filename> on
<Filename>.a&lowbar;hi</Filename>, and
<Filename>.b&lowbar;hc</Filename> on
<Filename>.b&lowbar;hi</Filename>. (Useful in conjunction
with NoFib "ways".)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--exclude-module=&lt;file&gt;</option></term>
<listitem>
<para>Regard <Filename>&lt;file&gt;</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=&lt;dirs&gt;</option></term>
<listitem>
<para>Regard the colon-separated list of directories
<Filename>&lt;dirs&gt;</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=&lt;file&gt;</option></term>
<listitem>
<para>Regard <Filename>&lt;file&gt;</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>-syslib</Option> option is used, dependencies will
also be generated on the library's interfaces.</para>
</listitem>
</varlistentry>
</variablelist>
</Sect2>
......
ghc/docs/users_guide/utils.sgml
+ 2
− 248
View file @ 8f320598
......@@ -9,252 +9,6 @@ This section describes other program(s) which we distribute, that help
with the Great Haskell Programming Task.
</Para>
<Sect1 id="mkdependHS">
<Title>Makefile dependencies in Haskell: using <Command>mkdependHS</Command>
</Title>
<Para>
<IndexTerm><Primary>mkdependHS</Primary></IndexTerm>
<IndexTerm><Primary>Makefile dependencies</Primary></IndexTerm>
<IndexTerm><Primary>dependencies in Makefiles</Primary></IndexTerm>
</Para>
<Para>
You run <Command>mkdependHS</Command> like this:
<Screen>
mkdependHS [mkdependHS options] [-- GHC options --] srcfile1 [srcfile2 ...]
</Screen>
or
<Screen>
ghc -M [mkdependHS options(prefix with -optdep)] [ GHC options ] srcfile1 [srcfile2 ...]
</Screen>
To see <Command>mkdependHS</Command>'s command-line flags, give it a duff flag,
e.g., <Command>mkdependHS -help</Command>.
</Para>
<Para>
In general, if module <Literal>A</Literal> contains the line
<ProgramListing>
import B ...blah...
</ProgramListing>
then <Command>mkdependHS</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>mkdependHS</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>mkdependHS</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>&num; DO NOT DELETE: Beginning of Haskell dependencies</Literal>" and
"<Literal>&num; DO NOT DELETE: End of Haskell dependencies</Literal>". If these lines
already exist in the <Filename>makefile</Filename>, <Command>mkdependHS</Command> deletes the old
dependencies first.
</Para>
<Para>
<Command>mkdependHS</Command> takes GHC options between <Literal>--</Literal> brackets.
It understands the following ones. Any options between <Literal>--</Literal> brackets
that it doesn't understand are simply ignored; this way you can feed your
Makefile's standard GHC options to <Command>mkdependHS</Command> un-filtered.
<VariableList>
<VarListEntry>
<Term><Option>-cpp</Option></Term>
<ListItem>
<Para>
Run the C pre-processor over the input files. The
default is not to.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-D&lt;blah&gt;</Option></Term>
<ListItem>
<Para>
A cpp <Option>&num;define</Option>; usual meaning.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-i&lt;dirs&gt;</Option></Term>
<ListItem>
<Para>
Add <Filename>&lt;dirs&gt;</Filename> (colon-separated) to list of directories
to search for "import"ed modules.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-I&lt;dir&gt;</Option></Term>
<ListItem>
<Para>
Add <Filename>&lt;dir&gt;</Filename> to list of directories to search for
.h files (i.e., usual meaning).
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-syslib &lt;blah&gt;</Option></Term>
<ListItem>
<Para>
This program uses this GHC system library; take
appropriate action (e.g., recognise when they are
"import"ing a module from that library).
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
<Para>
Here are the <Command>mkdependHS</Command>-specific options (not between <Literal>--</Literal>'s):
<VariableList>
<VarListEntry>
<Term><Option>-v</Option></Term>
<ListItem>
<Para>
Be verbose.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-v -v</Option></Term>
<ListItem>
<Para>
Be very verbose.
</Para>
</ListItem>
</VarListEntry>
<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 &lt;osuf&gt;</Option></Term>
<ListItem>
<Para>
Use <Filename>.&lt;osuf&gt;</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 &lt;suf&gt;</Option></Term>
<ListItem>
<Para>
Make extra dependencies that declare that files with
suffix <Filename>.&lt;suf&gt;&lowbar;&lt;osuf&gt;</Filename> depend on interface files with suffix <Filename>.&lt;suf&gt;&lowbar;hi</Filename>, or
(for <Literal>&lcub;-&num; SOURCE &num;-&rcub;</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&lowbar;hc</Filename> on <Filename>.a&lowbar;hi</Filename>, and <Filename>.b&lowbar;hc</Filename> on <Filename>.b&lowbar;hi</Filename>.
(Useful in conjunction with NoFib "ways".)
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>--exclude-module=&lt;file&gt;</Option></Term>
<ListItem>
<Para>
Regard <Filename>&lt;file&gt;</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=&lt;dirs&gt;</Option></Term>
<ListItem>
<Para>
Regard the colon-separated list of directories <Filename>&lt;dirs&gt;</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=&lt;file&gt;</Option></Term>
<ListItem>
<Para>
Regard <Filename>&lt;file&gt;</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>-syslib</Option> option is used, dependencies will also be
generated on the library's interfaces.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
</Sect1>
<Sect1 id="hstags">
<Title>Emacs `TAGS' for Haskell: <Command>hstags</Command>
</Title>
......@@ -332,8 +86,8 @@ is to Haskell what <Command>Yacc</Command> is to C.
</Para>
<Para>
You can get <Command>happy</Command> by FTP from <Literal>ftp.dcs.gla.ac.uk</Literal> in
<Filename>pub/haskell/happy</Filename>, the file <Filename>happy-1.5-src.tar.gz</Filename>.
You can get <Command>happy</Command> from <ulink
url="http://www.haskell.org/happy/">the Happy Homepage</ulink>.
</Para>
<Para>
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment