X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fusing.vsgml;h=e6f6e9be56593f9001ecf819430177ec44afd740;hb=0e24544c6c180bce89fbf852f6421a7c4b58cab8;hp=254eb0d362785c95ef5871c20e67b9988adc7a3c;hpb=abdd55c9c4a2873c2f4b25b4ea54ca921bca4f5e;p=ghc-hetmet.git

diff --git a/ghc/docs/users_guide/using.vsgml b/ghc/docs/users_guide/using.vsgml
index 254eb0d..e6f6e9b 100644
--- a/ghc/docs/users_guide/using.vsgml
+++ b/ghc/docs/users_guide/using.vsgml
@@ -228,7 +228,7 @@ If you would like to look at the assembler output, toss in a
 <nidx>standard error, saving</nidx>
 
 Sometimes, you may cause GHC to be rather chatty on standard error;
-with @-fshow-import-specs@, for example.  You can instruct GHC to
+with @-dshow-rn-trace@, for example.  You can instruct GHC to
 <em>append</em> this output to a particular log file with a @-odump
 <blah>@<nidx>-odump &lt;blah&gt; option</nidx> option.
 
@@ -265,7 +265,7 @@ GHC has a number of options that select which types of non-fatal error
 messages, otherwise known as warnings, can be generated during
 compilation.  By default, you get a standard set of warnings which are
 generally likely to indicate bugs in your program.  These are:
-@-fwarn-overlpapping-patterns@, @-fwarn-duplicate-exports@, and
+@-fwarn-overlapping-patterns@, @-fwarn-duplicate-exports@, and
 @-fwarn-missing-methods@.  The following flags are simple ways to
 select standard ``packages'' of warnings:
 
@@ -284,8 +284,8 @@ Synonym for @-Wnot@.
 <tag>@-W@:</tag>
 <nidx>-W option</nidx>
 
-Provides the standard warnings plus @-fwarn-incomplete-patterns@
-and @-fwarn-unused-names@.
+Provides the standard warnings plus @-fwarn-incomplete-patterns@,
+@-fwarn-unused-imports@ and @-fwarn-unused-binds@.
 
 <tag>@-Wall@:</tag>
 <nidx>-Wall option</nidx>
@@ -313,6 +313,16 @@ into hard-to-find bugs, e.g., in the inadvertent cyclic definition
 Consequently, this option does <em>not</em> allow cyclic recursive
 definitions.
 
+<tag>@-fwarn-hi-shadowing@:</tag> 
+<nidx>-fwarn-hi-shadowing option</nidx>
+<nidx>interface files, shadowing</nidx>
+
+Warns you about shadowing of interface files along the supplied import path.
+For instance, assuming you invoke @ghc@ with the import path
+@-iutils:src@ and @Utils.hi@ exist in both the @utils@ and @src@
+directories, @-fwarn-hi-shadowing@ will warn you that @utils/Utils.hi@
+shadows @src/Utils.hi@.
+
 <tag>@-fwarn-overlapping-patterns@:</tag>
 <nidx>-fwarn-overlapping-patterns option</nidx>
 <nidx>overlapping patterns, warning</nidx>
@@ -353,12 +363,31 @@ This option is on by default, and warns you whenever an instance
 declaration is missing one or more methods, and the corresponding
 class declaration has no default declaration for them.
 
-<tag>@-fwarn-unused-names@:</tag>
-<nidx>-fwarn-unused-names option</nidx>
-<nidx>unused names, warning</nidx>
-<nidx>names, unused</nidx>
+<tag>@-fwarn-unused-imports@:</tag>
+<nidx>-fwarn-unused-imports option</nidx>
+<nidx>unused imports, warning</nidx>
+<nidx>imports, unused</nidx>
+
+Report any objects that are explicitly imported but never used.
+
+<tag>@-fwarn-unused-binds@:</tag>
+<nidx>-fwarn-unused-binds option</nidx>
+<nidx>unused binds, warning</nidx>
+<nidx>binds, unused</nidx>
+
+Report any function definitions (and local bindings) which are unused.
+For top-level functions, the warning is only given if the binding is
+not exported.
 
-Have the renamer report which locally defined names are not used/exported.
+<tag>@-fwarn-unused-matches@:</tag>
+<nidx>-fwarn-unused-matches option</nidx>
+<nidx>unused matches, warning</nidx>
+<nidx>matches, unused</nidx>
+
+Report all unused variables which arise from pattern matches,
+including patterns consisting of a single variable.  For instance @f x
+y = []@ would report @x@ and @y@ as unused.  To eliminate the warning,
+all unused variables can be replaced with wildcards.
 
 <tag>@-fwarn-duplicate-exports@:</tag>
 <nidx>-fwarn-duplicate-exports option</nidx>
@@ -457,26 +486,40 @@ In your program, you import a module @Foo@ by saying
 It has a builtin list of directories (notably including @.@) where
 it looks.
 
-The @-i<dirs>@ option<nidx>-i&lt;dirs&gt; option</nidx> prepends a
-colon-separated list of @dirs@ to the ``import directories'' list.
+<descrip>
+
+<tag>@-i<dirs>@</tag><nidx>-i&lt;dirs&gt; option</nidx> This flag
+prepends a colon-separated list of @dirs@ to the ``import
+directories'' list.
+
+<tag>@-i@</tag> resets the ``import directories'' list back to nothing.
+
+<tag>@-fno-implicit-prelude@</tag>
+<nidx>-fno-implicit-prelude option</nidx>
+GHC normally imports @Prelude.hi@ files for you.  If you'd rather it
+didn't, then give it a @-fno-implicit-prelude@ option.  You are
+unlikely to get very far without a Prelude, but, hey, it's a free
+country.
 
-A plain @-i@ resets the ``import directories'' list back to nothing.
+<tag>@-syslib <lib>@</tag>
+<nidx>-syslib &lt;lib&gt; option</nidx>
 
-GHC normally imports @Prelude.hi@ files for you.  If you'd rather
-it didn't, then give it a @-fno-implicit-prelude@
-option<nidx>-fno-implicit-prelude option</nidx>.  You are unlikely to get
-very far without a Prelude, but, hey, it's a free country.
+If you are using a system-supplied non-Prelude library (e.g., the
+POSIX library), just use a @-syslib posix@ option (for example).  The
+right interface files should then be available.  Section <ref
+name="The GHC Prelude and Libraries" id="ghc-prelude"> lists the
+libraries available by this mechanism.
 
-If you are using a system-supplied non-Prelude library (e.g., the HBC
-library), just use a @-syslib hbc@<nidx>-syslib &lt;lib&gt; option</nidx>
-option (for example).  The right interface files should then be
-available.
+<tag>@-I<dir>@</tag>
+<nidx>-I&lt;dir&gt; option</nidx>
 
 Once a Haskell module has been compiled to C (@.hc@ file), you may
-wish to specify where GHC tells the C compiler to look for @.h@
-files.  (Or, if you are using the @-cpp@ option<nidx>-cpp option</nidx>,
-where it tells the C pre-processor to look...)  For this purpose, use
-a @-I<dir>@<nidx>-I&lt;dir&gt; option</nidx> in the usual C-ish way.
+wish to specify where GHC tells the C compiler to look for @.h@ files.
+(Or, if you are using the @-cpp@ option<nidx>-cpp option</nidx>, where
+it tells the C pre-processor to look...)  For this purpose, use a @-I@
+option in the usual C-ish way.
+
+</descrip>
 
 %************************************************************************
 %*                                                                      *
@@ -523,8 +566,9 @@ turned off with @-fno-prune-tydecls@ and @-fno-prune-instdecls@.
 <nidx>-fno-prune-tydecls option</nidx><nidx>-fno-prune-instdecls
 option</nidx>
 
-See also Section <ref name="Linking and consistency-checking" id="options-linker">, which describes how the linker
-finds standard Haskell libraries.
+See also Section <ref name="Linking and consistency-checking"
+id="options-linker">, which describes how the linker finds standard
+Haskell libraries.
 
 %************************************************************************
 %*                                                                      *
@@ -638,19 +682,22 @@ a rule to do so; one of the preceding suffix rules does the job
 nicely.
 
 Putting inter-dependencies of the form @Foo.o : Bar.hi@ into your
-@Makefile@ by hand is rather error-prone.  Don't worry---never fear,
-@mkdependHS@ is here! (and is distributed as part of GHC) Add the
-following to your @Makefile@:
+@Makefile@ by hand is rather error-prone.  @ghc@ offers you a helping
+hand with it's @-M@ option. To automatically generate
+inter-dependencies, add the following to your @Makefile@:
 
 <tscreen><verb>
 depend :
-        mkdependHS -- $(HC_OPTS) -- $(SRCS)
+        $(HC) -M $(HC_OPTS) $(SRCS)
 </verb></tscreen>
 
 Now, before you start compiling, and any time you change the @imports@
 in your program, do @make depend@ before you do @make cool_pgm@.
-@mkdependHS@ will append the needed dependencies to your @Makefile@.
-@mkdependHS@ is fully describe in Section <ref name="Makefile
+@ghc -M@ will then append the needed dependencies to your @Makefile@.
+
+The dependencies are actually generated by another utility,
+@mkdependHS@, which @ghc -M@ just calls upon. @mkdependHS@ is
+distributed with GHC and is documented in Section <ref name="Makefile
 dependencies in Haskell: using mkdependHS" id="mkdependHS">.
 
 A few caveats about this simple scheme:
@@ -671,6 +718,90 @@ again, it may take multiple iterations to ``settle.''
 
 %************************************************************************
 %*                                                                      *
+<sect2>How to compile mutually recursive modules
+<label id="mutual-recursion">
+<p>
+<nidx>module system, recursion</nidx>
+<nidx>recursion, between modules</nidx>
+%*                                                                      *
+%************************************************************************
+
+Currently, the compiler does not have proper support for dealing with
+mutually recursive modules:
+
+<tscreen><verb>
+module A where
+
+import B
+
+newtype A = A Int
+
+f :: B -> A
+f (B x) = A x
+--------
+module B where
+
+import A
+
+data B = B !Int
+
+g :: A -> B
+g (A x) = B x
+</verb></tscreen>
+
+When compiling either module A and B, the compiler will try (in vain)
+to look for the interface file of the other. So, to get mutually
+recursive modules off the ground, you need to hand write an interface
+file for A or B, so as to break the loop.  These hand-written
+interface files are called @hi-boot@ files, and are placed in a file
+called @<module>.hi-boot@.  To import from an @hi-boot@ file instead
+of the standard @.hi@ file, use the following syntax in the importing module:
+<nidx>hi-boot files</nidx>
+<nidx>importing, hi-boot files</nidx>
+
+<tscreen> <verb>
+import {-# SOURCE #-} A
+</verb> </tscreen>
+
+The hand-written interface need only contain the bare minimum of
+information needed to get the bootstrapping process started.  For
+example, it doesn't need to contain declarations for <em/everything/
+that module @A@ exports, only the things required by the module that
+imports @A@ recursively.
+
+For the example at hand, the boot interface file for A would like the
+following:
+
+<tscreen><verb>
+_interface_ A 1
+_exports_
+A(A);
+_declarations_
+1 newtype A = A PrelBase.Int ;
+</verb></tscreen>
+
+The syntax is essentially the same as a normal @.hi@ file
+(unfortunately), but you can usually tailor an existing @.hi@ file to
+make a @.hi-boot@ file.
+
+Notice that we only put the declaration for the newtype @A@ in the
+@hi-boot@ file, not the signature for @f@, since @f@ isn't used by
+@B@.
+
+The number ``1'' at the beginning of a declaration is the <em>version
+number</em> of that declaration: for the purposes of @.hi-boot@ files
+these can all be set to 1.  All names must be fully qualified with the
+<em/original/ module that an object comes from: for example, the
+reference to @Int@ in the interface for @A@ comes from @PrelBase@,
+which is a module internal to GHC's prelude.  It's a pain, but that's
+the way it is.
+
+<bf>Note:</bf> This is all a temporary solution, a version of the
+compiler that handles mutually recursive properly without the manual
+construction of interface file, is in the works.
+
+%************************************************************************
+%*                                                                      *
 <sect1>Optimisation (code improvement)
 <label id="options-optimise">
 <p>