-<Chapter id="wrong">
-<Title>What to do when something goes wrong
-</Title>
-
-<Para>
-<IndexTerm><Primary>problems</Primary></IndexTerm>
-</Para>
-
-<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>
-
-<Para>
-<IndexTerm><Primary>compiler problems</Primary></IndexTerm>
-<IndexTerm><Primary>problems with the compiler</Primary></IndexTerm>
-</Para>
-
-<Para>
-<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>“The compiler ran out of heap (or stack) when compiling itself!”</Term>
-<ListItem>
-<Para>
-It happens. We try to supply reasonable <Option>-H<n></Option> flags for
-<Filename>ghc/compiler/</Filename> and <Filename>ghc/lib/</Filename>, but GHC's memory consumption
-can vary by platform (e.g., on a 64-bit machine).
-</Para>
-
-<Para>
-Just say <Command>make all EXTRA_HC_OPTS=-H<a reasonable number></Command> and see
-how you get along.
-</Para>
-
-<Para>
-Note that this is less likely to happen if you are compiling with GHC
-4.00 or later, since the introduction of the dynamically expanding
-heap.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>“The compiler died with a pattern-matching error.”</Term>
-<ListItem>
-<Para>
-This is a bug just as surely as a “panic.” Please report it.
-</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 these `trace' messages from GHC?”</Term>
-<ListItem>
-<Para>
-Almost surely not a problem. About some specific cases…
-<VariableList>
-
-<VarListEntry>
-<Term>Simplifier still going after N iterations:</Term>
-<ListItem>
-<Para>
-Sad, but harmless. You can change the number with a
-<Option>-fmax-simplifier-iterations<N></Option><IndexTerm><Primary>-fmax-simplifier-iterations<N> option</Primary></IndexTerm> option (no space);
-and you can see what actions took place in each iteration by
-turning on the <Option>-fshow-simplifier-progress</Option>
-<IndexTerm><Primary>-fshow-simplifier-progress option</Primary></IndexTerm> option.
-</Para>
-
-<Para>
-If the simplifier definitely seems to be “looping,” please report
-it.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</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>
-</Para>
-
-</Sect1>
-
-<Sect1 id="wrong-compilee">
-<Title>When your program “does the wrong thing”
-</Title>
-
-<Para>
-<IndexTerm><Primary>problems running your program</Primary></IndexTerm>
-</Para>
-
-<Para>
-(For advice about overly slow or memory-hungry Haskell programs,
-please see <XRef LinkEnd="sooner-faster-quicker">).
-</Para>
-
-<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, 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:
+<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
% ./my_prog ... # retry...
</Screen>
-</Para>
-
-<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>
-
-<Para>
-If you are interested in hard-core debugging of a crashing
-GHC-compiled program, please see <XRef LinkEnd="hard-core-debug">.
-</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
-architecture). Divide-by-zero <Emphasis>may</Emphasis> cause an untrapped
-exception (please report it if it does).
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-</Sect1>
-
-<Sect1 id="hard-core-debug">
-<Title>Hard-core debugging of GHC-compiled programs
-</Title>
-
-<Para>
-<IndexTerm><Primary>debugging, hard-core</Primary></IndexTerm>
-</Para>
-
-<Para>
-If your program is crashing, you should almost surely file a bug
-report, as outlined in <xref linkend="bug-reporting">.
-</Para>
-
-<Para>
-This section suggests ways to Make Further Progress Anyway.
-</Para>
-
-<Para>
-The first thing to establish is: Is it a garbage-collection (GC) bug?
-Try your program with a very large heap and a <Option>-Sstderr</Option> RTS
-flag.
-
-<ItemizedList>
-<ListItem>
-
-<Para>
-If it crashes <Emphasis>without</Emphasis> garbage-collecting, then it is
-definitely <Emphasis>not</Emphasis> a GC bug.
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-If you can make it crash with one heap size but not with another, then
-it <Emphasis>probably is</Emphasis> a GC bug.
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-If it crashes with the normal collector, but not when you force
-two-space collection (<Option>-G1</Option> runtime flag), then it
-<Emphasis>probably is</Emphasis> a GC bug.
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-
-<Para>
-If it <Emphasis>is</Emphasis> a GC bug, you may be able to avoid it by
-using a particular heap size or by using a <Option>-G1</Option>
-runtime flag. (But don't forget to report the bug!!!)
-</Para>
-
-<Para>
-ToDo: more here?
-</Para>
-
-</Sect1>
-
-</Chapter>
+ <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>
+
+ <para>If you are interested in hard-core debugging of a
+ crashing GHC-compiled program, please see <xref
+ linkend="hard-core-debug">.</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: ***
projects / ghc-hetmet.git / commitdiff