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>
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
%************************************************************************
%* *
+<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>
<tag>@-i<dirs>@</tag><nidx>-i<dirs> option</nidx> This flag
prepends a colon-separated list of @dirs@ to the ``import
directories'' list.
+See also Section <ref id="recomp"> for the significance of using
+relative and absolute pathnames in the @-i@ list.
<tag>@-i@</tag> resets the ``import directories'' list back to nothing.
%* *
%************************************************************************
+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 <file> option</nidx>
+
The interface output may be directed to another file
-@bar2/Wurble.iface@ with the option @-ohi bar2/Wurble.iface@<nidx>-ohi
-<file> 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.
@-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
file a list of the version numbers of everything it used when it last
compiled the file. If the source file's modification date is earlier
than the @.o@ file's date (i.e. the source hasn't changed since the
-file was last compiled), and you give GHC the @-recomp@<nidx>-recomp
-option</nidx> flag, then GHC will be clever. It compares the version
+file was last compiled), GHC will be clever. It compares the version
numbers on the things it needs this time with the version numbers on
the things it needed last time (gleaned from the interface file of the
module being compiled); if they are all the same it stops compiling
rather early in the process saying ``Compilation IS NOT required''.
What a beautiful sight!
-It's still an experimental feature (that's why @-recomp@ is off by
-default), so tell us if you think it doesn't work.
+GHC <em>only</em> keeps detailed dependency information for ``user'' modules,
+not for ``library'' modules. It distinguishes the two by a hack: a module
+whose @.hi@ file has an absolute path name is considered a library module,
+while a relative path name indicates a user module. So if you have a
+multi-directory application, use <em>relative</em> path names in your
+@-i@ path, to force GHC to record detailed dependency information.
+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 has a workshop paper about how all this is done. Ask
+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"
url="mailto:sansom@@dcs.gla.ac.uk">) if you want a copy.
import B
-newtype A = A Int
+newtype TA = MkTA Int
-f :: B -> A
-f (B x) = A x
+f :: TB -> TA
+f (MkTB x) = MkTA x
--------
module B where
import A
-data B = B !Int
+data TB = MkTB !Int
-g :: A -> B
-g (A x) = B x
+g :: TA -> TB
+g (MkTA x) = MkTB x
</verb></tscreen>
When compiling either module A and B, the compiler will try (in vain)
the following:
<tscreen><verb>
-__interface A 1 where
-__exports A A f;
-__import PrelBase Int;
-1 newtype A = A PrelBase.Int ;
-1 f :: A -> A ;
+__interface A 1 404 where
+__export A TA{MkTA} ;
+1 newtype TA = MkTA 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
+Notice that we only put the declaration for the newtype @TA@ in the
@hi-boot@ file, not the signature for @f@, since @f@ isn't used by
@B@.
+The number ``1'' after ``__interface A'' gives the version number of module A;
+it is incremented whenever anything in A's interface file changes. The ``404'' is
+the version number of the interface file <em>syntax</em>; we change it when
+we change the syntax of interface files so that you get a better error message when
+you try to read an old-format file with a new-format compiler.
+
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
which is a module internal to GHC's prelude. It's a pain, but that's
the way it is.
+If you want an hi-boot file to export a data type, but you don't want to give its constructors
+(because the constructors aren't used by the SOURCE-importing module), you can write simply:
+
+<tscreen><verb>
+__interface A 1 404 where
+__export A TA;
+1 data TA
+</verb></tscreen>
+
+(You must write all the type parameters, but leave out the '=' and everything that follows it.)
+
<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 files, is in the works.
+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).
+
%************************************************************************
%* *
<nidx>-Onot option</nidx>
<nidx>optimising, reset</nidx>
-This option will make GHC ``forget'' any -Oish options it has seen so
+This option will make GHC ``forget'' any @-O@ish options it has seen so
far. Sometimes useful; for example: @make all EXTRA_HC_OPTS=-Onot@.
<tag>@-Ofile <file>@:</tag>
something. When we want to go for broke, we tend to use @-O -fvia-C
-O2-for-C@ (and we go for lots of coffee breaks).
-The easiest way to see what @-O@ (etc) ``really mean'' is to run with
+The easiest way to see what @-O@ (etc.) ``really mean'' is to run with
@-v@, then stand back in amazement. Alternatively, just look at the
@HsC_minus<blah>@ lists in the @ghc@ driver script.
any running of the strictness analyser.
The options you are most likely to want to turn off are:
+<itemize>
+<item>
@-fno-strictness@<nidx>-fno-strictness option</nidx> (strictness
-analyser [because it is sometimes slow]),
+analyser, because it is sometimes slow),
+<item>
@-fno-specialise@<nidx>-fno-specialise option</nidx> (automatic
-specialisation of overloaded functions [because it makes your code
-bigger]) [US spelling also accepted], and
-@-fno-update-analysis@<nidx>-fno-update-analysis option</nidx> (update
-analyser, because it sometimes takes a <em>long</em> time). This one
-is only enabled with -O2 anyway.
+specialisation of overloaded functions, because it can make your code
+bigger) (US spelling also accepted), and
+<item>
+@-fno-cpr-analyse@<nidx>-fno-cpr-analyse option</nidx> switches off the CPR (constructed product
+result) analyser.
+</itemize>
Should you wish to turn individual flags <em>on</em>, you are advised
to use the @-Ofile@ option, described above. Because the order in
more critical one; it's what determines how eager GHC is about
expanding unfoldings.
+<tag>@-funbox-strict-fields@:</tag>
+<nidx>-funbox-strict-fields option</nidx>
+<nidx>strict constructor fields</nidx>
+<nidx>constructor fields, strict</nidx>
+
+This option causes all constructor fields which are marked strict
+(i.e. ``!'') to be unboxed or unpacked if possible. For example:
+
+<tscreen><verb>
+data T = T !Float !Float
+</verb></tscreen>
+
+will create a constructor @T@ containing two unboxed floats if the
+@-funbox-strict-fields@ flag is given. This may not always be an
+optimisation: if the @T@ constructor is scrutinised and the floats
+passed to a non-strict function for example, they will have to be
+reboxed (this is done automatically by the compiler).
+
+This option should only be used in conjunction with @-O@, in order to
+expose unfoldings to the compiler so the reboxing can be removed as
+often as possible. For example:
+
+<tscreen><verb>
+f :: T -> Float
+f (T f1 f2) = f1 + f2
+</verb></tscreen>
+
+The compiler will avoid reboxing @f1@ and @f2@ by inlining @+@ on
+floats, but only when @-O@ is on.
+
+Any single-constructor data is eligible for unpacking; for example
+
+<tscreen><verb>
+data T = T !(Int,Int)
+</verb></tscreen>
+
+will store the two @Int@s directly in the @T@ constructor, by flattening
+the pair. Multi-level unpacking is also supported:
+
+<tscreen><verb>
+data T = T !S
+data S = S !Int !Int
+</verb></tscreen>
+
+will store two unboxed @Int#@s directly in the @T@ constructor.
+
<tag>@-fsemi-tagging@:</tag>
This option (which <em>does not work</em> with the native-code generator)
tells the compiler to add extra code to test for already-evaluated
the usual C way.
</descrip>
-The @ghc@ driver pre-defines several macros:
+The @ghc@ driver pre-defines several macros when processing Haskell
+source code (@.hs@ or @.lhs@ files):
+
<descrip>
+<tag>@__HASKELL98__@:</tag>
+<nidx>__HASKELL98__</nidx>
+If defined, this means that GHC supports the language defined by the
+Haskell 98 report.
+
+<tag>@__HASKELL__=98@:</tag>
+<nidx>__HASKELL__</nidx>
+In GHC 4.04 and later, the @__HASKELL__@ macro is defined as having
+the value @98@.
+
<tag>@__HASKELL1__@:</tag>
<nidx>__HASKELL1__ macro</nidx>
-If defined to <em/n/, that means GHC supports the
-Haskell language defined in the Haskell report version <em/1.n/.
-Currently 4.
-
-NB. This macro is <em/only/ set when pre-processing Haskell source
-(ie. @.hs@ or @.lhs@ files).
+If defined to <em/n/, that means GHC supports the Haskell language
+defined in the Haskell report version <em/1.n/. Currently 5. This
+macro is deprecated, and will probably disappear in future versions.
<tag>@__GLASGOW_HASKELL__@:</tag>
<nidx>__GLASGOW_HASKELL__ macro</nidx>
for a parallel machine and the others weren't.) You may turn off this
check with @-no-link-chk@. You can turn it (back) on with
@-link-chk@ (the default).
+
+<tag><tt>-no-hs-main</tt>:</tag>
+<nidx>-no-hs-main option</nidx>
+<nidx>linking Haskell libraries with foreign code</nidx>
+
+In the event you want to include ghc-compiled code as part of another
+(non-Haskell) program, the RTS will not be supplying its definition of
+<tt/main()/ at link-time, you will have to. To signal that to the
+driver script when linking, use <tt/-no-hs-main/.
+
+Notice that since the command-line passed to the linker is rather
+involved, you probably want to use the ghc driver script to do the
+final link of your `mixed-language' application. This is not a
+requirement though, just try linking once with <tt/-v/ on to see what
+options the driver passes through to the linker.
+
</descrip>
%************************************************************************
%************************************************************************
%* *
-<sect2>Potential problems with Concurrent Haskell
-<label id="concurrent-problems">
-<p>
-<nidx>Concurrent Haskell problems</nidx>
-<nidx>problems, Concurrent Haskell</nidx>
-%* *
-%************************************************************************
-
-The previous implementation of Concurrent Haskell in GHC had problems
-with using signals handlers in concurrent programs. The current
-system, however, provides thread-safe signal handling (see Section
-<ref name="Signal Handling" id="signals">).
-
-%************************************************************************
-%* *
<sect1>Using Parallel Haskell
<p>
<nidx>Parallel Haskell---use</nidx>
projects / ghc-hetmet.git / blobdiff