<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 <blah> option</nidx> option.
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:
<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>
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>
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>
It has a builtin list of directories (notably including @.@) where
it looks.
-The @-i<dirs>@ option<nidx>-i<dirs> option</nidx> prepends a
-colon-separated list of @dirs@ to the ``import directories'' list.
+<descrip>
+
+<tag>@-i<dirs>@</tag><nidx>-i<dirs> 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 <lib> 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 <lib> option</nidx>
-option (for example). The right interface files should then be
-available.
+<tag>@-I<dir>@</tag>
+<nidx>-I<dir> 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<dir> 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>
%************************************************************************
%* *
<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.
%************************************************************************
%* *
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:
%************************************************************************
%* *
+<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>
projects / ghc-hetmet.git / blobdiff