Commit 2947e534 authored by simonmar's avatar simonmar
Browse files

[project @ 2001-03-22 12:12:23 by simonmar]

Move the bug reporting section earlier, and mention the SourceForge
bug tracker.

Update the release notes.

I think I'm just about done in here...
parent f4742cfc
......@@ -5,19 +5,103 @@
<title>User-visible compiler changes</title>
<itemizedlist>
<listitem>
<para>GHCi added</para>
<para>GHCi, the new interactive environment on top of GHC, has
been added (<xref linkend="ghci">).</para>
</listitem>
<listitem>
<para><option>--make</option> flag added</para>
<para>New <option>--make</option> flag added (<xref
linkend="make-mode">).</para>
</listitem>
<listitem>
<para>dynamic vs. static options</para>
<para>The native code generator now supports Sparc in addition
to x86.</para>
</listitem>
<listitem>
<para>NCG support for Sparc</para>
<para>We now make it clear which options can be placed in an
OPTIONS pragma. See <xref
linkend="static-dynamic-flags">.</para>
</listitem>
<listitem>
<para><command>hsc2hs</command> added</para>
<para><option>-fglasgow-exts</option> no longer implies
<option>-package lang</option>.</para>
</listitem>
<listitem>
<para><option>-noC</option> is no more.</para>
</listitem>
<listitem>
<para><option>-hi</option> and <option>-nohi</option> are no more.</para>
</listitem>
<listitem>
<para>The concept of &ldquo;packages&rdquo; has been
generalised and extended. Packages may be installed or
removed from an existing GHC installation using the new
<command>ghc-pkg</command> tool. See <xref
linkend="packages">.</para>
</listitem>
<listitem>
<para>Initial unicode support: the <literal>Char</literal>
type is now 31 bits. We don't yet have support for unicode
I/O.</para>
</listitem>
<listitem>
<para><option>-v</option> now takes an optional numeric
argument indicating the level of verbosity (<xref
linkend="options-help">). <option>-dshow-passes</option> has
been removed.</para>
</listitem>
<listitem>
<para>Parallel list comprehensions added.</para>
</listitem>
<listitem>
<para>Profiling: please use
<literal>{-# SCC ".." #-}</literal>
rather than <literal>_scc_ "..."</literal>. The latter
will be phased out in due course.</para>
</listitem>
<listitem>
<para>A new experimental optimisation, SpecConstr, is turned
on with <literal>-O2</literal>.</para>
</listitem>
<listitem>
<para>Please report bugs using the <ulink
url="http://sourceforge.net/projects/ghc/">SourceForge bug
tracker</ulink> instead of
<email>glasgow-haskell-bugs@haskell.org</email> if
possible.</para>
</listitem>
<listitem>
<para>Documentation changes: there's now a useful Flag
Reference section, see <xref linkend="flag-reference">.</para>
</listitem>
<listitem>
<para>Many, many, bugfixes.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>New experimental features</title>
<itemizedlist>
<listitem>
<para>A &ldquo;front panel&rdquo; for GHC-compiled programs
displays real-time graphs of memory behaviour in a GTK+
window. You need to recompile the RTS with front panel
support to use this.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>FFI changes</title>
<itemizedlist>
<listitem>
<para><command>hsc2hs</command> added (<xref linkend="hsc2hs">).</para>
</listitem>
<listitem>
<para>FFI libraries have been updated to the latest proposal
from the FFI task force. Too many changes to list here, see
the docs: <xref linkend="sec-Foreign">.</para>
</listitem>
</itemizedlist>
</sect2>
......@@ -26,7 +110,43 @@
<title>User-visible library changes</title>
<itemizedlist>
<listitem>
<para>FFI libraries enhanced, lots of deprecations.</para>
<para><function>putMVar</function> now blocks if the
<literal>MVar</literal> is already full. The
<literal>PutFullMVar</literal> exception no longer exists. A
non-blocking version of <function>putMVar</function>,
<function>tryPutMVar</function>, has been added (<xref
linkend="sec-MVars">).</para>
</listitem>
<listitem>
<para>The <literal>Integer</literal> type now has an instance
of <literal>Bits</literal> (<xref linkend="sec-Bits">).</para>
</listitem>
<listitem>
<para>Package <literal>hssource</literal> has been added. It
contains a Haskell 98 abstract syntax, parser, lexer and pretty
printer. No documentation yet.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>Build system changes</title>
<itemizedlist>
<listitem>
<para>The <literal>WithGhcHc</literal> setting in
<literal>build.mk</literal> has been replaced by the
<literal>--with-ghc=<replaceable>ghc</replaceable></literal>
option to <literal>configure</literal>. The new option
<emphasis>must</emphasis> be used if you intend to use
anything except &ldquo;<literal>ghc</literal>&rdquo; to
bootstrap GHC, in order that the build system can figure out
what version of GHC you're using.</para>
</listitem>
<listitem>
<para>Source distributions are now made by doing <literal>make
distclean</literal> in a build tree, instead of requiring a
linked build tree.</para>
</listitem>
</itemizedlist>
</sect2>
......@@ -34,10 +154,18 @@
<sect2>
<title>Internal changes</title>
<itemizedlist>
<listitem>
<para>Many internal compiler changes: too many to list
here.</para>
</listitem>
<listitem>
<para>The old perl driver has been removed and replaced by a
driver in the compiler proper.</para>
</listitem>
<listitem>
<para>We now use GMP 3 instead of GMP 2 for
arbitrary-precision integer support.</para>
</listitem>
<listitem>
<para>Several libraries rewritten to use the FFI.</para>
</listitem>
......
......@@ -8,9 +8,10 @@
<Para>
If you still have a problem after consulting this section, then you
may have found a <Emphasis>bug</Emphasis>&mdash;please report it! See <XRef LinkEnd="bug-reports"> for a
list of things we'd like to know about your bug. If in doubt, send a
report&mdash;we love mail from irate users :-!
may have found a <Emphasis>bug</Emphasis>&mdash;please report it! See
<XRef LinkEnd="bug-reporting"> for details on how to report a bug and
a list of things we'd like to know about your bug. If in doubt, send
a report&mdash;we love mail from irate users :-!
</Para>
<Para>
......@@ -153,28 +154,7 @@ proper dependency order.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>&ldquo;What's a `consistency error'?&rdquo;</Term>
<ListItem>
<Para>
(These are reported just after linking your program.)
</Para>
<Para>
You tried to link incompatible object files, e.g., normal ones
(registerised, Appel garbage-collector) with profiling ones (two-space
collector). Or those compiled by a previous version of GHC
with an incompatible newer version.
</Para>
<Para>
If you run <Command>nm -o *.o &verbar; egrep 't (cc&verbar;hsc)\.'</Command> (or, on
unregisterised files: <Command>what *.o</Command>), you'll see all the consistency
tags/strings in your object files. They must all be the same!
(ToDo: tell you what they mean&hellip;)
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>&ldquo;Is this line number right?&rdquo;</Term>
<ListItem>
......@@ -286,7 +266,8 @@ GHC-compiled program, please see <XRef LinkEnd="hard-core-debug">.
<Term>&ldquo;My program entered an `absent' argument.&rdquo;</Term>
<ListItem>
<Para>
This is definitely caused by a bug in GHC. Please report it.
This is definitely caused by a bug in GHC. Please report it (see <xref
linkend="bug-reporting">).
</Para>
</ListItem>
</VarListEntry>
......@@ -307,96 +288,6 @@ exception (please report it if it does).
</Sect1>
<Sect1 id="bug-reports">
<Title>How to report a bug in the GHC system
</Title>
<Para>
<IndexTerm><Primary>bug reports</Primary></IndexTerm>
</Para>
<Para>
Glasgow Haskell is a changing system so there are sure to be bugs in
it. Please report them to
<Email>glasgow-haskell-bugs@haskell.org</Email>! (However, please
check the earlier part of this section to be sure it's not a known
not-really-a problem.)
</Para>
<Para>
The name of the bug-reporting game is: facts, facts, facts.
Don't omit them because &ldquo;Oh, they won't be interested&hellip;&rdquo;
</Para>
<Para>
<OrderedList>
<ListItem>
<Para>
What kind of machine are you running on, and exactly what version of
the operating system are you using? (<Command>uname -a</Command> or
<Command>cat /etc/motd</Command> will show the desired information.)
</Para>
</ListItem>
<ListItem>
<Para>
What version of GCC are you using? <Command>gcc -v</Command> will tell you.
</Para>
</ListItem>
<ListItem>
<Para>
Run the sequence of compiles/runs that caused the offending
behaviour, capturing all the input/output in a &ldquo;script&rdquo; (a UNIX
command) or in an Emacs shell window. We'd prefer to see the whole
thing.
</Para>
</ListItem>
<ListItem>
<Para>
Be sure any Haskell compilations are run with a <Option>-v</Option> (verbose)
flag, so we can see exactly what was run, what versions of things you
have, etc.
</Para>
</ListItem>
<ListItem>
<Para>
What is the program behaviour that is wrong, in your opinion?
</Para>
</ListItem>
<ListItem>
<Para>
If practical, please send enough source files for us to duplicate the
problem.
</Para>
</ListItem>
<ListItem>
<Para>
If you are a Hero and track down the problem in the
compilation-system sources, please send us patches relative to a known
released version of GHC, or whole files if you prefer.
</Para>
</ListItem>
</OrderedList>
</Para>
</Sect1>
<Sect1 id="hard-core-debug">
<Title>Hard-core debugging of GHC-compiled programs
</Title>
......@@ -407,7 +298,7 @@ released version of GHC, or whole files if you prefer.
<Para>
If your program is crashing, you should almost surely file a bug
report, as outlined in previous sections.
report, as outlined in <xref linkend="bug-reporting">.
</Para>
<Para>
......
......@@ -212,6 +212,87 @@
</sect1>
<sect1 id="bug-reporting">
<title>Reporting bugs in GHC</title>
<indexterm><primary>bugs</primary><secondary>reporting</secondary>
</indexterm>
<indexterm><primary>reporting bugs</primary>
</indexterm>
<para>Glasgow Haskell is a changing system so there are sure to be
bugs in it. </para>
<para>To repot a bug, either:</para>
<itemizedlist>
<listitem>
<para>Go to the <ulink
url="http://sourceforge.net/projects/ghc/">SoureForge GHC
page</ulink>, go to the <quote>bugs</quote> section, click on
<quote>submit</quote>, and enter your bug report. You can also
check the outstanding bugs here to make sure it hasn't already
been reported. Or:</para>
</listitem>
<listitem>
<para>Email your bug report to
<Email>glasgow-haskell-bugs@haskell.org</Email>. </para>
</listitem>
</itemizedlist>
<sect2>
<title>What to put in a bug report</title>
<indexterm><primary>bug reports</primary><secondary>contents</secondary></indexterm>
<para>The name of the bug-reporting game is: facts, facts,
facts. Don't omit them because &ldquo;Oh, they won't be
interested&hellip;&rdquo;</para>
<orderedlist>
<listitem>
<para>What kind of machine are you running on, and exactly
what version of the operating system are you using?
(on a Unix system, <Command>uname -a</Command> or <Command>cat
/etc/motd</Command> will show the desired information.)</para>
</listitem>
<listitem>
<para> What version of GCC are you using? <Command>gcc
-v</Command> will tell you.</para>
</listitem>
<listitem>
<para> Run the sequence of compiles/runs that caused the
offending behaviour, capturing all the input/output in a
&ldquo;script&rdquo; (a UNIX command) or in an Emacs shell
window. We'd prefer to see the whole thing.</para>
</listitem>
<listitem>
<para> Be sure any Haskell compilations are run with a
<Option>-v</Option> (verbose) flag, so we can see exactly
what was run, what versions of things you have, etc.</para>
</listitem>
<listitem>
<para> What is the program behaviour that is wrong, in your
opinion?</para>
</listitem>
<listitem>
<para> If practical, please send enough source files for us
to duplicate the problem.</para>
</listitem>
<listitem>
<para> If you are a Hero and track down the problem in the
compilation-system sources, please send us patches relative
to a known released version of GHC, or whole files if you
prefer.</para>
</listitem>
</orderedlist>
</sect2>
</sect1>
<sect1 id="version-numbering">
<title>GHC version numbering policy</title>
<indexterm><primary>version, of ghc</primary></indexterm>
......
......@@ -1542,10 +1542,10 @@ which you can then display. For example, to run your program
<Para>
<Screen>
<prompt> ./a.out +RTS -qP -qp8
<prompt> grs2gr *.???.gr &#62; temp.gr # combine the 8 .gr files into one
<prompt> gr2ps -O temp.gr # cvt to .ps; output in temp.ps
<prompt> ghostview -seascape temp.ps # look at it!
<prompt>&dollar;</prompt> ./a.out +RTS -qP -qp8
<prompt>&dollar;</prompt> grs2gr *.???.gr &#62; temp.gr # combine the 8 .gr files into one
<prompt>&dollar;</prompt> gr2ps -O temp.gr # cvt to .ps; output in temp.ps
<prompt>&dollar;</prompt> ghostview -seascape temp.ps # look at it!
</Screen>
</Para>
......@@ -1654,7 +1654,7 @@ translates to 4K bytes, and for 64-bit machines, 8K bytes.)
</Para>
</ListItem>
</VarListEntry>
<!-- no more -- HWL
<!-- no more -HWL
<VarListEntry>
<Term><Option>-d</Option>:</Term>
<ListItem>
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment