Today's doc hacking.
-<Sect1 id="options-debugging">
-<Title>Debugging the compiler
-</Title>
-
-<Para>
-<IndexTerm><Primary>debugging options (for GHC)</Primary></IndexTerm>
-</Para>
-
-<Para>
-HACKER TERRITORY. HACKER TERRITORY.
-(You were warned.)
-</Para>
-
-
-<Sect2 id="dumping-output">
-<Title>Dumping out compiler intermediate structures
-</Title>
-
-<Para>
-<IndexTerm><Primary>dumping GHC intermediates</Primary></IndexTerm>
-<IndexTerm><Primary>intermediate passes, output</Primary></IndexTerm>
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-hi</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-hi option</Primary></IndexTerm>
-<Emphasis>Do</Emphasis> generate an interface file. This would normally be used in
-conjunction with <Option>-noC</Option>, which turns off interface generation;
-thus: <Option>-noC -hi</Option>.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-dshow-passes</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-dshow-passes option</Primary></IndexTerm>
-Prints a message to stderr as each pass starts. Gives a warm but
-undoubtedly misleading feeling that GHC is telling you what's
-happening.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-<pass></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-ddump-<pass> options</Primary></IndexTerm>
-Make a debugging dump after pass <Literal><pass></Literal> (may be common enough to
-need a short form…). You can get all of these at once (<Emphasis>lots</Emphasis> of
-output) by using <Option>-ddump-all</Option>, or most of them with <Option>-ddump-most</Option>.
-Some of the most useful ones are:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-ddump-parsed</Option>:</Term>
-<ListItem>
-<Para>
-parser output
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-ddump-rn</Option>:</Term>
-<ListItem>
-<Para>
-renamer output
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-ddump-tc</Option>:</Term>
-<ListItem>
-<Para>
-typechecker output
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-ddump-types</Option>:</Term>
-<ListItem>
-<Para>
-Dump a type signature for each value defined at the top level
-of the module. The list is sorted alphabetically.
-Using <Option>-dppr-debug</Option> dumps a type signature for
-all the imported and system-defined things as well; useful
-for debugging the compiler.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-ddump-deriv</Option>:</Term>
-<ListItem>
-<Para>
-derived instances
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-ds</Option>:</Term>
-<ListItem>
-<Para>
-desugarer output
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-spec</Option>:</Term>
-<ListItem>
-<Para>
-output of specialisation pass
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-rules</Option>:</Term>
-<ListItem>
-<Para>
-dumps all rewrite rules (including those generated by the specialisation pass)
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-simpl</Option>:</Term>
-<ListItem>
-<Para>
-simplifer output (Core-to-Core passes)
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-usagesp</Option>:</Term>
-<ListItem>
-<Para>
-UsageSP inference pre-inf and output
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-cpranal</Option>:</Term>
-<ListItem>
-<Para>
-CPR analyser output
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-stranal</Option>:</Term>
-<ListItem>
-<Para>
-strictness analyser output
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-workwrap</Option>:</Term>
-<ListItem>
-<Para>
-worker/wrapper split output
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-occur-anal</Option>:</Term>
-<ListItem>
-<Para>
-`occurrence analysis' output
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-stg</Option>:</Term>
-<ListItem>
-<Para>
-output of STG-to-STG passes
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-absC</Option>:</Term>
-<ListItem>
-<Para>
-<Emphasis>un</Emphasis>flattened Abstract C
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-flatC</Option>:</Term>
-<ListItem>
-<Para>
-<Emphasis>flattened</Emphasis> Abstract C
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-realC</Option>:</Term>
-<ListItem>
-<Para>
-same as what goes to the C compiler
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-asm</Option>:</Term>
-<ListItem>
-<Para>
-assembly language from the native-code generator
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-<IndexTerm><Primary>-ddump-all option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-most option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-parsed option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-rn option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-tc option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-deriv option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-ds option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-simpl option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-cpranal option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-workwrap option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-rules option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-usagesp option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-stranal option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-occur-anal option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-spec option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-stg option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-absC option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-flatC option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-realC option</Primary></IndexTerm>
-<IndexTerm><Primary>-ddump-asm option</Primary></IndexTerm>
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-dverbose-simpl</Option> and <Option>-dverbose-stg</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-dverbose-simpl option</Primary></IndexTerm>
-<IndexTerm><Primary>-dverbose-stg option</Primary></IndexTerm>
-Show the output of the intermediate Core-to-Core and STG-to-STG
-passes, respectively. (<Emphasis>Lots</Emphasis> of output!) So: when we're
-really desperate:
-
-<Screen>
+<sect1 id="options-debugging">
+ <title>Debugging the compiler</title>
+
+ <indexterm><primary>debugging options (for GHC)</primary></indexterm>
+
+ <para>HACKER TERRITORY. HACKER TERRITORY. (You were warned.)</para>
+
+ <Sect2 id="dumping-output">
+ <title>Dumping out compiler intermediate structures</title>
+
+ <indexterm><primary>dumping GHC intermediates</primary></indexterm>
+ <indexterm><primary>intermediate passes, output</primary></indexterm>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-ddump-</option><replaceable>pass</replaceable></term>
+ <indexterm><primary><option>-ddump</option> options</primary></indexterm>
+ <listitem>
+ <para>Make a debugging dump after pass
+ <literal><pass></literal> (may be common enough to need
+ a short form…). You can get all of these at once
+ (<emphasis>lots</emphasis> of output) by using
+ <option>-ddump-all</option>, or most of them with
+ <option>-ddump-most</option>. Some of the most useful ones
+ are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-ddump-parsed</option>:</term>
+ <listitem>
+ <para>parser output</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-rn</option>:</term>
+ <listitem>
+ <para>renamer output</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-tc</option>:</term>
+ <listitem>
+ <para>typechecker output</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-types</option>:</term>
+ <listitem>
+ <para>Dump a type signature for each value defined at
+ the top level of the module. The list is sorted
+ alphabetically. Using <option>-dppr-debug</option>
+ dumps a type signature for all the imported and
+ system-defined things as well; useful for debugging the
+ compiler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-deriv</option>:</term>
+ <listitem>
+ <para>derived instances</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-ds</option>:</term>
+ <listitem>
+ <para>desugarer output</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-spec</option>:</term>
+ <listitem>
+ <para>output of specialisation pass</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-rules</option>:</term>
+ <listitem>
+ <para>dumps all rewrite rules (including those generated
+ by the specialisation pass)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-simpl</option>:</term>
+ <listitem>
+ <para>simplifer output (Core-to-Core passes)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-inlinings</option>:</term>
+ <listitem>
+ <para>inlining info from the simplifier</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-usagesp</option>:</term>
+ <listitem>
+ <para>UsageSP inference pre-inf and output</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-cpranal</option>:</term>
+ <listitem>
+ <para>CPR analyser output</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-stranal</option>:</term>
+ <listitem>
+ <para>strictness analyser output</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-cse</option>:</term>
+ <listitem>
+ <para>CSE pass output</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-workwrap</option>:</term>
+ <listitem>
+ <para>worker/wrapper split output</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-occur-anal</option>:</term>
+ <listitem>
+ <para>`occurrence analysis' output</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-sat</option>:</term>
+ <listitem>
+ <para>output of “saturate” pass</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-stg</option>:</term>
+ <listitem>
+ <para>output of STG-to-STG passes</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-absC</option>:</term>
+ <listitem>
+ <para><emphasis>un</emphasis>flattened Abstract C</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-flatC</option>:</term>
+ <listitem>
+ <para><emphasis>flattened</emphasis> Abstract C</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-realC</option>:</term>
+ <listitem>
+ <para>same as what goes to the C compiler</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-stix</option>:</term>
+ <listitem>
+ <para>native-code generator intermediate form</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-asm</option>:</term>
+ <listitem>
+ <para>assembly language from the native-code generator</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-bcos</option>:</term>
+ <listitem>
+ <para>byte code compiler output</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-foreign</option>:</term>
+ <listitem>
+ <para>dump foreign export stubs</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <indexterm><primary><option>-ddump-absC</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-bcos</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-cpranal</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-cse</option></primary></indexterm>
+
+ <indexterm><primary><option>-ddump-deriv</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-ds</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-flatC</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-foreign</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-inlinings</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-occur-anal</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-parsed</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-realC</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-rn</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-rules</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-sat</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-simpl</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-spec</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-stg</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-stix</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-stranal</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-tc</option></primary></indexterm>
+
+ <indexterm><primary><option>-ddump-usagesp</option></primary></indexterm>
+ <indexterm><primary><option>-ddump-workwrap</option></primary></indexterm>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-dverbose-core2core</option></term>
+ <term><option>-dverbose-stg2stg</option></term>
+ <indexterm><primary><option>-dverbose-core2core</option></primary></indexterm>
+ <indexterm><primary><option>-dverbose-stg2stg</option></primary></indexterm>
+ <listitem>
+ <para>Show the output of the intermediate Core-to-Core and
+ STG-to-STG passes, respectively. (<emphasis>Lots</emphasis>
+ of output!) So: when we're really desperate:</para>
+
+ <Screen>
% ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
</Screen>
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-simpl-iterations</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-ddump-simpl-iterations option</Primary></IndexTerm>
-Show the output of each <Emphasis>iteration</Emphasis> of the simplifier (each run of
-the simplifier has a maximum number of iterations, normally 4). Used
-when even <Option>-dverbose-simpl</Option> doesn't cut it.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-dppr-{user,debug</Option>}:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-dppr-user option</Primary></IndexTerm>
-<IndexTerm><Primary>-dppr-debug option</Primary></IndexTerm>
-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).
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-simpl-stats</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-ddump-simpl-stats option</Primary></IndexTerm>
-Dump statistics about how many of each kind
-of transformation too place. If you add <Option>-dppr-debug</Option> you get more detailed information.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-raw-asm</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-ddump-raw-asm option</Primary></IndexTerm>
-Dump out the assembly-language stuff, before the “mangler” gets it.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-ddump-rn-trace</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-ddump-rn-trace</Primary></IndexTerm>
-Make the renamer be *real* chatty about what it is upto.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-dshow-rn-stats</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-dshow-rn-stats</Primary></IndexTerm>
-Print out summary of what kind of information the renamer had to bring
-in.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-dshow-unused-imports</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-dshow-unused-imports</Primary></IndexTerm>
-Have the renamer report what imports does not contribute.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-</Sect2>
-
-<Sect2 id="checking-consistency">
-<Title>Checking for consistency
-</Title>
-
-<Para>
-<IndexTerm><Primary>consistency checks</Primary></IndexTerm>
-<IndexTerm><Primary>lint</Primary></IndexTerm>
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-dcore-lint</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-dcore-lint option</Primary></IndexTerm>
-Turn on heavyweight intra-pass sanity-checking within GHC, at Core
-level. (It checks GHC's sanity, not yours.)
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-dstg-lint</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-dstg-lint option</Primary></IndexTerm>
-Ditto for STG level.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-dusagesp-lint</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-dstg-lint option</Primary></IndexTerm>
-Turn on checks around UsageSP inference (<Option>-fusagesp</Option>). 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.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-</Sect2>
-
-<Sect2>
-<Title>How to read Core syntax (from some <Option>-ddump-*</Option> flags)</Title>
-
-<Para>
-<IndexTerm><Primary>reading Core syntax</Primary></IndexTerm>
-<IndexTerm><Primary>Core syntax, how to read</Primary></IndexTerm>
-</Para>
-
-<Para>
-Let's do this by commenting an example. It's from doing
-<Option>-ddump-ds</Option> on this code:
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-simpl-iterations</option>:</term>
+ <indexterm><primary><option>-ddump-simpl-iterations</option></primary></indexterm>
+ <listitem>
+ <para>Show the output of each <emphasis>iteration</emphasis>
+ of the simplifier (each run of the simplifier has a maximum
+ number of iterations, normally 4). Used when even
+ <option>-dverbose-simpl</option> doesn't cut it.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-dppr-debug</option></term>
+ <indexterm><primary><option>-dppr-debug</option></primary></indexterm>
+ <listitem>
+ <para>Debugging output is in one of several
+ “styles.” Take the printing of types, for
+ example. In the “user” style (the default), 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). This
+ flag makes debugging output appear in the more verbose debug
+ style.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-dppr-user-length</option></term>
+ <indexterm><primary><option>-dppr-user-length</option></primary></indexterm>
+ <listitem>
+ <para>In error messages, expressions are printed to a
+ certain “depth”, with subexpressions beyond the
+ depth replaced by ellipses. This flag sets the
+ depth.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-simpl-stats</option></term>
+ <indexterm><primary><option>-ddump-simpl-stats option</option></primary></indexterm>
+ <listitem>
+ <para>Dump statistics about how many of each kind of
+ transformation too place. If you add
+ <option>-dppr-debug</option> you get more detailed
+ information.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-rn-trace</option></term>
+ <indexterm><primary><option>-ddump-rn-trace</option></primary></indexterm>
+ <listitem>
+ <para>Make the renamer be *real* chatty about what it is
+ upto.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ddump-rn-stats</option></term>
+ <indexterm><primary><option>-dshow-rn-stats</option></primary></indexterm>
+ <listitem>
+ <para>Print out summary of what kind of information the renamer
+ had to bring in.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-dshow-unused-imports</option></term>
+ <indexterm><primary><option>-dshow-unused-imports</option></primary></indexterm>
+ <listitem>
+ <para>Have the renamer report what imports does not
+ contribute.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id="checking-consistency">
+ <title>Checking for consistency</title>
+
+ <indexterm><primary>consistency checks</primary></indexterm>
+ <indexterm><primary>lint</primary></indexterm>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-dcore-lint</option></term>
+ <indexterm><primary><option>-dcore-lint</option></primary></indexterm>
+ <listitem>
+ <para>Turn on heavyweight intra-pass sanity-checking within
+ GHC, at Core level. (It checks GHC's sanity, not yours.)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-dstg-lint</option>:</term>
+ <indexterm><primary><option>-dstg-lint</option></primary></indexterm>
+ <listitem>
+ <para>Ditto for STG level. (NOTE: currently doesn't work).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-dusagesp-lint</option>:</term>
+ <indexterm><primary><option>-dstg-lint</option></primary></indexterm>
+ <listitem>
+ <para>Turn on checks around UsageSP inference
+ (<option>-fusagesp</option>). 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.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>How to read Core syntax (from some <option>-ddump</option>
+ flags)</title>
+
+ <indexterm><primary>reading Core syntax</primary></indexterm>
+ <indexterm><primary>Core syntax, how to read</primary></indexterm>
+
+ <para>Let's do this by commenting an example. It's from doing
+ <option>-ddump-ds</option> on this code:
<ProgramListing>
skip2 m = m : skip2 (m+2)
</ProgramListing>
-</Para>
-
-<Para>
-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., <Literal>_</Literal> means “built-in type variable”;
-<Literal>t</Literal> means “from the typechecker”; <Literal>s</Literal> means “from the
-simplifier”; and so on. The `number' is printed fairly compactly in
-a `base-62' format, which everyone hates except me (WDP).
-</Para>
-
-<Para>
-Remember, everything has a “Unique” and it is usually printed out
-when debugging, in some form or another. So here we go…
-</Para>
-
-<Para>
+ 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., <literal>_</literal>
+ means “built-in type variable”; <literal>t</literal>
+ means “from the typechecker”; <literal>s</literal>
+ means “from the simplifier”; and so on. The `number'
+ is printed fairly compactly in a `base-62' format, which everyone
+ hates except me (WDP).</para>
+
+ <para>Remember, everything has a “Unique” and it is
+ usually printed out when debugging, in some form or another. So
+ here we go…</para>
+
<ProgramListing>
Desugared:
Main.skip2{-r1L6-} :: _forall_ a$_4 =>{{Num a$_4}} -> a$_4 -> [a$_4]
{- end CoRec -}
} in skip2.t3Ja
</ProgramListing>
-</Para>
-
-<Para>
-(“It's just a simple functional language” is an unregisterised
-trademark of Peyton Jones Enterprises, plc.)
-</Para>
-
-</Sect2>
-
-<Sect2 id="source-file-options">
-<Title>Command line options in source files
-</Title>
-
-<Para>
-<IndexTerm><Primary>source-file options</Primary></IndexTerm>
-</Para>
-
-<Para>
-Sometimes it is useful to make the connection between a source file
-and the command-line options it requires quite tight. For instance,
-if a (Glasgow) Haskell source file uses <Literal>casm</Literal>s, the C back-end
-often needs to be told about which header files to include. Rather than
-maintaining the list of files the source depends on in a
-<Filename>Makefile</Filename> (using the <Option>-#include</Option> command-line option), it is
-possible to do this directly in the source file using the <Literal>OPTIONS</Literal>
-pragma <IndexTerm><Primary>OPTIONS pragma</Primary></IndexTerm>:
-</Para>
-
-<Para>
-<ProgramListing>
-{-# OPTIONS -#include "foo.h" #-}
-module X where
-...
-</ProgramListing>
-</Para>
-
-<Para>
-<Literal>OPTIONS</Literal> pragmas are only looked for at the top of your source
-files, upto the first (non-literate,non-empty) line not containing
-<Literal>OPTIONS</Literal>. Multiple <Literal>OPTIONS</Literal> pragmas are recognised. Note
-that your command shell does not get to the source file options, they
-are just included literally in the array of command-line arguments
-the compiler driver maintains internally, so you'll be desperately
-disappointed if you try to glob etc. inside <Literal>OPTIONS</Literal>.
-</Para>
-
-<Para>
-NOTE: the contents of OPTIONS are prepended to the command-line
-options, so you <Emphasis>do</Emphasis> have the ability to override OPTIONS settings
-via the command line.
-</Para>
-
-<Para>
-It is not recommended to move all the contents of your Makefiles into
-your source files, but in some circumstances, the <Literal>OPTIONS</Literal> pragma
-is the Right Thing. (If you use <Option>-keep-hc-file-too</Option> and have OPTION
-flags in your module, the OPTIONS will get put into the generated .hc
-file).
-</Para>
-
-</Sect2>
+ <para>(“It's just a simple functional language” is an
+ unregisterised trademark of Peyton Jones Enterprises, plc.)</para>
+
+ </sect2>
<sect2 id="unreg">
<title>Unregisterised compilation</title>
- <sect1>
+ <sect1 id="flag-reference">
<title>Flag reference</title>
+ <para>This section is a quick-reference for GHC's command-line
+ flags. For each flag, we also list its static/dynamic status (see
+ <xref linkend="static-dynamic-flags">), and the flag's opposite
+ (if available).</para>
+
<sect2>
<title>Help and verbosity options (<xref linkend="options-help">)</title>
</thead>
<tbody>
<row>
- <entry><option>-cpp</option></entry>
- <entry>Run the C pre-processor on the Haskell source</entry>
- <entry>dynamic</entry>
- <entry>-</entry>
- </row>
- <row>
<entry><option>-E</option></entry>
<entry>Stop after preprocessing (<literal>.hspp</literal> file)</entry>
<entry>static</entry>
<entry>static</entry>
<entry>-</entry>
</row>
- <row>
- <entry><option>-fasm</option></entry>
- <entry>Use the native code generator</entry>
- <entry>dynamic</entry>
- <entry>-fvia-C</entry>
- </row>
- <row>
- <entry><option>-fvia-C</option></entry>
- <entry>Compile via C</entry>
- <entry>dynamic</entry>
- <entry>-fasm</entry>
- </row>
</tbody>
</tgroup>
</informaltable>
<entry><option>-no-recomp</option></entry>
<entry>Turn off recompilation checking</entry>
<entry>static</entry>
- <entry>-recomp</entry>
+ <entry><option>-recomp</option></entry>
</row>
</tbody>
</tgroup>
</thead>
<tbody>
<row>
+ <entry><option>-cpp</option></entry>
+ <entry>Run the C pre-processor on Haskell source files</entry>
+ <entry>dynamic</entry>
+ <entry>-</entry>
+ </row>
+ <row>
<entry><option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional></entry>
<entry>Define a symbol in the C pre-processor</entry>
<entry>dynamic</entry>
</sect2>
<sect2>
+ <title>Code generation options (<xref linkend="options-codegen">)</title>
+
+ <informaltable>
+ <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <thead>
+ <row>
+ <entry>Flag</entry>
+ <entry>Description</entry>
+ <entry>Static/Dynamic</entry>
+ <entry>Reverse</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><option>-fasm</option></entry>
+ <entry>Use the native code generator</entry>
+ <entry>dynamic</entry>
+ <entry>-fvia-C</entry>
+ </row>
+ <row>
+ <entry><option>-fvia-C</option></entry>
+ <entry>Compile via C</entry>
+ <entry>dynamic</entry>
+ <entry>-fasm</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2>
<title>Linking options (<xref linkend="options-linker">)</title>
<informaltable>
<entry>-</entry>
</row>
<row>
- <entry><option>-mlong-calls</option></entry>
- <entry>(HPPA only) enable long call support</entry>
- <entry>static</entry>
- <entry>-</entry>
- </row>
- <row>
<entry><option>-monly-[32]-regs</option></entry>
<entry>(x86 only) give some registers back to the C compiler</entry>
<entry>dynamic</entry>
</row>
<row>
<entry><option>-ddump-foreign</option></entry>
- <entry>Dump FFI-related output</entry>
+ <entry>Dump <literal>foreign export</literal> stubs</entry>
<entry>dynamic</entry>
<entry>-</entry>
</row>
<entry>-</entry>
</row>
<row>
- <entry><option>-dshow-passes</option></entry>
- <entry>(equivalent to <option>-v2</option>)</entry>
- <entry>dynamic</entry>
- <entry>-</entry>
- </row>
- <row>
<entry><option>-ddump-rn-trace</option></entry>
<entry>Trace renamer</entry>
<entry>dynamic</entry>
<entry>dynamic</entry>
<entry>-</entry>
</row>
+ <row>
+ <entry><option>-unreg</option></entry>
+ <entry>Enable unregisterised compilation</entry>
+ <entry>static</entry>
+ <entry>-</entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
, ( "H" , HasArg (setHeapSize . fromIntegral . decodeSize) )
, ( "Rghc-timing" , NoArg (enableTimingStats) )
- , ( "unreg" , NoArg (addNoDups v_Ways WayUnreg) )
+ -Bdir
-->
<!-- Emacs stuff:
--- /dev/null
+<chapter>
+ <title>Using GHCi</title>
+
+ <para>ToDo</para>
+</chapter>
+
+<!-- Emacs stuff:
+ ;;; Local Variables: ***
+ ;;; mode: sgml ***
+ ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
+ ;;; End: ***
+ -->
<indexterm><primary>C pre-processor options</primary></indexterm>
<indexterm><primary>cpp, pre-processing with</primary></indexterm>
- <para>The C pre-processor <command>cpp</command> is run over
- your Haskell code only if the <option>-cpp</option> option
- <indexterm><primary>-cpp option</primary></indexterm> is given.
- Unless you are building a large system with significant doses of
- conditional compilation, you really shouldn't need it.</para>
-
<variablelist>
<varlistentry>
+ <term><option>-cpp</option></term>
+ <indexterm><primary><option>-cpp</option></primary></indexterm>
+ <listitem>
+ <para>The C pre-processor <command>cpp</command> is run
+ over your Haskell code only if the <option>-cpp</option>
+ option <indexterm><primary>-cpp
+ option</primary></indexterm> is given. Unless you are
+ building a large system with significant doses of
+ conditional compilation, you really shouldn't need
+ it.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional></term>
<indexterm><primary><option>-D</option></primary></indexterm>
<listitem>
<indexterm><primary>C compiler options</primary></indexterm>
<indexterm><primary>GCC options</primary></indexterm>
- <informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
- <thead>
- <row>
- <entry>Flag</entry>
- <entry>Description</entry>
- <entry>Static/Dynamic</entry>
- <entry>Reverse</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><option>-#include</option> <replaceable>file</replaceable></entry>
- <entry>Include <replaceable>file</replaceable> when
- compiling the <filename>.hc</filename> file</entry>
- <entry>dynamic</entry>
- <entry>-</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
<para>If you are compiling with lots of foreign calls, you may
need to tell the C compiler about some
<literal>#include</literal> files. There is no real pretty
</sect2>
+ <sect2 id="options-codegen">
+ <title>Options affecting code generation</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-fasm</option></term>
+ <indexterm><primary><option>-fasm</option></primary></indexterm>
+ <listitem>
+ <para>Use GHC's native code generator rather than
+ compiling via C. This will compile faster (up to twice as
+ fast), but may produce code that is slightly slower than
+ compiling via C. <option>-fasm</option> is the default
+ when optimisation is off (see <xref
+ linkend="options-optimise">).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fvia-C</option></term>
+ <indexterm><primary><option>-fvia-C</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Compile via C instead of using the native code
+ generator. This is default for optimised compilations,
+ and on architectures for which GHC doesn't have a native
+ code generator.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
<sect2 id="options-linker">
<title>Options affecting linking</title>
<para>This section describes how GHC supports separate
compilation.</para>
-
+
<sect2 id="hi-files">
<title>Interface files</title>
</Address>
</BookInfo>
-&license
-&intro
-&installing
-&using
-&prof
-&sooner
-&lang-features
-&ffi-chap
-&wrong
-&utils
-&win32-dll
+&license;
+&intro;
+&installing;
+&using;
+&ghci;
+&prof;
+&sooner;
+&lang-features;
+&ffi-chap;
+&wrong;
+&utils;
+&win32-dll;
+<!ENTITY ghci SYSTEM "ghci.sgml">
<!ENTITY flags SYSTEM "flags.sgml">
<!ENTITY license SYSTEM "license.sgml">
<!ENTITY intro SYSTEM "intro.sgml" >
-<Chapter id="using-GHC">
-<title>Using GHC
-</title>
+<chapter>
+ <title>Using GHC</title>
-<para>
-<IndexTerm><Primary>GHC, using</Primary></IndexTerm>
-<IndexTerm><Primary>using GHC</Primary></IndexTerm>
-GHC is a command-line compiler: in order to compile a Haskell program,
-GHC must be invoked on the source file(s) by typing a command to the
-shell. The steps involved in compiling a program can be automated
-using the <command>make</command> tool (this is especially useful if the program
-consists of multiple source files which depend on each other). This
-section describes how to use GHC from the command-line.
-</para>
+ <indexterm><primary>GHC, using</primary></indexterm>
+ <indexterm><primary>using GHC</primary></indexterm>
-<Sect1 id="command-line-structure">
-<title>Overall command-line structure
-</title>
+ <para>GHC can work in one of three “modes”:</para>
-<para>
-<IndexTerm><Primary>structure, command-line</Primary></IndexTerm>
-<IndexTerm><Primary>command-line structure</Primary></IndexTerm>
-</para>
+ <variablelist>
+ <varlistentry>
+ <term><cmdsynopsis><command>ghc</command>
+ <arg choice=plain>--interactive</arg>
+ </cmdsynopsis></term>
+ <indexterm><primary>interactive mode</primary>
+ </indexterm>
+ <indexterm><primary>ghci</primary>
+ </indexterm>
+ <listitem>
+ <para>Interactive mode, which is also available as
+ <command>ghci</command>. Interactive mode is described in
+ more detail in <xref linkend="ghci">.</para>
+ </listitem>
+ </varlistentry>
-<para>
-An invocation of GHC takes the following form:
-</para>
+ <varlistentry>
+ <term><cmdsynopsis><command>ghc</command>
+ <arg choice=plain>--make</arg>
+ </cmdsynopsis></term>
+ <indexterm><primary>make mode</primary>
+ </indexterm>
+ <indexterm><primary><option>--make</option></primary>
+ </indexterm>
+ <listitem>
+ <para>In this mode, GHC will build a multi-module Haskell
+ program automatically, figuring out dependencies for itself.
+ If you have a straightforward Haskell program, this is
+ likely to be much easier, and faster, than using
+ <command>make</command>.</para>
+ </listitem>
+ </varlistentry>
-<para>
+ <varlistentry>
+ <term><cmdsynopsis>
+ <command>ghc</command>
+ <group>
+ <arg>-E</arg>
+ <arg>-C</arg>
+ <arg>-S</arg>
+ <arg>-c</arg>
+ </group>
+ </cmdsynopsis></term>
+ <indexterm><primary><option>--make</option></primary>
+ </indexterm>
+ <listitem>
+ <para>This is the traditional batch-compiler mode, in which
+ GHC can compile source files one at a time, or link objects
+ together into an executable.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <sect1>
+ <title>Options overview</title>
+
+ <para>GHC's behaviour is controlled by
+ <firstterm>options</firstterm>, which for historical reasons are
+ also sometimes referred to as command-line flags or arguments.
+ Options can be specified in three ways:</para>
+
+ <sect2>
+ <title>Command-line arguments</title>
+
+ <indexterm><primary>structure, command-line</primary></indexterm>
+ <indexterm><primary>command-line</primary><secondary>arguments</secondary></indexterm>
+ <indexterm><primary>arguments</primary><secondary>command-line</secondary></indexterm>
+
+ <para>An invocation of GHC takes the following form:</para>
<Screen>
ghc [argument...]
</Screen>
-</para>
+ <para>Command-line arguments are either options or file names.</para>
+
+ <para>Command-line options begin with <literal>-</literal>.
+ They may <emphasis>not</emphasis> be grouped:
+ <option>-vO</option> is different from <option>-v -O</option>.
+ Options need not precede filenames: e.g., <literal>ghc *.o -o
+ foo</literal>. All options are processed and then applied to
+ all files; you cannot, for example, invoke <literal>ghc -c -O1
+ Foo.hs -O2 Bar.hs</literal> to apply different optimisation
+ levels to the files <filename>Foo.hs</filename> and
+ <filename>Bar.hs</filename>.</para>
+ </sect2>
-<para>
-Command-line arguments are either options or file names.
-</para>
+ <Sect2 id="source-file-options">
+ <title>Command line options in source files</title>
+
+ <indexterm><primary>source-file options</primary></indexterm>
+
+ <para>Sometimes it is useful to make the connection between a
+ source file and the command-line options it requires quite
+ tight. For instance, if a Haskell source file uses GHC
+ extensions, it will always need to be compiled with the
+ <option>-fglasgow-exts</option> option. Rather than maintaining
+ the list of per-file options in a <filename>Makefile</filename>,
+ it is possible to do this directly in the source file using the
+ <literal>OPTIONS</literal> pragma <indexterm><primary>OPTIONS
+ pragma</primary></indexterm>:</para>
-<para>
-Command-line options begin with <literal>-</literal>. They may <emphasis>not</emphasis> be
-grouped: <option>-vO</option> is different from <option>-v -O</option>. Options need not
-precede filenames: e.g., <command>ghc *.o -o foo</command>. All options are
-processed and then applied to all files; you cannot, for example, invoke
-<command>ghc -c -O1 Foo.hs -O2 Bar.hs</command> to apply different optimisation
-levels to the files <filename>Foo.hs</filename> and <filename>Bar.hs</filename>. For conflicting
-options, e.g., <option>-c -S</option>, we reserve the right to do anything we
-want. (Usually, the last one applies.)
-</para>
+<ProgramListing>
+{-# OPTIONS -fglasgow-exts #-}
+module X where
+...
+</ProgramListing>
+
+ <para><literal>OPTIONS</literal> pragmas are only looked for at
+ the top of your source files, upto the first
+ (non-literate,non-empty) line not containing
+ <literal>OPTIONS</literal>. Multiple <literal>OPTIONS</literal>
+ pragmas are recognised. Note that your command shell does not
+ get to the source file options, they are just included literally
+ in the array of command-line arguments the compiler driver
+ maintains internally, so you'll be desperately disappointed if
+ you try to glob etc. inside <literal>OPTIONS</literal>.</para>
+
+ <para>NOTE: the contents of OPTIONS are prepended to the
+ command-line options, so you <emphasis>do</emphasis> have the
+ ability to override OPTIONS settings via the command
+ line.</para>
+
+ <para>It is not recommended to move all the contents of your
+ Makefiles into your source files, but in some circumstances, the
+ <literal>OPTIONS</literal> pragma is the Right Thing. (If you
+ use <option>-keep-hc-file-too</option> and have OPTION flags in
+ your module, the OPTIONS will get put into the generated .hc
+ file).</para>
+ </sect2>
-</Sect1>
+ <sect2>
+ <title>Setting options in GHCi</title>
-<Sect1 id="file-suffixes">
-<title>Meaningful file suffixes
-</title>
+ <para>Options may also be modified from within GHCi, using the
+ <literal>:set</literal> command. See <xref linkend="ghci-set">
+ for more details.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="static-dynamic-flags">
+ <title>Static vs. Dynamic options</title>
+ <indexterm><primary>static</primary><secondary>options</secondary>
+ </indexterm>
+ <indexterm><primary>dynamic</primary><secondary>options</secondary>
+ </indexterm>
+
+ <para>Each of GHC's command line options is classified as either
+ <firstterm>static</firstterm> or <firstterm>dynamic</firstterm>.
+ A static flag may only be specified on the command line, whereas a
+ dynamic flag may also be given in an <literal>OPTIONS</literal>
+ pragma in a source file or set from the GHCi command-line with
+ <literal>:set</literal>.</para>
+
+ <para>As a rule of thumb, all the language options are dynamic, as
+ are the warning options and the debugging options. The rest are
+ static, with the notable exceptions of <option>-v</option>,
+ <option>-cpp</option>, <option>-fasm</option>,
+ <option>-fvia-C</option>, and <option>-#include</option>.
+
+ The flag reference tables (<xref linkend="flag-reference">) lists
+ the status of each flag.</para>
+ </sect1>
-<para>
-<IndexTerm><Primary>suffixes, file</Primary></IndexTerm>
-<IndexTerm><Primary>file suffixes for GHC</Primary></IndexTerm>
-</para>
+ <sect1 id="file-suffixes">
+ <title>Meaningful file suffixes</title>
-<para>
-File names with “meaningful” suffixes (e.g., <filename>.lhs</filename> or <filename>.o</filename>)
-cause the “right thing” to happen to those files.
-</para>
+ <indexterm><primary>suffixes, file</primary></indexterm>
+ <indexterm><primary>file suffixes for GHC</primary></indexterm>
-<para>
-<VariableList>
+ <para>File names with “meaningful” suffixes (e.g.,
+ <filename>.lhs</filename> or <filename>.o</filename>) cause the
+ “right thing” to happen to those files.</para>
-<VarListEntry>
-<Term><filename>.lhs</filename>:</Term>
-<ListItem>
-<para>
-<IndexTerm><Primary>lhs suffix</Primary></IndexTerm>
-A “literate Haskell” module.
-</para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><filename>.hs</filename>:</Term>
-<ListItem>
-<para>
-A not-so-literate Haskell module.
-</para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><filename>.hi</filename>:</Term>
-<ListItem>
-<para>
-A Haskell interface file, probably compiler-generated.
-</para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><filename>.hc</filename>:</Term>
-<ListItem>
-<para>
-Intermediate C file produced by the Haskell compiler.
-</para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><filename>.c</filename>:</Term>
-<ListItem>
-<para>
-A C file not produced by the Haskell compiler.
-</para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><filename>.s</filename>:</Term>
-<ListItem>
-<para>
-An assembly-language source file, usually
-produced by the compiler.
-</para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><filename>.o</filename>:</Term>
-<ListItem>
-<para>
-An object file, produced by an assembler.
-</para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</para>
+ <variablelist>
-<para>
-Files with other suffixes (or without suffixes) are passed straight
-to the linker.
-</para>
+ <varlistentry>
+ <term><filename>.lhs</filename></term>
+ <indexterm><primary><literal>lhs</literal> suffix</primary></indexterm>
+ <listitem>
+ <para>A “literate Haskell” module.</para>
+ </listitem>
+ </varlistentry>
-</Sect1>
+ <varlistentry>
+ <term><filename>.hs</filename></term>
+ <listitem>
+ <para>A not-so-literate Haskell module.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>.hi</filename></term>
+ <listitem>
+ <para>A Haskell interface file, probably
+ compiler-generated.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>.hc</filename></term>
+ <listitem>
+ <para>Intermediate C file produced by the Haskell
+ compiler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>.c</filename></term>
+ <listitem>
+ <para>A C file not produced by the Haskell
+ compiler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>.s</filename></term>
+ <listitem>
+ <para>An assembly-language source file, usually produced by
+ the compiler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>.o</filename></term>
+ <listitem>
+ <para>An object file, produced by an assembler.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Files with other suffixes (or without suffixes) are passed
+ straight to the linker.</para>
+
+ </sect1>
<sect1 id="options-help">
<title>Help and verbosity options</title>
</varlistentry>
</variablelist>
</sect1>
-
- <Sect1 id="options-order">
- <title>Running the right phases in the right order</title>
- <indexterm><primary>order of passes in GHC</primary></indexterm>
- <indexterm><primary>pass ordering in GHC</primary></indexterm>
+ <sect1 id="make-mode">
+ <title>Using <command>ghc</command> <option>--make</option></title>
+ <indexterm><primary><option>--make</option></primary>
+ </indexterm>
+ <indexterm><primary>separate compilation</primary>
+ </indexterm>
+
+ <para>When given the <option>--make</option> option, GHC will
+ build a multi-module Haskell program by following dependencies
+ from a single root module (usually <literal>Main</literal>). For
+ example, if your <literal>Main</literal> module is in a file
+ called <filename>Main.hs</filename>, you could compile and link
+ the program like this:</para>
+
+<screen>
+ghc --make Main.hs
+</screen>
+
+ <para>The command line must contain one source file or module
+ name; GHC will figure out all the modules in the program by
+ following the imports from this initial module. It will then
+ attempt to compile each module which is out of date, and finally
+ if the top module is <literal>Main</literal>, the program
+ will also be linked into an executable.</para>
+
+ <para>The main advantages to using <literal>ghc --make</literal>
+ over traditional <literal>Makefile</literal>s are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>GHC doesn't have to be restarted for each compilation,
+ which means it can cache information between compilations.
+ Compiling a muli-module program with <literal>ghc
+ --make</literal> can be up to twice as fast as running
+ <literal>ghc</literal> individually on each source
+ file.</para>
+ </listitem>
+ <listitem>
+ <para>You don't have to write a
+ <literal>Makefile</literal>.</para>
+ </listitem>
+ <indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary>
+ </indexterm>
+ <listitem>
+ <para>GHC re-calculates the dependencies each time it is
+ invoked, so the dependencies never get out of sync with the
+ source.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Any of the command-line options described in the rest of
+ this chapter can be used with <option>--make</option>, but note
+ that any options you give on the command line will apply to all
+ the source files compiled, so if you want any options to apply to
+ a single source file only, you'll need to use an
+ <literal>OPTIONS</literal> pragma (see <xref
+ linkend="source-file-options">).</para>
+
+ <para>If the program needs to be linked with additional objects
+ (say, some auxilliary C code), these can be specified on the
+ command line as usual.</para>
+ </sect1>
+
+ <Sect1 id="options-order">
+ <title>GHC without <option>--make</option></title>
- <para>The basic task of the <command>ghc</command> driver is to
- run each input file through the right phases (compiling, linking,
- etc.).</para>
+ <para>Without <option>--make</option>, GHC will compile one or
+ more source files given on the command line.</para>
- <para>The first phase to run is determined by the input-file
+ <para>The first phase to run is determined by each input-file
suffix, and the last phase is determined by a flag. If no
relevant flag is present, then go all the way through linking.
This table summarises:</para>
-<InformalTable>
-<TGroup Cols="4">
-<ColSpec Align="Left">
-<ColSpec Align="Left">
-<ColSpec Align="Left">
-<ColSpec Align="Left">
-<TBody>
-
-<Row>
-<Entry>Phase of the compilation system</Entry>
-<Entry>Suffix saying “start here”</Entry>
-<Entry>Flag saying “stop after”</Entry>
-<Entry>(suffix of) output file</Entry>
-</Row>
-
-<Row>
-<Entry>
-literate pre-processor </Entry>
-<Entry> .lhs </Entry>
-<Entry> - </Entry>
-<Entry> .hs </Entry>
-</Row>
-<Row>
-<Entry>
-C pre-processor (opt.) </Entry>
-<Entry> .hs (with <literal>-cpp</literal>) </Entry>
-<Entry> -E </Entry>
-<Entry> .hspp </Entry>
-</Row>
-<Row>
-<Entry>
-Haskell compiler </Entry>
-<Entry> .hs </Entry>
-<Entry> -C, -S </Entry>
-<Entry> .hc, .s </Entry>
-</Row>
-<Row>
-<Entry>
-C compiler (opt.) </Entry>
-<Entry> .hc or .c </Entry>
-<Entry> -S </Entry>
-<Entry> .s </Entry>
-</Row>
-<Row>
-<Entry>
-assembler </Entry>
-<Entry> .s </Entry>
-<Entry> -c </Entry>
-<Entry> .o </Entry>
-</Row>
-<Row>
-<Entry>
-linker </Entry>
-<Entry> other </Entry>
-<Entry> - </Entry>
-<Entry> a.out </Entry>
-</Row>
-</TBody>
-</TGroup>
-</InformalTable>
-
-<IndexTerm><Primary>-C option</Primary></IndexTerm>
-<IndexTerm><Primary>-S option</Primary></IndexTerm>
-<IndexTerm><Primary>-c option</Primary></IndexTerm>
-
-<para>
-Thus, a common invocation would be: <command>ghc -c Foo.hs</command>
-</para>
-
-<para>
-Note: What the Haskell compiler proper produces depends on whether a
-native-code generator is used (producing assembly language) or not
-(producing C).
-</para>
-
- <para>NOTE: the option <option>-E</option><IndexTerm><Primary>-E
+ <informaltable>
+ <tgroup cols="4">
+ <colspec align="left">
+ <colspec align="left">
+ <colspec align="left">
+ <colspec align="left">
+
+ <thead>
+ <row>
+ <entry>Phase of the compilation system</entry>
+ <entry>Suffix saying “start here”</entry>
+ <entry>Flag saying “stop after”</entry>
+ <entry>(suffix of) output file</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>literate pre-processor</entry>
+ <entry><literal>.lhs</literal></entry>
+ <entry>-</entry>
+ <entry><literal>.hs</literal></entry>
+ </row>
+
+ <row>
+ <entry>C pre-processor (opt.)
+ </entry>
+ <entry><literal>.hs</literal> (with
+ <option>-cpp</option>)</entry>
+ <entry><option>-E</option></entry>
+ <entry><literal>.hspp</literal></entry>
+ </row>
+
+ <row>
+ <entry>Haskell compiler</entry>
+ <entry><literal>.hs</literal></entry>
+ <entry><option>-C</option>, <option>-S</option></entry>
+ <entry><literal>.hc</literal>, <literal>.s</literal></entry>
+ </row>
+
+ <row>
+ <entry>C compiler (opt.)</entry>
+ <entry><literal>.hc</literal> or <literal>.c</literal></entry>
+ <entry><option>-S</option></entry>
+ <entry><literal>.s</literal></entry>
+ </row>
+
+ <row>
+ <entry>assembler</entry>
+ <entry><literal>.s</literal></entry>
+ <entry><option>-c</option></entry>
+ <entry><literal>.o</literal></entry>
+ </row>
+
+ <row>
+ <entry>linker</entry>
+ <entry><replaceable>other</replaceable></entry>
+ <entry>-</entry>
+ <entry><filename>a.out</filename></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <indexterm><primary><option>-C</option></primary></indexterm>
+ <indexterm><primary><option>-E</option></primary></indexterm>
+ <indexterm><primary><option>-S</option></primary></indexterm>
+ <indexterm><primary><option>-c</option></primary></indexterm>
+
+ <para>Thus, a common invocation would be: <literal>ghc -c
+ Foo.hs</literal></para>
+
+ <para>Note: What the Haskell compiler proper produces depends on
+ whether a native-code generator<indexterm><primary>native-code
+ generator</primary></indexterm> is used (producing assembly
+ language) or not (producing C). See <xref
+ linkend="options-codegen"> for more details.</para>
+
+ <para>Note: C pre-processing is optional, the
+ <option>-ccp</option><indexterm><primary><option>-cpp</option></primary>
+ </indexterm>flag turns it on. See <xref
+ linkend="c-pre-processor"> for more details.</para>
+
+ <para>Note: The option <option>-E</option><IndexTerm><Primary>-E
option</Primary></IndexTerm> runs just the pre-processing passes
of the compiler, dumping the result in a file. Note that this
- differs from all GHCs prior to version 4.11, in which the result
- was dumped to the standard output. If used in conjunction with
- -cpp, the output is the code blocks of the original (literal)
- source after having put it through the grinder that is the C
- pre-processor. Sans <option>-cpp</option>, the output is the
- de-litted version of the original source.</para>
-
- <para>The following options also affect which phases get run:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>-cpp</option></term>
- <indexterm><primary><option>-cpp</option></primary></indexterm>
- <listitem>
- <para>Run the C pre-processor on the Haskell source before
- compiling it. See <xref linkend="c-pre-processor"> for more
- details.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-fasm</option></term>
- <indexterm><primary><option>-fasm</option></primary></indexterm>
- <listitem>
- <para>Use GHC's native code generator rather than compiling
- via C. This will compile faster (up to twice as fast), but
- may produce code that is slightly slower than compiling via
- C. <option>-fasm</option> is the default when optimisation
- is off (see <xref linkend="options-optimise">).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-fvia-C</option></term>
- <indexterm><primary><option>-fvia-C</option></primary>
- </indexterm>
- <listitem>
- <para>Compile via C instead of using the native code
- generator. This is default for optimised compilations, and
- on architectures for which GHC doesn't have a native code
- generator.</para>
- </listitem>
- </varlistentry>
- </variablelist>
+ differs from the previous behaviour of dumping the file to
+ standard output.</para>
</sect1>
<sect1 id="options-output">
<ColSpec Align="Left">
<TBody>
-<Row>
-<Entry><KeyCombo><KeyCap>Control</KeyCap><KeyCap>D</KeyCap></KeyCombo></Entry>
-<Entry>exit <command>pvm</command>, leaving it running</Entry>
-</Row>
-
-<Row>
-<Entry><command>halt</command></Entry>
-<Entry>kill off this “parallel machine” & exit</Entry>
-</Row>
-
-<Row>
-<Entry><command>add <host></command></Entry>
-<Entry>add <command><host></command> as a processor</Entry>
-</Row>
-
-<Row>
-<Entry><command>delete <host></command></Entry>
-<Entry>delete <command><host></command></Entry>
-</Row>
-
-<Row>
-<Entry><command>reset</command></Entry>
-<Entry>kill what's going, but leave PVM up</Entry>
-</Row>
-
-<Row>
-<Entry><command>conf</command></Entry>
-<Entry>list the current configuration</Entry>
-</Row>
-
-<Row>
-<Entry><command>ps</command></Entry>
-<Entry>report processes' status</Entry>
-</Row>
-
-<Row>
-<Entry><command>pstat <pid></command></Entry>
-<Entry>status of a particular process</Entry>
-</Row>
+<row>
+<entry><KeyCombo><KeyCap>Control</KeyCap><KeyCap>D</KeyCap></KeyCombo></entry>
+<entry>exit <command>pvm</command>, leaving it running</entry>
+</row>
+
+<row>
+<entry><command>halt</command></entry>
+<entry>kill off this “parallel machine” & exit</entry>
+</row>
+
+<row>
+<entry><command>add <host></command></entry>
+<entry>add <command><host></command> as a processor</entry>
+</row>
+
+<row>
+<entry><command>delete <host></command></entry>
+<entry>delete <command><host></command></entry>
+</row>
+
+<row>
+<entry><command>reset</command></entry>
+<entry>kill what's going, but leave PVM up</entry>
+</row>
+
+<row>
+<entry><command>conf</command></entry>
+<entry>list the current configuration</entry>
+</row>
+
+<row>
+<entry><command>ps</command></entry>
+<entry>report processes' status</entry>
+</row>
+
+<row>
+<entry><command>pstat <pid></command></entry>
+<entry>status of a particular process</entry>
+</row>
</TBody>
</TGroup>
</varlistentry>
<varlistentry>
- <term><option>-mlong-calls</option>:</term>
- <listitem>
- <para>(HPPA machines)<indexterm><primary>-mlong-calls option
- (HPPA only)</primary></indexterm> Means to pass the
- like-named option to GCC. Required for Very Big modules,
- maybe. (Probably means you're in trouble…)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><option>-monly-[32]-regs</option>:</term>
<listitem>
<para>(iX86 machines)<indexterm><primary>-monly-N-regs
</sect1>
-&runtime
-&debug
-&flags
+&runtime;
+&debug;
+&flags;
</Chapter>
projects / ghc-hetmet.git / commitdiff