Retagged <Literal>s into <Filename>, <Option>, <Command>, &c.
<ItemizedList>
<ListItem>
<Para>
-Finalise is now spelt finalize in all function names.
+``Finalise'' is now spelt ``finalize'' in all function names.
</Para>
</ListItem>
<ListItem>
<Para>
-<Literal>finalize</Literal> now runs the finalizer immediately, and
+<Function>finalize</Function> now runs the finalizer immediately, and
waits for it to complete before returning.
</Para>
</ListItem>
<ListItem>
<Para>
-<Literal>mkWeak</Literal> now takes a <Literal>Maybe (IO ())</Literal> for the finalizer,
-and <Literal>mkWeakNoFinalizer</Literal> is removed.
+<Function>mkWeak</Function> now takes a <Literal>Maybe (IO ())</Literal> for the finalizer,
+and <Function>mkWeakNoFinalizer</Function> is removed.
</Para>
</ListItem>
<Para>
Changed representation of <Literal>Integer</Literal> type to speed up
computations on small integers. The performance of <Literal>Integer</Literal> is now
-only slightly slower than <Literal>Int</Literal> for values between <Literal>minBound::Int</Literal>
-and <Literal>maxBound::Int</Literal>.
+only slightly slower than <Literal>Int</Literal> for values between <Constant>minBound::Int</Constant>
+and <Constant>maxBound::Int</Constant>.
</Para>
</ListItem>
<ListItem>
<Para>
-Added <Literal>-funbox-strict-fields</Literal> for unboxing/unpacking strict
+Added <Option>-funbox-strict-fields</Option> for unboxing/unpacking strict
constructor fields.
</Para>
</ListItem>
<ListItem>
<Para>
-GHC now has a license! Check out <Literal>fptools/ghc/LICENSE/</Literal>.
+GHC now has a license! See <XRef LinkEnd="License">.
</Para>
</ListItem>
<ListItem>
<Para>
Added CPR analysis, which reduces allocation by unboxing function results
-(thanks to Kevin Glynn <Literal><keving@cs.mu.OZ.AU></Literal>).
+(thanks to Kevin Glynn <Email>keving@cs.mu.oz.au</Email>).
</Para>
</ListItem>
<ListItem>
<Para>
-Added <Literal>Concurrent.yield :: IO ()</Literal>.
+Added <Function>Concurrent.yield :: IO ()</Function>.
</Para>
</ListItem>
<ListItem>
<Para>
-Added RULES pragms—transformation rules for Haskell source.
+Added <Literal>RULES</Literal> pragma—transformation rules for Haskell source.
This is used for list fusion: now intermediate lists between map,
foldr, list comprehensions are removed automatically.
</Para>
<ListItem>
<Para>
-GHC now defines <Literal>__HASKELL98__</Literal> when compiling files with <Literal>-cpp</Literal>.
+GHC now defines <Literal>__HASKELL98__</Literal> when compiling files with <Option>-cpp</Option>.
</Para>
</ListItem>
<ListItem>
<Para>
New operations for unsafely thawing byte arrays:
-<Literal>unsafeThaw{Byte,ST,IO}Array</Literal>.
+<Function>unsafeThaw{Byte,ST,IO}Array</Function>.
</Para>
</ListItem>
<ListItem>
<Para>
-<Literal>mkdependHS</Literal> now lives in GHC's lib directory, not the
+<Command>mkdependHS</Command> now lives in GHC's lib directory, not the
binary directory. It isn't intended to be run standalone, only via
-<Literal>ghc -M</Literal>.
+<Command>ghc -M</Command>.
</Para>
</ListItem>
<ListItem>
<Para>
-Asynchronous exceptions are now supported (see <XRef LinkEnd="concurrent-interface">). New operations:
+Asynchronous exceptions are now supported (see the libary documentation for Concurrent Haskell). New operations:
+<!-- Want to add external ref here -->
<ItemizedList>
<ListItem>
<Para>
-<Literal>Exception.killThread</Literal> now raises an exception
-(<Literal>AsyncException.KilledThread</Literal>) in the killed thread.
+<Function>Exception.killThread</Function> now raises an exception
+(<Function>AsyncException.KilledThread</Function>) in the killed thread.
</Para>
</ListItem>
<ListItem>
<Para>
-<Literal>Exception.raiseInThread</Literal> allows a thread to raise an
+<Function>Exception.raiseInThread</Function> allows a thread to raise an
exception in another thread.
</Para>
</ListItem>
<ListItem>
<Para>
-<Literal>Concurrent.myThreadId</Literal> returns the <Literal>ThreadId</Literal> of the calling thread.
+<Function>Concurrent.myThreadId</Function> returns the <Literal>ThreadId</Literal> of the calling thread.
</Para>
</ListItem>
<ListItem>
<Para>
-Stack overflow results in <Literal>AsyncException.StackOverflow</Literal>
+Stack overflow results in <Constant>AsyncException.StackOverflow</Constant>
being raised in the offending thread.
</Para>
</ListItem>
<ListItem>
<Para>
-Assertion failures now raise an <Literal>AssertionFailed</Literal> exception.
+Assertion failures now raise an <Constant>AssertionFailed</Constant> exception.
</Para>
</ListItem>
<ListItem>
<Para>
-<Literal>forkIO</Literal> now handles any uncaught exceptions cleanly.
+<Function>forkIO</Function> now handles any uncaught exceptions cleanly.
</Para>
</ListItem>
<ListItem>
<Para>
-<Literal>integer2Int#</Literal> isn't sign preserving any longer, but modulo <Literal>(maxBound::Int + 1) * 2</Literal>.
+<Function>integer2Int#</Function> isn't sign preserving any longer, but modulo <Constant>(maxBound::Int + 1) * 2</Constant>.
</Para>
</ListItem>
<ListItem>
<Para>
-<Literal>-ddump-rdr</Literal> is now called <Literal>-ddump-parsed</Literal>.
+<Option>-ddump-rdr</Option> is now called <Option>-ddump-parsed</Option>.
</Para>
</ListItem>
<ListItem>
<Para>
-The operation <Literal>newByteArray</Literal> creates a byte array of length
+The operation <Function>newByteArray</Function> creates a byte array of length
equal to the range of its indices <Emphasis>in bytes</Emphasis>.
</Para>
</ListItem>
<ListItem>
<Para>
-<Literal>sizeofByteArray</Literal> returns the size of the byte array, <Emphasis>in bytes</Emphasis>.
+<Function>sizeofByteArray</Function> returns the size of the byte array, <Emphasis>in bytes</Emphasis>.
</Para>
</ListItem>
<ListItem>
<Para>
-The <Literal>freezeArray</Literal> action converts a mutable array into an
-immutable one by copying, whereas <Literal>unsafeFreezeArray</Literal> returns
+The <Function>freezeArray</Function> action converts a mutable array into an
+immutable one by copying, whereas <Function>unsafeFreezeArray</Function> returns
an immutable array that is effectively just the type cast version
of the mutable array. Should you write to the mutable array after
it has been (unsafely) frozen, you'll side-effect the immutable
<ListItem>
<Para>
-The operation <Literal>thawArray</Literal> goes the other way, converting
+The operation <Function>thawArray</Function> goes the other way, converting
an immutable <Literal>Array</Literal> into a mutable one. This is done by
-copying. The operation <Literal>unsafeThawArray</Literal> is also provided,
+copying. The operation <Function>unsafeThawArray</Function> is also provided,
which places the same kind of proof obligation on the programmer
-as <Literal>unsafeFreezeArray</Literal> does.
+as <Function>unsafeFreezeArray</Function> does.
</Para>
</ListItem>
<ListItem>
<Para>
As for mutable arrays, operations for turning mutable byte arrays
-into immutable byte arrays are also provided by the <Literal>freeze*</Literal>
+into immutable byte arrays are also provided by the <Function>freeze*</Function>
class of actions. There's also the non-copying
-<Literal>unsafeFreezeByteArray</Literal>.
+<Function>unsafeFreezeByteArray</Function>.
</Para>
</ListItem>
<ListItem>
<Para>
Operations for going the other way, where an immutable byte
-array is 'thawed' are also provided. <Literal>thawByteArray</Literal> does
-this by copying, whereas <Literal>unsafeThawByteArray</Literal> does not
+array is 'thawed' are also provided. <Function>thawByteArray</Function> does
+this by copying, whereas <Function>unsafeThawByteArray</Function> does not
</Para>
</ListItem>
<ListItem>
<Para>
-The operation <Literal>sizeofMutableByteArray</Literal> returns the size of
+The operation <Function>sizeofMutableByteArray</Function> returns the size of
the array, <Emphasis>in bytes.</Emphasis>
</Para>
</ListItem>
<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
+of the compilation system, in place of whatever the driver <Command>ghc</Command> 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>
+<Option>-pgm<phase-code><program-name></Option><IndexTerm><Primary>-pgm<phase><stuff>
+option</Primary></IndexTerm> option to <Command>ghc</Command> 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>
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
+specific option <Option><option></Option> 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>-opt<phase-code><option></Option>.<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
+So, for example, to force an <Option>-Ewurble</Option> option to the assembler, you
+would tell the driver <Option>-opta-Ewurble</Option> (the dash before the E is
required).
</Para>
<Para>
-Besides getting options to the Haskell compiler with <Literal>-optC<blah></Literal>,
+Besides getting options to the Haskell compiler with <Option>-optC<blah></Option>,
you can get options through to its runtime system with
-<Literal>-optCrts<blah></Literal><IndexTerm><Primary>-optCrts<blah> option</Primary></IndexTerm>.
+<Option>-optCrts<blah></Option><IndexTerm><Primary>-optCrts<blah> option</Primary></IndexTerm>.
</Para>
<Para>
<VariableList>
<VarListEntry>
-<Term><Literal>-noC</Literal>:</Term>
+<Term><Option>-noC</Option>:</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>
+used in conjunction with one or more of the <Option>-ddump-*</Option> options; for
+example: <Command>ghc -noC -ddump-simpl Foo.hs</Command>
</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
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-rn</Literal>:</Term>
+<Term><Option>-ddump-rn</Option>:</Term>
<ListItem>
<Para>
renamer output
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-tc</Literal>:</Term>
+<Term><Option>-ddump-tc</Option>:</Term>
<ListItem>
<Para>
typechecker output
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ddump-deriv</Literal>:</Term>
+<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>
</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>
</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)
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>
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>
<IndexTerm><Primary>language, GHC</Primary></IndexTerm>
<IndexTerm><Primary>extensions, GHC</Primary></IndexTerm>
As with all known Haskell systems, GHC implements some extensions to
-the language. To use them, you'll need to give a <Literal>-fglasgow-exts</Literal>
+the language. To use them, you'll need to give a <Option>-fglasgow-exts</Option>
<IndexTerm><Primary>-fglasgow-exts option</Primary></IndexTerm> option.
</Para>
There are some restrictions on the use of unboxed types, the main one
being that you can't pass an unboxed value to a polymorphic function
or store one in a polymorphic data type. This rules out things like
-<Literal>[Int#]</Literal> (ie. lists of unboxed integers). The reason for this
+<Literal>[Int#]</Literal> (i.e. lists of unboxed integers). The reason for this
restriction is that polymorphic arguments and constructor fields are
assumed to be pointers: if an unboxed integer is stored in one of
these, the garbage collector would attempt to follow it, leading to
-unpredictable space leaks. Or a <Literal>seq</Literal> operation on the polymorphic
+unpredictable space leaks. Or a <Function>seq</Function> operation on the polymorphic
component may attempt to dereference the pointer, with disastrous
results. Even worse, the unboxed value might be larger than a pointer
(<Literal>Double#</Literal> for instance).
</Para>
<Para>
-The <Literal>ST</Literal> library, which provides access to the <Literal>ST</Literal> monad, is a
+The <Literal>ST</Literal> library, which provides access to the <Function>ST</Function> monad, is a
GHC/Hugs extension library and is described in the separate <ULink
URL="libs.html"
>GHC/Hugs Extension Libraries</ULink
</Para>
<Sect2 id="ccall-intro">
-<Title><Literal>_ccall_</Literal> and <Literal>_casm_</Literal>: an introduction
+<Title><Function>_ccall_</Function> and <Function>_casm_</Function>: an introduction
</Title>
<Para>
</Para>
<Para>
-The function <Literal>fooH</Literal> will unbox all of its arguments, call the C
-function <Literal>fooC</Literal> and box the corresponding arguments.
+The function <Function>fooH</Function> unbox all of its arguments, call the C
+function <Function>fooC</Function> and box the corresponding arguments.
</Para>
<Para>
-One of the annoyances about <Literal>_ccall_</Literal>s is when the C types don't quite
-match the Haskell compiler's ideas. For this, the <Literal>_casm_</Literal> variant
+One of the annoyances about <Function>_ccall_</Function>s is when the C types don't quite
+match the Haskell compiler's ideas. For this, the <Function>_casm_</Function> variant
may be just the ticket (NB: <Emphasis>no chance</Emphasis> of such code going
through a native-code generator):
</Para>
</Para>
<Para>
-The first literal-literal argument to a <Literal>_casm_</Literal> is like a <Literal>printf</Literal>
-format: <Literal>%r</Literal> is replaced with the ``result,'' <Literal>%0</Literal>--<Literal>%n-1</Literal> are
-replaced with the 1st--nth arguments. As you can see above, it is an
-easy way to do simple C casting. Everything said about <Literal>_ccall_</Literal> goes
-for <Literal>_casm_</Literal> as well.
+The first literal-literal argument to a <Function>_casm_</Function> is like a <Function>printf</Function>
+format: <Literal>%r</Literal> is replaced with the ``result,'' <Literal>%0</Literal>–<Literal>%n-1</Literal> are
+replaced with the 1st–nth arguments. As you can see above, it is an
+easy way to do simple C casting. Everything said about <Function>_ccall_</Function> goes
+for <Function>_casm_</Function> as well.
</Para>
<Para>
-The use of <Literal>_casm_</Literal> in your code does pose a problem to the compiler
+The use of <Function>_casm_</Function> in your code does pose a problem to the compiler
when it comes to generating an interface file for a freshly compiled
module. Included in an interface file is the unfolding (if any) of a
declaration. However, if a declaration's unfolding happens to contain
-a <Literal>_casm_</Literal>, its unfolding will <Emphasis>not</Emphasis> be emitted into the interface
+a <Function>_casm_</Function>, its unfolding will <Emphasis>not</Emphasis> be emitted into the interface
file even if it qualifies by all the other criteria. The reason why
-the compiler prevents this from happening is that unfolding <Literal>_casm_</Literal>s
+the compiler prevents this from happening is that unfolding <Function>_casm_</Function>s
into an interface file unduly constrains how code that import your
module have to be compiled. If an imported declaration is unfolded and
-it contains a <Literal>_casm_</Literal>, you now have to be using a compiler backend
+it contains a <Function>_casm_</Function>, you now have to be using a compiler backend
capable of dealing with it (i.e., the C compiler backend). If you are
-using the C compiler backend, the unfolded <Literal>_casm_</Literal> may still cause you
+using the C compiler backend, the unfolded <Function>_casm_</Function> may still cause you
problems since the C code snippet it contains may mention CPP symbols
that were in scope when compiling the original module are not when
compiling the importing module.
<Para>
If you're willing to put up with the drawbacks of doing cross-module
inlining of C code (GHC - A Better C Compiler :-), the option
-<Literal>-funfold-casms-in-hi-file</Literal> will turn off the default behaviour.
+<Option>-funfold-casms-in-hi-file</Option> will turn off the default behaviour.
<IndexTerm><Primary>-funfold-casms-in-hi-file option</Primary></IndexTerm>
</Para>
</Sect2>
<Sect2 id="glasgow-literal-literals">
-<Title>Literal-literals
-</Title>
+<Title>Literal-literals</Title>
<Para>
<IndexTerm><Primary>Literal-literals</Primary></IndexTerm>
-</Para>
-
-<Para>
-The literal-literal argument to <Literal>_casm_</Literal> can be made use of separately
-from the <Literal>_casm_</Literal> construct itself. Indeed, we've already used it:
+The literal-literal argument to <Function>_casm_</Function> can be made use of separately
+from the <Function>_casm_</Function> construct itself. Indeed, we've already used it:
</Para>
<Para>
</Para>
<Para>
-The first argument that's passed to <Literal>fooC</Literal> is given as a literal-literal,
+The first argument that's passed to <Function>fooC</Function> is given as a literal-literal,
that is, a literal chunk of C code that will be inserted into the generated
-<Literal>.hc</Literal> code at the right place.
+<Filename>.hc</Filename> code at the right place.
</Para>
<Para>
</Para>
<Para>
-When generating C (using the <Literal>-fvia-C</Literal> directive), one can assist the
-C compiler in detecting type errors by using the <Literal>-#include</Literal> directive
-to provide <Literal>.h</Literal> files containing function headers.
+When generating C (using the <Option>-fvia-C</Option> directive), one can assist the
+C compiler in detecting type errors by using the <Command>-#include</Command> directive
+to provide <Filename>.h</Filename> files containing function headers.
</Para>
<Para>
<Para>
You can find appropriate definitions for <Literal>StgInt</Literal>, <Literal>StgForeignObj</Literal>,
-etc using <Literal>gcc</Literal> on your architecture by consulting
-<Literal>ghc/includes/StgTypes.h</Literal>. The following table summarises the
+etc using <Command>gcc</Command> on your architecture by consulting
+<Filename>ghc/includes/StgTypes.h</Filename>. The following table summarises the
relationship between Haskell types and C types.
</Para>
</Para>
<Para>
-The arguments of a <Literal>_ccall_</Literal> are automatically unboxed before the
+The arguments of a <Function>_ccall_</Function> automatically unboxed before the
call. There are two reasons why this is usually the Right Thing to
do:
</Para>
<Para>
It is possible to subvert the unboxing process by creating a ``stable
pointer'' to a value and passing the stable pointer instead. For
-example, to pass/return an integer lazily to C functions <Literal>storeC</Literal> and
-<Literal>fetchC</Literal>, one might write:
+example, to pass/return an integer lazily to C functions <Function>storeC</Function> and
+<Function>fetchC</Function> might write:
</Para>
<Para>
</Para>
<Para>
-As with the use of <Literal>free</Literal> in C programs, GREAT CARE SHOULD BE
+As with the use of <Function>free</Function> in C programs, GREAT CARE SHOULD BE
EXERCISED to ensure these functions are called at the right time: too
early and you get dangling references (and, if you're lucky, an error
message from the runtime system); too late and you get space leaks.
</Para>
<Para>
-And to force evaluation of the argument within <Literal>fooC</Literal>, one would
+And to force evaluation of the argument within <Function>fooC</Function>, one would
call one of the following C functions (according to type of argument).
</Para>
</Para>
<Para>
-Nota Bene: <Literal>_ccall_GC_</Literal><IndexTerm><Primary>_ccall_GC_</Primary></IndexTerm> must be used if any of
+Nota Bene: <Function>_ccall_GC_</Function><IndexTerm><Primary>_ccall_GC_</Primary></IndexTerm> must be used if any of
these functions are used.
</Para>
</Para>
<Para>
-There are two types that <Literal>ghc</Literal> programs can use to reference
+There are two types that GHC programs can use to reference
(heap-allocated) objects outside the Haskell world: <Literal>Addr</Literal> and
<Literal>ForeignObj</Literal>.
</Para>
</Para>
<Para>
-If you use <Literal>ForeignObj</Literal>, <Literal>ghc</Literal>'s garbage collector will call upon the
+If you use <Literal>ForeignObj</Literal>, GHC's garbage collector will call upon the
user-supplied <Emphasis>finaliser</Emphasis> function to free the object when the
Haskell world no longer can access the object. (An object is
associated with a finaliser function when the abstract
</Para>
<Para>
-The <Literal>_ccall_</Literal> construct is part of the <Literal>IO</Literal> monad because 9 out of 10
+The <Function>_ccall_</Function> construct is part of the <Literal>IO</Literal> monad because 9 out of 10
uses will be to call imperative functions with side effects such as
-<Literal>printf</Literal>. Use of the monad ensures that these operations happen in a
+<Function>printf</Function>. Use of the monad ensures that these operations happen in a
predictable order in spite of laziness and compiler optimisations.
</Para>
<Para>
To avoid having to be in the monad to call a C function, it is
-possible to use <Literal>unsafePerformIO</Literal>, which is available from the
+possible to use <Function>unsafePerformIO</Function>, which is available from the
<Literal>IOExts</Literal> module. There are three situations where one might like to
call a C function from outside the IO world:
</Para>
<Para>
Calling a side-effecting function even though the results will
-be unpredictable. For example the <Literal>trace</Literal> function is defined by:
+be unpredictable. For example the <Function>trace</Function> function is defined by:
<ProgramListing>
<ListItem>
<Para>
- For modules that use <Literal>_ccall_</Literal>s, etc., compile with
-<Literal>-fvia-C</Literal>.<IndexTerm><Primary>-fvia-C option</Primary></IndexTerm> You don't have to, but you should.
+ For modules that use <Function>_ccall_</Function>s, etc., compile with
+<Option>-fvia-C</Option>.<IndexTerm><Primary>-fvia-C option</Primary></IndexTerm> You don't have to, but you should.
-Also, use the <Literal>-#include "prototypes.h"</Literal> flag (hack) to inform the C
+Also, use the <Option>-#include "prototypes.h"</Option> flag (hack) to inform the C
compiler of the fully-prototyped types of all the C functions you
call. (<XRef LinkEnd="glasgow-foreign-headers"> says more about this…)
This scheme is the <Emphasis>only</Emphasis> way that you will get <Emphasis>any</Emphasis>
-typechecking of your <Literal>_ccall_</Literal>s. (It shouldn't be that way, but…).
-GHC will pass the flag <Literal>-Wimplicit</Literal> to gcc so that you'll get warnings
-if any <Literal>_ccall_</Literal>ed functions have no prototypes.
+typechecking of your <Function>_ccall_</Function>s. (It shouldn't be that way, but…).
+GHC will pass the flag <Option>-Wimplicit</Option> to <Command>gcc</Command> so that you'll get warnings
+if any <Function>_ccall_</Function>ed functions have no prototypes.
</Para>
</ListItem>
<ListItem>
<Para>
-Try to avoid <Literal>_ccall_</Literal>s to C functions that take <Literal>float</Literal>
+Try to avoid <Function>_ccall_</Function>s to C functions that take <Literal>float</Literal>
arguments or return <Literal>float</Literal> results. Reason: if you do, you will
become entangled in (ANSI?) C's rules for when arguments/results are
promoted to <Literal>doubles</Literal>. It's a nightmare and just not worth it.
Use <Literal>doubles</Literal> if possible.
If you do use <Literal>floats</Literal>, check and re-check that the right thing is
-happening. Perhaps compile with <Literal>-keep-hc-file-too</Literal> and look at
-the intermediate C (<Literal>.hc</Literal> file).
+happening. Perhaps compile with <Option>-keep-hc-file-too</Option> and look at
+the intermediate C (<Function>.hc</Function>).
</Para>
</ListItem>
<Para>
The compiler uses two non-standard type-classes when
-type-checking the arguments and results of <Literal>_ccall_</Literal>: the arguments
-(respectively result) of <Literal>_ccall_</Literal> must be instances of the class
+type-checking the arguments and results of <Function>_ccall_</Function>: the arguments
+(respectively result) of <Function>_ccall_</Function> must be instances of the class
<Literal>CCallable</Literal> (respectively <Literal>CReturnable</Literal>). Both classes may be
imported from the module <Literal>CCall</Literal>, but this should only be
necessary if you want to define a new instance. (Neither class
</ProgramListing>
-is not good enough, because the compiler can't work out what type <Literal>x</Literal>
-is, nor what type the <Literal>_ccall_</Literal> returns. You have to write, say:
+is not good enough, because the compiler can't work out what type <VarName>x</VarName>
+is, nor what type the <Function>_ccall_</Function> returns. You have to write, say:
<ProgramListing>
<Para>
If you call out to C code which may trigger the Haskell garbage
collector or create new threads (examples of this later…), then you
-must use the <Literal>_ccall_GC_</Literal><IndexTerm><Primary>_ccall_GC_ primitive</Primary></IndexTerm> or
-<Literal>_casm_GC_</Literal><IndexTerm><Primary>_casm_GC_ primitive</Primary></IndexTerm> variant of C-calls. (This
-does not work with the native code generator - use <Literal>\fvia-C</Literal>.) This
+must use the <Function>_ccall_GC_</Function><IndexTerm><Primary>_ccall_GC_ primitive</Primary></IndexTerm> or
+<Function>_casm_GC_</Function><IndexTerm><Primary>_casm_GC_ primitive</Primary></IndexTerm> variant of C-calls. (This
+does not work with the native code generator—use <Option>-fvia-C</Option>.) This
stuff is hairy with a capital H!
</Para>
</ListItem>
"overlap" if <Literal>type1</Literal> and <Literal>type2</Literal> unify
However, if you give the command line option
-<Literal>-fallow-overlapping-instances</Literal><IndexTerm><Primary>-fallow-overlapping-instances
+<Option>-fallow-overlapping-instances</Option><IndexTerm><Primary>-fallow-overlapping-instances
option</Primary></IndexTerm> then two overlapping instance declarations are permitted
iff
I'm on the lookout for a simple rule that preserves decidability while
allowing these idioms. The experimental flag
-<Literal>-fallow-undecidable-instances</Literal><IndexTerm><Primary>-fallow-undecidable-instances
+<Option>-fallow-undecidable-instances</Option><IndexTerm><Primary>-fallow-undecidable-instances
option</Primary></IndexTerm> lifts this restriction, allowing all the types in an
instance head to be type variables.
Voluminous correspondence on the Haskell mailing list has convinced me
that it's worth experimenting with a more liberal rule. If you use
-the flag <Literal>-fallow-undecidable-instances</Literal> you can use arbitrary
+the flag <Option>-fallow-undecidable-instances</Option> can use arbitrary
types in an instance context. Termination is ensured by having a
fixed-depth recursion stack. If you exceed the stack depth you get a
sort of backtrace, and the opportunity to increase the stack depth
-with <Literal>-fcontext-stack</Literal><Emphasis>N</Emphasis>.
+with <Option>-fcontext-stack</Option><Emphasis>N</Emphasis>.
</Para>
</ListItem>
<Para>
Notice that you don't need to use a <Literal>forall</Literal> if there's an
explicit context. For example in the first argument of the
-constructor <Literal>MkSwizzle</Literal>, an implicit "<Literal>forall a.</Literal>" is
+constructor <Function>MkSwizzle</Function>, an implicit "<Literal>forall a.</Literal>" is
prefixed to the argument type. The implicit <Literal>forall</Literal>
quantifies all type variables that are not already in scope, and are
mentioned in the type quantified over.
<Para>
The type of the argument can, as usual, be more general than the type
-required, as <Literal>(MkSwizzle reverse)</Literal> shows. (<Literal>reverse</Literal>
+required, as <Literal>(MkSwizzle reverse)</Literal> shows. (<Function>reverse</Function>
does not need the <Literal>Ord</Literal> constraint.)
</Para>
</Para>
<Para>
-In the function <Literal>h</Literal> we use the record selectors <Literal>return</Literal>
+In the function <Function>h</Function> we use the record selectors <Literal>return</Literal>
and <Literal>bind</Literal> to extract the polymorphic bind and return functions
from the <Literal>MonadT</Literal> data structure, rather than using pattern
matching.
</Para>
<Para>
-even though it involves a partial application of <Literal>T1</Literal>, because
+even though it involves a partial application of <Function>T1</Function>, because
the sub-expression <Literal>T1 (\a b -> a)</Literal> has type <Literal>Int -> T
Int</Literal>.
</Para>
<Para>
Once you have data constructors with universally-quantified fields, or
-constants such as <Literal>runST</Literal> that have rank-2 types, it isn't long
+constants such as <Constant>runST</Constant> that have rank-2 types, it isn't long
before you discover that you need more! Consider:
</Para>
</Para>
<Para>
-<Literal>mkTs</Literal> is a fuction that constructs some values of type
+<Function>mkTs</Function> is a fuction that constructs some values of type
<Literal>T</Literal>, using some pieces passed to it. The trouble is that since
<Literal>f</Literal> is a function argument, Haskell assumes that it is
-monomorphic, so we'll get a type error when applying <Literal>T1</Literal> to
+monomorphic, so we'll get a type error when applying <Function>T1</Function> to
it. This is a rather silly example, but the problem really bites in
practice. Lots of people trip over the fact that you can't make
-"wrappers functions" for <Literal>runST</Literal> for exactly the same reason.
+"wrappers functions" for <Constant>runST</Constant> for exactly the same reason.
In short, it is impossible to build abstractions around functions with
rank-2 types.
</Para>
<Para>
This type signature tells the compiler to attribute <Literal>f</Literal> with
the polymorphic type <Literal>(forall b. b -> b -> b)</Literal> when type
-checking the body of <Literal>mkTs</Literal>, so now the application of
-<Literal>T1</Literal> is fine.
+checking the body of <Function>mkTs</Function>, so now the application of
+<Function>T1</Function> is fine.
</Para>
<Para>
<ProgramListing>
- rank2type ::= [forall tyvars .] [context =>] funty
- funty ::= ([forall tyvars .] [context =>] ty) -> funty
- | ty
- ty ::= ...current Haskell monotype syntax...
+rank2type ::= [forall tyvars .] [context =>] funty
+funty ::= ([forall tyvars .] [context =>] ty) -> funty
+ | ty
+ty ::= ...current Haskell monotype syntax...
</ProgramListing>
There is a restriction on the definition of a function whose
type signature is a rank-2 type: the polymorphic arguments must be
matched on the left hand side of the "<Literal>=</Literal>" sign. You can't
-define <Literal>mkTs</Literal> like this:
+define <Function>mkTs</Function> like this:
<ProgramListing>
- mkTs :: (forall b. b -> b -> b) -> a -> [T a]
- mkTs = \ f x y -> [T1 f x, T1 f y]
+mkTs :: (forall b. b -> b -> b) -> a -> [T a]
+mkTs = \ f x y -> [T1 f x, T1 f y]
</ProgramListing>
The idea of using existential quantification in data type declarations
was suggested by Laufer (I believe, thought doubtless someone will
correct me), and implemented in Hope+. It's been in Lennart
-Augustsson's <Literal>hbc</Literal> Haskell compiler for several years, and
+Augustsson's <Command>hbc</Command> Haskell compiler for several years, and
proved very useful. Here's the idea. Consider the declaration:
</Para>
</Para>
<Para>
-Notice that the type variable <Literal>a</Literal> in the type of <Literal>MkFoo</Literal>
+Notice that the type variable <Literal>a</Literal> in the type of <Function>MkFoo</Function>
does not appear in the data type itself, which is plain <Literal>Foo</Literal>.
For example, the following expression is fine:
</Para>
<Para>
Here, <Literal>(MkFoo 3 even)</Literal> packages an integer with a function
-<Literal>even</Literal> that maps an integer to <Literal>Bool</Literal>; and <Literal>MkFoo 'c'
-isUpper</Literal> packages a character with a compatible function. These
+<Function>even</Function> that maps an integer to <Literal>Bool</Literal>; and <Function>MkFoo 'c'
+isUpper</Function> packages a character with a compatible function. These
two things are each of type <Literal>Foo</Literal> and can be put in a list.
</Para>
<Para>
What can we do with a value of type <Literal>Foo</Literal>?. In particular,
-what happens when we pattern-match on <Literal>MkFoo</Literal>?
+what happens when we pattern-match on <Function>MkFoo</Function>?
</Para>
<Para>
</Para>
<Para>
-Since all we know about <Literal>val</Literal> and <Literal>fn</Literal> is that they
+Since all we know about <Literal>val</Literal> and <Function>fn</Function> is that they
are compatible, the only (useful) thing we can do with them is to
-apply <Literal>fn</Literal> to <Literal>val</Literal> to get a boolean. For example:
+apply <Function>fn</Function> to <Literal>val</Literal> to get a boolean. For example:
</Para>
<Para>
<Para>
What has this to do with <Emphasis>existential</Emphasis> quantification?
-Simply that <Literal>MkFoo</Literal> has the (nearly) isomorphic type
+Simply that <Function>MkFoo</Function> has the (nearly) isomorphic type
</Para>
<Para>
<Title>Type classes</Title>
<Para>
-An easy extension (implemented in <Literal>hbc</Literal>) is to allow
+An easy extension (implemented in <Command>hbc</Command>) is to allow
arbitrary contexts before the constructor. For example:
</Para>
<Para>
<ProgramListing>
- data Baz = forall a. Eq a => Baz1 a a
- | forall b. Show b => Baz2 b (b -> b)
+data Baz = forall a. Eq a => Baz1 a a
+ | forall b. Show b => Baz2 b (b -> b)
</ProgramListing>
</Para>
<Para>
<ProgramListing>
- Baz1 :: forall a. Eq a => a -> a -> Baz
- Baz2 :: forall b. Show b => b -> (b -> b) -> Baz
+Baz1 :: forall a. Eq a => a -> a -> Baz
+Baz2 :: forall b. Show b => b -> (b -> b) -> Baz
</ProgramListing>
</Para>
<Para>
-But when pattern matching on <Literal>Baz1</Literal> the matched values can be compared
-for equality, and when pattern matching on <Literal>Baz2</Literal> the first matched
+But when pattern matching on <Function>Baz1</Function> the matched values can be compared
+for equality, and when pattern matching on <Function>Baz2</Function> the first matched
value can be converted to a string (as well as applying the function to it).
So this program is legal:
</Para>
<Para>
Operationally, in a dictionary-passing implementation, the
-constructors <Literal>Baz1</Literal> and <Literal>Baz2</Literal> must store the
+constructors <Function>Baz1</Function> and <Function>Baz2</Function> must store the
dictionaries for <Literal>Eq</Literal> and <Literal>Show</Literal> respectively, and
extract it on pattern matching.
</Para>
<ProgramListing>
- f1 (MkFoo a f) = a
+f1 (MkFoo a f) = a
</ProgramListing>
-Here, the type bound by <Literal>MkFoo</Literal> "escapes", because <Literal>a</Literal>
-is the result of <Literal>f1</Literal>. One way to see why this is wrong is to
-ask what type <Literal>f1</Literal> has:
+Here, the type bound by <Function>MkFoo</Function> "escapes", because <Literal>a</Literal>
+is the result of <Function>f1</Function>. One way to see why this is wrong is to
+ask what type <Function>f1</Function> has:
<ProgramListing>
It's ok to say <Literal>a==b</Literal> or <Literal>p==q</Literal>, but
<Literal>a==q</Literal> is wrong because it equates the two distinct types arising
-from the two <Literal>Baz1</Literal> constructors.
+from the two <Function>Baz1</Function> constructors.
</Para>
Reason: in most cases it would not make sense. For example:#
<ProgramListing>
- data T = forall a. MkT [a] deriving( Eq )
+data T = forall a. MkT [a] deriving( Eq )
</ProgramListing>
To derive <Literal>Eq</Literal> in the standard way we would need to have equality
-between the single component of two <Literal>MkT</Literal> constructors:
+between the single component of two <Function>MkT</Function> constructors:
<ProgramListing>
- instance Eq T where
- (MkT a) == (MkT b) = ???
+instance Eq T where
+ (MkT a) == (MkT b) = ???
</ProgramListing>
-But <Literal>a</Literal> and <Literal>b</Literal> have distinct types, and so can't be compared.
+But <VarName>a</VarName> and <VarName>b</VarName> have distinct types, and so can't be compared.
It's just about possible to imagine examples in which the derived instance
would make sense, but it seems altogether simpler simply to prohibit such
declarations. Define your own instances!
</Para>
<Para>
-One way out is to define an extended <Literal>assert</Literal> function which also
+One way out is to define an extended <Function>assert</Function> function which also
takes a descriptive string to include in the error message and
perhaps combine this with the use of a pre-processor which inserts
-the source location where <Literal>assert</Literal> was used.
+the source location where <Function>assert</Function> was used.
</Para>
<Para>
Ghc offers a helping hand here, doing all of this for you. For every
-use of <Literal>assert</Literal> in the user's source:
+use of <Function>assert</Function> in the user's source:
</Para>
<Para>
<Para>
The rewrite is only performed by the compiler when it spots
-applications of <Literal>Exception.assert</Literal>, so you can still define and
-use your own versions of <Literal>assert</Literal>, should you so wish. If not,
-import <Literal>Exception</Literal> to make use <Literal>assert</Literal> in your code.
+applications of <Function>Exception.assert</Function>, so you can still define and
+use your own versions of <Function>assert</Function>, should you so wish. If not,
+import <Literal>Exception</Literal> to make use <Function>assert</Function> in your code.
</Para>
<Para>
To have the compiler ignore uses of assert, use the compiler option
-<Literal>-fignore-asserts</Literal>. <IndexTerm><Primary>-fignore-asserts option</Primary></IndexTerm> That is,
+<Option>-fignore-asserts</Option>. <IndexTerm><Primary>-fignore-asserts option</Primary></IndexTerm> That is,
expressions of the form <Literal>assert pred e</Literal> will be rewritten to <Literal>e</Literal>.
</Para>
</Para>
<Para>
-The pattern <Literal>(xs::[a])</Literal> includes a type signature for <Literal>xs</Literal>.
+The pattern <Literal>(xs::[a])</Literal> includes a type signature for <VarName>xs</VarName>.
This brings the type variable <Literal>a</Literal> into scope; it scopes over
-all the patterns and right hand sides for this equation for <Literal>f</Literal>.
-In particular, it is in scope at the type signature for <Literal>y</Literal>.
+all the patterns and right hand sides for this equation for <Function>f</Function>.
+In particular, it is in scope at the type signature for <VarName>y</VarName>.
</Para>
<Para>
-At ordinary type signatures, such as that for <Literal>ys</Literal>, any type variables
+At ordinary type signatures, such as that for <VarName>ys</VarName>, any type variables
mentioned in the type signature <Emphasis>that are not in scope</Emphasis> are
implicitly universally quantified. (If there are no type variables in
scope, all type variables mentioned in the signature are universally
-quantified, which is just as in Haskell 98.) In this case, since <Literal>a</Literal>
-is in scope, it is not universally quantified, so the type of <Literal>ys</Literal> is
-the same as that of <Literal>xs</Literal>. In Haskell 98 it is not possible to declare
-a type for <Literal>ys</Literal>; a major benefit of scoped type variables is that
+quantified, which is just as in Haskell 98.) In this case, since <VarName>a</VarName>
+is in scope, it is not universally quantified, so the type of <VarName>ys</VarName> is
+the same as that of <VarName>xs</VarName>. In Haskell 98 it is not possible to declare
+a type for <VarName>ys</VarName>; a major benefit of scoped type variables is that
it becomes possible to do so.
</Para>
</ProgramListing>
-It's illegal because <Literal>a</Literal> is not in scope in the body of <Literal>f</Literal>,
+It's illegal because <VarName>a</VarName> is not in scope in the body of <Function>f</Function>,
so the ordinary signature <Literal>x::a</Literal> is equivalent to <Literal>x::forall a.a</Literal>;
and that is an incorrect typing.
</ProgramListing>
-The final <Literal>":: [a]"</Literal> after all the patterns gives a signature to the
+The final <Literal>:: [a]</Literal> after all the patterns gives a signature to the
result type. Sometimes this is the only way of naming the type variable
you want:
</ProgramListing>
-Here, <Literal>f1</Literal> is OK, but <Literal>f2</Literal> is not, because <Literal>c</Literal> gets unified
+Here, <Function>f1</Function> is OK, but <Function>f2</Function> is not, because <VarName>c</VarName> gets unified
with a type variable free in the environment, in this
-case, the type of <Literal>f2</Literal>, which is in the environment when
+case, the type of <Function>f2</Function>, which is in the environment when
the lambda abstraction is checked.
</Para>
</Para>
<Para>
-Here <Literal>g</Literal> has type <Literal>forall a. Eq a => a -> a -> Bool</Literal>, just as if
-<Literal>g</Literal> had a separate type signature. Lacking a type signature, <Literal>g</Literal>
+Here <Function>g</Function> has type <Literal>forall a. Eq a => a -> a -> Bool</Literal>, just as if
+<Function>g</Function> had a separate type signature. Lacking a type signature, <Function>g</Function>
would get a monomorphic type.
</Para>
<IndexTerm><Primary>pragma, INLINE</Primary></IndexTerm></Title>
<Para>
-GHC (with <Literal>-O</Literal>, as always) tries to inline (or ``unfold'')
+GHC (with <Option>-O</Option>, as always) tries to inline (or ``unfold'')
functions/values that are ``small enough,'' thus avoiding the call
overhead and possibly exposing other more-wonderful optimisations.
</Para>
{-# SPECIALIZE hammeredLookup :: ...as before... = blah #-}
</ProgramListing>
-It's <Emphasis>Your Responsibility</Emphasis> to make sure that <Literal>blah</Literal> really
-behaves as a specialised version of <Literal>hammeredLookup</Literal>!!!
+It's <Emphasis>Your Responsibility</Emphasis> to make sure that <Function>blah</Function> really
+behaves as a specialised version of <Function>hammeredLookup</Function>!!!
</Para>
<Para>
i2d (I# i) = D# (int2Double# i) -- uses Glasgow prim-op directly
</ProgramListing>
-The <Literal>i2d</Literal> function is virtually one machine instruction; the
+The <Function>i2d</Function> function is virtually one machine instruction; the
default conversion—via an intermediate <Literal>Rational</Literal>—is obscenely
expensive by comparison.
</Para>
</Para>
<Para>
-if you'd generated the current file from something called <Literal>Foo.vhs</Literal>
+if you'd generated the current file from something called <Filename>Foo.vhs</Filename>
and this line corresponds to line 42 in the original. GHC will adjust
its error messages to refer to the line/file named in the <Literal>LINE</Literal>
pragma.
<ListItem>
<Para>
- Each variable mentioned in a rule must either be in scope (e.g. <Literal>map</Literal>),
-or bound by the <Literal>forall</Literal> (e.g. <Literal>f</Literal>, <Literal>g</Literal>, <Literal>xs</Literal>). The variables bound by
+ Each variable mentioned in a rule must either be in scope (e.g. <Function>map</Function>),
+or bound by the <Literal>forall</Literal> (e.g. <Function>f</Function>, <Function>g</Function>, <Function>xs</Function>). The variables bound by
the <Literal>forall</Literal> are called the <Emphasis>pattern</Emphasis> variables. They are separated
by spaces, just like in a type <Literal>forall</Literal>.
</Para>
For example, here is the <Literal>foldr/build</Literal> rule:
<ProgramListing>
- "fold/build" forall k z (g::forall b. (a->b->b) -> b -> b) .
- foldr k z (build g) = g k z
+"fold/build" forall k z (g::forall b. (a->b->b) -> b -> b) .
+ foldr k z (build g) = g k z
</ProgramListing>
-Since <Literal>g</Literal> has a polymorphic type, it must have a type signature.
+Since <Function>g</Function> has a polymorphic type, it must have a type signature.
</Para>
</ListItem>
<ListItem>
<Para>
- The left hand side of a rule must consist of a top-level variable applied
+The left hand side of a rule must consist of a top-level variable applied
to arbitrary expressions. For example, this is <Emphasis>not</Emphasis> OK:
<ProgramListing>
- "wrong1" forall e1 e2. case True of { True -> e1; False -> e2 } = e1
- "wrong2" forall f. f True = True
+"wrong1" forall e1 e2. case True of { True -> e1; False -> e2 } = e1
+"wrong2" forall f. f True = True
</ProgramListing>
In <Literal>"wrong1"</Literal>, the LHS is not an application; in <Literal>"wrong1"</Literal>, the LHS has a pattern variable
<ListItem>
<Para>
- Rules are only applied if you use the <Literal>-O</Literal> flag.
-
+Rules are only applied if you use the <Option>-O</Option> flag.
</Para>
</ListItem>
-<ListItem>
+<ListItem>
<Para>
Rules are regarded as left-to-right rewrite rules.
When GHC finds an expression that is a substitution instance of the LHS
</ProgramListing>
The expression <Literal>s (t xs)</Literal> does not match the rule <Literal>"map/map"</Literal>, but GHC
-will substitute for <Literal>s</Literal> and <Literal>t</Literal>, giving an expression which does match.
-If <Literal>s</Literal> or <Literal>t</Literal> was (a) used more than once, and (b) large or a redex, then it would
+will substitute for <VarName>s</VarName> and <VarName>t</VarName>, giving an expression which does match.
+If <VarName>s</VarName> or <VarName>t</VarName> was (a) used more than once, and (b) large or a redex, then it would
not be substituted, and the rule would not fire.
</Para>
Well, not quite. It <Emphasis>will</Emphasis> match the expression
<ProgramListing>
- wibble f g xs
+wibble f g xs
</ProgramListing>
-where <Literal>wibble</Literal> is defined:
+where <Function>wibble</Function> is defined:
<ProgramListing>
- wibble f g = map f . map g
+wibble f g = map f . map g
</ProgramListing>
-because <Literal>wibble</Literal> will be inlined (it's small).
+because <Function>wibble</Function> will be inlined (it's small).
Later on in compilation, GHC starts inlining even things on the
LHS of rules, but still leaves the rules enabled. This inlining
-policy is controlled by the per-simplification-pass flag <Literal>-finline-phase</Literal>n.
+policy is controlled by the per-simplification-pass flag <Option>-finline-phase</Option><Emphasis>n</Emphasis>.
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>++</Literal>
+ <Function>++</Function>
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>map</Literal>
+ <Function>map</Function>
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>filter</Literal>
+ <Function>filter</Function>
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>iterate</Literal>, <Literal>repeat</Literal>
+ <Function>iterate</Function>, <Function>repeat</Function>
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>zip</Literal>, <Literal>zipWith</Literal>
+ <Function>zip</Function>, <Function>zipWith</Function>
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>array</Literal> (on its second argument)
+ <Function>array</Function> (on its second argument)
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>length</Literal>
+ <Function>length</Function>
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>++</Literal> (on its first argument)
+ <Function>++</Function> (on its first argument)
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>map</Literal>
+ <Function>map</Function>
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>filter</Literal>
+ <Function>filter</Function>
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>concat</Literal>
+ <Function>concat</Function>
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>unzip</Literal>, <Literal>unzip2</Literal>, <Literal>unzip3</Literal>, <Literal>unzip4</Literal>
+ <Function>unzip</Function>, <Function>unzip2</Function>, <Function>unzip3</Function>, <Function>unzip4</Function>
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>zip</Literal>, <Literal>zipWith</Literal> (but on one argument only; if both are good producers, <Literal>zip</Literal>
+ <Function>zip</Function>, <Function>zipWith</Function> (but on one argument only; if both are good producers, <Function>zip</Function>
will fuse with one but not the other)
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>partition</Literal>
+ <Function>partition</Function>
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>head</Literal>
+ <Function>head</Function>
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>and</Literal>, <Literal>or</Literal>, <Literal>any</Literal>, <Literal>all</Literal>
+ <Function>and</Function>, <Function>or</Function>, <Function>any</Function>, <Function>all</Function>
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>sequence_</Literal>
+ <Function>sequence_</Function>
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>msum</Literal>
+ <Function>msum</Function>
</Para>
</ListItem>
<ListItem>
<Para>
- <Literal>sortBy</Literal>
+ <Function>sortBy</Function>
</Para>
</ListItem>
So, for example, the following should generate no intermediate lists:
<ProgramListing>
- array (1,10) [(i,i*i) | i <- map (+ 1) [0..9]]
+array (1,10) [(i,i*i) | i <- map (+ 1) [0..9]]
</ProgramListing>
</Para>
{-# SPECIALIZE fromIntegral :: Int8 -> Int16 = int8ToInt16 #-}
</ProgramListing>
-This told GHC to use <Literal>int8ToInt16</Literal> instead of <Literal>fromIntegral</Literal> whenever
+This told GHC to use <Function>int8ToInt16</Function> instead of <Function>fromIntegral</Function> whenever
the latter was called with type <Literal>Int8 -> Int16</Literal>. That is, rather than
-specialising the original definition of <Literal>fromIntegral</Literal> the programmer is
-promising that it is safe to use <Literal>int8ToInt16</Literal> instead.
+specialising the original definition of <Function>fromIntegral</Function> the programmer is
+promising that it is safe to use <Function>int8ToInt16</Function> instead.
</Para>
<Para>
same thing:
<ProgramListing>
- {-# RULES
- "fromIntegral/Int8/Int16" fromIntegral = int8ToInt16
- #-}
+{-# RULES
+ "fromIntegral/Int8/Int16" fromIntegral = int8ToInt16
+#-}
</ProgramListing>
-This slightly odd-looking rule instructs GHC to replace <Literal>fromIntegral</Literal>
-by <Literal>int8ToInt16</Literal> <Emphasis>whenever the types match</Emphasis>. Speaking more operationally,
+This slightly odd-looking rule instructs GHC to replace <Function>fromIntegral</Function>
+by <Function>int8ToInt16</Function> <Emphasis>whenever the types match</Emphasis>. Speaking more operationally,
GHC adds the type and dictionary applications to get the typed rule
<ProgramListing>
- forall (d1::Integral Int8) (d2::Num Int16) .
- fromIntegral Int8 Int16 d1 d2 = int8ToInt16
+forall (d1::Integral Int8) (d2::Num Int16) .
+ fromIntegral Int8 Int16 d1 d2 = int8ToInt16
</ProgramListing>
What is more,
<ListItem>
<Para>
- Use <Literal>-ddump-rules</Literal> to see what transformation rules GHC is using.
+ Use <Option>-ddump-rules</Option> to see what transformation rules GHC is using.
</Para>
</ListItem>
<ListItem>
<Para>
- Use <Literal>-ddump-simpl-stats</Literal> to see what rules are being fired.
-If you add <Literal>-dppr-debug</Literal> you get a more detailed listing.
+ Use <Option>-ddump-simpl-stats</Option> to see what rules are being fired.
+If you add <Option>-dppr-debug</Option> you get a more detailed listing.
</Para>
</ListItem>
<ListItem>
<Para>
- The defintion of (say) <Literal>build</Literal> in <Literal>PrelBase.lhs</Literal> looks llike this:
+ The defintion of (say) <Function>build</Function> in <FileName>PrelBase.lhs</FileName> looks llike this:
<ProgramListing>
build :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
<ListItem>
<Para>
- In <Literal>ghc/lib/std/PrelBase.lhs</Literal> look at the rules for <Literal>map</Literal> to
+ In <Filename>ghc/lib/std/PrelBase.lhs</Filename> look at the rules for <Function>map</Function> to
see how to write rules that will do fusion and yet give an efficient
-program even if fusion doesn't happen. More rules in <Literal>PrelList.lhs</Literal>.
+program even if fusion doesn't happen. More rules in <Filename>PrelList.lhs</Filename>.
</Para>
</ListItem>
<Term>``The compiler ran out of heap (or stack) when compiling itself!''</Term>
<ListItem>
<Para>
-It happens. We try to supply reasonable <Literal>-H<n></Literal> flags for
-<Literal>ghc/compiler/</Literal> and <Literal>ghc/lib/</Literal>, but GHC's memory consumption
+It happens. We try to supply reasonable <Option>-H<n></Option> flags for
+<Filename>ghc/compiler/</Filename> and <Filename>ghc/lib/</Filename>, but GHC's memory consumption
can vary by platform (e.g., on a 64-bit machine).
</Para>
<Para>
-Just say <Literal>make all EXTRA_HC_OPTS=-H<a reasonable number></Literal> and see
+Just say <Command>make all EXTRA_HC_OPTS=-H<a reasonable number></Command> and see
how you get along.
</Para>
<ListItem>
<Para>
Sad, but harmless. You can change the number with a
-<Literal>-fmax-simplifier-iterations<N></Literal><IndexTerm><Primary>-fmax-simplifier-iterations<N> option</Primary></IndexTerm> option (no space);
+<Option>-fmax-simplifier-iterations<N></Option><IndexTerm><Primary>-fmax-simplifier-iterations<N> option</Primary></IndexTerm> option (no space);
and you can see what actions took place in each iteration by
-turning on the <Literal>-fshow-simplifier-progress</Literal>
+turning on the <Option>-fshow-simplifier-progress</Option>
<IndexTerm><Primary>-fshow-simplifier-progress option</Primary></IndexTerm> option.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term>Sensitivity to <Literal>.hi</Literal> interface files:</Term>
+<Term>Sensitivity to <Filename>.hi</Filename> interface files:</Term>
<ListItem>
<Para>
GHC is very sensitive about interface files. For example, if it picks
-up a non-standard <Literal>Prelude.hi</Literal> file, pretty terrible things will
+up a non-standard <Filename>Prelude.hi</Filename> file, pretty terrible things will
happen. If you turn on
-<Literal>-fno-implicit-prelude</Literal><IndexTerm><Primary>-fno-implicit-prelude option</Primary></IndexTerm>, the
+<Option>-fno-implicit-prelude</Option><IndexTerm><Primary>-fno-implicit-prelude option</Primary></IndexTerm>, the
compiler will almost surely die, unless you know what you are doing.
</Para>
<ListItem>
<Para>
Unlikely :-) A useful be-more-paranoid option to give to GHC is
-<Literal>-dcore-lint</Literal><IndexTerm><Primary>-dcore-lint option</Primary></IndexTerm>; this causes a ``lint''
+<Option>-dcore-lint</Option><IndexTerm><Primary>-dcore-lint option</Primary></IndexTerm>; this causes a ``lint''
pass to check for errors (notably type errors) after each Core-to-Core
-transformation pass. We run with <Literal>-dcore-lint</Literal> on all the time; it
+transformation pass. We run with <Option>-dcore-lint</Option> on all the time; it
costs about 5% in compile time.
</Para>
</ListItem>
</Para>
<Para>
-If you run <Literal>nm -o *.o | egrep 't (cc|hsc)\.'</Literal> (or, on
-unregisterised files: <Literal>what *.o</Literal>), you'll see all the consistency
+If you run <Command>nm -o *.o | egrep 't (cc|hsc)\.'</Command> (or, on
+unregisterised files: <Command>what *.o</Command>), you'll see all the consistency
tags/strings in your object files. They must all be the same!
(ToDo: tell you what they mean…)
</Para>
</Para>
<Para>
-If your program has no <Literal>_ccall_</Literal>s/<Literal>_casm_</Literal>s in it, then a crash is
+If your program has no <Function>_ccall_</Function>s/<Function>_casm_</Function>s in it, then a crash is
always a BUG in the GHC system, except in one case: If your program is
made of several modules, each module must have been compiled after any
-modules on which it depends (unless you use <Literal>.hi-boot</Literal> files, in which
+modules on which it depends (unless you use <Filename>.hi-boot</Filename> files, in which
case these <Emphasis>must</Emphasis> be correct with respect to the module source).
</Para>
<Para>
A useful option to alert you when interfaces change is
-<Literal>-hi-diffs</Literal><IndexTerm><Primary>-hi-diffs option</Primary></IndexTerm>. It will run <Literal>diff</Literal> on the
+<Option>-hi-diffs</Option><IndexTerm><Primary>-hi-diffs option</Primary></IndexTerm>. It will run <Command>diff</Command> on the
changed interface file, before and after, when applicable.
</Para>
<Para>
-If you are using <Literal>make</Literal>, a useful tool to make sure that every module
+If you are using <Command>make</Command>, a useful tool to make sure that every module
<Emphasis>is</Emphasis> up-to-date with respect to its imported interfaces is
-<Literal>mkdependHS</Literal> (which comes with GHC). Please see <XRef LinkEnd="mkdependHS">.
+<Command>mkdependHS</Command> (which comes with GHC). Please see <XRef LinkEnd="mkdependHS">.
</Para>
<Para>
If you are down to your last-compile-before-a-bug-report, we would
-recommend that you add a <Literal>-dcore-lint</Literal> option (for extra checking) to your compilation options.
+recommend that you add a <Option>-dcore-lint</Option> option (for extra checking) to your compilation options.
</Para>
<Para>
</Para>
<Para>
-Of course, if you have <Literal>_ccall_</Literal>s/<Literal>_casm_</Literal>s in your program then all
+Of course, if you have <Function>_ccall_</Function>s/<Function>_casm_</Function>s in your program then all
bets are off, because you can trash the heap, the stack, or whatever.
</Para>
<Para>
Glasgow Haskell is a changing system so there are sure to be bugs in
-it. Please report them to <ULink
-URL="mailto:glasgow-haskell-bugs@haskell.org"
->glasgow-haskell-bugs@haskell.org</ULink
->! (However, please
+it. Please report them to <Email>glasgow-haskell-bugs@haskell.org</Email>! (However, please
check the earlier part of this section to be sure it's not a known
not-really-a problem.)
</Para>
<Para>
What kind of machine are you running on, and exactly what
-version of the operating system are you using? (<Literal>uname -a</Literal> or <Literal>cat
-/etc/motd</Literal> will show the desired information.)
+version of the operating system are you using? (<Command>uname -a</Command> or <Command>cat
+/etc/motd</Command> will show the desired information.)
</Para>
</ListItem>
<ListItem>
<Para>
- What version of GCC are you using? <Literal>gcc -v</Literal> will tell you.
+ What version of GCC are you using? <Command>gcc -v</Command> will tell you.
</Para>
</ListItem>
<ListItem>
<Para>
- Be sure any Haskell compilations are run with a <Literal>-v</Literal> (verbose)
+ Be sure any Haskell compilations are run with a <Option>-v</Option> (verbose)
flag, so we can see exactly what was run, what versions of things you
have, etc.
<Para>
The first thing to establish is: Is it a garbage-collection (GC) bug?
-Try your program with a very large heap and a <Literal>-Sstderr</Literal> RTS
+Try your program with a very large heap and a <Option>-Sstderr</Option> RTS
flag.
<ItemizedList>
<Para>
If it crashes with the normal
-collector, but not when you force two-space collection (<Literal>-F2s</Literal>
+collector, but not when you force two-space collection (<Option>-F2s</Option>
runtime flag), then it <Emphasis>probably is</Emphasis> a GC bug.
</Para>
</ListItem>
<Para>
If it <Emphasis>is</Emphasis> a GC bug, you may be able to avoid it by using a
-particular heap size or by using a <Literal>-F2s</Literal> runtime flag. (But don't
+particular heap size or by using a <Option>-F2s</Option> runtime flag. (But don't
forget to report the bug!!!)
</Para>
<Para>
This section describes a collection of Haskell libraries we've
collected over the years. Access to any of these modules is provided
-by giving the <Literal>-syslib misc</Literal><IndexTerm><Primary>-syslib misc option</Primary></IndexTerm>.
+by giving the <Option>-syslib misc</Option><IndexTerm><Primary>-syslib misc option</Primary></IndexTerm>.
</Para>
<Sect2 id="Bag">
</Para>
<Para>
-NB: <Literal>catMaybes</Literal> which used to be here, is now available via the
+NB: <Function>catMaybes</Function> which used to be here, is now available via the
standard <Literal>Maybe</Literal> interface (<Literal>Maybe</Literal> is an instance of <Literal>MonadPlus</Literal>).
</Para>
<Para>
-<Literal>allMaybes</Literal> collects a list of <Literal>Justs</Literal> into a single <Literal>Just</Literal>, returning
+<Function>allMaybes</Function> collects a list of <Literal>Justs</Literal> into a single <Literal>Just</Literal>, returning
<Literal>Nothing</Literal> if there are any <Literal>Nothings</Literal>.
</Para>
<Para>
-<Literal>firstJust</Literal> takes a list of <Literal>Maybes</Literal> and returns the
+<Function>firstJust</Function> takes a list of <Literal>Maybes</Literal> and returns the
first <Literal>Just</Literal> if there is one, or <Literal>Nothing</Literal> otherwise.
</Para>
<Para>
-<Literal>assocMaybe</Literal> looks up in an association list, returning
+<Function>assocMaybe</Function> looks up in an association list, returning
<Literal>Nothing</Literal> if it fails.
</Para>
</Para>
<Para>
-<Literal>listMaybeErrs</Literal> takes a list of <Literal>MaybeErrs</Literal> and, if they all succeed,
+<Function>listMaybeErrs</Function> takes a list of <Literal>MaybeErrs</Literal> and, if they all succeed,
returns a <Literal>Succeeded</Literal> of a list of their values. If any fail, it
returns a <Literal>Failed</Literal> of the list of all the errors in the list.
</Para>
<Para>
-<Literal>foldlMaybeErrs</Literal> works along a list, carrying an accumulator; it
+<Function>foldlMaybeErrs</Function> works along a list, carrying an accumulator; it
applies the given function to the accumulator and the next list item,
accumulating any errors that occur.
</Para>
</Para>
<Para>
-So, for example, <Literal>memo f</Literal> is a version of <Literal>f</Literal> that caches the results
+So, for example, <Function>memo f</Function> is a version of <Function>f</Function> that caches the results
of previous calls.
</Para>
</Para>
<Para>
-There's another version of <Literal>memo</Literal> if you want to explicitly give a
+There's another version of <Function>memo</Function> if you want to explicitly give a
size for the hash table (the default size is 1001 buckets):
</Para>
<Para>
You need to <Literal>import PackedString</Literal> and heave in your
-<Literal>-syslib ghc</Literal> to use <Literal>PackedString</Literal>s.
+<Option>-syslib ghc</Option> to use <Literal>PackedString</Literal>s.
</Para>
<Para>
</Para>
<Para>
-The GHC system library (<Literal>-syslib misc</Literal>) also provides interfaces to
+The GHC system library (<Option>-syslib misc</Option>) also provides interfaces to
several useful C libraries, mostly from the GNU project.
</Para>
<Para>
The <Literal>Readline</Literal> module is a straightforward interface to the GNU
Readline library. As such, you will need to look at the GNU
-documentation (and have a <Literal>libreadline.a</Literal> file around somewhere…)
+documentation (and have a <Filename>libreadline.a</Filename> file around somewhere…)
</Para>
<Para>
-You'll need to link any Readlining program with <Literal>-lreadline -ltermcap</Literal>,
-besides the usual <Literal>-syslib ghc</Literal> (and <Literal>-fhaskell-1.3</Literal>).
+You'll need to link any Readlining program with <Option>-lreadline -ltermcap</Option>,
+besides the usual <Option>-syslib ghc</Option> (and <Option>-fhaskell-1.3</Option>).
</Para>
<Para>
The <Literal>MatchPS</Literal> module provides Perl-like ``higher-level'' facilities
to operate on <Literal>PackedStrings</Literal>. The regular expressions in
question are in Perl syntax. The ``flags'' on various functions can
-include: <Literal>i</Literal> for case-insensitive, <Literal>s</Literal> for single-line mode, and
-<Literal>g</Literal> for global. (It's probably worth your time to peruse the
+include: <Option>i</Option> for case-insensitive, <Option>s</Option> for single-line mode, and
+<Option>g</Option> for global. (It's probably worth your time to peruse the
source code…)
</Para>
<Para>
Your best bet for documentation is to look at the code—really!—
normally in
-<Literal>fptools/ghc/lib/misc/{BSD,Socket,SocketPrim</Literal>.lhs}.
+<Filename>fptools/ghc/lib/misc/{BSD,Socket,SocketPrim</Filename>.lhs}.
</Para>
<Para>
</Para>
<Para>
-The <Literal>Select</Literal> interface provides a Haskell wrapper for the <Literal>select()</Literal>
+The <Literal>Select</Literal> interface provides a Haskell wrapper for the <Function>select()</Function>
OS call supplied by many modern UNIX variants. <Literal>Select</Literal> exports the
following:
</Para>
</Para>
<Para>
-where the call to <Literal>hSelect</Literal> makes the process go to sleep
-until there's input available on <Literal>stdin</Literal>.
+where the call to <Function>hSelect</Function> makes the process go to sleep
+until there's input available on <VarName>stdin</VarName>.
</Para>
<Para>
-Notice that this particular use of <Literal>hSelect</Literal> is now really a no-op
+Notice that this particular use of <Function>hSelect</Function> is now really a no-op
with GHC compiled code, as its implementation of IO will take care to
avoid blocking the process (i.e., all running Haskell threads), and
-call <Literal>select()</Literal> for you, if needs be. However, <Literal>hSelect</Literal> exposes
+call <Function>select()</Function> for you, if needs be. However, <Function>hSelect</Function> exposes
functionality that is useful in other contexts (e.g., you want to
wait for input on two <Literal>Handles</Literal> for 3 seconds, but no longer.)
</Para>
<VariableList>
<VarListEntry>
-<Term><Literal>fromInt</Literal> method in class <Literal>Num</Literal>:</Term>
+<Term><Function>fromInt</Function> method in class <Literal>Num</Literal>:</Term>
<ListItem>
<Para>
It's there. Converts from
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>toInt</Literal> method in class <Literal>Integral</Literal>:</Term>
+<Term><Function>toInt</Function> method in class <Literal>Integral</Literal>:</Term>
<ListItem>
<Para>
Converts from Integral
don't recommend that you use any module names beginning with <Literal>Prel</Literal> in
your own programs. The <Literal>Prel</Literal> modules are always available: in fact,
you can get access to several extensions this way (for some you might
-need to give the <Literal>-fglasgow-exts</Literal><IndexTerm><Primary>-fglasgow-exts option</Primary></IndexTerm>
+need to give the <Option>-fglasgow-exts</Option><IndexTerm><Primary>-fglasgow-exts option</Primary></IndexTerm>
flag).
</Para>
The extension libraries provided by both GHC and Hugs are described in
the
<ULink
-URL="http://www.dcs.gla.ac.uk/fp/software/ghc/hg-libs/hg-libs.html"
->GHC/Hugs Extension Library Document</ULink
->
+URL="libs.html">GHC/Hugs Extension Library Document</ULink>
</Para>
</Sect1>
<Para>
If you rely on the implicit <Literal>import Prelude</Literal> that GHC normally does
for you, and if you don't use any weird flags (notably
-<Literal>-fglasgow-exts</Literal>), and if you don't import the Glasgow extensions
+<Option>-fglasgow-exts</Option>), and if you don't import the Glasgow extensions
interface, <Literal>GlaExts</Literal>, then GHC should work <Emphasis>exactly</Emphasis> as the
Haskell report says (modulo a few minor issues, see <XRef LinkEnd="vs-Haskell-defn">).
</Para>
<Para>
-If you turn on <Literal>-fglasgow-exts</Literal>, a new world opesn up to you and the compiler
+If you turn on <Option>-fglasgow-exts</Option>, a new world opesn up to you and the compiler
will recognise and parse unboxed values properly, and provide access to the
various interfaces libraries described here (and piles of other goodies.)
</Para>
<Para>
The <Literal>CCall</Literal> module defines the classes <Literal>CCallable</Literal> and <Literal>CReturnable</Literal>,
along with instances for the primitive types (<Literal>Int</Literal>, <Literal>Int#</Literal>, <Literal>Float</Literal>,
-<Literal>Float#</Literal> etc.) GHC knows to import this module if you use <Literal>_ccall_</Literal>,
+<Literal>Float#</Literal> etc.) GHC knows to import this module if you use <Function>_ccall_</Function>,
but if you need to define your own instances of these classes, you
will need to import <Literal>CCall</Literal> explicitly.
</Para>
<Para>
-More information on how to use <Literal>_ccall_</Literal> can be found in <XRef LinkEnd="glasgow-ccalls">.
+More information on how to use <Function>_ccall_</Function> can be found in <XRef LinkEnd="glasgow-ccalls">.
</Para>
</Sect2>
The <Literal>GlaExts</Literal> interface provides access to extensions that only GHC
implements. These currently are: unboxed types, including the
representations of the primitive types (Int, Float, etc.), and the
-GHC primitive operations (<Literal>+#</Literal>, <Literal>==#</Literal>, etc.).
+GHC primitive operations (<Function>+#</Function>, <Function>==#</Function>, etc.).
</Para>
<Para>
<Para>
Unboxed tuples aren't really exported by <Literal>PrelGHC</Literal>, they're available
-by default with <Literal>-fglasgow-exts</Literal>. An unboxed tuple looks like this:
+by default with <Option>-fglasgow-exts</Option>. An unboxed tuple looks like this:
</Para>
<Para>
</ProgramListing>
-because <Literal>x</Literal> has an unboxed tuple type.
+because <VarName>x</VarName> has an unboxed tuple type.
</Para>
</ListItem>
<Para>
If you really want to know their exact equivalents in C, see
-<Literal>ghc/includes/StgTypes.h</Literal> in the GHC source tree.
+<Filename>ghc/includes/StgTypes.h</Filename> in the GHC source tree.
</Para>
<Para>
</Para>
<Para>
-The primitive versions of <Literal>encodeDouble</Literal>/<Literal>decodeDouble</Literal>:
+The primitive versions of <Function>encodeDouble</Function>/<Function>decodeDouble</Function>:
</Para>
<Para>
<Para>
The data type for <Literal>Integer</Literal> is either a small integer,
represented by an <Literal>Int</Literal>, or a large integer represented
-using the pieces requird by GMP's <Literal>MP_INT</Literal> in <Literal>gmp.h</Literal>
-(see <Literal>gmp.info</Literal> in <Literal>ghc/includes/runtime/gmp</Literal>). It comes out as:
+using the pieces required by GMP's <Literal>MP_INT</Literal> in <Filename>gmp.h</Filename>
+(see <Filename>gmp.info</Filename> in <Filename>ghc/includes/runtime/gmp</Filename>). It comes out as:
</Para>
<Para>
Haskell <Literal>Array</Literal> interface is implemented using <Literal>Array#</Literal>—in that an
<Literal>Array#</Literal> is indexed only by <Literal>Int#</Literal>s, starting at zero. It is also
more primitive by virtue of being unboxed. That doesn't mean that it
-isn't a heap-allocated object - of course, it is. Rather, being
+isn't a heap-allocated object—of course, it is. Rather, being
unboxed means that it is represented by a pointer to the array itself,
and not to a thunk which will evaluate to the array (or to bottom).
The components of an <Literal>Array#</Literal> are themselves boxed.
</Para>
<Para>
-The last of these, <Literal>indexAddrOffAddr#</Literal>, extracts an <Literal>Addr#</Literal> using an offset
+The last of these, <Function>indexAddrOffAddr#</Function>, extracts an <Literal>Addr#</Literal> using an offset
from another <Literal>Addr#</Literal>, thereby providing the ability to follow a chain of
C pointers.
</Para>
<Para>
Only unsafe-freeze has a primitive. (Safe freeze is done directly in Haskell
-by copying the array and then using <Literal>unsafeFreeze</Literal>.)
+by copying the array and then using <Function>unsafeFreeze</Function>.)
</Para>
<Para>
</Para>
<Para>
-The <Literal>makeStablePointer</Literal> function converts a value into a stable
+The <Function>makeStablePointer</Function> function converts a value into a stable
pointer. It is part of the <Literal>IO</Literal> monad, because we want to be sure
we don't allocate one twice by accident, and then only free one of the
copies.
</Para>
<Para>
-There is also a C procedure <Literal>FreeStablePtr</Literal> which frees a stable pointer.
+There is also a C procedure <Function>FreeStablePtr</Function> which frees a stable pointer.
</Para>
</Sect2>
-<Preface>
+<Preface id="License">
<Title>The Glasgow Haskell Compiler License</Title>
<Para>
<Para>
<IndexTerm><Primary>Concurrent Haskell</Primary></IndexTerm>
<IndexTerm><Primary>Parallel Haskell</Primary></IndexTerm>
-</Para>
-
-<Para>
Concurrent and Parallel Haskell are Glasgow extensions to Haskell
which let you structure your program as a group of independent
`threads'.
<Para>
The expression <Literal>(x `seq` y)</Literal> evaluates <Literal>x</Literal> to weak head normal
-form and then returns <Literal>y</Literal>. The <Literal>seq</Literal> primitive can be used to
+form and then returns <Literal>y</Literal>. The <Function>seq</Function> primitive can be used to
force evaluation of an expression beyond WHNF, or to impose a desired
execution sequence for the evaluation of an expression.
</Para>
<Para>
For example, consider the following parallel version of our old
-nemesis, <Literal>nfib</Literal>:
+nemesis, <Function>nfib</Function>:
</Para>
<Para>
</Para>
<Para>
-For values of <Literal>n</Literal> greater than 1, we use <Literal>par</Literal> to spark a thread
-to evaluate <Literal>nfib (n-1)</Literal>, and then we use <Literal>seq</Literal> to force the
+For values of <VarName>n</VarName> greater than 1, we use <Function>par</Function> to spark a thread
+to evaluate <Literal>nfib (n-1)</Literal>, and then we use <Function>seq</Function> to force the
parent thread to evaluate <Literal>nfib (n-2)</Literal> before going on to add
together these two subexpressions. In this divide-and-conquer
approach, we only spark a new thread for one branch of the computation
(leaving the parent to evaluate the other branch). Also, we must use
-<Literal>seq</Literal> to ensure that the parent will evaluate <Literal>n2</Literal> <Emphasis>before</Emphasis>
-<Literal>n1</Literal> in the expression <Literal>(n1 + n2 + 1)</Literal>. It is not sufficient to
+<Function>seq</Function> to ensure that the parent will evaluate <VarName>n2</VarName> <Emphasis>before</Emphasis>
+<VarName>n1</VarName> in the expression <Literal>(n1 + n2 + 1)</Literal>. It is not sufficient to
reorder the expression as <Literal>(n2 + n1 + 1)</Literal>, because the compiler may
not generate code to evaluate the addends from left to right.
</Para>
<IndexTerm><Primary>primitives for parallelism</Primary></IndexTerm></Title>
<Para>
-The functions <Literal>par</Literal> and <Literal>seq</Literal> are wired into GHC, and unfold
-into uses of the <Literal>par#</Literal> and <Literal>seq#</Literal> primitives, respectively. If
+The functions <Function>par</Function> and <Function>seq</Function> are wired into GHC, and unfold
+into uses of the <Function>par#</Function> and <Function>seq#</Function> primitives, respectively. If
you'd like to see this with your very own eyes, just run GHC with the
-<Literal>-ddump-simpl</Literal> option. (Anything for a good time…)
+<Option>-ddump-simpl</Option> option. (Anything for a good time…)
</Para>
</Sect3>
Runnable threads are scheduled in round-robin fashion. Context
switches are signalled by the generation of new sparks or by the
expiry of a virtual timer (the timer interval is configurable with the
-<Literal>-C[<num>]</Literal><IndexTerm><Primary>-C<num> RTS option (concurrent,
+<Option>-C[<num>]</Option><IndexTerm><Primary>-C<num> RTS option (concurrent,
parallel)</Primary></IndexTerm> RTS option). However, a context switch doesn't
really happen until the current heap block is full. You can't get any
faster context switching than this.
been reduced to weak head normal form are turned into new threads.
However, there is a limit to the number of active threads (runnable or
blocked) which are allowed at any given time. This limit can be
-adjusted with the <Literal>-t<num></Literal><IndexTerm><Primary>-t <num> RTS option (concurrent, parallel)</Primary></IndexTerm>
+adjusted with the <Option>-t<num></Option><IndexTerm><Primary>-t <num> RTS option (concurrent, parallel)</Primary></IndexTerm>
RTS option (the default is 32). Once the
thread limit is reached, any remaining sparks are deferred until some
of the currently active threads are completed.
services standardised by POSIX 1003.1b (or the <Emphasis>IEEE Portable
Operating System Interface for Computing Environments</Emphasis> - IEEE Std.
1003.1). The interface is accessed by <Literal>import Posix</Literal> and
-adding <Literal>-syslib posix</Literal> on your command-line.
+adding <Option>-syslib posix</Option> on your command-line.
</Para>
<Sect2 id="Posix-data-types">
</Para>
<Para>
-<Literal>forkProcess</Literal> calls <Literal>fork</Literal>, returning
-<Literal>Just pid</Literal> to the parent, where <Literal>pid</Literal> is the
+<Function>forkProcess</Function> calls <Function>fork</Function>, returning
+<Literal>Just pid</Literal> to the parent, where <VarName>pid</VarName> is the
ProcessID of the child, and returning <Literal>Nothing</Literal> to the
child.
</Para>
<Para>
<Literal>executeFile cmd args env</Literal> calls one of the
-<Literal>execv*</Literal> family, depending on whether or not the current
+<Function>execv*</Function> family, depending on whether or not the current
PATH is to be searched for the command, and whether or not an
environment is provided to supersede the process's current
environment. The basename (leading directory names suppressed) of
-the command is passed to <Literal>execv*</Literal> as <Literal>arg[0]</Literal>;
-the argument list passed to <Literal>executeFile</Literal> therefore begins
-with <Literal>arg[1]</Literal>.
+the command is passed to <Function>execv*</Function> as <VarName>arg[0]</VarName>;
+the argument list passed to <Function>executeFile</Function> therefore begins with <VarName>arg[1]</VarName>.
</Para>
<Para>
</Para>
<Para>
-Note that <Literal>execvpe</Literal> is not provided by the POSIX standard, and must
+Note that <Function>execvpe</Function> is not provided by the POSIX standard, and must
be written by hand. Care must be taken to ensure that the search path
is extracted from the original environment, and not from the
environment to be passed on to the new image.
<Para>
NOTE: In general, sharing open files between parent and child
processes is potential bug farm, and should be avoided unless you
-really depend on this `feature' of POSIX' <Literal>fork()</Literal> semantics. Using
+really depend on this `feature' of POSIX' <Function>fork()</Function> semantics. Using
Haskell, there's the extra complication that arguments to
-<Literal>executeFile</Literal> might come from files that are read lazily (using
-<Literal>hGetContents</Literal>, or some such.) If this is the case, then for your own
-sanity, please ensure that the arguments to <Literal>executeFile</Literal> have been
-fully evaluated before calling <Literal>forkProcess</Literal> (followed by
-<Literal>executeFile</Literal>.) Consider yourself warned :-)
+<Function>executeFile</Function> might come from files that are read lazily (using
+<Function>hGetContents</Function>, or some such.) If this is the case, then for your own
+sanity, please ensure that the arguments to <Function>executeFile</Function> have been
+fully evaluated before calling <Function>forkProcess</Function> (followed by
+<Function>executeFile</Function>.) Consider yourself warned :-)
</Para>
<Para>
-A successful <Literal>executeFile</Literal> overlays the current process image with
+A successful <Function>executeFile</Function> overlays the current process image with
a new one, so it only returns on failure.
</Para>
</Para>
<Para>
-<Literal>runProcess</Literal> is our candidate for the high-level OS-independent
+<Function>runProcess</Function> is our candidate for the high-level OS-independent
primitive.
</Para>
<Para>
-<Literal>runProcess cmd args env wd inhdl outhdl errhdl</Literal> runs <Literal>cmd</Literal>
+<Literal>runProcess cmd args env wd inhdl outhdl errhdl</Literal> runs <Command>cmd</Command>
(searching the current <Literal>PATH</Literal>) with arguments <Literal>args</Literal>. If
<Literal>env</Literal> is <Literal>Just pairs</Literal>, the command is executed with the
environment specified by <Literal>pairs</Literal> of variables and values;
</Para>
<Para>
-<Literal>getProcessStatus blk stopped pid</Literal> calls <Literal>waitpid</Literal>, returning
+<Literal>getProcessStatus blk stopped pid</Literal> calls <Function>waitpid</Function>, returning
<Literal>Just tc</Literal>, the <Literal>ProcessStatus</Literal> for process <Literal>pid</Literal> if it is
available, <Literal>Nothing</Literal> otherwise. If <Literal>blk</Literal> is <Literal>False</Literal>, then
-<Literal>WNOHANG</Literal> is set in the options for <Literal>waitpid</Literal>, otherwise not.
+<Literal>WNOHANG</Literal> is set in the options for <Function>waitpid</Function>, otherwise not.
If <Literal>stopped</Literal> is <Literal>True</Literal>, then <Literal>WUNTRACED</Literal> is set in the
-options for <Literal>waitpid</Literal>, otherwise not.
+options for <Function>waitpid</Function>, otherwise not.
</Para>
<Para>
</Para>
<Para>
-<Literal>getGroupProcessStatus blk stopped pgid</Literal> calls <Literal>waitpid</Literal>,
+<Literal>getGroupProcessStatus blk stopped pgid</Literal> calls <Function>waitpid</Function>,
returning <Literal>Just (pid, tc)</Literal>, the <Literal>ProcessID</Literal> and
<Literal>ProcessStatus</Literal> for any process in group <Literal>pgid</Literal> if one is
available, <Literal>Nothing</Literal> otherwise. If <Literal>blk</Literal> is <Literal>False</Literal>, then
-<Literal>WNOHANG</Literal> is set in the options for <Literal>waitpid</Literal>, otherwise not.
+<Literal>WNOHANG</Literal> is set in the options for <Function>waitpid</Function>, otherwise not.
If <Literal>stopped</Literal> is <Literal>True</Literal>, then <Literal>WUNTRACED</Literal> is set in the
-options for <Literal>waitpid</Literal>, otherwise not.
+options for <Function>waitpid</Function>, otherwise not.
</Para>
<Para>
</Para>
<Para>
-<Literal>getAnyProcessStatus blk stopped</Literal> calls <Literal>waitpid</Literal>, returning
+<Literal>getAnyProcessStatus blk stopped</Literal> calls <Function>waitpid</Function>, returning
<Literal>Just (pid, tc)</Literal>, the <Literal>ProcessID</Literal> and <Literal>ProcessStatus</Literal> for any
child process if one is available, <Literal>Nothing</Literal> otherwise. If
<Literal>blk</Literal> is <Literal>False</Literal>, then <Literal>WNOHANG</Literal> is set in the options for
-<Literal>waitpid</Literal>, otherwise not. If <Literal>stopped</Literal> is <Literal>True</Literal>, then
-<Literal>WUNTRACED</Literal> is set in the options for <Literal>waitpid</Literal>, otherwise not.
+<Function>waitpid</Function>, otherwise not. If <Literal>stopped</Literal> is <Literal>True</Literal>, then
+<Literal>WUNTRACED</Literal> is set in the options for <Function>waitpid</Function>, otherwise not.
</Para>
<Para>
</Para>
<Para>
-<Literal>exitImmediately status</Literal> calls <Literal>_exit</Literal> to terminate the process
+<Literal>exitImmediately status</Literal> calls <Function>_exit</Function> to terminate the process
with the indicated exit <Literal>status</Literal>.
The operation never returns.
</Para>
</Para>
<Para>
-<Literal>getEnvironment</Literal> parses the environment variable mapping provided by
+<Function>getEnvironment</Function> parses the environment variable mapping provided by
<Literal>environ</Literal>, returning <Literal>(variable, value)</Literal> pairs.
The operation never fails.
</Para>
</Para>
<Para>
-<Literal>setEnvironment</Literal> replaces the process environment with the provided
+<Function>setEnvironment</Function> replaces the process environment with the provided
mapping of <Literal>(variable, value)</Literal> pairs.
</Para>
</Para>
<Para>
-<Literal>getEnvVar var</Literal> returns the value associated with variable <Literal>var</Literal>
+<Literal>getEnvVar var</Literal> returns the value associated with variable <VarName>var</VarName>
in the current environment (identical functionality provided through
-standard Haskell library function <Literal>System.getEnv</Literal>).
+standard Haskell library function <Function>System.getEnv</Function>).
</Para>
<Para>
</Para>
<Para>
-<Literal>setEnvVar var val</Literal> sets the value associated with variable <Literal>var</Literal>
+<Literal>setEnvVar var val</Literal> sets the value associated with variable <VarName>var</VarName>
in the current environment to be <Literal>val</Literal>. Any previous mapping is
superseded.
</Para>
</Para>
<Para>
-<Literal>removeEnvVar var</Literal> removes any value associated with variable <Literal>var</Literal>
+<Literal>removeEnvVar var</Literal> removes any value associated with variable <VarName>var</VarName>
in the current environment. Deleting a variable for which there is no mapping
does not generate an error.
</Para>
</Para>
<Para>
-<Literal>signalProcess int pid</Literal> calls <Literal>kill</Literal> to signal
+<Literal>signalProcess int pid</Literal> calls <Function>kill</Function> to signal
process <Literal>pid</Literal> with interrupt signal <Literal>int</Literal>.
</Para>
</Para>
<Para>
-<Literal>raiseSignal int</Literal> calls <Literal>kill</Literal> to signal the current process
+<Literal>raiseSignal int</Literal> calls <Function>kill</Function> to signal the current process
with interrupt signal <Literal>int</Literal>.
</Para>
</Para>
<Para>
-<Literal>signalProcessGroup int pgid</Literal> calls <Literal>kill</Literal> to signal
+<Literal>signalProcessGroup int pgid</Literal> calls <Function>kill</Function> to signal
all processes in group <Literal>pgid</Literal> with interrupt signal <Literal>int</Literal>.
</Para>
<Para>
<Literal>setStoppedChildFlag bool</Literal> sets a flag which controls whether or
-not the <Literal>NOCLDSTOP</Literal> option will be used the next time a signal
-handler is installed for <Literal>SIGCHLD</Literal>. If <Literal>bool</Literal> is <Literal>True</Literal> (the
-default), <Literal>NOCLDSTOP</Literal> will not be used; otherwise it will be. The
+not the <Constant>NOCLDSTOP</Constant> option will be used the next time a signal
+handler is installed for <Constant>SIGCHLD</Constant>. If <Literal>bool</Literal> is <Literal>True</Literal> (the
+default), <Constant>NOCLDSTOP</Constant> will not be used; otherwise it will be. The
operation never fails.
</Para>
</Para>
<Para>
-<Literal>queryStoppedChildFlag</Literal> queries the flag which
-controls whether or not the <Literal>NOCLDSTOP</Literal> option will be used
-the next time a signal handler is installed for <Literal>SIGCHLD</Literal>.
-If <Literal>NOCLDSTOP</Literal> will be used, it returns <Literal>False</Literal>;
+<Function>queryStoppedChildFlag</Function> queries the flag which
+controls whether or not the <Constant>NOCLDSTOP</Constant> option will be used
+the next time a signal handler is installed for <Constant>SIGCHLD</Constant>.
+If <Constant>NOCLDSTOP</Constant> will be used, it returns <Literal>False</Literal>;
otherwise (the default) it returns <Literal>True</Literal>.
The operation never fails.
</Para>
</Para>
<Para>
-<Literal>installHandler int handler iset</Literal> calls <Literal>sigaction</Literal> to install an
+<Literal>installHandler int handler iset</Literal> calls <Constant>sigaction</Constant> to install an
interrupt handler for signal <Literal>int</Literal>. If <Literal>handler</Literal> is <Literal>Default</Literal>,
-<Literal>SIG_DFL</Literal> is installed; if <Literal>handler</Literal> is <Literal>Ignore</Literal>, <Literal>SIG_IGN</Literal> is
+<Constant>SIG_DFL</Constant> is installed; if <Literal>handler</Literal> is <Literal>Ignore</Literal>, <Constant>SIG_IGN</Constant> is
installed; if <Literal>handler</Literal> is <Literal>Catch action</Literal>, a handler is installed
which will invoke <Literal>action</Literal> in a new thread when (or shortly after) the
signal is received. See <XRef LinkEnd="concurrent-haskell"> for details on how to communicate between
</Para>
<Para>
-If <Literal>iset</Literal> is <Literal>Just s</Literal>, then the <Literal>sa_mask</Literal> of the <Literal>sigaction</Literal> structure
+If <Literal>iset</Literal> is <Literal>Just s</Literal>, then the <VarName>sa_mask</VarName> of the <Literal>sigaction</Literal> structure
is set to <Literal>s</Literal>; otherwise it is cleared. The previously installed
signal handler for <Literal>int</Literal> is returned.
</Para>
</Para>
<Para>
-<Literal>getSignalMask</Literal> calls <Literal>sigprocmask</Literal> to determine the
+<Function>getSignalMask</Function> calls <Function>sigprocmask</Function> to determine the
set of interrupts which are currently being blocked.
</Para>
</Para>
<Para>
-<Literal>setSignalMask mask</Literal> calls <Literal>sigprocmask</Literal> with
-<Literal>SIG_SETMASK</Literal> to block all interrupts in <Literal>mask</Literal>. The
+<Literal>setSignalMask mask</Literal> calls <Function>sigprocmask</Function> with
+<Constant>SIG_SETMASK</Constant> to block all interrupts in <Literal>mask</Literal>. The
previous set of blocked interrupts is returned.
</Para>
</Para>
<Para>
-<Literal>setSignalMask mask</Literal> calls <Literal>sigprocmask</Literal> with
-<Literal>SIG_BLOCK</Literal> to add all interrupts in <Literal>mask</Literal> to the
+<Literal>setSignalMask mask</Literal> calls <Function>sigprocmask</Function> with
+<Constant>SIG_BLOCK</Constant> to add all interrupts in <Literal>mask</Literal> to the
set of blocked interrupts. The previous set of blocked interrupts is returned.
</Para>
</Para>
<Para>
-<Literal>setSignalMask mask</Literal> calls <Literal>sigprocmask</Literal> with
-<Literal>SIG_UNBLOCK</Literal> to remove all interrupts in <Literal>mask</Literal> from the
+<Literal>setSignalMask mask</Literal> calls <Function>sigprocmask</Function> with
+<Constant>SIG_UNBLOCK</Constant> to remove all interrupts in <Literal>mask</Literal> from the
set of blocked interrupts. The previous set of blocked interrupts is returned.
</Para>
</Para>
<Para>
-<Literal>getPendingSignals</Literal> calls <Literal>sigpending</Literal> to obtain
+<Function>getPendingSignals</Function> calls <Function>sigpending</Function> to obtain
the set of interrupts which have been received but are currently blocked.
</Para>
<Para>
<Literal>awaitSignal iset</Literal> suspends execution until an interrupt is received.
-If <Literal>iset</Literal> is <Literal>Just s</Literal>, <Literal>awaitSignal</Literal> calls <Literal>sigsuspend</Literal>, installing
+If <Literal>iset</Literal> is <Literal>Just s</Literal>, <Function>awaitSignal</Function> calls <Function>sigsuspend</Function>, installing
<Literal>s</Literal> as the new signal mask before suspending execution; otherwise, it
-calls <Literal>pause</Literal>. <Literal>awaitSignal</Literal> returns on receipt of a signal. If you
-have installed any signal handlers with <Literal>installHandler</Literal>, it may be
-wise to call <Literal>yield</Literal> directly after <Literal>awaitSignal</Literal> to ensure that the
+calls <Function>pause</Function>. <Function>awaitSignal</Function> returns on receipt of a signal. If you
+have installed any signal handlers with <Function>installHandler</Function>, it may be
+wise to call <Function>yield</Function> directly after <Function>awaitSignal</Function> to ensure that the
signal handler runs as promptly.
</Para>
</Para>
<Para>
-<Literal>scheduleAlarm i</Literal> calls <Literal>alarm</Literal> to schedule a real time
+<Literal>scheduleAlarm i</Literal> calls <Function>alarm</Function> to schedule a real time
alarm at least <Literal>i</Literal> seconds in the future.
</Para>
</Para>
<Para>
-<Literal>sleep i</Literal> calls <Literal>sleep</Literal> to suspend execution of the
+<Literal>sleep i</Literal> calls <Function>sleep</Function> to suspend execution of the
program until at least <Literal>i</Literal> seconds have elapsed or a signal is
received.
</Para>
</Para>
<Para>
-<Literal>getProcessID</Literal> calls <Literal>getpid</Literal> to obtain the <Literal>ProcessID</Literal> for
+<Function>getProcessID</Function> calls <Function>getpid</Function> to obtain the <Literal>ProcessID</Literal> for
the current process.
</Para>
</Para>
<Para>
-<Literal>getProcessID</Literal> calls <Literal>getppid</Literal> to obtain the <Literal>ProcessID</Literal> for
+<Function>getProcessID</Function> calls <Function>getppid</Function> to obtain the <Literal>ProcessID</Literal> for
the parent of the current process.
</Para>
</Para>
<Para>
-<Literal>getRealUserID</Literal> calls <Literal>getuid</Literal> to obtain the real <Literal>UserID</Literal>
+<Function>getRealUserID</Function> calls <Function>getuid</Function> to obtain the real <Literal>UserID</Literal>
associated with the current process.
</Para>
</Para>
<Para>
-<Literal>getRealUserID</Literal> calls <Literal>geteuid</Literal> to obtain the effective
+<Function>getRealUserID</Function> calls <Function>geteuid</Function> to obtain the effective
<Literal>UserID</Literal> associated with the current process.
</Para>
</Para>
<Para>
-<Literal>setUserID uid</Literal> calls <Literal>setuid</Literal> to set the real, effective, and
+<Literal>setUserID uid</Literal> calls <Function>setuid</Function> to set the real, effective, and
saved set-user-id associated with the current process to <Literal>uid</Literal>.
</Para>
</Para>
<Para>
-<Literal>getLoginName</Literal> calls <Literal>getlogin</Literal> to obtain the login name
+<Function>getLoginName</Function> calls <Function>getlogin</Function> to obtain the login name
associated with the current process.
</Para>
</Para>
<Para>
-<Literal>getRealGroupID</Literal> calls <Literal>getgid</Literal> to obtain the real <Literal>GroupID</Literal>
+<Function>getRealGroupID</Function> calls <Function>getgid</Function> to obtain the real <Literal>GroupID</Literal>
associated with the current process.
</Para>
</Para>
<Para>
-<Literal>getEffectiveGroupID</Literal> calls <Literal>getegid</Literal> to obtain the effective
+<Function>getEffectiveGroupID</Function> calls <Function>getegid</Function> to obtain the effective
<Literal>GroupID</Literal> associated with the current process.
</Para>
</Para>
<Para>
-<Literal>setGroupID gid</Literal> calls <Literal>setgid</Literal> to set the real, effective, and
+<Literal>setGroupID gid</Literal> calls <Function>setgid</Function> to set the real, effective, and
saved set-group-id associated with the current process to <Literal>gid</Literal>.
</Para>
</Para>
<Para>
-<Literal>getGroups</Literal> calls <Literal>getgroups</Literal> to obtain the list of
+<Function>getGroups</Function> calls <Function>getgroups</Function> to obtain the list of
supplementary <Literal>GroupID</Literal>s associated with the current process.
</Para>
</Para>
<Para>
-<Literal>getEffectiveUserName</Literal> calls <Literal>cuserid</Literal> to obtain a name
+<Function>getEffectiveUserName</Function> calls <Function>cuserid</Function> to obtain a name
associated with the effective <Literal>UserID</Literal> of the process.
</Para>
</Para>
<Para>
-<Literal>getProcessGroupID</Literal> calls <Literal>getpgrp</Literal> to obtain the
+<Function>getProcessGroupID</Function> calls <Function>getpgrp</Function> to obtain the
<Literal>ProcessGroupID</Literal> for the current process.
</Para>
</Para>
<Para>
-<Literal>createProcessGroup pid</Literal> calls <Literal>setpgid</Literal> to make
+<Literal>createProcessGroup pid</Literal> calls <Function>setpgid</Function> to make
process <Literal>pid</Literal> a new process group leader.
</Para>
</Para>
<Para>
-<Literal>joinProcessGroup pgid</Literal> calls <Literal>setpgid</Literal> to set the
+<Literal>joinProcessGroup pgid</Literal> calls <Function>setpgid</Function> to set the
<Literal>ProcessGroupID</Literal> of the current process to <Literal>pgid</Literal>.
</Para>
</Para>
<Para>
-<Literal>setProcessGroupID pid pgid</Literal> calls <Literal>setpgid</Literal> to set the
+<Literal>setProcessGroupID pid pgid</Literal> calls <Function>setpgid</Function> to set the
<Literal>ProcessGroupID</Literal> for process <Literal>pid</Literal> to <Literal>pgid</Literal>.
</Para>
</Para>
<Para>
-<Literal>createSession</Literal> calls <Literal>setsid</Literal> to create a new session
+<Function>createSession</Function> calls <Function>setsid</Function> to create a new session
with the current process as session leader.
</Para>
</Para>
<Para>
-<Literal>getSystemID</Literal> calls <Literal>uname</Literal> to obtain information
+<Function>getSystemID</Function> calls <Function>uname</Function> to obtain information
about the current operating system.
</Para>
</Para>
<Para>
-<Literal>epochTime</Literal> calls <Literal>time</Literal> to obtain the number of
+<Function>epochTime</Function> calls <Function>time</Function> to obtain the number of
seconds that have elapsed since the epoch (Jan 01 00:00:00 GMT 1970).
</Para>
</Para>
<Para>
-<Literal>getProcessTimes</Literal> calls <Literal>times</Literal> to obtain time-accounting
+<Function>getProcessTimes</Function> calls <Function>times</Function> to obtain time-accounting
information for the current process and its children.
</Para>
</Para>
<Para>
-<Literal>getControllingTerminalName</Literal> calls <Literal>ctermid</Literal> to obtain
+<Function>getControllingTerminalName</Function> calls <Function>ctermid</Function> to obtain
a name associated with the controlling terminal for the process. If a
controlling terminal exists,
-<Literal>getControllingTerminalName</Literal> returns the name of the
+<Function>getControllingTerminalName</Function> returns the name of the
controlling terminal.
</Para>
</Para>
<Para>
-<Literal>getTerminalName fd</Literal> calls <Literal>ttyname</Literal> to obtain a name associated
+<Literal>getTerminalName fd</Literal> calls <Function>ttyname</Function> to obtain a name associated
with the terminal for <Literal>Fd</Literal> <Literal>fd</Literal>. If <Literal>fd</Literal> is associated
-with a terminal, <Literal>getTerminalName</Literal> returns the name of the
+with a terminal, <Function>getTerminalName</Function> returns the name of the
terminal.
</Para>
</Para>
<Para>
-<Literal>queryTerminal fd</Literal> calls <Literal>isatty</Literal> to determine whether or
+<Literal>queryTerminal fd</Literal> calls <Function>isatty</Function> to determine whether or
not <Literal>Fd</Literal> <Literal>fd</Literal> is associated with a terminal.
</Para>
</Para>
<Para>
-<Literal>getSysVar var</Literal> calls <Literal>sysconf</Literal> to obtain the
+<Literal>getSysVar var</Literal> calls <Function>sysconf</Function> to obtain the
dynamic value of the requested configurable system limit or option.
-For defined system limits, <Literal>getSysVar</Literal> returns the associated
-value. For defined system options, the result of <Literal>getSysVar</Literal>
+For defined system limits, <Function>getSysVar</Function> returns the associated
+value. For defined system options, the result of <Function>getSysVar</Function>
is undefined, but not failure.
</Para>
</Para>
<Para>
-<Literal>openDirStream dir</Literal> calls <Literal>opendir</Literal> to obtain a
+<Literal>openDirStream dir</Literal> calls <Function>opendir</Function> to obtain a
directory stream for <Literal>dir</Literal>.
</Para>
</Para>
<Para>
-<Literal>readDirStream dp</Literal> calls <Literal>readdir</Literal> to obtain the
+<Literal>readDirStream dp</Literal> calls <Function>readdir</Function> to obtain the
next directory entry (<Literal>struct dirent</Literal>) for the open directory
-stream <Literal>dp</Literal>, and returns the <Literal>d_name</Literal> member of that
+stream <Literal>dp</Literal>, and returns the <VarName>d_name</VarName> member of that
structure.
</Para>
</Para>
<Para>
-<Literal>rewindDirStream dp</Literal> calls <Literal>rewinddir</Literal> to reposition
+<Literal>rewindDirStream dp</Literal> calls <Function>rewinddir</Function> to reposition
the directory stream <Literal>dp</Literal> at the beginning of the directory.
</Para>
</Para>
<Para>
-<Literal>closeDirStream dp</Literal> calls <Literal>closedir</Literal> to close
+<Literal>closeDirStream dp</Literal> calls <Function>closedir</Function> to close
the directory stream <Literal>dp</Literal>.
</Para>
</Para>
<Para>
-<Literal>getWorkingDirectory</Literal> calls <Literal>getcwd</Literal> to obtain the name
+<Function>getWorkingDirectory</Function> calls <Function>getcwd</Function> to obtain the name
of the current working directory.
</Para>
</Para>
<Para>
-<Literal>changeWorkingDirectory dir</Literal> calls <Literal>chdir</Literal> to change
+<Literal>changeWorkingDirectory dir</Literal> calls <Function>chdir</Function> to change
the current working directory to <Literal>dir</Literal>.
</Para>
<Para>
<Literal>openFd path acc mode (OpenFileFlags app excl noctty nonblock trunc)</Literal> calls
-<Literal>open</Literal> to obtain a <Literal>Fd</Literal> for the file <Literal>path</Literal> with access
-mode <Literal>acc</Literal>. If <Literal>mode</Literal> is <Literal>Just m</Literal>, the <Literal>O_CREAT</Literal> flag is
+<Function>open</Function> to obtain a <Literal>Fd</Literal> for the file <Literal>path</Literal> with access
+mode <Literal>acc</Literal>. If <Literal>mode</Literal> is <Literal>Just m</Literal>, the <Constant>O_CREAT</Constant> flag is
set and the file's permissions will be based on <Literal>m</Literal> if it does not
-already exist; otherwise, the <Literal>O_CREAT</Literal> flag is not set. The
+already exist; otherwise, the <Constant>O_CREAT</Constant> flag is not set. The
arguments <Literal>app</Literal>, <Literal>excl</Literal>, <Literal>noctty</Literal>, <Literal>nonblock</Literal>, and
-<Literal>trunc</Literal> control whether or not the flags <Literal>O_APPEND</Literal>,
-<Literal>O_EXCL</Literal>, <Literal>O_NOCTTY</Literal>, <Literal>O_NONBLOCK</Literal>, and <Literal>O_TRUNC</Literal> are set,
+<Literal>trunc</Literal> control whether or not the flags <Constant>O_APPEND</Constant>,
+<Constant>O_EXCL</Constant>, <Constant>O_NOCTTY</Constant>, <Constant>O_NONBLOCK</Constant>, and <Constant>O_TRUNC</Constant> are set,
respectively.
</Para>
</Para>
<Para>
-<Literal>createFile path mode</Literal> calls <Literal>creat</Literal> to obtain a <Literal>Fd</Literal>
+<Literal>createFile path mode</Literal> calls <Function>creat</Function> to obtain a <Literal>Fd</Literal>
for file <Literal>path</Literal>, which will be created with permissions based on
<Literal>mode</Literal> if it does not already exist.
</Para>
</Para>
<Para>
-<Literal>setFileCreationMask mode</Literal> calls <Literal>umask</Literal> to set
+<Literal>setFileCreationMask mode</Literal> calls <Function>umask</Function> to set
the process's file creation mask to <Literal>mode</Literal>. The previous file
creation mask is returned.
</Para>
</Para>
<Para>
-<Literal>createLink old new</Literal> calls <Literal>link</Literal> to create a
+<Literal>createLink old new</Literal> calls <Function>link</Function> to create a
new path, <Literal>new</Literal>, linked to an existing file, <Literal>old</Literal>.
<ProgramListing>
</Para>
<Para>
-<Literal>createDirectory dir mode</Literal> calls <Literal>mkdir</Literal> to
+<Literal>createDirectory dir mode</Literal> calls <Function>mkdir</Function> to
create a new directory, <Literal>dir</Literal>, with permissions based on
<Literal>mode</Literal>.
</Para>
</Para>
<Para>
-<Literal>createNamedPipe fifo mode</Literal> calls <Literal>mkfifo</Literal> to
+<Literal>createNamedPipe fifo mode</Literal> calls <Function>mkfifo</Function> to
create a new named pipe, <Literal>fifo</Literal>, with permissions based on
<Literal>mode</Literal>.
</Para>
</Para>
<Para>
-<Literal>removeLink path</Literal> calls <Literal>unlink</Literal> to remove the link
+<Literal>removeLink path</Literal> calls <Function>unlink</Function> to remove the link
named <Literal>path</Literal>.
</Para>
</Para>
<Para>
-<Literal>removeDirectory dir</Literal> calls <Literal>rmdir</Literal> to remove the
+<Literal>removeDirectory dir</Literal> calls <Function>rmdir</Function> to remove the
directory named <Literal>dir</Literal>.
</Para>
</Para>
<Para>
-<Literal>rename old new</Literal> calls <Literal>rename</Literal> to rename a
+<Literal>rename old new</Literal> calls <Function>rename</Function> to rename a
file or directory from <Literal>old</Literal> to <Literal>new</Literal>.
</Para>
</Para>
<Para>
-<Literal>getFileStatus path</Literal> calls <Literal>stat</Literal> to get the
+<Literal>getFileStatus path</Literal> calls <Function>stat</Function> to get the
<Literal>FileStatus</Literal> information for the file <Literal>path</Literal>.
</Para>
</Para>
<Para>
-<Literal>getFdStatus fd</Literal> calls <Literal>fstat</Literal> to get the
+<Literal>getFdStatus fd</Literal> calls <Function>fstat</Function> to get the
<Literal>FileStatus</Literal> information for the file associated with
<Literal>Fd</Literal> <Literal>fd</Literal>.
</Para>
</Para>
<Para>
-<Literal>queryAccess path r w x</Literal> calls <Literal>access</Literal> to test the access
+<Literal>queryAccess path r w x</Literal> calls <Function>access</Function> to test the access
permissions for file <Literal>path</Literal>. The three arguments, <Literal>r</Literal>, <Literal>w</Literal>,
-and <Literal>x</Literal> control whether or not <Literal>access</Literal> is called with
-<Literal>R_OK</Literal>, <Literal>W_OK</Literal>, and <Literal>X_OK</Literal> respectively.
+and <Literal>x</Literal> control whether or not <Function>access</Function> is called with
+<Constant>R_OK</Constant>, <Constant>W_OK</Constant>, and <Constant>X_OK</Constant> respectively.
</Para>
<Para>
</Para>
<Para>
-<Literal>queryFile path</Literal> calls <Literal>access</Literal> with <Literal>F_OK</Literal> to test for the
+<Literal>queryFile path</Literal> calls <Function>access</Function> with <Constant>F_OK</Constant> to test for the
existence for file <Literal>path</Literal>.
</Para>
</Para>
<Para>
-<Literal>setFileMode path mode</Literal> calls <Literal>chmod</Literal> to set the
+<Literal>setFileMode path mode</Literal> calls <Function>chmod</Function> to set the
permission bits associated with file <Literal>path</Literal> to <Literal>mode</Literal>.
</Para>
</Para>
<Para>
-<Literal>setOwnerAndGroup path uid gid</Literal> calls <Literal>chown</Literal> to
+<Literal>setOwnerAndGroup path uid gid</Literal> calls <Function>chown</Function> to
set the <Literal>UserID</Literal> and <Literal>GroupID</Literal> associated with file
<Literal>path</Literal> to <Literal>uid</Literal> and <Literal>gid</Literal>, respectively.
</Para>
</Para>
<Para>
-<Literal>setFileTimes path atime mtime</Literal> calls <Literal>utime</Literal> to
+<Literal>setFileTimes path atime mtime</Literal> calls <Function>utime</Function> to
set the access and modification times associated with file
<Literal>path</Literal> to <Literal>atime</Literal> and <Literal>mtime</Literal>, respectively.
</Para>
</Para>
<Para>
-<Literal>touchFile path</Literal> calls <Literal>utime</Literal> to
+<Literal>touchFile path</Literal> calls <Function>utime</Function> to
set the access and modification times associated with file
<Literal>path</Literal> to the current time.
</Para>
</Para>
<Para>
-<Literal>getPathVar var path</Literal> calls <Literal>pathconf</Literal> to obtain the
+<Literal>getPathVar var path</Literal> calls <Function>pathconf</Function> to obtain the
dynamic value of the requested configurable file limit or option associated
with file or directory <Literal>path</Literal>. For
-defined file limits, <Literal>getPathVar</Literal> returns the associated
-value. For defined file options, the result of <Literal>getPathVar</Literal>
+defined file limits, <Function>getPathVar</Function> returns the associated
+value. For defined file options, the result of <Function>getPathVar</Function>
is undefined, but not failure.
The operation may fail with:
<VariableList>
</Para>
<Para>
-<Literal>getFdVar var fd</Literal> calls <Literal>fpathconf</Literal> to obtain the
+<Literal>getFdVar var fd</Literal> calls <Function>fpathconf</Function> to obtain the
dynamic value of the requested configurable file limit or option associated
with the file or directory attached to the open channel <Literal>fd</Literal>.
-For defined file limits, <Literal>getFdVar</Literal> returns the associated
-value. For defined file options, the result of <Literal>getFdVar</Literal>
+For defined file limits, <Function>getFdVar</Function> returns the associated
+value. For defined file options, the result of <Function>getFdVar</Function>
is undefined, but not failure.
</Para>
</Para>
<Para>
-<Literal>createPipe</Literal> calls <Literal>pipe</Literal> to create a pipe and returns a pair of
+<Function>createPipe</Function> calls <Function>pipe</Function> to create a pipe and returns a pair of
<Literal>Fd</Literal>s, the first for reading and the second for writing.
</Para>
</Para>
<Para>
-<Literal>dup fd</Literal> calls <Literal>dup</Literal> to duplicate <Literal>Fd</Literal> <Literal>fd</Literal> to
+<Literal>dup fd</Literal> calls <Function>dup</Function> to duplicate <Literal>Fd</Literal> <Literal>fd</Literal> to
another <Literal>Fd</Literal>.
</Para>
</Para>
<Para>
-<Literal>dupTo src dst</Literal> calls <Literal>dup2</Literal> to duplicate <Literal>Fd</Literal>
+<Literal>dupTo src dst</Literal> calls <Function>dup2</Function> to duplicate <Literal>Fd</Literal>
<Literal>src</Literal> to <Literal>Fd</Literal> <Literal>dst</Literal>.
</Para>
</Para>
<Para>
-<Literal>fdClose fd</Literal> calls <Literal>close</Literal> to close <Literal>Fd</Literal> <Literal>fd</Literal>.
+<Literal>fdClose fd</Literal> calls <Function>close</Function> to close <Literal>Fd</Literal> <Literal>fd</Literal>.
</Para>
<Para>
</Para>
<Para>
-<Literal>fdRead fd nbytes</Literal> calls <Literal>read</Literal> to read at most <Literal>nbytes</Literal>
+<Literal>fdRead fd nbytes</Literal> calls <Function>read</Function> to read at most <Literal>nbytes</Literal>
bytes from <Literal>Fd</Literal> <Literal>fd</Literal>, and returns the result as a string
paired with the number of bytes actually read.
</Para>
</Para>
<Para>
-<Literal>fdWrite fd s</Literal> calls <Literal>write</Literal> to write
+<Literal>fdWrite fd s</Literal> calls <Function>write</Function> to write
the string <Literal>s</Literal> to <Literal>Fd</Literal> <Literal>fd</Literal> as a
contiguous sequence of bytes. It returns the number of bytes successfully
written.
</Para>
<Para>
-<Literal>getFdOption opt fd</Literal> calls <Literal>fcntl</Literal> to determine whether or
+<Literal>getFdOption opt fd</Literal> calls <Function>fcntl</Function> to determine whether or
not the flag associated with <Literal>FdOption</Literal> <Literal>opt</Literal> is set for
<Literal>Fd</Literal> <Literal>fd</Literal>.
</Para>
</Para>
<Para>
-<Literal>setFdOption fd opt val</Literal> calls <Literal>fcntl</Literal> to set the flag
+<Literal>setFdOption fd opt val</Literal> calls <Function>fcntl</Function> to set the flag
associated with <Literal>FdOption</Literal> <Literal>opt</Literal> on <Literal>Fd</Literal> <Literal>fd</Literal> to
<Literal>val</Literal>.
</Para>
</Para>
<Para>
-<Literal>getLock fd lock</Literal> calls <Literal>fcntl</Literal> to get the first <Literal>FileLock</Literal>
+<Literal>getLock fd lock</Literal> calls <Function>fcntl</Function> to get the first <Literal>FileLock</Literal>
for <Literal>Fd</Literal> <Literal>fd</Literal> which blocks the <Literal>FileLock</Literal> <Literal>lock</Literal>. If
-no such <Literal>FileLock</Literal> exists, <Literal>getLock</Literal> returns <Literal>Nothing</Literal>.
+no such <Literal>FileLock</Literal> exists, <Function>getLock</Function> returns <Literal>Nothing</Literal>.
Otherwise, it returns <Literal>Just (pid, block)</Literal>, where <Literal>block</Literal> is the
blocking <Literal>FileLock</Literal> and <Literal>pid</Literal> is the <Literal>ProcessID</Literal> of the
process holding the blocking <Literal>FileLock</Literal>.
</Para>
<Para>
-<Literal>setLock fd lock</Literal> calls <Literal>fcntl</Literal> with <Literal>F_SETLK</Literal> to set or
+<Literal>setLock fd lock</Literal> calls <Function>fcntl</Function> with <Constant>F_SETLK</Constant> to set or
clear a lock segment for <Literal>Fd</Literal> <Literal>fd</Literal> as indicated by the
-<Literal>FileLock</Literal> <Literal>lock</Literal>. <Literal>setLock</Literal> does not block, but fails with
+<Literal>FileLock</Literal> <Literal>lock</Literal>. <Function>setLock</Function> does not block, but fails with
<Literal>SystemError</Literal> if the request cannot be satisfied immediately.
</Para>
</Para>
<Para>
-<Literal>waitToSetLock fd lock</Literal> calls <Literal>fcntl</Literal> with <Literal>F_SETLKW</Literal> to set
+<Literal>waitToSetLock fd lock</Literal> calls <Function>fcntl</Function> with <Constant>F_SETLKW</Constant> to set
or clear a lock segment for <Literal>Fd</Literal> <Literal>fd</Literal> as indicated by the
<Literal>FileLock</Literal> <Literal>lock</Literal>. If the request cannot be satisfied
-immediately, <Literal>waitToSetLock</Literal> blocks until the request can be
+immediately, <Function>waitToSetLock</Function> blocks until the request can be
satisfied.
</Para>
</Para>
<Para>
-<Literal>fdSeek fd whence offset</Literal> calls <Literal>lseek</Literal> to position the
+<Literal>fdSeek fd whence offset</Literal> calls <Function>lseek</Function> to position the
<Literal>Fd</Literal> <Literal>fd</Literal> at the given <Literal>offset</Literal> from the starting location
indicated by <Literal>whence</Literal>. It returns the resulting offset from the
start of the file in bytes.
</Para>
<Para>
-<Literal>getTerminalAttributes fd</Literal> calls <Literal>tcgetattr</Literal> to obtain
+<Literal>getTerminalAttributes fd</Literal> calls <Function>tcgetattr</Function> to obtain
the <Literal>TerminalAttributes</Literal> associated with <Literal>Fd</Literal> <Literal>fd</Literal>.
</Para>
</Para>
<Para>
-<Literal>setTerminalAttributes fd attr ts</Literal> calls <Literal>tcsetattr</Literal> to change
+<Literal>setTerminalAttributes fd attr ts</Literal> calls <Function>tcsetattr</Function> to change
the <Literal>TerminalAttributes</Literal> associated with <Literal>Fd</Literal> <Literal>fd</Literal> to
<Literal>attr</Literal>, when the terminal is in the state indicated by <Literal>ts</Literal>.
</Para>
</Para>
<Para>
-<Literal>sendBreak fd duration</Literal> calls <Literal>tcsendbreak</Literal> to transmit a
+<Literal>sendBreak fd duration</Literal> calls <Function>tcsendbreak</Function> to transmit a
continuous stream of zero-valued bits on <Literal>Fd</Literal> <Literal>fd</Literal> for the
specified implementation-dependent <Literal>duration</Literal>.
</Para>
</Para>
<Para>
-<Literal>drainOutput fd</Literal> calls <Literal>tcdrain</Literal> to block until all output
+<Literal>drainOutput fd</Literal> calls <Function>tcdrain</Function> to block until all output
written to <Literal>Fd</Literal> <Literal>fd</Literal> has been transmitted.
</Para>
</Para>
<Para>
-<Literal>discardData fd queues</Literal> calls <Literal>tcflush</Literal> to discard
+<Literal>discardData fd queues</Literal> calls <Function>tcflush</Function> to discard
pending input and/or output for <Literal>Fd</Literal> <Literal>fd</Literal>,
as indicated by the <Literal>QueueSelector</Literal> <Literal>queues</Literal>.
</Para>
</Para>
<Para>
-<Literal>controlFlow fd action</Literal> calls <Literal>tcflow</Literal> to control the
+<Literal>controlFlow fd action</Literal> calls <Function>tcflow</Function> to control the
flow of data on <Literal>Fd</Literal> <Literal>fd</Literal>, as indicated by
<Literal>action</Literal>.
</Para>
</Para>
<Para>
-<Literal>getTerminalProcessGroupID fd</Literal> calls <Literal>tcgetpgrp</Literal> to
+<Literal>getTerminalProcessGroupID fd</Literal> calls <Function>tcgetpgrp</Function> to
obtain the <Literal>ProcessGroupID</Literal> of the foreground process group
associated with the terminal attached to <Literal>Fd</Literal> <Literal>fd</Literal>.
</Para>
</Para>
<Para>
-<Literal>setTerminalProcessGroupID fd pgid</Literal> calls <Literal>tcsetpgrp</Literal> to
+<Literal>setTerminalProcessGroupID fd pgid</Literal> calls <Function>tcsetpgrp</Function> to
set the <Literal>ProcessGroupID</Literal> of the foreground process group
associated with the terminal attached to <Literal>Fd</Literal>
<Literal>fd</Literal> to <Literal>pgid</Literal>.
</Para>
<Para>
-<Literal>getGroupEntryForID gid</Literal> calls <Literal>getgrgid</Literal> to obtain
+<Literal>getGroupEntryForID gid</Literal> calls <Function>getgrgid</Function> to obtain
the <Literal>GroupEntry</Literal> information associated with <Literal>GroupID</Literal>
<Literal>gid</Literal>.
</Para>
</Para>
<Para>
-<Literal>getGroupEntryForName name</Literal> calls <Literal>getgrnam</Literal> to obtain
+<Literal>getGroupEntryForName name</Literal> calls <Function>getgrnam</Function> to obtain
the <Literal>GroupEntry</Literal> information associated with the group called
<Literal>name</Literal>.
</Para>
</Para>
<Para>
-<Literal>getUserEntryForID gid</Literal> calls <Literal>getpwuid</Literal> to obtain
+<Literal>getUserEntryForID gid</Literal> calls <Function>getpwuid</Function> to obtain
the <Literal>UserEntry</Literal> information associated with <Literal>UserID</Literal>
<Literal>uid</Literal>.
The operation may fail with:
</Para>
<Para>
-<Literal>getUserEntryForName name</Literal> calls <Literal>getpwnam</Literal> to obtain
+<Literal>getUserEntryForName name</Literal> calls <Function>getpwnam</Function> to obtain
the <Literal>UserEntry</Literal> information associated with the user login
<Literal>name</Literal>.
</Para>
</Para>
<Para>
-<Literal>getErrorCode</Literal> returns the current value of the external
-variable <Literal>errno</Literal>. It never fails.
+<Function>getErrorCode</Function> returns the current value of the external
+variable <Function>errno</Function>. It never fails.
</Para>
<Para>
<Para>
<Literal>setErrorCode err</Literal> sets the external
-variable <Literal>errno</Literal> to <Literal>err</Literal>. It never fails.
+variable <Function>errno</Function> to <Literal>err</Literal>. It never fails.
</Para>
<Para>
<Para>
<IndexTerm><Primary>profiling, with cost-centres</Primary></IndexTerm>
<IndexTerm><Primary>cost-centre profiling</Primary></IndexTerm>
-</Para>
-
-<Para>
Glasgow Haskell comes with a time and space profiling system. Its
purpose is to help you improve your understanding of your program's
execution behaviour, so you can improve it.
</Para>
<Para>
-The costs of the evaluating the expressions bound to <Literal>output1</Literal>,
-<Literal>output2</Literal> and <Literal>output3</Literal> will be attributed to the ``cost
-centres'' <Literal>Pass1</Literal>, <Literal>Pass2</Literal> and <Literal>Pass3</Literal>, respectively.
+The costs of the evaluating the expressions bound to <VarName>output1</VarName>,
+<VarName>output2</VarName> and <VarName>output3</VarName> will be attributed to the ``cost
+centres'' <VarName>Pass1</VarName>, <VarName>Pass2</VarName> and <VarName>Pass3</VarName>, respectively.
</Para>
<Para>
The costs of evaluating other expressions, e.g., <Literal>concat output4</Literal>,
-will be inherited by the scope which referenced the function <Literal>f</Literal>.
+will be inherited by the scope which referenced the function <Function>f</Function>.
</Para>
<Para>
-You can put in cost-centres via <Literal>_scc_</Literal> constructs by hand, as in the
+You can put in cost-centres via <Function>_scc_</Function> constructs by hand, as in the
example above. Perfectly cool. That's probably what you
<Emphasis>would</Emphasis> do if your program divided into obvious ``passes'' or
``phases'', or whatever.
<Para>
If your program is large or you have no clue what might be gobbling
-all the time, you can get GHC to mark all functions with <Literal>_scc_</Literal>
-constructs, automagically. Add an <Literal>-auto</Literal> compilation flag to the
-usual <Literal>-prof</Literal> option.
+all the time, you can get GHC to mark all functions with <Function>_scc_</Function>
+constructs, automagically. Add an <Option>-auto</Option> compilation flag to the
+usual <Option>-prof</Option> option.
</Para>
<Para>
<Para>
To make use of the cost centre profiling system <Emphasis>all</Emphasis> modules must
-be compiled and linked with the <Literal>-prof</Literal> option.<IndexTerm><Primary>-prof option</Primary></IndexTerm>
-Any <Literal>_scc_</Literal> constructs you've put in your source will spring to life.
+be compiled and linked with the <Option>-prof</Option> option.<IndexTerm><Primary>-prof option</Primary></IndexTerm>
+Any <Function>_scc_</Function> constructs you've put in your source will spring to life.
</Para>
<Para>
-Without a <Literal>-prof</Literal> option, your <Literal>_scc_</Literal>s are ignored; so you can
-compiled <Literal>_scc_</Literal>-laden code without changing it.
+Without a <Option>-prof</Option> option, your <Function>_scc_</Function>s are ignored; so you can
+compiled <Function>_scc_</Function>-laden code without changing it.
</Para>
<Para>
There are a few other profiling-related compilation options. Use them
-<Emphasis>in addition to</Emphasis> <Literal>-prof</Literal>. These do not have to be used
+<Emphasis>in addition to</Emphasis> <Option>-prof</Option>. These do not have to be used
consistently for all modules in a program.
</Para>
<VariableList>
<VarListEntry>
-<Term><Literal>-auto</Literal>:</Term>
+<Term><Option>-auto</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-auto option</Primary></IndexTerm>
<IndexTerm><Primary>cost centres, automatically inserting</Primary></IndexTerm>
-GHC will automatically add <Literal>_scc_</Literal> constructs for
+GHC will automatically add <Function>_scc_</Function> constructs for
all top-level, exported functions.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-auto-all</Literal>:</Term>
+<Term><Option>-auto-all</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-auto-all option</Primary></IndexTerm>
<Emphasis>All</Emphasis> top-level functions, exported or not, will be automatically
-<Literal>_scc_</Literal>'d.
+<Function>_scc_</Function>'d.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-caf-all</Literal>:</Term>
+<Term><Option>-caf-all</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-caf-all option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-ignore-scc</Literal>:</Term>
+<Term><Option>-ignore-scc</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-ignore-scc option</Primary></IndexTerm>
-Ignore any <Literal>_scc_</Literal> constructs,
-so a module which already has <Literal>_scc_</Literal>s can be
+Ignore any <Function>_scc_</Function> constructs,
+so a module which already has <Function>_scc_</Function>s can be
compiled for profiling with the annotations ignored.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-G<group></Literal>:</Term>
+<Term><Option>-G<group></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-G<group> option</Primary></IndexTerm>
</Para>
<Para>
-In addition to the <Literal>-prof</Literal> option your system might be setup to enable
-you to compile and link with the <Literal>-prof-details</Literal> <IndexTerm><Primary>-prof-details
+In addition to the <Option>-prof</Option> option your system might be setup to enable
+you to compile and link with the <Option>-prof-details</Option> <IndexTerm><Primary>-prof-details
option</Primary></IndexTerm> option instead. This enables additional detailed counts
-to be reported with the <Literal>-P</Literal> RTS option.
+to be reported with the <Option>-P</Option> RTS option.
</Para>
</Sect1>
</Para>
<Para>
-It isn't enough to compile your program for profiling with <Literal>-prof</Literal>!
+It isn't enough to compile your program for profiling with <Option>-prof</Option>!
</Para>
<Para>
</Para>
<Para>
-Executive summary: <Literal>./a.out +RTS -pT</Literal> produces a time profile in
-<Literal>a.out.prof</Literal>; <Literal>./a.out +RTS -hC</Literal> produces space-profiling
-info which can be mangled by <Literal>hp2ps</Literal> and viewed with <Literal>ghostview</Literal>
+Executive summary: <Command>./a.out +RTS -pT</Command> produces a time profile in
+<Filename>a.out.prof</Filename>; <Command>./a.out +RTS -hC</Command> produces space-profiling
+info which can be mangled by <Command>hp2ps</Command> and viewed with <Command>ghostview</Command>
(or equivalent).
</Para>
<Para>
Profiling runtime flags are passed to your program between the usual
-<Literal>+RTS</Literal> and <Literal>-RTS</Literal> options.
+<Option>+RTS</Option> and <Option>-RTS</Option> options.
</Para>
<Para>
<VariableList>
<VarListEntry>
-<Term><Literal>-p<sort></Literal> or <Literal>-P<sort></Literal>:</Term>
+<Term><Option>-p<sort></Option> or <Option>-P<sort></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-p<sort> RTS option (profiling)</Primary></IndexTerm>
<IndexTerm><Primary>-P<sort> RTS option (profiling)</Primary></IndexTerm>
<IndexTerm><Primary>time profile</Primary></IndexTerm>
<IndexTerm><Primary>serial time profile</Primary></IndexTerm>
-The <Literal>-p?</Literal> option produces a standard <Emphasis>time profile</Emphasis> report.
-It is written into the file <Literal><program>@.prof</Literal>.
+The <Option>-p?</Option> option produces a standard <Emphasis>time profile</Emphasis> report.
+It is written into the file <Filename><program>@.prof</Filename>.
</Para>
<Para>
-The <Literal>-P?</Literal> option produces a more detailed report containing the
+The <Option>-P?</Option> option produces a more detailed report containing the
actual time and allocation data as well. (Not used much.)
</Para>
<VariableList>
<VarListEntry>
-<Term><Literal>T</Literal>:</Term>
+<Term><Option>T</Option>:</Term>
<ListItem>
<Para>
by time, largest first (the default);
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>A</Literal>:</Term>
+<Term><Option>A</Option>:</Term>
<ListItem>
<Para>
by bytes allocated, largest first;
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>C</Literal>:</Term>
+<Term><Option>C</Option>:</Term>
<ListItem>
<Para>
alphabetically by group, module and cost centre.
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-i<secs></Literal>:</Term>
+<Term><Option>-i<secs></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-i<secs> RTS option
(profiling)</Primary></IndexTerm> Set the profiling (sampling) interval to <Literal><secs></Literal>
seconds (the default is 1 second). Fractions are allowed: for example
-<Literal>-i0.2</Literal> will get 5 samples per second.
+<Option>-i0.2</Option> will get 5 samples per second.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-h<break-down></Literal>:</Term>
+<Term><Option>-h<break-down></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-h<break-down> RTS option (profiling)</Primary></IndexTerm>
<Para>
Produce a detailed <Emphasis>space profile</Emphasis> of the heap occupied by live
-closures. The profile is written to the file <Literal><program>@.hp</Literal> from
-which a PostScript graph can be produced using <Literal>hp2ps</Literal> (see
+closures. The profile is written to the file <Filename><program>@.hp</Filename> from
+which a PostScript graph can be produced using <Command>hp2ps</Command> (see
<XRef LinkEnd="hp2ps">).
</Para>
<VariableList>
<VarListEntry>
-<Term><Literal>-hC</Literal>:</Term>
+<Term><Option>-hC</Option>:</Term>
<ListItem>
<Para>
cost centre which produced the closure (the default).
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-hM</Literal>:</Term>
+<Term><Option>-hM</Option>:</Term>
<ListItem>
<Para>
cost centre module which produced the closure.
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-hG</Literal>:</Term>
+<Term><Option>-hG</Option>:</Term>
<ListItem>
<Para>
cost centre group which produced the closure.
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-hD</Literal>:</Term>
+<Term><Option>-hD</Option>:</Term>
<ListItem>
<Para>
closure description—a string describing the closure.
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-hY</Literal>:</Term>
+<Term><Option>-hY</Option>:</Term>
<ListItem>
<Para>
closure type—a string describing the closure's type.
<Para>
Heap (space) profiling uses hash tables. If these tables
should fill the run will abort. The
-<Literal>-z<tbl><size></Literal><IndexTerm><Primary>-z<tbl><size> RTS option (profiling)</Primary></IndexTerm> option is used to
+<Option>-z<tbl><size></Option><IndexTerm><Primary>-z<tbl><size> RTS option (profiling)</Primary></IndexTerm> option is used to
increase the size of the relevant hash table (<Literal>C</Literal>, <Literal>M</Literal>,
<Literal>G</Literal>, <Literal>D</Literal> or <Literal>Y</Literal>, defined as for <Literal><break-down></Literal> above). The
actual size used is the next largest power of 2.
<VariableList>
<VarListEntry>
-<Term><Literal>-c{<mod>:<lab>,<mod>:<lab>...</Literal>}:</Term>
+<Term><Option>-c{<mod>:<lab>,<mod>:<lab>...</Option>}:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-c{<lab></Primary></IndexTerm> RTS option (profiling)}
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-m{<mod>,<mod>...</Literal>}:</Term>
+<Term><Option>-m{<mod>,<mod>...</Option>}:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-m{<mod></Primary></IndexTerm> RTS option (profiling)}
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-g{<grp>,<grp>...</Literal>}:</Term>
+<Term><Option>-g{<grp>,<grp>...</Option>}:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-g{<grp></Primary></IndexTerm> RTS option (profiling)}
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-d{<des>,<des>...</Literal>}:</Term>
+<Term><Option>-d{<des>,<des>...</Option>}:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-d{<des></Primary></IndexTerm> RTS option (profiling)}
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-y{<typ>,<typ>...</Literal>}:</Term>
+<Term><Option>-y{<typ>,<typ>...</Option>}:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-y{<typ></Primary></IndexTerm> RTS option (profiling)}
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-k{<knd>,<knd>...</Literal>}:</Term>
+<Term><Option>-k{<knd>,<knd>...</Option>}:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-k{<knd></Primary></IndexTerm> RTS option (profiling)}
</Para>
<Para>
-When you run your profiled program with the <Literal>-p</Literal> RTS option <IndexTerm><Primary>-p
+When you run your profiled program with the <Option>-p</Option> RTS option <IndexTerm><Primary>-p
RTS option</Primary></IndexTerm>, you get the following information about your ``cost
centres'':
</Para>
<ListItem>
<Para>
How many times this cost-centre was entered; think
-of it as ``I got to the <Literal>_scc_</Literal> construct this many times…''
+of it as ``I got to the <Function>_scc_</Function> construct this many times…''
</Para>
</ListItem>
</VarListEntry>
</Para>
<Para>
-In addition you can use the <Literal>-P</Literal> RTS option <IndexTerm><Primary></Primary></IndexTerm> to get the following additional information:
+In addition you can use the <Option>-P</Option> RTS option <IndexTerm><Primary></Primary></IndexTerm> to get the following additional information:
<VariableList>
<VarListEntry>
</Para>
<Para>
-Finally if you built your program with <Literal>-prof-details</Literal>
-<IndexTerm><Primary></Primary></IndexTerm> the <Literal>-P</Literal> RTS option will also
+Finally if you built your program with <Option>-prof-details</Option>
+<IndexTerm><Primary></Primary></IndexTerm> the <Option>-P</Option> RTS option will also
produce the following information:
<VariableList>
</Para>
<Sect2 id="hp2ps">
-<Title><Literal>hp2ps</Literal>--heap profile to PostScript
+<Title><Command>hp2ps</Command>--heap profile to PostScript
</Title>
<Para>
</Para>
<Para>
-The program <Literal>hp2ps</Literal><IndexTerm><Primary>hp2ps program</Primary></IndexTerm> converts a heap profile
-as produced by the <Literal>-h<break-down></Literal><IndexTerm><Primary>-h<break-down> RTS
+The program <Command>hp2ps</Command><IndexTerm><Primary>hp2ps program</Primary></IndexTerm> converts a heap profile
+as produced by the <Option>-h<break-down></Option><IndexTerm><Primary>-h<break-down> RTS
option</Primary></IndexTerm> runtime option into a PostScript graph of the heap
-profile. By convention, the file to be processed by <Literal>hp2ps</Literal> has a
-<Literal>.hp</Literal> extension. The PostScript output is written to <Literal><file>@.ps</Literal>. If
-<Literal><file></Literal> is omitted entirely, then the program behaves as a filter.
+profile. By convention, the file to be processed by <Command>hp2ps</Command> has a
+<Filename>.hp</Filename> extension. The PostScript output is written to <Filename><file>@.ps</Filename>. If
+<Filename><file></Filename> is omitted entirely, then the program behaves as a filter.
</Para>
<Para>
-<Literal>hp2ps</Literal> is distributed in <Literal>ghc/utils/hp2ps</Literal> in a GHC source
+<Command>hp2ps</Command> is distributed in <Filename>ghc/utils/hp2ps</Filename> in a GHC source
distribution. It was originally developed by Dave Wakeling as part of
the HBC/LML heap profiler.
</Para>
<VariableList>
<VarListEntry>
-<Term><Literal>-d</Literal></Term>
+<Term><Option>-d</Option></Term>
<ListItem>
<Para>
-In order to make graphs more readable, <Literal>hp2ps</Literal> sorts the shaded
+In order to make graphs more readable, <Command>hp2ps</Command> sorts the shaded
bands for each identifier. The default sort ordering is for the bands
with the largest area to be stacked on top of the smaller ones. The
-<Literal>-d</Literal> option causes rougher bands (those representing series of
+<Option>-d</Option> option causes rougher bands (those representing series of
values with the largest standard deviations) to be stacked on top of
smoother ones.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-b</Literal></Term>
+<Term><Option>-b</Option></Term>
<ListItem>
<Para>
-Normally, <Literal>hp2ps</Literal> puts the title of the graph in a small box at the
+Normally, <Command>hp2ps</Command> puts the title of the graph in a small box at the
top of the page. However, if the JOB string is too long to fit in a
small box (more than 35 characters), then
-<Literal>hp2ps</Literal> will choose to use a big box instead. The <Literal>-b</Literal>
-option forces <Literal>hp2ps</Literal> to use a big box.
+<Command>hp2ps</Command> will choose to use a big box instead. The <Option>-b</Option>
+option forces <Command>hp2ps</Command> to use a big box.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-e<float>[in|mm|pt]</Literal></Term>
+<Term><Option>-e<float>[in|mm|pt]</Option></Term>
<ListItem>
<Para>
Generate encapsulated PostScript suitable for inclusion in LaTeX
documents. Usually, the PostScript graph is drawn in landscape mode
-in an area 9 inches wide by 6 inches high, and <Literal>hp2ps</Literal> arranges
+in an area 9 inches wide by 6 inches high, and <Command>hp2ps</Command> arranges
for this area to be approximately centred on a sheet of a4 paper.
This format is convenient of studying the graph in detail, but it is
-unsuitable for inclusion in LaTeX documents. The <Literal>-e</Literal> option
+unsuitable for inclusion in LaTeX documents. The <Option>-e</Option> option
causes the graph to be drawn in portrait mode, with float specifying
the width in inches, millimetres or points (the default). The
resulting PostScript file conforms to the Encapsulated PostScript
(EPS) convention, and it can be included in a LaTeX document using
-Rokicki's dvi-to-PostScript converter <Literal>dvips</Literal>.
+Rokicki's dvi-to-PostScript converter <Command>dvips</Command>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-g</Literal></Term>
+<Term><Option>-g</Option></Term>
<ListItem>
<Para>
-Create output suitable for the <Literal>gs</Literal> PostScript previewer (or
+Create output suitable for the <Command>gs</Command> PostScript previewer (or
similar). In this case the graph is printed in portrait mode without
scaling. The output is unsuitable for a laser printer.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-l</Literal></Term>
+<Term><Option>-l</Option></Term>
<ListItem>
<Para>
Normally a profile is limited to 20 bands with additional identifiers
-being grouped into an <Literal>OTHER</Literal> band. The <Literal>-l</Literal> flag removes this
+being grouped into an <Literal>OTHER</Literal> band. The <Option>-l</Option> flag removes this
20 band and limit, producing as many bands as necessary. No key is
produced as it won't fit!. It is useful for creation time profiles
with many bands.
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-m<int></Literal></Term>
+<Term><Option>-m<int></Option></Term>
<ListItem>
<Para>
Normally a profile is limited to 20 bands with additional identifiers
-being grouped into an <Literal>OTHER</Literal> band. The <Literal>-m</Literal> flag specifies an
+being grouped into an <Literal>OTHER</Literal> band. The <Option>-m</Option> flag specifies an
alternative band limit (the maximum is 20).
</Para>
<Para>
-<Literal>-m0</Literal> requests the band limit to be removed. As many bands as
+<Option>-m0</Option> requests the band limit to be removed. As many bands as
necessary are produced. However no key is produced as it won't fit! It
is useful for displaying creation time profiles with many bands.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-p</Literal></Term>
+<Term><Option>-p</Option></Term>
<ListItem>
<Para>
Use previous parameters. By default, the PostScript graph is
automatically scaled both horizontally and vertically so that it fills
the page. However, when preparing a series of graphs for use in a
presentation, it is often useful to draw a new graph using the same
-scale, shading and ordering as a previous one. The <Literal>-p</Literal> flag causes
+scale, shading and ordering as a previous one. The <Option>-p</Option> flag causes
the graph to be drawn using the parameters determined by a previous
-run of <Literal>hp2ps</Literal> on <Literal>file</Literal>. These are extracted from
-<Literal>file@.aux</Literal>.
+run of <Command>hp2ps</Command> on <Filename>file</Filename>. These are extracted from
+<Filename>file@.aux</Filename>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-s</Literal></Term>
+<Term><Option>-s</Option></Term>
<ListItem>
<Para>
Use a small box for the title.
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-t<float></Literal></Term>
+<Term><Option>-t<float></Option></Term>
<ListItem>
<Para>
Normally trace elements which sum to a total of less than 1% of the
-profile are removed from the profile. The <Literal>-t</Literal> option allows this
+profile are removed from the profile. The <Option>-t</Option> option allows this
percentage to be modified (maximum 5%).
</Para>
<Para>
-<Literal>-t0</Literal> requests no trace elements to be removed from the profile,
+<Option>-t0</Option> requests no trace elements to be removed from the profile,
ensuring that all the data will be displayed.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-?</Literal></Term>
+<Term><Option>-?</Option></Term>
<ListItem>
<Para>
Print out usage information.
</Sect2>
<Sect2 id="stat2resid">
-<Title><Literal>stat2resid</Literal>—residency info from GC stats
+<Title><Command>stat2resid</Command>—residency info from GC stats
</Title>
<Para>
</Para>
<Para>
-The program <Literal>stat2resid</Literal><IndexTerm><Primary>stat2resid</Primary></IndexTerm> converts a detailed
+The program <Command>stat2resid</Command><IndexTerm><Primary>stat2resid</Primary></IndexTerm> converts a detailed
garbage collection statistics file produced by the
-<Literal>-S</Literal><IndexTerm><Primary>-S RTS option</Primary></IndexTerm> runtime option into a PostScript heap
+<Option>-S</Option><IndexTerm><Primary>-S RTS option</Primary></IndexTerm> runtime option into a PostScript heap
residency graph. The garbage collection statistics file can be
produced without compiling your program for profiling.
</Para>
<Para>
-By convention, the file to be processed by <Literal>stat2resid</Literal> has a
-<Literal>.stat</Literal> extension. If the <Literal><outfile></Literal> is not specified the
-PostScript will be written to <Literal><file>@.resid.ps</Literal>. If
-<Literal><file></Literal> is omitted entirely, then the program behaves as a filter.
+By convention, the file to be processed by <Command>stat2resid</Command> has a
+<Filename>.stat</Filename> extension. If the <Filename><outfile></Filename> is not specified the
+PostScript will be written to <Filename><file>@.resid.ps</Filename>. If
+<Filename><file></Filename> is omitted entirely, then the program behaves as a filter.
</Para>
<Para>
The plot can not be produced from the statistics file for a
generational collector, though a suitable stats file can be produced
-using the <Literal>-F2s</Literal><IndexTerm><Primary>-F2s RTS option</Primary></IndexTerm> runtime option when the
+using the <Option>-F2s</Option><IndexTerm><Primary>-F2s RTS option</Primary></IndexTerm> runtime option when the
program has been compiled for generational garbage collection (the
default).
</Para>
<Para>
-<Literal>stat2resid</Literal> is distributed in <Literal>ghc/utils/stat2resid</Literal> in a GHC source
+<Command>stat2resid</Command> is distributed in <Filename>ghc/utils/stat2resid</Filename> in a GHC source
distribution.
</Para>
<Para>
To get your compiled program to spit out the ticky-ticky numbers, use
-a <Literal>-r</Literal> RTS option<IndexTerm><Primary>-r RTS option</Primary></IndexTerm>. See <XRef LinkEnd="runtime-control">.
+a <Option>-r</Option> RTS option<IndexTerm><Primary>-r RTS option</Primary></IndexTerm>. See <XRef LinkEnd="runtime-control">.
</Para>
<Para>
-Compiling your program with the <Literal>-ticky</Literal> switch yields an executable
+Compiling your program with the <Option>-ticky</Option> switch yields an executable
that performs these counts. Here is a sample ticky-ticky statistics
-file, generated by the invocation <Literal>foo +RTS -rfoo.ticky</Literal>.
+file, generated by the invocation <Command>foo +RTS -rfoo.ticky</Command>.
</Para>
<Para>
<Para>
When your Haskell program starts up, its RTS extracts command-line
-arguments bracketed between <Literal>+RTS</Literal><IndexTerm><Primary>+RTS option</Primary></IndexTerm> and
-<Literal>-RTS</Literal><IndexTerm><Primary>-RTS option</Primary></IndexTerm> as its own. For example:
+arguments bracketed between <Option>+RTS</Option><IndexTerm><Primary>+RTS option</Primary></IndexTerm> and
+<Option>-RTS</Option><IndexTerm><Primary>-RTS option</Primary></IndexTerm> as its own. For example:
</Para>
<Para>
</Para>
<Para>
-The RTS will snaffle <Literal>-p -S</Literal> for itself, and the remaining arguments
-<Literal>-f -h foo bar</Literal> will be handed to your program if/when it calls
-<Literal>System.getArgs</Literal>.
+The RTS will snaffle <Option>-p -S</Option> for itself, and the remaining arguments
+<Option>-f -h foo bar</Option> will be handed to your program if/when it calls
+<Function>System.getArgs</Function>.
</Para>
<Para>
-No <Literal>-RTS</Literal> option is required if the runtime-system options extend to
+No <Option>-RTS</Option> option is required if the runtime-system options extend to
the end of the command line, as in this example:
</Para>
<Para>
If you absolutely positively want all the rest of the options in a
command line to go to the program (and not the RTS), use a
-<Literal>--RTS</Literal><IndexTerm><Primary>--RTS option</Primary></IndexTerm>.
+<Option>--RTS</Option><IndexTerm><Primary>--RTS option</Primary></IndexTerm>.
</Para>
<Para>
</Para>
<Para>
-Giving a <Literal>+RTS -f</Literal><IndexTerm><Primary>-f RTS option</Primary></IndexTerm> option will print out the
+Giving a <Option>+RTS -f</Option><IndexTerm><Primary>-f RTS option</Primary></IndexTerm> option will print out the
RTS options actually available in your program (which vary, depending
on how you compiled).
</Para>
<Para>
NOTE: to send RTS options to the compiler itself, you need to prefix
-the option with <Literal>-optCrts</Literal>, eg. to increase the maximum heap size for
-a compilation to 128M, you would add <Literal>-optCrts-M128m</Literal> to the command
+the option with <Option>-optCrts</Option>, eg. to increase the maximum heap size for
+a compilation to 128M, you would add <Option>-optCrts-M128m</Option> to the command
line. The compiler understands some options directly without needing
-<Literal>-optCrts</Literal>: these are <Literal>-H</Literal> and <Literal>-K</Literal>.
+<Option>-optCrts</Option>: these are <Option>-H</Option> and <Option>-K</Option>.
</Para>
<Sect2 id="rts-options-gc">
<VariableList>
<VarListEntry>
-<Term><Literal>-A<size></Literal>:</Term>
+<Term><Option>-A<size></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-A<size> RTS option</Primary></IndexTerm>
<Para>
[Default: 256k] Set the allocation area size used by the garbage
collector. The allocation area (actually generation 0 step 0) is
-fixed and is never resized (unless you use <Literal>-H</Literal>, below).
+fixed and is never resized (unless you use <Option>-H</Option>, below).
</Para>
<Para>
</Para>
<Para>
-With only 1 generation (<Literal>-G1</Literal>) the <Literal>-A</Literal> option specifies the
+With only 1 generation (<Option>-G1</Option>) the <Option>-A</Option> option specifies the
minimum allocation area, since the actual size of the allocation area
will be resized according to the amount of data in the heap (see
-<Literal>-F</Literal>, below).
+<Option>-F</Option>, below).
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-F<factor></Literal>:</Term>
+<Term><Option>-F<factor></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-F<factor> RTS option</Primary></IndexTerm>
<Para>
The default seems to work well here. If you have plenty of memory, it
-is usually better to use <Literal>-H<size></Literal> than to increase
-<Literal>-F<factor></Literal>.
+is usually better to use <Option>-H<size></Option> than to increase
+<Option>-F<factor></Option>.
</Para>
<Para>
-The <Literal>-F</Literal> setting will be automatically reduced by the garbage
-collector when the maximum heap size (the <Literal>-M<size></Literal> setting)
+The <Option>-F</Option> setting will be automatically reduced by the garbage
+collector when the maximum heap size (the <Option>-M<size></Option> setting)
is approaching.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-G<generations></Literal>:</Term>
+<Term><Option>-G<generations></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-G<generations> RTS option</Primary></IndexTerm>
</Para>
<Para>
-Specifying 1 generation with <Literal>+RTS -G1</Literal> gives you a simple 2-space
-collector, as you would expect. In a 2-space collector, the <Literal>-A</Literal>
+Specifying 1 generation with <Option>+RTS -G1</Option> gives you a simple 2-space
+collector, as you would expect. In a 2-space collector, the <Option>-A</Option>
option (see above) specifies the <Emphasis>minimum</Emphasis> allocation area size,
since the allocation area will grow with the amount of live data in
the heap. In a multi-generational collector the allocation area is a
-fixed size (unless you use the <Literal>-H</Literal> option, see below).
+fixed size (unless you use the <Option>-H</Option> option, see below).
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-H<size></Literal>:</Term>
+<Term><Option>-H<size></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-H<size> RTS option</Primary></IndexTerm>
<Para>
By default, the heap will start small, and grow and shrink as
necessary. This can be bad for performance, so if you have plenty of
-memory it's worthwhile supplying a big <Literal>-H<size></Literal>. For
-improving GC performance, using <Literal>-H<size></Literal> is usually a better
-bet than <Literal>-A<size></Literal>.
+memory it's worthwhile supplying a big <Option>-H<size></Option>. For
+improving GC performance, using <Option>-H<size></Option> is usually a better
+bet than <Option>-A<size></Option>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-k<size></Literal>:</Term>
+<Term><Option>-k<size></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-k<size> RTS option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-K<size></Literal>:</Term>
+<Term><Option>-K<size></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-K<size> RTS option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-m<n></Literal>:</Term>
+<Term><Option>-m<n></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-m<n> RTS option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-M<size></Literal>:</Term>
+<Term><Option>-M<size></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-M<size> RTS option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-s<file></Literal> or <Literal>-S<file></Literal>:</Term>
+<Term><Option>-s<file></Option> or <Option>-S<file></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-S<file> RTS option</Primary></IndexTerm>
<IndexTerm><Primary>-s<file> RTS option</Primary></IndexTerm>
-Write modest (<Literal>-s</Literal>) or verbose (<Literal>-S</Literal>) garbage-collector
-statistics into file <Literal><file></Literal>. The default <Literal><file></Literal> is
-<Literal><program>@.stat</Literal>. The <Literal><file></Literal> <Literal>stderr</Literal> is treated
-specially, with the output really being sent to <Literal>stderr</Literal>.
+Write modest (<Option>-s</Option>) or verbose (<Option>-S</Option>) garbage-collector
+statistics into file <Filename><file></Filename>. The default <Filename><file></Filename> is
+<Filename><program>@.stat</Filename>. The <Filename><file></Filename> <Constant>stderr</Constant> is treated
+specially, with the output really being sent to <Constant>stderr</Constant>.
</Para>
<Para>
<VariableList>
<VarListEntry>
-<Term><Literal>-B</Literal>:</Term>
+<Term><Option>-B</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-B RTS option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-r<file></Literal>:</Term>
+<Term><Option>-r<file></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-r <file> RTS option</Primary></IndexTerm>
<IndexTerm><Primary>ticky ticky profiling</Primary></IndexTerm>
Produce ``ticky-ticky'' statistics at the end of the program run.
-The <Literal><file></Literal> business works just like on the <Literal>-S</Literal> RTS option (above).
+The <Filename><file></Filename> business works just like on the <Option>-S</Option> RTS option (above).
</Para>
<Para>
``Ticky-ticky'' statistics are counts of various program actions
(updates, enters, etc.) The program must have been compiled using
-<Literal>-ticky</Literal><IndexTerm><Primary>-ticky option</Primary></IndexTerm> (a.k.a. ``ticky-ticky profiling''),
+<Option>-ticky</Option><IndexTerm><Primary>-ticky option</Primary></IndexTerm> (a.k.a. ``ticky-ticky profiling''),
and, for it to be really useful, linked with suitable system
libraries. Not a trivial undertaking: consult the installation guide
on how to set things up for easy ``ticky-ticky'' profiling. For more
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-D<num></Literal>:</Term>
+<Term><Option>-D<num></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-D RTS option</Primary></IndexTerm>
An RTS debugging flag; varying quantities of output depending on which
bits are set in <Literal><num></Literal>. Only works if the RTS was compiled with the
-<Literal>DEBUG</Literal> option.
+<Option>DEBUG</Option> option.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-Z</Literal>:</Term>
+<Term><Option>-Z</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-Z RTS option</Primary></IndexTerm>
</Para>
<Para>
-The function <Literal>defaultsHook</Literal><IndexTerm><Primary>defaultHook</Primary></IndexTerm> lets you change various
+The function <Function>defaultsHook</Function><IndexTerm><Primary>defaultHook</Primary></IndexTerm> lets you change various
RTS options. The commonest use for this is to give your program a
default heap and/or stack size that is greater than the default. For
-example, to set <Literal>-H8m -K1m</Literal>:
+example, to set <Option>-H8m -K1m</Option>:
</Para>
<Para>
<Para>
Don't use powers of two for heap/stack sizes: these are more likely to
interact badly with direct-mapped caches. The full set of flags is
-defined in <Literal>ghc/rts/RtsFlags.h</Literal> the the GHC source tree.
+defined in <Filename>ghc/rts/RtsFlags.h</Filename> the the GHC source tree.
</Para>
<Para>
<VariableList>
<VarListEntry>
-<Term><Literal>void ErrorHdrHook (FILE *)</Literal>:</Term>
+<Term><Function>void ErrorHdrHook (FILE *)</Function>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>ErrorHdrHook</Primary></IndexTerm>
-What's printed out before the message from <Literal>error</Literal>.
+What's printed out before the message from <Function>error</Function>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>void OutOfHeapHook (unsigned long, unsigned long)</Literal>:</Term>
+<Term><Function>void OutOfHeapHook (unsigned long, unsigned long)</Function>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>OutOfHeapHook</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>void StackOverflowHook (long int)</Literal>:</Term>
+<Term><Function>void StackOverflowHook (long int)</Function>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>StackOverflowHook</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>void MallocFailHook (long int)</Literal>:</Term>
+<Term><Function>void MallocFailHook (long int)</Function>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>MallocFailHook</Primary></IndexTerm>
-The message printed if <Literal>malloc</Literal> fails.
+The message printed if <Function>malloc</Function> fails.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>void PatErrorHdrHook (FILE *)</Literal>:</Term>
+<Term><Function>void PatErrorHdrHook (FILE *)</Function>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>PatErrorHdrHook</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>void PreTraceHook (FILE *)</Literal>:</Term>
+<Term><Function>void PreTraceHook (FILE *)</Function>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>PreTraceHook</Primary></IndexTerm>
-What's printed out before a <Literal>trace</Literal> message.
+What's printed out before a <Function>trace</Function> message.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>void PostTraceHook (FILE *)</Literal>:</Term>
+<Term><Function>void PostTraceHook (FILE *)</Function>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>PostTraceHook</Primary></IndexTerm>
-What's printed out after a <Literal>trace</Literal> message.
+What's printed out after a <Function>trace</Function> message.
</Para>
</ListItem>
</VarListEntry>
<VariableList>
<VarListEntry>
-<Term>Don't use <Literal>-O</Literal> or (especially) <Literal>-O2</Literal>:</Term>
+<Term>Don't use <Option>-O</Option> or (especially) <Option>-O2</Option>:</Term>
<ListItem>
<Para>
By using them, you are telling GHC that you are willing to suffer
</Para>
<Para>
-GHC is surprisingly zippy for normal compilations without <Literal>-O</Literal>!
+GHC is surprisingly zippy for normal compilations without <Option>-O</Option>!
</Para>
</ListItem>
</VarListEntry>
<Para>
Within reason, more memory for heap space means less garbage
collection for GHC, which means less compilation time. If you use
-the <Literal>-Rgc-stats</Literal> option, you'll get a garbage-collector report.
-(Again, you can use the cheap-and-nasty <Literal>-optCrts-Sstderr</Literal> option to
+the <Option>-Rgc-stats</Option> option, you'll get a garbage-collector report.
+(Again, you can use the cheap-and-nasty <Option>-optCrts-Sstderr</Option> option to
send the GC stats straight to standard error.)
</Para>
<Para>
If the heap size is approaching the maximum (64M by default), and you
have lots of memory, try increasing the maximum with the
-<Literal>-M<size></Literal><IndexTerm><Primary>-M<size> option</Primary></IndexTerm> option, e.g.: <Literal>ghc -c -O
--M1024m Foo.hs</Literal>.
+<Option>-M<size></Option><IndexTerm><Primary>-M<size> option</Primary></IndexTerm> option, e.g.: <Command>ghc -c -O
+-M1024m Foo.hs</Command>.
</Para>
<Para>
Increasing the default allocation area size used by the compiler's RTS
-might also help: use the <Literal>-A<size></Literal><IndexTerm><Primary>-A<size> option</Primary></IndexTerm>
+might also help: use the <Option>-A<size></Option><IndexTerm><Primary>-A<size> option</Primary></IndexTerm>
option.
</Para>
machine) start using more than the <Emphasis>real memory</Emphasis> on your
machine, and the machine starts ``thrashing,'' <Emphasis>the party is
over</Emphasis>. Compile times will be worse than terrible! Use something
-like the csh-builtin <Literal>time</Literal> command to get a report on how many page
+like the csh-builtin <Command>time</Command> command to get a report on how many page
faults you're getting.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term>Don't derive/use <Literal>Read</Literal> unnecessarily:</Term>
+<Term>Don't derive/use <Function>Read</Function> unnecessarily:</Term>
<ListItem>
<Para>
It's ugly and slow.
The parts of the compiler that seem most prone to wandering off for a
long time are the abstract interpreters (strictness and update
analysers). You can turn these off individually with
-<Literal>-fno-strictness</Literal><IndexTerm><Primary>-fno-strictness anti-option</Primary></IndexTerm> and
-<Literal>-fno-update-analysis</Literal>.<IndexTerm><Primary>-fno-update-analysis anti-option</Primary></IndexTerm>
+<Option>-fno-strictness</Option><IndexTerm><Primary>-fno-strictness anti-option</Primary></IndexTerm> and
+<Option>-fno-update-analysis</Option>.<IndexTerm><Primary>-fno-update-analysis anti-option</Primary></IndexTerm>
</Para>
<Para>
To figure out which part of the compiler is badly behaved, the
-<Literal>-dshow-passes</Literal><IndexTerm><Primary>-dshow-passes option</Primary></IndexTerm> option is your
+<Option>-dshow-passes</Option><IndexTerm><Primary>-dshow-passes option</Primary></IndexTerm> option is your
friend.
</Para>
<Para>
If your module has big wads of constant data, GHC may produce a huge
basic block that will cause the native-code generator's register
-allocator to founder. Bring on <Literal>-fvia-C</Literal><IndexTerm><Primary>-fvia-C option</Primary></IndexTerm>
+allocator to founder. Bring on <Option>-fvia-C</Option><IndexTerm><Primary>-fvia-C option</Primary></IndexTerm>
(not that GCC will be that quick about it, either).
</Para>
</ListItem>
<Term>Avoid the consistency-check on linking:</Term>
<ListItem>
<Para>
-Use <Literal>-no-link-chk</Literal><IndexTerm><Primary>-no-link-chk</Primary></IndexTerm>; saves effort. This is
+Use <Option>-no-link-chk</Option><IndexTerm><Primary>-no-link-chk</Primary></IndexTerm>; saves effort. This is
probably safe in a I-only-compile-things-one-way setup.
</Para>
</ListItem>
<VariableList>
<VarListEntry>
-<Term>Optimise, using <Literal>-O</Literal> or <Literal>-O2</Literal>:</Term>
+<Term>Optimise, using <Option>-O</Option> or <Option>-O2</Option>:</Term>
<ListItem>
<Para>
This is the most basic way
to make your program go faster. Compilation time will be slower,
-especially with <Literal>-O2</Literal>.
+especially with <Option>-O2</Option>.
</Para>
<Para>
-At present, <Literal>-O2</Literal> is nearly indistinguishable from <Literal>-O</Literal>.
+At present, <Option>-O2</Option> is nearly indistinguishable from <Option>-O</Option>.
</Para>
</ListItem>
</VarListEntry>
<Term>Compile via C and crank up GCC:</Term>
<ListItem>
<Para>
-Even with <Literal>-O</Literal>, GHC tries to
+Even with <Option>-O</Option>, GHC tries to
use a native-code generator, if available. But the native
code-generator is designed to be quick, not mind-bogglingly clever.
Better to let GCC have a go, as it tries much harder on register
</Para>
<Para>
-So, when we want very fast code, we use: <Literal>-O -fvia-C -O2-for-C</Literal>.
+So, when we want very fast code, we use: <Option>-O -fvia-C -O2-for-C</Option>.
</Para>
</ListItem>
</VarListEntry>
<Para>
Signatures are the basic trick; putting them on exported, top-level
functions is good software-engineering practice, anyway. (Tip: using
-<Literal>-fwarn-missing-signatures</Literal><IndexTerm><Primary>-fwarn-missing-signatures
+<Option>-fwarn-missing-signatures</Option><IndexTerm><Primary>-fwarn-missing-signatures
option</Primary></IndexTerm> can help enforce good signature-practice).
</Para>
<Para>
-The automatic specialisation of overloaded functions (with <Literal>-O</Literal>)
+The automatic specialisation of overloaded functions (with <Option>-O</Option>)
should take care of overloaded local and/or unexported functions.
</Para>
</ListItem>
<Para>
Look for your function in the interface file, then for the third field
in the pragma; it should say <Literal>_S_ <string></Literal>. The <Literal><string></Literal>
-gives the strictness of the function's arguments. <Literal>L</Literal> is lazy
-(bad), <Literal>S</Literal> and <Literal>E</Literal> are strict (good), <Literal>P</Literal> is ``primitive'' (good),
-<Literal>U(...)</Literal> is strict and
-``unpackable'' (very good), and <Literal>A</Literal> is absent (very good).
+gives the strictness of the function's arguments. <Function>L</Function> is lazy
+(bad), <Function>S</Function> and <Function>E</Function> are strict (good), <Function>P</Function> is ``primitive'' (good),
+<Function>U(...)</Function> is strict and
+``unpackable'' (very good), and <Function>A</Function> is absent (very good).
</Para>
<Para>
-For an ``unpackable'' <Literal>U(...)</Literal> argument, the info inside
+For an ``unpackable'' <Function>U(...)</Function> argument, the info inside
tells the strictness of its components. So, if the argument is a
-pair, and it says <Literal>U(AU(LSS))</Literal>, that means ``the first component of the
+pair, and it says <Function>U(AU(LSS))</Function>, that means ``the first component of the
pair isn't used; the second component is itself unpackable, with three
components (lazy in the first, strict in the second \& third).''
</Para>
<Para>
-If the function isn't exported, just compile with the extra flag <Literal>-ddump-simpl</Literal>;
+If the function isn't exported, just compile with the extra flag <Option>-ddump-simpl</Option>;
next to the signature for any binder, it will print the self-same
pragmatic information as would be put in an interface file.
(Besides, Core syntax is fun to look at!)
<ListItem>
<Para>
(The form in which GHC manipulates your code.) Just run your
-compilation with <Literal>-ddump-simpl</Literal> (don't forget the <Literal>-O</Literal>).
+compilation with <Option>-ddump-simpl</Option> (don't forget the <Option>-O</Option>).
</Para>
<Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term>Use <Literal>_ccall_s</Literal> (a GHC extension) to plug into fast libraries:</Term>
+<Term>Use <Function>_ccall_s</Function> (a GHC extension) to plug into fast libraries:</Term>
<ListItem>
<Para>
This may take real work, but… There exist piles of
<Term>Use a bigger heap!</Term>
<ListItem>
<Para>
-If your program's GC stats (<Literal>-S</Literal><IndexTerm><Primary>-S RTS option</Primary></IndexTerm> RTS option)
+If your program's GC stats (<Option>-S</Option><IndexTerm><Primary>-S RTS option</Primary></IndexTerm> RTS option)
indicate that it's doing lots of garbage-collection (say, more than
20% of execution time), more memory might help—with the
-<Literal>-M<size></Literal><IndexTerm><Primary>-M<size> RTS option</Primary></IndexTerm> or
-<Literal>-A<size></Literal><IndexTerm><Primary>-A<size> RTS option</Primary></IndexTerm> RTS options (see
+<Option>-M<size></Option><IndexTerm><Primary>-M<size> RTS option</Primary></IndexTerm> or
+<Option>-A<size></Option><IndexTerm><Primary>-A<size> RTS option</Primary></IndexTerm> RTS options (see
<XRef LinkEnd="rts-options-gc">).
</Para>
</ListItem>
<Para>
Decrease the ``go-for-it'' threshold for unfolding smallish
expressions. Give a
-<Literal>-funfolding-use-threshold0</Literal><IndexTerm><Primary>-funfolding-use-threshold0
+<Option>-funfolding-use-threshold0</Option><IndexTerm><Primary>-funfolding-use-threshold0
option</Primary></IndexTerm> option for the extreme case. (``Only unfoldings with
zero cost should proceed.'') Warning: except in certain specialiised
cases (like Happy parsers) this is likely to actually
</Para>
<Para>
-Avoid <Literal>Read</Literal>.
+Avoid <Function>Read</Function>.
</Para>
<Para>
<Para>
``I think I have a space leak…'' Re-run your program with
-<Literal>+RTS -Sstderr</Literal>,<IndexTerm><Primary>-Sstderr RTS option</Primary></IndexTerm> and remove all doubt!
+<Option>+RTS -Sstderr</Option>,<IndexTerm><Primary>-Sstderr RTS option</Primary></IndexTerm> and remove all doubt!
(You'll see the heap usage get bigger and bigger…) [Hmmm…this
-might be even easier with the <Literal>-F2s</Literal><IndexTerm><Primary>-F2s RTS option</Primary></IndexTerm> RTS
-option; so… <Literal>./a.out +RTS -Sstderr -F2s</Literal>...]
+might be even easier with the <Option>-F2s</Option><IndexTerm><Primary>-F2s RTS option</Primary></IndexTerm> RTS
+option; so… <Command>./a.out +RTS -Sstderr -F2s</Command>...]
</Para>
<Para>
-<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+<!DOCTYPE BOOK PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!ENTITY license SYSTEM "license.sgml">
<!ENTITY intro SYSTEM "intro.sgml" >
<!ENTITY relnotes SYSTEM "4-04-notes.sgml" >
<Para>
<IndexTerm><Primary>GHC, using</Primary></IndexTerm>
<IndexTerm><Primary>using GHC</Primary></IndexTerm>
-</Para>
-
-<Para>
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 <Literal>make</Literal> tool (this is especially useful if the program
+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>
<Para>
Command-line options begin with <Literal>-</Literal>. They may <Emphasis>not</Emphasis> be
-grouped: <Literal>-vO</Literal> is different from <Literal>-v -O</Literal>. Options need not
-precede filenames: e.g., <Literal>ghc *.o -o foo</Literal>. All options are
+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
-<Literal>ghc -c -O1 Foo.hs -O2 Bar.hs</Literal> to apply different optimisation
-levels to the files <Literal>Foo.hs</Literal> and <Literal>Bar.hs</Literal>. For conflicting
-options, e.g., <Literal>-c -S</Literal>, we reserve the right to do anything we
+<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>
</Para>
<Para>
-File names with ``meaningful'' suffixes (e.g., <Literal>.lhs</Literal> or <Literal>.o</Literal>)
+File names with ``meaningful'' suffixes (e.g., <Filename>.lhs</Filename> or <Filename>.o</Filename>)
cause the ``right thing'' to happen to those files.
</Para>
<VariableList>
<VarListEntry>
-<Term><Literal>.lhs</Literal>:</Term>
+<Term><Filename>.lhs</Filename>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>lhs suffix</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>.hs</Literal>:</Term>
+<Term><Filename>.hs</Filename>:</Term>
<ListItem>
<Para>
A not-so-literate Haskell module.
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>.hi</Literal>:</Term>
+<Term><Filename>.hi</Filename>:</Term>
<ListItem>
<Para>
A Haskell interface file, probably compiler-generated.
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>.hc</Literal>:</Term>
+<Term><Filename>.hc</Filename>:</Term>
<ListItem>
<Para>
Intermediate C file produced by the Haskell compiler.
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>.c</Literal>:</Term>
+<Term><Filename>.c</Filename>:</Term>
<ListItem>
<Para>
A C file not produced by the Haskell compiler.
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>.s</Literal>:</Term>
+<Term><Filename>.s</Filename>:</Term>
<ListItem>
<Para>
An assembly-language source file, usually
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>.o</Literal>:</Term>
+<Term><Filename>.o</Filename>:</Term>
<ListItem>
<Para>
An object file, produced by an assembler.
</Para>
<Para>
-A good option to start with is the <Literal>-help</Literal> (or <Literal>-?</Literal>) option.
+A good option to start with is the <Option>-help</Option> (or <Option>-?</Option>) option.
<IndexTerm><Primary>-help option</Primary></IndexTerm>
<IndexTerm><Primary>-? option</Primary></IndexTerm>
GHC spews a long message to standard output and then exits.
</Para>
<Para>
-The <Literal>-v</Literal><IndexTerm><Primary>-v option</Primary></IndexTerm> option makes GHC <Emphasis>verbose</Emphasis>: it
+The <Option>-v</Option><IndexTerm><Primary>-v option</Primary></IndexTerm> option makes GHC <Emphasis>verbose</Emphasis>: it
reports its version number and shows (on stderr) exactly how it invokes each
phase of the compilation system. Moreover, it passes
-the <Literal>-v</Literal> flag to most phases; each reports
+the <Option>-v</Option> flag to most phases; each reports
its version number (and possibly some other information).
</Para>
<Para>
-Please, oh please, use the <Literal>-v</Literal> option when reporting bugs!
+Please, oh please, use the <Option>-v</Option> option when reporting bugs!
Knowing that you ran the right bits in the right order is always the
first thing we want to verify.
</Para>
<Para>
If you're just interested in the compiler version number, the
-<Literal>--version</Literal><IndexTerm><Primary>--version option</Primary></IndexTerm> option prints out a
+<Option>--version</Option><IndexTerm><Primary>--version option</Primary></IndexTerm> option prints out a
one-line string containing the requested info.
</Para>
<Para>
<IndexTerm><Primary>order of passes in GHC</Primary></IndexTerm>
<IndexTerm><Primary>pass ordering in GHC</Primary></IndexTerm>
-The basic task of the <Literal>ghc</Literal> driver is to run each input file
+The basic task of the <Command>ghc</Command> driver is to run each input file
through the right phases (compiling, linking, etc.).
</Para>
</Para>
<Para>
-Thus, a common invocation would be: <Literal>ghc -c Foo.hs</Literal>
+Thus, a common invocation would be: <Command>ghc -c Foo.hs</Command>
</Para>
<Para>
</Para>
<Para>
-The option <Literal>-cpp</Literal><IndexTerm><Primary>-cpp option</Primary></IndexTerm> must be given for the C
+The option <Option>-cpp</Option><IndexTerm><Primary>-cpp option</Primary></IndexTerm> must be given for the C
pre-processor phase to be run, that is, the pre-processor will be run
over your Haskell source file before continuing.
</Para>
<Para>
-The option <Literal>-E</Literal><IndexTerm><Primary>-E option</Primary></IndexTerm> runs just the pre-processing
+The option <Option>-E</Option><IndexTerm><Primary>-E option</Primary></IndexTerm> runs just the pre-processing
passes of the compiler, outputting the result on stdout before
stopping. 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 <Literal>-cpp</Literal>, the
+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 option <Literal>-optcpp-E</Literal><IndexTerm><Primary>-optcpp-E option</Primary></IndexTerm> runs just the
+The option <Option>-optcpp-E</Option><IndexTerm><Primary>-optcpp-E option</Primary></IndexTerm> runs just the
pre-processing stage of the C-compiling phase, sending the result to
stdout. (For debugging or obfuscation contests, usually.)
</Para>
</Para>
<Para>
-GHC's compiled output normally goes into a <Literal>.hc</Literal>, <Literal>.o</Literal>, etc., file,
-depending on the last-run compilation phase. The option <Literal>-o
-foo</Literal><IndexTerm><Primary>-o option</Primary></IndexTerm> re-directs the output of that last-run
-phase to file <Literal>foo</Literal>.
+GHC's compiled output normally goes into a <Filename>.hc</Filename>, <Filename>.o</Filename>, etc., file,
+depending on the last-run compilation phase. The option <Option>-o
+foo</Option><IndexTerm><Primary>-o option</Primary></IndexTerm> re-directs the output of that last-run
+phase to file <Filename>foo</Filename>.
</Para>
<Para>
Note: this ``feature'' can be counterintuitive:
-<Literal>ghc -C -o foo.o foo.hs</Literal> will put the intermediate C code in the
-file <Literal>foo.o</Literal>, name notwithstanding!
+<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>
<Para>
-EXOTICA: But the <Literal>-o</Literal> option isn't of much use if you have
+EXOTICA: But the <Option>-o</Option> option isn't of much use if you have
<Emphasis>several</Emphasis> input files… Non-interface output files are
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 <Literal>-odir <dir></Literal><IndexTerm><Primary>-odir <dir> option</Primary></IndexTerm> (the
+using the <Option>-odir <dir></Option><IndexTerm><Primary>-odir <dir> option</Primary></IndexTerm> (the
``Oh, dear'' option). For example:
</Para>
</Para>
<Para>
-The output files, <Literal>Foo.o</Literal>, <Literal>Bar.o</Literal>, and <Literal>Bumble.o</Literal> would be
+The output files, <Filename>Foo.o</Filename>, <Filename>Bar.o</Filename>, and <Filename>Bumble.o</Filename> would be
put into a subdirectory named after the architecture of the executing
-machine (<Literal>sun4</Literal>, <Literal>mips</Literal>, etc). The directory must already
+machine (<Filename>sun4</Filename>, <Filename>mips</Filename>, etc). The directory must already
exist; it won't be created.
</Para>
<Para>
-Note that the <Literal>-odir</Literal> option does <Emphasis>not</Emphasis> affect where the
+Note that the <Option>-odir</Option> option does <Emphasis>not</Emphasis> affect where the
interface files are put. In the above example, they would still be
-put in <Literal>parse/Foo.hi</Literal>, <Literal>parse/Bar.hi</Literal>, and <Literal>gurgle/Bumble.hi</Literal>.
+put in <Filename>parse/Foo.hi</Filename>, <Filename>parse/Bar.hi</Filename>, and <Filename>gurgle/Bumble.hi</Filename>.
</Para>
<Para>
-MORE EXOTICA: The <Literal>-osuf <suffix></Literal><IndexTerm><Primary>-osuf <suffix>
-option</Primary></IndexTerm> will change the <Literal>.o</Literal> file suffix for object files to
+MORE EXOTICA: The <Option>-osuf <suffix></Option><IndexTerm><Primary>-osuf <suffix>
+option</Primary></IndexTerm> will change the <Filename>.o</Filename> file suffix for object files to
whatever you specify. (We use this in compiling the prelude.).
-Similarly, the <Literal>-hisuf <suffix></Literal><IndexTerm><Primary>-hisuf <suffix>
-option</Primary></IndexTerm> will change the <Literal>.hi</Literal> file suffix for non-system
+Similarly, the <Option>-hisuf <suffix></Option><IndexTerm><Primary>-hisuf <suffix>
+option</Primary></IndexTerm> will change the <Filename>.hi</Filename> file suffix for non-system
interface files (see <XRef LinkEnd="hi-options">).
</Para>
<Para>
-The <Literal>-hisuf</Literal>/<Literal>-osuf</Literal> game is useful if you want to compile a program
+The <Option>-hisuf</Option>/<Option>-osuf</Option> game is useful if you want to compile a program
with both GHC and HBC (say) in the same directory. Let HBC use the
-standard <Literal>.hi</Literal>/<Literal>.o</Literal> suffixes; add <Literal>-hisuf g_hi -osuf g_o</Literal> to your
-<Literal>make</Literal> rule for GHC compiling…
+standard <Filename>.hi</Filename>/<Filename>.o</Filename> suffixes; add <Option>-hisuf g_hi -osuf g_o</Option> to your
+<Command>make</Command> rule for GHC compiling…
</Para>
<Para>
-FURTHER EXOTICA: If you are doing a normal <Literal>.hs</Literal>-to-<Literal>.o</Literal> compilation
-but would like to hang onto the intermediate <Literal>.hc</Literal> C file, just
-throw in a <Literal>-keep-hc-file-too</Literal> option<IndexTerm><Primary>-keep-hc-file-too option</Primary></IndexTerm>.
+FURTHER EXOTICA: If you are doing a normal <Filename>.hs</Filename>-to-<Filename>.o</Filename> compilation
+but would like to hang onto the intermediate <Filename>.hc</Filename> C file, just
+throw in a <Option>-keep-hc-file-too</Option> option<IndexTerm><Primary>-keep-hc-file-too option</Primary></IndexTerm>.
If you would like to look at the assembler output, toss in a
-<Literal>-keep-s-file-too</Literal>,<IndexTerm><Primary>-keep-s-file-too option</Primary></IndexTerm> too.
+<Option>-keep-s-file-too</Option>,<IndexTerm><Primary>-keep-s-file-too option</Primary></IndexTerm> too.
</Para>
<Sect2 id="saving-ghc-stderr">
<Para>
Sometimes, you may cause GHC to be rather chatty on standard error;
-with <Literal>-v</Literal>, for example. You can instruct GHC to <Emphasis>append</Emphasis> this
-output to a particular log file with a <Literal>-odump <blah></Literal><IndexTerm><Primary>-odump
+with <Option>-v</Option>, for example. You can instruct GHC to <Emphasis>append</Emphasis> this
+output to a particular log file with a <Option>-odump <blah></Option><IndexTerm><Primary>-odump
<blah> option</Primary></IndexTerm> option.
</Para>
</Para>
<Para>
-If you have trouble because of running out of space in <Literal>/tmp</Literal> (or
+If you have trouble because of running out of space in <Filename>/tmp</Filename> (or
wherever your installation thinks temporary files should go), you may
-use the <Literal>-tmpdir <dir></Literal><IndexTerm><Primary>-tmpdir <dir> option</Primary></IndexTerm> option
-to specify an alternate directory. For example, <Literal>-tmpdir .</Literal> says to
+use the <Option>-tmpdir <dir></Option><IndexTerm><Primary>-tmpdir <dir> option</Primary></IndexTerm> option
+to specify an alternate directory. For example, <Option>-tmpdir .</Option> says to
put temporary files in the current working directory.
</Para>
<Para>
-Alternatively, use your <Literal>TMPDIR</Literal> environment variable.<IndexTerm><Primary>TMPDIR
+Alternatively, use your <Constant>TMPDIR</Constant> environment variable.<IndexTerm><Primary>TMPDIR
environment variable</Primary></IndexTerm> Set it to the name of the directory where
temporary files should be put. GCC and other programs will honour the
-<Literal>TMPDIR</Literal> variable as well.
+<Constant>TMPDIR</Constant> variable as well.
</Para>
<Para>
-Even better idea: Set the <Literal>TMPDIR</Literal> variable when building GHC, and
-never worry about <Literal>TMPDIR</Literal> again. (see the build documentation).
+Even better idea: Set the <Constant>TMPDIR</Constant> variable when building GHC, and
+never worry about <Constant>TMPDIR</Constant> again. (see the build documentation).
</Para>
</Sect2>
messages, otherwise known as warnings, can be generated during
compilation. By default, you get a standard set of warnings which are
generally likely to indicate bugs in your program. These are:
-<Literal>-fwarn-overlpapping-patterns</Literal>, <Literal>-fwarn-duplicate-exports</Literal>, and
-<Literal>-fwarn-missing-methods</Literal>. The following flags are simple ways to
+<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:
</Para>
<VariableList>
<VarListEntry>
-<Term><Literal>-Wnot</Literal>:</Term>
+<Term><Option>-Wnot</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-Wnot option</Primary></IndexTerm>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-w</Literal>:</Term>
+<Term><Option>-w</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-w option</Primary></IndexTerm>
-Synonym for <Literal>-Wnot</Literal>.
+Synonym for <Option>-Wnot</Option>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-W</Literal>:</Term>
+<Term><Option>-W</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-W option</Primary></IndexTerm>
-Provides the standard warnings plus <Literal>-fwarn-incomplete-patterns</Literal>,
-<Literal>-fwarn-unused-imports</Literal> and <Literal>-fwarn-unused-binds</Literal>.
+Provides the standard warnings plus <Option>-fwarn-incomplete-patterns</Option>,
+<Option>-fwarn-unused-imports</Option> and <Option>-fwarn-unused-binds</Option>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-Wall</Literal>:</Term>
+<Term><Option>-Wall</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-Wall option</Primary></IndexTerm>
<Para>
The full set of warning options is described below. To turn off any
-warning, simply give the corresponding <Literal>-fno-warn-...</Literal> option on
+warning, simply give the corresponding <Option>-fno-warn-...</Option> option on
the command line.
</Para>
<VariableList>
<VarListEntry>
-<Term><Literal>-fwarn-name-shadowing</Literal>:</Term>
+<Term><Option>-fwarn-name-shadowing</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-name-shadowing option</Primary></IndexTerm>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-fwarn-overlapping-patterns</Literal>:</Term>
+<Term><Option>-fwarn-overlapping-patterns</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-overlapping-patterns option</Primary></IndexTerm>
</Para>
<Para>
-where the last pattern match in <Literal>f</Literal> won't ever be reached, as the
+where the last pattern match in <Function>f</Function> won't ever be reached, as the
second pattern overlaps it. More often than not, redundant patterns
is a programmer mistake/error, so this option is enabled by default.
</Para>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-fwarn-incomplete-patterns</Literal>:</Term>
+<Term><Option>-fwarn-incomplete-patterns</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-incomplete-patterns option</Primary></IndexTerm>
<IndexTerm><Primary>incomplete patterns, warning</Primary></IndexTerm>
<IndexTerm><Primary>patterns, incomplete</Primary></IndexTerm>
-Similarly for incomplete patterns, the function <Literal>g</Literal> below will fail
+Similarly for incomplete patterns, the function <Function>g</Function> below will fail
when applied to non-empty lists, so the compiler will emit a warning
-about this when <Literal>-fwarn-incomplete-patterns</Literal> is enabled.
+about this when <Option>-fwarn-incomplete-patterns</Option> is enabled.
</Para>
<Para>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-fwarn-missing-methods</Literal>:</Term>
+<Term><Option>-fwarn-missing-methods</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-missing-methods option</Primary></IndexTerm>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-fwarn-missing-fields</Literal>:</Term>
+<Term><Option>-fwarn-missing-fields</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-missing-fields option</Primary></IndexTerm>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-fwarn-unused-imports</Literal>:</Term>
+<Term><Option>-fwarn-unused-imports</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-unused-imports option</Primary></IndexTerm>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-fwarn-unused-binds</Literal>:</Term>
+<Term><Option>-fwarn-unused-binds</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-unused-binds option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-fwarn-unused-matches</Literal>:</Term>
+<Term><Option>-fwarn-unused-matches</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-unused-matches option</Primary></IndexTerm>
<IndexTerm><Primary>matches, unused</Primary></IndexTerm>
Report all unused variables which arise from pattern matches,
including patterns consisting of a single variable. For instance <Literal>f x
-y = []</Literal> would report <Literal>x</Literal> and <Literal>y</Literal> as unused. To eliminate the warning,
+y = []</Literal> would report <VarName>x</VarName> and <VarName>y</VarName> as unused. To eliminate the warning,
all unused variables can be replaced with wildcards.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-fwarn-duplicate-exports</Literal>:</Term>
+<Term><Option>-fwarn-duplicate-exports</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-duplicate-exports option</Primary></IndexTerm>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-fwarn-type-defaults</Literal>:</Term>
+<Term><Option>-fwarn-type-defaults</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-type-defaults option</Primary></IndexTerm>
defaulting mechanism for numeric types kicks in. This is useful
information when converting code from a context that assumed one
default into one with another, e.g., the `default default' for Haskell
-1.4 caused the otherwise unconstrained value <Literal>1</Literal> to be given
+1.4 caused the otherwise unconstrained value <Constant>1</Constant> to be given
the type <Literal>Int</Literal>, whereas Haskell 98 defaults it to
<Literal>Integer</Literal>. This may lead to differences in performance and
behaviour, hence the usefulness of being non-silent about this.
</VarListEntry>
<VarListEntry>
-<Term><Literal>-fwarn-missing-signatures</Literal>:</Term>
+<Term><Option>-fwarn-missing-signatures</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-missing-signatures option</Primary></IndexTerm>
<IndexTerm><Primary>type signatures, missing</Primary></IndexTerm>
If you would like GHC to check that every top-level function/value has
-a type signature, use the <Literal>-fwarn-missing-signatures</Literal> option. This
+a type signature, use the <Option>-fwarn-missing-signatures</Option> option. This
option is off by default.
</Para>
</ListItem>
</Para>
<Para>
-If you're feeling really paranoid, the <Literal>-dcore-lint</Literal>
+If you're feeling really paranoid, the <Option>-dcore-lint</Option>
option<IndexTerm><Primary>-dcore-lint option</Primary></IndexTerm> is a good choice. It turns on
heavyweight intra-pass sanity-checking within GHC. (It checks GHC's
sanity, not yours.)
</Para>
<Para>
-When GHC compiles a source file <Literal>F</Literal> which contains a module <Literal>A</Literal>, say,
-it generates an object <Literal>F.o</Literal>, <Emphasis>and</Emphasis> a companion <Emphasis>interface
-file</Emphasis> <Literal>A.hi</Literal>. The interface file is not intended for human
+When GHC compiles a source file <Filename>F</Filename> which contains a module <Literal>A</Literal>, say,
+it generates an object <Filename>F.o</Filename>, <Emphasis>and</Emphasis> a companion <Emphasis>interface
+file</Emphasis> <Filename>A.hi</Filename>. The interface file is not intended for human
consumption, as you'll see if you take a look at one. It's merely
there to help the compiler compile other modules in the same program.
</Para>
<Para>
NOTE: Having the name of the interface file follow the module name and
-not the file name, means that working with tools such as <Literal>make(1)</Literal>
-become harder. <Literal>make</Literal> implicitly assumes that any output files
+not the file name, means that working with tools such as <Command>make</Command>
+become harder. <Command>make</Command> implicitly assumes that any output files
produced by processing a translation unit will have file names that
can be derived from the file name of the translation unit. For
instance, pattern rules becomes unusable. For this reason, we
<Para>
The interface file for <Literal>A</Literal> contains information needed by the compiler
when it compiles any module <Literal>B</Literal> that imports <Literal>A</Literal>, whether directly or
-indirectly. When compiling <Literal>B</Literal>, GHC will read <Literal>A.hi</Literal> to find the
+indirectly. When compiling <Literal>B</Literal>, GHC will read <Filename>A.hi</Filename> to find the
details that it needs to know about things defined in <Literal>A</Literal>.
</Para>
Furthermore, when compiling module <Literal>C</Literal> which imports <Literal>B</Literal>, GHC may
decide that it needs to know something about <Literal>A</Literal>—for example, <Literal>B</Literal>
might export a function that involves a type defined in <Literal>A</Literal>. In this
-case, GHC will go and read <Literal>A.hi</Literal> even though <Literal>C</Literal> does not explicitly
+case, GHC will go and read <Command>A.hi</Command> even though <Literal>C</Literal> does not explicitly
import <Literal>A</Literal> at all.
</Para>
<Para>
The interface file may contain all sorts of things that aren't
explicitly exported from <Literal>A</Literal> by the programmer. For example, even
-though a data type is exported abstractly, <Literal>A.hi</Literal> will contain the
-full data type definition. For small function definitions, <Literal>A.hi</Literal>
+though a data type is exported abstractly, <Filename>A.hi</Filename> will contain the
+full data type definition. For small function definitions, <Filename>A.hi</Filename>
will contain the complete definition of the function. For bigger
-functions, <Literal>A.hi</Literal> will contain strictness information about the
-function. And so on. GHC puts much more information into <Literal>.hi</Literal> files
-when optimisation is turned on with the <Literal>-O</Literal> flag. Without <Literal>-O</Literal> it
-puts in just the minimum; with <Literal>-O</Literal> it lobs in a whole pile of stuff.
+functions, <Filename>A.hi</Filename> will contain strictness information about the
+function. And so on. GHC puts much more information into <Filename>.hi</Filename> files
+when optimisation is turned on with the <Option>-O</Option> flag. Without <Option>-O</Option> it
+puts in just the minimum; with <Option>-O</Option> it lobs in a whole pile of stuff.
<IndexTerm><Primary>optimsation, effect on .hi files</Primary></IndexTerm>
</Para>
<Para>
-<Literal>A.hi</Literal> should really be thought of as a compiler-readable version of
-<Literal>A.o</Literal>. If you use a <Literal>.hi</Literal> file that wasn't generated by the same
-compilation run that generates the <Literal>.o</Literal> file the compiler may assume
+<Filename>A.hi</Filename> should really be thought of as a compiler-readable version of
+<Filename>A.o</Filename>. If you use a <Filename>.hi</Filename> file that wasn't generated by the same
+compilation run that generates the <Filename>.o</Filename> file the compiler may assume
all sorts of incorrect things about <Literal>A</Literal>, resulting in core dumps and
other unpleasant happenings.
</Para>
<Para>
In your program, you import a module <Literal>Foo</Literal> by saying
-<Literal>import Foo</Literal>. GHC goes looking for an interface file, <Literal>Foo.hi</Literal>.
-It has a builtin list of directories (notably including <Literal>.</Literal>) where
+<Literal>import Foo</Literal>. GHC goes looking for an interface file, <Filename>Foo.hi</Filename>.
+It has a builtin list of directories (notably including <Filename>.</Filename>) where
it looks.
</Para>
<VariableList>
<VarListEntry>
-<Term><Literal>-i<dirs></Literal></Term>
+<Term><Option>-i<dirs></Option></Term>
<ListItem>
<Para>
<IndexTerm><Primary>-i<dirs> option</Primary></IndexTerm>This flag
-prepends a colon-separated list of <Literal>dirs</Literal> to the ``import
+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 <Literal>-i</Literal> list.
+relative and absolute pathnames in the <Option>-i</Option> list.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-i</Literal></Term>
+<Term><Option>-i</Option></Term>
<ListItem>
<Para>
resets the ``import directories'' list back to nothing.
</VarListEntry>
<VarListEntry>
-<Term><Literal>-fno-implicit-prelude</Literal></Term>
+<Term><Option>-fno-implicit-prelude</Option></Term>
<ListItem>
<Para>
<IndexTerm><Primary>-fno-implicit-prelude option</Primary></IndexTerm>
-GHC normally imports <Literal>Prelude.hi</Literal> files for you. If you'd rather it
-didn't, then give it a <Literal>-fno-implicit-prelude</Literal> option. You are
+GHC normally imports <Filename>Prelude.hi</Filename> files for you. If you'd rather it
+didn't, then give it a <Option>-fno-implicit-prelude</Option> option. You are
unlikely to get very far without a Prelude, but, hey, it's a free
country.
</Para>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-syslib <lib></Literal></Term>
+<Term><Option>-syslib <lib></Option></Term>
<ListItem>
<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 <Literal>-syslib posix</Literal> option (for example). 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.
</Para>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-I<dir></Literal></Term>
+<Term><Option>-I<dir></Option></Term>
<ListItem>
<Para>
<IndexTerm><Primary>-I<dir> option</Primary></IndexTerm>
-Once a Haskell module has been compiled to C (<Literal>.hc</Literal> file), you may
-wish to specify where GHC tells the C compiler to look for <Literal>.h</Literal> files.
-(Or, if you are using the <Literal>-cpp</Literal> option<IndexTerm><Primary>-cpp option</Primary></IndexTerm>, where
-it tells the C pre-processor to look…) For this purpose, use a <Literal>-I</Literal>
+Once a Haskell module has been compiled to C (<Filename>.hc</Filename> file), you may
+wish to specify where GHC tells the C compiler to look for <Filename>.h</Filename> files.
+(Or, if you are using the <Option>-cpp</Option> option<IndexTerm><Primary>-cpp option</Primary></IndexTerm>, where
+it tells the C pre-processor to look…) For this purpose, use a <Option>-I</Option>
option in the usual C-ish way.
</Para>
</ListItem>
<Para>
<IndexTerm><Primary>interface files, options</Primary></IndexTerm>
The interface output may be directed to another file
-<Literal>bar2/Wurble.iface</Literal> with the option <Literal>-ohi bar2/Wurble.iface</Literal><IndexTerm><Primary>-ohi
+<Filename>bar2/Wurble.iface</Filename> with the option <Option>-ohi bar2/Wurble.iface</Option><IndexTerm><Primary>-ohi
<file> option</Primary></IndexTerm> (not recommended).
</Para>
<Para>
-To avoid generating an interface file at all, use a <Literal>-nohi</Literal>
+To avoid generating an interface file at all, use a <Option>-nohi</Option>
option.<IndexTerm><Primary>-nohi option</Primary></IndexTerm>
</Para>
<Para>
-The compiler does not overwrite an existing <Literal>.hi</Literal> interface file if
+The compiler does not overwrite an existing <Filename>.hi</Filename> interface file if
the new one is byte-for-byte the same as the old one; this is friendly
-to <Literal>make</Literal>. When an interface does change, it is often enlightening to
-be informed. The <Literal>-hi-diffs</Literal><IndexTerm><Primary>-hi-diffs option</Primary></IndexTerm> option will
-make <Literal>ghc</Literal> run <Literal>diff</Literal> on the old and new <Literal>.hi</Literal> files. You can also
+to <Command>make</Command>. When an interface does change, it is often enlightening to
+be informed. The <Option>-hi-diffs</Option><IndexTerm><Primary>-hi-diffs option</Primary></IndexTerm> option will
+make GHC run <Command>diff</Command> on the old and new <Filename>.hi</Filename> files. You can also
record the difference in the interface file itself, the
-<Literal>-keep-hi-diffs</Literal><IndexTerm><Primary>-keep-hi-diffs</Primary></IndexTerm> option takes care of that.
+<Option>-keep-hi-diffs</Option><IndexTerm><Primary>-keep-hi-diffs</Primary></IndexTerm> option takes care of that.
</Para>
<Para>
-The <Literal>.hi</Literal> 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
-<Literal>-hi-diffs-with-usages</Literal><IndexTerm><Primary>-hi-diffs-with-usages option</Primary></IndexTerm>
+<Option>-hi-diffs-with-usages</Option><IndexTerm><Primary>-hi-diffs-with-usages option</Primary></IndexTerm>
option.
</Para>
<Emphasis>pragmas</Emphasis>, which record arities, strictness info, etc. If you
think these pragmas are messing you up (or you are doing some kind of
weird experiment), you can tell GHC to ignore them with the
-<Literal>-fignore-interface-pragmas</Literal><IndexTerm><Primary>-fignore-interface-pragmas
+<Option>-fignore-interface-pragmas</Option><IndexTerm><Primary>-fignore-interface-pragmas
option</Primary></IndexTerm> option.
</Para>
about not slurping in data constructors and instance declarations that
it will not need. If you believe it is getting it wrong and not
importing stuff which you think it should, this optimisation can be
-turned off with <Literal>-fno-prune-tydecls</Literal> and <Literal>-fno-prune-instdecls</Literal>.
+turned off with <Option>-fno-prune-tydecls</Option> and <Option>-fno-prune-instdecls</Option>.
<IndexTerm><Primary>-fno-prune-tydecls option</Primary></IndexTerm><IndexTerm><Primary>-fno-prune-instdecls
option</Primary></IndexTerm>
</Para>
</Para>
<Para>
-In the olden days, GHC compared the newly-generated <Literal>.hi</Literal> file with
+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 <Literal>.hi</Literal> file were not
+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 <Literal>A.hi</Literal> should force a
+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 <Literal>B.hi</Literal> one jot. So
+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 <Literal>.o</Literal> file's date (i.e. the source hasn't changed since the
+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
<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 <Literal>.hi</Literal> file has an absolute path name is considered a library 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
-<Literal>-i</Literal> path, to force GHC to record detailed dependency information.
+<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 ``<Literal>/</Literal>'', or
-``<Literal>A:/</Literal>'', or ``<Literal>A:\</Literal>'' (or ``<Literal>B:/</Literal>'', ``<Literal>B:\</Literal>'' 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). Ask
-him (email: <ULink
-URL="mailto:sansom@dcs.gla.ac.uk"
->sansom@dcs.gla.ac.uk</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>
<Sect2 id="using-make">
-<Title>Using <Literal>make</Literal>
+<Title>Using <Command>make</Command>
</Title>
<Para>
</Para>
<Para>
-It is reasonably straightforward to set up a <Literal>Makefile</Literal> to use with
+It is reasonably straightforward to set up a <Filename>Makefile</Filename> to use with
GHC, assuming you name your source files the same as your modules.
Thus:
</Para>
</Para>
<Para>
-(Sophisticated <Literal>make</Literal> variants may achieve some of the above more
-elegantly. Notably, <Literal>gmake</Literal>'s pattern rules let you write the more
+(Sophisticated <Command>make</Command> variants may achieve some of the above more
+elegantly. Notably, <Command>gmake</Command>'s pattern rules let you write the more
comprehensible:
</Para>
</Para>
<Para>
-What we've shown should work with any <Literal>make</Literal>.)
+What we've shown should work with any <Command>make</Command>.)
</Para>
<Para>
Note the cheesy <Literal>.o.hi</Literal> rule: It records the dependency of the
-interface (<Literal>.hi</Literal>) file on the source. The rule says a <Literal>.hi</Literal> file can
-be made from a <Literal>.o</Literal> file by doing…nothing. Which is true.
+interface (<Filename>.hi</Filename>) file on the source. The rule says a <Filename>.hi</Filename> file can
+be made from a <Filename>.o</Filename> file by doing…nothing. Which is true.
</Para>
<Para>
</Para>
<Para>
-They tell <Literal>make</Literal> that if any of <Literal>Foo.o</Literal>, <Literal>Foo.hc</Literal> or <Literal>Foo.s</Literal> have an
+They tell <Command>make</Command> that if any of <Literal>Foo.o</Literal>, <Literal>Foo.hc</Literal> or <Literal>Foo.s</Literal> have an
earlier modification date than <Literal>Baz.hi</Literal>, then the out-of-date file
must be brought up to date. To bring it up to date, <Literal>make</Literal> looks for
a rule to do so; one of the preceding suffix rules does the job
<Para>
Putting inter-dependencies of the form <Literal>Foo.o : Bar.hi</Literal> into your
-<Literal>Makefile</Literal> by hand is rather error-prone. Don't worry—never fear,
-<Literal>mkdependHS</Literal> is here! (and is distributed as part of GHC) Add the
-following to your <Literal>Makefile</Literal>:
+<Filename>Makefile</Filename> by hand is rather error-prone. Don't worry—never fear,
+<Command>mkdependHS</Command> is here! (and is distributed as part of GHC) Add the
+following to your <Filename>Makefile</Filename>:
</Para>
<Para>
<Para>
Now, before you start compiling, and any time you change the <Literal>imports</Literal>
-in your program, do <Literal>make depend</Literal> before you do <Literal>make cool_pgm</Literal>.
-<Literal>mkdependHS</Literal> will append the needed dependencies to your <Literal>Makefile</Literal>.
-<Literal>mkdependHS</Literal> is fully described in <XRef LinkEnd="mkdependHS">.
+in your program, do <Command>make depend</Command> before you do <Command>make cool_pgm</Command>.
+<Command>mkdependHS</Command> will append the needed dependencies to your <Filename>Makefile</Filename>.
+<Command>mkdependHS</Command> is fully described in <XRef LinkEnd="mkdependHS">.
</Para>
<Para>
<Para>
You may need to compile some modules explicitly to create their
-interfaces in the first place (e.g., <Literal>make Bar.o</Literal> to create <Literal>Bar.hi</Literal>).
+interfaces in the first place (e.g., <Command>make Bar.o</Command> to create <Filename>Bar.hi</Filename>).
</Para>
</ListItem>
<ListItem>
<Para>
- You may have to type <Literal>make</Literal> more than once for the dependencies
-to have full effect. However, a <Literal>make</Literal> run that does nothing
+ 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.''
</Para>
recursive modules off the ground, you need to hand write an interface
file for A or B, so as to break the loop. These hand-written
interface files are called <Literal>hi-boot</Literal> files, and are placed in a file
-called <Literal><module>.hi-boot</Literal>. To import from an <Literal>hi-boot</Literal> file instead
-of the standard <Literal>.hi</Literal> file, use the following syntax in the importing module:
+called <Filename><module>.hi-boot</Filename>. To import from an <Literal>hi-boot</Literal> file instead
+of the standard <Filename>.hi</Filename> file, use the following syntax in the importing module:
<IndexTerm><Primary>hi-boot files</Primary></IndexTerm>
<IndexTerm><Primary>importing, hi-boot files</Primary></IndexTerm>
</Para>
</Para>
<Para>
-The syntax is essentially the same as a normal <Literal>.hi</Literal> file
-(unfortunately), but you can usually tailor an existing <Literal>.hi</Literal> file to
-make a <Literal>.hi-boot</Literal> file.
+The syntax is essentially the same as a normal <Filename>.hi</Filename> file
+(unfortunately), but you can usually tailor an existing <Filename>.hi</Filename> file to
+make a <Filename>.hi-boot</Filename> file.
</Para>
<Para>
Notice that we only put the declaration for the newtype <Literal>TA</Literal> in the
-<Literal>hi-boot</Literal> file, not the signature for <Literal>f</Literal>, since <Literal>f</Literal> isn't used by
+<Literal>hi-boot</Literal> file, not the signature for <Function>f</Function>, since <Function>f</Function> isn't used by
<Literal>B</Literal>.
</Para>
<Para>
The number ``1'' at the beginning of a declaration is the <Emphasis>version
-number</Emphasis> of that declaration: for the purposes of <Literal>.hi-boot</Literal> files
+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
reference to <Literal>Int</Literal> in the interface for <Literal>A</Literal> comes from <Literal>PrelBase</Literal>,
</Para>
<Para>
-The <Literal>-O*</Literal> options specify convenient ``packages'' of optimisation
-flags; the <Literal>-f*</Literal> options described later on specify
-<Emphasis>individual</Emphasis> optimisations to be turned on/off; the <Literal>-m*</Literal>
+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
on/off.
</Para>
<Sect2 id="optimise-pkgs">
-<Title><Literal>-O*</Literal>: convenient ``packages'' of optimisation flags.
+<Title><Option>-O*</Option>: convenient ``packages'' of optimisation flags.
</Title>
<Para>
</Para>
<Para>
-Once you choose a <Literal>-O*</Literal> ``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
-<Literal>-O*</Literal> option, and you may have to recompile a large chunk of all
+<Option>-O*</Option> option, and you may have to recompile a large chunk of all
importing modules before your program can again be run
safely (see <XRef LinkEnd="recomp">).
</Para>
<VariableList>
<VarListEntry>
-<Term>No <Literal>-O*</Literal>-type option specified:</Term>
+<Term>No <Option>-O*</Option>-type option specified:</Term>
<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: <Literal>ghc -c Foo.hs</Literal>
+about compiled-code quality.'' So, for example: <Command>ghc -c Foo.hs</Command>
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-O</Literal> or <Literal>-O1</Literal>:</Term>
+<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: <Literal>ghc -c -O Main.lhs</Literal>
+Thus, for example: <Command>ghc -c -O Main.lhs</Command>
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-O2</Literal>:</Term>
+<Term><Option>-O2</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-O2 option</Primary></IndexTerm>
</Para>
<Para>
-At the moment, <Literal>-O2</Literal> is <Emphasis>unlikely</Emphasis> to produce
-better code than <Literal>-O</Literal>.
+At the moment, <Option>-O2</Option> is <Emphasis>unlikely</Emphasis> to produce
+better code than <Option>-O</Option>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-O2-for-C</Literal>:</Term>
+<Term><Option>-O2-for-C</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-O2-for-C option</Primary></IndexTerm>
</Para>
<Para>
-Says to run GCC with <Literal>-O2</Literal>, which may be worth a few percent in
-execution speed. Don't forget <Literal>-fvia-C</Literal>, lest you use the native-code
+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
generator and bypass GCC altogether!
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-Onot</Literal>:</Term>
+<Term><Option>-Onot</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-Onot option</Primary></IndexTerm>
</Para>
<Para>
-This option will make GHC ``forget'' any <Literal>-O</Literal>ish options it has seen so
-far. Sometimes useful; for example: <Literal>make all EXTRA_HC_OPTS=-Onot</Literal>.
+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><Literal>-Ofile <file></Literal>:</Term>
+<Term><Option>-Ofile <file></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-Ofile <file> option</Primary></IndexTerm>
<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 <Literal>-Ofile</Literal>.
+of options can be put in a file and then slurped in with <Option>-Ofile</Option>.
</Para>
<Para>
</Para>
<Para>
-Please ask if you are baffled and would like an example of <Literal>-Ofile</Literal>!
+Please ask if you are baffled and would like an example of <Option>-Ofile</Option>!
</Para>
</ListItem>
</VarListEntry>
</Para>
<Para>
-At Glasgow, we don't use a <Literal>-O*</Literal> flag for day-to-day work. We use
-<Literal>-O</Literal> to get respectable speed; e.g., when we want to measure
-something. When we want to go for broke, we tend to use <Literal>-O -fvia-C
--O2-for-C</Literal> (and we go for lots of coffee breaks).
+At Glasgow, we don't use a <Option>-O*</Option> flag for day-to-day work. We use
+<Option>-O</Option> to get respectable speed; e.g., when we want to measure
+something. When we want to go for broke, we tend to use <Option>-O -fvia-C
+-O2-for-C</Option> (and we go for lots of coffee breaks).
</Para>
<Para>
-The easiest way to see what <Literal>-O</Literal> (etc.) ``really mean'' is to run with
-<Literal>-v</Literal>, then stand back in amazement. Alternatively, just look at the
-<Literal>HsC_minus<blah></Literal> lists in the <Literal>ghc</Literal> driver script.
+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>
</Sect2>
<Sect2>
-<Title><Literal>-f*</Literal>: platform-independent flags</Title>
+<Title><Option>-f*</Option>: platform-independent flags</Title>
<Para>
<IndexTerm><Primary>-f* options (GHC)</Primary></IndexTerm>
<Para>
Flags can be turned <Emphasis>off</Emphasis> individually. (NB: I hope you have a
-good reason for doing this…) To turn off the <Literal>-ffoo</Literal> flag, just use
-the <Literal>-fno-foo</Literal> flag.<IndexTerm><Primary>-fno-<opt> anti-option</Primary></IndexTerm> So, for
-example, you can say <Literal>-O2 -fno-strictness</Literal>, which will then drop out
+good reason for doing this…) To turn off the <Option>-ffoo</Option> flag, just use
+the <Option>-fno-foo</Option> flag.<IndexTerm><Primary>-fno-<opt> anti-option</Primary></IndexTerm> So, for
+example, you can say <Option>-O2 -fno-strictness</Option>, which will then drop out
any running of the strictness analyser.
</Para>
<ListItem>
<Para>
-<Literal>-fno-strictness</Literal><IndexTerm><Primary>-fno-strictness option</Primary></IndexTerm> (strictness
+<Option>-fno-strictness</Option><IndexTerm><Primary>-fno-strictness option</Primary></IndexTerm> (strictness
analyser, because it is sometimes slow),
</Para>
</ListItem>
<ListItem>
<Para>
-<Literal>-fno-specialise</Literal><IndexTerm><Primary>-fno-specialise option</Primary></IndexTerm> (automatic
+<Option>-fno-specialise</Option><IndexTerm><Primary>-fno-specialise option</Primary></IndexTerm> (automatic
specialisation of overloaded functions, because it can make your code
bigger) (US spelling also accepted), and
</Para>
<ListItem>
<Para>
-<Literal>-fno-cpr-analyse</Literal><IndexTerm><Primary>-fno-cpr-analyse option</Primary></IndexTerm> switches off the CPR (constructed product
+<Option>-fno-cpr-analyse</Option><IndexTerm><Primary>-fno-cpr-analyse option</Primary></IndexTerm> switches off the CPR (constructed product
result) analyser.
</Para>
</ListItem>
<Para>
Should you wish to turn individual flags <Emphasis>on</Emphasis>, you are advised
-to use the <Literal>-Ofile</Literal> option, described above. Because the order in
+to use the <Option>-Ofile</Option> option, described above. Because the order in
which optimisation passes are run is sometimes crucial, it's quite
hard to do with command-line options.
</Para>
<VariableList>
<VarListEntry>
-<Term><Literal>-fvia-C</Literal>:</Term>
+<Term><Option>-fvia-C</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-fvia-C option</Primary></IndexTerm>
<Para>
Compile via C, and don't use the native-code generator. (There are
many cases when GHC does this on its own.) You might pick up a little
-bit of speed by compiling via C. If you use <Literal>_ccall_gc_</Literal>s or
-<Literal>_casm_</Literal>s, you probably <Emphasis>have</Emphasis> to use <Literal>-fvia-C</Literal>.
+bit of speed by compiling via C. If you use <Function>_ccall_gc_</Function>s or
+<Function>_casm_</Function>s, you probably <Emphasis>have</Emphasis> to use <Option>-fvia-C</Option>.
</Para>
<Para>
-The lower-case incantation, <Literal>-fvia-c</Literal>, is synonymous.
+The lower-case incantation, <Option>-fvia-c</Option>, is synonymous.
</Para>
<Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-funfolding-interface-threshold<n></Literal>:</Term>
+<Term><Option>-funfolding-interface-threshold<n></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-funfolding-interface-threshold option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-funfolding-creation-threshold<n></Literal>:</Term>
+<Term><Option>-funfolding-creation-threshold<n></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-funfolding-creation-threshold option</Primary></IndexTerm>
<IndexTerm><Primary>inlining, controlling</Primary></IndexTerm>
<IndexTerm><Primary>unfolding, controlling</Primary></IndexTerm>
(Default: 30) This option is similar to
-<Literal>-funfolding-interface-threshold</Literal>, except that it governs unfoldings
+<Option>-funfolding-interface-threshold</Option>, except that it governs unfoldings
within a single module. Increasing this figure is more likely to
result in longer compile times than faster code. The next option is
more useful:
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-funfolding-use-threshold<n></Literal>:</Term>
+<Term><Option>-funfolding-use-threshold<n></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-funfolding-use-threshold option</Primary></IndexTerm>
this size, a function definition will be unfolded at the call-site,
any bigger and it won't. The size computed for a function depends on
two things: the actual size of the expression minus any discounts that
-apply (see <Literal>-funfolding-con-discount</Literal>).
+apply (see <Option>-funfolding-con-discount</Option>).
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-funfolding-con-discount<n></Literal>:</Term>
+<Term><Option>-funfolding-con-discount<n></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-funfolding-con-discount option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-funbox-strict-fields</Literal>:</Term>
+<Term><Option>-funbox-strict-fields</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-funbox-strict-fields option</Primary></IndexTerm>
<Para>
will create a constructor <Literal>T</Literal> containing two unboxed floats if the
-<Literal>-funbox-strict-fields</Literal> flag is given. This may not always be an
-optimisation: if the <Literal>T</Literal> constructor is scrutinised and the floats
+<Option>-funbox-strict-fields</Option> flag is given. This may not always be an
+optimisation: if the <Function>T</Function> constructor is scrutinised and the floats
passed to a non-strict function for example, they will have to be
reboxed (this is done automatically by the compiler).
</Para>
<Para>
-This option should only be used in conjunction with <Literal>-O</Literal>, in order to
+This option should only be used in conjunction with <Option>-O</Option>, in order to
expose unfoldings to the compiler so the reboxing can be removed as
often as possible. For example:
</Para>
</Para>
<Para>
-The compiler will avoid reboxing <Literal>f1</Literal> and <Literal>f2</Literal> by inlining <Literal>+</Literal> on
-floats, but only when <Literal>-O</Literal> is on.
+The compiler will avoid reboxing <Function>f1</Function> and <Function>f2</Function> by inlining <Function>+</Function> on
+floats, but only when <Option>-O</Option> is on.
</Para>
<Para>
</Para>
<Para>
-will store the two <Literal>Int</Literal>s directly in the <Literal>T</Literal> constructor, by flattening
+will store the two <Literal>Int</Literal>s directly in the <Function>T</Function> constructor, by flattening
the pair. Multi-level unpacking is also supported:
</Para>
</Para>
<Para>
-will store two unboxed <Literal>Int#</Literal>s directly in the <Literal>T</Literal> constructor.
+will store two unboxed <Literal>Int#</Literal>s directly in the <Function>T</Function> constructor.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-fsemi-tagging</Literal>:</Term>
+<Term><Option>-fsemi-tagging</Option>:</Term>
<ListItem>
<Para>
This option (which <Emphasis>does not work</Emphasis> with the native-code generator)
</Para>
<Para>
-We have not played with <Literal>-fsemi-tagging</Literal> enough to recommend it.
+We have not played with <Option>-fsemi-tagging</Option> enough to recommend it.
(For all we know, it doesn't even work anymore… Sigh.)
</Para>
</ListItem>
</Sect2>
<Sect2>
-<Title><Literal>-m*</Literal>: platform-specific flags</Title>
+<Title><Option>-m*</Option>: platform-specific flags</Title>
<Para>
<IndexTerm><Primary>-m* options (GHC)</Primary></IndexTerm>
<VariableList>
<VarListEntry>
-<Term><Literal>-mv8</Literal>:</Term>
+<Term><Option>-mv8</Option>:</Term>
<ListItem>
<Para>
(SPARC machines)<IndexTerm><Primary>-mv8 option (SPARC only)</Primary></IndexTerm>
Means to pass the like-named option to GCC; it says to use the
Version 8 SPARC instructions, notably integer multiply and divide.
-The similiar <Literal>-m*</Literal> GCC options for SPARC also work, actually.
+The similiar <Option>-m*</Option> GCC options for SPARC also work, actually.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-mlong-calls</Literal>:</Term>
+<Term><Option>-mlong-calls</Option>:</Term>
<ListItem>
<Para>
(HPPA machines)<IndexTerm><Primary>-mlong-calls option (HPPA only)</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-monly-[32]-regs</Literal>:</Term>
+<Term><Option>-monly-[32]-regs</Option>:</Term>
<ListItem>
<Para>
(iX86 machines)<IndexTerm><Primary>-monly-N-regs option (iX86 only)</Primary></IndexTerm>
statements or clauses.
</Screen>
-Just give some registers back with <Literal>-monly-N-regs</Literal>. Try `3' first,
+Just give some registers back with <Option>-monly-N-regs</Option>. Try `3' first,
then `2'. If `2' doesn't work, please report the bug to us.
</Para>
</ListItem>
</Para>
<Para>
-The C compiler (GCC) is run with <Literal>-O</Literal> turned on. (It has
+The C compiler (GCC) is run with <Option>-O</Option> turned on. (It has
to be, actually).
</Para>
<Para>
-If you want to run GCC with <Literal>-O2</Literal>—which may be worth a few
+If you want to run GCC with <Option>-O2</Option>—which may be worth a few
percent in execution speed—you can give a
-<Literal>-O2-for-C</Literal><IndexTerm><Primary>-O2-for-C option</Primary></IndexTerm> option.
+<Option>-O2-for-C</Option><IndexTerm><Primary>-O2-for-C option</Primary></IndexTerm> option.
</Para>
</Sect2>
</Para>
<Para>
-The C pre-processor <Literal>cpp</Literal> is run over your Haskell code only if the
-<Literal>-cpp</Literal> option <IndexTerm><Primary>-cpp option</Primary></IndexTerm> is given. Unless you are
+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.
<VariableList>
<VarListEntry>
-<Term><Literal>-D<foo></Literal>:</Term>
+<Term><Option>-D<foo></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-D<name> option</Primary></IndexTerm>
-Define macro <Literal><foo></Literal> in the usual way. NB: does <Emphasis>not</Emphasis> affect
-<Literal>-D</Literal> macros passed to the C compiler when compiling via C! For those,
-use the <Literal>-optc-Dfoo</Literal> hack… (see <XRef LinkEnd="forcing-options-through">).
+Define macro <Constant><foo></Constant> in the usual way. NB: does <Emphasis>not</Emphasis> affect
+<Option>-D</Option> macros passed to the C compiler when compiling via C! For those,
+use the <Option>-optc-Dfoo</Option> hack… (see <XRef LinkEnd="forcing-options-through">).
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-U<foo></Literal>:</Term>
+<Term><Option>-U<foo></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-U<name> option</Primary></IndexTerm>
-Undefine macro <Literal><foo></Literal> in the usual way.
+Undefine macro <Command><foo></Command> in the usual way.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-I<dir></Literal>:</Term>
+<Term><Option>-I<dir></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-I<dir> option</Primary></IndexTerm>
</Para>
<Para>
-The <Literal>ghc</Literal> driver pre-defines several macros when processing Haskell
-source code (<Literal>.hs</Literal> or <Literal>.lhs</Literal> files):
+The GHC driver pre-defines several macros when processing Haskell
+source code (<Filename>.hs</Filename> or <Filename>.lhs</Filename> files):
</Para>
<Para>
<VariableList>
<VarListEntry>
-<Term><Literal>__HASKELL98__</Literal>:</Term>
+<Term><Constant>__HASKELL98__</Constant>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>__HASKELL98__</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>__HASKELL__=98</Literal>:</Term>
+<Term><Constant>__HASKELL__=98</Constant>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>__HASKELL__</Primary></IndexTerm>
-In GHC 4.04 and later, the <Literal>__HASKELL__</Literal> macro is defined as having
-the value <Literal>98</Literal>.
+In GHC 4.04 and later, the <Constant>__HASKELL__</Constant> macro is defined as having
+the value <Constant>98</Constant>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>__HASKELL1__</Literal>:</Term>
+<Term><Constant>__HASKELL1__</Constant>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>__HASKELL1__ macro</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>__GLASGOW_HASKELL__</Literal>:</Term>
+<Term><Constant>__GLASGOW_HASKELL__</Constant>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>__GLASGOW_HASKELL__ macro</Primary></IndexTerm>
</Para>
<Para>
-With any luck, <Literal>__GLASGOW_HASKELL__</Literal> will be undefined in all other
+With any luck, <Constant>__GLASGOW_HASKELL__</Constant> will be undefined in all other
implementations that support C-style pre-processing.
</Para>
<Para>
(For reference: the comparable symbols for other systems are:
-<Literal>__HUGS__</Literal> for Hugs and <Literal>__HBC__</Literal> for Chalmers.)
+<Constant>__HUGS__</Constant> for Hugs and <Constant>__HBC__</Constant> for Chalmers.)
</Para>
<Para>
NB. This macro is set when pre-processing both Haskell source and C
source, including the C source generated from a Haskell module
-(ie. <Literal>.hs</Literal>, <Literal>.lhs</Literal>, <Literal>.c</Literal> and <Literal>.hc</Literal> files).
+(i.e. <Filename>.hs</Filename>, <Filename>.lhs</Filename>, <Filename>.c</Filename> and <Filename>.hc</Filename> files).
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>__CONCURRENT_HASKELL__</Literal>:</Term>
+<Term><Constant>__CONCURRENT_HASKELL__</Constant>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>__CONCURRENT_HASKELL__ macro</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>__PARALLEL_HASKELL__</Literal>:</Term>
+<Term><Constant>__PARALLEL_HASKELL__</Constant>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>__PARALLEL_HASKELL__ macro</Primary></IndexTerm>
-Only defined when <Literal>-parallel</Literal> is in use! This symbol is defined when
+Only defined when <Option>-parallel</Option> is in use! This symbol is defined when
pre-processing Haskell (input) and pre-processing C (GHC output).
</Para>
</ListItem>
<Para>
Options other than the above can be forced through to the C
-pre-processor with the <Literal>-opt</Literal> flags (see
+pre-processor with the <Option>-opt</Option> flags (see
<XRef LinkEnd="forcing-options-through">).
</Para>
<Para>
-A small word of warning: <Literal>-cpp</Literal> is not friendly to ``string
+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>
</Para>
<Para>
-don't work with <Literal>-cpp</Literal>; <Literal>/usr/bin/cpp</Literal> elides the
+don't work with <Option>-cpp</Option>; <Filename>/usr/bin/cpp</Filename> elides the
backslash-newline pairs.
</Para>
<Para>
However, it appears that if you add a space at the end of the line,
-then <Literal>cpp</Literal> (at least GNU <Literal>cpp</Literal> and possibly other <Literal>cpp</Literal>s)
+then <Command>cpp</Command> (at least GNU <Command>cpp</Command> and possibly other <Command>cpp</Command>s)
leaves the backslash-space pairs alone and the string gap works as
expected.
</Para>
<ColSpec Align="Left" Colsep="0">
<TBody>
<Row>
-<Entry><Literal>-ansi</Literal> </Entry>
+<Entry><Option>-ansi</Option> </Entry>
<Entry> do ANSI C (not K&R) </Entry>
</Row>
<Row>
<Entry>
-<Literal>-pedantic</Literal> </Entry>
+<Option>-pedantic</Option> </Entry>
<Entry> be so</Entry>
</Row>
<Row>
<Entry>
-<Literal>-dgcc-lint</Literal> </Entry>
+<Option>-dgcc-lint</Option> </Entry>
<Entry> (hack) short for ``make GCC very paranoid''</Entry>
</Row>
<Para>
GHC has to link your code with various libraries, possibly including:
-user-supplied, GHC-supplied, and system-supplied (<Literal>-lm</Literal> math
+user-supplied, GHC-supplied, and system-supplied (<Option>-lm</Option> math
library, for example).
</Para>
<VariableList>
<VarListEntry>
-<Term><Literal>-l<FOO></Literal>:</Term>
+<Term><Option>-l<FOO></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-l<lib> option</Primary></IndexTerm>
-Link in a library named <Literal>lib<FOO>.a</Literal> which resides somewhere on the
+Link in a library named <Filename>lib<FOO>.a</Filename> which resides somewhere on the
library directories path.
</Para>
<Para>
Because of the sad state of most UNIX linkers, the order of such
-options does matter. Thus: <Literal>ghc -lbar *.o</Literal> is almost certainly
-wrong, because it will search <Literal>libbar.a</Literal> <Emphasis>before</Emphasis> it has
-collected unresolved symbols from the <Literal>*.o</Literal> files.
-<Literal>ghc *.o -lbar</Literal> is probably better.
+options does matter. Thus: <Command>ghc -lbar *.o</Command> is almost certainly
+wrong, because it will search <Filename>libbar.a</Filename> <Emphasis>before</Emphasis> it has
+collected unresolved symbols from the <Filename>*.o</Filename> files.
+<Command>ghc *.o -lbar</Command> is probably better.
</Para>
<Para>
<Row>
<Entry>
-<Literal>-lHSrts,-lHSclib</Literal> </Entry>
+<Option>-lHSrts,-lHSclib</Option> </Entry>
<Entry> basic runtime libraries </Entry>
</Row>
<Row>
<Entry>
-<Literal>-lHS</Literal> </Entry>
+<Option>-lHS</Option> </Entry>
<Entry> standard Prelude library </Entry>
</Row>
<Row>
<Entry>
-<Literal>-lHS_cbits</Literal> </Entry>
+<Option>-lHS_cbits</Option> </Entry>
<Entry> C support code for standard Prelude library </Entry>
</Row>
<Row>
<Entry>
-<Literal>-lgmp</Literal> </Entry>
+<Option>-lgmp</Option> </Entry>
<Entry> GNU multi-precision library (for Integers)</Entry>
</Row>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-syslib <name></Literal>:</Term>
+<Term><Option>-syslib <name></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-syslib <name> option</Primary></IndexTerm>
<Para>
If you are using a Haskell ``system library'' (e.g., the POSIX
-library), just use the <Literal>-syslib posix</Literal> option, and the correct code
+library), just use the <Option>-syslib posix</Option> option, and the correct code
should be linked in.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-L<dir></Literal>:</Term>
+<Term><Option>-L<dir></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-L<dir> option</Primary></IndexTerm>
Where to find user-supplied libraries… Prepend the directory
-<Literal><dir></Literal> to the library directories path.
+<Filename><dir></Filename> to the library directories path.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-static</Literal>:</Term>
+<Term><Option>-static</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-static option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-no-link-chk</Literal> and <Literal>-link-chk</Literal>:</Term>
+<Term><Option>-no-link-chk</Option> and <Option>-link-chk</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-no-link-chk option</Primary></IndexTerm>
the pieces that went into it were compiled with compatible flags; a
``consistency check''.
(This is to avoid mysterious failures caused by non-meshing of
-incompatibly-compiled programs; e.g., if one <Literal>.o</Literal> file was compiled
+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
-check with <Literal>-no-link-chk</Literal>. You can turn it (back) on with
-<Literal>-link-chk</Literal> (the default).
+check with <Option>-no-link-chk</Option>. You can turn it (back) on with
+<Option>-link-chk</Option> (the default).
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-no-hs-main</Literal>:</Term>
+<Term><Option>-no-hs-main</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-no-hs-main option</Primary></IndexTerm>
<Para>
In the event you want to include ghc-compiled code as part of another
(non-Haskell) program, the RTS will not be supplying its definition of
-<Literal>main()</Literal> at link-time, you will have to. To signal that to the
-driver script when linking, use <Literal>-no-hs-main</Literal>.
+<Function>main()</Function> at link-time, you will have to. To signal that to the
+driver script when linking, use <Option>-no-hs-main</Option>.
</Para>
<Para>
Notice that since the command-line passed to the linker is rather
involved, you probably want to use the ghc driver script to do the
final link of your `mixed-language' application. This is not a
-requirement though, just try linking once with <Literal>-v</Literal> on to see what
+requirement though, just try linking once with <Option>-v</Option> on to see what
options the driver passes through to the linker.
</Para>
</ListItem>
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
-(ie. <Literal>Concurrent</Literal> and friends), use the <Literal>-syslib concurrent</Literal> 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 <Literal>-C[<us>]</Literal>, <Literal>-q</Literal>,
-and <Literal>-t<num></Literal> 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>
<Para>
To compile a Haskell program for parallel execution under PVM, use the
-<Literal>-parallel</Literal> option,<IndexTerm><Primary>-parallel option</Primary></IndexTerm> both when compiling
+<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 <Literal>-N<n></Literal>, to say how many
+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>
<IndexTerm><Primary>Parallel Haskell—PVM use</Primary></IndexTerm>
Before you can run a parallel program under PVM, you must set the
required environment variables (PVM's idea, not ours); something like,
-probably in your <Literal>.cshrc</Literal> or equivalent:
+probably in your <Filename>.cshrc</Filename> or equivalent:
<ProgramListing>
setenv PVM_ROOT /wherever/you/put/it
</Para>
<Para>
-You use the <Literal>pvm</Literal><IndexTerm><Primary>pvm command</Primary></IndexTerm> command to start PVM on your
+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:
</Para>
<TBody>
<Row>
-<Entry><Literal>Control-D</Literal></Entry>
-<Entry>exit <Literal>pvm</Literal>, leaving it running</Entry>
+<Entry><KeyCombo><KeyCap>Control</KeyCap><KeyCap>D</KeyCap></KeyCombo></Entry>
+<Entry>exit <Command>pvm</Command>, leaving it running</Entry>
</Row>
<Row>
-<Entry><Literal>halt</Literal></Entry>
+<Entry><Command>halt</Command></Entry>
<Entry>kill off this ``parallel machine'' & exit</Entry>
</Row>
<Row>
-<Entry><Literal>add <host></Literal></Entry>
-<Entry>add <Literal><host></Literal> as a processor</Entry>
+<Entry><Command>add <host></Command></Entry>
+<Entry>add <Command><host></Command> as a processor</Entry>
</Row>
<Row>
-<Entry><Literal>delete <host></Literal></Entry>
-<Entry>delete <Literal><host></Literal></Entry>
+<Entry><Command>delete <host></Command></Entry>
+<Entry>delete <Command><host></Command></Entry>
</Row>
<Row>
-<Entry><Literal>reset</Literal></Entry>
+<Entry><Command>reset</Command></Entry>
<Entry>kill what's going, but leave PVM up</Entry>
</Row>
<Row>
-<Entry><Literal>conf</Literal></Entry>
+<Entry><Command>conf</Command></Entry>
<Entry>list the current configuration</Entry>
</Row>
<Row>
-<Entry><Literal>ps</Literal></Entry>
+<Entry><Command>ps</Command></Entry>
<Entry>report processes' status</Entry>
</Row>
<Row>
-<Entry><Literal>pstat <pid></Literal></Entry>
+<Entry><Command>pstat <pid></Command></Entry>
<Entry>status of a particular process</Entry>
</Row>
</Para>
<Para>
-The PVM documentation can tell you much, much more about <Literal>pvm</Literal>!
+The PVM documentation can tell you much, much more about <Command>pvm</Command>!
</Para>
</Sect2>
</Para>
<Para>
-Parallelism profiles (à la <Literal>hbcpp</Literal>) can be generated with the
-<Literal>-q</Literal><IndexTerm><Primary>-q RTS option (concurrent, parallel)</Primary></IndexTerm> RTS option. The
+Parallelism profiles (à la <Command>hbcpp</Command>) can be generated with the
+<Option>-q</Option><IndexTerm><Primary>-q RTS option (concurrent, parallel)</Primary></IndexTerm> RTS option. The
per-processor profiling info is dumped into files named
-<Literal><full-path><program>.gr</Literal>. These are then munged into a PostScript picture,
+<Filename><full-path><program>.gr</Filename>. These are then munged into a PostScript picture,
which you can then display. For example, to run your program
-<Literal>a.out</Literal> on 8 processors, then view the parallelism profile, do:
+<Filename>a.out</Filename> on 8 processors, then view the parallelism profile, do:
</Para>
<Para>
<Para>
The scripts for processing the parallelism profiles are distributed
-in <Literal>ghc/utils/parallel/</Literal>.
+in <Filename>ghc/utils/parallel/</Filename>.
</Para>
</Sect2>
<Para>
The ``garbage-collection statistics'' RTS options can be useful for
seeing what parallel programs are doing. If you do either
-<Literal>+RTS -Sstderr</Literal><IndexTerm><Primary>-Sstderr RTS option</Primary></IndexTerm> or <Literal>+RTS -sstderr</Literal>, then
+<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
error. The standard error of all PE's other than the `main thread'
-appears in <Literal>/tmp/pvml.nnn</Literal>, courtesy of PVM.
+appears in <Filename>/tmp/pvml.nnn</Filename>, courtesy of PVM.
</Para>
<Para>
-Whether doing <Literal>+RTS -Sstderr</Literal> or not, a handy way to watch
-what's happening overall is: <Literal>tail -f /tmp/pvml.nnn</Literal>.
+Whether doing <Option>+RTS -Sstderr</Option> or not, a handy way to watch
+what's happening overall is: <Command>tail -f /tmp/pvml.nnn</Command>.
</Para>
</Sect2>
<VariableList>
<VarListEntry>
-<Term><Literal>-N<N></Literal>:</Term>
+<Term><Option>-N<N></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-N<N> RTS option (parallel)</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-C[<us>]</Literal>:</Term>
+<Term><Option>-C[<us>]</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-C<us> RTS option</Primary></IndexTerm>
Sets the context switch interval to <Literal><us></Literal> microseconds. A context
switch will occur at the next heap allocation after the timer expires.
-With <Literal>-C0</Literal> or <Literal>-C</Literal>, context switches will occur as often as
+With <Option>-C0</Option> or <Option>-C</Option>, context switches will occur as often as
possible (at every heap allocation). By default, context switches
occur every 10 milliseconds. Note that many interval timers are only
capable of 10 millisecond granularity, so the default setting may be
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-q[v]</Literal>:</Term>
+<Term><Option>-q[v]</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-q RTS option</Primary></IndexTerm>
(PARALLEL ONLY) Produce a quasi-parallel profile of thread activity,
-in the file <Literal><program>.qp</Literal>. In the style of <Literal>hbcpp</Literal>, this profile
+in the file <FIlename><program>.qp</FIlename>. In the style of <Command>hbcpp</Command>, this profile
records the movement of threads between the green (runnable) and red
-(blocked) queues. If you specify the verbose suboption (<Literal>-qv</Literal>), the
+(blocked) queues. If you specify the verbose suboption (<Option>-qv</Option>), the
green queue is split into green (for the currently running thread
only) and amber (for other runnable threads). We do not recommend
that you use the verbose suboption if you are planning to use the
-<Literal>hbcpp</Literal> profiling tools or if you are context switching at every heap
-check (with <Literal>-C</Literal>).
+<Command>hbcpp</Command> profiling tools or if you are context switching at every heap
+check (with <Option>-C</Option>).
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-t<num></Literal>:</Term>
+<Term><Option>-t<num></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-t<num> RTS option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-d</Literal>:</Term>
+<Term><Option>-d</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-d RTS option (parallel)</Primary></IndexTerm>
(PARALLEL ONLY) Turn on debugging. It pops up one xterm (or GDB, or
-something…) per PVM processor. We use the standard <Literal>debugger</Literal>
+something…) per PVM processor. We use the standard <Command>debugger</Command>
script that comes with PVM3, but we sometimes meddle with the
-<Literal>debugger2</Literal> script. We include ours in the GHC distribution,
-in <Literal>ghc/utils/pvm/</Literal>.
+<Command>debugger2</Command> script. We include ours in the GHC distribution,
+in <Filename>ghc/utils/pvm/</Filename>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-e<num></Literal>:</Term>
+<Term><Option>-e<num></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-e<num> RTS option (parallel)</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-Q<num></Literal>:</Term>
+<Term><Option>-Q<num></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-Q<num> RTS option (parallel)</Primary></IndexTerm>
</Para>
<Sect1 id="mkdependHS">
-<Title>Makefile dependencies in Haskell: using <Literal>mkdependHS</Literal>
+<Title>Makefile dependencies in Haskell: using <Command>mkdependHS</Command>
</Title>
<Para>
</Para>
<Para>
-You run <Literal>mkdependHS</Literal> like this:
+You run <Command>mkdependHS</Command> like this:
<Screen>
mkdependHS [mkdependHS options] [-- GHC options --] srcfile1 [srcfile2 ...]
ghc -M [mkdependHS options(prefix with -optdep)] [ GHC options ] srcfile1 [srcfile2 ...]
</Screen>
-To see <Literal>mkdependHS</Literal>'s command-line flags, give it a duff flag,
-e.g., <Literal>mkdependHS -help</Literal>.
+To see <Command>mkdependHS</Command>'s command-line flags, give it a duff flag,
+e.g., <Command>mkdependHS -help</Command>.
</Para>
<Para>
import B ...blah...
</ProgramListing>
-then <Literal>mkdependHS</Literal> will generate a dependency line of the form:
+then <Command>mkdependHS</Command> will generate a dependency line of the form:
<ProgramListing>
A.o : B.hi
import {-# SOURCE #-} B ...blah...
</ProgramListing>
-then <Literal>mkdependHS</Literal> will generate a dependency line of the form:
+then <Command>mkdependHS</Command> will generate a dependency line of the form:
<ProgramListing>
A.o : B.hi-boot
</ProgramListing>
(See <XRef LinkEnd="hi-files"> for details of interface files.)
-If <Literal>A</Literal> imports multiple modules, then there will be multiple lines with <Literal>A.o</Literal> as the
+If <Literal>A</Literal> imports multiple modules, then there will be multiple lines with <Filename>A.o</Filename> as the
target.
</Para>
<Para>
-By default, <Literal>mkdependHS</Literal> generates all the dependencies, and then
+By default, <Command>mkdependHS</Command> generates all the dependencies, and then
concatenates them onto the end of
-<Literal>makefile</Literal> (or <Literal>Makefile</Literal> if <Literal>makefile</Literal> doesn't exist) bracketed by
+<Filename>makefile</Filename> (or <Filename>Makefile</Filename> if <Filename>makefile</Filename> doesn't exist) bracketed by
the lines "<Literal># DO NOT DELETE: Beginning of Haskell dependencies</Literal>" and
"<Literal># DO NOT DELETE: End of Haskell dependencies</Literal>". If these lines
-already exist in the <Literal>makefile</Literal>, <Literal>mkdependHS</Literal> deletes the old
+already exist in the <Filename>makefile</Filename>, <Command>mkdependHS</Command> deletes the old
dependencies first.
</Para>
<Para>
-<Literal>mkdependHS</Literal> takes GHC options between <Literal>--</Literal> brackets.
+<Command>mkdependHS</Command> takes GHC options between <Literal>--</Literal> brackets.
It understands the following ones. Any options between <Literal>--</Literal> brackets
that it doesn't understand are simply ignored; this way you can feed your
-Makefile's standard GHC options to <Literal>mkdependHS</Literal> un-filtered.
+Makefile's standard GHC options to <Command>mkdependHS</Command> un-filtered.
<VariableList>
<VarListEntry>
-<Term><Literal>-cpp</Literal></Term>
+<Term><Option>-cpp</Option></Term>
<ListItem>
<Para>
Run the C pre-processor over the input files. The
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-D<blah></Literal></Term>
+<Term><Option>-D<blah></Option></Term>
<ListItem>
<Para>
-A cpp <Literal>#define</Literal>; usual meaning.
+A cpp <Option>#define</Option>; usual meaning.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-i<dirs></Literal></Term>
+<Term><Option>-i<dirs></Option></Term>
<ListItem>
<Para>
-Add <Literal><dirs></Literal> (colon-separated) to list of directories
+Add <Filename><dirs></Filename> (colon-separated) to list of directories
to search for "import"ed modules.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-I<dir></Literal></Term>
+<Term><Option>-I<dir></Option></Term>
<ListItem>
<Para>
-Add <Literal><dir></Literal> to list of directories to search for
+Add <Filename><dir></Filename> to list of directories to search for
.h files (i.e., usual meaning).
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-syslib <blah></Literal></Term>
+<Term><Option>-syslib <blah></Option></Term>
<ListItem>
<Para>
This program uses this GHC system library; take
</Para>
<Para>
-Here are the <Literal>mkdependHS</Literal>-specific options (not between <Literal>--</Literal>'s):
+Here are the <Command>mkdependHS</Command>-specific options (not between <Literal>--</Literal>'s):
<VariableList>
<VarListEntry>
-<Term><Literal>-v</Literal></Term>
+<Term><Option>-v</Option></Term>
<ListItem>
<Para>
Be verbose.
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-v -v</Literal></Term>
+<Term><Option>-v -v</Option></Term>
<ListItem>
<Para>
Be very verbose.
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-w</Literal></Term>
+<Term><Option>-w</Option></Term>
<ListItem>
<Para>
Turn off warnings about interface file shadowing.
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-f blah</Literal></Term>
+<Term><Option>-f blah</Option></Term>
<ListItem>
<Para>
-Use <Literal>blah</Literal> as the makefile, rather than <Literal>makefile</Literal>
-or <Literal>Makefile</Literal>. If <Literal>blah</Literal> doesn't exist, <Literal>mkdependHS</Literal> creates it.
-We often use <Literal>-f .depend</Literal> to put the dependencies in <Literal>.depend</Literal> and
-then <Literal>include</Literal> the file <Literal>.depend</Literal> into <Literal>Makefilpe</Literal>.
+Use <Filename>blah</Filename> as the makefile, rather than <Filename>makefile</Filename>
+or <Filename>Makefile</Filename>. If <Filename>blah</Filename> doesn't exist, <Command>mkdependHS</Command> creates it.
+We often use <Option>-f .depend</Option> to put the dependencies in <Filename>.depend</Filename> and
+then <Command>include</Command> the file <Filename>.depend</Filename> into <Filename>Makefile</Filename>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-o <osuf></Literal></Term>
+<Term><Option>-o <osuf></Option></Term>
<ListItem>
<Para>
-Use <Literal>.<osuf></Literal> as the "target file" suffix ( default: <Literal>o</Literal>).
-Multiple <Literal>-o</Literal> flags are permitted (GHC2.05 onwards). Thus "<Literal>-o hc -o o</Literal>"
-will generate dependencies for <Literal>.hc</Literal> and <Literal>.o</Literal> files.
+Use <Filename>.<osuf></Filename> as the "target file" suffix ( default: <Literal>o</Literal>).
+Multiple <Option>-o</Option> flags are permitted (GHC2.05 onwards). Thus "<Option>-o hc -o o</Option>"
+will generate dependencies for <Filename>.hc</Filename> and <Filename>.o</Filename> files.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-s <suf></Literal></Term>
+<Term><Option>-s <suf></Option></Term>
<ListItem>
<Para>
Make extra dependencies that declare that files with
-suffix <Literal>.<suf>_<osuf></Literal> depend on interface files with suffix <Literal>.<suf>_hi</Literal>, or
-(for <Literal>{-# SOURCE #-}</Literal> imports) on <Literal>.hi-boot</Literal>.
-Multiple <Literal>-s</Literal> flags are permitted.
-For example, "<Literal>-o hc -s a -s b</Literal>" will
-make dependencies for <Literal>.hc</Literal> on <Literal>.hi</Literal>, <Literal>.a_hc</Literal> on <Literal>.a_hi</Literal>, and <Literal>.b_hc</Literal> on <Literal>.b_hi</Literal>.
+suffix <Filename>.<suf>_<osuf></Filename> depend on interface files with suffix <Filename>.<suf>_hi</Filename>, or
+(for <Literal>{-# SOURCE #-}</Literal> imports) on <Filename>.hi-boot</Filename>.
+Multiple <Option>-s</Option> flags are permitted.
+For example, <Option>-o hc -s a -s b</Option> will
+make dependencies for <Filename>.hc</Filename> on <Filename>.hi</Filename>, <Filename>.a_hc</Filename> on <Filename>.a_hi</Filename>, and <Filename>.b_hc</Filename> on <Filename>.b_hi</Filename>.
(Useful in conjunction with NoFib "ways".)
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>--exclude-module=<file></Literal></Term>
+<Term><Option>--exclude-module=<file></Option></Term>
<ListItem>
<Para>
-Regard <Literal><file></Literal> as "stable"; i.e., exclude it from having
+Regard <Filename><file></Filename> as "stable"; i.e., exclude it from having
dependencies on it.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-x</Literal></Term>
+<Term><Option>-x</Option></Term>
<ListItem>
<Para>
-same as <Literal>--exclude-module</Literal>
+same as <Option>--exclude-module</Option>
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>--exclude-directory=<dirs></Literal></Term>
+<Term><Option>--exclude-directory=<dirs></Option></Term>
<ListItem>
<Para>
-Regard the colon-separated list of directories <Literal><dirs></Literal> as containing stable,
+Regard the colon-separated list of directories <Filename><dirs></Filename> as containing stable,
don't generate any dependencies on modules therein.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-Xdirs</Literal></Term>
+<Term><Option>-Xdirs</Option></Term>
<ListItem>
<Para>
-same as <Literal>--exclude-directory</Literal>.
+same as <Option>--exclude-directory</Option>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>--include-module=<file></Literal></Term>
+<Term><Option>--include-module=<file></Option></Term>
<ListItem>
<Para>
-Regard <Literal><file></Literal> as not "stable"; i.e., generate dependencies
+Regard <Filename><file></Filename> as not "stable"; i.e., generate dependencies
on it (if any). This option is normally used in conjunction
-with the <Literal>--exclude-directory</Literal> option.
+with the <Option>--exclude-directory</Option> option.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>--include-prelude</Literal></Term>
+<Term><Option>--include-prelude</Option></Term>
<ListItem>
<Para>
Regard prelude libraries as unstable, i.e., generate dependencies
on the prelude modules used (including <Literal>Prelude</Literal>).
This option is normally only used by the various system libraries. If
-a <Literal>-syslib</Literal> option is used, dependencies will also be
+a <Option>-syslib</Option> option is used, dependencies will also be
generated on the library's interfaces.
</Para>
</ListItem>
</Sect1>
<Sect1 id="hstags">
-<Title>Emacs `TAGS' for Haskell: <Literal>hstags</Literal>
+<Title>Emacs `TAGS' for Haskell: <Command>hstags</Command>
</Title>
<Para>
</Para>
<Para>
-GHC comes with a program <Literal>hstags</Literal>, which build Emacs-able TAGS files. The invocation syntax is:
+GHC comes with a program <Command>hstags</Command>, which build Emacs-able TAGS files. The invocation syntax is:
<Screen>
hstags [GHC-options] file [files...]
</Para>
<Para>
-The only flags of its own are: <Literal>-v</Literal> to be verbose; <Literal>-a</Literal> to
-**APPEND** to the TAGS file, rather than write to it.
+The only flags of its own are: <Option>-v</Option> to be verbose; <Option>-a</Option> to
+<Emphasis>APPEND</Emphasis> to the TAGS file, rather than write to it.
</Para>
<Para>
</Para>
<Para>
-(Actually, GHC also comes with <Literal>etags</Literal> [for C], and <Literal>perltags</Literal>
+(Actually, GHC also comes with <Command>etags</Command> [for C], and <Command>perltags</Command>
[for You Know What]. And—I cannot tell a lie—there is Denis
-Howe's <Literal>fptags</Literal> [for Haskell, etc.] in the <Literal>ghc/CONTRIB</Literal>
+Howe's <Command>fptags</Command> [for Haskell, etc.] in the <Filename>ghc/CONTRIB</Filename>
section…)
</Para>
</Sect1>
<Sect1 id="happy">
-<Title>``Yacc for Haskell'': <Literal>happy</Literal>
+<Title>``Yacc for Haskell'': <Command>happy</Command>
</Title>
<Para>
<IndexTerm><Primary>Yacc for Haskell</Primary></IndexTerm>
<IndexTerm><Primary>parser generator for Haskell</Primary></IndexTerm>
Andy Gill and Simon Marlow have written a parser-generator for
-Haskell, called <Literal>happy</Literal>.<IndexTerm><Primary>happy parser generator</Primary></IndexTerm> <Literal>Happy</Literal>
-is to Haskell what <Literal>Yacc</Literal> is to C.
+Haskell, called <Command>happy</Command>.<IndexTerm><Primary>happy parser generator</Primary></IndexTerm> <Command>Happy</Command>
+is to Haskell what <Command>Yacc</Command> is to C.
</Para>
<Para>
-You can get <Literal>happy</Literal> by FTP from <Literal>ftp.dcs.gla.ac.uk</Literal> in
-<Literal>pub/haskell/happy</Literal>, the file <Literal>happy-1.5-src.tar.gz</Literal>.
+You can get <Command>happy</Command> by FTP from <Literal>ftp.dcs.gla.ac.uk</Literal> in
+<Filename>pub/haskell/happy</Filename>, the file <Filename>happy-1.5-src.tar.gz</Filename>.
</Para>
<Para>
-<Literal>Happy</Literal> is at its shining best when compiled by GHC.
+<Command>Happy</Command> is at its shining best when compiled by GHC.
</Para>
</Sect1>
<Sect1 id="pphs">
-<Title>Pretty-printing Haskell: <Literal>pphs</Literal>
+<Title>Pretty-printing Haskell: <Command>pphs</Command>
</Title>
<Para>
<Para>
Andrew Preece has written
-<Literal>pphs</Literal>,<IndexTerm><Primary>pphs</Primary></IndexTerm><IndexTerm><Primary>pretty-printing Haskell</Primary></IndexTerm>
+<Command>pphs</Command>,<IndexTerm><Primary>pphs</Primary></IndexTerm><IndexTerm><Primary>pretty-printing Haskell</Primary></IndexTerm>
a utility to pretty-print Haskell code in LaTeX documents.
Keywords in bolds, variables in italics—that sort of thing. It is
good at lining up program clauses and equals signs, things that are
</Para>
<Para>
-The code is distributed with GHC in <Literal>ghc/CONTRIB/pphs</Literal>.
+The code is distributed with GHC in <Filename>ghc/CONTRIB/pphs</Filename>.
</Para>
</Sect1>
</Para>
<Para>
-Bear in mind that string gaps and the <Literal>-cpp</Literal><IndexTerm><Primary>-cpp option</Primary></IndexTerm>
+Bear in mind that string gaps and the <Option>-cpp</Option><IndexTerm><Primary>-cpp option</Primary></IndexTerm>
option don't mix very well (see <XRef LinkEnd="c-pre-processor">).
</Para>
</ListItem>
</Para>
<Para>
-will give you a binary as before, but the <Literal>main.exe</Literal> generated
+will give you a binary as before, but the <Filename>main.exe</Filename> generated
will use the Prelude and RTS DLLs instead.
</Para>
<Para>
If you want to build an executable that doesn't depend on any
-ghc-compiled DLLs, use the <Literal>-static</Literal> option to link in
+ghc-compiled DLLs, use the <Option>-static</Option> option to link in
the code statically.
</Para>
<Para>
Notice that you cannot mix code that has been compiled with
-<Literal>-static</Literal> and not, so you have to use the <Literal>-static</Literal>
+<Option>-static</Option> and not, so you have to use the <Option>-static</Option>
option on all the Haskell modules that make up your application.
</Para>
</Para>
<Para>
-By feeding the ghc compiler driver the option <Literal>--mk-dll</Literal>, it
+By feeding the ghc compiler driver the option <Option>--mk-dll</Option>, it
will build a DLL rather than produce an executable. The DLL will
consist of all the object files and archives given on the command
line.
<Para>
If a directory contains the (probably empty) file
-<Literal>dLL_ifs.hi</Literal>, the code corresponding to the interface
+<Filename>dLL_ifs.hi</Filename>, the code corresponding to the interface
files found in that directory are assumed to live in a DLL
separate from the one being compiled.
Notice that the first rule takes precedence over this one, so if
you're compiling a module that imports from a Haskell module whose
interface file live in the same directory, <Emphasis>and</Emphasis> that directory
-also contains the file <Literal>dLL_ifs.hi</Literal>, the import is still not
+also contains the file <Filename>dLL_ifs.hi</Filename>, the import is still not
being considered to be a 'DLL import'.
</Para>
<ListItem>
<Para>
-If compiling with the option <Literal>-static</Literal>, the previous rule
+If compiling with the option <Option>-static</Option>, the previous rule
is disabled.
</Para>
</ListItem>
So, in short, after having built your Haskell DLL, make sure you
-create the file <Literal>dLL_ifs.hi</Literal> in the directory that contains
+create the file <Filename>dLL_ifs.hi</Filename> in the directory that contains
its interface files. If you don't, Haskell code that calls upon entry
points in that DLL, will do so incorrectly, and a crash will result.
(it is unfortunate that this isn't currently caught at compile-time).
<Para>
By default, the entry points of all the object files will
-be exported from the DLL when using <Literal>--mk-dll</Literal>. Should you want
+be exported from the DLL when using <Option>--mk-dll</Option>. Should you want
to constrain this, you can specify the <Emphasis>module definition file</Emphasis>
to use on the command line as follows:
<ListItem>
<Para>
-In addition to creating a DLL, the <Literal>--mk-dll</Literal> option will also
+In addition to creating a DLL, the <Option>--mk-dll</Option> option will also
create an import library. The import library name is derived from the
name of the DLL, as follows:
The naming scheme may look a bit weird, but it has the purpose of
allowing the co-existence of import libraries with ordinary static
-libraries (e.g., <Literal>libHSfoo.a</Literal> and <Literal>libHSfoo_imp.a</Literal>.
+libraries (e.g., <Filename>libHSfoo.a</Filename> and <Filename>libHSfoo_imp.a</Filename>.
Additionally, when the compiler driver is linking in non-static mode,
-it will rewrite occurrence of <Literal>-lHSfoo</Literal> on the command line to
-<Literal>-lHSfoo_imp</Literal>. By doing this for you, switching from non-static
-to static linking is simply a question of adding <Literal>-static</Literal> to
+it will rewrite occurrence of <Option>-lHSfoo</Option> on the command line to
+<Option>-lHSfoo_imp</Option>. By doing this for you, switching from non-static
+to static linking is simply a question of adding <Option>-static</Option> to
your command line.
</Para>
projects / ghc-hetmet.git / commitdiff