Commit a13f31cc authored by rrt's avatar rrt
Browse files

[project @ 2000-01-05 11:20:23 by rrt]

VSGML files removed because of conversion from LinuxDoc to DocBook (now
have just SGML files).
parent c7f8f1e6
<sect1>Release notes for version~4.00---10/98
<label id="release-4-00">
<p>
<sect2>Language matters
<p>
<itemize>
<item> Universal and existential quantification: see Section <ref
name="Explicit universal quantification"
id="universal-quantification"> and Section <ref name="Existentially
quantified data constructors" id="existential-quantification">
respectively.
Universal quantification was in in GHC 2.10 and later, but the
syntax has changed: it's now @forall a. ...@ instead of @All a => ...@.
<item> Multi-paramter type classes. We have relaxed some of the rules
since GHC 3.00. In particular
<descrip>
<tag>@-fallow-overlapping-instances@</tag>
allows overlapping instances
<tag>@-fallow-undecidable-instances@</tag>
allows you to write instance contexts that constrain non-type-variables
</descrip>
Full details in Section <ref name="Multi-parameter type classes"
id="multi-param-type-classes">.
</itemize>
<sect2>New Libraries
<p>
Documentation in <url name="GHC/Hugs Extension Libraries"
url="libs.html">.
<descrip>
<tag>@Dynamic@</tag>
Dynamic types.
<tag>@Exceptions@</tag>
The library @Exception@ in @-syslib exts@ provide an interface for
exception handling. Calls to @error@, pattern matching failures and a
bunch of other exception can be caught.
</descrip>
<sect2>Compiler internals
<p>
The intermediate language used by GHC has had a radical overhaul.
The new Core language (coreSyn/CoreSyn.lhs) is much smaller and
more uniform. The main transformation engine (the "simplifier")
has been totally rewritten. The compiler is several thousand lines
shorter as a result. It's also very much easier to understand
and modify. (It's true. Honest!)
<sect2>Run time system
<p>
There is a completely new runtime system, aimed at integration with
Hugs. Tons of cruft removed. Some changes to code generation; things
typically run a bit faster as a result.
An overview of the new RTS is available: <url name="The New GHC/Hugs
Runtime System" url="http://www.dcs.gla.ac.uk/~simonm/rts.ps">.
<sect2>Storage Manager/Garbage Collector
<p>
The new storage manager features a dynamically resizing heap, so you
won't need those pesky @-H@ options anymore. In fact, the @-H@ option
is now ignored for compatibility with older versions.
Stacks are now also expandable, and the @-K@ option now specifies a
<em/maximum/ heap size. The default is (a perhaps conservative) @1M@.
The garbage collector now collects CAFs, so there's no more space
leaks associated with these. If you think you have a CAF-related
space leak, we'd like to hear about it.
The storage manager current only has a two-space garbage collector,
which will be slower than 3.02's generational collector when the
amount of live data is large. A new generational collector is high on
our priority list.
For the other new tweakables, see Section <ref name="RTS options to
control the garbage-collector" id="rts-options-gc">.
<sect2>Profiling
<p>
There is a new profiler based on <em/Cost Centre Stacks/. This is an
extension of the previous cost centre scheme, whereby the profilier
stores information about the call-graph of the program and attributes
costs to nodes of this graph.
For a quick demo, try compiling a program with @-prof -auto-all@, then
run it with @+RTS -p@ and see what comes out (in the @<prog>.prof@
file).
The feature is still experimental, and the call graph may not be
exactly what you were expecting. Also, we only have time/allocation
profiling at the moment; heap profiling will follow shortly.
<sect2>Miscellaneous
<p>
<itemize>
<item> Concurrent Haskell is now the default. No need to
compile/download special libraries. The context switch interval isn't
tweakable any more; threads just yield after allocating a fixed amount
of heap (currently 4k). If you want a quicker context switch, that
won't be possible: this decision was made for efficiency reasons (it
reduces the penalty for runnning threaded code to almost zero). We
might allow the context switch interval to be increased in the future;
but also context switches are pretty fast (faster than before).
<item> @forkIO@ now returns a @ThreadId@, and there's a new operation
@killThread@ which will terminate an existing thread. See Section
<ref name="The Concurrent interface" id="concurrent-interface"> for
more details.
<item> You need @-syslib concurrent@ to get the @Concurrent@ library.
<item> The rewritten IO library from 3.03 has been ported to 4.00.
<item> New constructs: @foriegn import@ and @foreign export@ for
H/Direct.
<item> Supported architectures: all the development has been done on
x86(mainly FreeBSD/Linux) so this is the most stable environment.
Sparc (Solaris) and x86/Win32 (cygwin32) have also been mildly tested, and
an Alpha port is in the works. Everything else will need a little
porting effort; we don't have machines here, so any help would be
greatly appreciated.
<item> Code is faster and smaller, but programs might run slower due
to the garbage collector (see "Storage Manager" above). Increasing
the minimum allocation area with the @-A@ RTS option can claw back
some of this speed.
<item> We now use GMP 2.02, and attempt to use an already-installed
copy if available. If you have GMP on your system but the configure
script doesn't detect it, we'd like to know.
<item> @seq@ works better than in 3.xx - you can now @seq@ functions
without crashing the program.
<item> The @Eval@ class has been removed (i.e. every type is assumed
to be in class @Eval@). This change has been made in anticipation of
Haskell 98.
<item> The native code generator has had very little testing (it's not used
on x86 yet), so Sparcs may have some trouble with it. Try -fvia-C if
strange errors occur.
<item> The compiler is slightly faster, but sometimes needs more heap.
If you have an example where this is the case, please let us know.
</itemize>
<sect1>Release notes for version~4.01---11/98
<label id="release-4-01">
<p>
<itemize>
<item> <tt/relocate_TSO/ bug fixed.
<item> Weak pointers implemented, and new <tt/Weak/ library provided
(see <htmlurl name="GHC/Hugs Extension Libraries" url="libs.html">).
The <tt/ForeignObj/ interface no longer supports finalisation - use
the <tt/Weak/ interface for that.
<item> Foreign funcion interface is now complete and working.
<item> New interface file format for compatibility with Hugs. No
user-visible changes except that you'll have to update any .hi-boot
files you have lying around - check out some GHC-generated .hi files
for examples.
<item> Space leak in the compiler is partially fixed -
<tt/-dcore-lint/ is still recommended for decent space behaviour.
<item> New API to the RTS (not interesting unless you're an RTS client
writer).
<item> <tt/thawIOArray/ added to <tt/IOExts/.
<item> Many many small bugs fixed.
</itemize>
<sect1>Release notes for version~4.02---12/98
<label id="release-4-02">
<p>
<itemize>
<item> Full Haskell 98 language support.
<item> Scoped type variables implemented (see Section <ref
name="Scoped Type Variables" id="scoped-type-variables">).
<item> Several bugs in _ccall_GC and foreign export fixed.
<item> Warnings for unused variables should work now (they didn't before).
<item> Simplifier improvements:
<itemize>
<item> Much better treatment of strict arguments.
<item> Function arguments of unlifted type are treated as strict.
<item> Better treatment of bottoming Ids.
<item> No need for worker/wrapper split for fns that are merely strict.
<item> Fewer iterations needed, I hope.
</itemize>
<item> Strictness of primitive operations is now explicit and used by
the simplifier.
<item> Less gratuitous renaming in interface files and abs C.
<item> <tt/OccName/ is a separate module, and is an abstract data type.
<item> A new generational garbage collector: the number of generations
is variable, using the -G RTS option (see <ref id="rts-options-gc"
name="RTS options to control the garbage-collector">). This collector
is faster and more space-efficient than the two-space collector in 4.01.
<item> Error messages and warnings are now printed out in the order they
occur in the source code.
<item> <tt/isEmptyMVar/ operation added to the <tt/Concurrent/ library.
<item> Two new functions exported from <tt/ST/ (and <tt/LazyST/):
<tt/unsafeIOToST/ and <tt/stToIO/.
<item> The <tt/+RTS -H&lt;size&gt;/ option is reinstated. Now it
means "use about this much memory" (see Section <ref
id="rts-options-gc" name="RTS options to control the garbage
collector">). This option was added mainly so that 4.02 GC times look
good compared to 3.02 :-).
<item> <tt/finalise/ and <tt/mkWeakNoFinaliser/ operations added to
<tt/Weak/ library.
<item> Ticky-ticky profiling works again (cost-centre profiling is
still broken).
<item> Better <tt/egcs-1.1.1/ support.
</itemize>
<sect1>Release notes for version~4.03---3/99
<label id="release-4-03">
<p>
<itemize>
<item> <tt/Weak/ library changes:
<itemize>
<item> Finalise is now spelt finalize in all function names.
<item> <tt/finalize/ now runs the finalizer immediately, and
waits for it to complete before returning.
<item> <tt/mkWeak/ now takes a <tt/Maybe (IO ())/ for the finalizer,
and <tt/mkWeakNoFinalizer/ is removed.
</itemize>
<item> Changed representation of <tt/Integer/ type to speed up
computations on small integers. The performance of <tt/Integer/ is now
only slightly slower than <tt/Int/ for values between <tt/minBound :: Int/
and <tt/maxBound :: Int/.
<item> On Win32 platforms, added support for using (and producing) dynamic
link libraries (DLLs) containing ghc-compiled code.
<item> Added @-funbox-strict-fields@ for unboxing/unpacking strict
constructor fields.
</itemize>
<sect1>Release notes for version~4.04---7/99
<label id="release-4-04">
<p>
<itemize>
<item> <tt/Weak/ library changes:
<itemize>
<item> Finalise is now spelt finalize in all function names.
<item> <tt/finalize/ now runs the finalizer immediately, and
waits for it to complete before returning.
<item> <tt/mkWeak/ now takes a <tt/Maybe (IO ())/ for the finalizer,
and <tt/mkWeakNoFinalizer/ is removed.
<item> A weak pointer whose key is itself a weak pointer will now do
the right thing.
</itemize>
<item> Changed representation of <tt/Integer/ type to speed up
computations on small integers. The performance of <tt/Integer/ is now
only slightly slower than <tt/Int/ for values between <tt/minBound::Int/
and <tt/maxBound::Int/.
<item> On Win32 platforms, added support for using (and producing) dynamic
link libraries (DLLs) containing ghc-compiled code.
<item> Added @-funbox-strict-fields@ for unboxing/unpacking strict
constructor fields.
<item> GHC now has a license! Check out <tt>fptools/ghc/LICENSE/</tt>.
<item> Added CPR analysis, which reduces allocation by unboxing
function results (thanks to Kevin Glynn <tt>&lt;keving@@cs.mu.OZ.AU&gt;</tt>).
<item> UsageSP analysis added, but not yet functional.
<item> Added a simple common sub-expression analysis pass.
<item> Implemented update-in-place for certain very restricted cases.
<item> Replaced GHC's old and worn yacc/lex parser with a new one
based on Happy. Fixed several Haskell 98 non-conformance issues in
the process.
<item> Added <tt>Concurrent.yield :: IO ()</tt>.
<item> Added RULES pragms - transformation rules for Haskell source.
This is used for list fusion: now intermediate lists between map,
foldr, list comprehensions are removed automatically.
<item> Unregisterised/unmangled builds now work.
<item> Much performance tuning: GHC 4.04 produces faster code than all
previous compilers.
<item> GHC now defines <tt/__HASKELL98__/ when compiling files with
<tt/-cpp/.
<item> <tt/hppa1.1-hp-hpux/ port reinstated.
<item> New operations for unsafely thawing byte arrays:
<tt/unsafeThaw{Byte,ST,IO}Array/.
<item> <tt/mkdependHS/ now lives in GHC's lib directory, not the
binary directory. It isn't intended to be run standalone, only via
<tt/ghc -M/.
<item> Asynchronous exceptions are now supported (see Section <ref name="The Concurrent Library" id="concurrent-interface">). New operations:
<itemize> <item> <tt/Exception.killThread/ now raises an exception
(<tt/AsyncException.KilledThread/) in the killed thread.
<item> <tt/Exception.raiseInThread/ allows a thread to raise an
exception in another thread.
<item> <tt/Concurrent.myThreadId/ returns the <tt/ThreadId/ of the
calling thread.
<item> Stack overflow results in <tt/AsyncException.StackOverflow/
being raised in the offending thread.
</itemize>
<item> Assertion failures now raise an <tt/AssertionFailed/ exception.
<item> Added simple high-level interface to the Regex library, see
Section <ref name="The RegexString Library" id="RegexString">.
<item> <tt/forkIO/ now handles any uncaught exceptions cleanly.
<item> <tt/integer2Int#/ isn't sign preserving any longer, but modulo
<tt/(maxBound::Int + 1) * 2/.
<item> <tt/-ddump-rdr/ is now called <tt/-ddump-parsed/.
<item> Signal handling with the <tt/Posix/ library now works.
<item> Many, many bugs fixed.
</itemize>
%************************************************************************
%* *
<sect1>Debugging the compiler
<label id="options-debugging">
<p>
<nidx>debugging options (for GHC)</nidx>
%* *
%************************************************************************
HACKER TERRITORY. HACKER TERRITORY.
(You were warned.)
%----------------------------------------------------------------------
<sect2>Replacing the program for one or more phases.
<label id="replacing-phases">
<p>
<nidx>GHC phases, changing</nidx>
<nidx>phases, changing GHC</nidx>
You may specify that a different program be used for one of the phases
of the compilation system, in place of whatever the driver @ghc@ has
wired into it. For example, you might want to try a different
assembler. The
@-pgm<phase-code><program-name>@<nidx>-pgm&lt;phase&gt;&lt;stuff&gt;
option</nidx> option to @ghc@ will cause it to use @<program-name>@
for phase @<phase-code>@, where the codes to indicate the phases are:
<tabular ca="ll">
<bf>code</bf> | <bf>phase</bf> @@
@@
L | literate pre-processor @@
P | C pre-processor (if -cpp only) @@
C | Haskell compiler @@
c | C compiler@@
a | assembler @@
l | linker @@
dep | Makefile dependency generator @@
</tabular>
%----------------------------------------------------------------------
<sect2>Forcing options to a particular phase.
<label id="forcing-options-through">
<p>
<nidx>forcing GHC-phase options</nidx>
The preceding sections describe driver options that are mostly
applicable to one particular phase. You may also <em>force</em> a
specific option @<option>@ to be passed to a particular phase
@<phase-code>@ by feeding the driver the option
@-opt<phase-code><option>@.<nidx>-opt&lt;phase&gt;&lt;stuff&gt;
option</nidx> The codes to indicate the phases are the same as in the
previous section.
So, for example, to force an @-Ewurble@ option to the assembler, you
would tell the driver @-opta-Ewurble@ (the dash before the E is
required).
Besides getting options to the Haskell compiler with @-optC<blah>@,
you can get options through to its runtime system with
@-optCrts<blah>@<nidx>-optCrts&lt;blah&gt; option</nidx>.
So, for example: when I want to use my normal driver but with my
profiled compiler binary, I use this script:
<tscreen><verb>
#! /bin/sh
exec /local/grasp_tmp3/simonpj/ghc-BUILDS/working-alpha/ghc/driver/ghc \
-pgmC/local/grasp_tmp3/simonpj/ghc-BUILDS/working-hsc-prof/hsc \
-optCrts-i0.5 \
-optCrts-PT \
"$@"
</verb></tscreen>
%----------------------------------------------------------------------
<sect2>Dumping out compiler intermediate structures
<label id="dumping-output">
<p>
<nidx>dumping GHC intermediates</nidx>
<nidx>intermediate passes, output</nidx>
<descrip>
<tag>@-noC@:</tag>
<nidx>-noC option</nidx>
Don't bother generating C output <em>or</em> an interface file. Usually
used in conjunction with one or more of the @-ddump-*@ options; for
example: @ghc -noC -ddump-simpl Foo.hs@
<tag>@-hi@:</tag>
<nidx>-hi option</nidx>
<em>Do</em> generate an interface file. This would normally be used in
conjunction with @-noC@, which turns off interface generation;
thus: @-noC -hi@.
<tag>@-dshow-passes@:</tag>
<nidx>-dshow-passes option</nidx>
Prints a message to stderr as each pass starts. Gives a warm but
undoubtedly misleading feeling that GHC is telling you what's
happening.
<tag>@-ddump-<pass>@:</tag>
<nidx>-ddump-&lt;pass&gt; options</nidx>
Make a debugging dump after pass @<pass>@ (may be common enough to
need a short form...). You can get all of these at once (<em/lots/ of
output) by using @-ddump-all@, or most of them with @-ddump-most@.
Some of the most useful ones are:
<descrip>
<tag>@-ddump-parsed@:</tag> parser output
<tag>@-ddump-rn@:</tag> renamer output
<tag>@-ddump-tc@:</tag> typechecker output
<tag>@-ddump-deriv@:</tag> derived instances
<tag>@-ddump-ds@:</tag> desugarer output
<tag>@-ddump-spec@:</tag> output of specialisation pass
<tag>@-ddump-rules@:</tag> dumps all rewrite rules (including those generated by the specialisation pass)
<tag>@-ddump-simpl@:</tag> simplifer output (Core-to-Core passes)
<tag>@-ddump-usagesp@:</tag> UsageSP inference pre-inf and output
<tag>@-ddump-cpranal@:</tag> CPR analyser output
<tag>@-ddump-stranal@:</tag> strictness analyser output
<tag>@-ddump-workwrap@:</tag> worker/wrapper split output
<tag>@-ddump-occur-anal@:</tag> `occurrence analysis' output
<tag>@-ddump-stg@:</tag> output of STG-to-STG passes
<tag>@-ddump-absC@:</tag> <em>un</em>flattened Abstract~C
<tag>@-ddump-flatC@:</tag> <em>flattened</em> Abstract~C
<tag>@-ddump-realC@:</tag> same as what goes to the C compiler
<tag>@-ddump-asm@:</tag> assembly language from the native-code generator
<tag>@-ddump-most@:</tag> most of the above, plus @-dshow-passes@, @-dsource-stats@, @-ddump-simpl-stats@,
<tag>@-ddump-all@:</tag> all the above, plus @-ddump-inlinings@,
@-ddump-simpl-iterations@, @-ddump-rn-trace@,
@-ddump-verbose-simpl@, @-ddump-verbose-stg@.
</descrip>
<nidx>-ddump-all option</nidx>%
<nidx>-ddump-most option</nidx>%
<nidx>-ddump-parsed option</nidx>%
<nidx>-ddump-rn option</nidx>%
<nidx>-ddump-tc option</nidx>%
<nidx>-ddump-deriv option</nidx>%
<nidx>-ddump-ds option</nidx>%
<nidx>-ddump-simpl option</nidx>%
<nidx>-ddump-cpranal option</nidx>%
<nidx>-ddump-workwrap option</nidx>%
<nidx>-ddump-rules option</nidx>%
<nidx>-ddump-usagesp option</nidx>%
<nidx>-ddump-stranal option</nidx>%
<nidx>-ddump-occur-anal option</nidx>%
<nidx>-ddump-spec option</nidx>%
<nidx>-ddump-stg option</nidx>%
<nidx>-ddump-absC option</nidx>%
<nidx>-ddump-flatC option</nidx>%
<nidx>-ddump-realC option</nidx>%
<nidx>-ddump-asm option</nidx>
%For any other @-ddump-*@ options: consult the source, notably
%@ghc/compiler/main/CmdLineOpts.lhs@.
<tag>@-dverbose-simpl@ and @-dverbose-stg@:</tag>
<nidx>-dverbose-simpl option</nidx>
<nidx>-dverbose-stg option</nidx>
Show the output of the intermediate Core-to-Core and STG-to-STG
passes, respectively. (<em>Lots</em> of output!) So: when we're
really desperate:
<tscreen><verb>
% ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
</verb></tscreen>
<tag>@-ddump-simpl-iterations@:</tag>
<nidx>-ddump-simpl-iterations option</nidx>
Show the output of each <em/iteration/ of the simplifier (each run of
the simplifier has a maximum number of iterations, normally 4). Used
when even @-dverbose-simpl@ doesn't cut it.
<tag>@-dppr-{user,debug@}:</tag>
<nidx>-dppr-user option</nidx>
<nidx>-dppr-debug option</nidx>
Debugging output is in one of several ``styles.'' Take the printing
of types, for example. In the ``user'' style, the compiler's internal
ideas about types are presented in Haskell source-level syntax,
insofar as possible. In the ``debug'' style (which is the default for
debugging output), the types are printed in with
explicit foralls, and variables have their unique-id attached (so you
can check for things that look the same but aren't).
<tag>@-ddump-simpl-stats@:</tag>
<nidx>-ddump-simpl-stats option</nidx>
Dump statistics about how many of each kind
of transformation too place. If you add @-dppr-debug@ you get more detailed information.
<tag>@-ddump-raw-asm@:</tag>
<nidx>-ddump-raw-asm option</nidx>
Dump out the assembly-language stuff, before the ``mangler'' gets it.
<tag>@-ddump-rn-trace@:</tag>
<nidx>-ddump-rn-trace</nidx>
Make the renamer be *real* chatty about what it is upto.
<tag>@-dshow-rn-stats@:</tag>
<nidx>-dshow-rn-stats</nidx>
Print out summary of what kind of information the renamer had to bring
in.
<tag>@-dshow-unused-imports@:</tag>
<nidx>-dshow-unused-imports</nidx>
Have the renamer report what imports does not contribute.
%
%<tag>@-dgc-debug@:</tag>
%<nidx>-dgc-debug option</nidx>
%Enables some debugging code related to the garbage-collector.
</descrip>
%ToDo: -ddump-asm-insn-counts
%-ddump-asm-globals-info
%----------------------------------------------------------------------
<sect2>Checking for consistency
<label id="checking-consistency">
<p>
<nidx>consistency checks</nidx>
<nidx>lint</nidx>
<descrip>
<tag>@-dcore-lint@:</tag>
<nidx>-dcore-lint option</nidx>
Turn on heavyweight intra-pass sanity-checking within GHC, at Core
level. (It checks GHC's sanity, not yours.)
<tag>@-dstg-lint@:</tag>
<nidx>-dstg-lint option</nidx>
Ditto for STG level.
<tag>@-dusagesp-lint@:</tag>
<nidx>-dstg-lint option</nidx>
Turn on checks around UsageSP inference (@-fusagesp@). This verifies
various simple properties of the results of the inference, and also
warns if any identifier with a used-once annotation before the
inference has a used-many annotation afterwards; this could indicate a
non-worksafe transformation is being applied.
</descrip>
%----------------------------------------------------------------------
<sect2>How to read Core syntax (from some @-ddump-*@ flags)
<p>
<nidx>reading Core syntax</nidx>
<nidx>Core syntax, how to read</nidx>
Let's do this by commenting an example. It's from doing
@-ddump-ds@ on this code:
<tscreen><verb>
skip2 m = m : skip2 (m+2)
</verb></tscreen>
Before we jump in, a word about names of things. Within GHC,
variables, type constructors, etc., are identified by their
``Uniques.'' These are of the form `letter' plus `number' (both
loosely interpreted). The `letter' gives some idea of where the
Unique came from; e.g., @_@ means ``built-in type variable'';