X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fusing.vsgml;h=88d404ad2822d4c5a05e7f337d5beda25fd483b9;hb=c7f8f1e62b555462f98c3f813440559116033a99;hp=8ef625551443153c59eee7e8e17cc9f6dddac62f;hpb=6d8504e2cc7c78390185c10a26416f2636e7a743;p=ghc-hetmet.git

diff --git a/ghc/docs/users_guide/using.vsgml b/ghc/docs/users_guide/using.vsgml
index 8ef6255..88d404a 100644
--- a/ghc/docs/users_guide/using.vsgml
+++ b/ghc/docs/users_guide/using.vsgml
@@ -359,6 +359,17 @@ 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-missing-fields@:</tag>
+<nidx>-fwarn-missing-fields option</nidx>
+<nidx>missing fields, warning</nidx>
+<nidx>fields, missing</nidx>
+
+This option is on by default, and warns you whenever the construction
+of a labelled field constructor isn't complete, missing initializers
+for one or more fields. While not an error (the missing fields are
+initialised with bottoms), it is often an indication of a programmer
+error.
+
 <tag>@-fwarn-unused-imports@:</tag>
 <nidx>-fwarn-unused-imports option</nidx>
 <nidx>unused imports, warning</nidx>
@@ -452,7 +463,10 @@ file</em> @A.hi@.  The interface file is not intended for human
 consumption, as you'll see if you take a look at one.  It's merely
 there to help the compiler compile other modules in the same program.
 
-NOTE: Having the name of the interface file follow the module name and
+NOTE: <em>The name of the interface file is derived from the name
+of the module, not from the name of the file containing the module</em>.
+This means that GHC knows what to look for when it sees <tt>import A</tt>
+in another module.  However, having the name of the interface file follow the module name and
 not the file name, means that working with tools such as @make(1)@
 become harder. @make@ implicitly assumes that any output files
 produced by processing a translation unit will have file names that
@@ -490,6 +504,26 @@ other unpleasant happenings.
 
 %************************************************************************
 %*                                                                      *
+<sect2>File names and module names
+<label id="files-and-modules">
+<p>
+%*                                                                      *
+%************************************************************************
+
+Typically, a module @Foo@ will be contained in a file called @Foo.hs@
+or @Foo.lhs@.  But GHC does not require that to be the case.  You can put a module
+named @Foo@ in a file named @SomethingElse@.  In this case, <em>GHC will still
+write an interface file @Foo.hi@</em>, but it will write an object fild
+@SomethingElse.o@.  Any module that imports @Foo@ will
+of course look for @Foo.hi@, and it will find it.
+
+A useful consequence is that you can have many files, @A.hs@, @B.hs@, etc, containing
+the module @Main@.  This is useful if you want to build distinct programs
+in the same directory.
+
+
+%************************************************************************
+%*                                                                      *
 <sect2>Finding interface files
 <label id="options-finding-imports">
 <p>
@@ -549,17 +583,31 @@ option in the usual C-ish way.
 %*                                                                      *
 %************************************************************************
 
+GHC supports some other more exotic command-line options related to interface files.
+Most programmers should never need to use any of them.
+
+<descrip>
+
+<tag>@-ohi@ <filename></tag> 
+<nidx>-ohi &lt;file&gt; option</nidx> 
+
 The interface output may be directed to another file
-@bar2/Wurble.iface@ with the option @-ohi bar2/Wurble.iface@<nidx>-ohi
-&lt;file&gt; option</nidx> (not recommended).
+@bar2/Wurble.iface@ with the option @-ohi bar2/Wurble.iface@
+(not recommended).
 
-To avoid generating an interface file at all, use a @-nohi@
-option.<nidx>-nohi option</nidx>
+<tag>@-nohi@</tag>
+<nidx>-nohi option</nidx>
 
+Don't generate an interface file at all.
+
+<tag>@-hi-diffs@, @-hi-diffs-with-usages@, @-keep-hi-diffs@</tag>
+<nidx>-hi-diffs option</nidx> 
+<nidx>-hi-diffs-with-usages option</nidx> 
+<nidx>-keep-hi-diffs option</nidx> 
 The compiler does not overwrite an existing @.hi@ interface file if
 the new one is byte-for-byte the same as the old one; this is friendly
 to @make@.  When an interface does change, it is often enlightening to
-be informed.  The @-hi-diffs@<nidx>-hi-diffs option</nidx> option will
+be informed.  The @-hi-diffs@ option will
 make @ghc@ run @diff@ on the old and new @.hi@ files. You can also
 record the difference in the interface file itself, the
 @-keep-hi-diffs@<nidx>-keep-hi-diffs</nidx> option takes care of that.
@@ -570,20 +618,24 @@ reported, you need to use the
 @-hi-diffs-with-usages@<nidx>-hi-diffs-with-usages option</nidx>
 option.
 
+<tag>@-fignore-interface-pragmas@</tag>
+<nidx>-fignore-interface-pragmas option</nidx>
+
 Interface files are normally jammed full of compiler-produced
 <em>pragmas</em>, which record arities, strictness info, etc.  If you
 think these pragmas are messing you up (or you are doing some kind of
 weird experiment), you can tell GHC to ignore them with the
-@-fignore-interface-pragmas@<nidx>-fignore-interface-pragmas
-option</nidx> option.
+@-fignore-interface-pragmas@ option.
 
+<tag>@-fno-prune-tydecls@</tag>
+<nidx>-fno-prune-tydecls option</nidx>
 When compiling without optimisations on, the compiler is extra-careful
-about not slurping in data constructors and instance declarations that
-it will not need. If you believe it is getting it wrong and not
-importing stuff which you think it should, this optimisation can be
-turned off with @-fno-prune-tydecls@ and @-fno-prune-instdecls@.
-<nidx>-fno-prune-tydecls option</nidx><nidx>-fno-prune-instdecls
-option</nidx>
+about not slurping in data constructors that it will not need. 
+The @-fno-prune-tydecls@ flag lets you turn this cleverness off; the reason
+is to allow us to measure the effect of the cleverness.   (In earlier versions
+of GHC there was a bug that meant you <em>had</em> to turn it off sometimes,
+but that is no longer true.)
+</descrip>
 
 See also Section <ref name="Linking and consistency-checking"
 id="options-linker">, which describes how the linker finds standard
@@ -632,6 +684,9 @@ multi-directory application, use <em>relative</em> path names in your
 Use absolute path names only for directories containing slowly-changing
 library modules.
 
+A path is considered ``absolute'' if it starts with ``@/@'', or
+``@A:/@'', or ``@A:\@'' (or ``@B:/@'', ``@B:\@'' etc).
+
 Patrick Sansom had a workshop paper about how all this is done (though
 the details have changed quite a bit).  Ask
 him (email: <htmlurl name="sansom@@dcs.gla.ac.uk"
@@ -839,6 +894,43 @@ construction of interface files, is (allegedly) in the works.
 
 %************************************************************************
 %*                                                                      *
+<sect1>Command line options in source files
+<label id="source-file-options">
+<p>
+<nidx>source-file options</nidx>
+%*                                                                      *
+%************************************************************************
+
+GHC expects its flags on the command line, but it is also possible
+to embed them in the Haskell module itself, using the  @OPTIONS@
+pragma <nidx>OPTIONS pragma</nidx>: 
+<tscreen><verb>
+  {-# OPTIONS -fglasgow-exts -fno-cpr-analyse #-}
+  module X where
+  
+  ...
+</verb></tscreen>
+@OPTIONS@ pragmas are only looked for at the top of your source
+files, upto the first (non-literate,non-empty) line not containing
+@OPTIONS@. Multiple @OPTIONS@ pragmas are recognised. Note
+that your command shell does not get to the source file options, they
+are just included literally in the array of command-line arguments
+the compiler driver maintains internally, so you'll be desperately
+disappointed if you try to @glob@ etc. inside @OPTIONS@.
+
+The contents of @OPTIONS@ are prepended to the command-line
+options, so you *do* have the ability to override @OPTIONS@ settings
+via the command line.
+
+It is not recommended to move all the contents of your Makefiles into
+your source files, but in some circumstances, the @OPTIONS@ pragma
+is the Right Thing. (If you use @-keep-hc-file-too@ and have @OPTIONS@
+flags in your module, the @OPTIONS@ will get put into the generated .hc
+file).
+
+
+%************************************************************************
+%*                                                                      *
 <sect1>Optimisation (code improvement)
 <label id="options-optimise">
 <p>