%************************************************************************
The basic task of the @ghc@ driver is to run each input file
-through the right phases (parsing, linking, etc.).
+through the right phases (compiling, linking, etc.).
The first phase to run is determined by the input-file suffix, and the
last phase is determined by a flag. If no relevant flag is present,
<nidx>standard error, saving</nidx>
Sometimes, you may cause GHC to be rather chatty on standard error;
-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.
+with @-v@, 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.
<sect2> Redirecting temporary files
<label id="temp-files">
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-overlapping-patterns@, @-fwarn-duplicate-exports@, and
+@-fwarn-overlpapping-patterns@, @-fwarn-duplicate-exports@, and
@-fwarn-missing-methods@. The following flags are simple ways to
select standard ``packages'' of warnings:
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>
<nidx>patterns, overlapping</nidx>
-By default, the compiler will warn you if a set of patterns are either
-incomplete (i.e., you're only matching on a subset of an algebraic
-data type's constructors), or overlapping, i.e.,
+By default, the compiler will warn you if a set of patterns are
+overlapping, i.e.,
<tscreen><verb>
f :: String -> Int
f [] = 0
f (_:xs) = 1
f "2" = 2
-
-g [] = 2
</verb></tscreen>
where the last pattern match in @f@ won't ever be reached, as the
<nidx>incomplete patterns, warning</nidx>
<nidx>patterns, incomplete</nidx>
-Similarly for incomplete patterns, the function @g@ will fail when
-applied to non-empty lists, so the compiler will emit a warning about
-this when this option is enabled.
+Similarly for incomplete patterns, the function @g@ below will fail
+when applied to non-empty lists, so the compiler will emit a warning
+about this when @-fwarn-incomplete-patterns@ is enabled.
+
+<tscreen><verb>
+g [] = 2
+</verb></tscreen>
+
+This option isn't enabled be default because it can be a bit noisy,
+and it doesn't always indicate a bug in the program. However, it's
+generally considered good practice to cover all the cases in your
+functions.
<tag>@-fwarn-missing-methods@:</tag>
<nidx>-fwarn-missing-methods option</nidx>
This option is on by default.
-</descrip>
+<tag>@-fwarn-missing-signatures@:</tag>
+<nidx>-fwarn-missing-signatures option</nidx>
+<nidx>type signatures, missing</nidx>
+
+If you would like GHC to check that every top-level function/value has
+a type signature, use the @-fwarn-missing-signatures@ option. This
+option is off by default.
-If you would like GHC to check that every top-level value has a type
-signature, use the @-fsignatures-required@
-option.<nidx>-fsignatures-required option</nidx>
+</descrip>
If you're feeling really paranoid, the @-dcore-lint@
option<nidx>-dcore-lint option</nidx> is a good choice. It turns on
When GHC compiles a source file @F@ which contains a module @A@, say,
it generates an object @F.o@, <em>and</em> a companion <em>interface
-file</em> @A.hi@.
+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
not the file name, means that working with tools such as @make(1)@
nicely.
Putting inter-dependencies of the form @Foo.o : Bar.hi@ into your
-@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@:
+@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@:
<tscreen><verb>
depend :
- $(HC) -M $(HC_OPTS) $(SRCS)
+ mkdependHS -- $(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@.
-@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
+@mkdependHS@ will append the needed dependencies to your @Makefile@.
+@mkdependHS@ is fully describe in Section <ref name="Makefile
dependencies in Haskell: using mkdependHS" id="mkdependHS">.
A few caveats about this simple scheme:
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:
+For the example at hand, the boot interface file for A would look like
+the following:
<tscreen><verb>
-_interface_ A 1
-_exports_
-A(A);
-_declarations_
+__interface A 1 where
+__exports A A f;
+__import PrelBase Int;
1 newtype A = A PrelBase.Int ;
+1 f :: A -> A ;
</verb></tscreen>
The syntax is essentially the same as a normal @.hi@ file
<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.
+construction of interface files, is in the works.
%************************************************************************
%* *
@-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-analyser@<nidx>-fno-update-analyser option</nidx>
-(update analyser, because it sometimes takes a <em>long</em> time).
+@-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.
Should you wish to turn individual flags <em>on</em>, you are advised
to use the @-Ofile@ option, described above. Because the order in
The lower-case incantation, @-fvia-c@, is synonymous.
-<tag>@-funfolding-creation-threshold<n>@:</tag>
-<nidx>-funfolding-creation-threshold option</nidx>
+Compiling via C will probably be slower (in compilation time) than
+using GHC's native code generator.
+
+<tag>@-funfolding-interface-threshold<n>@:</tag>
+<nidx>-funfolding-interface-threshold option</nidx>
<nidx>inlining, controlling</nidx>
<nidx>unfolding, controlling</nidx>
(Default: 30) By raising or lowering this number, you can raise or
lower the amount of pragmatic junk that gets spewed into interface
files. (An unfolding has a ``size'' that reflects the cost in terms
of ``code bloat'' of expanding that unfolding in another module. A
-bigger Core expression would be assigned a bigger cost.)
+bigger function would be assigned a bigger cost.)
+
+<tag>@-funfolding-creation-threshold<n>@:</tag>
+<nidx>-funfolding-creation-threshold option</nidx>
+<nidx>inlining, controlling</nidx>
+<nidx>unfolding, controlling</nidx>
+(Default: 30) This option is similar to
+@-funfolding-interface-threshold@, except that it governs unfoldings
+within a single module. Increasing this figure is more likely to
+result in longer compile times than faster code. The next option is
+more useful:
<tag>@-funfolding-use-threshold<n>@:</tag>
<nidx>-funfolding-use-threshold option</nidx>
<nidx>inlining, controlling</nidx>
<nidx>unfolding, controlling</nidx>
-(Default: 3) By raising or lowering this number, you can make the
-compiler more or less keen to expand unfoldings.
-
-OK, folks, these magic numbers `30' and `3' are mildly arbitrary; they
-are of the ``seem to be OK'' variety. The `3' is the more critical
-one; it's what determines how eager GHC is about expanding unfoldings.
-
-% <tag>@-funfolding-override-threshold<n>@:</tag>
-% (Default: 8) [Pretty obscure]
-W hen deciding what unfoldings from a module should be made available
-% to the rest of the world (via this module's interface), the compiler
-% normally likes ``small'' expressions.
-
-% For example, if it sees @foo = bar@, it will decide that the very
-% small expression @bar@ is a great unfolding for @foo@. But if
-% @bar@ turns out to be @(True,False,True)@, we would probably
-% prefer <em>that</em> for the unfolding for @foo@.
-
-% Should we ``override'' the initial small unfolding from @foo=bar@
-% with the bigger-but-better one? Yes, if the bigger one's ``size'' is
-% still under the ``override threshold.'' You can use this flag to
-% adjust this threshold (why, I'm not sure).
-
-% <tag>@-fliberated-case-threshold<n>@:</tag>
-% (Default: 12) [Vastly obscure: NOT IMPLEMENTED YET]
-% ``Case liberation'' lifts evaluation out of recursive functions; it
-% does this by duplicating code. Done without constraint, you can get
-% serious code bloat; so we only do it if the ``size'' of the duplicated
-% code is smaller than some ``threshold.'' This flag can fiddle that
-% threshold.
+(Default: 8) This is the magic cut-off figure for unfolding: below
+this size, a function definition will be unfolded at the call-site,
+any bigger and it won't. The size computed for a function depends on
+two things: the actual size of the expression minus any discounts that
+apply (see @-funfolding-con-discount@).
+
+<tag>@-funfolding-con-discount<n>@:</tag>
+<nidx>-funfolding-con-discount option</nidx>
+<nidx>inlining, controlling</nidx>
+<nidx>unfolding, controlling</nidx>
+(Default: 2) If the compiler decides that it can eliminate some
+computation by performing an unfolding, then this is a discount factor
+that it applies to the funciton size before deciding whether to unfold
+it or not.
+
+OK, folks, these magic numbers `30', `8', and '2' are mildly
+arbitrary; they are of the ``seem to be OK'' variety. The `8' is the
+more critical one; it's what determines how eager GHC is about
+expanding unfoldings.
<tag>@-fsemi-tagging@:</tag>
This option (which <em>does not work</em> with the native-code generator)
<tag>@-D<foo>@:</tag>
<nidx>-D<name> option</nidx>
Define macro @<foo>@ in the usual way. NB: does <em>not</em> affect
-@-D@ macros passed to the C~compiler when compiling via C! For
-those, use the @-optc-Dfoo@ hack...
+@-D@ macros passed to the C~compiler when compiling via C! For those,
+use the @-optc-Dfoo@ hack... (see Section <ref name="Forcing options
+to a particular phase." id="forcing-options-through">).
<tag>@-U<foo>@:</tag>
<nidx>-U<name> option</nidx>
<descrip>
<tag>@__HASKELL1__@:</tag>
<nidx>__HASKELL1__ macro</nidx>
-If defined to $n$, that means GHC supports the
-Haskell language defined in the Haskell report version $1.n$.
+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 set both when pre-processing Haskell source and
-when pre-processing generated C (@.hc@) files.
+NB. This macro is <em/only/ set when pre-processing Haskell source
+(ie. @.hs@ or @.lhs@ files).
<tag>@__GLASGOW_HASKELL__@:</tag>
<nidx>__GLASGOW_HASKELL__ macro</nidx>
-For version $n$ of the GHC system, this will be @#define@d to
-$100 \times n$. So, for version~3.00, it is 300.
-
-This macro is <em>only</em> set when pre-processing Haskell source.
-(<em>Not</em> when pre-processing generated C.)
+For version <em/n/ of the GHC system, this will be @#define@d to
+<em/100n/. So, for version 4.00, it is 400.
With any luck, @__GLASGOW_HASKELL__@ will be undefined in all other
implementations that support C-style pre-processing.
(For reference: the comparable symbols for other systems are:
@__HUGS__@ for Hugs and @__HBC__@ for Chalmers.)
+NB. This macro is set when pre-processing both Haskell source and C
+source, including the C source generated from a Haskell module
+(ie. @.hs@, @.lhs@, @.c@ and @.hc@ files).
+
<tag>@__CONCURRENT_HASKELL__@:</tag>
<nidx>__CONCURRENT_HASKELL__ macro</nidx>
-Only defined when @-concurrent@ is in use!
This symbol is defined when pre-processing Haskell (input) and
-pre-processing C (GHC output).
+pre-processing C (GHC output). Since GHC from verion 4.00 now
+supports concurrent haskell by default, this symbol is always defined.
<tag>@__PARALLEL_HASKELL__@:</tag>
<nidx>__PARALLEL_HASKELL__ macro</nidx>
Section <ref name="Forcing options to a particular phase." id="forcing-options-through">).
A small word of warning: @-cpp@ is not friendly to ``string
-gaps''.<nidx>-cpp vs string gaps</nidx><nidx>string gaps vs -cpp</nidx>. In
-other words, strings such as the following:
+gaps''.<nidx>-cpp vs string gaps</nidx><nidx>string gaps vs
+-cpp</nidx>. In other words, strings such as the following:
<tscreen><verb>
strmod = "\
%* *
%************************************************************************
-To compile a program as Concurrent Haskell, use the @-concurrent@
-option,<nidx>-concurrent option</nidx> both when compiling <em>and
-linking</em>. You will probably need the @-fglasgow-exts@ option, too.
+GHC (as of version 4.00) supports Concurrent Haskell by default,
+without requiring a special option or libraries compiled in a certain
+way. To get access to the support libraries for Concurrent Haskell
+(ie. @Concurrent@ and friends), use the @-syslib concurrent@ option.
Three RTS options are provided for modifying the behaviour of the
threaded runtime system. See the descriptions of @-C[<us>]@, @-q@,
-and @-t<num>@ in Section <ref name="RTS options for Concurrent/Parallel Haskell" id="parallel-rts-opts">.
+and @-t<num>@ in Section <ref name="RTS options for
+Concurrent/Parallel Haskell" id="parallel-rts-opts">.
+
+Concurrent Haskell is described in more detail in Section <ref
+name="Concurrent and Parallel Haskell" id="concurrent-and-parallel">.
%************************************************************************
%* *
%* *
%************************************************************************
-The main thread in a Concurrent Haskell program is given its own
-private stack space, but all other threads are given stack space from
-the heap. Stack space for the main thread can be
-adjusted as usual with the @-K@ RTS
-option,<nidx>-K RTS option (concurrent, parallel)</nidx> but if this
-private stack space is exhausted, the main thread will switch to stack
-segments in the heap, just like any other thread. Thus, problems
-which would normally result in stack overflow in ``sequential Haskell''
-can be expected to result in heap overflow when using threads.
-
-The concurrent runtime system uses black holes as synchronisation
-points for subexpressions which are shared among multiple threads. In
-``sequential Haskell'', a black hole indicates a cyclic data
-dependency, which is a fatal error. However, in concurrent execution, a
-black hole may simply indicate that the desired expression is being
-evaluated by another thread. Therefore, when a thread encounters a
-black hole, it simply blocks and waits for the black hole to be
-updated. Cyclic data dependencies will result in deadlock, and the
-program will fail to terminate.
-
-Because the concurrent runtime system uses black holes as
-synchronisation points, it is not possible to disable black-holing
-with the @-N@ RTS option.<nidx>-N RTS option</nidx> Therefore, the use
-of signal handlers (including timeouts) with the concurrent runtime
-system can lead to problems if a thread attempts to enter a black hole
-that was created by an abandoned computation. The use of signal
-handlers in conjunction with threads is strongly discouraged.
-
+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">).
%************************************************************************
%* *
the finest granularity possible, short of a context switch at every
heap allocation.
+[NOTE: this option currently has no effect (version 4.00). Context
+switches happen when the current heap block is full, i.e. every 4k of
+allocation].
+
<tag>@-q[v]@:</tag>
<nidx>-q RTS option</nidx>
-Produce a quasi-parallel profile of thread activity, in the file
-@<program>.qp@. In the style of @hbcpp@, this profile records
-the movement of threads between the green (runnable) and red (blocked)
-queues. If you specify the verbose suboption (@-qv@), the green
-queue is split into green (for the currently running thread only) and
-amber (for other runnable threads). We do not recommend that you use
-the verbose suboption if you are planning to use the @hbcpp@
-profiling tools or if you are context switching at every heap check
-(with @-C@).
+(PARALLEL ONLY) Produce a quasi-parallel profile of thread activity,
+in the file @<program>.qp@. In the style of @hbcpp@, this profile
+records the movement of threads between the green (runnable) and red
+(blocked) queues. If you specify the verbose suboption (@-qv@), the
+green queue is split into green (for the currently running thread
+only) and amber (for other runnable threads). We do not recommend
+that you use the verbose suboption if you are planning to use the
+@hbcpp@ profiling tools or if you are context switching at every heap
+check (with @-C@).
<tag>@-t<num>@:</tag>
<nidx>-t<num> RTS option</nidx>
-Limit the number of concurrent threads per processor to @<num>@.
-The default is 32. Each thread requires slightly over 1K <em>words</em>
-in the heap for thread state and stack objects. (For 32-bit machines,
-this translates to 4K bytes, and for 64-bit machines, 8K bytes.)
+(PARALLEL ONLY) Limit the number of concurrent threads per processor
+to @<num>@. The default is 32. Each thread requires slightly over 1K
+<em>words</em> in the heap for thread state and stack objects. (For
+32-bit machines, this translates to 4K bytes, and for 64-bit machines,
+8K bytes.)
<tag>@-d@:</tag>
<nidx>-d RTS option (parallel)</nidx>
appropriate if your machine has a high communication cost relative to
computation speed.
</descrip>
-
-%************************************************************************
-%* *
-<sect2>Potential problems with Parallel Haskell
-<label id="parallel-problems">
-<p>
-<nidx>Parallel Haskell---problems</nidx>
-<nidx>problems, Parallel Haskell</nidx>
-%* *
-%************************************************************************
-
-The ``Potential problems'' for Concurrent Haskell also apply for
-Parallel Haskell. Please see Section <ref name="Potential problems with Concurrent Haskell" id="concurrent-problems">.
projects / ghc-hetmet.git / blobdiff