diff options
| author | Simon Marlow <simonmar@microsoft.com> | 2006-04-07 02:05:11 +0000 |
|---|---|---|
| committer | Simon Marlow <simonmar@microsoft.com> | 2006-04-07 02:05:11 +0000 |
| commit | 0065d5ab628975892cea1ec7303f968c3338cbe1 (patch) | |
| tree | 8e2afe0ab48ee33cf95009809d67c9649573ef92 /docs/users_guide/gone_wrong.xml | |
| parent | 28a464a75e14cece5db40f2765a29348273ff2d2 (diff) | |
| download | haskell-0065d5ab628975892cea1ec7303f968c3338cbe1.tar.gz | |
Reorganisation of the source tree
Most of the other users of the fptools build system have migrated to
Cabal, and with the move to darcs we can now flatten the source tree
without losing history, so here goes.
The main change is that the ghc/ subdir is gone, and most of what it
contained is now at the top level. The build system now makes no
pretense at being multi-project, it is just the GHC build system.
No doubt this will break many things, and there will be a period of
instability while we fix the dependencies. A straightforward build
should work, but I haven't yet fixed binary/source distributions.
Changes to the Building Guide will follow, too.
Diffstat (limited to 'docs/users_guide/gone_wrong.xml')
| -rw-r--r-- | docs/users_guide/gone_wrong.xml | 213 |
1 files changed, 213 insertions, 0 deletions
diff --git a/docs/users_guide/gone_wrong.xml b/docs/users_guide/gone_wrong.xml new file mode 100644 index 0000000000..d31087c164 --- /dev/null +++ b/docs/users_guide/gone_wrong.xml @@ -0,0 +1,213 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<chapter id="wrong"> + <title>What to do when something goes wrong</title> + + <indexterm><primary>problems</primary></indexterm> + + <para>If you still have a problem after consulting this section, + then you may have found a <emphasis>bug</emphasis>—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—we love mail from irate users + :-!</para> + + <para>(<xref linkend="vs-Haskell-defn"/>, which describes Glasgow + Haskell's shortcomings vs. the Haskell language definition, may + also be of interest.)</para> + + <sect1 id="wrong-compiler"> + <title>When the compiler “does the wrong thing”</title> + + <indexterm><primary>compiler problems</primary></indexterm> + <indexterm><primary>problems with the compiler</primary></indexterm> + + <variablelist> + <varlistentry> + <term>“Help! The compiler crashed (or `panic'd)!”</term> + <listitem> + <para>These events are <emphasis>always</emphasis> bugs in + the GHC system—please report them.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>“This is a terrible error message.”</term> + <listitem> + <para>If you think that GHC could have produced a better + error message, please report it as a bug.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>“What about this warning from the C + compiler?”</term> + <listitem> + <para>For example: “…warning: `Foo' declared + `static' but never defined.” Unsightly, but shouldn't + be a problem.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Sensitivity to <filename>.hi</filename> interface files:</term> + <listitem> + <para>GHC is very sensitive about interface files. For + example, if it picks up a non-standard + <filename>Prelude.hi</filename> file, pretty terrible things + will happen. If you turn on + <option>-fno-implicit-prelude</option><indexterm><primary>-fno-implicit-prelude + option</primary></indexterm>, the compiler will almost + surely die, unless you know what you are doing.</para> + + <para>Furthermore, as sketched below, you may have big + problems running programs compiled using unstable + interfaces.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>“I think GHC is producing incorrect code”:</term> + <listitem> + <para>Unlikely :-) A useful be-more-paranoid option to give + to GHC is + <option>-dcore-lint</option><indexterm><primary>-dcore-lint + option</primary></indexterm>; this causes a + “lint” pass to check for errors (notably type + errors) after each Core-to-Core transformation pass. We run + with <option>-dcore-lint</option> on all the time; it costs + about 5% in compile time.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>“Why did I get a link error?”</term> + <listitem> + <para>If the linker complains about not finding + <literal>_<something>_fast</literal>, + then something is inconsistent: you probably didn't compile + modules in the proper dependency order.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>“Is this line number right?”</term> + <listitem> + <para>On this score, GHC usually does pretty well, + especially if you “allow” it to be off by one or + two. In the case of an instance or class declaration, the + line number may only point you to the declaration, not to a + specific method.</para> + + <para>Please report line-number errors that you find + particularly unhelpful.</para> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1 id="wrong-compilee"> + <title>When your program “does the wrong thing”</title> + + <indexterm><primary>problems running your program</primary></indexterm> + + <para>(For advice about overly slow or memory-hungry Haskell + programs, please see <xref + linkend="sooner-faster-quicker"/>).</para> + + <variablelist> + + <varlistentry> + <term>“Help! My program crashed!”</term> + <listitem> + <para>(e.g., a `segmentation fault' or `core dumped') + <indexterm><primary>segmentation + fault</primary></indexterm></para> + + <para>If your program has no foreign calls in it, and no + calls to known-unsafe functions (such as + <literal>unsafePerformIO</literal>) then a crash is always a + BUG in the GHC system, except in one case: If your program + is made of several modules, each module must have been + compiled after any modules on which it depends (unless you + use <filename>.hi-boot</filename> files, in which case these + <emphasis>must</emphasis> be correct with respect to the + module source).</para> + + <para>For example, if an interface is lying about the type + of an imported value then GHC may well generate duff code + for the importing module. <emphasis>This applies to pragmas + inside interfaces too!</emphasis> If the pragma is lying + (e.g., about the “arity” of a value), then duff + code may result. Furthermore, arities may change even if + types do not.</para> + + <para>In short, if you compile a module and its interface + changes, then all the modules that import that interface + <emphasis>must</emphasis> be re-compiled.</para> + + <para>A useful option to alert you when interfaces change is + <option>-hi-diffs</option><indexterm><primary>-hi-diffs + option</primary></indexterm>. It will run + <command>diff</command> on the changed interface file, + before and after, when applicable.</para> + + <para>If you are using <command>make</command>, GHC can + automatically generate the dependencies required in order to + make sure that every module <emphasis>is</emphasis> + up-to-date with respect to its imported interfaces. Please + see <xref linkend="sec-makefile-dependencies"/>.</para> + + <para>If you are down to your + last-compile-before-a-bug-report, we would recommend that + you add a <option>-dcore-lint</option> option (for extra + checking) to your compilation options.</para> + + <para>So, before you report a bug because of a core dump, + you should probably:</para> + +<screen> +% rm *.o # scrub your object files +% make my_prog # re-make your program; use -hi-diffs to highlight changes; + # as mentioned above, use -dcore-lint to be more paranoid +% ./my_prog ... # retry... +</screen> + + <para>Of course, if you have foreign calls in your program + then all bets are off, because you can trash the heap, the + stack, or whatever.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>“My program entered an `absent' argument.”</term> + <listitem> + <para>This is definitely caused by a bug in GHC. Please + report it (see <xref linkend="bug-reporting"/>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>“What's with this `arithmetic (or `floating') + exception' ”?</term> + <listitem> + <para><literal>Int</literal>, <literal>Float</literal>, and + <literal>Double</literal> arithmetic is + <emphasis>unchecked</emphasis>. Overflows, underflows and + loss of precision are either silent or reported as an + exception by the operating system (depending on the + platform). Divide-by-zero <emphasis>may</emphasis> cause an + untrapped exception (please report it if it does).</para> + </listitem> + </varlistentry> + + </variablelist> + </sect1> + +</chapter> + +<!-- Emacs stuff: + ;;; Local Variables: *** + ;;; mode: xml *** + ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** + ;;; End: *** + --> |