</Para>
<Para>
-File names with ``meaningful'' suffixes (e.g., <Filename>.lhs</Filename> or <Filename>.o</Filename>)
-cause the ``right thing'' to happen to those files.
+File names with “meaningful” suffixes (e.g., <Filename>.lhs</Filename> or <Filename>.o</Filename>)
+cause the “right thing” to happen to those files.
</Para>
<Para>
<ListItem>
<Para>
<IndexTerm><Primary>lhs suffix</Primary></IndexTerm>
-A ``literate Haskell'' module.
+A “literate Haskell” module.
</Para>
</ListItem>
</VarListEntry>
<Row>
<Entry>Phase of the compilation system</Entry>
-<Entry>Suffix saying ``start here''</Entry>
-<Entry>Flag saying ``stop after''</Entry>
+<Entry>Suffix saying “start here”</Entry>
+<Entry>Flag saying “stop after”</Entry>
<Entry>(suffix of) output file</Entry>
</Row>
</Para>
<Para>
-Note: this ``feature'' can be counterintuitive:
+Note: this “feature” can be counterintuitive:
<Command>ghc -C -o foo.o foo.hs</Command> will put the intermediate C code in the
file <Filename>foo.o</Filename>, name notwithstanding!
</Para>
normally put in the same directory as their corresponding input file
came from. You may specify that they be put in another directory
using the <Option>-odir <dir></Option><IndexTerm><Primary>-odir <dir> option</Primary></IndexTerm> (the
-``Oh, dear'' option). For example:
+“Oh, dear” option). For example:
</Para>
<Para>
generally likely to indicate bugs in your program. These are:
<Option>-fwarn-overlpapping-patterns</Option>, <Option>-fwarn-duplicate-exports</Option>, and
<Option>-fwarn-missing-methods</Option>. The following flags are simple ways to
-select standard ``packages'' of warnings:
+select standard “packages” of warnings:
</Para>
<Para>
<ListItem>
<Para>
<IndexTerm><Primary>-i<dirs> option</Primary></IndexTerm>This flag
-prepends a colon-separated list of <Filename>dirs</Filename> to the ``import
-directories'' list.
+prepends a colon-separated list of <Filename>dirs</Filename> to the “import
+directories” list.
See also <XRef LinkEnd="recomp"> for the significance of using
relative and absolute pathnames in the <Option>-i</Option> list.
</Para>
<Term><Option>-i</Option></Term>
<ListItem>
<Para>
-resets the ``import directories'' list back to nothing.
+resets the “import directories” list back to nothing.
</Para>
</ListItem>
</VarListEntry>
<Para>
<IndexTerm><Primary>-syslib <lib> option</Primary></IndexTerm>
If you are using a system-supplied non-Prelude library (e.g., the
-POSIX library), just use a <Option>-syslib posix</Option> option (for example). The
-right interface files should then be available. <XRef LinkEnd="ghc-prelude"> lists the
-libraries available by this mechanism.
+POSIX library), just use a <Option>-syslib posix</Option> option (for
+example). The right interface files should then be available. The
+accompanying HsLibs document lists the libraries available by this
+mechanism.
</Para>
</ListItem>
</VarListEntry>
</Para>
<Para>
-The <Filename>.hi</Filename> files from GHC contain ``usage'' information which changes
+The <Filename>.hi</Filename> files from GHC contain “usage” information which changes
often and uninterestingly. If you really want to see these changes
reported, you need to use the
<Option>-hi-diffs-with-usages</Option><IndexTerm><Primary>-hi-diffs-with-usages option</Primary></IndexTerm>
<Title>The recompilation checker
</Title>
-<Para>
<IndexTerm><Primary>recompilation checker</Primary></IndexTerm>
-</Para>
<Para>
-In the olden days, GHC compared the newly-generated <Filename>.hi</Filename> file with
-the previous version; if they were identical, it left the old one
-alone and didn't change its modification date. In consequence,
-importers of a module with an unchanged output <Filename>.hi</Filename> file were not
+<variablelist>
+<VarListEntry>
+<Term><Option>-recomp</Option></Term>
+<IndexTerm><Primary><option>-recomp</option> option</Primary></IndexTerm>
+<ListItem>
+<Para>
+(On by default) Turn on recompilation checking. This will stop
+compilation early, leaving an existing <filename>.o</filename> file in
+place, if it can be determined that the module does not need to be
recompiled.
</Para>
+</ListItem>
+</VarListEntry>
+<VarListEntry>
+<Term><Option>-no-recomp</Option></Term>
+<IndexTerm><Primary><option>-recomp</option> option</Primary></IndexTerm>
+<ListItem>
+<Para>
+Turn off recompilation checking.
+</Para>
+</ListItem>
+</VarListEntry>
+</VariableList>
+</Para>
+
+<Para>
+In the olden days, GHC compared the newly-generated
+<Filename>.hi</Filename> file with the previous version; if they were
+identical, it left the old one alone and didn't change its
+modification date. In consequence, importers of a module with an
+unchanged output <Filename>.hi</Filename> file were not recompiled.
+</Para>
<Para>
-This doesn't work any more. In our earlier example, module <Literal>C</Literal> does
-not import module <Literal>A</Literal> directly, yet changes to <Filename>A.hi</Filename> should force a
-recompilation of <Literal>C</Literal>. And some changes to <Literal>A</Literal> (changing the
-definition of a function that appears in an inlining of a function
-exported by <Literal>B</Literal>, say) may conceivably not change <Filename>B.hi</Filename> one jot. So
+This doesn't work any more. In our earlier example, module
+<Literal>C</Literal> does not import module <Literal>A</Literal>
+directly, yet changes to <Filename>A.hi</Filename> should force a
+recompilation of <Literal>C</Literal>. And some changes to
+<Literal>A</Literal> (changing the definition of a function that
+appears in an inlining of a function exported by <Literal>B</Literal>,
+say) may conceivably not change <Filename>B.hi</Filename> one jot. So
now…
</Para>
signature within the interface file. It also keeps in every interface
file a list of the version numbers of everything it used when it last
compiled the file. If the source file's modification date is earlier
-than the <Filename>.o</Filename> file's date (i.e. the source hasn't changed since the
-file was last compiled), GHC will be clever. It compares the version
-numbers on the things it needs this time with the version numbers on
-the things it needed last time (gleaned from the interface file of the
-module being compiled); if they are all the same it stops compiling
-rather early in the process saying ``Compilation IS NOT required''.
-What a beautiful sight!
-</Para>
-
-<Para>
-GHC <Emphasis>only</Emphasis> keeps detailed dependency information for ``user'' modules,
-not for ``library'' modules. It distinguishes the two by a hack: a module
-whose <Filename>.hi</Filename> file has an absolute path name is considered a library module,
-while a relative path name indicates a user module. So if you have a
-multi-directory application, use <Emphasis>relative</Emphasis> path names in your
-<Option>-i</Option> path, to force GHC to record detailed dependency information.
-Use absolute path names only for directories containing slowly-changing
+than the <Filename>.o</Filename> file's date (i.e. the source hasn't
+changed since the file was last compiled), and the
+<option>-recomp</option> is given on the command line, GHC will be
+clever. It compares the version numbers on the things it needs this
+time with the version numbers on the things it needed last time
+(gleaned from the interface file of the module being compiled); if
+they are all the same it stops compiling rather early in the process
+saying “Compilation IS NOT required”. What a beautiful
+sight!
+</Para>
+
+<Para>
+GHC <Emphasis>only</Emphasis> keeps detailed dependency information
+for “user” modules, not for “Prelude” modules.
+It distinguishes Prelude modules because their names start with
+"Prel", so don't start your modules that way!
+
+<!-- April 2000: hack disabled. Now we use a different hack!
+
+It distinguishes the two by a hack: a module whose
+<Filename>.hi</Filename> file has an absolute path name is considered
+a library module, while a relative path name indicates a user module.
+So if you have a multi-directory application, use
+<Emphasis>relative</Emphasis> path names in your <Option>-i</Option>
+path, to force GHC to record detailed dependency information. Use
+absolute path names only for directories containing slowly-changing
library modules.
</Para>
<Para>
-A path is considered ``absolute'' if it starts with ``<Filename>/</Filename>'', or
-``<Filename>A:/</Filename>'', or ``<Filename>A:\</Filename>'' (or ``<Filename>B:/</Filename>'', ``<Filename>B:\</Filename>'' etc).
+A path is considered “absolute” if it starts with
+“<Filename>/</Filename>”, or
+“<Filename>A:/</Filename>”, or
+“<Filename>A:\</Filename>” (or
+“<Filename>B:/</Filename>”,
+“<Filename>B:\</Filename>” etc).
</Para>
+-->
<Para>
Patrick Sansom had a workshop paper about how all this is done (though
-the details have changed quite a bit). <ULink URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink>) if you want a copy.
+the details have changed quite a bit). <ULink URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a copy.
</Para>
</Sect2>
<Para>
You may have to type <Command>make</Command> more than once for the dependencies
to have full effect. However, a <Command>make</Command> run that does nothing
-<Emphasis>does</Emphasis> mean ``everything's up-to-date.''
+<Emphasis>does</Emphasis> mean “everything's up-to-date.”
</Para>
</ListItem>
<Para>
This scheme will work with mutually-recursive modules but,
-again, it may take multiple iterations to ``settle.''
+again, it may take multiple iterations to “settle.”
</Para>
</ListItem>
</Para>
<Para>
-The number ``1'' after ``__interface A'' gives the version number of module A;
-it is incremented whenever anything in A's interface file changes. The ``404'' is
+The number “1” after “__interface A” gives the version number of module A;
+it is incremented whenever anything in A's interface file changes. The “404” is
the version number of the interface file <Emphasis>syntax</Emphasis>; we change it when
we change the syntax of interface files so that you get a better error message when
you try to read an old-format file with a new-format compiler.
</Para>
<Para>
-The number ``1'' at the beginning of a declaration is the <Emphasis>version
+The number “1” at the beginning of a declaration is the <Emphasis>version
number</Emphasis> of that declaration: for the purposes of <Filename>.hi-boot</Filename> files
these can all be set to 1. All names must be fully qualified with the
<Emphasis>original</Emphasis> module that an object comes from: for example, the
</Para>
<Para>
-The <Option>-O*</Option> options specify convenient ``packages'' of optimisation
+The <Option>-O*</Option> options specify convenient “packages” of optimisation
flags; the <Option>-f*</Option> options described later on specify
<Emphasis>individual</Emphasis> optimisations to be turned on/off; the <Option>-m*</Option>
options specify <Emphasis>machine-specific</Emphasis> optimisations to be turned
</Para>
<Sect2 id="optimise-pkgs">
-<Title><Option>-O*</Option>: convenient ``packages'' of optimisation flags.
+<Title><Option>-O*</Option>: convenient “packages” of optimisation flags.
</Title>
<Para>
<Para>
There are <Emphasis>many</Emphasis> options that affect the quality of code
produced by GHC. Most people only have a general goal, something like
-``Compile quickly'' or ``Make my program run like greased lightning.''
-The following ``packages'' of optimisations (or lack thereof) should
+“Compile quickly” or “Make my program run like greased lightning.”
+The following “packages” of optimisations (or lack thereof) should
suffice.
</Para>
<Para>
-Once you choose a <Option>-O*</Option> ``package,'' stick with it—don't chop and
+Once you choose a <Option>-O*</Option> “package,” stick with it—don't chop and
change. Modules' interfaces <Emphasis>will</Emphasis> change with a shift to a new
<Option>-O*</Option> option, and you may have to recompile a large chunk of all
importing modules before your program can again be run
<VarListEntry>
<Term>No <Option>-O*</Option>-type option specified:</Term>
+<IndexTerm><Primary>-O* not specified</Primary></IndexTerm>
<ListItem>
<Para>
-<IndexTerm><Primary>-O* not specified</Primary></IndexTerm>
-This is taken to mean: ``Please compile quickly; I'm not over-bothered
-about compiled-code quality.'' So, for example: <Command>ghc -c Foo.hs</Command>
+This is taken to mean: “Please compile quickly; I'm not over-bothered
+about compiled-code quality.” So, for example: <Command>ghc -c Foo.hs</Command>
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-O</Option> or <Option>-O1</Option>:</Term>
-<ListItem>
-<Para>
<IndexTerm><Primary>-O option</Primary></IndexTerm>
<IndexTerm><Primary>-O1 option</Primary></IndexTerm>
-<IndexTerm><Primary>optimise normally</Primary></IndexTerm>
-Means: ``Generate good-quality code without taking too long about it.''
-Thus, for example: <Command>ghc -c -O Main.lhs</Command>
+<IndexTerm><Primary>optimise</Primary><secondary>normally</secondary></IndexTerm>
+<ListItem>
+<Para>
+Means: “Generate good-quality code without taking too long about
+it.” Thus, for example: <Command>ghc -c -O Main.lhs</Command>
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-O2</Option>:</Term>
+<IndexTerm><Primary>-O2 option</Primary></IndexTerm>
+<IndexTerm><Primary>optimise</Primary><secondary>aggressively</secondary></IndexTerm>
<ListItem>
<Para>
-<IndexTerm><Primary>-O2 option</Primary></IndexTerm>
-<IndexTerm><Primary>optimise aggressively</Primary></IndexTerm>
-Means: ``Apply every non-dangerous optimisation, even if it means
-significantly longer compile times.''
+Means: “Apply every non-dangerous optimisation, even if it means
+significantly longer compile times.”
</Para>
<Para>
-The avoided ``dangerous'' optimisations are those that can make
+The avoided “dangerous” optimisations are those that can make
runtime or space <Emphasis>worse</Emphasis> if you're unlucky. They are
normally turned on or off individually.
</Para>
</VarListEntry>
<VarListEntry>
<Term><Option>-O2-for-C</Option>:</Term>
-<ListItem>
-<Para>
<IndexTerm><Primary>-O2-for-C option</Primary></IndexTerm>
<IndexTerm><Primary>gcc, invoking with -O2</Primary></IndexTerm>
-</Para>
-
+<ListItem>
<Para>
Says to run GCC with <Option>-O2</Option>, which may be worth a few percent in
execution speed. Don't forget <Option>-fvia-C</Option>, lest you use the native-code
</VarListEntry>
<VarListEntry>
<Term><Option>-Onot</Option>:</Term>
-<ListItem>
-<Para>
<IndexTerm><Primary>-Onot option</Primary></IndexTerm>
<IndexTerm><Primary>optimising, reset</Primary></IndexTerm>
-</Para>
-
+<ListItem>
<Para>
-This option will make GHC ``forget'' any <Option>-O</Option>ish options it has seen so
-far. Sometimes useful; for example: <Command>make all EXTRA_HC_OPTS=-Onot</Command>.
+This option will make GHC “forget” any
+<Option>-O</Option>ish options it has seen so far. Sometimes useful;
+for example: <Command>make all
+EXTRA_HC_OPTS=-Onot</Command>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-Ofile <file></Option>:</Term>
-<ListItem>
-<Para>
<IndexTerm><Primary>-Ofile <file> option</Primary></IndexTerm>
<IndexTerm><Primary>optimising, customised</Primary></IndexTerm>
-</Para>
-
+<ListItem>
<Para>
-For those who need <Emphasis>absolute</Emphasis> control over <Emphasis>exactly</Emphasis>
-what options are used (e.g., compiler writers, sometimes :-), a list
-of options can be put in a file and then slurped in with <Option>-Ofile</Option>.
+For those who need <Emphasis>absolute</Emphasis> control over
+<Emphasis>exactly</Emphasis> what options are used (e.g., compiler
+writers, sometimes :-), a list of options can be put in a file and
+then slurped in with <Option>-Ofile</Option>.
</Para>
<Para>
-In that file, comments are of the <Literal>#</Literal>-to-end-of-line variety; blank
-lines and most whitespace is ignored.
+In that file, comments are of the
+<Literal>#</Literal>-to-end-of-line variety; blank lines and most
+whitespace is ignored.
</Para>
<Para>
</Para>
<Para>
-The easiest way to see what <Option>-O</Option> (etc.) ``really mean'' is to run with
+The easiest way to see what <Option>-O</Option> (etc.) “really mean” is to run with
<Option>-v</Option>, then stand back in amazement. Alternatively, just look at the
<Literal>HsC_minus<blah></Literal> lists in the GHC driver script.
</Para>
</Para>
<Para>
-Here are some ``dangerous'' optimisations you <Emphasis>might</Emphasis> want to try:
+Here are some “dangerous” optimisations you <Emphasis>might</Emphasis> want to try:
<VariableList>
<VarListEntry>
<IndexTerm><Primary>unfolding, controlling</Primary></IndexTerm>
(Default: 30) By raising or lowering this number, you can raise or
lower the amount of pragmatic junk that gets spewed into interface
-files. (An unfolding has a ``size'' that reflects the cost in terms
-of ``code bloat'' of expanding that unfolding in another module. A
+files. (An unfolding has a “size” that reflects the cost in terms
+of “code bloat” of expanding that unfolding in another module. A
bigger function would be assigned a bigger cost.)
</Para>
</ListItem>
<Para>
OK, folks, these magic numbers `30', `8', and '2' are mildly
-arbitrary; they are of the ``seem to be OK'' variety. The `8' is the
+arbitrary; they are of the “seem to be OK” variety. The `8' is the
more critical one; it's what determines how eager GHC is about
expanding unfoldings.
</Para>
<Para>
This option causes all constructor fields which are marked strict
-(i.e. ``!'') to be unboxed or unpacked if possible. For example:
+(i.e. “!”) to be unboxed or unpacked if possible. For example:
</Para>
<Para>
<ListItem>
<Para>
(iX86 machines)<IndexTerm><Primary>-monly-N-regs option (iX86 only)</Primary></IndexTerm>
-GHC tries to ``steal'' four registers from GCC, for performance
+GHC tries to “steal” four registers from GCC, for performance
reasons; it almost always works. However, when GCC is compiling some
modules with four stolen registers, it will crash, probably saying:
</Para>
<Para>
-A small word of warning: <Option>-cpp</Option> is not friendly to ``string
-gaps''.<IndexTerm><Primary>-cpp vs string gaps</Primary></IndexTerm><IndexTerm><Primary>string gaps vs
+A small word of warning: <Option>-cpp</Option> is not friendly to “string
+gaps”.<IndexTerm><Primary>-cpp vs string gaps</Primary></IndexTerm><IndexTerm><Primary>string gaps vs
-cpp</Primary></IndexTerm>. In other words, strings such as the following:
</Para>
<Row>
<Entry>
<Option>-dgcc-lint</Option> </Entry>
-<Entry> (hack) short for ``make GCC very paranoid''</Entry>
+<Entry> (hack) short for “make GCC very paranoid”</Entry>
</Row>
</TBody>
</Para>
<Para>
-If you are using a Haskell ``system library'' (e.g., the POSIX
+If you are using a Haskell “system library” (e.g., the POSIX
library), just use the <Option>-syslib posix</Option> option, and the correct code
should be linked in.
</Para>
<IndexTerm><Primary>consistency checking of executables</Primary></IndexTerm>
By default, immediately after linking an executable, GHC verifies that
the pieces that went into it were compiled with compatible flags; a
-``consistency check''.
+“consistency check”.
(This is to avoid mysterious failures caused by non-meshing of
incompatibly-compiled programs; e.g., if one <Filename>.o</Filename> file was compiled
for a parallel machine and the others weren't.) You may turn off this
GHC (as of version 4.00) supports Concurrent Haskell by default,
without requiring a special option or libraries compiled in a certain
way. To get access to the support libraries for Concurrent Haskell
-(i.e. <Literal>Concurrent</Literal> and friends), use the <Option>-syslib concurrent</Option> option.
+(i.e. <Literal>Concurrent</Literal> and friends), use the
+<Option>-syslib concurrent</Option> option.
</Para>
<Para>
Three RTS options are provided for modifying the behaviour of the
-threaded runtime system. See the descriptions of <Option>-C[<us>]</Option>, <Option>-q</Option>,
-and <Option>-t<num></Option> in <XRef LinkEnd="parallel-rts-opts">.
+threaded runtime system. See the descriptions of
+<Option>-C[<us>]</Option>, <Option>-q</Option>, and
+<Option>-t<num></Option> in <XRef LinkEnd="parallel-rts-opts">.
</Para>
<Para>
-Concurrent Haskell is described in more detail in <XRef LinkEnd="concurrent-and-parallel">.
+Concurrent Haskell is described in more detail in <XRef
+LinkEnd="sec-Concurrent">.
</Para>
</Sect1>
<Para>
To compile a Haskell program for parallel execution under PVM, use the
-<Option>-parallel</Option> option,<IndexTerm><Primary>-parallel option</Primary></IndexTerm> both when compiling
-<Emphasis>and linking</Emphasis>. You will probably want to <Literal>import Parallel</Literal>
-into your Haskell modules.
+<Option>-parallel</Option> option,<IndexTerm><Primary>-parallel
+option</Primary></IndexTerm> both when compiling <Emphasis>and
+linking</Emphasis>. You will probably want to <Literal>import
+Parallel</Literal> into your Haskell modules.
</Para>
<Para>
-To run your parallel program, once PVM is going, just invoke it ``as
-normal''. The main extra RTS option is <Option>-N<n></Option>, to say how many
-PVM ``processors'' your program to run on. (For more details of
-all relevant RTS options, please see <XRef LinkEnd="parallel-rts-opts">.)
+To run your parallel program, once PVM is going, just invoke it
+“as normal”. The main extra RTS option is
+<Option>-N<n></Option>, to say how many PVM
+“processors” your program to run on. (For more details of
+all relevant RTS options, please see <XRef
+LinkEnd="parallel-rts-opts">.)
</Para>
<Para>
</Para>
<Para>
-Creating and/or controlling your ``parallel machine'' is a purely-PVM
+Creating and/or controlling your “parallel machine” is a purely-PVM
business; nothing specific to Parallel Haskell.
</Para>
<Para>
You use the <Command>pvm</Command><IndexTerm><Primary>pvm command</Primary></IndexTerm> command to start PVM on your
machine. You can then do various things to control/monitor your
-``parallel machine;'' the most useful being:
+“parallel machine;” the most useful being:
</Para>
<Para>
<Row>
<Entry><Command>halt</Command></Entry>
-<Entry>kill off this ``parallel machine'' & exit</Entry>
+<Entry>kill off this “parallel machine” & exit</Entry>
</Row>
<Row>
<Para>
With Parallel Haskell programs, we usually don't care about the
-results—only with ``how parallel'' it was! We want pretty pictures.
+results—only with “how parallel” it was! We want pretty pictures.
</Para>
<Para>
<Title>Other useful info about running parallel programs</Title>
<Para>
-The ``garbage-collection statistics'' RTS options can be useful for
+The “garbage-collection statistics” RTS options can be useful for
seeing what parallel programs are doing. If you do either
<Option>+RTS -Sstderr</Option><IndexTerm><Primary>-Sstderr RTS option</Primary></IndexTerm> or <Option>+RTS -sstderr</Option>, then
you'll get mutator, garbage-collection, etc., times on standard
projects / ghc-hetmet.git / blobdiff