(You were warned.)
</Para>
-<Sect2 id="replacing-phases">
-<Title>Replacing the program for one or more phases.
-</Title>
-
-<Para>
-<IndexTerm><Primary>GHC phases, changing</Primary></IndexTerm>
-<IndexTerm><Primary>phases, changing GHC</Primary></IndexTerm>
-You may specify that a different program be used for one of the phases
-of the compilation system, in place of whatever the driver <Literal>ghc</Literal> has
-wired into it. For example, you might want to try a different
-assembler. The
-<Literal>-pgm<phase-code><program-name></Literal><IndexTerm><Primary>-pgm<phase><stuff>
-option</Primary></IndexTerm> option to <Literal>ghc</Literal> will cause it to use <Literal><program-name></Literal>
-for phase <Literal><phase-code></Literal>, where the codes to indicate the phases are:
-</Para>
-
-<Para>
-<InformalTable>
-<TGroup Cols="2">
-<ColSpec Align="Left" Colsep="0">
-<ColSpec Align="Left" Colsep="0">
-<TBody>
-<Row>
-<Entry><Emphasis>code</Emphasis> </Entry>
-<Entry><Emphasis>phase</Emphasis> </Entry>
-</Row>
-
-<Row>
-<Entry>
-L </Entry>
-<Entry> literate pre-processor </Entry>
-</Row>
-<Row>
-<Entry>
-P </Entry>
-<Entry> C pre-processor (if -cpp only) </Entry>
-</Row>
-<Row>
-<Entry>
-C </Entry>
-<Entry> Haskell compiler </Entry>
-</Row>
-<Row>
-<Entry>
-c </Entry>
-<Entry> C compiler</Entry>
-</Row>
-<Row>
-<Entry>
-a </Entry>
-<Entry> assembler </Entry>
-</Row>
-<Row>
-<Entry>
-l </Entry>
-<Entry> linker </Entry>
-</Row>
-<Row>
-<Entry>
-dep </Entry>
-<Entry> Makefile dependency generator </Entry>
-</Row>
-
-</TBody>
-
-</TGroup>
-</InformalTable>
-</Para>
-
-</Sect2>
-
-<Sect2 id="forcing-options-through">
-<Title>Forcing options to a particular phase.
-</Title>
-
-<Para>
-<IndexTerm><Primary>forcing GHC-phase options</Primary></IndexTerm>
-</Para>
-
-<Para>
-The preceding sections describe driver options that are mostly
-applicable to one particular phase. You may also <Emphasis>force</Emphasis> a
-specific option <Literal><option></Literal> to be passed to a particular phase
-<Literal><phase-code></Literal> by feeding the driver the option
-<Literal>-opt<phase-code><option></Literal>.<IndexTerm><Primary>-opt<phase><stuff>
-option</Primary></IndexTerm> The codes to indicate the phases are the same as in the
-previous section.
-</Para>
-
-<Para>
-So, for example, to force an <Literal>-Ewurble</Literal> option to the assembler, you
-would tell the driver <Literal>-opta-Ewurble</Literal> (the dash before the E is
-required).
-</Para>
-
-<Para>
-Besides getting options to the Haskell compiler with <Literal>-optC<blah></Literal>,
-you can get options through to its runtime system with
-<Literal>-optCrts<blah></Literal><IndexTerm><Primary>-optCrts<blah> option</Primary></IndexTerm>.
-</Para>
-
-<Para>
-So, for example: when I want to use my normal driver but with my
-profiled compiler binary, I use this script:
-
-<ProgramListing>
-#! /bin/sh
-exec /local/grasp_tmp3/simonpj/ghc-BUILDS/working-alpha/ghc/driver/ghc \
- -pgmC/local/grasp_tmp3/simonpj/ghc-BUILDS/working-hsc-prof/hsc \
- -optCrts-i0.5 \
- -optCrts-PT \
- "$@"
-</ProgramListing>
-
-</Para>
-
-</Sect2>
<Sect2 id="dumping-output">
<Title>Dumping out compiler intermediate structures
<VariableList>
<VarListEntry>
-<Term><Literal>-noC</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-noC option</Primary></IndexTerm>
-Don't bother generating C output <Emphasis>or</Emphasis> an interface file. Usually
-used in conjunction with one or more of the <Literal>-ddump-*</Literal> options; for
-example: <Literal>ghc -noC -ddump-simpl Foo.hs</Literal>
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-hi</Literal>:</Term>
+<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 <Literal>-noC</Literal>, which turns off interface generation;
-thus: <Literal>-noC -hi</Literal>.
+conjunction with <Option>-noC</Option>, which turns off interface generation;
+thus: <Option>-noC -hi</Option>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-dshow-passes</Literal>:</Term>
+<Term><Option>-dshow-passes</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-dshow-passes option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-<pass></Literal>:</Term>
+<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 <Literal>-ddump-all</Literal>, or most of them with <Literal>-ddump-most</Literal>.
+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><Literal>-ddump-parsed</Literal>:</Term>
+<Term><Option>-ddump-parsed</Option>:</Term>
<ListItem>
<Para>
-oarser output
+parser output
</Para>
</ListItem>
</VarListEntry>
+
<VarListEntry>
-<Term><Literal>-ddump-rn</Literal>:</Term>
+<Term><Option>-ddump-rn</Option>:</Term>
<ListItem>
<Para>
renamer output
</Para>
</ListItem>
</VarListEntry>
+
<VarListEntry>
-<Term><Literal>-ddump-tc</Literal>:</Term>
+<Term><Option>-ddump-tc</Option>:</Term>
<ListItem>
<Para>
typechecker output
</Para>
</ListItem>
</VarListEntry>
+
<VarListEntry>
-<Term><Literal>-ddump-deriv</Literal>:</Term>
+<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
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-ds</Literal>:</Term>
+<Term><Option>-ddump-ds</Option>:</Term>
<ListItem>
<Para>
desugarer output
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-spec</Literal>:</Term>
+<Term><Option>-ddump-spec</Option>:</Term>
<ListItem>
<Para>
output of specialisation pass
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-rules</Literal>:</Term>
+<Term><Option>-ddump-rules</Option>:</Term>
<ListItem>
<Para>
dumps all rewrite rules (including those generated by the specialisation pass)
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-simpl</Literal>:</Term>
+<Term><Option>-ddump-simpl</Option>:</Term>
<ListItem>
<Para>
simplifer output (Core-to-Core passes)
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-usagesp</Literal>:</Term>
+<Term><Option>-ddump-usagesp</Option>:</Term>
<ListItem>
<Para>
UsageSP inference pre-inf and output
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-cpranal</Literal>:</Term>
+<Term><Option>-ddump-cpranal</Option>:</Term>
<ListItem>
<Para>
CPR analyser output
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-stranal</Literal>:</Term>
+<Term><Option>-ddump-stranal</Option>:</Term>
<ListItem>
<Para>
strictness analyser output
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-workwrap</Literal>:</Term>
+<Term><Option>-ddump-workwrap</Option>:</Term>
<ListItem>
<Para>
worker/wrapper split output
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-occur-anal</Literal>:</Term>
+<Term><Option>-ddump-occur-anal</Option>:</Term>
<ListItem>
<Para>
`occurrence analysis' output
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-stg</Literal>:</Term>
+<Term><Option>-ddump-stg</Option>:</Term>
<ListItem>
<Para>
output of STG-to-STG passes
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-absC</Literal>:</Term>
+<Term><Option>-ddump-absC</Option>:</Term>
<ListItem>
<Para>
<Emphasis>un</Emphasis>flattened Abstract C
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-flatC</Literal>:</Term>
+<Term><Option>-ddump-flatC</Option>:</Term>
<ListItem>
<Para>
<Emphasis>flattened</Emphasis> Abstract C
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-realC</Literal>:</Term>
+<Term><Option>-ddump-realC</Option>:</Term>
<ListItem>
<Para>
same as what goes to the C compiler
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-asm</Literal>:</Term>
+<Term><Option>-ddump-asm</Option>:</Term>
<ListItem>
<Para>
assembly language from the native-code generator
</ListItem>
</VarListEntry>
</VariableList>
-</Para>
-
-<Para>
<IndexTerm><Primary>-ddump-all option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-most option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-parsed option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-dverbose-simpl</Literal> and <Literal>-dverbose-stg</Literal>:</Term>
+<Term><Option>-dverbose-simpl</Option> and <Option>-dverbose-stg</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-dverbose-simpl option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-simpl-iterations</Literal>:</Term>
+<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 <Literal>-dverbose-simpl</Literal> doesn't cut it.
+when even <Option>-dverbose-simpl</Option> doesn't cut it.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-dppr-{user,debug</Literal>}:</Term>
+<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
+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
+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).
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-simpl-stats</Literal>:</Term>
+<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 <Literal>-dppr-debug</Literal> you get more detailed information.
+of transformation too place. If you add <Option>-dppr-debug</Option> you get more detailed information.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-raw-asm</Literal>:</Term>
+<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.
+Dump out the assembly-language stuff, before the “mangler” gets it.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-rn-trace</Literal>:</Term>
+<Term><Option>-ddump-rn-trace</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-ddump-rn-trace</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-dshow-rn-stats</Literal>:</Term>
+<Term><Option>-dshow-rn-stats</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-dshow-rn-stats</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-dshow-unused-imports</Literal>:</Term>
+<Term><Option>-dshow-unused-imports</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-dshow-unused-imports</Primary></IndexTerm>
<VariableList>
<VarListEntry>
-<Term><Literal>-dcore-lint</Literal>:</Term>
+<Term><Option>-dcore-lint</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-dcore-lint option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-dstg-lint</Literal>:</Term>
+<Term><Option>-dstg-lint</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-dstg-lint option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-dusagesp-lint</Literal>:</Term>
+<Term><Option>-dusagesp-lint</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-dstg-lint option</Primary></IndexTerm>
-Turn on checks around UsageSP inference (<Literal>-fusagesp</Literal>). This verifies
+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
</Sect2>
<Sect2>
-<Title>How to read Core syntax (from some <Literal>-ddump-*</Literal> flags)</Title>
+<Title>How to read Core syntax (from some <Option>-ddump-*</Option> flags)</Title>
<Para>
<IndexTerm><Primary>reading Core syntax</Primary></IndexTerm>
<Para>
Let's do this by commenting an example. It's from doing
-<Literal>-ddump-ds</Literal> on this code:
+<Option>-ddump-ds</Option> on this code:
<ProgramListing>
skip2 m = m : skip2 (m+2)
<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
+“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
+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
+Remember, everything has a “Unique” and it is usually printed out
when debugging, in some form or another. So here we go…
</Para>
</Para>
<Para>
-(``It's just a simple functional language'' is an unregisterised
+(“It's just a simple functional language” is an unregisterised
trademark of Peyton Jones Enterprises, plc.)
</Para>
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
-<Literal>Makefile</Literal> (using the <Literal>-#include</Literal> command-line option), it is
+<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>
NOTE: the contents of OPTIONS are prepended to the command-line
-options, so you *do* have the ability to override OPTIONS settings
+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 <Literal>-keep-hc-file-too</Literal> and have OPTION
+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>
+ <sect2 id="unreg">
+ <title>Unregisterised compilation</title>
+ <indexterm><primary>unregisterised compilation</primary></indexterm>
+
+ <para>The term "unregisterised" really means "compile via vanilla
+ C", disabling some of the platform-specific tricks that GHC
+ normally uses to make programs go faster. When compiling
+ unregisterised, GHC simply generates a C file which is compiled
+ via gcc.</para>
+
+ <para>Unregisterised compilation can be useful when porting GHC to
+ a new machine, since it reduces the prerequisite tools to
+ <command>gcc</command>, <command>as</command>, and
+ <command>ld</command> and nothing more, and furthermore the amount
+ of platform-specific code that needs to be written in order to get
+ unregisterised compilation going is usually fairly small.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-unreg</option>:</term>
+ <indexterm><primary><option>-unreg</option></primary></indexterm>
+ <listitem>
+ <para>Compile via vanilla ANSI C only, turning off
+ platform-specific optimisations. NOTE: in order to use
+ <option>-unreg</option>, you need to have a set of libraries
+ (including the RTS) built for unregisterised compilation.
+ This amounts to building GHC with way "u" enabled.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
</Sect1>
+
+<!-- Emacs stuff:
+ ;;; Local Variables: ***
+ ;;; mode: sgml ***
+ ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter" "sect1") ***
+ ;;; End: ***
+ -->
projects / ghc-hetmet.git / blobdiff