From 8f320598066b0b22e6a1d8f485b5ace7f87578fa Mon Sep 17 00:00:00 2001
From: simonmar <unknown>
Date: Mon, 12 Jun 2000 11:41:00 +0000
Subject: [PATCH] [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.
---
ghc/docs/users_guide/using.sgml | 241 +++++++++++++++++++++++-------
ghc/docs/users_guide/utils.sgml | 250 +-------------------------------
2 files changed, 190 insertions(+), 301 deletions(-)
diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml
index 4819a99337a4..e3f63e9d7cc5 100644
--- a/ghc/docs/users_guide/using.sgml
+++ b/ghc/docs/users_guide/using.sgml
@@ -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—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_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</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># 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>-syslib</Option> option is used, dependencies will
+ also be generated on the library's interfaces.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</Sect2>
diff --git a/ghc/docs/users_guide/utils.sgml b/ghc/docs/users_guide/utils.sgml
index 4bd99a11911f..67547c37d4dd 100644
--- a/ghc/docs/users_guide/utils.sgml
+++ b/ghc/docs/users_guide/utils.sgml
@@ -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># 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>, <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<blah></Option></Term>
-<ListItem>
-<Para>
-A cpp <Option>#define</Option>; usual meaning.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-i<dirs></Option></Term>
-<ListItem>
-<Para>
-Add <Filename><dirs></Filename> (colon-separated) to list of directories
-to search for "import"ed modules.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-I<dir></Option></Term>
-<ListItem>
-<Para>
-Add <Filename><dir></Filename> to list of directories to search for
-.h files (i.e., usual meaning).
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-syslib <blah></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 <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>-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>
--
GitLab