New SGML User Guide, first cut.
state-of-play with the Haskell~1.2 compiler---at the same time as
2.01.
-The announcement for this release is distributed as \tr{ANNOUNCE-2.01}
+The announcement for this release is distributed as @ANNOUNCE-2.01@
in the top-level directory. It contains very important caveats about
2.01, which we do not repeat here!
%************************************************************************
%* *
-\subsection[2-01-config]{New configuration things in 2.01}
+<sect1>New configuration things in 2.01
+<label id="2-01-config">
+<p>
%* *
%************************************************************************
%************************************************************************
%* *
-\subsection[2-01-user-visible]{User-visible changes in 2.01, including incompatibilities}
+<sect1>User-visible changes in 2.01, including incompatibilities
+<label id="2-01-user-visible">
+<p>
%* *
%************************************************************************
%************************************************************************
%* *
-\subsection[2-01-options]{New or changed GHC command-line options}
+<sect1>New or changed GHC command-line options
+<label id="2-01-options">
+<p>
%* *
%************************************************************************
-A new flag, \tr{-recomp} invokes the new ``recompilation checker.''
+A new flag, @-recomp@ invokes the new ``recompilation checker.''
We recommend that you use it whenever you use `make' to build your
Haskell programs. Please see the User's Guide for details.
-The flags \tr{-fomit-derived-read} and
-\tr{-fomit-reexported-instances} have died; there is no longer any
+The flags @-fomit-derived-read@ and
+@-fomit-reexported-instances@ have died; there is no longer any
need for them.
%************************************************************************
%* *
-\subsection[2-01-new-in-compiler]{New in the compiler proper}
+<sect1>New in the compiler proper
+<label id="2-01-new-in-compiler">
+<p>
%* *
%************************************************************************
Substantially rewritten. Notable points:
-\begin{itemize}
-\item
+<itemize>
+<item>
The typechecker, besides doing all the new 1.3
features (constructor classes, records, etc.), has been made
ready to do linear types (e.g., there are now ``usage
variables'' as well as ``type variables'').
-\item
+<item>
The Core language now has one constructor for lambdas
-(\tr{Lam}; rather than two, \tr{CoLam} and \tr{CoTyLam});
-also, one constructor for applications (\tr{App}, rather
-than two, \tr{CoApp} and \tr{CoTyApp}).
+(@Lam@; rather than two, @CoLam@ and @CoTyLam@);
+also, one constructor for applications (@App@, rather
+than two, @CoApp@ and @CoTyApp@).
Consequently, new more-general datatypes for binders and
-arguments now exist (\tr{CoreBinder} and \tr{CoreArg},
+arguments now exist (@CoreBinder@ and @CoreArg@,
respectively).
Again, the Core language is now ``linear types''-ready
(though the work hasn't been done yet).
-A new Core constructor, \tr{Coerce}, exists to support the
-1.3 \tr{newtype} construct.
+A new Core constructor, @Coerce@, exists to support the
+1.3 @newtype@ construct.
-\item
+<item>
The ``renamer''---the part of the compiler that implements
the Haskell module system---has been completely rewritten.
We've implemented the new system with a ``go to the
horse's mouth'' scheme; that is, to discover the facts about
-an entity \tr{Foo.bar}, we {\em always} go to the interface
-for module \tr{Foo}; hence, we can never get duff information
-about \tr{bar} from some intermediary.
+an entity @Foo.bar@, we <em>always</em> go to the interface
+for module @Foo@; hence, we can never get duff information
+about @bar@ from some intermediary.
Interface files are no longer mandated by the language, so
they are completely different in 2.01 compared to 0.2x. They
files is done in Haskell now (the most likely reason why GHC
has slowed down :-().
-\item
+<item>
Much less special pleading for the Prelude. If you wanted
to write your own Prelude and drop it in, you would have
a fighting chance now.
-\item
+<item>
No more `make' dependency loops! (Hooray!) The whole compiler
will build in one `make' run, no fuss or bother.
-\end{itemize}
+</itemize>
%************************************************************************
%* *
-\subsection[2-01-new-in-libraries]{In the ``required'' libraries (incl. Prelude)}
+<sect1>In the ``required'' libraries (incl. Prelude)
+<label id="2-01-new-in-libraries">
+<p>
%* *
%************************************************************************
We support standard 1.3 monadic I/O, to the best of our knowledge.
-The proposal for \tr{LibPosix} didn't make it into Haskell 1.3 I/O.
-So it's now a system library, \tr{-syslib posix}. (And, of course,
-the \tr{Lib} prefix is gone.)
+The proposal for @LibPosix@ didn't make it into Haskell 1.3 I/O.
+So it's now a system library, @-syslib posix@. (And, of course,
+the @Lib@ prefix is gone.)
%************************************************************************
%* *
-\subsection[2-01-new-in-glaexts]{New in ``Glasgow extensions'' library things}
+<sect1>New in ``Glasgow extensions'' library things
+<label id="2-01-new-in-glaexts">
+<p>
%* *
%************************************************************************
MallocPtrs now called ForeignObjs
The @_PackedString@ gunk (with leading underscores) is gone. Just
-\tr{import PackedString} and use ``normal'' names.
+@import PackedString@ and use ``normal'' names.
-All of the following are {\em gone}:
-\begin{verbatim}
+All of the following are <em>gone</em>:
+<tscreen><verb>
data _FILE -- corresponds to a "FILE *" in C
fclose :: _FILE -> PrimIO Int
appendFilePrimIO :: String -> String -> PrimIO ()
getArgsPrimIO :: PrimIO [String]
readChanPrimIO :: String -> PrimIO String
-\end{verbatim}
+</verb></tscreen>
%************************************************************************
%* *
-\subsection[2-01-new-in-syslibs]{In the ``system'' libraries}
+<sect1>In the ``system'' libraries
+<label id="2-01-new-in-syslibs">
+<p>
%* *
%************************************************************************
The ``system'' libraries are no longer part of GHC (they lived in
-\tr{ghc/lib/}); they have been lifted out into a subsystem in their
-own right (they live in \tr{hslibs}).
+@ghc/lib/@); they have been lifted out into a subsystem in their
+own right (they live in @hslibs@).
Of course, a GHC distribution will ``happen'' to have these libraries
included; however, we hope the libraries will evolve into a large,
flourishing, independently-maintained, and independently-distributed
body of code---preferably compiler-independent, too!
-Renamings in the GHC system library (\tr{hslibs/ghc/}): The function
-\tr{BitSet.singletonBS} is now called \tr{unitBS}. Similarly,
-\tr{FiniteMap.singletonFM} is now \tr{unitFM}. \tr{Set.singletonSet}
-lingers briefly; \tr{unitSet} is also available now.
+Renamings in the GHC system library (@hslibs/ghc/@): The function
+@BitSet.singletonBS@ is now called @unitBS@. Similarly,
+@FiniteMap.singletonFM@ is now @unitFM@. @Set.singletonSet@
+lingers briefly; @unitSet@ is also available now.
-We are {\em not} up-to-date with the HBC-for-1.3's HBC library (the source
+We are <em>not</em> up-to-date with the HBC-for-1.3's HBC library (the source
hasn't been released yet).
-The \tr{Either}, \tr{Maybe}, and \tr{Option} modules in the HBC
-library (\tr{hslibs/hbc/}) have been deleted---they are too close to
+The @Either@, @Maybe@, and @Option@ modules in the HBC
+library (@hslibs/hbc/@) have been deleted---they are too close to
what Haskell~1.3 provides anyway (hence, confusing).
-The POSIX support code is in \tr{hslibs/posix}.
+The POSIX support code is in @hslibs/posix@.
-We have added a ``contrib'' system library (\tr{hslibs/contrib/});
+We have added a ``contrib'' system library (@hslibs/contrib/@);
made up of code that was contributed to the ``Haskell library'',
mostly by Stephen Bevan. Quite of bit of code for numerical methods
in there...
%************************************************************************
%* *
-\subsection[2-01-new-in-rts]{In the runtime system}
+<sect1>In the runtime system
+<label id="2-01-new-in-rts">
+<p>
%* *
%************************************************************************
-We have made a point {\em not} to beat on the runtime system very much.
+We have made a point <em>not</em> to beat on the runtime system very much.
Some bugs have been fixed since 0.26, of course.
The GranSim (parallel-machine simulator) stuff is substantially improved
%************************************************************************
%* *
-%\subsection[2-01-new-elsewhere]{Other new stuff}
+%<sect1>Other new stuff
+<label id="2-01-new-elsewhere">
+<p>
%* *
%************************************************************************
+<sect1>Release notes for version~2.02---3/97
+<label id="release-2-02">
+<p>
+
Release~2.02 is the first release of Glasgow Haskell for Haskell~1.4.
-The announcement for this release is distributed as \tr{ANNOUNCE-2.02}
+The announcement for this release is distributed as @ANNOUNCE-2.02@
in the top-level directory. It contains very important caveats about
2.02, which we do not repeat here!
%************************************************************************
%* *
-\subsection[2-02-config]{New configuration things in 2.02}
+<sect1>New configuration things in 2.02
+<label id="2-02-config">
+<p>
%* *
%************************************************************************
%************************************************************************
%* *
-\subsection[2-02-user-visible]{User-visible changes in 2.02, including incompatibilities}
+<sect1>User-visible changes in 2.02, including incompatibilities
+<label id="2-02-user-visible">
+<p>
%* *
%************************************************************************
%************************************************************************
%* *
-\subsection[2-02-options]{New or changed GHC command-line options}
+<sect1>New or changed GHC command-line options
+<label id="2-02-options">
+<p>
%* *
%************************************************************************
-\begin{itemize}
-\item GHC now warns of possibly-incomplete patterns in case expressions
+<itemize>
+<item> GHC now warns of possibly-incomplete patterns in case expressions
and function bindings. You can suppress these warnings with @-fno-warn-incomplete-patterns@.
GHC also warns of completely overlapped patterns. You can't switch this off.
-\item GHC can warn of shadowed names, though it does not do so by default.
+<item> GHC can warn of shadowed names, though it does not do so by default.
Just occasionally this shows up
an otherwise hard-to-find bug. To warn of shadowed names use @-fwarn-name-shadowing@
-\item You can now generate `make' dependencies via the compiler
+<item> You can now generate `make' dependencies via the compiler
driver, use the option @-M@ together with the list source files to compute
the dependencies for. By default, the dependencies will be appended to
-the file \tr{Makefile} in the current directory.
+the file @Makefile@ in the current directory.
-\item For hackers, the flag @-dshow-rn-trace@ shows what the renamer is up to.
+<item> For hackers, the flag @-dshow-rn-trace@ shows what the renamer is up to.
Sit back and marvel.
-\end{itemize}
+</itemize>
%************************************************************************
%* *
-\subsection[2-02-new-in-compiler]{New in the compiler proper}
+<sect1>New in the compiler proper
+<label id="2-02-new-in-compiler">
+<p>
%* *
%************************************************************************
-\begin{itemize}
-\item
+<itemize>
+<item>
Completely new ``make-world'' system, properly documented (at last) in the
installation guide. No Jmakefiles; but you *need* Gnu make
(gmake). The more recent the better (v 3.70+).
-\item
+<item>
The ``renamer''---the part of the compiler that implements
the Haskell module system---has been completely rewritten, again.
The format of interface files has changed significantly. Interface files
generated by 2.01 will not work with 2.02.
-\item
+<item>
Even less special pleading for the Prelude than in 2.01. If you wanted
to write your own Prelude and drop it in, you would have
a really good chance now.
-\end{itemize}
+</itemize>
%************************************************************************
%* *
-\subsection[2-02-new-in-libraries]{In the libraries}
+<sect1>In the libraries
+<label id="2-02-new-in-libraries">
+<p>
%* *
%************************************************************************
-The libraries have been completely reorganised. There's a description in
-\sectionref{syslibs}.
+The libraries have been completely reorganised. There's a description
+in Section <ref name="System Libraries" id="syslibs">.
%************************************************************************
%* *
-\subsection[2-02-new-in-syslibs]{In ``hslibs'' libraries}
+<sect1>In ``hslibs'' libraries
+<label id="2-02-new-in-syslibs">
+<p>
%* *
%************************************************************************
%************************************************************************
%* *
-\subsection[2-02-new-in-rts]{In the runtime system}
+<sect1>In the runtime system
+<label id="2-02-new-in-rts">
+<p>
%* *
%************************************************************************
-\begin{itemize}
-\item @ForeignObjs@ are properly deallocated when execution halts, as well
+<itemize>
+<item> @ForeignObjs@ are properly deallocated when execution halts, as well
as when the garbage collector spots the @ForeignObj@ as being unreferenced.
This is important if you are using a @ForeignObj@ to refer to
a @COM@ object or other remote resource. You want that resource to be relased
when the program terminates.
-\item Files handles in the IO prelude are implemented using
+<item> Files handles in the IO prelude are implemented using
@ForeignObjs@, and closed when the file handle is unreferenced. This
means that if you open zillions of files then just letting go of the
file handle is enough to close it.
-\end{itemize}
+</itemize>
%************************************************************************
%* *
-\subsection[2-02-new-elsewhere]{Other new stuff}
+<sect1>Other new stuff
+<label id="2-02-new-elsewhere">
+<p>
%* *
%************************************************************************
%************************************************************************
%* *
-\subsection[2-02-troublespots]{Known troublespots}
+<sect1>Known troublespots
+<label id="2-02-troublespots">
+<p>
%* *
%************************************************************************
The 2.02 compiler has the following known deficiencies:
-\begin{description}
-\item[native code generator, x86:]
+<descrip>
+<tag>native code generator, x86:</tag>
The native code generator for x86 platforms is by default switched
off, as the code the compiler produces with it enabled was discovered
just before releaseing to be wonky. Rather than delay the release
-further, GHC on x86 platforms rely on \tr{GCC} as their
+further, GHC on x86 platforms rely on @GCC@ as their
backend for now. Hopefully fixed soon.
-\item[Simplifier looping:]
+<tag>Simplifier looping:</tag>
The simplifier(Glasgow-speak for optimiser) has been observed to get
into a loop in one or two cases. If you should observe this, please
report it as a bug - the work around is to turn off optimisation.
-\item[Undefined @*_vap_info@ symbols:]
+<tag>Undefined @*_vap_info@ symbols:</tag>
If the linker complains about some undefined @*_vap_info@ symbols when
linking 2.02 compiled programs (very unlikely) - fix this by compiling
the module where the references are coming from with
@-fno-lambda-lifting@.
-\end{description}
+</descrip>
+<sect1>Release notes for version~2.03---4/97
+<label id="release-2-03">
+<p>
+
GHC 2.03 is a minor upgrade of GHC 2.02. It differs in the following
ways:
-\begin{itemize}
-\item
+<itemize>
+<item>
A slew of small bugs are fixed. You can find the complete list
at:
-\begin{verbatim}
+<tscreen><verb>
http://www.cse.ogi.edu/~simonpj/ghc-bugs.html
-\end{verbatim}
+</verb></tscreen>
One bug remains un-fixes, namely the crash when there's an empty
comment at the end of file. It's wierd!
-\item
+<item>
Last-minute language changes have been implemented (minor changes
to the libraries, and to module export/hiding scope rules)
-\item
+<item>
It is only available as a source distribution. If you want to
use it you'll have to build it from source. Nowadays this is
a well-documented process (see the build and installation guide, but
note that this release is still not self-booting, you still need
to have The Good Old Compiler (0.29) at your disposal).
-\end{itemize}
+</itemize>
None of the bugs in GHC 2.02 are show-stoppers, so you'll only want
to upgrade if you are a build-from-source junkie and the bugs are
Apart from bug-fixes, which are itemized elsewhere,
the exact language and standard-library changes are as follows:
-\begin{itemize}
-\item
+<itemize>
+<item>
A hiding clause hides the unqualified name, but not the qualified name.
-\item
+<item>
There's a new @Numeric@ library, containing mostly mildly marginal
code for showing and reading numbers. Parts of its exports used to be
exported by @Prelude@, but now you'll have to import them explicitly.
It also defines some functions that weren't provided before; have a
look in the Haskell library report for details of complete interface.
-\item
+<item>
The following extra functions are exported from @IO@:
@try@, @bracket@, @bracket_@, @hGetLine@, @hWaitForInput@.
-\end{itemize}
+</itemize>
In addition, we've made following changes to GHC libraries/GHC's
implementation of the Haskell standard prelude:
-\begin{itemize}
-\item The function @fromRational__@, exported from @PrelNum@, is now called @fromRat@.
+<itemize>
+<item> The function @fromRational__@, exported from @PrelNum@, is now called @fromRat@.
(And it's exported by @Numeric@.)
-\item
+<item>
Documentation for the Glasgow specific interfaces plus the system
libraries have been re-instated. Posix library documentation included also.
-\item
+<item>
@maybe@ is now exported from Prelude, as it should have been in 2.02.
-\item
+<item>
Equality on @IO.Handle@ is now defined as specified by the library
report.
-\item
-@Ix.rangeSize@ returns \tr{0} on an empty range;previously it failed.
-\item
+<item>
+@Ix.rangeSize@ returns @0@ on an empty range;previously it failed.
+<item>
The new interface @GlaExts@ which is meant to be the gateway to the
various Glasgow extensions has now been documented.
-\item
+<item>
@GlaExts@ now exports the representation of @Char@.
-\item
+<item>
The mutable variable interface, @MutVar@, has also been documented,
together with @ByteArray@, @MutableArray@ and @Foreign@.
-\item
+<item>
Added documentation on how to compile mutually recursive modules with
2.03.
-\end{itemize}
+</itemize>
+<sect1>Release notes for version~2.04---6/97
+<label id="release-2-04">
+<p>
+
GHC 2.04 is a minor upgrade of GHC 2.02 (and the bugfix release,
2.03), representing work done through May '97. This new release
adds the following:
-\begin{itemize}
-\item
+<itemize>
+<item>
Data constructors can now have polymorphic fields, and ordinary
functions can have polymorphic arguments. Details on
-\begin{verbatim}
+<tscreen><verb>
http://www.cse.ogi.edu/~simonpj/quantification.html
-\end{verbatim}
+</verb></tscreen>
Existential types coming, but not done yet.
-\item Pattern guards implemented, see
+<item> Pattern guards implemented, see
-\begin{verbatim}
+<tscreen><verb>
http://www.cse.ogi.edu/~simonpj/guards.html
-\end{verbatim}
+</verb></tscreen>
-\item Compiler can now compile itself.
+<item> Compiler can now compile itself.
-\item \tr{INLINE} pragmas honoured (caveat: not yet
+<item> @INLINE@ pragmas honoured (caveat: not yet
working on instance-decl methods)
-\item Simplifier improvements and better inlining gives
+<item> Simplifier improvements and better inlining gives
better code; not sure how *much* better.
-\item \tr{-dshow-rn-stats} print out amusing statistics about what
+<item> @-dshow-rn-stats@ print out amusing statistics about what
the renamer does.
-\item
+<item>
When compiling without -O, the renamer (the pass responsible for
slurping in interface file and making sure everything is in scope
etc.) is now more careful about what it will bring in (especially
change is that a lot of the (unnecessary) work this pass did in
2.02/2.03 is now avoided.
-\tr{-fno-prune-tydecls} and \tr{-fno-prune-instdecls} switch off these
+@-fno-prune-tydecls@ and @-fno-prune-instdecls@ switch off these
renamer optimisations. You can try the effect with the renamer
statistics. War stories welcome.
-\item
- The Heroic Efforts of \tr{Andr\'e Santos <alms@di.ufpe.br>} have
- been included, AIX/RS6000 is now a supported \tr{ghc}
+<item>
+ The Heroic Efforts of @Andr\'e Santos <alms@@di.ufpe.br>@ have
+ been included, AIX/RS6000 is now a supported @ghc@
platform! Bug reports concerning this port to (as always)
- \tr{glasgow-haskell-bugs@dcs.gla.ac.uk}.
+ @glasgow-haskell-bugs@@dcs.gla.ac.uk@.
-\item
+<item>
A lot of the bugs that were present in versions 2.02/2.03
have been fixed (thanks to everyone that reported bugs!).
A list of the reported problems with 2.02/2.03 can be found at
-\begin{verbatim}
+<tscreen><verb>
http://www.dcs.gla.ac.uk/fp/software/ghc/ghc-bugs.html
-\end{verbatim}
+</verb></tscreen>
No doubt entries for 2.04 will be added here as well :-)
-\item
+<item>
This release is available in source format only. To build it you'll
need to have either a copy of GHC~0.29 or GHC~2.02/3 installed.
For people either doing porting work or work on a (supported)
(in the fptools/docs directory), and an on-line version of the
document can be found at
-\begin{verbatim}
+<tscreen><verb>
http://www.dcs.gla.ac.uk/fp/software/ghc/ghc-doc/install-guide.html
-\end{verbatim}
-\end{itemize}
+</verb></tscreen>
+</itemize>
In addition to the above, we've made the following minor changes to
the GHC libraries/our implementation of the Haskell standard prelude:
-\begin{itemize}
-\item
-\tr{isPrefixOf} and \tr{isSuffixOf} has been added to \tr{List}.
-\item
-The empty type \tr{Void} is now exported from the prelude.
-\item
-\tr{GlaExts} exports the \tr{Lift} data type:
+<itemize>
+<item>
+@isPrefixOf@ and @isSuffixOf@ has been added to @List@.
+<item>
+The empty type @Void@ is now exported from the prelude.
+<item>
+@GlaExts@ exports the @Lift@ data type:
-\begin{verbatim}
+<tscreen><verb>
data Lift a = Lift a
-\end{verbatim}
+</verb></tscreen>
you might need it someday...
-\item
-The \tr{Foreign} interface now also exports the representations
-for \tr{Word} and \tr{Addr}.
+<item>
+The @Foreign@ interface now also exports the representations
+for @Word@ and @Addr@.
-\item The low-level file handle interface in the \tr{POSIX} system
+<item> The low-level file handle interface in the @POSIX@ system
library has been reworked a bit, most notably is the renaming of
-\tr{Channel} to \tr{Fd} and the introduction of operations for converting
-to and from \tr{Handle} and \tr{Fd} values. The changes are:
+@Channel@ to @Fd@ and the introduction of operations for converting
+to and from @Handle@ and @Fd@ values. The changes are:
-\begin{verbatim}
+<tscreen><verb>
--Renamed functions (old name in square brackets)
openFd :: FilePath
-> OpenMode
fdToHandle :: Fd -> IO Handle
handleToFd :: Handle -> IO Fd
intToFd :: Int -> Fd -- use with care.
-\end{verbatim}
+</verb></tscreen>
-\end{itemize}
+</itemize>
+++ /dev/null
-GHC 2.06 is a minor upgrade of GHC 2.05, and is released as source only. It represents work done through August '97.
-
-Here's a list of the changes made since GHC 2.05:
-
-\begin{itemize}
-
-\item Fix to reader to allow let expressions in pattern guards.
-
-\item Tidied up @nofib/parallel@
-
-\item Changed derived @Show@ (and @Read@) code for constructors
-with labelled fields to bring them into line with the Report.
-
-\item Fixed @ghc-0.29 -O@ booting problem (codeGen/ClosureInfo not closed.)
-
-\item Improved error messages for illegal derivings of @Ix@, @Enum@
-and @Bounded@.
-
-\item Fixed bug in deriving @Ix@ code. (need to actively slurp in
-return and zero)
-
-\item New module: @PackBase@ - minimum pack/unpack code.
-
-\item Moved @PackedString@ to ghc system library
-
-\item Added export of @unionBy@ and @intersectBy@ to @List@ (plus
-commented out unused functions).
-
-\item Uniform size to @ForeignObj@ closures (indep of GC scheme).
-
-\item Added @ForeignObj@ support to NCG
-
-\item Added @index*OffForeignObj#@ primops (for completeness, mostly)
-
-\item Removed: @Util.mapAccumL@ and @Util.mapAccumR@ (now via List)
-
-\item Removed: @forall@ and @exists@ from @Util@ (now @any@ and @all@ from @Prelude@).
-
-\item fixed: handling of source input from stdin in the driver.
-
-\item x86 NCG should now compile under 2.0x
-
-\item PECULIAR: compiling -prof "fixes" simplifier performance on deep
- list comprehensions.
-
-\item Added -O for ghc/lib/cbits
-
-\item Updated @lndir@ (sync wrt. X11R6.3)
-
-\item Removed @glafp-utils/msub@
-
-\item Fixed misleading error message for guards (used to
-mention list comprehensions)
-
-\item Fixed incorrect handling of default methods (used to
-complain about differing contexts)
-
-\item Fixed missing @tidyPrimOp@ in @simplCore/SimplCore@
- (Sven Panne bug report.)
-
-\item Fixed desugaring of record construction for overloaded
-constructors. (Dave Barton bug report.)
-
-\item Fixed rank-2 polymorphism bug (Ralf Hinze bug report.)
-
-\item Fixed interface-file parser error on @GHC.->@
-
-\item Added @-no-recomp@ flag
-
-\item Changed grouping syntax for simplifier opts, instead of
- '(' and ')', use '[' and ']'. The change is made to make
- it more Win32 (and cygwin32) friendly.
-
-\item Removed the use of @COMPILING_GHC@ in @ghc/compiler/@
-
-\item Use @COMPILING_NCG@ instead of @COMPILING_GHC@ in @ghc/includes/@
- header files to control visibility of info needed when
- compiling the native code generator.
-
-\item Tidied up handling of IO error messages in @IOBase@
-
-\item Fixed @PackBase.unpackCString@ and @PackedString.unpackCString@
-to handle @NULL@ pointer arg gracefully.
-
-\item fix: archives in @INSTALL_LIBS@ are now ranlib'ed when installing.
-
-\item fix: for @-monly-x-regs@, the mangler now generates necessary code
- for loading up unstolen registers before GC, and save their updated
- contents (via BaseReg) on GC return before `handing back'
- the registers. This change fixed the @SIGSEGV@ problem reported by
- David Barton on an x86 platform (linux) with 2.05.
-
-\item changed @SMstats.elapsedtime@ to return non-negative floats. (=>
- no more @-Rghc-timing@ warnings about not finding @InitTime@ etc.)
-
-\item Change @mkWrapper@ in @WwLib.lhs@ to call
- @splitForAllTyExpandingDicts@ instead of @splitForALlTy@ to fix
- @absApply@ crash. (Jon Mountjoy bug report.)
-
-\item GHC's interface file parser now uses the latest version of
-Happy.
-
-\item Happy is now included in the source distribution.
-\end{itemize}
--- /dev/null
+<sect1>Release notes for version~2.06---9/97
+<label id="release-2-06">
+<p>
+
+GHC 2.06 is a minor upgrade of GHC 2.05, and is released as source only. It represents work done through August '97.
+
+Here's a list of the changes made since GHC 2.05:
+
+<itemize>
+
+<item> Fix to reader to allow let expressions in pattern guards.
+
+<item> Tidied up @nofib/parallel@
+
+<item> Changed derived @Show@ (and @Read@) code for constructors
+with labelled fields to bring them into line with the Report.
+
+<item> Fixed @ghc-0.29 -O@ booting problem (codeGen/ClosureInfo not closed.)
+
+<item> Improved error messages for illegal derivings of @Ix@, @Enum@
+and @Bounded@.
+
+<item> Fixed bug in deriving @Ix@ code. (need to actively slurp in
+return and zero)
+
+<item> New module: @PackBase@ - minimum pack/unpack code.
+
+<item> Moved @PackedString@ to ghc system library
+
+<item> Added export of @unionBy@ and @intersectBy@ to @List@ (plus
+commented out unused functions).
+
+<item> Uniform size to @ForeignObj@ closures (indep of GC scheme).
+
+<item> Added @ForeignObj@ support to NCG
+
+<item> Added @index*OffForeignObj#@ primops (for completeness, mostly)
+
+<item> Removed: @Util.mapAccumL@ and @Util.mapAccumR@ (now via List)
+
+<item> Removed: @forall@ and @exists@ from @Util@ (now @any@ and @all@ from @Prelude@).
+
+<item> fixed: handling of source input from stdin in the driver.
+
+<item> x86 NCG should now compile under 2.0x
+
+<item> PECULIAR: compiling -prof "fixes" simplifier performance on deep
+ list comprehensions.
+
+<item> Added -O for ghc/lib/cbits
+
+<item> Updated @lndir@ (sync wrt. X11R6.3)
+
+<item> Removed @glafp-utils/msub@
+
+<item> Fixed misleading error message for guards (used to
+mention list comprehensions)
+
+<item> Fixed incorrect handling of default methods (used to
+complain about differing contexts)
+
+<item> Fixed missing @tidyPrimOp@ in @simplCore/SimplCore@
+ (Sven Panne bug report.)
+
+<item> Fixed desugaring of record construction for overloaded
+constructors. (Dave Barton bug report.)
+
+<item> Fixed rank-2 polymorphism bug (Ralf Hinze bug report.)
+
+<item> Fixed interface-file parser error on @GHC.->@
+
+<item> Added @-no-recomp@ flag
+
+<item> Changed grouping syntax for simplifier opts, instead of
+ '(' and ')', use `&lsqb' and `&rsqb'. The change is made to make
+ it more Win32 (and cygwin32) friendly.
+
+<item> Removed the use of @COMPILING_GHC@ in @ghc/compiler/@
+
+<item> Use @COMPILING_NCG@ instead of @COMPILING_GHC@ in @ghc/includes/@
+ header files to control visibility of info needed when
+ compiling the native code generator.
+
+<item> Tidied up handling of IO error messages in @IOBase@
+
+<item> Fixed @PackBase.unpackCString@ and @PackedString.unpackCString@
+to handle @NULL@ pointer arg gracefully.
+
+<item> fix: archives in @INSTALL_LIBS@ are now ranlib'ed when installing.
+
+<item> fix: for @-monly-x-regs@, the mangler now generates necessary code
+ for loading up unstolen registers before GC, and save their updated
+ contents (via BaseReg) on GC return before `handing back'
+ the registers. This change fixed the @SIGSEGV@ problem reported by
+ David Barton on an x86 platform (linux) with 2.05.
+
+<item> changed @SMstats.elapsedtime@ to return non-negative floats. (=>
+ no more @-Rghc-timing@ warnings about not finding @InitTime@ etc.)
+
+<item> Change @mkWrapper@ in @WwLib.lhs@ to call
+ @splitForAllTyExpandingDicts@ instead of @splitForALlTy@ to fix
+ @absApply@ crash. (Jon Mountjoy bug report.)
+
+<item> GHC's interface file parser now uses the latest version of
+Happy.
+
+<item> Happy is now included in the source distribution.
+</itemize>
+++ /dev/null
-GHC 2.08 is a minor upgrade of GHC 2.07, and is released as source only. It represents work done through September '97.
-
-Here's a list of the changes made since GHC 2.07:
-
-\begin{itemize}
-
-\item removed deforester from source tree, including the @{-# DEFOREST #-}@
- pragma. This stuff didn't work anymore, so there was no point
- leaving it hanging around. If someone wants to pick it up again,
- the source can be checked out of the repository.
-
-\item documentation is now built automatically for binary distributions
-
-\item fixed several bugs affecting binary distributions.
-
-\item fixed bug in Regex.lhs causing random segmentation faults.
-
-\item a couple of changes to the simplifier means that binary sizes should
- be (very slightly) smaller.
-
-\item fixed a problem with error messages not being as accurate as they used to
- be.
-
-\item fixed a problem with ticky-ticky profiling (symptom: compiling modules
- with -ticky gave lots of parse errors from the C compiler).
-
-\item added support for @unmapMiddleStackPage@ on cygwin32.
-
-\item fixed a divide-by-zero problem in the GC statistics code.
-
-\end{itemize}
-
-The following changes were made to Happy:
-
-\begin{itemize}
-\item bug fixed in state generation.
-
-\item happy now reports the number of unused rules and terminals in the
- grammar, and lists which ones are unused in the info file.
-
-\item happy now tries to avoid generating fully overlapped patterns.
-
-\item bug fixed in lexer: line numbers weren't being counted for @--@
- commented lines.
-\end{itemize}
-
--- /dev/null
+<sect1>Release notes for version~2.08---10/97
+<label id="release-2-08">
+<p>
+
+GHC 2.08 is a minor upgrade of GHC 2.07, and is released as source only. It represents work done through September '97.
+
+Here's a list of the changes made since GHC 2.07:
+
+<itemize>
+
+<item> removed deforester from source tree, including the @{-# DEFOREST #-}@
+ pragma. This stuff didn't work anymore, so there was no point
+ leaving it hanging around. If someone wants to pick it up again,
+ the source can be checked out of the repository.
+
+<item> documentation is now built automatically for binary distributions
+
+<item> fixed several bugs affecting binary distributions.
+
+<item> fixed bug in Regex.lhs causing random segmentation faults.
+
+<item> a couple of changes to the simplifier means that binary sizes should
+ be (very slightly) smaller.
+
+<item> fixed a problem with error messages not being as accurate as they used to
+ be.
+
+<item> fixed a problem with ticky-ticky profiling (symptom: compiling modules
+ with -ticky gave lots of parse errors from the C compiler).
+
+<item> added support for @unmapMiddleStackPage@ on cygwin32.
+
+<item> fixed a divide-by-zero problem in the GC statistics code.
+
+</itemize>
+
+The following changes were made to Happy:
+
+<itemize>
+<item> bug fixed in state generation.
+
+<item> happy now reports the number of unused rules and terminals in the
+ grammar, and lists which ones are unused in the info file.
+
+<item> happy now tries to avoid generating fully overlapped patterns.
+
+<item> bug fixed in lexer: line numbers weren't being counted for @--@
+ commented lines.
+</itemize>
+
+++ /dev/null
-Changes made since 2.08:
-
-\begin{itemize}
-\item fixed type-synonym-arity bug in the typechecker.
-
-\item fixed overloaded-constructor-argument bug in the typechecker.
-
-\item fix off-by-one error in @PackedString:filterPS@.
-
-\item fixed @getCurrentDirectory@.
-
-\item fixed space-leak bug to do with polymorphic recursion and overloading.
-
-\item fixed lit-deatify that was core dumping on Linux.
-
-\item some fixes to the native code generator for i386.
-
-\item unboxed the state in ST and IO, and specialised IO (it is no longer built
- on top of ST).
-
-\item reversed the sense of @-fwarn-{overlapped,incomplete}-patterns@.
- The driver now has to have the flag to provide the warning.
-
-\item added @-fwarn-missing-methods@.
-
-\item added the @-Wnot@, @-W@, and @-Wall@ options. Set up a default
- set of warnings, namely @-fwarn-{overlapped,incomplete}-patterns@.
-
-\item Added @-fwarn-duplicate-exports@ warning to check for duplicates in
- export lists. Included in default warning set.
-
-\item Renamed @SampleVar.{write,read}Sample@ to
- @SampleVar.{write,read}SampleVar@.
-
-\item new @mkdependHS@ options: @-W@ disables warnings of duplicate interface
- files found along the import path. @--include-prelude@ *will* generate
- dependencies on Prelude + any prelude/syslib .hi files used.
-
-\item removed the @PrimIO@ type. For a limited time only, @PrimIO@
- will be available from @GlaExts@ as a synonym for @IO@.
-
-\item changed the type of @_ccall_@s to return @(IO a)@.
-
-\item renamed @mainPrimIO@ to @mainIO@, as it now has type @IO ()@.
-
-\item fixed the semantics of the @-i@ flag to @mkdependHS@ to be the
- same as GHC.
-
-\item fix panic when a type constructor is used as a class.
-
-\item don't arbitrarily truncate cost centre names in profiling information.
-\end{itemize}
-
-In 2.09, we've made extensive changes to the libraries that provide
-access to various GHC extensions. Many of these extensions are now
-provided by Hugs, and as a result we are now using a common set of
-extension libraries.
-
-Briefly, the changes are as follows (for the definition of the new
-libraries, see the section on GHC/Hugs libraries in the User Guide).
-
-\begin{itemize}
-\item @Addr@ moved out of @Foreign@ and into its own module.
-
-\item @MutVar@ module disappeared, @IOExts@ now exports @IORefs@ and
- associated operations.
-
-\item The @CCallable@ and @CReturnable@ classes now have their own
- module, @CCall@. You only need to import this module to provide a
- new instance of one of these classes.
-
-\item A new module @IOExts@ provides extensions to the @IO@ monad,
- including @unsafePerformIO@, @unsafeInterleaveIO@, @IORef@s (mutable
- variables), and @IOArray@s (mutable arrays).
-
-\item Importing @ST@ is now the official way to get access to the @ST@
- monad. This module also supports @STRef@s (mutable variables) and
- @STArray@s (mutable arrays).
-
-\item A new module @LazyST@ provides an identical interface to @ST@
- except that the underlying implementation of the monad is lazy. Be
- careful about mixing these two in the same program.
-
-\item The new module @Bits@ provides a class of bit operations. The
- modules @Int@ and @Word@ provide signed and unsiged integer types
- (respectively) of varying sizes, all of which support bit
- operations.
-
-\item Added @Bits@, @Int@, @Word@ (and a few new primops over words).
-
-\item The @GlaExts@ module will provide Glasgow-only extensions. For
- now, we've kept the old interface for compatibility, but beware that
- this is deprecated and the relevant extension libraries should be
- imported explicitly.
-
-\item Several changes to the libraries in @lib/ghc@ - see the User
- Guide for details.
-\end{itemize}
--- /dev/null
+<sect1>Release notes for version~2.09---11/97
+<label id="release-2-09">
+<p>
+
+Changes made since 2.08:
+
+<itemize>
+<item> fixed type-synonym-arity bug in the typechecker.
+
+<item> fixed overloaded-constructor-argument bug in the typechecker.
+
+<item> fix off-by-one error in @PackedString:filterPS@.
+
+<item> fixed @getCurrentDirectory@.
+
+<item> fixed space-leak bug to do with polymorphic recursion and overloading.
+
+<item> fixed lit-deatify that was core dumping on Linux.
+
+<item> some fixes to the native code generator for i386.
+
+<item> unboxed the state in ST and IO, and specialised IO (it is no longer built
+ on top of ST).
+
+<item> reversed the sense of @-fwarn-{overlapped,incomplete}-patterns@.
+ The driver now has to have the flag to provide the warning.
+
+<item> added @-fwarn-missing-methods@.
+
+<item> added the @-Wnot@, @-W@, and @-Wall@ options. Set up a default
+ set of warnings, namely @-fwarn-{overlapped,incomplete}-patterns@.
+
+<item> Added @-fwarn-duplicate-exports@ warning to check for duplicates in
+ export lists. Included in default warning set.
+
+<item> Renamed @SampleVar.{write,read}Sample@ to
+ @SampleVar.{write,read}SampleVar@.
+
+<item> new @mkdependHS@ options: @-W@ disables warnings of duplicate interface
+ files found along the import path. @--include-prelude@ *will* generate
+ dependencies on Prelude + any prelude/syslib .hi files used.
+
+<item> removed the @PrimIO@ type. For a limited time only, @PrimIO@
+ will be available from @GlaExts@ as a synonym for @IO@.
+
+<item> changed the type of @_ccall_@s to return @(IO a)@.
+
+<item> renamed @mainPrimIO@ to @mainIO@, as it now has type @IO ()@.
+
+<item> fixed the semantics of the @-i@ flag to @mkdependHS@ to be the
+ same as GHC.
+
+<item> fix panic when a type constructor is used as a class.
+
+<item> don't arbitrarily truncate cost centre names in profiling information.
+</itemize>
+
+In 2.09, we've made extensive changes to the libraries that provide
+access to various GHC extensions. Many of these extensions are now
+provided by Hugs, and as a result we are now using a common set of
+extension libraries.
+
+Briefly, the changes are as follows (for the definition of the new
+libraries, see the section on GHC/Hugs libraries in the User Guide).
+
+<itemize>
+<item> @Addr@ moved out of @Foreign@ and into its own module.
+
+<item> @MutVar@ module disappeared, @IOExts@ now exports @IORefs@ and
+ associated operations.
+
+<item> The @CCallable@ and @CReturnable@ classes now have their own
+ module, @CCall@. You only need to import this module to provide a
+ new instance of one of these classes.
+
+<item> A new module @IOExts@ provides extensions to the @IO@ monad,
+ including @unsafePerformIO@, @unsafeInterleaveIO@, @IORef@s (mutable
+ variables), and @IOArray@s (mutable arrays).
+
+<item> Importing @ST@ is now the official way to get access to the @ST@
+ monad. This module also supports @STRef@s (mutable variables) and
+ @STArray@s (mutable arrays).
+
+<item> A new module @LazyST@ provides an identical interface to @ST@
+ except that the underlying implementation of the monad is lazy. Be
+ careful about mixing these two in the same program.
+
+<item> The new module @Bits@ provides a class of bit operations. The
+ modules @Int@ and @Word@ provide signed and unsiged integer types
+ (respectively) of varying sizes, all of which support bit
+ operations.
+
+<item> Added @Bits@, @Int@, @Word@ (and a few new primops over words).
+
+<item> The @GlaExts@ module will provide Glasgow-only extensions. For
+ now, we've kept the old interface for compatibility, but beware that
+ this is deprecated and the relevant extension libraries should be
+ imported explicitly.
+
+<item> Several changes to the libraries in @lib/ghc@ - see the User
+ Guide for details.
+</itemize>
+++ /dev/null
-Changes made since 2.09:
-
-\begin{itemize}
-
-\item export some missing operations from @ST@/@LazyST@.
-
-\item remove wired-in @runST@ from the compiler, move @runST@ from
-@STBase@ to @UnsafeST@ and give it a type signature. Fix a bug in the
-compiler to do with universal quantification so this actually works.
-
-\item fix cut-n-paste-o in @PosixUtils.lhs@.
-
-\item better code for checking for overlapping(incomplete?) patterns.
-
-\item @-fwarn-simple-patterns@ for pattern-bindings that could fail.
-
-\item win32 green-card stubs imported.
-
-\item fix 'make carries on after errors' problem {\em again}.
-
-\item driver fixed to be perl4 compatible again.
-
-\item obscure happy bug fixed.
-
-\item @Word@ removed from hbc library to avoid conflicts.
-
-\item lots of fixes to the binary distribution system - you can now do
-@gmake binary-dist Project=Happy@ from the top-level and get a Happy
-binary distribution. GHC binary distributions no longer contain
-Happy.
-
-\item add some suffix rules for SGML, we can use SGML-Tools for
-documentation now.
-
-\item added an new manual for Happy, in SGML format.
-
-\item added the GHC/Hugs extension library documentation as a separate
-document, and removed that information from the Users' Guide.
-
-\item Fixed a bug where ':::' wasn't being parsed properly in interface files.
-
-\item Fixed a long-standing bug in the strictness analyser.
-
-\item Fixed the cause of the @getWorkerIdAndCons@ panic.
-
-\item Moved the array tests from ghc/lib into the test framework.
-ghc/lib/tests now doesn't exist.
-
-\end{itemize}
--- /dev/null
+<sect1>Release notes for version~2.10---12/97
+<label id="release-2-10">
+<p>
+
+Changes made since 2.09:
+
+<itemize>
+
+<item> export some missing operations from @ST@/@LazyST@.
+
+<item> remove wired-in @runST@ from the compiler, move @runST@ from
+@STBase@ to @UnsafeST@ and give it a type signature. Fix a bug in the
+compiler to do with universal quantification so this actually works.
+
+<item> fix cut-n-paste-o in @PosixUtils.lhs@.
+
+<item> better code for checking for overlapping(incomplete?) patterns.
+
+<item> @-fwarn-simple-patterns@ for pattern-bindings that could fail.
+
+<item> win32 green-card stubs imported.
+
+<item> fix 'make carries on after errors' problem <em>again</em>.
+
+<item> driver fixed to be perl4 compatible again.
+
+<item> obscure happy bug fixed.
+
+<item> @Word@ removed from hbc library to avoid conflicts.
+
+<item> lots of fixes to the binary distribution system - you can now do
+@gmake binary-dist Project=Happy@ from the top-level and get a Happy
+binary distribution. GHC binary distributions no longer contain
+Happy.
+
+<item> add some suffix rules for SGML, we can use SGML-Tools for
+documentation now.
+
+<item> added an new manual for Happy, in SGML format.
+
+<item> added the GHC/Hugs extension library documentation as a separate
+document, and removed that information from the Users' Guide.
+
+<item> Fixed a bug where ':::' wasn't being parsed properly in interface files.
+
+<item> Fixed a long-standing bug in the strictness analyser.
+
+<item> Fixed the cause of the @getWorkerIdAndCons@ panic.
+
+<item> Moved the array tests from ghc/lib into the test framework.
+ghc/lib/tests now doesn't exist.
+
+</itemize>
--- /dev/null
+<sect1>Release notes for version~3-00---1/97
+<label id="release-3-00">
+<p>
+
+Changes made since 2.10:
+
+<itemize>
+
+<item> Multi-parameter type classes are fully implemented. There is more
+ sharing of dictionaries than in 2.10, so there's a chance that
+ efficiency will increase a little too.
+
+<item> Error messages from the type checker should be noticeably improved
+
+<item> Warnings for unused bindings @-fwarn-unused-names@.
+
+<item> The "boing" example works, and many other minor bug fixes.
+
+<item> Can only be built with 2.10 or later; committed to Haskell 1.4
+ module system and libraries. Much cruft removed as a result.
+
+<item> Dramatic clean-up of the @PprStyle@ stuff. No explicit "sty"
+parameters now; it's all handled under the hood in @Outputable.lhs@.
+
+<item> The type @Type@ has been substantially changed. Usage types have
+ gone away entirely. Type is parameterised wrt the "flexi" slot
+ in type variables, rather than wrt the type variable itself.
+ That means that many instance decls become much simpler, because
+ they are polymorphic in the "flexi" slot rather than needing
+ (say) @Outputable@ on the type variable.
+
+<item> The dictionary for each class is represented by a new
+ data type for that purpose, rather than by a tuple. That in
+ turn means that @Type@ can be a straightforward instance of @Eq@ and
+ @Ord@ No need for @eqSimpleTy@, @eqTy@.
+
+<item> The resulting compiler is just slightly (2%) shorter than the
+ old one in terms of source code size.
+
+<item> Fix bug in posix signal handling.
+
+<item> @Int@ and @Word@ rewritten to use unboxed types and operations.
+
+<item> Removed @ghc/Error.{lhs,hi-boot}@
+
+<item> Moved contents of @Error@ to @GHCerr@ + adjusted
+ import lists of files that use old Error functionality.
+
+<item> Moved @seqError@ from @Prelude@ to @GHCerr@.
+
+<item> Fix a misleading type checker error msg.
+
+<item> Fix a bug in @floatBind@ in @Simplify.lhs@
+
+<item> Better failure message when entering an unimplemented instance method
+
+</itemize>
--- /dev/null
+<sect1>Release notes for version~3-01---2/97
+<label id="release-3-01">
+<p>
+
+Changes made since 3.00:
+
+<itemize>
+
+<item> Fix interaction of "hiding" on import with "module M" on export.
+
+<item> Fix some floating point conversion problems in @floatExtreme.lc@.
+
+</itemize>
TOP = ../..
include $(TOP)/mk/boilerplate.mk
-DOC_SRCS = user.lit
-SRC_TEXI2HTML_OPTS += -number -monolithic -invisible xbm
-
ifeq "$(BIN_DIST)" "1"
install :: html dvi info
endif
+# These files are just concatenated to produce the complete document, in the
+# same order as they are given below.
+
+SGML_SRCS = \
+ user.sgml \
+ intro.sgml \
+ using.sgml \
+ runtime_control.sgml \
+ profiling.sgml \
+ debugging.sgml \
+ sooner.sgml \
+ lang.sgml \
+ glasgow_exts.sgml \
+ parallel.sgml \
+ vs_haskell.sgml \
+ libraries.sgml \
+ posix.sgml \
+ libmisc.sgml \
+ gone_wrong.sgml \
+ utils.sgml \
+ end.sgml
+
+# release.sgml \
+# 3-00-notes.sgml \
+# 2-10-notes.sgml \
+# 2-09-notes.sgml \
+# 2-08-notes.sgml \
+# 2-06-notes.sgml \
+# 2-04-notes.sgml \
+# 2-03-notes.sgml \
+# 2-02-notes.sgml \
+# how_to_run.sgml \
+
+SGML_DOC = users_guide
+
include $(TOP)/mk/target.mk
+++ /dev/null
-%************************************************************************
-%* *
-\section[backwards]{Backwards compatibility: Converting from GHC 0.xx and Haskell~1.2}
-\index{GHC vs the Haskell 1.2 language}
-\index{Haskell 1.2 language vs GHC}
-%* *
-%************************************************************************
-
-This part of the guide is to help people upgrading from a
-previous version of GHC. Right now, it is mostly to help people
-switching from GHC~0.29 (a Haskell~1.2 compiler, mostly) to GHC~2.xx
-(a Haskell~1.4 compiler).
-
-%ToDo: index
-
-If you need to maintain Haskell code that will work for multiple
-versions of GHC, you can use the \tr{-cpp} flag and the
-\tr{__GLASGOW_HASKELL__} pre-processor variable.
-
-For example, in GHC~0.29, \tr{__GLASGOW_HASKELL__} will be 29; for~2.04,
-it will be 204. Thus, you can write:
-\begin{verbatim}
-#if __HASKELL1__ <= 2
-main = appendChan stdout "Hello, world!\n" exit done -- 1.2
-#else
-# if __GLASGOW_HASKELL__ >= 200
-import IO
-main = putStr "Hello, world!" -- real 1.3
-# else
-main = putStr "Hello, world!\n" -- pseudo-1.3 in 0.2x
-# endif
-#endif
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsection{Types}
-%* *
-%************************************************************************
-
-A big new thing in Haskell~1.3 is constructor classes. Humble old functions
-such as @map@ now have an exciting new type:
-\begin{verbatim}
-map :: Functor f => (a->b) -> f a -> f b
-\end{verbatim}
-These new overloadings, expecially where it's the type constructor
-that's overloaded (as in @map@) can give rise to some puzzling error
-messages. For example:
-\begin{code}
- lookupColor :: String -> [(String, (a, b, c))] -> (a, b, c)
- lookupColor colorName colorTable =
- head [(r,g,b) | (c,(r,g,b)) <- colorTable, c == map toLower colorName]
-\end{code}
-With the type signature this is fine, but if you omit the type signature
-you'll get:
-\begin{verbatim}
- "Color.hs", line 49: No instance for: Prelude.Eq (a{-a18d-} Prelude.Char)
- "Color.hs", line 49:
- at a use of an overloaded identifier: `Prelude.meth.Prelude.Eq.=='
-\end{verbatim}
-@map@ no longer says that @colorName@ has to be a list; it could
-be any type of the form (t @Char@). Unfortunately, lookupColor has to
-take equality over these (t @Char@) things, so it gets stuck trying to figure
-out how to resolve (@Eq@ (t @Char@)) when it knows nothing about t.
-
-The solution to such messages is to add type signatures.
-
-%************************************************************************
-%* *
-\subsection{Lexical matters}
-%* *
-%************************************************************************
-
-Old uses of `compose' (\tr{(.)}) can magically turn into qualified
-names; e.g., \tr{LiteralInt.leStringToInt}; add spaces.
-
-Leading-underscore names (a Glasgow extension) don't work anymore,
-even with \tr{-fglasgow-exts}.
-
-The \tr{Prelude.lex} function doesn't grok Haskell comments any more
-(a good simplification, but a change nonetheless).
-
-%************************************************************************
-%* *
-\subsection{Expressions and patterns}
-%* *
-%************************************************************************
-
-You used to be able to define non-binary functions in a pseudo-infix-y
-say; e.g., \tr{(a `op` b) c = ...}. Illegal now.
-
-New keyword: \tr{do}. Any old variables named \tr{do} will now cause
-syntax errors.
-
-%************************************************************************
-%* *
-\subsection{Converting @Dialogue@ I/O}
-%* *
-%************************************************************************
-
-In most cases, it's really easy to convert from Haskell~1.2's I/O to
-the monadic I/O of Haskell~1.3.
-
-\begin{enumerate}
-\item
-The type \tr{Dialogue} usually can become \tr{IO ()}.
-\item
-Change \tr{readChan stdin} to \tr{getContents}.
-\item
-Change \tr{appendChan stdout} to \tr{putStr}, which is equivalent to
-\tr{hPutStr stdout}.
-Change \tr{appendChan stderr} to \tr{hPutStr stderr}.
-\item
-You need to \tr{import IO} to do any interesting I/O; in particular,
-anything to do with @Handle@s.
-\item
-You need to \tr{import System} if you used @getArgs@, @getEnv@,
-or @getProgName@.
-\item
-Assuming continuation-style @Dialogue@ code, change \tr{... exit done $}
-to \tr{... >>}. Change \tr{... exit $ \ foo ->} to \tr{... >>= \ foo ->}.
-\item
-Sometimes, when you change your \tr{main} routine to ``do'' notation,
-you'll get an error message like:
-\begin{verbatim}
-"Main.hs", line 32: No instance for: Prelude.MonadZero IO
- "Main.hs", line 32: in a do statement
-\end{verbatim}
-This probably means that you need to ``twiddle'' some patterns; e.g.,
-I added the twiddle to the \tr{getArgs}-related pattern here:
-\begin{verbatim}
-main = do
- ~[a1] <- getArgs
- let x = fst (head ((reads::ReadS Int) a1)
- putStr (show (result x))
-\end{verbatim}
-\item
-If you had any functions named \tr{(>>)}, \tr{(>>=)}, or \tr{return},
-change them to something else.
-\item
-If you used the \tr{StatusFile} I/O request, do something else. No
-exact equivalent exists in 1.3.
-\end{enumerate}
-
-%************************************************************************
-%* *
-\subsection{Converting from pre-1.3 monadic I/O}
-%* *
-%************************************************************************
-
-GHC~0.29 supported an early DRAFT of the Haskell~1.3 monadic I/O
-facilities. Inevitably, what Really Made It into 1.3 is not quite
-what was in the draft.
-
-What was called \tr{handle} in the draft is now called \tr{catch}.
-
-The type of the function \tr{fail} changed between draft and real-thing.
-Old: \tr{fail x}; new: \tr{fail (userError x)}.
-Also, what used to be \tr{failWith x} is now just \tr{fail x}.
-
-All the system modules named \tr{LibSomething} dropped the \tr{Lib}.
-So: \tr{LibSystem} is now just \tr{System}.
-
-As of 2.09, GHC doesn't have @PrimIO@, and all @_ccall_@s now return
-type @IO a@, where @a@ is the return type of the @_ccall_@ itself.
-
-The \tr{IOError} type is now abstract; you cannot see it's
-constructors. 1.3 provides functions to query errors.
-
-%************************************************************************
-%* *
-\subsection{Use of the standard Prelude}
-%* *
-%************************************************************************
-
-As with any previous Prelude/standard-modules changes, if you have
-top-level functions that name-clash with imported entities, you'll get
-compiler errors. So, for example, if your code defines a function
-called \tr{seq} (entirely cool in Haskell~1.2), you will now get a
-compiler error because there is now a Prelude entity called \tr{seq}.
-(You may, of course, \tr{import Prelude hiding (seq)}, if you wish).
-
-Names that frequently clash with new Prelude names:
-\tr{fail},
-\tr{lookup},
-\tr{seq}.
-
-Add \tr{import Ratio} if you use \tr{Rationals} at all.
-Ditto: \tr{import Complex} if you use complex numbers.
-Ditto: \tr{import Array} if you use arrays.
-
-As suggested above, any \tr{LibXXX} system modules are now just
-\tr{XXX}.
-
-Also: note that
-Arrays now use ordinary pairs, rather than a separate \tr{Assoc} type.
-In some modules, we've found it easier to do:
-\begin{verbatim}
-infix 1 =:
-(=:) a b = (a,b)
-\end{verbatim}
-and globally replace @:=@ with @=:@.
-Works fine for expressions; useless for patterns, however.
-
-For \tr{minInt}/\tr{maxInt} and \tr{minChar}/\tr{maxChar},
-use the \tr{Bounded} class methods, \tr{minBound} and \tr{maxBound}.
-
-Replace class \tr{Text} with \tr{Show}; on rare occasions,
-you may need to do something for \tr{Read}, too.
-
-The functions \tr{ord} and \tr{chr} have been replaced by
-the class methods \tr{fromEnum} and \tr{toEnum}, respectively.
-The changes, however, can lead to ambiguous overloading.
-
-The functions \tr{even} and \tr{odd} used to be methods of class
-@Integral@. They are now ordinary, overloaded functions.
-
-The \tr{print} function now appends a newline to its output. This is
-good, but different.
-
-\tr{readDec} no longer exists; use \tr{(reads::ReadS Int)}, or similar.
-
-If you relied on \tr{take}, \tr{drop}, \tr{splitAt}, etc., being
-overloaded, you will need to switch to \tr{genericTake},
-\tr{genericDrop}, etc., (imported from \tr{List}).
-
-%************************************************************************
-%* *
-\subsection{The module system}
-%* *
-%************************************************************************
-
-GHC~2.04 is fussier than 0.29 about junk in import lists. This is a
-feature.
-
-\tr{Foo..} (in export lists) must be changed to \tr{module Foo}.
-
-Type synonyms may be imported/exported with or without \tr{(..)}---it
-was required in Haskell~1.2--but you get a warning if you do it with.
-
-%************************************************************************
-%* *
-\subsection{Use of Glasgow extensions}
-%* *
-%************************************************************************
-
-Leading-underscore names are {\em gone}. Simon hated them.
-
-To get access to GHC innards, you will need to import system modules
-with names of the form \tr{GHCxxx}. We plan to restrict access to
-such interfaces in the future; and, of course, we reserve the right to
-make horrible changes to \tr{GHC*} modules....
-
-You can't dig around inside the @ST@/@IO@ monads quite so freely.
-
-The old \tr{PreludePrimIO} interface is DEAD.
-
-The even-older \tr{PreludeGlaIO} interface is DEADER.
-
-@returnPrimIO@, @thenPrimIO@, and @seqPrimIO@ are deprecated. You
-were warned.
-
-@foldrPrimIO@ has died.
-
-@_FILE@, @fclose@, @fdopen@, @fflush@, @fopen@, @fread@, @freopen@,
-and @fwrite@ are dead.
-
-@appendChanPrimIO@, @appendFilePrimIO@, @getArgsPrimIO@, and
-@readChanPrimIO@ are dead (as previously warned).
-
-The \tr{LibPosix} stuff didn't make it into 1.3 I/O, so it has become
-a ``system library'' (\tr{-syslib posix}). Other than dropping the
-\tr{Lib*} prefix, everything should be the same as in 0.29.
-
-As of GHC 2.09, @mainPrimIO@ is now called @mainIO@, to reflect the
-fact that @PrimIO@ doesn't exist anymore. If you want to provide your
-own @mainIO@ routine, it must be in a module @GHCmain@, not @Main@.
--- /dev/null
+%************************************************************************
+%* *
+<sect1>Debugging the compiler
+<label id="options-debugging">
+<p>
+<nidx>debugging options (for GHC)</nidx>
+%* *
+%************************************************************************
+
+HACKER TERRITORY. HACKER TERRITORY.
+(You were warned.)
+
+%----------------------------------------------------------------------
+<sect2>Replacing the program for one or more phases.
+<label id="replacing-phases">
+<p>
+<nidx>GHC phases, changing</nidx>
+<nidx>phases, changing GHC</nidx>
+
+You may specify that a different program
+be used for one of the phases of the compilation system, in place of
+whatever the driver @ghc@ has wired into it. For example, you
+might want to try a different assembler. The
+@-pgm<phase-code><program-name>@<nidx>-pgm<phase><stuff> option</nidx> option to
+@ghc@ will cause it to use @<program-name>@ for phase
+@<phase-code>@, where the codes to indicate the phases are:
+
+<tabular ca="ll">
+<bf>code</bf> | <bf>phase</bf> @@
+@@
+L | literate pre-processor @@
+P | C pre-processor (if -cpp only) @@
+C | Haskell compiler @@
+c | C compiler@@
+a | assembler @@
+l | linker @@
+</tabular>
+
+%----------------------------------------------------------------------
+<sect2>Forcing options to a particular phase.
+<label id="forcing-options-through">
+<p>
+<nidx>forcing GHC-phase options</nidx>
+
+The preceding sections describe driver options that are mostly
+applicable to one particular phase. You may also <em>force</em> a
+specific option @<option>@ to be passed to a particular phase
+@<phase-code>@ by feeding the driver the option
+@-opt<phase-code><option>@.<nidx>-opt<phase><stuff> option</nidx> The
+codes to indicate the phases are the same as in the previous section.
+
+So, for example, to force an @-Ewurble@ option to the assembler, you
+would tell the driver @-opta-Ewurble@ (the dash before the E is
+required).
+
+Besides getting options to the Haskell compiler with @-optC<blah>@,
+you can get options through to its runtime system with
+@-optCrts<blah>@<nidx>-optCrts<blah> option</nidx>.
+
+So, for example: when I want to use my normal driver but with my
+profiled compiler binary, I use this script:
+<tscreen><verb>
+#! /bin/sh
+exec /local/grasp_tmp3/simonpj/ghc-BUILDS/working-alpha/ghc/driver/ghc \
+ -pgmC/local/grasp_tmp3/simonpj/ghc-BUILDS/working-hsc-prof/hsc \
+ -optCrts-i0.5 \
+ -optCrts-PT \
+ "$@"
+</verb></tscreen>
+
+%----------------------------------------------------------------------
+<sect2>Dumping out compiler intermediate structures
+<label id="dumping-output">
+<p>
+<nidx>dumping GHC intermediates</nidx>
+<nidx>intermediate passes, output</nidx>
+
+<descrip>
+<tag>@-noC@:</tag>
+<nidx>-noC option</nidx>
+Don't bother generating C output <em>or</em> an interface file. Usually
+used in conjunction with one or more of the @-ddump-*@ options; for
+example: @ghc -noC -ddump-simpl Foo.hs@
+
+<tag>@-hi@:</tag>
+<nidx>-hi option</nidx>
+<em>Do</em> generate an interface file. This would normally be used in
+conjunction with @-noC@, which turns off interface generation;
+thus: @-noC -hi@.
+
+<tag>@-dshow-passes@:</tag>
+<nidx>-dshow-passes option</nidx>
+Prints a message to stderr as each pass starts. Gives a warm but
+undoubtedly misleading feeling that GHC is telling you what's
+happening.
+
+<tag>@-ddump-<pass>@:</tag>
+<nidx>-ddump-<pass> options</nidx>
+Make a debugging dump after pass @<pass>@ (may be common enough to
+need a short form...). Some of the most useful ones are:
+
+<tabular ca="ll">
+@-ddump-rdr@ | reader output (earliest stuff in the compiler) @@
+@-ddump-rn@ | renamer output @@
+@-ddump-tc@ | typechecker output @@
+@-ddump-deriv@ | derived instances @@
+@-ddump-ds@ | desugarer output @@
+@-ddump-simpl@ | simplifer output (Core-to-Core passes) @@
+@-ddump-stranal@ | strictness analyser output @@
+@-ddump-occur-anal@ | `occurrence analysis' output @@
+@-ddump-spec@ | dump specialisation info @@
+@-ddump-stg@ | output of STG-to-STG passes @@
+@-ddump-absC@ | <em>un</em>flattened Abstract~C @@
+@-ddump-flatC@ | <em>flattened</em> Abstract~C @@
+@-ddump-realC@ | same as what goes to the C compiler @@
+@-ddump-asm@ | assembly language from the native-code generator @@
+</tabular>
+
+<nidx>-ddump-rdr option</nidx>%
+<nidx>-ddump-rn option</nidx>%
+<nidx>-ddump-tc option</nidx>%
+<nidx>-ddump-deriv option</nidx>%
+<nidx>-ddump-ds option</nidx>%
+<nidx>-ddump-simpl option</nidx>%
+<nidx>-ddump-stranal option</nidx>%
+<nidx>-ddump-occur-anal option</nidx>%
+<nidx>-ddump-spec option</nidx>%
+<nidx>-ddump-stg option</nidx>%
+<nidx>-ddump-absC option</nidx>%
+<nidx>-ddump-flatC option</nidx>%
+<nidx>-ddump-realC option</nidx>%
+<nidx>-ddump-asm option</nidx>
+
+%For any other @-ddump-*@ options: consult the source, notably
+%@ghc/compiler/main/CmdLineOpts.lhs@.
+
+<tag>@-dverbose-simpl@ and @-dverbose-stg@:</tag>
+<nidx>-dverbose-simpl option</nidx>
+<nidx>-dverbose-stg option</nidx>
+Show the output of the intermediate Core-to-Core and STG-to-STG
+passes, respectively. (<em>Lots</em> of output!) So: when we're
+really desperate:
+<tscreen><verb>
+% ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
+</verb></tscreen>
+
+<tag>@-dppr-{user,debug,all@}:</tag>
+<nidx>-dppr-user option</nidx>
+<nidx>-dppr-debug option</nidx>
+<nidx>-dppr-all option</nidx>
+Debugging output is in one of several ``styles.'' Take the printing
+of types, for example. In the ``user'' style, the compiler's internal
+ideas about types are presented in Haskell source-level syntax,
+insofar as possible. In the ``debug'' style (which is the default for
+debugging output), the types are printed in the most-often-desired
+form, with explicit foralls, etc. In the ``show all'' style, very
+verbose information about the types (e.g., the Uniques on the
+individual type variables) is displayed.
+
+<tag>@-ddump-raw-asm@:</tag>
+<nidx>-ddump-raw-asm option</nidx>
+Dump out the assembly-language stuff, before the ``mangler'' gets it.
+
+<tag>@-ddump-rn-trace@:</tag>
+<nidx>-ddump-rn-trace</nidx>
+Make the renamer be *real* chatty about what it is upto.
+
+<tag>@-dshow-rn-stats@:</tag>
+<nidx>-dshow-rn-stats</nidx>
+Print out summary of what kind of information the renamer had to bring
+in.
+<tag>@-dshow-unused-imports@:</tag>
+<nidx>-dshow-unused-imports</nidx>
+Have the renamer report what imports does not contribute.
+
+%
+%<tag>@-dgc-debug@:</tag>
+%<nidx>-dgc-debug option</nidx>
+%Enables some debugging code related to the garbage-collector.
+</descrip>
+
+%ToDo: -ddump-asm-insn-counts
+%-ddump-asm-globals-info
+
+%----------------------------------------------------------------------
+<sect2>How to read Core syntax (from some @-ddump-*@ flags)
+<p>
+<nidx>reading Core syntax</nidx>
+<nidx>Core syntax, how to read</nidx>
+
+Let's do this by commenting an example. It's from doing
+@-ddump-ds@ on this code:
+<tscreen><verb>
+skip2 m = m : skip2 (m+2)
+</verb></tscreen>
+
+Before we jump in, a word about names of things. Within GHC,
+variables, type constructors, etc., are identified by their
+``Uniques.'' These are of the form `letter' plus `number' (both
+loosely interpreted). The `letter' gives some idea of where the
+Unique came from; e.g., @_@ means ``built-in type variable'';
+@t@ means ``from the typechecker''; @s@ means ``from the
+simplifier''; and so on. The `number' is printed fairly compactly in
+a `base-62' format, which everyone hates except me (WDP).
+
+Remember, everything has a ``Unique'' and it is usually printed out
+when debugging, in some form or another. So here we go...
+
+<tscreen><verb>
+Desugared:
+Main.skip2{-r1L6-} :: _forall_ a$_4 =>{{Num a$_4}} -> a$_4 -> [a$_4]
+
+--# `r1L6' is the Unique for Main.skip2;
+--# `_4' is the Unique for the type-variable (template) `a'
+--# `{{Num a$_4}}' is a dictionary argument
+
+_NI_
+
+--# `_NI_' means "no (pragmatic) information" yet; it will later
+--# evolve into the GHC_PRAGMA info that goes into interface files.
+
+Main.skip2{-r1L6-} =
+ /\ _4 -> \ d.Num.t4Gt ->
+ let {
+ {- CoRec -}
+ +.t4Hg :: _4 -> _4 -> _4
+ _NI_
+ +.t4Hg = (+{-r3JH-} _4) d.Num.t4Gt
+
+ fromInt.t4GS :: Int{-2i-} -> _4
+ _NI_
+ fromInt.t4GS = (fromInt{-r3JX-} _4) d.Num.t4Gt
+
+--# The `+' class method (Unique: r3JH) selects the addition code
+--# from a `Num' dictionary (now an explicit lamba'd argument).
+--# Because Core is 2nd-order lambda-calculus, type applications
+--# and lambdas (/\) are explicit. So `+' is first applied to a
+--# type (`_4'), then to a dictionary, yielding the actual addition
+--# function that we will use subsequently...
+
+--# We play the exact same game with the (non-standard) class method
+--# `fromInt'. Unsurprisingly, the type `Int' is wired into the
+--# compiler.
+
+ lit.t4Hb :: _4
+ _NI_
+ lit.t4Hb =
+ let {
+ ds.d4Qz :: Int{-2i-}
+ _NI_
+ ds.d4Qz = I#! 2#
+ } in fromInt.t4GS ds.d4Qz
+
+--# `I# 2#' is just the literal Int `2'; it reflects the fact that
+--# GHC defines `data Int = I# Int#', where Int# is the primitive
+--# unboxed type. (see relevant info about unboxed types elsewhere...)
+
+--# The `!' after `I#' indicates that this is a *saturated*
+--# application of the `I#' data constructor (i.e., not partially
+--# applied).
+
+ skip2.t3Ja :: _4 -> [_4]
+ _NI_
+ skip2.t3Ja =
+ \ m.r1H4 ->
+ let { ds.d4QQ :: [_4]
+ _NI_
+ ds.d4QQ =
+ let {
+ ds.d4QY :: _4
+ _NI_
+ ds.d4QY = +.t4Hg m.r1H4 lit.t4Hb
+ } in skip2.t3Ja ds.d4QY
+ } in
+ :! _4 m.r1H4 ds.d4QQ
+
+ {- end CoRec -}
+ } in skip2.t3Ja
+</verb></tscreen>
+
+(``It's just a simple functional language'' is an unregisterised
+trademark of Peyton Jones Enterprises, plc.)
+
+%----------------------------------------------------------------------
+<sect2>Command line options in source files
+<label id="source-file-options">
+<p>
+<nidx>source-file options</nidx>
+
+Sometimes it is useful to make the connection between a source file
+and the command-line options it requires quite tight. For instance,
+if a (Glasgow) Haskell source file uses @casm@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
+@Makefile@ (using the @-#include@ command-line option), it is
+possible to do this directly in the source file using the @OPTIONS@
+pragma <nidx>OPTIONS pragma</nidx>:
+
+<tscreen><verb>
+{-# OPTIONS -#include "foo.h" #-}
+module X where
+
+...
+</verb></tscreen>
+
+@OPTIONS@ pragmas are only looked for at the top of your source
+files, upto the first (non-literate,non-empty) line not containing
+@OPTIONS@. Multiple @OPTIONS@ pragmas are recognised. Note
+that your command shell does not get to the source file options, they
+are just included literally in the array of command-line arguments
+the compiler driver maintains internally, so you'll be desperately
+disappointed if you try to glob etc. inside @OPTIONS@.
+
+NOTE: the contents of OPTIONS are prepended to the command-line
+options, so you *do* have the ability to override OPTIONS settings
+via the command line.
+
+It is not recommended to move all the contents of your Makefiles into
+your source files, but in some circumstances, the @OPTIONS@ pragma
+is the Right Thing. (If you use @-keep-hc-file-too@ and have OPTION
+flags in your module, the OPTIONS will get put into the generated .hc
+file).
+
+%----------------------------------------------------------------------
+<sect2>How to compile mutually recursive modules
+<p>
+<nidx>module system, recursion</nidx>
+
+Currently, the compiler does not have proper support for dealing with
+mutually recursive modules:
+
+<tscreen><verb>
+module A where
+
+import B
+
+newtype A = A Int
+
+f :: B -> A
+f (B x) = A x
+--------
+module B where
+
+import A
+
+data B = B !Int
+
+g :: A -> B
+g (A x) = B x
+</verb></tscreen>
+
+When compiling either module A and B, the compiler will try (in vain)
+to look for the interface file of the other. So, to get mutually
+recursive modules off the ground, you need to hand write an interface
+file for A or B, so as to break the loop. For the example at hand, the
+boot interface file for A would like the following:
+
+<tscreen><verb>
+_interface_ A 1
+_exports_
+A A(A) f;
+_declarations_
+1 newtype A = A PrelBase.Int ;
+1 f _:_ B.B -> A.A ;;
+</verb></tscreen>
+
+To make sure you get the syntax right, tailoring an existing interface
+file is a Good Idea.
+
+<bf>Note:</bf> This is all a temporary solution, a version of the
+compiler that handles mutually recursive properly without the manual
+construction of interface file, is in the works.
--- /dev/null
+% document trailer for user guide.
+
+</article>
+++ /dev/null
-%************************************************************************
-%* *
-\section[glasgow-exts]{Glasgow extensions to Haskell}
-\index{Haskell, Glasgow extensions}
-\index{extensions, Glasgow Haskell}
-%* *
-%************************************************************************
-
-As with all known Haskell systems, GHC implements some extensions to
-the language.
-To use them, you'll need to give
-a \tr{-fglasgow-exts}%
-\index{-fglasgow-exts option} option.
-
-Virtually all of the Glasgow extensions serve to give you access to the
-underlying facilities with which we implement Haskell. Thus, you can
-get at the Raw Iron, if you are willing to write some non-standard
-code at a more primitive level. You need not be ``stuck'' on
-performance because of the implementation costs of Haskell's
-``high-level'' features---you can always code ``under'' them. In an
-extreme case, you can write all your time-critical code in C, and then
-just glue it together with Haskell!
-
-Executive summary of our extensions:
-\begin{description}
-\item[Unboxed types and primitive operations:] You can get right down
-to the raw machine types and operations; included in this are
-``primitive arrays'' (direct access to Big Wads of Bytes).
-Please see \Sectionref{glasgow-unboxed} and following.
-
-\item[Calling out to C:] Just what it sounds like. We provide {\em
-lots} of rope that you can dangle around your neck.
-Please see \Sectionref{glasgow-ccalls}.
-
-\item[``HBC-ish'' extensions:] Extensions implemented because people said,
-``HBC does Y. Could you teach GHC to do the same?'' Please see
-\Sectionref{glasgow-hbc-exts} for a quick list.
-\end{description}
-
-Before you get too carried away working at the lowest level (e.g.,
-sloshing \tr{MutableByteArray#}s around your program), you may wish to
-check if there are system libraries that provide a ``Haskellised
-veneer'' over the features you want. See \Sectionref{syslibs}.
-
-\Sectionref{ghc-prelude} is the definitive guide for many of the
-low-level facilities in GHC.
-
-%************************************************************************
-%* *
-\subsection[glasgow-unboxed]{Unboxed types}
-\index{Unboxed types (Glasgow extension)}
-%* *
-%************************************************************************
-
-These types correspond to the ``raw machine'' types you would use in
-C: \tr{Int#} (long int), \tr{Double#} (double),
-\tr{Addr#} (void *), etc. The {\em primitive
-operations} (PrimOps) on these types are what you might expect; e.g.,
-\tr{(+#)} is addition on \tr{Int#}s, and is the machine-addition that
-we all know and love---usually one instruction.
-
-A numerically-intensive program using unboxed types can go a {\em lot}
-faster than its ``standard'' counterpart---we saw a threefold speedup
-on one example.
-
-Please see \Sectionref{ghc-libs-ghc} for the details of
-unboxed types and the operations on them.
-
-%************************************************************************
-%* *
-\subsection[glasgow-ST-monad]{Primitive state-transformer monad}
-\index{state transformers (Glasgow extensions)}
-\index{ST monad (Glasgow extension)}
-%* *
-%************************************************************************
-
-This monad underlies our implementation of arrays, mutable and immutable,
-and our implementation of I/O, including ``C calls''.
-
-You probably won't use the monad directly, but you might use all those
-other things!
-
-More information on the state-related types can be found in the
-elsewhere, \Sectionref{ghc-prelude}.
-
-%************************************************************************
-%* *
-\subsection[glasgow-prim-arrays]{Primitive arrays, mutable and otherwise}
-\index{primitive arrays (Glasgow extension)}
-\index{arrays, primitive (Glasgow extension)}
-%* *
-%************************************************************************
-
-GHC knows about quite a few flavours of Large Swathes of Bytes.
-
-First, GHC distinguishes between primitive arrays of (boxed) Haskell
-objects (type \tr{Array# obj}) and primitive arrays of bytes (type
-\tr{ByteArray#}).
-
-Second, it distinguishes between...
-\begin{description}
-\item[Immutable:]
-Arrays that do not change (as with ``standard'' Haskell arrays); you
-can only read from them. Obviously, they do not need the care and
-attention of the state-transformer monad.
-
-\item[Mutable:]
-Arrays that may be changed or ``mutated.'' All the operations on them
-live within the state-transformer monad and the updates happen {\em
-in-place}.
-
-\item[``Static'' (in C land):]
-A C~routine may pass an \tr{Addr#} pointer back into Haskell land.
-There are then primitive operations with which you may merrily grab
-values over in C land, by indexing off the ``static'' pointer.
-
-\item[``Stable'' pointers:]
-If, for some reason, you wish to hand a Haskell pointer (i.e., {\em
-not} an unboxed value) to a C~routine, you first make the pointer
-``stable,'' so that the garbage collector won't forget that it exists.
-That is, GHC provides a safe way to pass Haskell pointers to C.
-
-Please see \Sectionref{glasgow-stablePtrs} for more details.
-
-\item[``Foreign objects'':]
-A ``foreign object'' is a safe way to pass an external object (a
-C~allocated pointer, say) to Haskell and have Haskell do the Right
-Thing when it no longer references the object. So, for example, C
-could pass a large bitmap over to Haskell and say ``please free this
-memory when you're done with it.''
-
-Please see \Sectionref{glasgow-foreignObjs} for more details.
-\end{description}
-
-The libraries section give more details on all these
-``primitive array'' types and the operations on them,
-\Sectionref{ghc-prelude}.
-
-
-%************************************************************************
-%* *
-\subsection[own-mainIO]{Using your own @mainIO@}
-\index{mainIO, rolling your own}
-\index{GHCmain, module containing mainIO}
-%* *
-%************************************************************************
-
-Normally, the GHC runtime system begins things by called an internal
-function
-
-\begin{verbatim}
- mainIO :: IO ()
-\end{verbatim}
-
-\noindent which, in turn, fires up your @Main.main@. The standard
-definition of @mainIO@ looks like this:
-
-\begin{verbatim}
- mainIO = catch Main.main
- (\err -> error ("I/O error: " ++
- showsPrec 0 err "\n"))
-\end{verbatim}
-
-\noindent that is, all it does is run @Main.main@, catching any I/O
-errors that occur and displaying them on standard error before exiting
-the program.
-
-To subvert the above process, you need only provide a @mainIO@ of your
-own (in a module named \tr{GHCmain}).
-
-Here's a little example, stolen from Alastair Reid:
-
-\begin{verbatim}
- module GHCmain ( mainIO ) where
-
- import GlaExts
-
- mainIO :: IO ()
- mainIO = do
- sleep 5
- _ccall_ printf "%d\n" (14::Int)
-
- sleep :: Int -> IO ()
- sleep t = _ccall_ sleep t
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsection[glasgow-ccalls]{Calling~C directly from Haskell}
-\index{C calls (Glasgow extension)}
-\index{_ccall_ (Glasgow extension)}
-\index{_casm_ (Glasgow extension)}
-%* *
-%************************************************************************
-
-GOOD ADVICE: Because this stuff is not Entirely Stable as far as names
-and things go, you would be well-advised to keep your C-callery
-corraled in a few modules, rather than sprinkled all over your code.
-It will then be quite easy to update later on.
-
-WARNING AS OF 2.03: Yes, the \tr{_ccall_} stuff probably {\em will
-change}, to something better, of course! One step in that direction
-is Green Card, a foreign function interface pre-processor for Haskell
-(``Glasgow'' Haskell in particular) --- check out
-\begin{verbatim}
-ftp://ftp.dcs.gla.ac.uk/pub/haskell/glasgow/green-card.ANNOUNCE
-ftp://ftp.dcs.gla.ac.uk/pub/haskell/glasgow/green-card-src.tar.gz
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsubsection[ccall-intro]{\tr{_ccall_} and \tr{_casm_}: an introduction}
-%* *
-%************************************************************************
-
-The simplest way to use a simple C function
-\begin{verbatim}
-double fooC( FILE *in, char c, int i, double d, unsigned int u )
-\end{verbatim}
-is to provide a Haskell wrapper:
-\begin{verbatim}
-fooH :: Char -> Int -> Double -> Word -> IO Double
-fooH c i d w = _ccall_ fooC (``stdin''::Addr) c i d w
-\end{verbatim}
-The function @fooH@ will unbox all of its arguments, call the C
-function \tr{fooC} and box the corresponding arguments.
-
-One of the annoyances about \tr{_ccall_}s is when the C types don't quite
-match the Haskell compiler's ideas. For this, the \tr{_casm_} variant
-may be just the ticket (NB: {\em no chance} of such code going through
-a native-code generator):
-\begin{verbatim}
-oldGetEnv name
- = _casm_ ``%r = getenv((char *) %0);'' name >>= \ litstring@(A# str#) ->
- return (
- if (litstring == ``NULL'') then
- Left ("Fail:oldGetEnv:"++name)
- else
- Right (unpackCString# str#)
- )
-\end{verbatim}
-
-The first literal-literal argument to a \tr{_casm_} is like a
-\tr{printf} format: \tr{%r} is replaced with the ``result,''
-\tr{%0}--\tr{%n-1} 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 \tr{_ccall_} goes for \tr{_casm_} as well.
-
-%************************************************************************
-%* *
-\subsubsection[glasgow-foreign-headers]{Using function headers}
-\index{C calls, function headers}
-%* *
-%************************************************************************
-
-When generating C (using the \tr{-fvia-C} directive), one can assist
-the C compiler in detecting type errors by using the \tr{-#include}
-directive to provide \tr{.h} files containing function headers.
-
-For example,
-\begin{verbatim}
-typedef unsigned long *StgForeignObj;
-typedef long StgInt;
-
-void initialiseEFS (StgInt size);
-StgInt terminateEFS (void);
-StgForeignObj emptyEFS(void);
-StgForeignObj updateEFS (StgForeignObj a, StgInt i, StgInt x);
-StgInt lookupEFS (StgForeignObj a, StgInt i);
-\end{verbatim}
-
-You can find appropriate definitions for \tr{StgInt},
-\tr{StgForeignObj}, etc using \tr{gcc} on your architecture by
-consulting \tr{ghc/includes/StgTypes.lh}. The following table
-summarises the relationship between Haskell types and C types.
-
-\begin{tabular}{ll}
-C type name & Haskell Type \\ \hline
-%----- & ---------------
-\tr{StgChar} & \tr{Char#}\\
-\tr{StgInt} & \tr{Int#}\\
-\tr{StgWord} & \tr{Word#}\\
-\tr{StgAddr} & \tr{Addr#}\\
-\tr{StgFloat} & \tr{Float#}\\
-\tr{StgDouble} & \tr{Double#}\\
-
-\tr{StgArray} & \tr{Array#}\\
-\tr{StgByteArray} & \tr{ByteArray#}\\
-\tr{StgArray} & \tr{MutableArray#}\\
-\tr{StgByteArray} & \tr{MutableByteArray#}\\
-
-\tr{StgStablePtr} & \tr{StablePtr#}\\
-\tr{StgForeignObj} & \tr{ForeignObj#}
-\end{tabular}
-
-Note that this approach is only {\em essential\/} for returning
-\tr{float}s (or if \tr{sizeof(int) != sizeof(int *)} on your
-architecture) but is a Good Thing for anyone who cares about writing
-solid code. You're crazy not to do it.
-
-%************************************************************************
-%* *
-\subsubsection[glasgow-stablePtrs]{Subverting automatic unboxing with ``stable pointers''}
-\index{stable pointers (Glasgow extension)}
-%* *
-%************************************************************************
-
-The arguments of a \tr{_ccall_} are automatically unboxed before the
-call. There are two reasons why this is usually the Right Thing to do:
-\begin{itemize}
-\item
-C is a strict language: it would be excessively tedious to pass
-unevaluated arguments and require the C programmer to force their
-evaluation before using them.
-
-\item Boxed values are stored on the Haskell heap and may be moved
-within the heap if a garbage collection occurs---that is, pointers
-to boxed objects are not {\em stable\/}.
-\end{itemize}
-
-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 \tr{storeC} and
-\tr{fetchC}, one might write:
-\begin{verbatim}
-storeH :: Int -> IO ()
-storeH x = makeStablePtr x >>= \ stable_x ->
- _ccall_ storeC stable_x
-
-fetchH :: IO Int
-fetchH x = _ccall_ fetchC >>= \ stable_x ->
- deRefStablePtr stable_x >>= \ x ->
- freeStablePtr stable_x >>
- return x
-\end{verbatim}
-
-The garbage collector will refrain from throwing a stable pointer away
-until you explicitly call one of the following from C or Haskell.
-\begin{verbatim}
-void freeStablePointer( StgStablePtr stablePtrToToss )
-freeStablePtr :: StablePtr a -> IO ()
-\end{verbatim}
-
-As with the use of \tr{free} 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.
-
-And to force evaluation of the argument within \tr{fooC}, one would
-call one of the following C functions (according to type of argument).
-
-\begin{verbatim}
-void performIO ( StgStablePtr stableIndex /* StablePtr s (IO ()) */ );
-StgInt enterInt ( StgStablePtr stableIndex /* StablePtr s Int */ );
-StgFloat enterFloat ( StgStablePtr stableIndex /* StablePtr s Float */ );
-\end{verbatim}
-
-\index{performIO, call a haskell IO computation from C}
-\index{enterInt, call a haskell function from C}
-\index{enterFloat, call a haskell function from C}
-
-% ToDo ADR: test these functions!
-
-Note Bene: \tr{_ccall_GC_} must be used if any of these functions are used.
-
-
-%************************************************************************
-%* *
-\subsubsection[glasgow-foreignObjs]{Pointing outside the Haskell heap}
-\index{foreign objects (Glasgow extension)}
-%* *
-%************************************************************************
-
-There are two types that \tr{ghc} programs can use to reference
-(heap-allocated) objects outside the Haskell world: \tr{Addr} and
-\tr{ForeignObj}.
-
-If you use \tr{Addr}, it is up to you to the programmer to arrange
-allocation and deallocation of the objects.
-
-If you use \tr{ForeignObj}, \tr{ghc}'s garbage collector will
-call upon the user-supplied {\em finaliser} 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
- Haskell type @ForeignObj@ is created). The finaliser function is
-expressed in C, and is passed as argument the object:
-
-\begin{verbatim}
-void foreignFinaliser ( StgForeignObj fo )
-\end{verbatim}
-when the Haskell world can no longer access the object. Since
-\tr{ForeignObj}s only get released when a garbage collection occurs,
-we provide ways of triggering a garbage collection from within C and
-from within Haskell.
-\begin{verbatim}
-void StgPerformGarbageCollection()
-performGC :: IO ()
-\end{verbatim}
-
-More information is provided on the programmers' interface to
-@ForeignObj@ can be found in Section \ref{sec:foreign-obj}.
-
-%************************************************************************
-%* *
-\subsubsection[glasgow-avoiding-monads]{Avoiding monads}
-\index{C calls to `pure C'}
-\index{unsafePerformIO}
-%* *
-%************************************************************************
-
-The \tr{_ccall_} construct is part of the \tr{IO} monad because 9 out
-of 10 uses will be to call imperative functions with side effects such
-as \tr{printf}. Use of the monad ensures that these operations happen
-in a predictable order in spite of laziness and compiler
-optimisations.
-
-To avoid having to be in the monad to call a C function, it is
-possible to use @unsafePerformIO@, which is available from the
-@IOExts@ module. There are three situations where one might like to
-call a C function from outside the IO world:
-
-\begin{itemize}
-\item
-Calling a function with no side-effects:
-\begin{verbatim}
-atan2d :: Double -> Double -> Double
-atan2d y x = unsafePerformIO (_ccall_ atan2d y x)
-
-sincosd :: Double -> (Double, Double)
-sincosd x = unsafePerformIO $ do
- da <- newDoubleArray (0, 1)
- _casm_ ``sincosd( %0, &((double *)%1[0]), &((double *)%1[1]) );'' x da
- s <- readDoubleArray da 0
- c <- readDoubleArray da 1
- return (s, c)
-\end{verbatim}
-
-\item Calling a set of functions which have side-effects but which can
-be used in a purely functional manner.
-
-For example, an imperative implementation of a purely functional
-lookup-table might be accessed using the following functions.
-
-\begin{verbatim}
-empty :: EFS x
-update :: EFS x -> Int -> x -> EFS x
-lookup :: EFS a -> Int -> a
-
-empty = unsafePerformIO (_ccall_ emptyEFS)
-
-update a i x = unsafePerformIO $
- makeStablePtr x >>= \ stable_x ->
- _ccall_ updateEFS a i stable_x
-
-lookup a i = unsafePerformIO $
- _ccall_ lookupEFS a i >>= \ stable_x ->
- deRefStablePtr stable_x
-\end{verbatim}
-
-You will almost always want to use \tr{ForeignObj}s with this.
-
-\item Calling a side-effecting function even though the results will
-be unpredictable. For example the \tr{trace} function is defined by:
-
-\begin{verbatim}
-trace :: String -> a -> a
-trace string expr
- = unsafePerformIO (
- ((_ccall_ PreTraceHook sTDERR{-msg-}):: IO ()) >>
- fputs sTDERR string >>
- ((_ccall_ PostTraceHook sTDERR{-msg-}):: IO ()) >>
- return expr )
- where
- sTDERR = (``stderr'' :: Addr)
-\end{verbatim}
-
-(This kind of use is not highly recommended --- it is only really
-useful in debugging code.)
-\end{itemize}
-
-%************************************************************************
-%* *
-\subsubsection[ccall-gotchas]{C-calling ``gotchas'' checklist}
-\index{C call dangers}
-%* *
-%************************************************************************
-
-And some advice, too.
-
-\begin{itemize}
-\item For modules that use \tr{_ccall_}s, etc., compile with
-\tr{-fvia-C}.\index{-fvia-C option} You don't have to, but you should.
-
-Also, use the \tr{-#include "prototypes.h"} flag (hack) to inform the
-C compiler of the fully-prototyped types of all the C functions you
-call. (\Sectionref{glasgow-foreign-headers} says more about this...)
-
-This scheme is the {\em only} way that you will get {\em any}
-typechecking of your \tr{_ccall_}s. (It shouldn't be that way,
-but...)
-
-\item
-Try to avoid \tr{_ccall_}s to C~functions that take \tr{float}
-arguments or return \tr{float} results. Reason: if you do, you will
-become entangled in (ANSI?) C's rules for when arguments/results are
-promoted to \tr{doubles}. It's a nightmare and just not worth it.
-Use \tr{doubles} if possible.
-
-If you do use \tr{floats}, check and re-check that the right thing is
-happening. Perhaps compile with \tr{-keep-hc-file-too} and look at
-the intermediate C (\tr{.hc} file).
-
-\item The compiler uses two non-standard type-classes when
-type-checking the arguments and results of \tr{_ccall_}: the arguments
-(respectively result) of \tr{_ccall_} must be instances of the class
-\tr{CCallable} (respectively \tr{CReturnable}). Both classes may be
-imported from the module @CCall@, but this should only be necessary if
-you want to define a new instance. (Neither class defines any methods
---- their only function is to keep the type-checker happy.)
-
-The type checker must be able to figure out just which of the
-C-callable/returnable types is being used. If it can't, you have to
-add type signatures. For example,
-\begin{verbatim}
-f x = _ccall_ foo x
-\end{verbatim}
-is not good enough, because the compiler can't work out what type @x@ is, nor
-what type the @_ccall_@ returns. You have to write, say:
-\begin{verbatim}
-f :: Int -> IO Double
-f x = _ccall_ foo x
-\end{verbatim}
-
-This table summarises the standard instances of these classes.
-
-% ToDo: check this table against implementation!
-
-\begin{tabular}{llll}
-Type &CCallable&CReturnable & Which is probably... \\ \hline
-%------ ---------- ------------ -------------
-\tr{Char} & Yes & Yes & \tr{unsigned char} \\
-\tr{Int} & Yes & Yes & \tr{long int} \\
-\tr{Word} & Yes & Yes & \tr{unsigned long int} \\
-\tr{Addr} & Yes & Yes & \tr{char *} \\
-\tr{Float} & Yes & Yes & \tr{float} \\
-\tr{Double} & Yes & Yes & \tr{double} \\
-\tr{()} & No & Yes & \tr{void} \\
-\tr{[Char]} & Yes & No & \tr{char *} (null-terminated) \\
-
-\tr{Array} & Yes & No & \tr{unsigned long *}\\
-\tr{ByteArray} & Yes & No & \tr{unsigned long *}\\
-\tr{MutableArray} & Yes & No & \tr{unsigned long *}\\
-\tr{MutableByteArray} & Yes & No & \tr{unsigned long *}\\
-
-\tr{State} & Yes & Yes & nothing!\\
-
-\tr{StablePtr} & Yes & Yes & \tr{unsigned long *}\\
-\tr{ForeignObjs} & Yes & Yes & see later\\
-\end{tabular}
-
-The brave and careful programmer can add their own instances of these
-classes for the following types:
-\begin{itemize}
-\item
-A {\em boxed-primitive} type may be made an instance of both
-\tr{CCallable} and \tr{CReturnable}.
-
-A boxed primitive type is any data type with a
-single unary constructor with a single primitive argument. For
-example, the following are all boxed primitive types:
-
-\begin{verbatim}
-Int
-Double
-data XDisplay = XDisplay Addr#
-data EFS a = EFS# ForeignObj#
-\end{verbatim}
-
-\begin{verbatim}
-instance CCallable (EFS a)
-instance CReturnable (EFS a)
-\end{verbatim}
-
-\item Any datatype with a single nullary constructor may be made an
-instance of \tr{CReturnable}. For example:
-
-\begin{verbatim}
-data MyVoid = MyVoid
-instance CReturnable MyVoid
-\end{verbatim}
-
-\item As at version 2.09, \tr{String} (i.e., \tr{[Char]}) is still
-not a \tr{CReturnable} type.
-
-Also, the now-builtin type \tr{PackedString} is neither
-\tr{CCallable} nor \tr{CReturnable}. (But there are functions in
-the PackedString interface to let you get at the necessary bits...)
-\end{itemize}
-
-\item
-The code-generator will complain if you attempt to use \tr{%r}
-in a \tr{_casm_} whose result type is \tr{IO ()}; or if you don't
-use \tr{%r} {\em precisely\/} once for any other result type. These
-messages are supposed to be helpful and catch bugs---please tell us
-if they wreck your life.
-
-\item If you call out to C code which may trigger the Haskell garbage
-collector (examples of this later...), then you must use the
-\tr{_ccall_GC_}\index{_ccall_GC_ primitive} or
-\tr{_casm_GC_}\index{_casm_GC_ primitive} variant of C-calls. (This
-does not work with the native code generator - use \tr{\fvia-C}.) This
-stuff is hairy with a capital H! \end{itemize}
-
-%************************************************************************
-%* *
-\subsection[glasgow-hbc-exts]{``HBC-ish'' extensions implemented by GHC}
-\index{HBC-like Glasgow extensions}
-\index{extensions, HBC-like}
-%* *
-%************************************************************************
-
-\begin{description}
-%-------------------------------------------------------------------
-\item[@fromInt@ method in class @Num@:]
-It's there. Converts from an \tr{Int} to the type.
-
-%-------------------------------------------------------------------
-\item[@toInt@ method in class @Integral@:]
-Converts from type type to an \tr{Int}.
-
-%-------------------------------------------------------------------
-\item[Overlapping instance declarations:]
-\index{overlapping instances}
-\index{instances, overlapping}
-
-In \tr{instance <context> => Class (T x1 ... xn)}, the \tr{xi}s can be
-{\em types}, rather than just {\em type variables}.
-
-Thus, you can have an instance \tr{instance Foo [Char]}, as well as
-the more general \tr{instance Foo [a]}; the former will be used in
-preference to the latter, where applicable.
-
-As Lennart says, ``This is a dubious feature and should not be used
-carelessly.''
-
-See also: \tr{SPECIALIZE instance} pragmas, in \Sectionref{faster}.
-\end{description}
--- /dev/null
+%
+% $Id: glasgow_exts.vsgml,v 1.1 1998/01/30 17:02:18 simonm Exp $
+%
+% GHC Language Extensions.
+%
+
+As with all known Haskell systems, GHC implements some extensions to
+the language. To use them, you'll need to give a @-fglasgow-exts@%
+<nidx>-fglasgow-exts option</nidx> option.
+
+Virtually all of the Glasgow extensions serve to give you access to
+the underlying facilities with which we implement Haskell. Thus, you
+can get at the Raw Iron, if you are willing to write some non-standard
+code at a more primitive level. You need not be ``stuck'' on
+performance because of the implementation costs of Haskell's
+``high-level'' features---you can always code ``under'' them. In an
+extreme case, you can write all your time-critical code in C, and then
+just glue it together with Haskell!
+
+Executive summary of our extensions:
+
+<descrip>
+
+<tag>Unboxed types and primitive operations:</tag>
+
+You can get right down to the raw machine types and operations;
+included in this are ``primitive arrays'' (direct access to Big Wads
+of Bytes). Please see Section <ref name="Unboxed types"
+id="glasgow-unboxed"> and following.
+
+<tag>Multi-parameter type classes:</tag>
+
+GHC's type system supports extended type classes with multiple
+parameters. Please see Section <ref name="Mult-parameter type
+classes" id="multi-param-type-classes">.
+
+<tag>Local universal quantification:</tag>
+
+GHC's type system supports explicit unversal quantification in
+constructor fields and function arguments. This is useful for things
+like defining @runST@ from the state-thread world amongst other
+things. See Section <ref name="Local universal quantification"
+id="universal-quantification">.
+
+<tag>Calling out to C:</tag>
+
+Just what it sounds like. We provide <em>lots</em> of rope that you
+can dangle around your neck. Please see Section <ref name="Calling~C
+directly from Haskell" id="glasgow-ccalls">.
+
+</descrip>
+
+Before you get too carried away working at the lowest level (e.g.,
+sloshing @MutableByteArray#@s around your program), you may wish to
+check if there are system libraries that provide a ``Haskellised
+veneer'' over the features you want. See Section <ref name="GHC
+Prelude and libraries" id="ghc-prelude">.
+
+%************************************************************************
+%* *
+<sect1>Unboxed types
+<label id="glasgow-unboxed">
+<p>
+<nidx>Unboxed types (Glasgow extension)</nidx>
+%* *
+%************************************************************************
+
+These types correspond to the ``raw machine'' types you would use in
+C: @Int#@ (long int), @Double#@ (double), @Addr#@ (void *), etc. The
+<em>primitive operations</em> (PrimOps) on these types are what you
+might expect; e.g., @(+#)@ is addition on @Int#@s, and is the
+machine-addition that we all know and love---usually one instruction.
+
+A numerically-intensive program using unboxed types can go a <em>lot</em>
+faster than its ``standard'' counterpart---we saw a threefold speedup
+on one example.
+
+Please see Section <ref name="The module PrelGHC: really primitive
+stuff" id="ghc-libs-ghc"> for the details of unboxed types and the
+operations on them.
+
+%************************************************************************
+%* *
+<sect1>Primitive state-transformer monad
+<label id="glasgow-ST-monad">
+<p>
+<nidx>state transformers (Glasgow extensions)</nidx>
+<nidx>ST monad (Glasgow extension)</nidx>
+%* *
+%************************************************************************
+
+This monad underlies our implementation of arrays, mutable and
+immutable, and our implementation of I/O, including ``C calls''.
+
+The @ST@ library, which provides access to the @ST@ monad, is a
+GHC/Hugs extension library and is described in the separate <htmlurl
+name="GHC/Hugs Extension Libraries" url="libs.html"> document.
+
+%************************************************************************
+%* *
+<sect1>Primitive arrays, mutable and otherwise
+<label id="glasgow-prim-arrays">
+<p>
+<nidx>primitive arrays (Glasgow extension)</nidx>
+<nidx>arrays, primitive (Glasgow extension)</nidx>
+%* *
+%************************************************************************
+
+GHC knows about quite a few flavours of Large Swathes of Bytes.
+
+First, GHC distinguishes between primitive arrays of (boxed) Haskell
+objects (type @Array# obj@) and primitive arrays of bytes (type
+@ByteArray#@).
+
+Second, it distinguishes between...
+<descrip>
+<tag>Immutable:</tag>
+Arrays that do not change (as with ``standard'' Haskell arrays); you
+can only read from them. Obviously, they do not need the care and
+attention of the state-transformer monad.
+
+<tag>Mutable:</tag>
+Arrays that may be changed or ``mutated.'' All the operations on them
+live within the state-transformer monad and the updates happen
+<em>in-place</em>.
+
+<tag>``Static'' (in C land):</tag>
+A C~routine may pass an @Addr#@ pointer back into Haskell land. There
+are then primitive operations with which you may merrily grab values
+over in C land, by indexing off the ``static'' pointer.
+
+<tag>``Stable'' pointers:</tag>
+If, for some reason, you wish to hand a Haskell pointer (i.e.,
+<em>not</em> an unboxed value) to a C~routine, you first make the
+pointer ``stable,'' so that the garbage collector won't forget that it
+exists. That is, GHC provides a safe way to pass Haskell pointers to
+C.
+
+Please see Section <ref name="Subverting automatic unboxing with
+``stable pointers''" id="glasgow-stablePtrs"> for more details.
+
+<tag>``Foreign objects'':</tag>
+A ``foreign object'' is a safe way to pass an external object (a
+C~allocated pointer, say) to Haskell and have Haskell do the Right
+Thing when it no longer references the object. So, for example, C
+could pass a large bitmap over to Haskell and say ``please free this
+memory when you're done with it.''
+
+Please see Section <ref name="Pointing outside the Haskell heap"
+id="glasgow-foreignObjs"> for more details.
+
+</descrip>
+
+The libraries section give more details on all these ``primitive
+array'' types and the operations on them, Section <ref name="The GHC
+Prelude and Libraries" id="ghc-prelude">. Some of these extensions
+are also supported by Hugs, and the supporting libraries are described
+in the <htmlurl name="GHC/Hugs Extension Libraries" url="libs.html">
+document.
+
+%************************************************************************
+%* *
+<sect1>Using your own @mainIO@
+<label id="own-mainIO">
+<p>
+<nidx>mainIO, rolling your own</nidx>
+<nidx>GHCmain, module containing mainIO</nidx>
+%* *
+%************************************************************************
+
+Normally, the GHC runtime system begins things by called an internal
+function
+
+<tscreen><verb>
+ mainIO :: IO ()
+</verb></tscreen>
+
+ which, in turn, fires up your @Main.main@. The standard
+definition of @mainIO@ looks like this:
+
+<tscreen><verb>
+ mainIO = catch Main.main
+ (\err -> error ("I/O error: " ++ show err ++ "\n"))
+</verb></tscreen>
+
+That is, all it does is run @Main.main@, catching any I/O errors that
+occur and displaying them on standard error before exiting the
+program.
+
+To subvert the above process, you need only provide a @mainIO@ of your
+own (in a module named @PrelMain@).
+
+Here's a little example, stolen from Alastair Reid:
+
+<tscreen><verb>
+module GHCmain ( mainIO ) where
+
+import GlaExts
+
+mainIO :: IO ()
+mainIO = do
+ _ccall_ sleep 5
+ _ccall_ printf "%d\n" (14::Int)
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect1>Calling~C directly from Haskell
+<label id="glasgow-ccalls">
+<p>
+<nidx>C calls (Glasgow extension)</nidx>
+<nidx>_ccall_ (Glasgow extension)</nidx>
+<nidx>_casm_ (Glasgow extension)</nidx>
+%* *
+%************************************************************************
+
+GOOD ADVICE: Because this stuff is not Entirely Stable as far as names
+and things go, you would be well-advised to keep your C-callery
+corraled in a few modules, rather than sprinkled all over your code.
+It will then be quite easy to update later on.
+
+WARNING AS OF 2.03: Yes, the @_ccall_@ stuff probably <em>will
+change</em>, to something better, of course! One step in that
+direction is Green Card, a foreign function interface pre-processor
+for Haskell (``Glasgow'' Haskell in particular) --- check out
+
+<tscreen><verb>
+ftp://ftp.dcs.gla.ac.uk/pub/haskell/glasgow/green-card.ANNOUNCE
+ftp://ftp.dcs.gla.ac.uk/pub/haskell/glasgow/green-card-src.tar.gz
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>@_ccall_@ and @_casm_@: an introduction
+<label id="ccall-intro">
+<p>
+%* *
+%************************************************************************
+
+The simplest way to use a simple C function
+
+<tscreen><verb>
+double fooC( FILE *in, char c, int i, double d, unsigned int u )
+</verb></tscreen>
+
+is to provide a Haskell wrapper:
+
+<tscreen><verb>
+fooH :: Char -> Int -> Double -> Word -> IO Double
+fooH c i d w = _ccall_ fooC (``stdin''::Addr) c i d w
+</verb></tscreen>
+
+The function @fooH@ will unbox all of its arguments, call the C
+function @fooC@ and box the corresponding arguments.
+
+One of the annoyances about @_ccall_@s is when the C types don't quite
+match the Haskell compiler's ideas. For this, the @_casm_@ variant
+may be just the ticket (NB: <em>no chance</em> of such code going
+through a native-code generator):
+
+<tscreen><verb>
+oldGetEnv name
+ = _casm_ ``%r = getenv((char *) %0);'' name >>= \ litstring@(A# str#) ->
+ return (
+ if (litstring == ``NULL'') then
+ Left ("Fail:oldGetEnv:"++name)
+ else
+ Right (unpackCString# str#)
+ )
+</verb></tscreen>
+
+The first literal-literal argument to a @_casm_@ is like a @printf@
+format: @%r@ is replaced with the ``result,'' @%0@--@%n-1@ 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 @_ccall_@ goes
+for @_casm_@ as well.
+
+%************************************************************************
+%* *
+<sect2>Using function headers
+<label id="glasgow-foreign-headers">
+<p>
+<nidx>C calls, function headers</nidx>
+%* *
+%************************************************************************
+
+When generating C (using the @-fvia-C@ directive), one can assist the
+C compiler in detecting type errors by using the @-#include@ directive
+to provide @.h@ files containing function headers.
+
+For example,
+
+<tscreen><verb>
+typedef unsigned long *StgForeignObj;
+typedef long StgInt;
+
+void initialiseEFS (StgInt size);
+StgInt terminateEFS (void);
+StgForeignObj emptyEFS(void);
+StgForeignObj updateEFS (StgForeignObj a, StgInt i, StgInt x);
+StgInt lookupEFS (StgForeignObj a, StgInt i);
+</verb></tscreen>
+
+You can find appropriate definitions for @StgInt@, @StgForeignObj@,
+etc using @gcc@ on your architecture by consulting
+@ghc/includes/StgTypes.lh@. The following table summarises the
+relationship between Haskell types and C types.
+
+<tabular ca="ll">
+<bf>C type name</bf> | <bf>Haskell Type</bf> @@
+@@
+@StgChar@ | @Char#@ @@
+@StgInt@ | @Int#@ @@
+@StgWord@ | @Word#@ @@
+@StgAddr@ | @Addr#@ @@
+@StgFloat@ | @Float#@ @@
+@StgDouble@ | @Double#@ @@
+
+@StgArray@ | @Array#@ @@
+@StgByteArray@ | @ByteArray#@ @@
+@StgArray@ | @MutableArray#@ @@
+@StgByteArray@ | @MutableByteArray#@ @@
+
+@StgStablePtr@ | @StablePtr#@ @@
+@StgForeignObj@ | @ForeignObj#@
+</tabular>
+
+Note that this approach is only <em>essential</em> for returning
+@float@s (or if @sizeof(int) != sizeof(int *)@ on your
+architecture) but is a Good Thing for anyone who cares about writing
+solid code. You're crazy not to do it.
+
+%************************************************************************
+%* *
+<sect2>Subverting automatic unboxing with ``stable pointers''
+<label id="glasgow-stablePtrs">
+<p>
+<nidx>stable pointers (Glasgow extension)</nidx>
+%* *
+%************************************************************************
+
+The arguments of a @_ccall_@ are automatically unboxed before the
+call. There are two reasons why this is usually the Right Thing to
+do:
+
+<itemize>
+<item>
+C is a strict language: it would be excessively tedious to pass
+unevaluated arguments and require the C programmer to force their
+evaluation before using them.
+
+<item> Boxed values are stored on the Haskell heap and may be moved
+within the heap if a garbage collection occurs---that is, pointers
+to boxed objects are not <em>stable</em>.
+</itemize>
+
+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 @storeC@ and
+@fetchC@, one might write:
+
+<tscreen><verb>
+storeH :: Int -> IO ()
+storeH x = makeStablePtr x >>= \ stable_x ->
+ _ccall_ storeC stable_x
+
+fetchH :: IO Int
+fetchH x = _ccall_ fetchC >>= \ stable_x ->
+ deRefStablePtr stable_x >>= \ x ->
+ freeStablePtr stable_x >>
+ return x
+</verb></tscreen>
+
+The garbage collector will refrain from throwing a stable pointer away
+until you explicitly call one of the following from C or Haskell.
+
+<tscreen><verb>
+void freeStablePointer( StgStablePtr stablePtrToToss )
+freeStablePtr :: StablePtr a -> IO ()
+</verb></tscreen>
+
+As with the use of @free@ 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.
+
+And to force evaluation of the argument within @fooC@, one would
+call one of the following C functions (according to type of argument).
+
+<tscreen><verb>
+void performIO ( StgStablePtr stableIndex /* StablePtr s (IO ()) */ );
+StgInt enterInt ( StgStablePtr stableIndex /* StablePtr s Int */ );
+StgFloat enterFloat ( StgStablePtr stableIndex /* StablePtr s Float */ );
+</verb></tscreen>
+
+<nidx>performIO</nidx>
+<nidx>enterInt</nidx>
+<nidx>enterFloat</nidx>
+
+% ToDo ADR: test these functions!
+
+Note Bene: @_ccall_GC_@<nidx>_ccall_GC_</nidx> must be used if any of
+these functions are used.
+
+%************************************************************************
+%* *
+<sect2>Pointing outside the Haskell heap
+<label id="glasgow-foreignObjs">
+<p>
+<nidx>foreign objects (Glasgow extension)</nidx>
+%* *
+%************************************************************************
+
+There are two types that @ghc@ programs can use to reference
+(heap-allocated) objects outside the Haskell world: @Addr@ and
+@ForeignObj@.
+
+If you use @Addr@, it is up to you to the programmer to arrange
+allocation and deallocation of the objects.
+
+If you use @ForeignObj@, @ghc@'s garbage collector will call upon the
+user-supplied <em>finaliser</em> 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
+ Haskell type @ForeignObj@ is created). The finaliser function is
+expressed in C, and is passed as argument the object:
+
+<tscreen><verb>
+void foreignFinaliser ( StgForeignObj fo )
+</verb></tscreen>
+
+when the Haskell world can no longer access the object. Since
+@ForeignObj@s only get released when a garbage collection occurs, we
+provide ways of triggering a garbage collection from within C and from
+within Haskell.
+
+<tscreen><verb>
+void StgPerformGarbageCollection()
+performGC :: IO ()
+</verb></tscreen>
+
+More information on the programmers' interface to @ForeignObj@ can be
+found in Section <ref name="Foreign objects" id="sec:foreign-obj">.
+
+%************************************************************************
+%* *
+<sect2>Avoiding monads
+<label id="glasgow-avoiding-monads">
+<p>
+<nidx>C calls to `pure C'</nidx>
+<nidx>unsafePerformIO</nidx>
+%* *
+%************************************************************************
+
+The @_ccall_@ construct is part of the @IO@ monad because 9 out of 10
+uses will be to call imperative functions with side effects such as
+@printf@. Use of the monad ensures that these operations happen in a
+predictable order in spite of laziness and compiler optimisations.
+
+To avoid having to be in the monad to call a C function, it is
+possible to use @unsafePerformIO@, which is available from the
+@IOExts@ module. There are three situations where one might like to
+call a C function from outside the IO world:
+
+<itemize>
+<item>
+Calling a function with no side-effects:
+<tscreen><verb>
+atan2d :: Double -> Double -> Double
+atan2d y x = unsafePerformIO (_ccall_ atan2d y x)
+
+sincosd :: Double -> (Double, Double)
+sincosd x = unsafePerformIO $ do
+ da <- newDoubleArray (0, 1)
+ _casm_ ``sincosd( %0, &((double *)%1[0]), &((double *)%1[1]) );'' x da
+ s <- readDoubleArray da 0
+ c <- readDoubleArray da 1
+ return (s, c)
+</verb></tscreen>
+
+<item> Calling a set of functions which have side-effects but which can
+be used in a purely functional manner.
+
+For example, an imperative implementation of a purely functional
+lookup-table might be accessed using the following functions.
+
+<tscreen><verb>
+empty :: EFS x
+update :: EFS x -> Int -> x -> EFS x
+lookup :: EFS a -> Int -> a
+
+empty = unsafePerformIO (_ccall_ emptyEFS)
+
+update a i x = unsafePerformIO $
+ makeStablePtr x >>= \ stable_x ->
+ _ccall_ updateEFS a i stable_x
+
+lookup a i = unsafePerformIO $
+ _ccall_ lookupEFS a i >>= \ stable_x ->
+ deRefStablePtr stable_x
+</verb></tscreen>
+
+You will almost always want to use @ForeignObj@s with this.
+
+<item> Calling a side-effecting function even though the results will
+be unpredictable. For example the @trace@ function is defined by:
+
+<tscreen><verb>
+trace :: String -> a -> a
+trace string expr
+ = unsafePerformIO (
+ ((_ccall_ PreTraceHook sTDERR{-msg-}):: IO ()) >>
+ fputs sTDERR string >>
+ ((_ccall_ PostTraceHook sTDERR{-msg-}):: IO ()) >>
+ return expr )
+ where
+ sTDERR = (``stderr'' :: Addr)
+</verb></tscreen>
+
+(This kind of use is not highly recommended --- it is only really
+useful in debugging code.)
+</itemize>
+
+%************************************************************************
+%* *
+<sect2>C-calling ``gotchas'' checklist
+<label id="ccall-gotchas">
+<p>
+<nidx>C call dangers</nidx>
+%* *
+%************************************************************************
+
+And some advice, too.
+
+<itemize>
+<item> For modules that use @_ccall_@s, etc., compile with
+@-fvia-C@.<nidx>-fvia-C option</nidx> You don't have to, but you should.
+
+Also, use the @-#include "prototypes.h"@ flag (hack) to inform the C
+compiler of the fully-prototyped types of all the C functions you
+call. (Section <ref name="Using function headers"
+id="glasgow-foreign-headers"> says more about this...)
+
+This scheme is the <em>only</em> way that you will get <em>any</em>
+typechecking of your @_ccall_@s. (It shouldn't be that way,
+but...)
+
+<item>
+Try to avoid @_ccall_@s to C~functions that take @float@
+arguments or return @float@ results. Reason: if you do, you will
+become entangled in (ANSI?) C's rules for when arguments/results are
+promoted to @doubles@. It's a nightmare and just not worth it.
+Use @doubles@ if possible.
+
+If you do use @floats@, check and re-check that the right thing is
+happening. Perhaps compile with @-keep-hc-file-too@ and look at
+the intermediate C (@.hc@ file).
+
+<item> The compiler uses two non-standard type-classes when
+type-checking the arguments and results of @_ccall_@: the arguments
+(respectively result) of @_ccall_@ must be instances of the class
+@CCallable@ (respectively @CReturnable@). Both classes may be
+imported from the module @CCall@, but this should only be
+necessary if you want to define a new instance. (Neither class
+defines any methods --- their only function is to keep the
+type-checker happy.)
+
+The type checker must be able to figure out just which of the
+C-callable/returnable types is being used. If it can't, you have to
+add type signatures. For example,
+
+<tscreen><verb>
+f x = _ccall_ foo x
+</verb></tscreen>
+
+is not good enough, because the compiler can't work out what type @x@
+is, nor what type the @_ccall_@ returns. You have to write, say:
+
+<tscreen><verb>
+f :: Int -> IO Double
+f x = _ccall_ foo x
+</verb></tscreen>
+
+This table summarises the standard instances of these classes.
+
+% ToDo: check this table against implementation!
+
+<tabular ca="llll">
+<bf>Type</bf> |<bf>CCallable</bf>|<bf>CReturnable</bf> | <bf>Which is probably...</bf> @@
+
+@Char@ | Yes | Yes | @unsigned char@ @@
+@Int@ | Yes | Yes | @long int@ @@
+@Word@ | Yes | Yes | @unsigned long int@ @@
+@Addr@ | Yes | Yes | @void *@ @@
+@Float@ | Yes | Yes | @float@ @@
+@Double@ | Yes | Yes | @double@ @@
+@()@ | No | Yes | @void@ @@
+@[Char]@ | Yes | No | @char *@ (null-terminated) @@
+
+@Array@ | Yes | No | @unsigned long *@ @@
+@ByteArray@ | Yes | No | @unsigned long *@ @@
+@MutableArray@ | Yes | No | @unsigned long *@ @@
+@MutableByteArray@ | Yes | No | @unsigned long *@ @@
+
+@State@ | Yes | Yes | nothing!@@
+
+@StablePtr@ | Yes | Yes | @unsigned long *@ @@
+@ForeignObjs@ | Yes | Yes | see later @@
+</tabular>
+
+The brave and careful programmer can add their own instances of these
+classes for the following types:
+
+<itemize>
+<item>
+A <em>boxed-primitive</em> type may be made an instance of both
+@CCallable@ and @CReturnable@.
+
+A boxed primitive type is any data type with a
+single unary constructor with a single primitive argument. For
+example, the following are all boxed primitive types:
+
+<tscreen><verb>
+Int
+Double
+data XDisplay = XDisplay Addr#
+data EFS a = EFS# ForeignObj#
+</verb></tscreen>
+
+<tscreen><verb>
+instance CCallable (EFS a)
+instance CReturnable (EFS a)
+</verb></tscreen>
+
+<item> Any datatype with a single nullary constructor may be made an
+instance of @CReturnable@. For example:
+
+<tscreen><verb>
+data MyVoid = MyVoid
+instance CReturnable MyVoid
+</verb></tscreen>
+
+<item> As at version 2.09, @String@ (i.e., @[Char]@) is still
+not a @CReturnable@ type.
+
+Also, the now-builtin type @PackedString@ is neither
+@CCallable@ nor @CReturnable@. (But there are functions in
+the PackedString interface to let you get at the necessary bits...)
+</itemize>
+
+<item> The code-generator will complain if you attempt to use @%r@ in
+a @_casm_@ whose result type is @IO ()@; or if you don't use @%r@
+<em>precisely</em> once for any other result type. These messages are
+supposed to be helpful and catch bugs---please tell us if they wreck
+your life.
+
+<item> If you call out to C code which may trigger the Haskell garbage
+collector (examples of this later...), then you must use the
+@_ccall_GC_@<nidx>_ccall_GC_ primitive</nidx> or
+@_casm_GC_@<nidx>_casm_GC_ primitive</nidx> variant of C-calls. (This
+does not work with the native code generator - use @\fvia-C@.) This
+stuff is hairy with a capital H! </itemize>
+
+<sect1> Multi-parameter type classes
+<label id="multi-param-type-classes">
+<p>
+
+(ToDo)
+
+<sect1> Local universal quantification
+<label id="universal-quantification">
+<p>
+
+(ToDo)
+++ /dev/null
-%************************************************************************
-%* *
-\section[wrong]{What to do when something goes wrong}
-\index{problems}
-%* *
-%************************************************************************
-
-If you still have a problem after consulting this section, then you
-may have found a {\em bug}---please report it! See
-\Sectionref{bug-reports} for a list of things we'd like to know about
-your bug. If in doubt, send a report---we love mail from irate users :-!
-
-(\Sectionref{vs-Haskell-defn}, which describes Glasgow Haskell's
-shortcomings vs.~the Haskell language definition, may also be of
-interest.)
-
-%************************************************************************
-%* *
-\subsection[wrong-compiler]{When the compiler ``does the wrong thing''}
-\index{compiler problems}
-\index{problems with the compiler}
-%* *
-%************************************************************************
-
-\begin{description}
-%-------------------------------------------------------------------
-\item[``Help! The compiler crashed (or `panic'd)!'']
-These events are {\em always} bugs in the GHC system---please report
-them.
-
-%Known compiler ``panics'':
-%\begin{description}
-%\item[From SPARC native-code generator:] These tend to say something
-%like ``unknown PrimOp;'' you can avoid it by compiling that module
-%with \tr{-fvia-C}.\index{-fvia-C option}
-%\end{description}
-
-%-------------------------------------------------------------------
-\item[``The compiler ran out of heap (or stack) when compiling itself!'']
-It happens. We try to supply reasonable \tr{-H<n>} flags for
-\tr{ghc/compiler/} and \tr{ghc/lib/}, but GHC's memory consumption
-can vary by platform (e.g., on a 64-bit machine).
-
-Just say \tr{make all EXTRA_HC_OPTS=-H<a reasonable number>} and see
-how you get along.
-
-%-------------------------------------------------------------------
-\item[``The compiler died with a pattern-matching error.'']
-This is a bug just as surely as a ``panic.'' Please report it.
-
-%-------------------------------------------------------------------
-% \item[``Some confusion about a value specialised to a type...'' Huh???]
-% (A deeply obscure and unfriendly error message.)
-%
-% This message crops up when the typechecker sees a reference in an
-% interface pragma to a specialisation of an overloaded value
-% (function); for example, \tr{elem} specialised for type \tr{[Char]}
-% (\tr{String}). The problem is: it doesn't {\em know} that such a
-% specialisation exists!
-%
-% The cause of this problem is (please report any other cases...): The
-% compiler has imported pragmatic info for the value in question from
-% more than one interface, and the multiple interfaces did not agree
-% {\em exactly} about the value's pragmatic info. Since the compiler
-% doesn't know whom to believe, it believes none of them.
-%
-% The cure is to re-compile the modules that {\em re-export} the
-% offending value (after possibly re-compiling its defining module).
-% Now the pragmatic info should be exactly the same in every case, and
-% things should be fine.
-
-%-------------------------------------------------------------------
-% \item[``Can't see the data constructors for a ccall/casm'' Huh?]
-% GHC ``unboxes'' C-call arguments and ``reboxes'' C-call results for you.
-% To do this, it {\\em has} to be able to see the types fully;
-% abstract types won't do!
-%
-% Thus, if you say \tr{data Foo = Foo Int#}
-% (a cool ``boxed primitive'' type), but then make it abstract
-% (only \tr{data Foo} appears in the interface), then GHC can't figure
-% out what to do with \tr{Foo} arguments/results to C-calls.
-%
-% Solutions: either make the type unabstract, or compile with \tr{-O}.
-% With the latter, the constructor info will be passed along in
-% the interface pragmas.
-
-%-------------------------------------------------------------------
-\item[``This is a terrible error message.'']
-If you think that GHC could have produced a better error message,
-please report it as a bug.
-
-%-------------------------------------------------------------------
-\item[``What about these `trace' messages from GHC?'']
-Almost surely not a problem. About some specific cases...
-\begin{description}
-\item[Simplifier still going after N iterations:]
-Sad, but harmless. You can change the number with a
-\tr{-fmax-simplifier-iterations<N>}\index{-fmax-simplifier-iterations<N> option} option (no space);
-and you can see what actions took place in each iteration by
-turning on the \tr{-fshow-simplifier-progress}
-\index{-fshow-simplifier-progress option} option.
-
-If the simplifier definitely seems to be ``looping,'' please report
-it.
-\end{description}
-
-%-------------------------------------------------------------------
-\item[``What about this warning from the C compiler?'']
-
-For example: ``...warning: `Foo' declared `static' but never defined.''
-Unsightly, but not a problem.
-
-%-------------------------------------------------------------------
-\item[Sensitivity to \tr{.hi} interface files:]
-
-GHC is very sensitive about interface files. For example, if it picks
-up a non-standard \tr{Prelude.hi} file, pretty terrible things will
-happen. If you turn on
-\tr{-fno-implicit-prelude}\index{-fno-implicit-prelude option}, the
-compiler will almost surely die, unless you know what you are doing.
-
-Furthermore, as sketched below, you may have big problems
-running programs compiled using unstable interfaces.
-
-%-------------------------------------------------------------------
-\item[``I think GHC is producing incorrect code'':]
-
-Unlikely :-) A useful be-more-paranoid option to give to GHC is
-\tr{-dcore-lint}\index{-dcore-lint option}; this causes a ``lint'' pass to
-check for errors (notably type errors) after each Core-to-Core
-transformation pass. We run with \tr{-dcore-lint} on all the time; it
-costs about 5\% in compile time. (Or maybe 25\%; who knows?)
-
-%-------------------------------------------------------------------
-%\item[``Can I use HBC-produced \tr{.hi} interface files?'']
-%Yes, though you should keep compiling until you have a stable set of
-%GHC-produced ones.
-
-%-------------------------------------------------------------------
-\item[``Why did I get a link error?'']
-
-If the linker complains about not finding \tr{_<something>_fast}, then
-your interface files haven't settled---keep on compiling! (In
-particular, this error means that arity information, which you can see
-in any \tr{.hi} file, has changed.)
-
-%If the linker complains about not finding \tr{SpA}, \tr{SuA}, and
-%other such things, then you've tried to link ``unregisterised'' object
-%code (produced with \tr{-O0}) with the normal registerised stuff.
-
-%If you get undefined symbols that look anything like (for example)
-%\tr{J3C_Interact$__writeln}, \tr{C_Prelude$__$2B$2B},
-%\tr{VC_Prelude$__map}, etc., then you are trying to link HBC-produced
-%object files with GHC.
-
-%-------------------------------------------------------------------
-\item[``What's a `consistency error'?'']
-(These are reported just after linking your program.)
-
-You tried to link incompatible object files, e.g., normal ones
-(registerised, Appel garbage-collector) with profiling ones (two-space
-collector). Or those compiled by a previous version of GHC
-with an incompatible newer version.
-
-If you run \tr{nm -o *.o | egrep 't (cc|hsc)\.'} (or, on
-unregisterised files: \tr{what *.o}), you'll see all the consistency
-tags/strings in your object files. They must all be the same!
-(ToDo: tell you what they mean...)
-
-%-------------------------------------------------------------------
-\item[``Is this line number right?'']
-On this score, GHC usually does pretty well, especially
-if you ``allow'' it to be off by one or two. In the case of an
-instance or class declaration, the line number
-may only point you to the declaration, not to a specific method.
-
-Please report line-number errors that you find particularly unhelpful.
-\end{description}
-
-%************************************************************************
-%* *
-\subsection[wrong-compilee]{When your program ``does the wrong thing''}
-\index{problems running your program}
-%* *
-%************************************************************************
-
-(For advice about overly slow or memory-hungry Haskell programs,
-please see \sectionref{sooner-faster-quicker}).
-
-\begin{description}
-%-----------------------------------------------------------------------
-\item[``Help! My program crashed!'']
-(e.g., a `segmentation fault' or `core dumped')
-
-If your program has no @_ccall_@s/@_casm_@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 with a stable
-group of interface (\tr{.hi}) files.
-
-For example, if an interface is lying about the type of an imported
-value then GHC may well generate duff code for the importing module.
-{\em This applies to pragmas inside interfaces too!} If the pragma is
-lying (e.g., about the ``arity'' of a value), then duff code may result.
-Furthermore, arities may change even if types do not.
-
-In short, if you compile a module and its interface changes, then all
-the modules that import that interface {\em must} be re-compiled.
-
-A useful option to alert you when interfaces change is
-\tr{-hi-diffs}\index{-hi-diffs option}. It will run \tr{diff} on the
-changed interface file, before and after, when applicable.
-
-If you are using \tr{make}, a useful tool to make sure that every
-module {\em is} up-to-date with respect to its imported interfaces is
-\tr{mkdependHS} (which comes with GHC). Please see
-\sectionref{mkdependHS}.
-
-If you are down to your last-compile-before-a-bug-report, we
-would recommend that you add a \tr{-dcore-lint} option (for
-extra checking) to your compilation options.
-
-So, before you report a bug because of a core dump, you should probably:
-\begin{verbatim}
-% rm *.o # scrub your object files
-% make my_prog # re-make your program; use -hi-diffs to highlight changes;
- # as mentioned above, use -dcore-lint to be more paranoid
-% ./my_prog ... # retry...
-\end{verbatim}
-
-Of course, if you have @_ccall_@s/@_casm_@s in your program then all bets
-are off, because you can trash the heap, the stack, or whatever.
-
-If you are interested in hard-core debugging of a crashing
-GHC-compiled program, please see \sectionref{hard-core-debug}.
-
-% (If you have an ``unregisterised'' arity-checking
-% (\tr{-O0 -darity-checks}) around [as we sometimes do at Glasgow], then you
-% might recompile with \tr{-darity-checks}\index{-darity-checks option},
-% which will definitely detect arity-compatibility errors.)
-
-%-------------------------------------------------------------------
-\item[``My program entered an `absent' argument.'']
-This is definitely caused by a bug in GHC. Please report it.
-
-%-----------------------------------------------------------------------
-\item[``What's with this `arithmetic (or `floating') exception' ''?]
-
-@Int@, @Float@, and @Double@ arithmetic is {\em unchecked}. Overflows
-and underflows are {\em silent}. Divide-by-zero {\em may} cause an
-untrapped exception (please report it if it does). I suppose other
-arithmetic uncheckiness might cause an exception, too...
-\end{description}
-
-%************************************************************************
-%* *
-\subsection[bug-reports]{How to report a bug in the GHC system}
-\index{bug reports}
-%* *
-%************************************************************************
-
-Glasgow Haskell is a changing system so there are sure to be bugs in
-it. Please report them to
-\tr{glasgow-haskell-bugs@dcs.gla.ac.uk}! (However, please check
-the earlier part of this section to be sure it's not a known
-not-really-a problem.)
-
-The name of the bug-reporting game is: facts, facts, facts.
-Don't omit them because ``Oh, they won't be interested...''
-\begin{enumerate}
-\item
-What kind of machine are you running on, and exactly what version of the
-operating system are you using? (\tr{uname -a} or \tr{cat /etc/motd} will show the desired
-information.)
-
-\item
-What version of GCC are you using? \tr{gcc -v} will tell you.
-
-\item
-Run the sequence of compiles/runs that caused the offending behaviour,
-capturing all the input/output in a ``script'' (a UNIX command) or in
-an Emacs shell window. We'd prefer to see the whole thing.
-
-\item
-Be sure any Haskell compilations are run with a \tr{-v} (verbose)
-flag, so we can see exactly what was run, what versions of things you
-have, etc.
-
-\item
-What is the program behaviour that is wrong, in your opinion?
-
-\item
-If practical, please send enough source files/interface files for us
-to duplicate the problem.
-
-\item
-If you are a Hero and track down the problem in the compilation-system
-sources, please send us {\em whole files} (by e-mail or FTP) that we
-can compare against some base release.
-\end{enumerate}
-
-%************************************************************************
-%* *
-\subsection[hard-core-debug]{Hard-core debugging of GHC-compiled programs}
-\index{debugging, hard-core}
-%* *
-%************************************************************************
-
-If your program is crashing, you should almost surely file a bug
-report, as outlined in previous sections.
-
-This section suggests ways to Make Further Progress Anyway.
-
-The first thing to establish is: Is it a garbage-collection (GC) bug?
-Try your program with a very large heap and a \tr{-Sstderr} RTS
-flag.
-\begin{itemize}
-\item
-If it crashes {\em without} garbage-collecting, then it is
-definitely {\em not} a GC bug.
-\item
-If you can make it crash with one heap size but not with another, then
-it {\em probably is} a GC bug.
-\item
-If it crashes with the normal
-collector, but not when you force two-space collection (\tr{-F2s}
-runtime flag), then it {\em probably is} a GC bug.
-\end{itemize}
-
-If it {\em is} a GC bug, you may be able to avoid it by using a
-particular heap size or by using a \tr{-F2s} runtime flag. (But don't
-forget to report the bug!!!)
-
-ToDo: more here?
--- /dev/null
+%************************************************************************
+%* *
+<sect>What to do when something goes wrong
+<label id="wrong">
+<p>
+<nidx>problems</nidx>
+%* *
+%************************************************************************
+
+If you still have a problem after consulting this section, then you
+may have found a <em>bug</em>---please report it! See
+Section <ref name="How to report a bug in the GHC system" id="bug-reports"> for a list of things we'd like to know about
+your bug. If in doubt, send a report---we love mail from irate users :-!
+
+(Section <ref name="Haskell 1.4 vs. Glasgow Haskell 3.00: language
+non-compliance" id="vs-Haskell-defn">, which describes Glasgow
+Haskell's shortcomings vs.~the Haskell language definition, may also
+be of interest.)
+
+%************************************************************************
+%* *
+<sect1>When the compiler ``does the wrong thing''
+<label id="wrong-compiler">
+<p>
+<nidx>compiler problems</nidx>
+<nidx>problems with the compiler</nidx>
+%* *
+%************************************************************************
+
+<descrip>
+%-------------------------------------------------------------------
+<tag>``Help! The compiler crashed (or `panic'd)!''</tag>
+These events are <em>always</em> bugs in the GHC system---please report
+them.
+
+%-------------------------------------------------------------------
+<tag>``The compiler ran out of heap (or stack) when compiling itself!''</tag>
+It happens. We try to supply reasonable @-H<n>@ flags for
+@ghc/compiler/@ and @ghc/lib/@, but GHC's memory consumption
+can vary by platform (e.g., on a 64-bit machine).
+
+Just say @make all EXTRA_HC_OPTS=-H<a reasonable number>@ and see
+how you get along.
+
+%-------------------------------------------------------------------
+<tag>``The compiler died with a pattern-matching error.''</tag>
+This is a bug just as surely as a ``panic.'' Please report it.
+
+%-------------------------------------------------------------------
+<tag>``This is a terrible error message.''</tag>
+If you think that GHC could have produced a better error message,
+please report it as a bug.
+
+%-------------------------------------------------------------------
+<tag>``What about these `trace' messages from GHC?''</tag>
+Almost surely not a problem. About some specific cases...
+<descrip>
+<tag>Simplifier still going after N iterations:</tag>
+Sad, but harmless. You can change the number with a
+@-fmax-simplifier-iterations<N>@<nidx>-fmax-simplifier-iterations<N> option</nidx> option (no space);
+and you can see what actions took place in each iteration by
+turning on the @-fshow-simplifier-progress@
+<nidx>-fshow-simplifier-progress option</nidx> option.
+
+If the simplifier definitely seems to be ``looping,'' please report
+it.
+</descrip>
+
+%-------------------------------------------------------------------
+<tag>``What about this warning from the C compiler?''</tag>
+
+For example: ``...warning: `Foo' declared `static' but never defined.''
+Unsightly, but not a problem.
+
+%-------------------------------------------------------------------
+<tag>Sensitivity to @.hi@ interface files:</tag>
+
+GHC is very sensitive about interface files. For example, if it picks
+up a non-standard @Prelude.hi@ file, pretty terrible things will
+happen. If you turn on
+@-fno-implicit-prelude@<nidx>-fno-implicit-prelude option</nidx>, the
+compiler will almost surely die, unless you know what you are doing.
+
+Furthermore, as sketched below, you may have big problems
+running programs compiled using unstable interfaces.
+
+%-------------------------------------------------------------------
+<tag>``I think GHC is producing incorrect code'':</tag>
+
+Unlikely :-) A useful be-more-paranoid option to give to GHC is
+@-dcore-lint@<nidx>-dcore-lint option</nidx>; this causes a ``lint''
+pass to check for errors (notably type errors) after each Core-to-Core
+transformation pass. We run with @-dcore-lint@ on all the time; it
+costs about 5\% in compile time. (Or maybe 25\%; who knows?)
+
+%-------------------------------------------------------------------
+<tag>``Why did I get a link error?''</tag>
+
+If the linker complains about not finding @_<something>_fast@, then
+your interface files haven't settled---keep on compiling! (In
+particular, this error means that arity information, which you can see
+in any @.hi@ file, has changed.)
+
+%-------------------------------------------------------------------
+<tag>``What's a `consistency error'?''</tag>
+(These are reported just after linking your program.)
+
+You tried to link incompatible object files, e.g., normal ones
+(registerised, Appel garbage-collector) with profiling ones (two-space
+collector). Or those compiled by a previous version of GHC
+with an incompatible newer version.
+
+If you run @nm -o *.o | egrep 't (cc|hsc)\.'@ (or, on
+unregisterised files: @what *.o@), you'll see all the consistency
+tags/strings in your object files. They must all be the same!
+(ToDo: tell you what they mean...)
+
+%-------------------------------------------------------------------
+<tag>``Is this line number right?''</tag>
+On this score, GHC usually does pretty well, especially
+if you ``allow'' it to be off by one or two. In the case of an
+instance or class declaration, the line number
+may only point you to the declaration, not to a specific method.
+
+Please report line-number errors that you find particularly unhelpful.
+</descrip>
+
+%************************************************************************
+%* *
+<sect1>When your program ``does the wrong thing''
+<label id="wrong-compilee">
+<p>
+<nidx>problems running your program</nidx>
+%* *
+%************************************************************************
+
+(For advice about overly slow or memory-hungry Haskell programs,
+please see Section <ref name="Advice on: sooner, faster, smaller,
+stingier" id="sooner-faster-quicker">).
+
+<descrip>
+%-----------------------------------------------------------------------
+<tag>``Help! My program crashed!''</tag>
+(e.g., a `segmentation fault' or `core dumped')
+
+If your program has no @_ccall_@s/@_casm_@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 with a stable
+group of interface (@.hi@) files.
+
+For example, if an interface is lying about the type of an imported
+value then GHC may well generate duff code for the importing module.
+<em>This applies to pragmas inside interfaces too!</em> If the pragma is
+lying (e.g., about the ``arity'' of a value), then duff code may result.
+Furthermore, arities may change even if types do not.
+
+In short, if you compile a module and its interface changes, then all
+the modules that import that interface <em>must</em> be re-compiled.
+
+A useful option to alert you when interfaces change is
+@-hi-diffs@<nidx>-hi-diffs option</nidx>. It will run @diff@ on the
+changed interface file, before and after, when applicable.
+
+If you are using @make@, a useful tool to make sure that every module
+<em>is</em> up-to-date with respect to its imported interfaces is
+@mkdependHS@ (which comes with GHC). Please see Section <ref
+name="Makefile dependencies in Haskell: using mkdependHS"
+id="mkdependHS">.
+
+If you are down to your last-compile-before-a-bug-report, we would
+recommend that you add a @-dcore-lint@ option (for extra checking) to
+your compilation options.
+
+So, before you report a bug because of a core dump, you should probably:
+<tscreen><verb>
+% rm *.o # scrub your object files
+% make my_prog # re-make your program; use -hi-diffs to highlight changes;
+ # as mentioned above, use -dcore-lint to be more paranoid
+% ./my_prog ... # retry...
+</verb></tscreen>
+
+Of course, if you have @_ccall_@s/@_casm_@s in your program then all
+bets are off, because you can trash the heap, the stack, or whatever.
+
+If you are interested in hard-core debugging of a crashing
+GHC-compiled program, please see Section <ref name="Hard-core
+debugging of GHC-compiled programs" id="hard-core-debug">.
+
+% (If you have an ``unregisterised'' arity-checking
+% (@-O0 -darity-checks@) around [as we sometimes do at Glasgow], then you
+% might recompile with @-darity-checks@<nidx>-darity-checks option</nidx>,
+% which will definitely detect arity-compatibility errors.)
+
+%-------------------------------------------------------------------
+<tag>``My program entered an `absent' argument.''</tag>
+This is definitely caused by a bug in GHC. Please report it.
+
+%-----------------------------------------------------------------------
+<tag>``What's with this `arithmetic (or `floating') exception' ''?</tag>
+
+@Int@, @Float@, and @Double@ arithmetic is <em>unchecked</em>.
+Overflows, underflows and loss of precision are either silent or
+reported as an exception by the operating system (depending on the
+architecture). Divide-by-zero <em>may</em> cause an untrapped
+exception (please report it if it does).
+
+</descrip>
+
+%************************************************************************
+%* *
+<sect1>How to report a bug in the GHC system
+<label id="bug-reports">
+<p>
+<nidx>bug reports</nidx>
+%* *
+%************************************************************************
+
+Glasgow Haskell is a changing system so there are sure to be bugs in
+it. Please report them to <htmlurl
+name="glasgow-haskell-bugs@@dcs.gla.ac.uk"
+url="mailto:glasgow-haskell-bugs@@dcs.gla.ac.uk">! (However, please
+check the earlier part of this section to be sure it's not a known
+not-really-a problem.)
+
+The name of the bug-reporting game is: facts, facts, facts.
+Don't omit them because ``Oh, they won't be interested...''
+
+<enum>
+
+<item> What kind of machine are you running on, and exactly what
+version of the operating system are you using? (@uname -a@ or @cat
+/etc/motd@ will show the desired information.)
+
+<item> What version of GCC are you using? @gcc -v@ will tell you.
+
+<item> Run the sequence of compiles/runs that caused the offending
+behaviour, capturing all the input/output in a ``script'' (a UNIX
+command) or in an Emacs shell window. We'd prefer to see the whole
+thing.
+
+<item> Be sure any Haskell compilations are run with a @-v@ (verbose)
+flag, so we can see exactly what was run, what versions of things you
+have, etc.
+
+<item> What is the program behaviour that is wrong, in your opinion?
+
+<item> If practical, please send enough source files/interface files
+for us to duplicate the problem.
+
+<item> If you are a Hero and track down the problem in the
+compilation-system sources, please send us patches relative to a known
+released version of GHC, or whole files if you prefer.
+
+</enum>
+
+%************************************************************************
+%* *
+<sect1>Hard-core debugging of GHC-compiled programs
+<label id="hard-core-debug">
+<p>
+<nidx>debugging, hard-core</nidx>
+%* *
+%************************************************************************
+
+If your program is crashing, you should almost surely file a bug
+report, as outlined in previous sections.
+
+This section suggests ways to Make Further Progress Anyway.
+
+The first thing to establish is: Is it a garbage-collection (GC) bug?
+Try your program with a very large heap and a @-Sstderr@ RTS
+flag.
+<itemize>
+<item>
+If it crashes <em>without</em> garbage-collecting, then it is
+definitely <em>not</em> a GC bug.
+<item>
+If you can make it crash with one heap size but not with another, then
+it <em>probably is</em> a GC bug.
+<item>
+If it crashes with the normal
+collector, but not when you force two-space collection (@-F2s@
+runtime flag), then it <em>probably is</em> a GC bug.
+</itemize>
+
+If it <em>is</em> a GC bug, you may be able to avoid it by using a
+particular heap size or by using a @-F2s@ runtime flag. (But don't
+forget to report the bug!!!)
+
+ToDo: more here?
+++ /dev/null
-\section[invoking-GHC]{Invoking GHC: Command-line options}
-\index{command-line options}
-\index{options, GHC command-line}
-
-Command-line arguments are either options or file names.
-
-Command-line options begin with \tr{-}. They may {\em not} be
-grouped: \tr{-vO} is different from \tr{-v -O}. Options need not
-precede filenames: e.g., \tr{ghc *.o -o foo}. All options are
-processed and then applied to all files; you cannot, for example, invoke
-\tr{ghc -c -O1 Foo.hs -O2 Bar.hs} to apply different optimisation
-levels to the files \tr{Foo.hs} and \tr{Bar.hs}. For conflicting
-options, e.g., \tr{-c -S}, we reserve the right to do anything we
-want. (Usually, the last one applies.)
-
-Options related to profiling, Glasgow extensions to Haskell (e.g.,
-unboxed values), Concurrent and Parallel Haskell are described in
-\sectionref{profiling}, \sectionref{glasgow-exts}, and
-\sectionref{concurrent-and-parallel}, respectively.
-
-%************************************************************************
-%* *
-\subsection[file-suffixes]{Meaningful file suffixes}
-\index{suffixes, file}
-\index{file suffixes for GHC}
-%* *
-%************************************************************************
-
-File names with ``meaningful'' suffixes (e.g., \tr{.lhs} or \tr{.o})
-cause the ``right thing'' to happen to those files.
-
-\begin{description}
-\item[\tr{.lhs}:]
-\index{lhs suffix@.lhs suffix}
-A ``literate Haskell'' module.
-
-\item[\tr{.hs}:]
-A not-so-literate Haskell module.
-
-\item[\tr{.hi}:]
-A Haskell interface file, probably compiler-generated.
-
-\item[\tr{.hc}:]
-Intermediate C file produced by the Haskell compiler.
-
-\item[\tr{.c}:]
-A C~file not produced by the Haskell compiler.
-
-% \item[\tr{.i}:]
-% C code after it has be preprocessed by the C compiler (using the
-% \tr{-E} flag).
-
-\item[\tr{.s}:]
-An assembly-language source file, usually
-produced by the compiler.
-
-\item[\tr{.o}:]
-An object file, produced by an assembler.
-\end{description}
-
-Files with other suffixes (or without suffixes) are passed straight
-to the linker.
-
-%************************************************************************
-%* *
-\subsection[options-help]{Help and verbosity options}
-\index{help options (GHC)}
-\index{verbose option (GHC)}
-%* *
-%************************************************************************
-
-A good option to start with is the \tr{-help} (or \tr{-?}) option.
-\index{-help option}
-\index{-? option}
-GHC spews a long message to standard output and then exits.
-
-The \tr{-v}\index{-v option} option makes GHC {\em verbose}: it
-reports its version number and shows (on stderr) exactly how it invokes each
-phase of the compilation system. Moreover, it passes
-the \tr{-v} flag to most phases; each reports
-its version number (and possibly some other information).
-
-Please, oh please, use the \tr{-v} option when reporting bugs!
-Knowing that you ran the right bits in the right order is always the
-first thing we want to verify.
-
-If you're just interested in the compiler version number, the
-\tr{--version}\index{--version option} option prints out a
-one-line string containing the requested info.
-
-%************************************************************************
-%* *
-\subsection[options-order]{Running the right phases in the right order}
-\index{order of passes in GHC}
-\index{pass ordering in GHC}
-%* *
-%************************************************************************
-
-The basic task of the \tr{ghc} driver is to run each input file
-through the right phases (parsing, linking, etc.).
-
-The first phase to run is determined by the input-file suffix, and the
-last phase is determined by a flag. If no relevant flag is present,
-then go all the way through linking. This table summarises:
-
-\begin{tabular}{llll}
-phase of the & suffix saying & flag saying & (suffix of) \\
-compilation system & ``start here''& ``stop after''& output file \\ \hline
-
-literate pre-processor & .lhs & - & - \\
-C pre-processor (opt.) & - & - & - \\
-Haskell compiler & .hs & -C, -S & .hc, .s \\
-C compiler (opt.) & .hc or .c & -S & .s \\
-assembler & .s & -c & .o \\
-linker & other & - & a.out \\
-\end{tabular}
-\index{-C option}
-\index{-S option}
-\index{-c option}
-
-Thus, a common invocation would be: \tr{ghc -c Foo.hs}
-
-Note: What the Haskell compiler proper produces depends on whether a
-native-code generator is used (producing assembly language) or not
-(producing C).
-
-%The suffix information may be overridden with a \tr{-lang <suf>}
-%\index{-lang <suf> option} option. This says: process all inputs
-%files as if they had suffix \pl{<suf>}. [NOT IMPLEMENTED YET]
-
-The option \tr{-cpp}\index{-cpp option} 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.
-
-The option \tr{-E}\index{-E option} 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 \tr{-cpp}, the
-output is the de-litted version of the original source.
-
-The option \tr{-optcpp-E}\index{-optcpp-E option} runs just the
-pre-processing stage of the C-compiling phase, sending the result to
-stdout. (For debugging or obfuscation contests, usually.)
-
-%************************************************************************
-%* *
-\subsection[options-optimise]{Optimisation (code improvement)}
-\index{optimisation (GHC)}
-\index{improvement, code (GHC)}
-%* *
-%************************************************************************
-
-The \tr{-O*} options specify convenient ``packages'' of optimisation
-flags; the \tr{-f*} options described later on specify {\em individual}
-optimisations to be turned on/off; the \tr{-m*} options specify {\em
-machine-specific} optimisations to be turned on/off.
-
-%----------------------------------------------------------------------
-\subsubsection[optimise-pkgs]{\tr{-O*}: convenient ``packages'' of optimisation flags.}
-\index{-O options (GHC)}
-
-There are {\em many} options that affect the quality of code produced by
-GHC. Most people only have a general goal, something like ``Compile
-quickly'' or ``Make my program run like greased lightning.'' The
-following ``packages'' of optimisations (or lack thereof) should suffice.
-
-Once you choose a \tr{-O*} ``package,'' stick with it---don't chop and
-change. Modules' interfaces {\em will} change with a shift to a new
-\tr{-O*} option, and you may have to recompile a large chunk of all
-importing modules before your program can again be run
-safely\sectionref{recomp}.
-
-\begin{description}
-\item[No \tr{-O*}-type option specified:]
-\index{-O* not specified}
-This is taken to mean: ``Please compile quickly; I'm not over-bothered
-about compiled-code quality.'' So, for example: \tr{ghc -c Foo.hs}
-
-\item[\tr{-O} or \tr{-O1}:]
-\index{-O option}
-\index{-O1 option}
-\index{optimise normally}
-Means: ``Generate good-quality code without taking too long about it.''
-Thus, for example: \tr{ghc -c -O Main.lhs}
-
-\item[\tr{-O2}:]
-\index{-O2 option}
-\index{optimise aggressively}
-Means: ``Apply every non-dangerous optimisation, even if it means
-significantly longer compile times.''
-
-The avoided ``dangerous'' optimisations are those that can make
-runtime or space {\em worse} if you're unlucky. They are
-normally turned on or off individually.
-
-At the moment, \tr{-O2} is {\em unlikely} to produce
-better code than \tr{-O}.
-
-% \item[\tr{-O0}:]
-% \index{-O0 option}
-% \index{optimise minimally}
-% [``Oh zero''] Means: ``Turn {\em off} as many optimisations (e.g.,
-% simplifications) as possible.'' This is the only optimisation level
-% at which the GCC-register-trickery is turned off. {\em You can't use
-% it unless you have a suitably-built Prelude to match.} Intended for
-% hard-core debugging.
-
-\item[\tr{-fvia-C}:]
-\index{-fvia-C option}
-\index{-fvia-c option}
-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
-\tr{_ccall_}s or \tr{_casm_}s, you probably {\em have to} use
-\tr{-fvia-C}.
-
-The lower-case incantation, \tr{-fvia-c}, is synonymous.
-
-\item[\tr{-O2-for-C}:]
-\index{-O2-for-C option}
-Says to run GCC with \tr{-O2}, which may be worth a few percent in
-execution speed. Don't forget \tr{-fvia-C}, lest you use the
-native-code generator and bypass GCC altogether!
-
-\item[\tr{-Onot}:]
-\index{-Onot option}
-\index{optimising, reset}
-This option will make GHC ``forget'' any -Oish options it has seen
-so far. Sometimes useful; for example: \tr{make all EXTRA_HC_OPTS=-Onot}.
-
-\item[\tr{-Ofile <file>}:]
-\index{-Ofile <file> option}
-\index{optimising, customised}
-For those who need {\em absolute} control over {\em exactly} what
-options are used (e.g., compiler writers, sometimes :-), a list of
-options can be put in a file and then slurped in with \tr{-Ofile}.
-
-In that file, comments are of the \tr{#}-to-end-of-line variety; blank
-lines and most whitespace is ignored.
-
-Please ask if you are baffled and would like an example of \tr{-Ofile}!
-\end{description}
-
-At Glasgow, we don't use a \tr{-O*} flag for day-to-day work. We use
-\tr{-O} to get respectable speed; e.g., when we want to measure
-something. When we want to go for broke, we tend to use
-\tr{-O -fvia-C -O2-for-C} (and we go for lots of coffee breaks).
-
-%Here is a table to summarise whether pragmatic interface information
-%is used or not, whether the native-code generator is used (if
-%available), and whether we use GCC register tricks (for speed!) on the
-%generated C code:
-%
-%\begin{tabular}{lccl}
-%\tr{-O*} & Interface & Native code & `Registerised' C \\
-% & pragmas? & (if avail.) & (if avail.) \\ \hline
-%%
-%\pl{<none>} & no & yes & yes, only if \tr{-fvia-C} \\
-%\tr{-O,-O1} & yes & yes & yes, only if \tr{-fvia-C} \\
-%\tr{-O2} & yes & no & yes \\
-%\tr{-Ofile} & yes & yes & yes, only if \tr{-fvia-C} \\
-%\end{tabular}
-
-The easiest way to see what \tr{-O} (etc) ``really mean'' is to run
-with \tr{-v}, then stand back in amazement.
-Alternatively, just look at the
-\tr{@HsC_minus<blah>} lists in the \tr{ghc} driver script.
-
-%----------------------------------------------------------------------
-\subsubsection{\tr{-f*}: platform-independent flags}
-\index{-f* options (GHC)}
-\index{-fno-* options (GHC)}
-
-Flags can be turned {\em off} individually. (NB: I hope
-you have a good reason for doing this....) To turn off the \tr{-ffoo}
-flag, just use the \tr{-fno-foo} flag.\index{-fno-<opt> anti-option}
-So, for example, you can say
-\tr{-O2 -fno-strictness}, which will then drop out any running of the
-strictness analyser.
-
-The options you are most likely to want to turn off are:
-\tr{-fno-strictness}\index{-fno-strictness option} (strictness
-analyser [because it is sometimes slow]),
-\tr{-fno-specialise}\index{-fno-specialise option} (automatic
-specialisation of overloaded functions [because it makes your code
-bigger]) [US spelling also accepted],
-and
-\tr{-fno-foldr-build}\index{-fno-foldr-build option}.
-
-Should you wish to turn individual flags {\em on}, you are advised to
-use the \tr{-Ofile} 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.
-
-Here are some ``dangerous'' optimisations you {\em might} want to try:
-\begin{description}
-%------------------------------------------------------------------
-\item[\tr{-funfolding-creation-threshold<n>}:]
-(Default: 30) By raising or lowering this number, you can raise or
-lower the amount of pragmatic junk that gets spewed into interface
-files. (An unfolding has a ``size'' that reflects the cost in terms
-of ``code bloat'' of expanding that unfolding in another module. A
-bigger Core expression would be assigned a bigger cost.)
-
-\item[\tr{-funfolding-use-threshold<n>}:]
-(Default: 3) By raising or lowering this number, you can make the
-compiler more or less keen to expand unfoldings.
-
-OK, folks, these magic numbers `30' and `3' are mildly arbitrary; they
-are of the ``seem to be OK'' variety. The `3' is the more critical
-one; it's what determines how eager GHC is about expanding unfoldings.
-
-\item[\tr{-funfolding-override-threshold<n>}:]
-(Default: 8) [Pretty obscure]
-When deciding what unfoldings from a module should be made available
-to the rest of the world (via this module's interface), the compiler
-normally likes ``small'' expressions.
-
-For example, if it sees \tr{foo = bar}, it will decide that the very
-small expression \tr{bar} is a great unfolding for \tr{foo}. But if
-\tr{bar} turns out to be \tr{(True,False,True)}, we would probably
-prefer {\em that} for the unfolding for \tr{foo}.
-
-Should we ``override'' the initial small unfolding from \tr{foo=bar}
-with the bigger-but-better one? Yes, if the bigger one's ``size'' is
-still under the ``override threshold.'' You can use this flag to
-adjust this threshold (why, I'm not sure).
-
-% \item[\tr{-fliberated-case-threshold<n>}:]
-% (Default: 12) [Vastly obscure: NOT IMPLEMENTED YET]
-% ``Case liberation'' lifts evaluation out of recursive functions; it
-% does this by duplicating code. Done without constraint, you can get
-% serious code bloat; so we only do it if the ``size'' of the duplicated
-% code is smaller than some ``threshold.'' This flag can fiddle that
-% threshold.
-
-\item[\tr{-fsemi-tagging}:]
-This option (which {\em does not work} with the native-code generator)
-tells the compiler to add extra code to test for already-evaluated
-values. You win if you have lots of such values during a run of your
-program, you lose otherwise. (And you pay in extra code space.)
-
-We have not played with \tr{-fsemi-tagging} enough to recommend it.
-(For all we know, it doesn't even work anymore... Sigh.)
-\end{description}
-
-%----------------------------------------------------------------------
-% \subsubsection[optimise-simplifier]{Controlling ``simplification'' in the Haskell compiler.}
-%
-%Almost everyone turns program transformation
-% (a.k.a. ``simplification'') on/off via one of the ``packages'' above,
-%but you can exert absolute control if you want to. Do a \tr{ghc -v -O ...},
-%and you'll see there are plenty of knobs to turn!
-%
-%The Core-to-Core and STG-to-STG passes can be run multiple times, and
-%in varying orders (though you may live to regret it). The on-or-off
-%global flags, however, are simply, well, on or off.
-%
-%The best way to give an exact list of options is the \tr{-Ofile}
-%option, described elsewhere.
-%
-% [Check out \tr{ghc/compiler/simplCore/SimplCore.lhs} and
-%\tr{simplStg/SimplStg.lhs} if you {\em really} want to see every
-%possible Core-to-Core and STG-to-STG pass, respectively. The
-%on-or-off global flags that effect what happens {\em within} one of
-%these passes are defined by the \tr{GlobalSwitch} datatype in
-%\tr{compiler/main/CmdLineOpts.lhs}.]
-
-%----------------------------------------------------------------------
-\subsubsection{\tr{-m*}: platform-specific flags}
-\index{-m* options (GHC)}
-\index{platform-specific options}
-\index{machine-specific options}
-
-Some flags only make sense for particular target platforms.
-
-\begin{description}
-\item[\tr{-mv8}:]
-(SPARC machines)\index{-mv8 option (SPARC only)}
-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 \tr{-m*} GCC options for SPARC also work, actually.
-
-\item[\tr{-mlong-calls}:]
-(HPPA machines)\index{-mlong-calls option (HPPA only)}
-Means to pass the like-named option to GCC. Required for Very Big
-modules, maybe. (Probably means you're in trouble...)
-
-\item[\tr{-monly-[32]-regs}:]
-(iX86 machines)\index{-monly-N-regs option (iX86 only)}
-GHC tries to ``steal'' four registers from GCC, for performance
-reasons; it almost always works. However, when GCC is compiling some
-modules with four stolen registers, it will crash, probably saying:
-\begin{verbatim}
-Foo.hc:533: fixed or forbidden register was spilled.
-This may be due to a compiler bug or to impossible asm
-statements or clauses.
-\end{verbatim}
-Just give some registers back with \tr{-monly-N-regs}. Try `3' first,
-then `2'. If `2' doesn't work, please report the bug to us.
-\end{description}
-
-%----------------------------------------------------------------------
-\subsubsection[optimise-C-compiler]{Code improvement by the C compiler.}
-\index{optimisation by GCC}
-\index{GCC optimisation}
-
-The C~compiler (GCC) is run with \tr{-O} turned on. (It has
-to be, actually).
-
-If you want to run GCC with \tr{-O2}---which may be worth a few
-percent in execution speed---you can give a
-\tr{-O2-for-C}\index{-O2-for-C option} option.
-
-%If you are brave or foolish, you might want to omit some checking code
-% (e.g., for stack-overflow checks), as sketched in
-%\sectionref{omit-checking}.
-
-%************************************************************************
-%* *
-\subsection[options-sanity]{Warnings and sanity-checking}
-\index{sanity-checking options}
-\index{warnings}
-%* *
-%************************************************************************
-
-GHC has a selection of options that select which types of non-fatal
-error 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:
-\tr{-fwarn-overlpapping-patterns} and \tr{-fwarn-missing-methods}.
-The following flags are simple ways to select standard ``packages'' of
-warnings:
-
-\begin{description}
-
-\item[\tr{-Wnot}:]
-\index{-Wnot option}
-
-Turns off all warnings, including the standard ones.
-
-\item[\tr{-w}:]
-\index{-w option}
-
-Synonym for \tr{-Wnot}.
-
-\item[\tr{-W}:]
-\index{-W option}
-
-Provides the standard warnings plus \tr{-fwarn-incomplete-patterns}
-and \tr{-fwarn-unused-names}.
-
-\item[\tr{-Wall}:]
-\index{-Wall option}
-
-Turns on all warning options.
-
-\end{description}
-
-The full set of warning options is described below. To turn off any
-warning, simply give the corresponding \tr{-fno-warn-...} option on
-the command line.
-
-\begin{description}
-
-\item[\tr{-fwarn-name-shadowing}:]
-\index{-fwarn-name-shadowing option}
-\index{shadowing, warning}
-
-This option causes a warning to be emitted whenever an inner-scope
-value has the same name as an outer-scope value, i.e. the inner value
-shadows the outer one. This can catch typographical errors that turn
-into hard-to-find bugs, e.g., in the inadvertent cyclic definition
-\tr{let x = ... x ... in}.
-
-Consequently, this option does {\em not} allow cyclic recursive
-definitions.
-
-\item[\tr{-fwarn-overlapping-patterns}:]
-\index{-fwarn-overlapping-patterns option}
-\index{overlapping patterns, warning}
-\index{patterns, overlapping}
-
-By default, the compiler will warn you if a set of patterns are either
-incomplete (i.e., you're only matching on a subset of an algebraic
-data type's constructors), or overlapping, i.e.,
-
-\begin{verbatim}
-f :: String -> Int
-f [] = 0
-f (_:xs) = 1
-f "2" = 2
-
-g [] = 2
-\end{verbatim}
-
-where the last pattern match in \tr{f} 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.
-
-\item[\tr{-fwarn-incomplete-patterns}:]
-\index{-fwarn-incomplete-patterns option}
-\index{incomplete patterns, warning}
-\index{patterns, incomplete}
-
-Similarly for incomplete patterns, the function \tr{g} will fail when
-applied to non-empty lists, so the compiler will emit a warning about
-this when this option is enabled.
-
-\item[\tr{-fwarn-missing-methods}:]
-\index{-fwarn-missing-methods option}
-\index{methods, missing}
-
-This option is on by default, and warns you whenever an instance
-declaration is missing one or more methods, and the corresponding
-class declaration has no default declaration for them.
-
-\item[\tr{-fwarn-unused-names}:]
-\index{-fwarn-unused-names}
-Have the renamer report which locally defined names are not
-used/exported. This option is not currently supported.
-
-\item[\tr{-fwarn-duplicate-exports}:]
-\index{-fwarn-duplicate-exports option}
-\index{export lists, duplicates}
-
-Have the compiler warn about duplicate entries in export lists. This
-is useful information if you maintain large export lists, and want to
-avoid the continued export of a definition after you've deleted (one)
-mention of it in the export list.
-
-This option is on by default.
-
-\end{description}
-
-If you would like GHC to check that every top-level value has a type
-signature, use the \tr{-fsignatures-required}
-option.\index{-fsignatures-required option}
-
-If you're feeling really paranoid, the \tr{-dcore-lint}
-option\index{-dcore-lint option} is a good choice. It turns on
-heavyweight intra-pass sanity-checking within GHC. (It checks GHC's
-sanity, not yours.)
-
-%************************************************************************
-%* *
-\subsection[options-output]{Re-directing the compilation output(s)}
-\index{output-directing options}
-%* *
-%************************************************************************
-
-When compiling a Haskell module, GHC may produce several files of
-output (usually two).
-
-One file is usually an {\em interface file}. The name of the
-interface file follows the Haskell {\em module} name, i.e., if
-compiling \tr{bar/Foo.hs}, and it implements \tr{module Bar ...}, the
-interface file would normally be \tr{bar/Bar.hi}.
-
-The interface output may be directed to another file
-\tr{bar2/Wurble.iface} with the option \tr{-ohi
-bar2/Wurble.iface}\index{-ohi <file> option} (not recommended).
-
-NOTE: Having the name of the interface file follow the module name
-and not the file name, means that working with tools such as
-\tr{make(1)} become harder. \tr{make} 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.
-
-To avoid generating an interface file at all, use a \tr{-nohi}
-option.\index{-nohi option}
-
-The compiler does not overwrite an existing \tr{.hi} interface file if
-the new one is byte-for-byte the same as the old one; this is friendly to
-\tr{make}. When an interface does change, it is often enlightening to
-be informed. The \tr{-hi-diffs}\index{-hi-diffs option} option will
-make \tr{ghc} run \tr{diff} on the old and new \tr{.hi} files. You can
-also record the difference in the interface file itself, the
-\tr{-keep-hi-diffs}\index{-keep-hi-diffs} option takes care of that.
-
-The \tr{.hi} files from GHC 2.xx contain ``usage'' information which
-changes often and uninterestingly. If you really want to see these
-changes reported, you need to use the
-\tr{-hi-diffs-with-usages}\index{-hi-diffs-with-usages option} option.
-
-GHC's non-interface output normally goes into a \tr{.hc}, \tr{.o},
-etc., file, depending on the last-run compilation phase. The option
-\tr{-o foo}\index{-o option} re-directs the output of that last-run
-phase to file \tr{foo}.
-
-Note: this ``feature'' can be counterintuitive:
-\tr{ghc -C -o foo.o foo.hs} will put the intermediate C code in the
-file \tr{foo.o}, name notwithstanding!
-
-EXOTICA: But the \tr{-o} option isn't of much use if you have {\em
-several} 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
-\tr{-odir <dir>}\index{-odir <dir> option} (the ``Oh, dear'' option).
-For example:
-
-\begin{verbatim}
-% ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
-\end{verbatim}
-
-The output files, \tr{Foo.o}, \tr{Bar.o}, and \tr{Bumble.o} would be
-put into a subdirectory named after the architecture of the executing
-machine (\tr{sun4}, \tr{mips}, etc). The directory must already
-exist; it won't be created.
-
-Note that the \tr{-odir} option does {\em not} affect where the
-interface files are put. In the above example, they would still be
-put in \tr{parse/Foo.hi}, \tr{parse/Bar.hi}, and
-\tr{gurgle/Bumble.hi}.
-
-MORE EXOTICA: The \tr{-osuf <suffix>}\index{-osuf <suffix> option}
-will change the \tr{.o} file suffix for object files to whatever
-you specify. (We use this in compiling the prelude.)
-
-Similarly, the \tr{-hisuf <suffix>}\index{-hisuf <suffix> option} will
-change the \tr{.hi} file suffix for non-system interface files. This
-can be useful when you are trying to compile a program several ways,
-all in the same directory. The suffix given is used for {\em all}
-interfaces files written, {\em and} for all non-system interface files
-that your read.
-
-The \tr{-hisuf}/\tr{-osuf} 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 \tr{.hi}/\tr{.o} suffixes; add
-\tr{-hisuf g_hi -osuf g_o} to your \tr{make} rule for GHC compiling...
-
-NB: {\em A change from 0.26 and before:} Before, you might have said
-\tr{-hisuf _g.hi -osuf _g.o}; now, the \tr{.} is assumed and you
-specify what comes {\em after} it. (This is a more portable solution
-for the long term.)
-
-% THIS SHOULD HAPPEN AUTOMAGICALLY:
-% If you want to change the suffix looked for on system-supplied
-% interface files (notably the \tr{Prelude.hi} file), use the
-% \tr{-hisuf-prelude <suffix>}\index{-hisuf-prelude <suffix> option}
-% option. (This may be useful if you've built GHC in various funny
-% ways, and you are running tests in even more funny ways. It happens.)
-
-FURTHER EXOTICA: If you are doing a normal \tr{.hs}-to-\tr{.o} compilation
-but would like to hang onto the intermediate \tr{.hc} C file, just
-throw in a \tr{-keep-hc-file-too} option\index{-keep-hc-file-too option}.
-If you would like to look at the assembler output, toss in a
-\tr{-keep-s-file-too},\index{-keep-hc-file-too option} too.
-
-SAVING GHC STDERR OUTPUT: Sometimes, you may cause GHC to be rather
-chatty on standard error; with \tr{-fshow-import-specs}, for example.
-You can instruct GHC to {\em append} this output to a particular log
-file with a \tr{-odump <blah>}\index{-odump <blah> option} option.
-
-TEMPORARY FILES: If you have trouble because of running out of space
-in \tr{/tmp/} (or wherever your installation thinks temporary files
-should go), you may use the \tr{-tmpdir <dir>}\index{-tmpdir <dir> option}
-option to specify an alternate directory. For example, \tr{-tmpdir .}
-says to put temporary files in the current working directory.
-
-BETTER IDEA FOR TEMPORARY FILES: Use your \tr{TMPDIR} environment
-variable.\index{TMPDIR environment variable} Set it to the name of
-the directory where temporary files should be put. GCC and other
-programs will honour the \tr{TMPDIR} variable as well.
-
-EVEN BETTER IDEA: Set the \tr{TMPDIR} variable when building
-GHC, and never worry about \tr{TMPDIR} again. (see the build
-documentation).
-
-%************************************************************************
-%* *
-\subsection[options-finding-imports-etc]{For finding interface files, etc.}
-\index{interface files, finding them}
-\index{finding interface files}
-%* *
-%************************************************************************
-
-In your program, you import a module \tr{Foo} by saying
-\tr{import Foo}. GHC goes looking for an interface file, \tr{Foo.hi}.
-It has a builtin list of directories (notably including \tr{.}) where
-it looks.
-
-The \tr{-i<dirs>} option\index{-i<dirs> option} prepends a
-colon-separated list of \tr{dirs} to the ``import directories'' list.
-
-A plain \tr{-i} resets the ``import directories'' list back to nothing.
-
-GHC normally imports \tr{Prelude.hi} files for you. If you'd rather
-it didn't, then give it a \tr{-fno-implicit-prelude}
-option\index{-fno-implicit-prelude option}. You are unlikely to get
-very far without a Prelude, but, hey, it's a free country.
-
-If you are using a system-supplied non-Prelude library (e.g., the HBC
-library), just use a \tr{-syslib hbc}\index{-syslib <lib> option}
-option (for example). The right interface files should then be
-available.
-
-Once a Haskell module has been compiled to C (\tr{.hc} file), you may
-wish to specify where GHC tells the C compiler to look for \tr{.h}
-files. (Or, if you are using the \tr{-cpp} option\index{-cpp option},
-where it tells the C pre-processor to look...) For this purpose, use
-a \tr{-I<dir>}\index{-I<dir> option} in the usual C-ish way.
-
-Pragmas: Interface files are normally jammed full of
-compiler-produced {\em pragmas}, 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 \tr{-fignore-interface-pragmas}\index{-fignore-interface-pragmas option}
-option.
-
-When compiling without optimisations on, the compiler is extra-careful
-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 \tr{-fno-prune-tydecls} and \tr{-fno-prune-instdecls}.
-\index{-fno-prune-tydecls option}\index{-fno-prune-instdecls}
-
-See also \sectionref{options-linker}, which describes how the linker
-finds standard Haskell libraries.
-
-%************************************************************************
-%* *
-%\subsection[options-names]{Fiddling with namespaces}
-%* *
-%************************************************************************
-
-%-split-objs and -fglobalise-toplev-names. You don't need them and you
-%don't want to know; used for the prelude (ToDo).
-
-%************************************************************************
-%* *
-\subsection[options-CPP]{Related to the C pre-processor}
-\index{C pre-processor options}
-\index{pre-processor (cpp) options}
-%* *
-%************************************************************************
-
-The C pre-processor \tr{cpp} is run over your Haskell code only if the
-\tr{-cpp} option \index{-cpp option} is given. Unless you are
-building a large system with significant doses of conditional
-compilation, you really shouldn't need it.
-\begin{description}
-\item[\tr{-D<foo>}:]
-\index{-D<name> option}
-Define macro \tr{<foo>} in the usual way. NB: does {\em not} affect
-\tr{-D} macros passed to the C~compiler when compiling via C! For
-those, use the \tr{-optc-Dfoo} hack...
-
-\item[\tr{-U<foo>}:]
-\index{-U<name> option}
-Undefine macro \tr{<foo>} in the usual way.
-
-\item[\tr{-I<dir>}:]
-\index{-I<dir> option}
-Specify a directory in which to look for \tr{#include} files, in
-the usual C way.
-\end{description}
-
-The \tr{ghc} driver pre-defines several macros:
-\begin{description}
-\item[\tr{__HASKELL1__}:]
-\index{__HASKELL1__ macro}
-If defined to $n$, that means GHC supports the
-Haskell language defined in the Haskell report version $1.n$.
-Currently 4.
-
-NB: This macro is set both when pre-processing Haskell source and
-when pre-processing generated C (\tr{.hc}) files.
-
-% If you give the \tr{-fhaskell-1.3} flag\index{-fhaskell-1.3 option},
-% then \tr{__HASKELL1__} is set to 3. Obviously.
-
-\item[\tr{__GLASGOW_HASKELL__}:]
-\index{__GLASGOW_HASKELL__ macro}
-For version $n$ of the GHC system, this will be \tr{#define}d to
-$100 \times n$. So, for version~2.02, it is 202.
-
-This macro is {\em only} set when pre-processing Haskell source.
-({\em Not} when pre-processing generated C.)
-
-With any luck, \tr{__GLASGOW_HASKELL__} will be undefined in all other
-implementations that support C-style pre-processing.
-
-(For reference: the comparable symbols for other systems are:
-\tr{__HUGS__} for Hugs and \tr{__HBC__} for Chalmers.)
-
-\item[\tr{__CONCURRENT_HASKELL__}:]
-\index{__CONCURRENT_HASKELL__ macro}
-Only defined when \tr{-concurrent} is in use!
-This symbol is defined when pre-processing Haskell (input) and
-pre-processing C (GHC output).
-
-\item[\tr{__PARALLEL_HASKELL__}:]
-\index{__PARALLEL_HASKELL__ macro}
-Only defined when \tr{-parallel} is in use! This symbol is defined when
-pre-processing Haskell (input) and pre-processing C (GHC output).
-\end{description}
-
-Options other than the above can be forced through to the C
-pre-processor with the \tr{-opt} flags (see
-\sectionref{forcing-options-through}).
-
-A small word of warning: \tr{-cpp} is not friendly to ``string
-gaps''.\index{-cpp vs string gaps}\index{string gaps vs -cpp}. In
-other words, strings such as the following:
-
-\begin{verbatim}
- strmod = "\
- \ p \
- \ "
-\end{verbatim}
-
-don't work with \tr{-cpp}; \tr{/usr/bin/cpp} elides the
-backslash-newline pairs.
-
-However, it appears that if you add a space at the end of the line,
-then \tr{cpp} (at least GNU \tr{cpp} and possibly other \tr{cpp}s)
-leaves the backslash-space pairs alone and the string gap works as
-expected.
-
-%************************************************************************
-%* *
-\subsection[options-C-compiler]{Options affecting the C compiler (if applicable)}
-\index{include-file-option}
-\index{C compiler options}
-\index{GCC options}
-%* *
-%************************************************************************
-
-At the moment, quite a few common C-compiler options are passed on
-quietly to the C compilation of Haskell-compiler-generated C files.
-THIS MAY CHANGE. Meanwhile, options so sent are:
-
-\begin{tabular}{ll}
-\tr{-Wall} & get all warnings from GCC \\
-\tr{-ansi} & do ANSI C (not K\&R) \\
-\tr{-pedantic} & be so\\
-\tr{-dgcc-lint} & (hack) short for ``make GCC very paranoid''\\
-\end{tabular}
-\index{-Wall option (for GCC)}
-\index{-ansi option (for GCC)}
-\index{-pedantic option (for GCC)}
-\index{-dgcc-lint option (GCC paranoia)}
-
-If you are compiling with lots of \tr{ccalls}, etc., you may need to
-tell the C~compiler about some \tr{#include} files. There is no real
-pretty way to do this, but you can use this hack from the
-command-line:
-\begin{verbatim}
-% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
-\end{verbatim}
-
-
-%************************************************************************
-%* *
-%\subsection[options-native-code]{Options affecting the native-code generator(s)}
-%* *
-%************************************************************************
-
-%The only option is to select the target architecture. Right now,
-%you have only at most one choice: \tr{-fasm-sparc}.\index{-fasm-<target> option}
-%
-%EXPECT this native-code stuff to change in the future.
-
-%************************************************************************
-%* *
-\subsection[options-linker]{Linking and consistency-checking}
-\index{linker options}
-\index{ld options}
-%* *
-%************************************************************************
-
-GHC has to link your code with various libraries, possibly including:
-user-supplied, GHC-supplied, and system-supplied (\tr{-lm} math
-library, for example).
-
-\begin{description}
-\item[\tr{-l<FOO>}:]
-\index{-l<lib> option}
-Link in a library named \tr{lib<FOO>.a} which resides somewhere on the
-library directories path.
-
-Because of the sad state of most UNIX linkers, the order of such
-options does matter. Thus: \tr{ghc -lbar *.o} is almost certainly
-wrong, because it will search \tr{libbar.a} {\em before} it has
-collected unresolved symbols from the \tr{*.o} files.
-\tr{ghc *.o -lbar} is probably better.
-
-The linker will of course be informed about some GHC-supplied
-libraries automatically; these are:
-
-\begin{tabular}{ll}
--l equivalent & description \\ \hline
-
--lHSrts,-lHSclib & basic runtime libraries \\
--lHS & standard Prelude library \\
--lHS\_cbits & C support code for standard Prelude library \\
--lgmp & GNU multi-precision library (for Integers)\\
-\end{tabular}
-\index{-lHS library}
-\index{-lHS_cbits library}
-\index{-lHSrts library}
-\index{-lgmp library}
-
-\item[\tr{-syslib <name>}:]
-\index{-syslib <name> option}
-
-If you are using a Haskell ``system library'' (e.g., the HBC
-library), just use the \tr{-syslib hbc} option, and the correct code
-should be linked in.
-
-%Please see \sectionref{syslibs} for information about
-%``system libraries.''
-
-\item[\tr{-L<dir>}:]
-\index{-L<dir> option}
-Where to find user-supplied libraries... Prepend the directory
-\tr{<dir>} to the library directories path.
-
-\item[\tr{-static}:]
-\index{-static option}
-Tell the linker to avoid shared libraries.
-
-\item[\tr{-no-link-chk} and \tr{-link-chk}:]
-\index{-no-link-chk option}
-\index{-link-chk option}
-\index{consistency checking of executables}
-By default, immediately after linking an executable, GHC verifies that
-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 \tr{.o} file was compiled
-for a parallel machine and the others weren't.) You may turn off this
-check with \tr{-no-link-chk}. You can turn it (back) on with
-\tr{-link-chk} (the default).
-\end{description}
-
-%************************************************************************
-%* *
-\subsection[options-compiler-RTS]{For the compiler's RTS: heap, stack sizes, etc.}
-\index{heap-size options (for GHC)}
-\index{stack-size options (for GHC)}
-%* *
-%************************************************************************
-
-The compiler is itself a Haskell program, so it has a tweakable
-runtime-system (RTS), just like any other Haskell program.
-
-\begin{description}
-\item[\tr{-H<size>} or \tr{-Rmax-heapsize <size>}:]
-\index{-H<size> option}
-\index{-Rmax-heapsize <size> option}
-Don't use more than \tr{<size>} {\em bytes} for heap space. If more
-than one of these arguments is given, the largest will be taken.
-
-A size of zero can be used to reset the heap size downwards. For
-example, to run GHC with a heap of 250KB (the default is 6MB), do
-\tr{-H0 -H250k}.
-
-\item[\tr{-K<size>} or \tr{-Rmax-stksize <size>}:]
-\index{-K<size> option}
-\index{-Rmax-stksize <size> option}
-Set the stack space to \tr{<size>} bytes. If you have to set it very
-high [a megabyte or two, say], the compiler is probably looping, which
-is a BUG (please report).
-
-A size of zero can be used to rest the stack size downwards, as above.
-
-\item[\tr{-Rscale-sizes<factor>}:]
-\index{-Rscale-sizes<factor> option}
-Multiply the given (or default) heap and stack sizes by \tr{<factor>}.
-For example, on a DEC Alpha (a 64-bit machine), you might want to
-double those space sizes; just use \tr{-Rscale-sizes2}.
-
-A non-integral factor is OK, too: \tr{-Rscale-sizes1.2}.
-
-\item[\tr{-Rghc-timing}:]
-\index{-Rghc-timing option}
-Reports a one-line useful collection of time- and space- statistics
-for a module's compilation.
-
-\item[\tr{-Rgc-stats}:]
-\index{-Rgc-stats option}
-Report garbage-collection statistics. It will create a
-\tr{<foo>.stat} file, in some obvious place (I hope).
-
-Alternatively, if you'd rather the GC stats went straight to standard
-error, you can ``cheat'' by using, instead: \tr{-optCrts-Sstderr}.
-%
-%\item[\tr{-Rhbc}:]
-%\index{-Rhbc option}
-%Tell the compiler it has an HBC-style RTS; i.e., it was compiled with
-%HBC. Not used in Real Life.
-%
-%\item[\tr{-Rghc}:]
-%\index{-Rghc option}
-%Tell the compiler it has a GHC-style RTS; i.e., it was compiled with
-%GHC. Not used in Real Life.
-\end{description}
-
-For all \tr{<size>}s: If the last character of \tr{size} is a K,
-multiply by 1000; if an M, by 1,000,000; if a G, by 1,000,000,000.
-Sizes are always in {\em bytes}, not words. Good luck on the G's (I
-think the counter is still only 32-bits [WDP])!
-
-%************************************************************************
-%* *
-%\subsection[options-cross-compiling]{For cross-compiling to another architecture}
-%* *
-%************************************************************************
-%
-% (We do this for GRIP at Glasgow; it's hacked in---not proper
-%cross-compiling support. But you could do the same, if required...)
-%
-%The \tr{-target <arch>} option\index{-target <arch> option} says to
-%generate code for the \tr{<arch>} architecture.
-
-%************************************************************************
-%* *
-\subsection[options-parallel]{For Concurrent and Parallel Haskell}
-%* *
-%************************************************************************
-
-For the full story on using GHC for concurrent \& parallel Haskell
-programming, please see \Sectionref{concurrent-and-parallel}.
-
-%The \tr{-fparallel} option\index{-fparallel option} tells the compiler
-%to generate code for parallel execution. The \tr{-mgrip}
-%option\index{-mgrip option} says that the code should be explicitly
-%suitable for the GRIP multiprocessor (the one in our Glasgow basement).
-
-%************************************************************************
-%* *
-%\subsection[options-experimental]{For experimental purposes}
-%\index{experimental options}
-%* *
-%************************************************************************
-
-%From time to time, we provide GHC options for ``experimenting.'' Easy
-%come, easy go. In version~0.26, the ``experimental'' options are:
-%\begin{description}
-%\item[\tr{-firrefutable-tuples} option:]
-%\index{-firrefutable-tuples option (experimental)}
-%Pretend that every tuple pattern is irrefutable; i.e., has a
-%``twiddle'' (\tr{~}) in front of it.
-%
-%Some parts of the GHC system {\em depend} on strictness properties which
-%\tr{-firrefutable-tuples} may undo, notably the low-level state-transformer
-%stuff, which includes I/O (!). You're on your own...
-%
-%\item[\tr{-fall-strict} option:]
-%\index{-fall-strict option (experimental)}
-% (DOESN'T REALLY WORK, I THINK) Changes the strictness analyser so
-%that, when it asks the question ``Is this function argument certain to
-%be evaluated?'', the answer is always ``yes''.
-%
-%Compilation is changed in no other way.
-%\end{description}
-
-% -firrefutable-everything
-% -fall-demanded
-
-%************************************************************************
-%* *
-\subsection[options-debugging]{For debugging the compiler}
-\index{debugging options (for GHC)}
-%* *
-%************************************************************************
-
-HACKER TERRITORY. HACKER TERRITORY.
-(You were warned.)
-
-%----------------------------------------------------------------------
-\subsubsection[replacing-phases]{Replacing the program for one or more phases.}
-\index{GHC phases, changing}
-\index{phases, changing GHC}
-
-You may specify that a different program
-be used for one of the phases of the compilation system, in place of
-whatever the driver \tr{ghc} has wired into it. For example, you
-might want to try a different assembler. The
-\tr{-pgm<phase-code><program-name>}\index{-pgm<phase><stuff> option} option to
-\tr{ghc} will cause it to use \pl{<program-name>} for phase
-\pl{<phase-code>}, where the codes to indicate the phases are:
-
-\begin{tabular}{ll}
-code & phase \\ \hline
-L & literate pre-processor \\
-P & C pre-processor (if -cpp only) \\
-C & Haskell compiler \\
-c & C compiler\\
-a & assembler \\
-l & linker \\
-\end{tabular}
-
-%----------------------------------------------------------------------
-\subsubsection[forcing-options-through]{Forcing options to a particular phase.}
-\index{forcing GHC-phase options}
-
-The preceding sections describe driver options that are mostly
-applicable to one particular phase. You may also {\em force} a
-specific option \tr{<option>} to be passed to a particular phase
-\tr{<phase-code>} by feeding the driver the option
-\tr{-opt<phase-code><option>}.\index{-opt<phase><stuff> option} The
-codes to indicate the phases are the same as in the previous section.
-
-So, for example, to force an \tr{-Ewurble} option to the assembler, you
-would tell the driver \tr{-opta-Ewurble} (the dash before the E is
-required).
-
-Besides getting options to the Haskell compiler with \tr{-optC<blah>},
-you can get options through to its runtime system with
-\tr{-optCrts<blah>}\index{-optCrts<blah> option}.
-
-So, for example: when I want to use my normal driver but with my
-profiled compiler binary, I use this script:
-\begin{verbatim}
-#! /bin/sh
-exec /local/grasp_tmp3/simonpj/ghc-BUILDS/working-alpha/ghc/driver/ghc \
- -pgmC/local/grasp_tmp3/simonpj/ghc-BUILDS/working-hsc-prof/hsc \
- -optCrts-i0.5 \
- -optCrts-PT \
- "$@"
-\end{verbatim}
-
-%----------------------------------------------------------------------
-\subsubsection[dumping-output]{Dumping out compiler intermediate structures}
-\index{dumping GHC intermediates}
-\index{intermediate passes, output}
-
-\begin{description}
-\item[\tr{-noC}:]
-\index{-noC option}
-Don't bother generating C output {\em or} an interface file. Usually
-used in conjunction with one or more of the \tr{-ddump-*} options; for
-example: \tr{ghc -noC -ddump-simpl Foo.hs}
-
-\item[\tr{-hi}:]
-\index{-hi option}
-{\em Do} generate an interface file. This would normally be used in
-conjunction with \tr{-noC}, which turns off interface generation;
-thus: \tr{-noC -hi}.
-
-\item[\tr{-dshow-passes}:]
-\index{-dshow-passes option}
-Prints a message to stderr as each pass starts. Gives a warm but
-undoubtedly misleading feeling that GHC is telling you what's
-happening.
-
-\item[\tr{-ddump-<pass>}:]
-\index{-ddump-<pass> options}
-Make a debugging dump after pass \tr{<pass>} (may be common enough to
-need a short form...). Some of the most useful ones are:
-
-\begin{tabular}{ll}
-\tr{-ddump-rdr} & reader output (earliest stuff in the compiler) \\
-\tr{-ddump-rn} & renamer output \\
-\tr{-ddump-tc} & typechecker output \\
-\tr{-ddump-deriv} & derived instances \\
-\tr{-ddump-ds} & desugarer output \\
-\tr{-ddump-simpl} & simplifer output (Core-to-Core passes) \\
-\tr{-ddump-stranal} & strictness analyser output \\
-\tr{-ddump-occur-anal} & `occurrence analysis' output \\
-\tr{-ddump-spec} & dump specialisation info \\
-\tr{-ddump-stg} & output of STG-to-STG passes \\
-\tr{-ddump-absC} & {\em un}flattened Abstract~C \\
-\tr{-ddump-flatC} & {\em flattened} Abstract~C \\
-\tr{-ddump-realC} & same as what goes to the C compiler \\
-\tr{-ddump-asm} & assembly language from the native-code generator \\
-\end{tabular}
-\index{-ddump-rdr option}%
-\index{-ddump-rn option}%
-\index{-ddump-tc option}%
-\index{-ddump-deriv option}%
-\index{-ddump-ds option}%
-\index{-ddump-simpl option}%
-\index{-ddump-stranal option}%
-\index{-ddump-occur-anal option}%
-\index{-ddump-spec option}%
-\index{-ddump-stg option}%
-\index{-ddump-absC option}%
-\index{-ddump-flatC option}%
-\index{-ddump-realC option}%
-\index{-ddump-asm option}
-
-%For any other \tr{-ddump-*} options: consult the source, notably
-%\tr{ghc/compiler/main/CmdLineOpts.lhs}.
-
-\item[\tr{-dverbose-simpl} and \tr{-dverbose-stg}:]
-\index{-dverbose-simpl option}
-\index{-dverbose-stg option}
-Show the output of the intermediate Core-to-Core and STG-to-STG
-passes, respectively. ({\em Lots} of output!) So: when we're
-really desperate:
-\begin{verbatim}
-% ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
-\end{verbatim}
-
-\item[\tr{-dppr-{user,debug,all}}:]
-\index{-dppr-user option}
-\index{-dppr-debug option}
-\index{-dppr-all option}
-Debugging output is in one of several ``styles.'' Take the printing
-of types, for example. In the ``user'' style, the compiler's internal
-ideas about types are presented in Haskell source-level syntax,
-insofar as possible. In the ``debug'' style (which is the default for
-debugging output), the types are printed in the most-often-desired
-form, with explicit foralls, etc. In the ``show all'' style, very
-verbose information about the types (e.g., the Uniques on the
-individual type variables) is displayed.
-
-\item[\tr{-ddump-raw-asm}:]
-\index{-ddump-raw-asm option}
-Dump out the assembly-language stuff, before the ``mangler'' gets it.
-
-\item[\tr{-ddump-rn-trace}:]
-\index{-ddump-rn-trace}
-Make the renamer be *real* chatty about what it is upto.
-
-\item[\tr{-dshow-rn-stats}:]
-\index{-dshow-rn-stats}
-Print out summary of what kind of information the renamer had to bring
-in.
-\item[\tr{-dshow-unused-imports}:]
-\index{-dshow-unused-imports}
-Have the renamer report what imports does not contribute.
-
-%
-%\item[\tr{-dgc-debug}:]
-%\index{-dgc-debug option}
-%Enables some debugging code related to the garbage-collector.
-\end{description}
-
-%ToDo: -ddump-asm-insn-counts
-%-ddump-asm-globals-info
-
-%----------------------------------------------------------------------
-\subsubsection{How to read Core syntax (from some \tr{-ddump-*} flags)}
-\index{reading Core syntax}
-\index{Core syntax, how to read}
-
-Let's do this by commenting an example. It's from doing
-\tr{-ddump-ds} on this code:
-\begin{verbatim}
-skip2 m = m : skip2 (m+2)
-\end{verbatim}
-
-Before we jump in, a word about names of things. Within GHC,
-variables, type constructors, etc., are identified by their
-``Uniques.'' These are of the form `letter' plus `number' (both
-loosely interpreted). The `letter' gives some idea of where the
-Unique came from; e.g., \tr{_} means ``built-in type variable'';
-\tr{t} means ``from the typechecker''; \tr{s} means ``from the
-simplifier''; and so on. The `number' is printed fairly compactly in
-a `base-62' format, which everyone hates except me (WDP).
-
-Remember, everything has a ``Unique'' and it is usually printed out
-when debugging, in some form or another. So here we go...
-
-\begin{verbatim}
-Desugared:
-Main.skip2{-r1L6-} :: _forall_ a$_4 =>{{Num a$_4}} -> a$_4 -> [a$_4]
-
---# `r1L6' is the Unique for Main.skip2;
---# `_4' is the Unique for the type-variable (template) `a'
---# `{{Num a$_4}}' is a dictionary argument
-
-_NI_
-
---# `_NI_' means "no (pragmatic) information" yet; it will later
---# evolve into the GHC_PRAGMA info that goes into interface files.
-
-Main.skip2{-r1L6-} =
- /\ _4 -> \ d.Num.t4Gt ->
- let {
- {- CoRec -}
- +.t4Hg :: _4 -> _4 -> _4
- _NI_
- +.t4Hg = (+{-r3JH-} _4) d.Num.t4Gt
-
- fromInt.t4GS :: Int{-2i-} -> _4
- _NI_
- fromInt.t4GS = (fromInt{-r3JX-} _4) d.Num.t4Gt
-
---# The `+' class method (Unique: r3JH) selects the addition code
---# from a `Num' dictionary (now an explicit lamba'd argument).
---# Because Core is 2nd-order lambda-calculus, type applications
---# and lambdas (/\) are explicit. So `+' is first applied to a
---# type (`_4'), then to a dictionary, yielding the actual addition
---# function that we will use subsequently...
-
---# We play the exact same game with the (non-standard) class method
---# `fromInt'. Unsurprisingly, the type `Int' is wired into the
---# compiler.
-
- lit.t4Hb :: _4
- _NI_
- lit.t4Hb =
- let {
- ds.d4Qz :: Int{-2i-}
- _NI_
- ds.d4Qz = I#! 2#
- } in fromInt.t4GS ds.d4Qz
-
---# `I# 2#' is just the literal Int `2'; it reflects the fact that
---# GHC defines `data Int = I# Int#', where Int# is the primitive
---# unboxed type. (see relevant info about unboxed types elsewhere...)
-
---# The `!' after `I#' indicates that this is a *saturated*
---# application of the `I#' data constructor (i.e., not partially
---# applied).
-
- skip2.t3Ja :: _4 -> [_4]
- _NI_
- skip2.t3Ja =
- \ m.r1H4 ->
- let { ds.d4QQ :: [_4]
- _NI_
- ds.d4QQ =
- let {
- ds.d4QY :: _4
- _NI_
- ds.d4QY = +.t4Hg m.r1H4 lit.t4Hb
- } in skip2.t3Ja ds.d4QY
- } in
- :! _4 m.r1H4 ds.d4QQ
-
- {- end CoRec -}
- } in skip2.t3Ja
-\end{verbatim}
-
-(``It's just a simple functional language'' is an unregisterised
-trademark of Peyton Jones Enterprises, plc.)
-
-%----------------------------------------------------------------------
-\subsubsection[source-file-options]{Command line options in source files}
-\index{source-file options}
-
-Sometimes it is useful to make the connection between a source file
-and the command-line options it requires quite tight. For instance,
-if a (Glasgow) Haskell source file uses \tr{casm}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
-\tr{Makefile} (using the \tr{-#include} command-line option), it is
-possible to do this directly in the source file using the \tr{OPTIONS}
-pragma \index{OPTIONS pragma}:
-
-\begin{verbatim}
-{-# OPTIONS -#include "foo.h" #-}
-module X where
-
-...
-\end{verbatim}
-
-\tr{OPTIONS} pragmas are only looked for at the top of your source
-files, upto the first (non-literate,non-empty) line not containing
-\tr{OPTIONS}. Multiple \tr{OPTIONS} pragmas are recognised. Note
-that your command shell does not get to the source file options, they
-are just included literally in the array of command-line arguments
-the compiler driver maintains internally, so you'll be desperately
-disappointed if you try to glob etc. inside \tr{OPTIONS}.
-
-NOTE: the contents of OPTIONS are prepended to the command-line
-options, so you *do* have the ability to override OPTIONS settings
-via the command line.
-
-It is not recommended to move all the contents of your Makefiles into
-your source files, but in some circumstances, the \tr{OPTIONS} pragma
-is the Right Thing. (If you use \tr{-keep-hc-file-too} and have OPTION
-flags in your module, the OPTIONS will get put into the generated .hc
-file).
-
-%----------------------------------------------------------------------
-\subsubsection{How to compile mutually recursive modules}
-\index{module system, recursion}
-
-Currently, the compiler does not have proper support for dealing with
-mutually recursive modules:
-
-\begin{verbatim}
-module A where
-
-import B
-
-newtype A = A Int
-
-f :: B -> A
-f (B x) = A x
---------
-module B where
-
-import A
-
-data B = B !Int
-
-g :: A -> B
-g (A x) = B x
-\end{verbatim}
-
-When compiling either module A and B, the compiler will try (in vain)
-to look for the interface file of the other. So, to get mutually
-recursive modules off the ground, you need to hand write an interface
-file for A or B, so as to break the loop. For the example at hand, the
-boot interface file for A would like the following:
-
-\begin{verbatim}
-_interface_ A 1
-_exports_
-A A(A) f;
-_declarations_
-1 newtype A = A PrelBase.Int ;
-1 f _:_ B.B -> A.A ;;
-\end{verbatim}
-
-To make sure you get the syntax right, tailoring an existing interface
-file is a Good Idea.
-
-{\bf Note:} This is all a temporary solution, a version of the compiler
-that handles mutually recursive properly without the manual
-construction of interface file, is in the works.
-
-%----------------------------------------------------------------------
-%\subsubsection[arity-checking]{Options to insert arity-checking code}
-%\index{arity checking}
-%
-%The \tr{-darity-checks}\index{-darity-checks option} option inserts
-%code to check for arity violations. Unfortunately, it's not that
-%simple: you have to link with a prelude that was also built with arity
-%checks. If you have one, then great; otherwise...
-%
-%The \tr{-darity-checks-C-only}\index{-darity-checks-C-only option}
-%option inserts the self-same arity checking code into \tr{.hc} files,
-%but doesn't compile it into the \tr{.o} files. We use this flag with
-%the \tr{-keep-hc-file-too}\index{-keep-hc-file-too option}, where we
-%are keeping \tr{.hc} files around for debugging purposes.
-
-%----------------------------------------------------------------------
-%\subsubsection[omit-checking]{Options to omit checking code}
-%\index{omitting runtime checks}
-%
-%By default, the GHC system emits all possible not-too-expensive
-%runtime checking code. If you are brave or experimenting, you might
-%want to turn off some of this (not recommended):
-%
-%\begin{tabular}{ll}
-%-dno-black-holing & won't buy you much (even if it works) \\
-%-dno-updates & you're crazy if you do this \\
-%-dno-stk-stubbing & omit stack stubbing (NOT DONE YET) \\
-%\end{tabular}
-%\index{-dno-black-holing option}%
-%\index{-dno-updates option}%
-%\index{-dno-stk-stubbing option}
-%
-%Warning: all very lightly tested, if at all...
-
-%% %************************************************************************
-%% %* *
-%% \subsection[options-GC]{Choosing a garbage collector}
-%% %* *
-%% %************************************************************************
-%%
-%% (Note: you need a Good Reason before launching into this territory.)
-%%
-%% There are up to four garbage collectors to choose from (it depends how
-%% your local system was built); the Appel-style generational collector
-%% is the default.
-%%
-%% If you choose a non-default collector, you must specify it both when
-%% compiling the modules and when linking them together into an
-%% executable. Also, the native-code generator only works with the
-%% default collector (a small point to bear in mind).
-%%
-%% \begin{description}
-%% \item[\tr{-gc-ap} option:]
-%% \index{-gc-ap option}
-%% Appel-like generational collector (the default).
-%%
-%% \item[\tr{-gc-2s} option:]
-%% \index{-gc-2s option}
-%% Two-space copying collector.
-%%
-%% \item[\tr{-gc-1s} option:]
-%% \index{-gc-1s option}
-%% One-space compacting collector.
-%%
-%% \item[\tr{-gc-du} option:]
-%% \index{-gc-du option}
-%% Dual-mode collector (swaps between copying and compacting).
-%% \end{description}
+++ /dev/null
-%
-% $Header: /srv/cvs/cvs.haskell.org/fptools/ghc/docs/users_guide/Attic/intro.lit,v 1.5 1997/06/06 22:19:30 sof Exp $
-%
-\section[introduction-GHC]{Introduction to GHC}
-
-This is a guide to using the Glasgow Haskell compilation (GHC) system.
-It is a batch compiler for the Haskell~1.4 language, with support for
-various Glasgow-only extensions.
-
-Many people will use GHC very simply: compile some
-modules---\tr{ghc -c -O Foo.hs Bar.hs}; and link them---
-\tr{ghc -o wiggle -O Foo.o Bar.o}.
-
-But if you need to do something more complicated, GHC can do that,
-too:
-\begin{verbatim}
-ghc -c -O -fno-foldr-build -dcore-lint -fvia-C -ddump-simpl Foo.lhs
-\end{verbatim}
-Stay tuned---all will be revealed!
-
-In this document, we assume that GHC has been installed at your
-site as \tr{ghc}.
-If you are unfamiliar with the conventions of UNIX compilers, the
-material in \sectionref{compiler-tutorial} may help.
-
-%--------------------------------------------------------------------
-\section[mailing-lists-GHC]{Knowing us, knowing you: Web sites, mailing lists, etc.}
-\index{mailing lists, Glasgow Haskell}
-\index{Glasgow Haskell mailing lists}
-
-On the World-Wide Web, there are several URLs of likely interest:
-\begin{display}
-Haskell home page -- \tr{http://haskell.org/}
-GHC home page -- \tr{http://www.dcs.gla.ac.uk/fp/software/ghc/}
-Glasgow FP group page -- \tr{http://www.dcs.gla.ac.uk/fp/}
-comp.lang.functional FAQ --
- \tr{http://www.cs.nott.ac.uk/Department/Staff/mpj/faq.html}
-\end{display}
-We run two mailing lists about Glasgow Haskell. We encourage you to
-join, as you feel is appropriate.
-\begin{description}
-\item[glasgow-haskell-users:]
-This list is for GHC users to chat among themselves. Subscribe by
-sending mail to \tr{majordomo@dcs.gla.ac.uk}, with
-a message body (not header) like this:
-\begin{verbatim}
-subscribe glasgow-haskell-users My Name <m.y.self@bigbucks.com>
-\end{verbatim}
-(The last bit is your all-important e-mail address, of course.)
-
-To communicate with your fellow users, send mail to \tr{glasgow-haskell-users}.
-
-To contact the list administrator, send mail to
-\tr{glasgow-haskell-users-request}. An archive of the list is
-available on the Web at:
-\begin{verbatim}
-http://www.dcs.gla.ac.uk/mail-www/glasgow-haskell-users
-\end{verbatim}
-
-\item[glasgow-haskell-bugs:]
-Send bug reports for GHC to this address! The sad and lonely people
-who subscribe to this list will muse upon what's wrong and what you
-might do about it.
-
-Subscribe via \tr{majordomo@dcs.gla.ac.uk} with:
-\begin{verbatim}
-subscribe glasgow-haskell-bugs My Name <m.y.self@hackers.r.us>
-\end{verbatim}
-
-Again, you may contact the list administrator at
-\tr{glasgow-haskell-bugs-request}.
-And, yes, an archive of the list is
-available on the Web at:
-\begin{verbatim}
-http://www.dcs.gla.ac.uk/mail-www/glasgow-haskell-bugs
-\end{verbatim}
-\end{description}
-
-There is also the general Haskell mailing list. Subscribe by sending
-email to \tr{majordomo@dcs.gla.ac.uk}, with the usual message body:
-\begin{verbatim}
-subscribe haskell My Name <m.y.self@fp.rules.ok.org>
-\end{verbatim}
-
-Some Haskell-related discussion takes place in the Usenet newsgroup
-\tr{comp.lang.functional}. (But note: news is basically dead at Glasgow.
-That's one reason Glaswegians aren't too active in c.f.l.)
-
-The main anonymous-FTP site for Glasgow Haskell is
-\tr{ftp.dcs.gla.ac.uk}, in \tr{pub/haskell/glasgow/}.
-``Important'' bits are mirrored at other Haskell archive sites (and we
-have their stuff, too).
-
--- /dev/null
+<sect>Introduction to GHC
+<label id="introduction-GHC">
+<p>
+
+This is a guide to using the Glasgow Haskell compilation (GHC) system.
+It is a batch compiler for the Haskell~1.4 language, with support for
+various Glasgow-only extensions.
+
+Many people will use GHC very simply: compile some
+modules---@ghc -c -O Foo.hs Bar.hs@; and link them---
+@ghc -o wiggle -O Foo.o Bar.o@.
+
+But if you need to do something more complicated, GHC can do that,
+too:
+<tscreen><verb>
+ghc -c -O -fno-foldr-build -dcore-lint -fvia-C -ddump-simpl Foo.lhs
+</verb></tscreen>
+Stay tuned---all will be revealed!
+
+In this document, we assume that GHC has been installed at your site
+as @ghc@. The rest of this section provide some tutorial information
+on batch-style compilation; if you're familiar with these concepts
+already, then feel free to skip to the next section.
+
+%************************************************************************
+%* *
+<sect1>The (batch) compilation system components
+<label id="batch-system-parts">
+<p>
+%* *
+%************************************************************************
+
+The Glorious Haskell Compilation System, as with most UNIX (batch)
+compilation systems, has several interacting parts:
+<enum>
+<item>
+A <em>driver</em><nidx>driver program</nidx> @ghc@<nidx>ghc</nidx>---which you
+usually think of as ``the compiler''---is a program that merely
+invokes/glues-together the other pieces of the system (listed below),
+passing the right options to each, slurping in the right libraries,
+etc.
+
+<item>
+A <em>literate pre-processor</em>
+<nidx>literate pre-processor</nidx>
+<nidx>pre-processor, literate</nidx>
+@unlit@<nidx>unlit</nidx> that extracts Haskell
+code from a literate script; used if you believe in that sort of
+thing.
+
+<item>
+The <em>Haskellised C pre-processor</em>
+<nidx>Haskellised C pre-processor</nidx>
+<nidx>C pre-processor, Haskellised</nidx>
+<nidx>pre-processor, Haskellised C</nidx>
+@hscpp@,<nidx>hscpp</nidx> only needed by people requiring conditional
+compilation, probably for large systems. The ``Haskellised'' part
+just means that @#line@ directives in the output have been
+converted into proper Haskell @{-# LINE ... -@} pragmas.
+
+You must give an explicit @-cpp@ option
+<nidx>-cpp option</nidx> for the C pre-processor to be invoked.
+
+<item>
+The <em>Haskell compiler</em>
+<nidx>Haskell compiler</nidx>
+<nidx>compiler, Haskell</nidx>
+@hsc@,<nidx>hsc</nidx>
+which---in normal use---takes its input from the C pre-processor
+and produces assembly-language output (sometimes: ANSI C output).
+
+<item>
+The <em>ANSI~C Haskell high-level assembler :-)</em>
+<nidx>ANSI C compiler</nidx>
+<nidx>high-level assembler</nidx>
+<nidx>assembler, high-level</nidx>
+compiles @hsc@'s C output into assembly language for a particular
+target architecture. (It doesn't have to be an ANSI C compiler, but
+that's preferred; to go fastest, you need GNU C, version 2.x.)
+
+<item>
+The <em>assembler</em><nidx>assembler</nidx>---a standard UNIX one, probably
+@as@<nidx>as</nidx>.
+
+<item>
+The <em>linker</em><nidx>linker</nidx>---a standard UNIX one, probably
+@ld@.<nidx>ld</nidx>
+
+<item>
+A <em>runtime system</em>,<nidx>runtime system</nidx> including (most notably)
+a storage manager; the linker links in the code for this.
+
+<item>
+The <em>Haskell standard prelude</em><nidx>standard prelude</nidx>, a
+large library of standard functions, is linked in as well.
+
+<item>
+Parts of other <em>installed libraries</em> that you have at your site
+may be linked in also.
+</enum>
+
+%************************************************************************
+%* *
+<sect1>What really happens when I ``compile'' a Haskell program?
+<label id="compile-what-really-happens">
+<p>
+%* *
+%************************************************************************
+
+You invoke the Glasgow Haskell compilation system through the
+driver program @ghc@.<nidx>ghc</nidx> For example, if you had typed a
+literate ``Hello, world!'' program into @hello.lhs@, and you then
+invoked:
+<tscreen><verb>
+ghc hello.lhs
+</verb></tscreen>
+
+the following would happen:
+<enum>
+<item>
+The file @hello.lhs@ is run through the literate-program
+code extractor @unlit@<nidx>unlit</nidx>, feeding its output to
+
+<item>
+The Haskell compiler proper @hsc@<nidx>hsc</nidx>, which produces
+input for
+
+<item>
+The assembler (or that ubiquitous ``high-level assembler,'' a C
+compiler), which produces an object file and passes it to
+
+<item>
+The linker, which links your code with the appropriate libraries
+(including the standard prelude), producing an executable program in
+the default output file named @a.out@.
+</enum>
+
+You have considerable control over the compilation process. You feed
+command-line arguments (call them ``options,'' for short) to the
+driver, @ghc@; the ``types'' of the input files (as encoded in
+their names' suffixes) also matter.
+
+Here's hoping this is enough background so that you can read the rest
+of this guide!
+
+% The ``style'' of the driver program @ghc@ follows that of the GNU C
+% compiler driver @gcc@. The use of environment variables to provide
+% defaults is more extensive in this compilation system.
+
+%--------------------------------------------------------------------
+<sect1>Meta-information: Web sites, mailing lists, etc.
+<label id="mailing-lists-GHC">
+<p>
+<nidx>mailing lists, Glasgow Haskell</nidx>
+<nidx>Glasgow Haskell mailing lists</nidx>
+
+On the World-Wide Web, there are several URLs of likely interest:
+
+<itemize>
+<item> <url name="Haskell home page" url="http://haskell.org/">
+<item> <url name="GHC home page" url="http://www.dcs.gla.ac.uk/fp/software/ghc/">
+<item> <url name="Glasgow FP group page" url="http://www.dcs.gla.ac.uk/fp/">
+<item> <url name="comp.lang.functional FAQ" url="http://www.cs.nott.ac.uk/Department/Staff/mpj/faq.html">
+</itemize>
+
+We run two mailing lists about Glasgow Haskell. We encourage you to
+join, as you feel is appropriate.
+
+<descrip>
+
+<tag>glasgow-haskell-users:</tag>
+
+This list is for GHC users to chat among themselves. Subscribe by
+sending mail to <htmlurl name="majordomo@@dcs.gla.ac.uk"
+url="mailto:majordomo@@dcs.gla.ac.uk">, with a message body (not
+header) like this:
+
+<tscreen><verb>
+subscribe glasgow-haskell-users MyName <m.y.self@@bigbucks.com>
+</verb></tscreen>
+
+(The last bit is your all-important e-mail address, of course.)
+
+To communicate with your fellow users, send mail to <url
+name="glasgow-haskell-users@@dcs.gla.ac.uk"
+url="mailto:glasgow-haskell-users@@dcs.gla.ac.uk">.
+
+To contact the list administrator, send mail to <htmlurl
+name="glasgow-haskell-users-request@@dcs.gla.ac.uk"
+url="mailto:glasgow-haskell-users-request@@dcs.gla.ac.uk">. An archive
+of the list is available on the Web: <url name="glasgow-haskell-users
+mailing list archive"
+url="http://www.dcs.gla.ac.uk/mail-www/glasgow-haskell-users">.
+
+<tag>glasgow-haskell-bugs:</tag>
+Send bug reports for GHC to this address! The sad and lonely people
+who subscribe to this list will muse upon what's wrong and what you
+might do about it.
+
+Subscribe via <htmlurl name="majordomo@@dcs.gla.ac.uk"
+url="mailto:majordomo@@dcs.gla.ac.uk"> with:
+
+<tscreen><verb>
+subscribe glasgow-haskell-bugs My Name <m.y.self@@hackers.r.us>
+</verb></tscreen>
+
+Again, you may contact the list administrator at <htmlurl
+name="glasgow-haskell-bugs-request@@dcs.gla.ac.uk"
+url="mailto:glasgow-haskell-bugs-request@@dcs.gla.ac.uk">.
+And, yes, an archive of the list is available on the Web at: : <url
+name="glasgow-haskell-bugs mailing list archive"
+url="http://www.dcs.gla.ac.uk/mail-www/glasgow-haskell-bugs">
+
+</descrip>
+
+There is also the general Haskell mailing list. Subscribe by sending
+email to <htmlurl name="majordomo@@dcs.gla.ac.uk"
+url="mailto:majordomo@@dcs.gla.ac.uk">, with the usual message body:
+
+<tscreen><verb>
+subscribe haskell My Name <m.y.self@@fp.rules.ok.org>
+</verb></tscreen>
+
+Some Haskell-related discussion takes place in the Usenet newsgroup
+@comp.lang.functional@. (But note: news is basically dead at Glasgow.
+That's one reason Glaswegians aren't too active in c.f.l.)
+
+The main anonymous-FTP site for Glasgow Haskell is <htmlurl
+name="ftp://ftp.dcs.gla.ac.uk/pub/haskell/glasgow"
+url="ftp://ftp.dcs.gla.ac.uk/pub/haskell/glasgow">. ``Important''
+bits are mirrored at other Haskell archive sites (and we have their
+stuff, too).
--- /dev/null
+%************************************************************************
+%* *
+<sect>GHC Language Features
+<label id="ghc-language-features">
+<p>
+<nidx>language, GHC</nidx>
+<nidx>extensions, GHC</nidx>
+%* *
+%************************************************************************
--- /dev/null
+%************************************************************************
+%* *
+<sect1>Miscellaneous libraries
+<label id="GHC-library">
+<p>
+<nidx>libraries, miscellaneous</nidx>
+<nidx>misc, syslib</nidx>
+%* *
+%************************************************************************
+
+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 @-syslib misc@<nidx>-syslib misc option</nidx>.
+
+%************************************************************************
+%* *
+<sect2>The @Bag@ type
+<label id="Bag">
+<p>
+<nidx>Bag module (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+A <em>bag</em> is an unordered collection of elements which may contain
+duplicates. To use, @import Bag@.
+
+<tscreen><verb>
+data Bag elt -- abstract
+
+emptyBag :: Bag elt
+unitBag :: elt -> Bag elt
+
+consBag :: elt -> Bag elt -> Bag elt
+snocBag :: Bag elt -> elt -> Bag elt
+
+unionBags :: Bag elt -> Bag elt -> Bag elt
+unionManyBags :: [Bag elt] -> Bag elt
+
+isEmptyBag :: Bag elt -> Bool
+elemBag :: Eq elt => elt -> Bag elt -> Bool
+
+filterBag :: (elt -> Bool) -> Bag elt -> Bag elt
+partitionBag :: (elt -> Bool) -> Bag elt-> (Bag elt, Bag elt)
+ -- returns the elements that do/don't satisfy the predicate
+
+concatBag :: Bag (Bag a) -> Bag a
+foldBag :: (r -> r -> r) -> (a -> r) -> r -> Bag a -> r
+mapBag :: (a -> b) -> Bag a -> Bag b
+
+listToBag :: [elt] -> Bag elt
+bagToList :: Bag elt -> [elt]
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>The @FiniteMap@ type
+<label id="FiniteMap">
+<p>
+<nidx>FiniteMap module (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+What functional programmers call a <em>finite map</em>, everyone else
+calls a <em>lookup table</em>.
+
+Out code is derived from that in this paper:
+<quote>
+S Adams
+"Efficient sets: a balancing act"
+Journal of functional programming 3(4) Oct 1993, pages 553-562
+</quote>
+Guess what? The implementation uses balanced trees.
+
+<tscreen><verb>
+data FiniteMap key elt -- abstract
+
+-- BUILDING
+emptyFM :: FiniteMap key elt
+unitFM :: key -> elt -> FiniteMap key elt
+listToFM :: Ord key => [(key,elt)] -> FiniteMap key elt
+ -- In the case of duplicates, the last is taken
+
+-- ADDING AND DELETING
+ -- Throws away any previous binding
+ -- In the list case, the items are added starting with the
+ -- first one in the list
+addToFM :: Ord key => FiniteMap key elt -> key -> elt -> FiniteMap key elt
+addListToFM :: Ord key => FiniteMap key elt -> [(key,elt)] -> FiniteMap key elt
+
+ -- Combines with previous binding
+ -- In the combining function, the first argument is
+ -- the "old" element, while the second is the "new" one.
+addToFM_C :: Ord key => (elt -> elt -> elt)
+ -> FiniteMap key elt -> key -> elt
+ -> FiniteMap key elt
+addListToFM_C :: Ord key => (elt -> elt -> elt)
+ -> FiniteMap key elt -> [(key,elt)]
+ -> FiniteMap key elt
+
+ -- Deletion doesn't complain if you try to delete something
+ -- which isn't there
+delFromFM :: Ord key => FiniteMap key elt -> key -> FiniteMap key elt
+delListFromFM :: Ord key => FiniteMap key elt -> [key] -> FiniteMap key elt
+
+-- COMBINING
+ -- Bindings in right argument shadow those in the left
+plusFM :: Ord key => FiniteMap key elt -> FiniteMap key elt
+ -> FiniteMap key elt
+
+ -- Combines bindings for the same thing with the given function
+plusFM_C :: Ord key => (elt -> elt -> elt)
+ -> FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
+
+minusFM :: Ord key => FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
+ -- (minusFM a1 a2) deletes from a1 any bindings which are bound in a2
+
+intersectFM :: Ord key => FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
+intersectFM_C :: Ord key => (elt -> elt -> elt)
+ -> FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
+
+-- MAPPING, FOLDING, FILTERING
+foldFM :: (key -> elt -> a -> a) -> a -> FiniteMap key elt -> a
+mapFM :: (key -> elt1 -> elt2) -> FiniteMap key elt1 -> FiniteMap key elt2
+filterFM :: Ord key => (key -> elt -> Bool)
+ -> FiniteMap key elt -> FiniteMap key elt
+
+-- INTERROGATING
+sizeFM :: FiniteMap key elt -> Int
+isEmptyFM :: FiniteMap key elt -> Bool
+
+elemFM :: Ord key => key -> FiniteMap key elt -> Bool
+lookupFM :: Ord key => FiniteMap key elt -> key -> Maybe elt
+lookupWithDefaultFM
+ :: Ord key => FiniteMap key elt -> elt -> key -> elt
+ -- lookupWithDefaultFM supplies a "default" elt
+ -- to return for an unmapped key
+
+-- LISTIFYING
+fmToList :: FiniteMap key elt -> [(key,elt)]
+keysFM :: FiniteMap key elt -> [key]
+eltsFM :: FiniteMap key elt -> [elt]
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>The @ListSetOps@ type
+<label id="ListSetOps">
+<p>
+<nidx>ListSetOps module (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+Just a few set-sounding operations on lists. If you want sets, use
+the @Set@ module.
+
+<tscreen><verb>
+unionLists :: Eq a => [a] -> [a] -> [a]
+intersectLists :: Eq a => [a] -> [a] -> [a]
+minusList :: Eq a => [a] -> [a] -> [a]
+disjointLists :: Eq a => [a] -> [a] -> Bool
+intersectingLists :: Eq a => [a] -> [a] -> Bool
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>The @Maybes@ type
+<label id="Maybes">
+<p>
+<nidx>Maybes module (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+The @Maybe@ type is in the Haskell 1.4 prelude. Moreover, the
+required @Maybe@ library provides many useful functions on
+@Maybe@s. This (pre-1.3) module provides some more:
+
+An @Either@-like type called @MaybeErr@:
+<tscreen><verb>
+data MaybeErr val err = Succeeded val | Failed err
+</verb></tscreen>
+
+Some operations to do with @Maybe@ (some commentary follows):
+<tscreen><verb>
+maybeToBool :: Maybe a -> Bool -- Nothing => False; Just => True
+allMaybes :: [Maybe a] -> Maybe [a]
+firstJust :: [Maybe a] -> Maybe a
+findJust :: (a -> Maybe b) -> [a] -> Maybe b
+
+assocMaybe :: Eq a => [(a,b)] -> a -> Maybe b
+mkLookupFun :: (key -> key -> Bool) -- Equality predicate
+ -> [(key,val)] -- The assoc list
+ -> (key -> Maybe val) -- A lookup fun to use
+mkLookupFunDef :: (key -> key -> Bool) -- Equality predicate
+ -> [(key,val)] -- The assoc list
+ -> val -- Value to return on failure
+ -> key -- The key
+ -> val -- The corresponding value
+
+ -- a monad thing
+thenMaybe :: Maybe a -> (a -> Maybe b) -> Maybe b
+returnMaybe :: a -> Maybe a
+failMaybe :: Maybe a
+mapMaybe :: (a -> Maybe b) -> [a] -> Maybe [b]
+</verb></tscreen>
+
+NB: @catMaybes@ which used to be here, is now available via the
+standard @Maybe@ interface (@Maybe@ is an instance of @MonadPlus@).
+
+@allMaybes@ collects a list of @Justs@ into a single @Just@, returning
+@Nothing@ if there are any @Nothings@.
+
+@firstJust@ takes a list of @Maybes@ and returns the
+first @Just@ if there is one, or @Nothing@ otherwise.
+
+@assocMaybe@ looks up in an association list, returning
+@Nothing@ if it fails.
+
+Now, some operations to do with @MaybeErr@ (comments follow):
+<tscreen><verb>
+ -- a monad thing (surprise, surprise)
+thenMaB :: MaybeErr a err -> (a -> MaybeErr b err) -> MaybeErr b err
+returnMaB :: val -> MaybeErr val err
+failMaB :: err -> MaybeErr val err
+
+listMaybeErrs :: [MaybeErr val err] -> MaybeErr [val] [err]
+foldlMaybeErrs :: (acc -> input -> MaybeErr acc err)
+ -> acc
+ -> [input]
+ -> MaybeErr acc [err]
+</verb></tscreen>
+
+@listMaybeErrs@ takes a list of @MaybeErrs@ and, if they all succeed,
+returns a @Succeeded@ of a list of their values. If any fail, it
+returns a @Failed@ of the list of all the errors in the list.
+
+@foldlMaybeErrs@ 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.
+
+%************************************************************************
+%* *
+<sect2>The @PackedString@ type
+<label id="PackedString">
+<p>
+<nidx>PackedString module (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+You need to @import PackedString@ and heave in your
+@-syslib ghc@ to use @PackedString@s.
+
+The basic type and functions available are:
+<tscreen><verb>
+data PackedString -- abstract
+
+packString :: [Char] -> PackedString
+packStringST :: [Char] -> ST s PackedString
+packCBytesST :: Int -> Addr -> ST s PackedString
+packBytesForCST :: [Char] -> ST s (ByteArray Int)
+byteArrayToPS :: ByteArray Int -> PackedString
+unsafeByteArrayToPS :: ByteArray a -> Int -> PackedString
+psToByteArray :: PackedString -> ByteArray Int
+psToByteArrayST :: PackedString -> ST s (ByteArray Int)
+
+unpackPS :: PackedString -> [Char]
+</verb></tscreen>
+
+We also provide a wad of list-manipulation-like functions:
+<tscreen><verb>
+nilPS :: PackedString
+consPS :: Char -> PackedString -> PackedString
+
+headPS :: PackedString -> Char
+tailPS :: PackedString -> PackedString
+nullPS :: PackedString -> Bool
+appendPS :: PackedString -> PackedString -> PackedString
+lengthPS :: PackedString -> Int
+indexPS :: PackedString -> Int -> Char
+ -- 0-origin indexing into the string
+mapPS :: (Char -> Char) -> PackedString -> PackedString
+filterPS :: (Char -> Bool) -> PackedString -> PackedString
+foldlPS :: (a -> Char -> a) -> a -> PackedString -> a
+foldrPS :: (Char -> a -> a) -> a -> PackedString -> a
+takePS :: Int -> PackedString -> PackedString
+dropPS :: Int -> PackedString -> PackedString
+splitAtPS :: Int -> PackedString -> (PackedString, PackedString)
+takeWhilePS :: (Char -> Bool) -> PackedString -> PackedString
+dropWhilePS :: (Char -> Bool) -> PackedString -> PackedString
+spanPS :: (Char -> Bool) -> PackedString -> (PackedString, PackedString)
+breakPS :: (Char -> Bool) -> PackedString -> (PackedString, PackedString)
+linesPS :: PackedString -> [PackedString]
+wordsPS :: PackedString -> [PackedString]
+reversePS :: PackedString -> PackedString
+concatPS :: [PackedString] -> PackedString
+elemPS :: Char -> PackedString -> Bool
+ -- Perl-style split&join
+splitPS :: Char -> PackedString -> [PackedString]
+splitWithPS :: (Char -> Bool) -> PackedString -> [PackedString]
+joinPS :: PackedString -> [PackedString] -> PackedString
+
+substrPS :: PackedString -> Int -> Int -> PackedString
+ -- pluck out a piece of a PackedString
+ -- start and end chars you want; both 0-origin-specified
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>The @Pretty@ type
+<label id="Pretty">
+<p>
+<nidx>Pretty module (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+This is the pretty-printer that is currently used in GHC:
+
+<tscreen><verb>
+type Pretty
+
+ppShow :: Int{-width-} -> Pretty -> [Char]
+
+pp'SP :: Pretty -- "comma space"
+ppComma :: Pretty -- ,
+ppEquals :: Pretty -- =
+ppLbrack :: Pretty -- [
+ppLparen :: Pretty -- (
+ppNil :: Pretty -- nothing
+ppRparen :: Pretty -- )
+ppRbrack :: Pretty -- ]
+ppSP :: Pretty -- space
+ppSemi :: Pretty -- ;
+
+ppChar :: Char -> Pretty
+ppDouble :: Double -> Pretty
+ppFloat :: Float -> Pretty
+ppInt :: Int -> Pretty
+ppInteger :: Integer -> Pretty
+ppRational :: Rational -> Pretty
+ppStr :: [Char] -> Pretty
+
+ppAbove :: Pretty -> Pretty -> Pretty
+ppAboves :: [Pretty] -> Pretty
+ppBeside :: Pretty -> Pretty -> Pretty
+ppBesides :: [Pretty] -> Pretty
+ppCat :: [Pretty] -> Pretty
+ppHang :: Pretty -> Int -> Pretty -> Pretty
+ppInterleave :: Pretty -> [Pretty] -> Pretty -- spacing between
+ppIntersperse :: Pretty -> [Pretty] -> Pretty -- no spacing between
+ppNest :: Int -> Pretty -> Pretty
+ppSep :: [Pretty] -> Pretty
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>The @Set@ type
+<label id="Set">
+<p>
+<nidx>Set module (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+Our implementation of <em>sets</em> (key property: no duplicates) is just
+a variant of the @FiniteMap@ module.
+
+<tscreen><verb>
+data Set -- abstract
+ -- instance of: Eq
+
+emptySet :: Set a
+mkSet :: Ord a => [a] -> Set a
+setToList :: Set a -> [a]
+unitSet :: a -> Set a
+singletonSet :: a -> Set a -- deprecated, use unitSet.
+
+union :: Ord a => Set a -> Set a -> Set a
+unionManySets :: Ord a => [Set a] -> Set a
+minusSet :: Ord a => Set a -> Set a -> Set a
+mapSet :: Ord a => (b -> a) -> Set b -> Set a
+intersect :: Ord a => Set a -> Set a -> Set a
+
+elementOf :: Ord a => a -> Set a -> Bool
+isEmptySet :: Set a -> Bool
+
+cardinality :: Set a -> Int
+
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>The @BitSet@ interface
+<label id="BitSet">
+<p>
+<nidx>Bitset interface (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+Bit sets are a fast implementation of sets of integers ranging from 0
+to one less than the number of bits in a machine word (typically 31).
+If any element exceeds the maximum value for a particular machine
+architecture, the results of these operations are undefined. You have
+been warned.
+
+<tscreen><verb>
+data BitSet -- abstract
+ -- instance of:
+
+emptyBS :: BitSet
+mkBS :: [Int] -> BitSet
+unitBS :: Int -> BitSet
+unionBS :: BitSet -> BitSet -> BitSet
+minusBS :: BitSet -> BitSet -> BitSet
+isEmptyBS :: BitSet -> Bool
+intersectBS :: BitSet -> BitSet -> BitSet
+elementBS :: Int -> BitSet -> Bool
+listBS :: BitSet -> [Int]
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>The @Util@ type
+<label id="Util">
+<p>
+<nidx>Util module (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+Stuff that has been generally useful to use in writing the compiler.
+Don't be too surprised if this stuff moves/gets-renamed/etc.
+
+<tscreen><verb>
+-- general list processing
+forall :: (a -> Bool) -> [a] -> Bool
+exists :: (a -> Bool) -> [a] -> Bool
+
+nOfThem :: Int -> a -> [a]
+lengthExceeds :: [a] -> Int -> Bool
+isSingleton :: [a] -> Bool
+
+--paranoid zip'ing (equal length lists)
+zipEqual :: [a] -> [b] -> [(a,b)]
+zipWithEqual :: String -> (a->b->c) -> [a]->[b]->[c]
+zipWith3Equal :: String -> (a->b->c->d) -> [a]->[b]->[c]->[d]
+zipWith4Equal :: String -> (a->b->c->d->e) -> [a]->[b]->[c]->[d]->[e]
+-- lazy in second argument
+zipLazy :: [a] -> [b] -> [(a,b)]
+
+mapAndUnzip :: (a -> (b, c)) -> [a] -> ([b], [c])
+mapAndUnzip3 :: (a -> (b, c, d)) -> [a] -> ([b], [c], [d])
+
+-- prefix and suffix matching on lists of characters.
+startsWith :: {-prefix-}String -> String -> Maybe String
+endsWith :: {-suffix-}String -> String -> Maybe String
+
+-- association lists
+assoc :: Eq a => String -> [(a, b)] -> a -> b
+
+-- duplicate handling
+hasNoDups :: Eq a => [a] -> Bool
+equivClasses :: (a -> a -> Ordering) -> [a] -> [[a]]
+runs :: (a -> a -> Bool) -> [a] -> [[a]]
+removeDups :: (a -> a -> Ordering) -> [a] -> ([a], [[a]])
+
+-- sorting (don't complain of no choice...)
+quicksort :: (a -> a -> Bool) -> [a] -> [a]
+sortLt :: (a -> a -> Bool) -> [a] -> [a]
+stableSortLt :: (a -> a -> Bool) -> [a] -> [a]
+mergesort :: (a -> a -> _CMP_TAG) -> [a] -> [a]
+mergeSort :: Ord a => [a] -> [a]
+naturalMergeSort :: Ord a => [a] -> [a]
+mergeSortLe :: Ord a => [a] -> [a]
+naturalMergeSortLe :: Ord a => [a] -> [a]
+
+-- transitive closures
+transitiveClosure :: (a -> [a]) -- Successor function
+ -> (a -> a -> Bool) -- Equality predicate
+ -> [a]
+ -> [a] -- The transitive closure
+
+-- accumulating (Left, Right, Bi-directional)
+mapAccumL :: (acc -> x -> (acc, y))
+ -- Function of elt of input list and
+ -- accumulator, returning new accumulator and
+ -- elt of result list
+ -> acc -- Initial accumulator
+ -> [x] -- Input list
+ -> (acc, [y]) -- Final accumulator and result list
+
+mapAccumR :: (acc -> x -> (acc, y)) -> acc -> [x] -> (acc, [y])
+
+mapAccumB :: (accl -> accr -> x -> (accl, accr,y))
+ -> accl -> accr -> [x]
+ -> (accl, accr, [y])
+
+--list comparison with explicit element comparer.
+cmpList :: (a -> a -> Ordering) -> [a] -> [a] -> Ordering
+
+-- pairs
+applyToPair :: ((a -> c), (b -> d)) -> (a, b) -> (c, d)
+applyToFst :: (a -> c) -> (a, b) -> (c, b)
+applyToSnd :: (b -> d) -> (a, b) -> (a, d)
+foldPair :: (a->a->a, b->b->b) -> (a, b) -> [(a, b)] -> (a, b)
+unzipWith :: (a -> b -> c) -> [(a, b)] -> [c]
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect1>Interfaces to C libraries
+<label id="C-interfaces">
+<p>
+<nidx>C library interfaces</nidx>
+<nidx>interfaces, C library</nidx>
+%* *
+%************************************************************************
+
+The GHC system library (@-syslib ghc@) also provides interfaces to
+several useful C libraries, mostly from the GNU project.
+
+%************************************************************************
+%* *
+<sect2>The @Readline@ interface
+<label id="Readline">
+<p>
+<nidx>Readline library (GHC syslib)</nidx>
+<nidx>command-line editing library</nidx>
+%* *
+%************************************************************************
+
+(Darren Moffat supplied the @Readline@ interface.)
+
+The @Readline@ module is a straightforward interface to the GNU
+Readline library. As such, you will need to look at the GNU
+documentation (and have a @libreadline.a@ file around somewhere...)
+
+You'll need to link any Readlining program with @-lreadline -ltermcap@,
+besides the usual @-syslib ghc@ (and @-fhaskell-1.3@).
+
+The main function you'll use is:
+<tscreen><verb>
+readline :: String{-the prompt-} -> IO String
+</verb></tscreen>
+
+If you want to mess around with Full Readline G(l)ory, we also
+provide:
+<tscreen><verb>
+rlInitialize, addHistory,
+
+rlBindKey, rlAddDefun, RlCallbackFunction(..),
+
+rlGetLineBuffer, rlSetLineBuffer, rlGetPoint, rlSetPoint, rlGetEnd,
+rlSetEnd, rlGetMark, rlSetMark, rlSetDone, rlPendingInput,
+
+rlPrompt, rlTerminalName, rlSetReadlineName, rlGetReadlineName
+</verb></tscreen>
+(All those names are just Haskellised versions of what you
+will see in the GNU readline documentation.)
+
+%************************************************************************
+%* *
+<sect2>The @Regexp@ and @MatchPS@ interfaces
+<label id="Regexp">
+<p>
+<nidx>Regex library (GHC syslib)</nidx>
+<nidx>MatchPS library (GHC syslib)</nidx>
+<nidx>regular-expressions library</nidx>
+%* *
+%************************************************************************
+
+(Sigbjorn Finne supplied the regular-expressions interface.)
+
+The @Regex@ library provides quite direct interface to the GNU
+regular-expression library, for doing manipulation on
+@PackedString@s. You probably need to see the GNU documentation
+if you are operating at this level.
+
+The datatypes and functions that @Regex@ provides are:
+<tscreen><verb>
+data PatBuffer # just a bunch of bytes (mutable)
+
+data REmatch
+ = REmatch (Array Int GroupBounds) -- for $1, ... $n
+ GroupBounds -- for $` (everything before match)
+ GroupBounds -- for $& (entire matched string)
+ GroupBounds -- for $' (everything after)
+ GroupBounds -- for $+ (matched by last bracket)
+
+-- GroupBounds hold the interval where a group
+-- matched inside a string, e.g.
+--
+-- matching "reg(exp)" "a regexp" returns the pair (5,7) for the
+-- (exp) group. (PackedString indices start from 0)
+
+type GroupBounds = (Int, Int)
+
+re_compile_pattern
+ :: PackedString -- pattern to compile
+ -> Bool -- True <=> assume single-line mode
+ -> Bool -- True <=> case-insensitive
+ -> PrimIO PatBuffer
+
+re_match :: PatBuffer -- compiled regexp
+ -> PackedString -- string to match
+ -> Int -- start position
+ -> Bool -- True <=> record results in registers
+ -> PrimIO (Maybe REmatch)
+
+-- Matching on 2 strings is useful when you're dealing with multiple
+-- buffers, which is something that could prove useful for
+-- PackedStrings, as we don't want to stuff the contents of a file
+-- into one massive heap chunk, but load (smaller chunks) on demand.
+
+re_match2 :: PatBuffer -- 2-string version
+ -> PackedString
+ -> PackedString
+ -> Int
+ -> Int
+ -> Bool
+ -> PrimIO (Maybe REmatch)
+
+re_search :: PatBuffer -- compiled regexp
+ -> PackedString -- string to search
+ -> Int -- start index
+ -> Int -- stop index
+ -> Bool -- True <=> record results in registers
+ -> PrimIO (Maybe REmatch)
+
+re_search2 :: PatBuffer -- Double buffer search
+ -> PackedString
+ -> PackedString
+ -> Int -- start index
+ -> Int -- range (?)
+ -> Int -- stop index
+ -> Bool -- True <=> results in registers
+ -> PrimIO (Maybe REmatch)
+</verb></tscreen>
+
+The @MatchPS@ module provides Perl-like ``higher-level'' facilities
+to operate on @PackedStrings@. The regular expressions in
+question are in Perl syntax. The ``flags'' on various functions can
+include: @i@ for case-insensitive, @s@ for single-line mode, and
+@g@ for global. (It's probably worth your time to peruse the
+source code...)
+
+<tscreen><verb>
+matchPS :: PackedString -- regexp
+ -> PackedString -- string to match
+ -> [Char] -- flags
+ -> Maybe REmatch -- info about what matched and where
+
+searchPS :: PackedString -- regexp
+ -> PackedString -- string to match
+ -> [Char] -- flags
+ -> Maybe REmatch
+
+-- Perl-like match-and-substitute:
+substPS :: PackedString -- regexp
+ -> PackedString -- replacement
+ -> [Char] -- flags
+ -> PackedString -- string
+ -> PackedString
+
+-- same as substPS, but no prefix and suffix:
+replacePS :: PackedString -- regexp
+ -> PackedString -- replacement
+ -> [Char] -- flags
+ -> PackedString -- string
+ -> PackedString
+
+match2PS :: PackedString -- regexp
+ -> PackedString -- string1 to match
+ -> PackedString -- string2 to match
+ -> [Char] -- flags
+ -> Maybe REmatch
+
+search2PS :: PackedString -- regexp
+ -> PackedString -- string to match
+ -> PackedString -- string to match
+ -> [Char] -- flags
+ -> Maybe REmatch
+
+-- functions to pull the matched pieces out of an REmatch:
+
+getMatchesNo :: REmatch -> Int
+getMatchedGroup :: REmatch -> Int -> PackedString -> PackedString
+getWholeMatch :: REmatch -> PackedString -> PackedString
+getLastMatch :: REmatch -> PackedString -> PackedString
+getAfterMatch :: REmatch -> PackedString -> PackedString
+
+-- (reverse) brute-force string matching;
+-- Perl equivalent is index/rindex:
+findPS, rfindPS :: PackedString -> PackedString -> Maybe Int
+
+-- Equivalent to Perl "chop" (off the last character, if any):
+chopPS :: PackedString -> PackedString
+
+-- matchPrefixPS: tries to match as much as possible of strA starting
+-- from the beginning of strB (handy when matching fancy literals in
+-- parsers):
+matchPrefixPS :: PackedString -> PackedString -> Int
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>Network-interface toolkit---@Socket@ and @SocketPrim@
+<label id="Socket">
+<p>
+<nidx>SocketPrim interface (GHC syslib)</nidx>
+<nidx>Socket interface (GHC syslib)</nidx>
+<nidx>network-interface library</nidx>
+<nidx>sockets library</nidx>
+<nidx>BSD sockets library</nidx>
+%* *
+%************************************************************************
+
+(Darren Moffat supplied the network-interface toolkit.)
+
+Your best bet for documentation is to look at the code---really!---
+normally in @fptools/ghc/lib/misc/{BSD,Socket,SocketPrim@.lhs}.
+
+The @BSD@ module provides functions to get at system-database info;
+pretty straightforward if you're into this sort of thing:
+<tscreen><verb>
+getHostName :: IO String
+
+getServiceByName :: ServiceName -> IO ServiceEntry
+getServicePortNumber:: ServiceName -> IO PortNumber
+getServiceEntry :: IO ServiceEntry
+setServiceEntry :: Bool -> IO ()
+endServiceEntry :: IO ()
+
+getProtocolByName :: ProtocolName -> IO ProtocolEntry
+getProtocolByNumber :: ProtocolNumber -> IO ProtcolEntry
+getProtocolNumber :: ProtocolName -> ProtocolNumber
+getProtocolEntry :: IO ProtocolEntry
+setProtocolEntry :: Bool -> IO ()
+endProtocolEntry :: IO ()
+
+getHostByName :: HostName -> IO HostEntry
+getHostByAddr :: Family -> HostAddress -> IO HostEntry
+getHostEntry :: IO HostEntry
+setHostEntry :: Bool -> IO ()
+endHostEntry :: IO ()
+</verb></tscreen>
+
+The @SocketPrim@ interface provides quite direct access to the
+socket facilities in a BSD Unix system, including all the
+complications. We hope you don't need to use it! See the source if
+needed...
+
+The @Socket@ interface is a ``higher-level'' interface to sockets,
+and it is what we recommend. Please tell us if the facilities it
+offers are inadequate to your task!
+
+The interface is relatively modest:
+<tscreen><verb>
+connectTo :: Hostname -> PortID -> IO Handle
+listenOn :: PortID -> IO Socket
+
+accept :: Socket -> IO (Handle, HostName)
+sendTo :: Hostname -> PortID -> String -> IO ()
+
+recvFrom :: Hostname -> PortID -> IO String
+socketPort :: Socket -> IO PortID
+
+data PortID -- PortID is a non-abstract type
+ = Service String -- Service Name eg "ftp"
+ | PortNumber Int -- User defined Port Number
+ | UnixSocket String -- Unix family socket in file system
+
+type Hostname = String
+</verb></tscreen>
+
+Various examples of networking Haskell code are provided in
+%@ghc/misc/examples/@, notably the @net???/Main.hs@ programs.
-\begin{onlystandalone}
-\documentstyle[a4wide,grasp]{article}
-\begin{rawlatex}
-\renewcommand{\textfraction}{0.1}
-\renewcommand{\floatpagefraction}{0.9}
-\renewcommand{\dblfloatpagefraction}{0.9}
-
-\sloppy
-\renewcommand{\today}{November 1997}
-\end{rawlatex}
-
-\begin{document}
-\title{The GHC Prelude and Libraries}
-\author{Simon L Peyton Jones \and Simon Marlow \and Will Partain}
-
-\maketitle
-\begin{rawlatex}
-\tableofcontents
-\end{rawlatex}
-\end{onlystandalone}
+%
+% $Id: libraries.vsgml,v 1.1 1998/01/30 17:02:32 simonm Exp $
+%
+% GHC Prelude and Libraries.
+%
-\section[ghc-prelude]{The GHC prelude and libraries}
+<sect>The GHC prelude and libraries
+<label id="ghc-prelude">
+<p>
This document describes GHC's prelude and libraries. The basic story is that of
the Haskell 1.4 Report and Libraries document (which we do not reproduce here),
but this document describes in addition:
-\begin{itemize}
-\item GHC's additional non-standard libraries and types, such as
+
+<itemize>
+
+<item> GHC's additional non-standard libraries and types, such as
state transformers, packed strings, foreign objects, stable
pointers, and so on.
-\item GHC's primitive types and operations. The standard Haskell
+<item> GHC's primitive types and operations. The standard Haskell
functions are implemented on top of these, and it is sometimes
useful to use them directly.
-\item The organisation of these libraries into directories.
-\item Short description of programmer interface to the non-standard,
- `built-in' libraries provided in addition to the standard
- prelude and libraries.
-\end{itemize}
-
-In addition to the GHC prelude libraries, GHC comes with a number of
-system libraries, which are presented in Section \ref{syslibs}.
-
-\subsection{Prelude library organisation}
-
-{\em Probably only of interest to implementors...}
-
-The prelude libraries are organised into the following three groups,
-each of which is kept in a separate sub-directory of GHC's source
-@lib/@ directory:
-\begin{description}
-\item[@lib/required/@] These are the libraries {\em required} by the
-Haskell definition. All are defined by the Haskell Report, or by the
-Haskell Libraries Report.
-They currently comprise:
-\begin{itemize}
-\item @Array@: monolithic arrays.
-\item @Char@: more functions on characters.
-\item @Complex@: interface defining complex number type and functions
-over it.
-\item @CPUTime@: get the CPU time used by the program.
-\item @Directory@: basic functions for accessing the file system.
-\item @Ix@: the @Ix@ class of indexing operations.
-\item @IO@: additional input/output functions.
-\item @List@: more functions on lists.
-\item @Locale@: localisation functions.
-\item @Maybe@: more functions on @Maybe@ types.
-\item @Monad@: functions on monads.
-\item @Numeric@: operations for reading and showing number values.
-\item @Prelude@: standard prelude interface.
-\item @Random@: pseudo-random number generator.
-\item @Ratio@: functions on rational numbers.
-\item @System@: basic operating-system interface functions.
-\item @Time@: operations on time.
-\end{itemize}
-
-\item[@lib/glaExts@] Extension libraries, currently comprising:
-\begin{itemize}
-\item @Addr@: primitive pointer type.
-\item @Bits@: a class of bitwise operations.
-\item @ByteArray@: operations over immutable chunks of (heap allocated) bytes.
-\item @CCall@: classes @CCallable@ and @CReturnable@ for calling C.
-\item @Foreign@: types and operations for GHC's foreign-language
-interface.
-\item @GlaExts@: interface for extensions that are only implemented in
-GHC: namely unboxed types and primitive operations.
-\item @IOExts@: extensions to the @IO@ library.
-\item @Int@: 8, 16, 32 and 64-bit integers with bit operations.
-\item @LazyST@: a lazy version of the @ST@ monad.
-\item @MutableArray@: operations over mutable arrays.
-\item @ST@: the state transformer monad, @STRef@s and @STArray@s.
-\item @Word@: 8, 16, 32 and 64-bit naturals with bit operations.
-\end{itemize}
-
-\item[@lib/concurrent@] GHC extension libraries to support Concurrent Haskell, currently comprising:
-\begin{itemize}
-\item @Concurrent@: main library.
-\item @Parallel@: stuff for multi-processor parallelism.
-\item @Channel@
-\item @ChannelVar@
-\item @Merge@
-\item @SampleVar@
-\item @Semaphore@
-\end{itemize}
-
-\item[@lib/ghc@] These libraries are the pieces on which all the
-others are built. They aren't typically imported by Joe Programmer,
-but there's nothing to stop you doing so if you want. In general, the
-modules prefixed by @Prel@ are pieces that go towards building
-@Prelude@.
-
-\begin{itemize}
-\item @GHC@: this ``library'' brings into scope all the primitive
-types and operations, such as @Int#@, @+#@, @encodeFloat#@, etc etc.
-It is unique in that there is no Haskell source code for it. Details
-in Section \ref{sect:ghc}.
-
-\item @PrelBase@: defines the basic types and classes without which
-very few Haskell programs can work. The classes are: @Eq@, @Ord@,
-@Enum@, @Bounded@, @Num@, @Show@, @Eval@, @Monad@, @MonadZero@,
-@MonadPlus@. The types are: list, @Bool@, @Char@, @Ordering@,
-@String@, @Int@, @Integer@.
-
-\item @PrelMaybe@: defines the @Maybe@ type.
-
-\item @PrelEither@: defines the @Either@ type.
-
-\item @PrelTup@: defines tuples and their instances.
-
-\item @PrelList@: defines most of the list operations required by
-@Prelude@. (A few are in @PrelBase@, to avoid gratuitous mutual
-recursion between modules.)
-
-\item @PrelNum@ defines: the numeric classes beyond @Num@, namely
-@Real@, @Integral@, @Fractional@, @Floating@, @RealFrac@, @RealFloat@;
-instances for appropriate classes for @Int@ and @Integer@; the types
-@Float@, @Double@, and @Ratio@ and their instances.
-
-\item @PrelRead@: the @Read@ class and all its instances. It's kept
-separate because many programs don't use @Read@ at all, so we don't
-even want to link in its code. (If the prelude libraries are built by
-splitting the object files, this is all a non-issue)
-
-\item @ConcBase@: substrate stuff for Concurrent Haskell.
-
-\item @IOBase@: substrate stuff for the main I/O libraries.
-\item @IOHandle@: large blob of code for doing I/O on handles.
-\item @PrelIO@: the remaining small pieces to produce the I/O stuff
-needed by @Prelude@.
-
-\item @STBase@: substrate stuff for @ST@.
-\item @ArrBase@: substrate stuff for @Array@.
-
-\item @GHCerr@: error reporting code, called from code that the
-compiler plants in compiled programs.
-
-\item @GHCmain@: the definition of @mainIO@, which is what {\em
- really} gets called by the runtime system. @mainIO@ in turn
- calls @main@.
-
-\item @PackBase@: low-level packing/unpacking operations.
-
-\item @Error@: the definition of @error@, placed in its own module
-with a hand-written @.hi-boot@ file in order to break recursive
-dependencies in the libraries (everything needs @error@, but the
-definition of @error@ itself needs a few things...).
-\end{itemize}
-\end{description}
-
-The @...Base@ modules generally export representation information that
-is hidden from the public interface. For example the module @STBase@
-exports the type @ST@ including its representation, whereas the module
-@ST@ exports @ST@ abstractly.
-
-None of these modules are involved in any mutual recursion, with the
-sole exception that many modules import @Error.error@.
-
-\subsection[ghc-libs-ghc]{The module @GHC@: really primitive stuff}
-\label{sect:ghc}
+<item> The organisation of these libraries into directories.
+
+<item> Short description of programmer interface to the non-standard
+ libraries provided in addition to the standard prelude.
+</itemize>
+
+A number of the libraries that provide access to GHC's language
+extensions are shared by Hugs, and are described in the <htmlurl
+name="GHC/Hugs Extension Libraries" url="libs.html"> document.
+
+<sect1>Prelude extensions
+<label id="ghc-prelude-exts">
+<p>
+
+GHC's prelude contains the following non-standard extensions:
+
+<descrip>
+
+<tag>@fromInt@ method in class @Num@:</tag> It's there. Converts from
+an @Int@ to the type.
+
+<tag>@toInt@ method in class @Integral@:</tag> Converts from type type
+to an @Int@.
+
+</descrip>
+
+GHC also internally uses a number of modules that begin with the
+string @Prel@: for this reason, we don't recommend that you use any
+module names beginning with @Prel@ in your own programs. The @Prel@
+modules are always available: in fact, you can get access to several
+extensions this way (for some you might need to give the
+@-fglasgow-exts@<nidx>-fglasgow-exts option</nidx> flag).
+
+<sect1>The module @PrelGHC@: really primitive stuff
+<label id="ghc-libs-ghc">
+<p>
This section defines all the types which are primitive in Glasgow
Haskell, and the operations provided for them.
This section also describes a few non-primitive types, which are needed
to express the result types of some primitive operations.
-\subsubsection{Character and numeric types}
+<sect2>Character and numeric types
+<p>
+<nidx>character types, primitive</nidx>
+<nidx>numeric types, primitive</nidx>
+<nidx>integer types, primitive</nidx>
+<nidx>floating point types, primitive</nidx>
There are the following obvious primitive types:
-\begin{verbatim}
+
+<tscreen><verb>
type Char#
type Int# -- see also Word# and Addr#, later
type Float#
type Double#
-\end{verbatim}
+</verb></tscreen>
+<ncdx>Char#</ncdx>
+<ncdx>Int#</ncdx>
+<ncdx>Float#</ncdx>
+<ncdx>Double#</ncdx>
+
If you really want to know their exact equivalents in C, see
@ghc/includes/StgTypes.lh@ in the GHC source tree.
Literals for these types may be written as follows:
-\begin{verbatim}
+
+<tscreen><verb>
1# an Int#
1.2# a Float#
1.34## a Double#
'a'# a Char#; for weird characters, use '\o<octal>'#
"a"# an Addr# (a `char *')
-\end{verbatim}
+</verb></tscreen>
+<nidx>literals, primitive</nidx>
+<nidx>constants, primitive</nidx>
+<nidx>numbers, primitive</nidx>
-\subsubsubsection{Comparison operations}
-\begin{verbatim}
+<sect2> Comparison operations
+<p>
+<nidx>comparisons, primitive</nidx>
+<nidx>operators, comparison</nidx>
+
+<tscreen><verb>
{>,>=,==,/=,<,<=}# :: Int# -> Int# -> Bool
{gt,ge,eq,ne,lt,le}Char# :: Char# -> Char# -> Bool
- -- ditto for Word#, Float#, Double#, and Addr#
-\end{verbatim}
-
-\subsubsubsection{Unboxed-character operations}
-\begin{verbatim}
+ -- ditto for Word# and Addr#
+</verb></tscreen>
+<ncdx>>#</ncdx>
+<ncdx>>=#</ncdx>
+<ncdx>==#</ncdx>
+<ncdx>/=#</ncdx>
+<ncdx><#</ncdx>
+<ncdx><=#</ncdx>
+<ncdx>gt{Char,Word,Addr}#</ncdx>
+<ncdx>ge{Char,Word,Addr}#</ncdx>
+<ncdx>eq{Char,Word,Addr}#</ncdx>
+<ncdx>ne{Char,Word,Addr}#</ncdx>
+<ncdx>lt{Char,Word,Addr}#</ncdx>
+<ncdx>le{Char,Word,Addr}#</ncdx>
+
+<sect2> Primitive-character operations
+<p>
+<nidx>characters, primitive</nidx>
+<nidx>operators, primitive character</nidx>
+
+<tscreen><verb>
ord# :: Char# -> Int#
chr# :: Int# -> Char#
-\end{verbatim}
+</verb></tscreen>
+<ncdx>ord#</ncdx>
+<ncdx>chr#</ncdx>
-\subsubsubsection{Unboxed-@Int@ operations}
-\begin{verbatim}
+<sect2> Primitive-@Int@ operations
+<p>
+<nidx>integers, primitive</nidx>
+<nidx>operators, primitive integer</nidx>
+
+<tscreen><verb>
{+,-,*,quotInt,remInt}# :: Int# -> Int# -> Int#
negateInt# :: Int# -> Int#
iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
-- shift left, right arithmetic, right logical
-\end{verbatim}
-
-{\bf Note:} No error/overflow checking!
-
-\subsubsubsection{Unboxed-@Double@ and @Float@ operations}
-\begin{verbatim}
-{plus,minus,times,divide}Double# :: Double# -> Double# -> Double#
-negateDouble# :: Double# -> Double#
-
-float2Int# :: Double# -> Int# -- just a cast, no checking!
-int2Double# :: Int# -> Double#
-
+</verb></tscreen>
+<ncdx>+#</ncdx>
+<ncdx>-#</ncdx>
+<ncdx>*#</ncdx>
+<ncdx>quotInt#</ncdx>
+<ncdx>remInt#</ncdx>
+<ncdx>iShiftL#</ncdx>
+<ncdx>iShiftRA#</ncdx>
+<ncdx>iShiftRL#</ncdx>
+<nidx>shift operations, integer</nidx>
+
+<bf>Note:</bf> No error/overflow checking!
+
+<sect2> Primitive-@Double@ and @Float@ operations
+<p>
+<nidx>floating point numbers, primitive</nidx>
+<nidx>operators, primitive floating point</nidx>
+
+<tscreen><verb>
+{+,-,*,/}## :: Double# -> Double# -> Double#
+{<,<=,==,/=,>=,>}## :: Double# -> Double# -> Bool
+negateDouble# :: Double# -> Double#
+double2Int# :: Double# -> Int#
+int2Double# :: Int# -> Double#
+
+{plus,minux,times,divide}Float# :: Float# -> Float# -> Float#
+{gt,ge,eq,ne,lt,le}Float# :: Float# -> Float# -> Bool
+negateFloat# :: Float# -> Float#
+float2Int# :: Float# -> Int#
+int2Float# :: Int# -> Float#
+</verb></tscreen>
+
+<ncdx>+##</ncdx>
+<ncdx>-##</ncdx>
+<ncdx>*##</ncdx>
+<ncdx>/##</ncdx>
+<ncdx><##</ncdx>
+<ncdx><=##</ncdx>
+<ncdx>==##</ncdx>
+<ncdx>=/##</ncdx>
+<ncdx>>=##</ncdx>
+<ncdx>>##</ncdx>
+<ncdx>negateDouble#</ncdx>
+<ncdx>double2Int#</ncdx>
+<ncdx>int2Double#</ncdx>
+
+<ncdx>plusFloat#</ncdx>
+<ncdx>minusFloat#</ncdx>
+<ncdx>timesFloat#</ncdx>
+<ncdx>divideFloat#</ncdx>
+<ncdx>gtFloat#</ncdx>
+<ncdx>geFloat#</ncdx>
+<ncdx>eqFloat#</ncdx>
+<ncdx>neFloat#</ncdx>
+<ncdx>ltFloat#</ncdx>
+<ncdx>leFloat#</ncdx>
+<ncdx>negateFloat#</ncdx>
+<ncdx>float2Int#</ncdx>
+<ncdx>int2Float#</ncdx>
+
+And a full complement of trigonometric functions:
+
+<tscreen> <verb>
expDouble# :: Double# -> Double#
logDouble# :: Double# -> Double#
sqrtDouble# :: Double# -> Double#
coshDouble# :: Double# -> Double#
tanhDouble# :: Double# -> Double#
powerDouble# :: Double# -> Double# -> Double#
-\end{verbatim}
+</verb></tscreen>
+<nidx>trigonometric functions, primitive</nidx>
+
+similarly for @Float#@.
-There's an exactly-matching set of unboxed-@Float@ ops; replace
-@Double#@ with @Float#@ in the list above. There are two
-coercion functions for @Float#@/@Double#@:
-\begin{verbatim}
+There are two coercion functions for @Float#@/@Double#@:
+
+<tscreen><verb>
float2Double# :: Float# -> Double#
double2Float# :: Double# -> Float#
-\end{verbatim}
+</verb></tscreen>
+<ncdx>float2Double#</ncdx>
+<ncdx>double2Float#</ncdx>
The primitive versions of @encodeDouble@/@decodeDouble@:
-\begin{verbatim}
+
+<tscreen><verb>
encodeDouble# :: Int# -> Int# -> ByteArray# -- Integer mantissa
-> Int# -- Int exponent
-> Double#
decodeDouble# :: Double# -> PrelNum.ReturnIntAndGMP
-\end{verbatim}
+</verb></tscreen>
+<ncdx>encodeDouble#</ncdx>
+<ncdx>decodeDouble#</ncdx>
(And the same for @Float#@s.)
-\subsubsection{Operations on/for @Integers@ (interface to GMP)}
-\label{sect:horrid-Integer-pairing-types}
+<sect2>Operations on/for @Integers@ (interface to GMP)
+<label id="horrid-Integer-pairing-types">
+<p>
+<nidx>arbitrary precision integers</nidx>
+<nidx>Integer, operations on</nidx>
We implement @Integers@ (arbitrary-precision integers) using the GNU
multiple-precision (GMP) package (version 1.3.2).
-{\bf Note:} some of this might change when we upgrade to using GMP~2.x.
+<bf>Note:</bf> some of this might change when we upgrade to using
+GMP~2.x.
The data type for @Integer@ must mirror that for @MP_INT@ in @gmp.h@
-(see @gmp.info@ in \tr{ghc/includes/runtime/gmp}). It comes out as:
-\begin{verbatim}
+(see @gmp.info@ in @ghc/includes/runtime/gmp@). It comes out as:
+
+<tscreen><verb>
data Integer = J# Int# Int# ByteArray#
-\end{verbatim}
+</verb></tscreen>
+<nidx>Integer type</nidx>
So, @Integer@ is really just a ``pairing'' type for a particular
collection of primitive types.
The operations in the GMP return other combinations of
GMP-plus-something, so we need ``pairing'' types for those, too:
-\begin{verbatim}
+
+<tscreen><verb>
data Return2GMPs = Return2GMPs Int# Int# ByteArray# Int# Int# ByteArray#
data ReturnIntAndGMP = ReturnIntAndGMP Int# Int# Int# ByteArray#
-- ????? something to return a string of bytes (in the heap?)
-\end{verbatim}
+</verb></tscreen>
+<ncdx>Return2GMPs</ncdx>
+<ncdx>ReturnIntAndGMP</ncdx>
The primitive ops to support @Integers@ use the ``pieces'' of the
representation, and are as follows:
-\begin{verbatim}
+
+<tscreen><verb>
negateInteger# :: Int# -> Int# -> ByteArray# -> Integer
{plus,minus,times}Integer# :: Int# -> Int# -> ByteArray#
addr2Integer# :: Addr# -> Integer
-- the Addr# is taken to be a `char *' string
-- to be converted into an Integer.
-\end{verbatim}
-
-
-\subsubsection{Words and addresses}
+</verb></tscreen>
+<ncdx>negateInteger#</ncdx>
+<ncdx>plusInteger#</ncdx>
+<ncdx>minusInteger#</ncdx>
+<ncdx>timesInteger#</ncdx>
+<ncdx>cmpInteger#</ncdx>
+<ncdx>divModInteger#</ncdx>
+<ncdx>quotRemInteger#</ncdx>
+<ncdx>integer2Int#</ncdx>
+<ncdx>int2Integer#</ncdx>
+<ncdx>word2Integer#</ncdx>
+<ncdx>addr2Integer#</ncdx>
+
+<sect2>Words and addresses
+<p>
+<nidx>word, primitive type</nidx>
+<nidx>address, primitive type</nidx>
+<nidx>unsigned integer, primitive type</nidx>
+<nidx>pointer, primitive type</nidx>
A @Word#@ is used for bit-twiddling operations. It is the same size as
an @Int#@, but has no sign nor any arithmetic operations.
-\begin{verbatim}
+<tscreen><verb>
type Word# -- Same size/etc as Int# but *unsigned*
type Addr# -- A pointer from outside the "Haskell world" (from C, probably);
-- described under "arrays"
-\end{verbatim}
+
+</verb></tscreen>
+<ncdx>Word#</ncdx>
+<ncdx>Addr#</ncdx>
@Word#@s and @Addr#@s have the usual comparison operations.
Other unboxed-@Word@ ops (bit-twiddling and coercions):
-\begin{verbatim}
+
+<tscreen><verb>
and#, or#, xor# :: Word# -> Word# -> Word#
-- standard bit ops.
int2Word# :: Int# -> Word# -- just a cast, really
word2Int# :: Word# -> Int#
-\end{verbatim}
+</verb></tscreen>
+<nidx>bit operations, Word and Addr</nidx>
+<ncdx>and#</ncdx>
+<ncdx>or#</ncdx>
+<ncdx>xor#</ncdx>
+<ncdx>not#</ncdx>
+<ncdx>quotWord#</ncdx>
+<ncdx>remWord#</ncdx>
+<ncdx>shiftL#</ncdx>
+<ncdx>shiftRA#</ncdx>
+<ncdx>shiftRL#</ncdx>
+<ncdx>int2Word#</ncdx>
+<ncdx>word2Int#</ncdx>
Unboxed-@Addr@ ops (C casts, really):
-\begin{verbatim}
+<tscreen><verb>
int2Addr# :: Int# -> Addr#
addr2Int# :: Addr# -> Int#
-\end{verbatim}
+</verb></tscreen>
+<ncdx>int2Addr#</ncdx>
+<ncdx>addr2Int#</ncdx>
The casts between @Int#@, @Word#@ and @Addr#@ correspond to null
operations at the machine level, but are required to keep the Haskell
Operations for indexing off of C pointers (@Addr#@s) to snatch values
are listed under ``arrays''.
-\subsubsection{Arrays}
+<sect2>Arrays
+<p>
+<nidx>arrays, primitive</nidx>
-The type @Array# elt@ is the type of primitive, unboxed arrays of
+The type @Array# elt@ is the type of primitive, unpointed arrays of
values of type @elt@.
-\begin{verbatim}
+<tscreen><verb>
type Array# elt
-\end{verbatim}
+</verb></tscreen>
+<ncdx>Array#</ncdx>
@Array#@ is more primitive than a Haskell array --- indeed, the
Haskell @Array@ interface is implemented using @Array#@ --- in that an
@Array#@ is indexed only by @Int#@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 @Array#@ are themselves boxed.
The type @ByteArray#@ is similar to @Array#@, except that it contains
just a string of (non-pointer) bytes.
-\begin{verbatim}
+<tscreen><verb>
type ByteArray#
-\end{verbatim}
+</verb></tscreen>
+<ncdx>ByteArray#</ncdx>
Arrays of these types are useful when a Haskell program wishes to
construct a value to pass to a C procedure. It is also possible to
collector. In other respects they are just like @ByteArray#@. They
are only needed in order to pass values from C to Haskell.
-\subsubsubsection{Reading and writing.}
+<sect2>Reading and writing
+<p>
Primitive arrays are linear, and indexed starting at zero.
type, which is often needed when preparing data for and unpicking
results from C. (Umm... not true of indices... WDP 95/09)
-{\em Should we provide some @sizeOfDouble#@ constants?}
+<em>Should we provide some @sizeOfDouble#@ constants?</em>
Out-of-range errors on indexing should be caught by the code which
uses the primitive operation; the primitive operations themselves do
-{\em not} check for out-of-range indexes. The intention is that the
+<em>not</em> check for out-of-range indexes. The intention is that the
primitive ops compile to one machine instruction or thereabouts.
We use the terms ``reading'' and ``writing'' to refer to accessing
-{\em mutable} arrays (see Section~\ref{sect:mutable}), and
-``indexing'' to refer to reading a value from an {\em immutable}
+<em>mutable</em> arrays (see Section~<ref name="Mutable arrays" id="sect:mutable">), and
+``indexing'' to refer to reading a value from an <em>immutable</em>
array.
Immutable byte arrays are straightforward to index (all indices in bytes):
-\begin{verbatim}
+<tscreen><verb>
indexCharArray# :: ByteArray# -> Int# -> Char#
indexIntArray# :: ByteArray# -> Int# -> Int#
indexAddrArray# :: ByteArray# -> Int# -> Addr#
indexDoubleOffAddr# :: Addr# -> Int# -> Double#
indexAddrOffAddr# :: Addr# -> Int# -> Addr#
-- Get an Addr# from an Addr# offset
-\end{verbatim}
-\index{indexCharArray# function}
-\index{indexIntArray# function}
-\index{indexAddrArray# function}
-\index{indexFloatArray# function}
-\index{indexDoubleArray# function}
-\index{indexCharOffAddr# function}
-\index{indexIntOffAddr# function}
-\index{indexFloatOffAddr# function}
-\index{indexDoubleOffAddr# function}
-\index{indexAddrOffAddr# function}
+</verb></tscreen>
+<ncdx>indexCharArray#</ncdx>
+<ncdx>indexIntArray#</ncdx>
+<ncdx>indexAddrArray#</ncdx>
+<ncdx>indexFloatArray#</ncdx>
+<ncdx>indexDoubleArray#</ncdx>
+<ncdx>indexCharOffAddr#</ncdx>
+<ncdx>indexIntOffAddr#</ncdx>
+<ncdx>indexFloatOffAddr#</ncdx>
+<ncdx>indexDoubleOffAddr#</ncdx>
+<ncdx>indexAddrOffAddr#</ncdx>
The last of these, @indexAddrOffAddr#@, extracts an @Addr#@ using an offset
from another @Addr#@, thereby providing the ability to follow a chain of
object! This is a pain: primitive ops aren't supposed to do
complicated things like enter objects. The current solution is to
return a lifted value, but I don't like it!
-\begin{verbatim}
+
+<tscreen><verb>
indexArray# :: Array# elt -> Int# -> PrelBase.Lift elt -- Yuk!
-\end{verbatim}
+</verb></tscreen>
+<ncdx>indexArray#</ncdx>
-\subsubsection{The state type}
-\index{State# type}
+<sect2>The state type
+<p>
+<ncdx>state, primitive type</ncdx>
+<ncdx>State#</ncdx>
-The primitive type @State#@ represents the state of a state transformer.
-It is parameterised on the desired type of state, which serves to keep
-states from distinct threads distinct from one another. But the {\em only}
-effect of this parameterisation is in the type system: all values of type
-@State#@ are represented in the same way. Indeed, they are all
-represented by nothing at all! The code generator ``knows'' to generate no
-code, and allocate no registers etc, for primitive states.
-\begin{verbatim}
-type State# s
-\end{verbatim}
+The primitive type @State#@ represents the state of a state
+transformer. It is parameterised on the desired type of state, which
+serves to keep states from distinct threads distinct from one another.
+But the <em>only</em> effect of this parameterisation is in the type
+system: all values of type @State#@ are represented in the same way.
+Indeed, they are all represented by nothing at all! The code
+generator ``knows'' to generate no code, and allocate no registers
+etc, for primitive states.
+<tscreen><verb>
+type State# s
+</verb></tscreen>
The type @GHC.RealWorld@ is truly opaque: there are no values defined
of this type, and no operations over it. It is ``primitive'' in that
-sense---but it is {\em not unboxed!} Its only role in life is to be
+sense - but it is <em>not unboxed!</em> Its only role in life is to be
the type which distinguishes the @IO@ state transformer.
-\begin{verbatim}
+
+<tscreen><verb>
data RealWorld
-\end{verbatim}
+</verb></tscreen>
-\subsubsubsection{State of the world}
+<sect2>State of the world
+<p>
A single, primitive, value of type @State# RealWorld@ is provided.
-\begin{verbatim}
+
+<tscreen><verb>
realWorld# :: State# GHC.RealWorld
-\end{verbatim}
-\index{realWorld# state object}
+</verb></tscreen>
+<nidx>realWorld# state object</nidx>
(Note: in the compiler, not a @PrimOp@; just a mucho magic
@Id@. Exported from @GHC@, though).
-\subsubsection{State pairing types}
-\label{sect:horrid-pairing-types}
+<sect2>State pairing types
+<p>
+<label id="horrid-pairing-types">
This subsection defines some types which, while they aren't quite
primitive because we can define them in Haskell, are very nearly so.
They define constructors which pair a primitive state with a value of
each primitive type. They are required to express the result type of
the primitive operations in the state monad.
-\begin{verbatim}
+<tscreen><verb>
data StateAndPtr# s elt = StateAndPtr# (State# s) elt
data StateAndChar# s = StateAndChar# (State# s) Char#
data StateAndMutableArray# s elt = StateAndMutableArray# (State# s) (MutableArray# s elt)
data StateAndByteArray# s = StateAndByteArray# (State# s) ByteArray#
data StateAndMutableByteArray# s = StateAndMutableByteArray# (State# s) (MutableByteArray# s)
-\end{verbatim}
+</verb></tscreen>
Hideous.
-\subsubsection{Mutable arrays}
-\label{sect:mutable}
-\index{Mutable arrays}
+<sect2>Mutable arrays
+<p>
+<label id="sect:mutable">
+<nidx>mutable arrays</nidx>
+<nidx>arrays, mutable</nidx>
Corresponding to @Array#@ and @ByteArray#@, we have the types of
mutable versions of each. In each case, the representation is a
pointer to a suitable block of (mutable) heap-allocated storage.
-\begin{verbatim}
+
+<tscreen><verb>
type MutableArray# s elt
type MutableByteArray# s
-\end{verbatim}
+</verb></tscreen>
+<ncdx>MutableArray#</ncdx>
+<ncdx>MutableByteArray#</ncdx>
-\subsubsubsection{Allocation}
-\index{Mutable arrays, allocation}
-\index{Allocation, of mutable arrays}
+<sect3>Allocation
+<p>
+<nidx>mutable arrays, allocation</nidx>
+<nidx>arrays, allocation</nidx>
+<nidx>allocation, of mutable arrays</nidx>
Mutable arrays can be allocated. Only pointer-arrays are initialised;
arrays of non-pointers are filled in by ``user code'' rather than by
the array-allocation primitive. Reason: only the pointer case has to
worry about GC striking with a partly-initialised array.
-\begin{verbatim}
+<tscreen><verb>
newArray# :: Int# -> elt -> State# s -> StateAndMutableArray# s elt
newCharArray# :: Int# -> State# s -> StateAndMutableByteArray# s
newAddrArray# :: Int# -> State# s -> StateAndMutableByteArray# s
newFloatArray# :: Int# -> State# s -> StateAndMutableByteArray# s
newDoubleArray# :: Int# -> State# s -> StateAndMutableByteArray# s
-\end{verbatim}
+</verb></tscreen>
+<ncdx>newArray#</ncdx>
+<ncdx>newCharArray#</ncdx>
+<ncdx>newIntArray#</ncdx>
+<ncdx>newAddrArray#</ncdx>
+<ncdx>newFloatArray#</ncdx>
+<ncdx>newDoubleArray#</ncdx>
The size of a @ByteArray#@ is given in bytes.
-\subsubsubsection{Reading and writing}
+<sect3>Reading and writing
+<p>
+<nidx>arrays, reading and writing</nidx>
-%OLD: Remember, offsets in a @MutableByteArray#@ are in bytes.
-\begin{verbatim}
+<tscreen><verb>
readArray# :: MutableArray# s elt -> Int# -> State# s -> StateAndPtr# s elt
readCharArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndChar# s
readIntArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndInt# s
writeAddrArray# :: MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
writeFloatArray# :: MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
writeDoubleArray# :: MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
-\end{verbatim}
-
-
-\subsubsubsection{Equality.}
+</verb></tscreen>
+<ncdx>readArray#</ncdx>
+<ncdx>readCharArray#</ncdx>
+<ncdx>readIntArray#</ncdx>
+<ncdx>readAddrArray#</ncdx>
+<ncdx>readFloatArray#</ncdx>
+<ncdx>readDoubleArray#</ncdx>
+<ncdx>writeArray#</ncdx>
+<ncdx>writeCharArray#</ncdx>
+<ncdx>writeIntArray#</ncdx>
+<ncdx>writeAddrArray#</ncdx>
+<ncdx>writeFloatArray#</ncdx>
+<ncdx>writeDoubleArray#</ncdx>
+
+
+<sect3>Equality
+<p>
+<nidx>arrays, testing for equality</nidx>
One can take ``equality'' of mutable arrays. What is compared is the
-{\em name} or reference to the mutable array, not its contents.
-\begin{verbatim}
+<em>name</em> or reference to the mutable array, not its contents.
+
+<tscreen><verb>
sameMutableArray# :: MutableArray# s elt -> MutableArray# s elt -> Bool
sameMutableByteArray# :: MutableByteArray# s -> MutableByteArray# s -> Bool
-\end{verbatim}
+</verb></tscreen>
+<ncdx>sameMutableArray#</ncdx>
+<ncdx>sameMutableByteArray#</ncdx>
-
-\subsubsubsection{Freezing mutable arrays}
+<sect3>Freezing mutable arrays
+<p>
+<nidx>arrays, freezing mutable</nidx>
+<nidx>freezing mutable arrays</nidx>
+<nidx>mutable arrays, freezing</nidx>
Only unsafe-freeze has a primitive. (Safe freeze is done directly in Haskell
by copying the array and then using @unsafeFreeze@.)
-\begin{verbatim}
+
+<tscreen><verb>
unsafeFreezeArray# :: MutableArray# s elt -> State# s -> StateAndArray# s elt
unsafeFreezeByteArray# :: MutableByteArray# s -> State# s -> StateAndByteArray# s
-\end{verbatim}
+</verb></tscreen>
+<ncdx>unsafeFreezeArray#</ncdx>
+<ncdx>unsafeFreezeByteArray#</ncdx>
-
-\subsubsection{Stable pointers}
-\index{Stable pointers}
+<sect2>Stable pointers
+<p>
+<nidx>stable pointers</nidx>
+<nidx>pointers, stable</nidx>
A stable pointer is a name for a Haskell object which can be passed to
the external world. It is ``stable'' in the sense that the name does
The stable pointer type is parameterised by the type of the thing
which is named.
-\begin{verbatim}
+
+<tscreen><verb>
type StablePtr# a
-\end{verbatim}
+</verb></tscreen>
+<ncdx>StablePtr#</ncdx>
A stable pointer is represented by an index into the (static)
@StablePointerTable@. The Haskell garbage collector treats the
pointer. It is part of the @IO@ monad, because we want to be sure
we don't allocate one twice by accident, and then only free one of the
copies.
-\begin{verbatim}
+
+<tscreen><verb>
makeStablePointer# :: a -> State# RealWorld -> StateAndStablePtr# RealWorld a
freeStablePointer# :: StablePtr# a -> State# RealWorld -> State# RealWorld
deRefStablePointer# :: StablePtr# a -> State# RealWorld -> StateAndPtr RealWorld a
-\end{verbatim}
+</verb></tscreen>
+<ncdx>makeStablePointer#</ncdx>
+<ncdx>freeStablePointer#</ncdx>
+<ncdx>deRefStablePointer#</ncdx>
There is also a C procedure @FreeStablePtr@ which frees a stable pointer.
-%{\em Andy's comment.} {\bf Errors:} The following is not strictly true: the current
+%<em>Andy's comment.</em> {\bf Errors:} The following is not strictly true: the current
%implementation is not as polymorphic as claimed. The reason for this
%is that the C programmer will have to use a different entry-routine
%for each type of stable pointer. At present, we only supply a very
%increase the range of these routines by providing general purpose
%entry points to apply stable pointers to (stable pointers to)
%arguments and to enter (stable pointers to) boxed primitive values.
-%{\em End of Andy's comment.}
+%<em>End of Andy's comment.</em>
-%
-% Rewritten and updated for MallocPtr++ -- 4/96 SOF
-%
-\subsubsection{Foreign objects}
-\index{Foreign objects}
-\index{ForeignObj type}
+<sect2>Foreign objects
+<p>
+<nidx>Foreign objects</nidx>
A @ForeignObj#@ is a reference to an object outside the Haskell world
(i.e., from the C world, or a reference to an object on another
machine completely.), where the Haskell world has been told ``Let me
know when you're finished with this ...''.
-\begin{verbatim}
+<tscreen><verb>
type ForeignObj#
-\end{verbatim}
+</verb></tscreen>
+<ncdx>ForeignObj#</ncdx>
GHC provides two primitives on @ForeignObj#@:
-\begin{verbatim}
+<tscreen><verb>
makeForeignObj#
:: Addr# -- foreign reference
-> Addr# -- pointer to finalisation routine
-> Addr# -- datum
-> State# RealWorld
-> State# RealWorld
-\end{verbatim}
+</verb></tscreen>
+<ncdx>makeForeignObj#</ncdx>
+<ncdx>writeForeignObj#</ncdx>
-The module @Foreign@ (Section \ref{sec:foreign-obj}) provides a more
-programmer-friendly interface to foreign objects.
+The module @Foreign@ (Section <ref name="Foreign objects"
+id="sec:foreign-obj">) provides a more programmer-friendly interface
+to foreign objects.
-\subsubsection{Synchronizing variables (M-vars)}
-\index{Synchronising variables (M-vars)}
-\index{M-Vars}
+<sect2>Synchronizing variables (M-vars)
+<p>
+<nidx>synchronising variables (M-vars)</nidx>
+<nidx>M-Vars</nidx>
Synchronising variables are the primitive type used to implement
Concurrent Haskell's MVars (see the Concurrent Haskell paper for
the operational behaviour of these operations).
-\begin{verbatim}
+<tscreen><verb>
type SynchVar# s elt -- primitive
newSynchVar#:: State# s -> StateAndSynchVar# s elt
takeMVar# :: SynchVar# s elt -> State# s -> StateAndPtr# s elt
putMVar# :: SynchVar# s elt -> State# s -> State# s
-\end{verbatim}
+</verb></tscreen>
+<ncdx>SynchVar#</ncdx>
+<ncdx>newSynchVar#</ncdx>
+<ncdx>takeMVar</ncdx>
+<ncdx>putMVar</ncdx>
-\subsubsection{@spark#@ primitive operation (for parallel execution)}
+<sect2>@spark#@ primitive operation (for parallel execution)
+<p>
+<nidx>spark primitive operation</nidx>
-{\em ToDo: say something} It's used in the unfolding for @par@.
+<em>ToDo: say something</em> It's used in the unfolding for @par@.
-\subsubsection{The @errorIO#@ primitive operation}
+<sect2>The @errorIO#@ primitive operation
+<p>
+<nidx>errors, primitive</nidx>
The @errorIO#@ primitive takes an argument much like @IO@. It aborts
execution of the current program, and continues instead by performing
the given @IO@-like value on the current state of the world.
-\begin{verbatim}
-errorIO# :: (State# RealWorld# -> a -> a
-\end{verbatim}
+<tscreen><verb>
+errorIO# :: (State# RealWorld# -> a) -> a
+</verb></tscreen>
+<ncdx>errorIO#</ncdx>
-\subsection{GHC/Hugs Extension Libraries}
+<sect1>GHC/Hugs Extension Libraries
+<p>
The extension libraries provided by both GHC and Hugs are described in
-a separate document ``The Hugs-GHC Extension Libraries''.
+the <htmlurl name="GHC/Hugs Extension Libraries" url="libs.html">
+document.
-\subsection{GHC-only Extension Libraries}
+<sect1>GHC-only Extension Libraries
+<p>
+<nidx>libraries, ghc-only</nidx>
+<nidx>extension libraries, ghc-only</nidx>
If you rely on the implicit @import Prelude@ that GHC normally does
for you, and if you don't use any weird flags (notably
@-fglasgow-exts@), and if you don't import the Glasgow extensions
-interface, @GlaExts@, then GHC should work {\em exactly} as the
-Haskell report says, and the full user namespaces should be available
-to you.
-
-If you mess about with @import Prelude@... innocent hiding, e.g.,
-
-\begin{verbatim}
-import Prelude hiding ( fromIntegral )
-\end{verbatim}
-
-should work just fine.
-
-% this should work now?? -- SDM
-
-%There are some things you can do that will make GHC crash, e.g.,
-%hiding a standard class:
-%\begin{verbatim}
-%import Prelude hiding ( Eq(..) )
-%\end{verbatim}
-%
-%Don't do that.
+interface, @GlaExts@, then GHC should work <em>exactly</em> as the
+Haskell report says (modulo a few minor issues, see Section <ref
+id="vs-Haskell-defn" name="Language Non-compliance">).
If you turn on @-fglasgow-exts@, the compiler will recognise and parse
-unboxed values properly. To get at the primitive operations described
-herein, import the relevant interfaces.
+unboxed values properly, and provide access to the various interfaces
+libraries described here.
-\subsubsection{The @GlaExts@ interface}
-\index{GlaExts interface (GHC extensions)}
+<sect2>The @GlaExts@ interface
+<p>
+<nidx>GlaExts interface (GHC extensions)</nidx>
The @GlaExts@ interface provides access to extensions that only GHC
implements. These currently are: unboxed types, including the
@GlaExts@ for compatibility, but this facility will likely be removed
in the future).
-\begin{verbatim}
+<tscreen><verb>
-- the representation of some basic types:
data Char = C# Char#
data Int = I# Int#
data Integer = J# Int# Int# ByteArray#
module GHC -- all primops and primitive types.
-\end{verbatim}
+</verb></tscreen>
-\subsubsection{The @MutableArray@ interface}
-\label{sec:mutable-array}
-\index{MutableArray interface (GHC extensions)}
+<sect2>The @MutableArray@ interface
+<label id="sec:mutable-array">
+<p>
+<nidx>MutableArray interface (GHC extensions)</nidx>
The @MutableArray@ interface defines a general set of operations over
mutable arrays (@MutableArray@) and mutable chunks of memory
(@MutableByteArray@):
-\begin{verbatim}
+<tscreen><verb>
data MutableArray s ix elt -- abstract
data MutableByteArray s ix -- abstract
-- instance of : CCallable
unsafeFreezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
unsafeFreezeByteArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
thawArray :: Ix ix => Array ix elt -> ST s (MutableArray s ix elt)
-\end{verbatim}
+</verb></tscreen>
+
+%ToDo: index these.
-\subsubsection{The @ByteArray@ interface}
-\label{sec:byte-array}
-\index{ByteArray interface (GHC extensions)}
+<sect2>The @ByteArray@ interface
+<label id="sec:byte-array">
+<p>
+<nidx>ByteArray interface (GHC extensions)</nidx>
@ByteArray@s are chunks of immutable Haskell heap:
-\begin{verbatim}
+<tscreen><verb>
data ByteArray ix -- abstract
-- instance of: CCallable
indexAddrOffAddr :: Addr -> Int -> Addr
indexFloatOffAddr :: Addr -> Int -> Float
indexDoubleOffAddr :: Addr -> Int -> Double
-\end{verbatim}
+</verb></tscreen>
-\subsubsection{Stable pointers}
+<sect2>Stable pointers
+<p>
Nothing exciting here, just simple boxing up.
-\begin{verbatim}
+<tscreen><verb>
data StablePtr a = StablePtr (StablePtr# a)
makeStablePointer :: a -> StablePtr a
freeStablePointer :: StablePtr a -> IO ()
-\end{verbatim}
+</verb></tscreen>
-\subsubsection{Foreign objects}
-\label{sec:foreign-obj}
-\index{Foreign objects}
+<sect2>Foreign objects
+<label id="sec:foreign-obj">
+<p>
+<nidx>Foreign objects</nidx>
This module provides the @ForeignObj@ type and wrappers around the
primitive operations on foreign objects.
-\begin{verbatim}
+<tscreen><verb>
data ForeignObj = ForeignObj ForeignObj#
makeForeignObj
-> Addr -- new value
-> IO ()
-\end{verbatim}
-\index{ForeignObj type}
-\index{makeForeignObj function}
-\index{writeForeignObj function}
+</verb></tscreen>
+<ncdx>ForeignObj</ncdx>
+<ncdx>makeForeignObj</ncdx>
+<ncdx>writeForeignObj</ncdx>
A typical use of @ForeignObj@ is in constructing Haskell bindings
to external libraries. A good example is that of writing a binding to
the library insist on allocating them internally or we (sensibly)
decide to spare the GC from having to heave heavy images around.
-\begin{verbatim}
+<tscreen><verb>
data Image = Image ForeignObj
-\end{verbatim}
+</verb></tscreen>
The @ForeignObj@ type is then used to refer to the externally
allocated image, and to acheive some type safety, the Haskell binding
used to ``box'' up an external reference into a Haskell heap object
that we can then indirectly reference:
-\begin{verbatim}
+<tscreen><verb>
createImage :: (Int,Int) -> IO Image
-\end{verbatim}
+</verb></tscreen>
So far, this looks just like an @Addr@ type, but @ForeignObj@ offers a
-bit more, namely that we can specify a {\em finalisation routine} to
+bit more, namely that we can specify a <em>finalisation routine</em> to
invoke when the @ForeignObj@ is discarded by the GC. The garbage
collector invokes the finalisation routine associated with the
@ForeignObj@, saying `` Thanks, I'm through with this now..'' For the
Upon controlled termination of the Haskell program, all @ForeignObjs@
are freed, invoking their respective finalisers before terminating.
-\subsubsection{The @CCall@ module}
+<sect2>The @CCall@ module
+<p>
The @CCall@ module defines the classes @CCallable@ and @CReturnable@,
along with instances for the primitive types (@Int@, @Int#@, @Float@,
will need to import @CCall@ explicitly.
More information on how to use @_ccall_@ can be found in Section
-\ref{glasgow-ccalls}.
-
-\begin{onlystandalone}
-\end{document}
-\end{onlystandalone}
+<ref name="Calling~C directly from Haskell" id="glasgow-ccalls">.
+++ /dev/null
-% both concurrent and parallel
-%************************************************************************
-%* *
-\section[concurrent-and-parallel]{Concurrent and Parallel Haskell}
-\index{Concurrent Haskell}
-\index{Parallel Haskell}
-%* *
-%************************************************************************
-
-Concurrent and Parallel Haskell are Glasgow extensions to Haskell
-which let you structure your program as a group of independent
-`threads'.
-
-Concurrent and Parallel Haskell have very different purposes.
-
-Concurrent Haskell is for applications which have an inherent
-structure of interacting, concurrent tasks (i.e. `threads'). Threads
-in such programs may be {\em required}. For example, if a concurrent
-thread has been spawned to handle a mouse click, it isn't
-optional---the user wants something done!
-
-A Concurrent Haskell program implies multiple `threads' running within
-a single Unix process on a single processor.
-
-You will find at least one paper about Concurrent Haskell hanging off
-of Simon Peyton Jones's Web page;
-\tr{http://www.dcs.gla.ac.uk/~simonpj/}.
-
-Parallel Haskell is about {\em speed}---spawning threads onto multiple
-processors so that your program will run faster. The `threads'
-are always {\em advisory}---if the runtime system thinks it can
-get the job done more quickly by sequential execution, then fine.
-
-A Parallel Haskell program implies multiple processes running on
-multiple processors, under a PVM (Parallel Virtual Machine) framework.
-
-Parallel Haskell is still relatively new; it is more about ``research
-fun'' than about ``speed.'' That will change.
-
-Again, check Simon's Web page for publications about Parallel Haskell
-(including ``GUM'', the key bits of the runtime system).
-
-Some details about Concurrent and Parallel Haskell follow.
-
-%************************************************************************
-%* *
-\subsection{Concurrent and Parallel Haskell---language features}
-\index{Concurrent Haskell---features}
-\index{Parallel Haskell---features}
-%* *
-%************************************************************************
-
-%************************************************************************
-%* *
-\subsubsection{Features specific to Concurrent Haskell}
-%* *
-%************************************************************************
-
-%************************************************************************
-%* *
-\subsubsubsection{The \tr{Concurrent} interface (recommended)}
-\index{Concurrent interface}
-%* *
-%************************************************************************
-
-GHC provides a \tr{Concurrent} module, a common interface to a
-collection of useful concurrency abstractions, including those
-mentioned in the ``concurrent paper''.
-
-Just put \tr{import Concurrent} into your modules, and away you go.
-To create a ``required thread'':
-
-\begin{verbatim}
-forkIO :: IO a -> IO a
-\end{verbatim}
-
-The \tr{Concurrent} interface also provides access to ``I-Vars''
-and ``M-Vars'', which are two flavours of {\em synchronising variables}.
-\index{synchronising variables (Glasgow extension)}
-\index{concurrency -- synchronising variables}
-
-\tr{IVars}\index{IVars (Glasgow extension)} are write-once
-variables. They start out empty, and any threads that attempt to read
-them will block until they are filled. Once they are written, any
-blocked threads are freed, and additional reads are permitted.
-Attempting to write a value to a full \tr{IVar} results in a runtime
-error. Interface:
-\begin{verbatim}
-newIVar :: IO (IVar a)
-readIVar :: IVar a -> IO a
-writeIVar :: IVar a -> a -> IO ()
-\end{verbatim}
-
-\tr{MVars}\index{MVars (Glasgow extension)} are rendezvous points,
-mostly for concurrent threads. They begin empty, and any attempt to
-read an empty \tr{MVar} blocks. When an \tr{MVar} is written, a
-single blocked thread may be freed. Reading an \tr{MVar} toggles its
-state from full back to empty. Therefore, any value written to an
-\tr{MVar} may only be read once. Multiple reads and writes are
-allowed, but there must be at least one read between any two
-writes. Interface:
-\begin{verbatim}
-newEmptyMVar :: IO (MVar a)
-newMVar :: a -> IO (MVar a)
-takeMVar :: MVar a -> IO a
-putMVar :: MVar a -> a -> IO ()
-readMVar :: MVar a -> IO a
-swapMVar :: MVar a -> a -> IO a
-\end{verbatim}
-
-A {\em channel variable} (@CVar@) is a one-element channel, as
-described in the paper:
-
-\begin{verbatim}
-data CVar a
-newCVar :: IO (CVar a)
-putCVar :: CVar a -> a -> IO ()
-getCVar :: CVar a -> IO a
-\end{verbatim}
-
-A @Channel@ is an unbounded channel:
-
-\begin{verbatim}
-data Chan a
-newChan :: IO (Chan a)
-putChan :: Chan a -> a -> IO ()
-getChan :: Chan a -> IO a
-dupChan :: Chan a -> IO (Chan a)
-unGetChan :: Chan a -> a -> IO ()
-getChanContents :: Chan a -> IO [a]
-\end{verbatim}
-
-General and quantity semaphores:
-
-\begin{verbatim}
-data QSem
-newQSem :: Int -> IO QSem
-waitQSem :: QSem -> IO ()
-signalQSem :: QSem -> IO ()
-
-data QSemN
-newQSemN :: Int -> IO QSemN
-signalQSemN :: QSemN -> Int -> IO ()
-waitQSemN :: QSemN -> Int -> IO ()
-\end{verbatim}
-
-Merging streams---binary and n-ary:
-
-\begin{verbatim}
-mergeIO :: [a] -> [a] -> IO [a]
-nmergeIO :: [[a]] -> IO [a]
-\end{verbatim}
-
-A {\em Sample variable} (@SampleVar@) is slightly different from a
-normal @MVar@:
-\begin{itemize}
-\item Reading an empty @SampleVar@ causes the reader to block
- (same as @takeMVar@ on empty @MVar@).
-\item Reading a filled @SampleVar@ empties it and returns value.
- (same as @takeMVar@)
-\item Writing to an empty @SampleVar@ fills it with a value, and
-potentially, wakes up a blocked reader (same as for @putMVar@ on empty @MVar@).
-\item Writing to a filled @SampleVar@ overwrites the current value.
- (different from @putMVar@ on full @MVar@.)
-\end{itemize}
-
-\begin{verbatim}
-type SampleVar a = MVar (Int, MVar a)
-
-emptySampleVar :: SampleVar a -> IO ()
-newSampleVar :: IO (SampleVar a)
-readSample :: SampleVar a -> IO a
-writeSample :: SampleVar a -> a -> IO ()
-\end{verbatim}
-
-Finally, there are operations to delay a concurrent thread, and to
-make one wait:\index{delay a concurrent thread}
-\index{wait for a file descriptor}
-\begin{verbatim}
-threadDelay :: Int -> IO () -- delay rescheduling for N microseconds
-threadWaitRead :: Int -> IO () -- wait for input on specified file descriptor
-threadWaitWrite :: Int -> IO () -- (read and write, respectively).
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsubsection{Features specific to Parallel Haskell}
-%* *
-%************************************************************************
-
-%************************************************************************
-%* *
-\subsubsubsection{The \tr{Parallel} interface (recommended)}
-\index{Parallel interface}
-%* *
-%************************************************************************
-
-GHC provides two functions for controlling parallel execution, through
-the \tr{Parallel} interface:
-\begin{verbatim}
-interface Parallel where
-infixr 0 `par`
-infixr 1 `seq`
-
-par :: a -> b -> b
-seq :: a -> b -> b
-\end{verbatim}
-
-The expression \tr{(x `par` y)} {\em sparks} the evaluation of \tr{x}
-(to weak head normal form) and returns \tr{y}. Sparks are queued for
-execution in FIFO order, but are not executed immediately. At the
-next heap allocation, the currently executing thread will yield
-control to the scheduler, and the scheduler will start a new thread
-(until reaching the active thread limit) for each spark which has not
-already been evaluated to WHNF.
-
-The expression \tr{(x `seq` y)} evaluates \tr{x} to weak head normal
-form and then returns \tr{y}. The \tr{seq} 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.
-
-For example, consider the following parallel version of our old
-nemesis, \tr{nfib}:
-
-\begin{verbatim}
-import Parallel
-
-nfib :: Int -> Int
-nfib n | n <= 1 = 1
- | otherwise = par n1 (seq n2 (n1 + n2 + 1))
- where n1 = nfib (n-1)
- n2 = nfib (n-2)
-\end{verbatim}
-
-For values of \tr{n} greater than 1, we use \tr{par} to spark a thread
-to evaluate \tr{nfib (n-1)}, and then we use \tr{seq} to force the
-parent thread to evaluate \tr{nfib (n-2)} 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
-\tr{seq} to ensure that the parent will evaluate \tr{n2} {\em before}
-\tr{n1} in the expression \tr{(n1 + n2 + 1)}. It is not sufficient to
-reorder the expression as \tr{(n2 + n1 + 1)}, because the compiler may
-not generate code to evaluate the addends from left to right.
-
-%************************************************************************
-%* *
-\subsubsubsection{Underlying functions and primitives}
-\index{parallelism primitives}
-\index{primitives for parallelism}
-%* *
-%************************************************************************
-
-The functions \tr{par} and \tr{seq} are wired into GHC, and unfold
-into uses of the \tr{par#} and \tr{seq#} primitives, respectively. If
-you'd like to see this with your very own eyes, just run GHC with the
-\tr{-ddump-simpl} option. (Anything for a good time...)
-
-You can use \tr{par} and \tr{seq} in Concurrent Haskell, though
-I'm not sure why you would want to.
-
-%************************************************************************
-%* *
-\subsubsection{Features common to Concurrent and Parallel Haskell}
-%* *
-%************************************************************************
-
-Actually, you can use the \tr{`par`} and \tr{`seq`} combinators
-(really for Parallel Haskell) in Concurrent Haskell as well.
-But doing things like ``\tr{par} to \tr{forkIO} many required threads''
-counts as ``jumping out the 9th-floor window, just to see what happens.''
-
-%************************************************************************
-%* *
-\subsubsubsection{Scheduling policy for concurrent/parallel threads}
-\index{Scheduling---concurrent/parallel}
-\index{Concurrent/parallel scheduling}
-%* *
-%************************************************************************
-
-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
-\tr{-C[<num>]}\index{-C<num> RTS option (concurrent, parallel)} RTS option).
-However, a context switch doesn't really happen until the next heap
-allocation. If you want extremely short time slices, the \tr{-C} RTS
-option can be used to force a context switch at each and every heap
-allocation.
-
-When a context switch occurs, pending sparks which have not already
-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 \tr{-t<num>}\index{-t <num> RTS option (concurrent, parallel)}
-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.
-
-%************************************************************************
-%* *
-\subsection{How to use Concurrent and Parallel Haskell}
-%* *
-%************************************************************************
-
-[You won't get far unless your GHC system was configured/built with
-concurrency and/or parallelism enabled. (They require separate
-library modules.) The relevant section of the installation guide says
-how to do this.]
-
-%************************************************************************
-%* *
-\subsubsection{Using Concurrent Haskell}
-\index{Concurrent Haskell---use}
-%* *
-%************************************************************************
-
-To compile a program as Concurrent Haskell, use the \tr{-concurrent}
-option,\index{-concurrent option} both when compiling {\em and
-linking}. You will probably need the \tr{-fglasgow-exts} option, too.
-
-Three RTS options are provided for modifying the behaviour of the
-threaded runtime system. See the descriptions of \tr{-C[<us>]}, \tr{-q},
-and \tr{-t<num>} in \Sectionref{parallel-rts-opts}.
-
-%************************************************************************
-%* *
-\subsubsubsection[concurrent-problems]{Potential problems with Concurrent Haskell}
-\index{Concurrent Haskell problems}
-\index{problems, Concurrent Haskell}
-%* *
-%************************************************************************
-
-The main thread in a Concurrent Haskell program is given its own
-private stack space, but all other threads are given stack space from
-the heap. Stack space for the main thread can be
-adjusted as usual with the \tr{-K} RTS
-option,\index{-K RTS option (concurrent, parallel)} but if this
-private stack space is exhausted, the main thread will switch to stack
-segments in the heap, just like any other thread. Thus, problems
-which would normally result in stack overflow in ``sequential Haskell''
-can be expected to result in heap overflow when using threads.
-
-The concurrent runtime system uses black holes as synchronisation
-points for subexpressions which are shared among multiple threads. In
-``sequential Haskell'', a black hole indicates a cyclic data
-dependency, which is a fatal error. However, in concurrent execution, a
-black hole may simply indicate that the desired expression is being
-evaluated by another thread. Therefore, when a thread encounters a
-black hole, it simply blocks and waits for the black hole to be
-updated. Cyclic data dependencies will result in deadlock, and the
-program will fail to terminate.
-
-Because the concurrent runtime system uses black holes as
-synchronisation points, it is not possible to disable black-holing
-with the \tr{-N} RTS option.\index{-N RTS option} Therefore, the use
-of signal handlers (including timeouts) with the concurrent runtime
-system can lead to problems if a thread attempts to enter a black hole
-that was created by an abandoned computation. The use of signal
-handlers in conjunction with threads is strongly discouraged.
-
-
-%************************************************************************
-%* *
-\subsubsection{Using Parallel Haskell}
-\index{Parallel Haskell---use}
-%* *
-%************************************************************************
-
-[You won't be able to execute parallel Haskell programs unless PVM3
-(Parallel Virtual Machine, version 3) is installed at your site.]
-
-To compile a Haskell program for parallel execution under PVM, use the
-\tr{-parallel} option,\index{-parallel option} both when compiling
-{\em and linking}. You will probably want to \tr{import Parallel}
-into your Haskell modules.
-
-To run your parallel program, once PVM is going, just invoke it ``as
-normal''. The main extra RTS option is \tr{-N<n>}, to say how many
-PVM ``processors'' your program to run on. (For more details of
-all relevant RTS options, please see \sectionref{parallel-rts-opts}.)
-
-In truth, running Parallel Haskell programs and getting information
-out of them (e.g., parallelism profiles) is a battle with the vagaries of
-PVM, detailed in the following sections.
-
-%************************************************************************
-%* *
-\subsubsubsection{Dummy's guide to using PVM}
-\index{PVM, how to use}
-\index{Parallel Haskell---PVM use}
-%* *
-%************************************************************************
-
-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 \tr{.cshrc} or equivalent:
-\begin{verbatim}
-setenv PVM_ROOT /wherever/you/put/it
-setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
-setenv PVM_DPATH $PVM_ROOT/lib/pvmd
-\end{verbatim}
-
-Creating and/or controlling your ``parallel machine'' is a purely-PVM
-business; nothing specific to Parallel Haskell.
-
-You use the \tr{pvm}\index{pvm command} command to start PVM on your
-machine. You can then do various things to control/monitor your
-``parallel machine;'' the most useful being:
-
-\begin{tabular}{ll}
-\tr{Control-D} & exit \tr{pvm}, leaving it running \\
-\tr{halt} & kill off this ``parallel machine'' \& exit \\
-\tr{add <host>} & add \tr{<host>} as a processor \\
-\tr{delete <host>} & delete \tr{<host>} \\
-\tr{reset} & kill what's going, but leave PVM up \\
-\tr{conf} & list the current configuration \\
-\tr{ps} & report processes' status \\
-\tr{pstat <pid>} & status of a particular process \\
-\end{tabular}
-
-The PVM documentation can tell you much, much more about \tr{pvm}!
-
-%************************************************************************
-%* *
-\subsubsection{Parallelism profiles}
-\index{parallelism profiles}
-\index{profiles, parallelism}
-\index{visualisation tools}
-%* *
-%************************************************************************
-
-With Parallel Haskell programs, we usually don't care about the
-results---only with ``how parallel'' it was! We want pretty pictures.
-
-Parallelism profiles (\`a la \tr{hbcpp}) can be generated with the
-\tr{-q}\index{-q RTS option (concurrent, parallel)} RTS option. The
-per-processor profiling info is dumped into files named
-\tr{<full-path><program>.gr}. These are then munged into a PostScript picture,
-which you can then display. For example, to run your program
-\tr{a.out} on 8 processors, then view the parallelism profile, do:
-
-\begin{verbatim}
-% ./a.out +RTS -N8 -q
-% grs2gr *.???.gr > temp.gr # combine the 8 .gr files into one
-% gr2ps -O temp.gr # cvt to .ps; output in temp.ps
-% ghostview -seascape temp.ps # look at it!
-\end{verbatim}
-
-The scripts for processing the parallelism profiles are distributed
-in \tr{ghc/utils/parallel/}.
-
-%$$************************************************************************
-%$$* *
-%$$\subsubsection{Activity profiles}
-%$$\index{activity profiles}
-%$$\index{profiles, activity}
-%$$\index{visualisation tools}
-%$$%$$* *
-%$$%$$************************************************************************
-%$$
-%$$You can also use the standard GHC ``cost-centre'' profiling to see how
-%$$much time each PVM ``processor'' spends
-%$$
-%$$No special compilation flags beyond \tr{-parallel} are required to get
-%$$this basic four-activity profile. Just use the \tr{-P} RTS option,
-%$$thusly:
-%$$\begin{verbatim}
-%$$./a.out +RTS -N7 -P # 7 processors
-%$$\end{verbatim}
-%$$
-%$$The above will create files named \tr{<something>.prof} and/or
-%$$\tr{<something>.time} {\em in your home directory}. You can
-%$$process the \tr{.time} files into PostScript using \tr{hp2ps},
-%$$\index{hp2ps}
-%$$as described elsewhere in this guide.
-%$$
-%$$Because of the weird file names, you probably need to use
-%$$\tr{hp2ps} as a filter. Also, you probably want to give \tr{hp2ps}
-%$$a \tr{-t0} flag, so that no ``inconsequential'' data is ignored---in
-%$$parallel-land it's all consequential. So:
-%$$\begin{verbatim}
-%$$%$$ hp2ps -t0 < fooo.001.time > temp.ps
-%$$\end{verbatim}
-%$$
-%$$ The first line of the
-%$$ \tr{.qp} file contains the name of the program executed, along with
-%$$ any program arguments and thread-specific RTS options. The second
-%$$ line contains the date and time of program execution. The third
-%$$ and subsequent lines contain information about thread state transitions.
-%$$
-%$$ The thread state transition lines have the following format:
-%$$ \begin{verbatim}
-%$$ time transition thread-id thread-name [thread-id thread-name]
-%$$ \end{verbatim}
-%$$
-%$$ The \tr{time} is the virtual time elapsed since the program started
-%$$ execution, in milliseconds. The \tr{transition} is a two-letter code
-%$$ indicating the ``from'' queue and the ``to'' queue, where each queue
-%$$ is one of:
-%$$ \begin{itemize}
-%$$ \item[\tr{*}] Void: Thread creation or termination.
-%$$ \item[\tr{G}] Green: Runnable (or actively running, with \tr{-qv}) threads.
-%$$ \item[\tr{A}] Amber: Runnable threads (\tr{-qv} only).
-%$$ \item[\tr{R}] Red: Blocked threads.
-%$$ \end{itemize}
-%$$ The \tr{thread-id} is a unique integer assigned to each thread. The
-%$$ \tr{thread-name} is currently the address of the thread's root closure
-%$$ (in hexadecimal). In the future, it will be the name of the function
-%$$ associated with the root of the thread.
-%$$
-%$$ The first \tr{(thread-id, thread-name)} pair identifies the thread
-%$$ involved in the indicated transition. For \tr{RG} and \tr{RA} transitions
-%$$ only, there is a second \tr{(thread-id, thread-name)} pair which identifies
-%$$ the thread that released the blocked thread.
-%$$
-%$$ Provided with the GHC distribution is a perl script, \tr{qp2pp}, which
-%$$ will convert \tr{.qp} files to \tr{hbcpp}'s \tr{.pp} format, so that
-%$$ you can use the \tr{hbcpp} profiling tools, such as \tr{pp2ps92}. The
-%$$ \tr{.pp} format has undergone many changes, so the conversion script
-%$$ is not compatible with earlier releases of \tr{hbcpp}. Note that GHC
-%$$ and \tr{hbcpp} use different thread scheduling policies (in
-%$$ particular, \tr{hbcpp} threads never move from the green queue to the
-%$$ amber queue). For compatibility, the \tr{qp2pp} script eliminates the
-%$$ GHC amber queue, so there is no point in using the verbose (\tr{-qv})
-%$$ option if you are only interested in using the \tr{hbcpp} profiling
-%$$ tools.
-
-%************************************************************************
-%* *
-\subsubsection{Other useful info about running parallel programs}
-%* *
-%************************************************************************
-
-The ``garbage-collection statistics'' RTS options can be useful for
-seeing what parallel programs are doing. If you do either
-\tr{+RTS -Sstderr}\index{-Sstderr RTS option} or \tr{+RTS -sstderr}, 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 \tr{/tmp/pvml.nnn}, courtesy of PVM.
-
-Whether doing \tr{+RTS -Sstderr} or not, a handy way to watch
-what's happening overall is: \tr{tail -f /tmp/pvml.nnn}.
-
-%************************************************************************
-%* *
-\subsubsection[parallel-rts-opts]{RTS options for Concurrent/Parallel Haskell}
-\index{RTS options, concurrent}
-\index{RTS options, parallel}
-\index{Concurrent Haskell---RTS options}
-\index{Parallel Haskell---RTS options}
-%* *
-%************************************************************************
-
-Besides the usual runtime system (RTS) options
-(\sectionref{runtime-control}), there are a few options particularly
-for concurrent/parallel execution.
-
-\begin{description}
-\item[\tr{-N<N>}:]
-\index{-N<N> RTS option (parallel)}
-(PARALLEL ONLY) Use \tr{<N>} PVM processors to run this program;
-the default is 2.
-
-\item[\tr{-C[<us>]}:]
-\index{-C<us> RTS option}
-Sets the context switch interval to \pl{<us>} microseconds. A context
-switch will occur at the next heap allocation after the timer expires.
-With \tr{-C0} or \tr{-C}, 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
-the finest granularity possible, short of a context switch at every
-heap allocation.
-
-\item[\tr{-q[v]}:]
-\index{-q RTS option}
-Produce a quasi-parallel profile of thread activity, in the file
-\tr{<program>.qp}. In the style of \tr{hbcpp}, this profile records
-the movement of threads between the green (runnable) and red (blocked)
-queues. If you specify the verbose suboption (\tr{-qv}), 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 \tr{hbcpp}
-profiling tools or if you are context switching at every heap check
-(with \tr{-C}).
-
-\item[\tr{-t<num>}:]
-\index{-t<num> RTS option}
-Limit the number of concurrent threads per processor to \pl{<num>}.
-The default is 32. Each thread requires slightly over 1K {\em words}
-in the heap for thread state and stack objects. (For 32-bit machines,
-this translates to 4K bytes, and for 64-bit machines, 8K bytes.)
-
-\item[\tr{-d}:]
-\index{-d RTS option (parallel)}
-(PARALLEL ONLY) Turn on debugging. It pops up one xterm (or GDB, or
-something...) per PVM processor. We use the standard \tr{debugger}
-script that comes with PVM3, but we sometimes meddle with the
-\tr{debugger2} script. We include ours in the GHC distribution,
-in \tr{ghc/utils/pvm/}.
-
-\item[\tr{-e<num>}:]
-\index{-e<num> RTS option (parallel)}
-(PARALLEL ONLY) Limit the number of pending sparks per processor to
-\tr{<num>}. The default is 100. A larger number may be appropriate if
-your program generates large amounts of parallelism initially.
-
-\item[\tr{-Q<num>}:]
-\index{-Q<num> RTS option (parallel)}
-(PARALLEL ONLY) Set the size of packets transmitted between processors
-to \tr{<num>}. The default is 1024 words. A larger number may be
-appropriate if your machine has a high communication cost relative to
-computation speed.
-\end{description}
-
-%************************************************************************
-%* *
-\subsubsubsection[parallel-problems]{Potential problems with Parallel Haskell}
-\index{Parallel Haskell---problems}
-\index{problems, Parallel Haskell}
-%* *
-%************************************************************************
-
-The ``Potential problems'' for Concurrent Haskell also apply for
-Parallel Haskell. Please see \Sectionref{concurrent-problems}.
-
-%$$ \subsubsubsection[par-notes]{notes for 0.26}
-%$$
-%$$ \begin{verbatim}
-%$$ Install PVM somewhere, as it says. We use 3.3
-%$$
-%$$ pvm.h : can do w/ a link from ghc/includes to its true home (???)
-%$$
-%$$
-%$$ ghc -gum ... => a.out
-%$$
-%$$ a.out goes to $PVM_ROOT/bin/$PVM_ARCH/$PE
-%$$
-%$$ (profiling outputs go to ~/$PE.<process-num>.<suffix>)
-%$$
-%$$ trinder scripts in: ~trinder/bin/any/instPHIL
-%$$
-%$$ To run:
-%$$
-%$$ Then:
-%$$ SysMan [-] N (PEs) args-to-program...
-%$$
-%$$ - ==> debug mode
-%$$ mattson setup: GDB window per task
-%$$ /local/grasp_tmp5/mattson/pvm3/lib/debugger{,2}
-%$$
-%$$ to set breakpoint, etc, before "run", just modify debugger2
-%$$
-%$$ stderr and stdout are directed to /tmp/pvml.NNN
-%$$
-%$$ Visualisation stuff (normal _mp build):
-%$$
-%$$ +RTS -q gransim-like profiling
-%$$ (should use exactly-gransim RTS options)
-%$$ -qb binary dumps : not tried, not recommended: hosed!
-%$$
-%$$ ascii dump : same info as gransim, one extra line at top w/
-%$$ start time; all times are ms since then
-%$$
-%$$ dumps appear in $HOME/<program>.nnn.gr
-%$$
-%$$ ~mattson/grs2gr.pl == combine lots into one (fixing times)
-%$$
-%$$ /local/grasp/hwloidl/GrAn/bin/ is where scripts are.
-%$$
-%$$ gr2ps == activity profile (bash script)
-%$$
-%$$ ~mattson/bin/`arch`/gr2qp must be picked up prior to hwloidl's for
-%$$ things to work...
-%$$
-%$$ +RTS -[Pp] (parallel) 4-cost-centre "profiling" (gc,MAIN,msg,idle)
-%$$
-%$$ ToDos: time-profiles from hp2ps: something about zeroth sample;
-%$$ \end{verbatim}
--- /dev/null
+% both concurrent and parallel
+%************************************************************************
+%* *
+<sect1>Concurrent and Parallel Haskell
+<label id="concurrent-and-parallel">
+<p>
+<nidx>Concurrent Haskell</nidx>
+<nidx>Parallel Haskell</nidx>
+%* *
+%************************************************************************
+
+Concurrent and Parallel Haskell are Glasgow extensions to Haskell
+which let you structure your program as a group of independent
+`threads'.
+
+Concurrent and Parallel Haskell have very different purposes.
+
+Concurrent Haskell is for applications which have an inherent
+structure of interacting, concurrent tasks (i.e. `threads'). Threads
+in such programs may be <em>required</em>. For example, if a concurrent
+thread has been spawned to handle a mouse click, it isn't
+optional---the user wants something done!
+
+A Concurrent Haskell program implies multiple `threads' running within
+a single Unix process on a single processor.
+
+You will find at least one paper about Concurrent Haskell hanging off
+of <url name="Simon Peyton Jones's Web page"
+url="http://www.dcs.gla.ac.uk/~simonpj/">.
+
+Parallel Haskell is about <em>speed</em>---spawning threads onto multiple
+processors so that your program will run faster. The `threads'
+are always <em>advisory</em>---if the runtime system thinks it can
+get the job done more quickly by sequential execution, then fine.
+
+A Parallel Haskell program implies multiple processes running on
+multiple processors, under a PVM (Parallel Virtual Machine) framework.
+
+Parallel Haskell is still relatively new; it is more about ``research
+fun'' than about ``speed.'' That will change.
+
+Again, check Simon's Web page for publications about Parallel Haskell
+(including ``GUM'', the key bits of the runtime system).
+
+Some details about Concurrent and Parallel Haskell follow.
+
+%************************************************************************
+%* *
+<sect2>Language features specific to Concurrent Haskell
+<p>
+<nidx>Concurrent Haskell---features</nidx>
+%* *
+%************************************************************************
+
+%************************************************************************
+%* *
+<sect3>The @Concurrent@ interface (recommended)
+<p>
+<nidx>Concurrent interface</nidx>
+%* *
+%************************************************************************
+
+GHC provides a @Concurrent@ module, a common interface to a
+collection of useful concurrency abstractions, including those
+mentioned in the ``concurrent paper''.
+
+Just put @import Concurrent@ into your modules, and away you go.
+To create a ``required thread'':
+
+<tscreen><verb>
+forkIO :: IO a -> IO a
+</verb></tscreen>
+
+The @Concurrent@ interface also provides access to ``I-Vars''
+and ``M-Vars'', which are two flavours of <em>synchronising variables</em>.
+<nidx>synchronising variables (Glasgow extension)</nidx>
+<nidx>concurrency -- synchronising variables</nidx>
+
+@IVars@<nidx>IVars (Glasgow extension)</nidx> are write-once
+variables. They start out empty, and any threads that attempt to read
+them will block until they are filled. Once they are written, any
+blocked threads are freed, and additional reads are permitted.
+Attempting to write a value to a full @IVar@ results in a runtime
+error. Interface:
+<tscreen><verb>
+newIVar :: IO (IVar a)
+readIVar :: IVar a -> IO a
+writeIVar :: IVar a -> a -> IO ()
+</verb></tscreen>
+
+@MVars@<nidx>MVars (Glasgow extension)</nidx> are rendezvous points,
+mostly for concurrent threads. They begin empty, and any attempt to
+read an empty @MVar@ blocks. When an @MVar@ is written, a
+single blocked thread may be freed. Reading an @MVar@ toggles its
+state from full back to empty. Therefore, any value written to an
+@MVar@ may only be read once. Multiple reads and writes are
+allowed, but there must be at least one read between any two
+writes. Interface:
+<tscreen><verb>
+newEmptyMVar :: IO (MVar a)
+newMVar :: a -> IO (MVar a)
+takeMVar :: MVar a -> IO a
+putMVar :: MVar a -> a -> IO ()
+readMVar :: MVar a -> IO a
+swapMVar :: MVar a -> a -> IO a
+</verb></tscreen>
+
+A <em>channel variable</em> (@CVar@) is a one-element channel, as
+described in the paper:
+
+<tscreen><verb>
+data CVar a
+newCVar :: IO (CVar a)
+putCVar :: CVar a -> a -> IO ()
+getCVar :: CVar a -> IO a
+</verb></tscreen>
+
+A @Channel@ is an unbounded channel:
+
+<tscreen><verb>
+data Chan a
+newChan :: IO (Chan a)
+putChan :: Chan a -> a -> IO ()
+getChan :: Chan a -> IO a
+dupChan :: Chan a -> IO (Chan a)
+unGetChan :: Chan a -> a -> IO ()
+getChanContents :: Chan a -> IO [a]
+</verb></tscreen>
+
+General and quantity semaphores:
+
+<tscreen><verb>
+data QSem
+newQSem :: Int -> IO QSem
+waitQSem :: QSem -> IO ()
+signalQSem :: QSem -> IO ()
+
+data QSemN
+newQSemN :: Int -> IO QSemN
+signalQSemN :: QSemN -> Int -> IO ()
+waitQSemN :: QSemN -> Int -> IO ()
+</verb></tscreen>
+
+Merging streams---binary and n-ary:
+
+<tscreen><verb>
+mergeIO :: [a] -> [a] -> IO [a]
+nmergeIO :: [[a]] -> IO [a]
+</verb></tscreen>
+
+A <em>Sample variable</em> (@SampleVar@) is slightly different from a
+normal @MVar@:
+<itemize>
+<item> Reading an empty @SampleVar@ causes the reader to block
+ (same as @takeMVar@ on empty @MVar@).
+<item> Reading a filled @SampleVar@ empties it and returns value.
+ (same as @takeMVar@)
+<item> Writing to an empty @SampleVar@ fills it with a value, and
+potentially, wakes up a blocked reader (same as for @putMVar@ on empty @MVar@).
+<item> Writing to a filled @SampleVar@ overwrites the current value.
+ (different from @putMVar@ on full @MVar@.)
+</itemize>
+
+<tscreen><verb>
+type SampleVar a = MVar (Int, MVar a)
+
+emptySampleVar :: SampleVar a -> IO ()
+newSampleVar :: IO (SampleVar a)
+readSample :: SampleVar a -> IO a
+writeSample :: SampleVar a -> a -> IO ()
+</verb></tscreen>
+
+Finally, there are operations to delay a concurrent thread, and to
+make one wait:<nidx>delay a concurrent thread</nidx>
+<nidx>wait for a file descriptor</nidx>
+<tscreen><verb>
+threadDelay :: Int -> IO () -- delay rescheduling for N microseconds
+threadWaitRead :: Int -> IO () -- wait for input on specified file descriptor
+threadWaitWrite :: Int -> IO () -- (read and write, respectively).
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>Features specific to Parallel Haskell
+<nidx>Parallel Haskell---features</nidx>
+<p>
+%* *
+%************************************************************************
+
+%************************************************************************
+%* *
+\subsubsubsection{The @Parallel@ interface (recommended)}
+<nidx>Parallel interface</nidx>
+%* *
+%************************************************************************
+
+GHC provides two functions for controlling parallel execution, through
+the @Parallel@ interface:
+<tscreen><verb>
+interface Parallel where
+infixr 0 `par`
+infixr 1 `seq`
+
+par :: a -> b -> b
+seq :: a -> b -> b
+</verb></tscreen>
+
+The expression @(x `par` y)@ <em>sparks</em> the evaluation of @x@
+(to weak head normal form) and returns @y@. Sparks are queued for
+execution in FIFO order, but are not executed immediately. At the
+next heap allocation, the currently executing thread will yield
+control to the scheduler, and the scheduler will start a new thread
+(until reaching the active thread limit) for each spark which has not
+already been evaluated to WHNF.
+
+The expression @(x `seq` y)@ evaluates @x@ to weak head normal
+form and then returns @y@. The @seq@ 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.
+
+For example, consider the following parallel version of our old
+nemesis, @nfib@:
+
+<tscreen><verb>
+import Parallel
+
+nfib :: Int -> Int
+nfib n | n <= 1 = 1
+ | otherwise = par n1 (seq n2 (n1 + n2 + 1))
+ where n1 = nfib (n-1)
+ n2 = nfib (n-2)
+</verb></tscreen>
+
+For values of @n@ greater than 1, we use @par@ to spark a thread
+to evaluate @nfib (n-1)@, and then we use @seq@ to force the
+parent thread to evaluate @nfib (n-2)@ 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
+@seq@ to ensure that the parent will evaluate @n2@ <em>before</em>
+@n1@ in the expression @(n1 + n2 + 1)@. It is not sufficient to
+reorder the expression as @(n2 + n1 + 1)@, because the compiler may
+not generate code to evaluate the addends from left to right.
+
+%************************************************************************
+%* *
+\subsubsubsection{Underlying functions and primitives}
+<nidx>parallelism primitives</nidx>
+<nidx>primitives for parallelism</nidx>
+%* *
+%************************************************************************
+
+The functions @par@ and @seq@ are wired into GHC, and unfold
+into uses of the @par#@ and @seq#@ primitives, respectively. If
+you'd like to see this with your very own eyes, just run GHC with the
+@-ddump-simpl@ option. (Anything for a good time...)
+
+You can use @par@ and @seq@ in Concurrent Haskell, though
+I'm not sure why you would want to.
+
+%************************************************************************
+%* *
+<sect2>Features common to Concurrent and Parallel Haskell
+<p>
+%* *
+%************************************************************************
+
+Actually, you can use the @`par`@ and @`seq`@ combinators
+(really for Parallel Haskell) in Concurrent Haskell as well.
+But doing things like ``@par@ to @forkIO@ many required threads''
+counts as ``jumping out the 9th-floor window, just to see what happens.''
+
+%************************************************************************
+%* *
+\subsubsubsection{Scheduling policy for concurrent/parallel threads}
+<nidx>Scheduling---concurrent/parallel</nidx>
+<nidx>Concurrent/parallel scheduling</nidx>
+%* *
+%************************************************************************
+
+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
+@-C[<num>]@<nidx>-C<num> RTS option (concurrent, parallel)</nidx> RTS option).
+However, a context switch doesn't really happen until the next heap
+allocation. If you want extremely short time slices, the @-C@ RTS
+option can be used to force a context switch at each and every heap
+allocation.
+
+When a context switch occurs, pending sparks which have not already
+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 @-t<num>@<nidx>-t <num> RTS option (concurrent, parallel)</nidx>
+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.
--- /dev/null
+%************************************************************************
+%* *
+<sect1>The Posix library
+<label id="Posix-library">
+<p>
+<nidx>Posix library</nidx>
+<nidx>libraries, Posix</nidx>
+%* *
+%************************************************************************
+
+The @Posix@ interface gives you access to the set of OS services
+standardised by POSIX 1003.1b (or the <em>IEEE Portable Operating System
+Interface for Computing Environments</em> - IEEE Std. 1003.1). The
+interface is accessed by @import Posix@ and adding
+@-syslib posix@ on your command-line.
+
+<sect2>Posix data types
+<label id="Posix data types">
+<p>
+<nidx>Posix, data types</nidx>
+
+
+<tscreen><verb>
+data ByteCount -- instances of : Eq Ord Num Real Integral Ix Enum Show
+</verb></tscreen>
+
+A @ByteCount@ is a primitive of type @unsigned@. At a minimum,
+an conforming implementation must support values in the range
+@[0, UINT_MAX]@.
+
+<tscreen><verb>
+data ClockTick -- instances of : Eq Ord Num Real Integral Ix Enum Show
+</verb></tscreen>
+
+A @ClockTick@ is a primitive of type @clock_t@, which
+is used to measure intervals of time in fractions of a second. The
+resolution is determined by @getSysVar ClockTick@.
+
+<tscreen><verb>
+data DeviceID -- instances of : Eq Ord Num Real Integral Ix Enum Show
+</verb></tscreen>
+
+A @DeviceID@ is a primitive of type @dev_t@. It must
+be an arithmetic type.
+
+<tscreen><verb>
+data EpochTime -- instances of : Eq Ord Num Real Integral Ix Enum Show
+</verb></tscreen>
+
+A @EpochTime@ is a primitive of type @time_t@, which is
+used to measure seconds since the Epoch. At a minimum, the implementation
+must support values in the range @[0, INT_MAX]@.
+
+<tscreen><verb>
+data FileID -- instances of : Eq Ord Num Real Integral Ix Enum Show
+</verb></tscreen>
+
+A @FileID@ is a primitive of type @ino_t@. It must
+be an arithmetic type.
+
+<tscreen><verb>
+data FileMode -- instances of : Eq Ord Num Real Integral Ix Enum Show
+</verb></tscreen>
+
+A @FileMode@ is a primitive of type @mode_t@.
+It must be an arithmetic type.
+
+<tscreen><verb>
+data FileOffset -- instances of : Eq Ord Num Real Integral Ix Enum Show
+</verb></tscreen>
+
+A @FileOffset@ is a primitive of type @off_t@. It must
+be an arithmetic type.
+
+<tscreen><verb>
+data GroupID -- instances of : Eq Ord Num Real Integral Ix Enum Show
+</verb></tscreen>
+
+A @GroupID@ is a primitive of type @gid_t@. It must
+be an arithmetic type.
+<tscreen><verb>
+data Limit -- instances of : Eq Ord Num Real Integral Ix Enum Show
+</verb></tscreen>
+
+A @Limit@ is a primitive of type @long@.
+At a minimum, the implementation must support values in the range
+@[LONG_MIN, LONG_MAX]@.
+
+<tscreen><verb>
+data LinkCount -- instances of : Eq Ord Num Real Integral Ix Enum Show
+</verb></tscreen>
+
+A @LinkCount@ is a primitive of type @nlink_t@. It must
+be an arithmetic type.
+
+<tscreen><verb>
+data ProcessID -- instances of : Eq Ord Num Real Integral Ix Enum Show
+type ProcessGroupID = ProcessID
+</verb></tscreen>
+
+A @ProcessID@ is a primitive of type @pid_t@. It
+must be a signed arithmetic type.
+<tscreen><verb>
+data UserID -- instances of : Eq Ord Num Real Integral Ix Enum Show
+</verb></tscreen>
+
+A @UserID@ is a primitive of type @uid_t@. It
+must be an arithmetic type.
+
+<tscreen><verb>
+data DirStream
+</verb></tscreen>
+A @DirStream@ is a primitive of type @DIR *@.
+
+<tscreen><verb>
+data FileStatus
+</verb></tscreen>
+A @FileStatus@ is a primitive of type @struct stat@.
+
+<tscreen><verb>
+data GroupEntry
+</verb></tscreen>
+
+A @GroupEntry@ is a primitive of type @struct group@.
+<tscreen><verb>
+data ProcessTimes
+</verb></tscreen>
+
+@ProcessTimes@ is a primitive structure containing a
+@clock_t@ and a @struct tms@.
+
+<tscreen><verb>
+data SignalSet
+</verb></tscreen>
+
+An @SignalSet@ is a primitive of type @sigset_t@.
+
+<tscreen><verb>
+data SystemID
+</verb></tscreen>
+
+A @SystemID@ is a primitive of type @struct utsname@.
+
+<tscreen><verb>
+data TerminalAttributes
+</verb></tscreen>
+@TerminalAttributes@ is a primitive of type @struct termios@.
+
+<tscreen><verb>
+data UserEntry
+</verb></tscreen>
+
+A @UserEntry@ is a primitive of type @struct passwd@.
+
+<tscreen><verb>
+data BaudRate = B0 | B50 | B75 | B110 | B134 | B150 | B200 | B300 | B600
+ | B1200 | B1800 | B2400 | B4800 | B9600 | B19200 | B38400
+ deriving (Eq, Show)
+
+data Fd
+
+intToFd :: Int -> Fd -- use with care.
+
+data FdOption = AppendOnWrite
+ | CloseOnExec
+ | NonBlockingRead
+
+data ControlCharacter = EndOfFile
+ | EndOfLine
+ | Erase
+ | Interrupt
+ | Kill
+ | Quit
+ | Suspend
+ | Start
+ | Stop
+
+type ErrorCode = Int
+
+type FileLock = (LockRequest, SeekMode, FileOffset, FileOffset)
+-- whence start length
+
+data FlowAction = SuspendOutput | RestartOutput | TransmitStop | TransmitStart
+
+data Handler = Default | Ignore | Catch (IO ())
+
+data LockRequest = ReadLock | WriteLock | Unlock
+ deriving (Eq, Show)
+
+data OpenMode = ReadOnly | WriteOnly | ReadWrite
+
+data PathVar = LinkLimit
+ | InputLineLimit
+ | InputQueueLimit
+ | FileNameLimit
+ | PathNameLimit
+ | PipeBufferLimit
+ | SetOwnerAndGroupIsRestricted
+ | FileNamesAreNotTruncated
+
+data QueueSelector = InputQueue | OutputQueue | BothQueues
+
+type Signal = Int
+
+data SysVar = ArgumentLimit
+ | ChildLimit
+ | ClockTick
+ | GroupLimit
+ | OpenFileLimit
+ | PosixVersion
+ | HasSavedIDs
+ | HasJobControl
+
+data TerminalMode = InterruptOnBreak -- BRKINT
+ | MapCRtoLF -- ICRNL
+ | IgnoreBreak -- IGNBRK
+ | IgnoreCR -- IGNCR
+ | IgnoreParityErrors -- IGNPAR
+ | MapLFtoCR -- INLCR
+ | CheckParity -- INPCK
+ | StripHighBit -- ISTRIP
+ | StartStopInput -- IXOFF
+ | StartStopOutput -- IXON
+ | MarkParityErrors -- PARMRK
+ | ProcessOutput -- OPOST
+ | LocalMode -- CLOCAL
+ | ReadEnable -- CREAD
+ | TwoStopBits -- CSTOPB
+ | HangupOnClose -- HUPCL
+ | EnableParity -- PARENB
+ | OddParity -- PARODD
+ | EnableEcho -- ECHO
+ | EchoErase -- ECHOE
+ | EchoKill -- ECHOK
+ | EchoLF -- ECHONL
+ | ProcessInput -- ICANON
+ | ExtendedFunctions -- IEXTEN
+ | KeyboardInterrupts -- ISIG
+ | NoFlushOnInterrupt -- NOFLSH
+ | BackgroundWriteInterrupt -- TOSTOP
+
+data TerminalState = Immediately | WhenDrained | WhenFlushed
+
+data ProcessStatus = Exited ExitCode
+ | Terminated Signal
+ | Stopped Signal
+ deriving (Eq, Show)
+</verb></tscreen>
+
+<sect2>Posix Process Primitives
+<label id="Process Primitives">
+<p>
+
+<tscreen><verb>
+forkProcess :: IO (Maybe ProcessID)
+</verb></tscreen>
+
+@forkProcess@ calls @fork@, returning
+@Just pid@ to the parent, where @pid@ is the
+ProcessID of the child, and returning @Nothing@ to the
+child.
+
+<tscreen><verb>
+executeFile :: FilePath -- Command
+ -> Bool -- Search PATH?
+ -> [String] -- Arguments
+ -> Maybe [(String, String)] -- Environment
+ -> IO ()
+</verb></tscreen>
+
+@executeFile cmd args env@ calls one of the
+@execv*@ 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 @execv*@ as @arg[0]@;
+the argument list passed to @executeFile@ therefore begins
+with @arg[1]@.
+
+<tscreen><verb>
+Search PATH? Supersede environ? Call
+~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~ ~~~~~~~
+False False execv
+False True execve
+True False execvp
+True True execvpe*
+</verb></tscreen>
+
+Note that @execvpe@ 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.
+
+A successful @executeFile@ overlays the current process image with
+a new one, so it only returns on failure.
+<tscreen><verb>
+runProcess :: FilePath -- Command
+ -> [String] -- Arguments
+ -> Maybe [(String, String)] -- Environment (Nothing -> Inherited)
+ -> Maybe FilePath -- Working directory (Nothing -> inherited)
+ -> Maybe Handle -- stdin (Nothing -> inherited)
+ -> Maybe Handle -- stdout (Nothing -> inherited)
+ -> Maybe Handle -- stderr (Nothing -> inherited)
+ -> IO ()
+</verb></tscreen>
+
+@runProcess@ is our candidate for the high-level OS-independent
+primitive.
+
+@runProcess cmd args env wd inhdl outhdl errhdl@ runs @cmd@
+(searching the current @PATH@) with arguments @args@. If
+@env@ is @Just pairs@, the command is executed with the
+environment specified by @pairs@ of variables and values;
+otherwise, the command is executed with the current environment. If
+@wd@ is @Just dir@, the command is executed with working
+directory @dir@; otherwise, the command is executed in the current
+working directory. If @{in,out,err@hdl} is @Just handle@, the
+command is executed with the @Fd@ for @std{in,out,err@}
+attached to the specified @handle@; otherwise, the @Fd@ for
+@std{in,out,err@} is left unchanged.
+
+<tscreen><verb>
+getProcessStatus :: Bool -- Block?
+ -> Bool -- Stopped processes?
+ -> ProcessID
+ -> IO (Maybe ProcessStatus)
+</verb></tscreen>
+
+@getProcessStatus blk stopped pid@ calls @waitpid@, returning
+@Just tc@, the @ProcessStatus@ for process @pid@ if it is
+available, @Nothing@ otherwise. If @blk@ is @False@, then
+@WNOHANG@ is set in the options for @waitpid@, otherwise not.
+If @stopped@ is @True@, then @WUNTRACED@ is set in the
+options for @waitpid@, otherwise not.
+
+<tscreen><verb>
+getGroupProcessStatus :: Bool -- Block?
+ -> Bool -- Stopped processes?
+ -> ProcessGroupID
+ -> IO (Maybe (ProcessID, ProcessStatus))
+</verb></tscreen>
+
+@getGroupProcessStatus blk stopped pgid@ calls @waitpid@,
+returning @Just (pid, tc)@, the @ProcessID@ and
+@ProcessStatus@ for any process in group @pgid@ if one is
+available, @Nothing@ otherwise. If @blk@ is @False@, then
+@WNOHANG@ is set in the options for @waitpid@, otherwise not.
+If @stopped@ is @True@, then @WUNTRACED@ is set in the
+options for @waitpid@, otherwise not.
+
+<tscreen><verb>
+getAnyProcessStatus :: Bool -- Block?
+ -> Bool -- Stopped processes?
+ -> IO (Maybe (ProcessID, ProcessStatus))
+</verb></tscreen>
+
+@getAnyProcessStatus blk stopped@ calls @waitpid@, returning
+@Just (pid, tc)@, the @ProcessID@ and @ProcessStatus@ for any
+child process if one is available, @Nothing@ otherwise. If
+@blk@ is @False@, then @WNOHANG@ is set in the options for
+@waitpid@, otherwise not. If @stopped@ is @True@, then
+@WUNTRACED@ is set in the options for @waitpid@, otherwise not.
+
+<tscreen><verb>
+exitImmediately :: ExitCode -> IO ()
+</verb></tscreen>
+
+@exitImmediately status@ calls @_exit@ to terminate the process
+with the indicated exit @status@.
+The operation never returns.
+
+<tscreen><verb>
+getEnvironment :: IO [(String, String)]
+</verb></tscreen>
+
+@getEnvironment@ parses the environment variable mapping provided by
+@environ@, returning @(variable, value)@ pairs.
+The operation never fails.
+
+<tscreen><verb>
+setEnvironment :: [(String, String)] -> IO ()
+</verb></tscreen>
+
+@setEnvironment@ replaces the process environment with the provided
+mapping of @(variable, value)@ pairs.
+
+<tscreen><verb>
+getEnvVar :: String -> IO String
+</verb></tscreen>
+
+@getEnvVar var@ returns the value associated with variable @var@
+in the current environment (identical functionality provided through
+standard Haskell library function @System.getEnv@).
+
+The operation may fail with:
+
+<descrip>
+<tag>@NoSuchThing@</tag>
+The variable has no mapping in the current environment.
+</descrip>
+
+<tscreen><verb>
+setEnvVar :: String -> String -> IO ()
+</verb></tscreen>
+
+@setEnvVar var val@ sets the value associated with variable @var@
+in the current environment to be @val@. Any previous mapping is
+superseded.
+
+<tscreen><verb>
+removeEnvVar :: String -> IO ()
+</verb></tscreen>
+
+@removeEnvVar var@ removes any value associated with variable @var@
+in the current environment. Deleting a variable for which there is no mapping
+does not generate an error.
+
+<tscreen><verb>
+nullSignal :: Signal
+nullSignal = 0
+
+backgroundRead, sigTTIN :: Signal
+backgroundWrite, sigTTOU :: Signal
+continueProcess, sigCONT :: Signal
+floatingPointException, sigFPE :: Signal
+illegalInstruction, sigILL :: Signal
+internalAbort, sigABRT :: Signal
+keyboardSignal, sigINT :: Signal
+keyboardStop, sigTSTP :: Signal
+keyboardTermination, sigQUIT :: Signal
+killProcess, sigKILL :: Signal
+lostConnection, sigHUP :: Signal
+openEndedPipe, sigPIPE :: Signal
+processStatusChanged, sigCHLD :: Signal
+realTimeAlarm, sigALRM :: Signal
+segmentationViolation, sigSEGV :: Signal
+softwareStop, sigSTOP :: Signal
+softwareTermination, sigTERM :: Signal
+userDefinedSignal1, sigUSR1 :: Signal
+userDefinedSignal2, sigUSR2 :: Signal
+
+signalProcess :: Signal -> ProcessID -> IO ()
+</verb></tscreen>
+
+@signalProcess int pid@ calls @kill@ to signal
+process @pid@ with interrupt signal @int@.
+
+<tscreen><verb>
+raiseSignal :: Signal -> IO ()
+</verb></tscreen>
+
+@raiseSignal int@ calls @kill@ to signal the current process
+with interrupt signal @int@.
+
+<tscreen><verb>
+signalProcessGroup :: Signal -> ProcessGroupID -> IO ()
+</verb></tscreen>
+
+@signalProcessGroup int pgid@ calls @kill@ to signal
+all processes in group @pgid@ with interrupt signal @int@.
+
+<tscreen><verb>
+setStoppedChildFlag :: Bool -> IO Bool
+</verb></tscreen>
+
+@setStoppedChildFlag bool@ sets a flag which controls whether or
+not the @NOCLDSTOP@ option will be used the next time a signal
+handler is installed for @SIGCHLD@. If @bool@ is @True@ (the
+default), @NOCLDSTOP@ will not be used; otherwise it will be. The
+operation never fails.
+
+<tscreen><verb>
+queryStoppedChildFlag :: IO Bool
+</verb></tscreen>
+
+@queryStoppedChildFlag@ queries the flag which
+controls whether or not the @NOCLDSTOP@ option will be used
+the next time a signal handler is installed for @SIGCHLD@.
+If @NOCLDSTOP@ will be used, it returns @False@;
+otherwise (the default) it returns @True@.
+The operation never fails.
+
+<tscreen><verb>
+emptySignalSet :: SignalSet
+fullSignalSet :: SignalSet
+addSignal :: Signal -> SignalSet -> SignalSet
+deleteSignal :: Signal -> SignalSet -> SignalSet
+inSignalSet :: Signal -> SignalSet -> Bool
+
+installHandler :: Signal
+ -> Handler
+ -> Maybe SignalSet -- other signals to block
+ -> IO Handler -- old handler
+</verb></tscreen>
+
+@installHandler int handler iset@ calls @sigaction@ to install
+an interrupt handler for signal @int@. If @handler@ is
+@Default@, @SIG_DFL@ is installed; if @handler@ is
+@Ignore@, @SIG_IGN@ is installed; if @handler@ is
+@Catch action@, a handler is installed which will invoke @action@ as a
+replacement for @main@. If @iset@ is @Just s@, then the
+@sa_mask@ of the @sigaction@ structure is set to @s@;
+otherwise it is cleared. The previously installed signal handler for
+@int@ is returned.
+
+<tscreen><verb>
+getSignalMask :: IO SignalSet
+</verb></tscreen>
+
+@getSignalMask@ calls @sigprocmask@ to determine the
+set of interrupts which are currently being blocked.
+
+<tscreen><verb>
+setSignalMask :: SignalSet -> IO SignalSet
+</verb></tscreen>
+
+@setSignalMask mask@ calls @sigprocmask@ with
+@SIG_SETMASK@ to block all interrupts in @mask@. The
+previous set of blocked interrupts is returned.
+
+<tscreen><verb>
+blockSignals :: SignalSet -> IO SignalSet
+</verb></tscreen>
+
+@setSignalMask mask@ calls @sigprocmask@ with
+@SIG_BLOCK@ to add all interrupts in @mask@ to the
+set of blocked interrupts. The previous set of blocked interrupts is returned.
+
+<tscreen><verb>
+unBlockSignals :: SignalSet -> IO SignalSet
+</verb></tscreen>
+
+@setSignalMask mask@ calls @sigprocmask@ with
+@SIG_UNBLOCK@ to remove all interrupts in @mask@ from the
+set of blocked interrupts. The previous set of blocked interrupts is returned.
+
+<tscreen><verb>
+getPendingSignals :: IO SignalSet
+</verb></tscreen>
+
+@getPendingSignals@ calls @sigpending@ to obtain
+the set of interrupts which have been received but are currently blocked.
+
+<tscreen><verb>
+awaitSignal :: Maybe SignalSet -> IO ()
+</verb></tscreen>
+
+@awaitSignal iset@ suspends execution until an interrupt is received.
+If @iset@ is @Just s@, @awaitSignal@ calls
+@sigsuspend@, installing @s@ as the new signal mask before
+suspending execution; otherwise, it calls @pause@. If successful,
+@awaitSignal@ does not return.
+
+<tscreen><verb>
+scheduleAlarm :: Int -> IO Int
+</verb></tscreen>
+
+@scheduleAlarm i@ calls @alarm@ to schedule a real time
+alarm at least @i@ seconds in the future.
+
+<tscreen><verb>
+sleep :: Int -> IO ()
+</verb></tscreen>
+
+@sleep i@ calls @sleep@ to suspend execution of the
+program until at least @i@ seconds have elapsed or a signal is
+received.
+
+<sect2>Posix Process Environment
+<label id="Process Environment">
+<p>
+<nidx>Posix, process environment</nidx>
+
+<tscreen><verb>
+getProcessID :: IO ProcessID
+</verb></tscreen>
+
+@getProcessID@ calls @getpid@ to obtain the @ProcessID@ for
+the current process.
+
+<tscreen><verb>
+getParentProcessID :: IO ProcessID
+</verb></tscreen>
+
+@getProcessID@ calls @getppid@ to obtain the @ProcessID@ for
+the parent of the current process.
+
+<tscreen><verb>
+getRealUserID :: IO UserID
+</verb></tscreen>
+
+@getRealUserID@ calls @getuid@ to obtain the real @UserID@
+associated with the current process.
+
+<tscreen><verb>
+getEffectiveUserID :: IO UserID
+</verb></tscreen>
+
+@getRealUserID@ calls @geteuid@ to obtain the effective
+@UserID@ associated with the current process.
+
+<tscreen><verb>
+setUserID :: UserID -> IO ()
+</verb></tscreen>
+
+@setUserID uid@ calls @setuid@ to set the real, effective, and
+saved set-user-id associated with the current process to @uid@.
+
+<tscreen><verb>
+getLoginName :: IO String
+</verb></tscreen>
+
+@getLoginName@ calls @getlogin@ to obtain the login name
+associated with the current process.
+
+<tscreen><verb>
+getRealGroupID :: IO GroupID
+</verb></tscreen>
+
+@getRealGroupID@ calls @getgid@ to obtain the real @GroupID@
+associated with the current process.
+
+<tscreen><verb>
+getEffectiveGroupID :: IO GroupID
+</verb></tscreen>
+
+@getEffectiveGroupID@ calls @getegid@ to obtain the effective
+@GroupID@ associated with the current process.
+
+<tscreen><verb>
+setGroupID :: GroupID -> IO ()
+</verb></tscreen>
+
+@setGroupID gid@ calls @setgid@ to set the real, effective, and
+saved set-group-id associated with the current process to @gid@.
+
+<tscreen><verb>
+getGroups :: IO [GroupID]
+</verb></tscreen>
+
+@getGroups@ calls @getgroups@ to obtain the list of
+supplementary @GroupID@s associated with the current process.
+
+<tscreen><verb>
+getEffectiveUserName :: IO String
+</verb></tscreen>
+
+@getEffectiveUserName@ calls @cuserid@ to obtain a name
+associated with the effective @UserID@ of the process.
+
+<tscreen><verb>
+getProcessGroupID :: IO ProcessGroupID
+</verb></tscreen>
+
+@getProcessGroupID@ calls @getpgrp@ to obtain the
+@ProcessGroupID@ for the current process.
+
+<tscreen><verb>
+createProcessGroup :: ProcessID -> IO ProcessGroupID
+</verb></tscreen>
+
+@createProcessGroup pid@ calls @setpgid@ to make
+process @pid@ a new process group leader.
+
+<tscreen><verb>
+joinProcessGroup :: ProcessGroupID -> IO ProcessGroupID
+</verb></tscreen>
+
+@joinProcessGroup pgid@ calls @setpgid@ to set the
+@ProcessGroupID@ of the current process to @pgid@.
+
+<tscreen><verb>
+setProcessGroupID :: ProcessID -> ProcessGroupID -> IO ()
+</verb></tscreen>
+
+@setProcessGroupID pid pgid@ calls @setpgid@ to set the
+@ProcessGroupID@ for process @pid@ to @pgid@.
+
+<tscreen><verb>
+createSession :: IO ProcessGroupID
+</verb></tscreen>
+
+@createSession@ calls @setsid@ to create a new session
+with the current process as session leader.
+
+<tscreen><verb>
+systemName :: SystemID -> String
+nodeName :: SystemID -> String
+release :: SystemID -> String
+version :: SystemID -> String
+machine :: SystemID -> String
+
+getSystemID :: IO SystemID
+</verb></tscreen>
+
+@getSystemID@ calls @uname@ to obtain information
+about the current operating system.
+
+<tscreen><verb>
+> epochTime :: IO EpochTime
+</verb></tscreen>
+
+@epochTime@ calls @time@ to obtain the number of
+seconds that have elapsed since the epoch (Jan 01 00:00:00 GMT 1970).
+
+<tscreen><verb>
+elapsedTime :: ProcessTimes -> ClockTick
+userTime :: ProcessTimes -> ClockTick
+systemTime :: ProcessTimes -> ClockTick
+childUserTime :: ProcessTimes -> ClockTick
+childSystemTime :: ProcessTimes -> ClockTick
+
+getProcessTimes :: IO ProcessTimes
+</verb></tscreen>
+
+@getProcessTimes@ calls @times@ to obtain time-accounting
+information for the current process and its children.
+
+<tscreen><verb>
+getControllingTerminalName :: IO FilePath
+</verb></tscreen>
+
+@getControllingTerminalName@ calls @ctermid@ to obtain
+a name associated with the controlling terminal for the process. If a
+controlling terminal exists,
+@getControllingTerminalName@ returns the name of the
+controlling terminal.
+
+The operation may fail with:
+
+<descrip>
+<tag>@NoSuchThing@</tag>
+There is no controlling terminal, or its name cannot be determined.
+<tag>@SystemError@</tag>
+Various other causes.
+</descrip>
+
+<tscreen><verb>
+getTerminalName :: Fd -> IO FilePath
+</verb></tscreen>
+
+@getTerminalName fd@ calls @ttyname@ to obtain a name associated
+with the terminal for @Fd@ @fd@. If @fd@ is associated
+with a terminal, @getTerminalName@ returns the name of the
+terminal.
+
+The operation may fail with:
+
+<descrip>
+<tag>@InappropriateType@</tag>
+The channel is not associated with a terminal.
+<tag>@NoSuchThing@</tag>
+The channel is associated with a terminal, but it has no name.
+<tag>@SystemError@</tag>
+Various other causes.
+</descrip>
+
+<tscreen><verb>
+queryTerminal :: Fd -> IO Bool
+</verb></tscreen>
+
+@queryTerminal fd@ calls @isatty@ to determine whether or
+not @Fd@ @fd@ is associated with a terminal.
+
+<tscreen><verb>
+getSysVar :: SysVar -> IO Limit
+</verb></tscreen>
+
+@getSysVar var@ calls @sysconf@ to obtain the
+dynamic value of the requested configurable system limit or option.
+For defined system limits, @getSysVar@ returns the associated
+value. For defined system options, the result of @getSysVar@
+is undefined, but not failure.
+
+The operation may fail with:
+
+<descrip>
+<tag>@NoSuchThing@</tag>
+The requested system limit or option is undefined.
+</descrip>
+
+<sect2>Posix operations on files and directories
+<label id="Files and Directories">
+<p>
+<nidx>Posix, files and directories</nidx>
+
+<tscreen><verb>
+openDirStream :: FilePath -> IO DirStream
+</verb></tscreen>
+
+@openDirStream dir@ calls @opendir@ to obtain a
+directory stream for @dir@.
+
+<tscreen><verb>
+readDirStream :: DirStream -> IO String
+</verb></tscreen>
+
+@readDirStream dp@ calls @readdir@ to obtain the
+next directory entry (@struct dirent@) for the open directory
+stream @dp@, and returns the @d_name@ member of that
+structure.
+
+The operation may fail with:
+
+<descrip>
+<tag>@EOF@</tag>
+End of file has been reached.
+<tag>@SystemError@</tag>
+Various other causes.
+</descrip>
+
+<tscreen><verb>
+rewindDirStream :: DirStream -> IO ()
+</verb></tscreen>
+
+@rewindDirStream dp@ calls @rewinddir@ to reposition
+the directory stream @dp@ at the beginning of the directory.
+
+<tscreen><verb>
+closeDirStream :: DirStream -> IO ()
+</verb></tscreen>
+
+@closeDirStream dp@ calls @closedir@ to close
+the directory stream @dp@.
+
+<tscreen><verb>
+getWorkingDirectory :: IO FilePath
+</verb></tscreen>
+
+@getWorkingDirectory@ calls @getcwd@ to obtain the name
+of the current working directory.
+
+<tscreen><verb>
+changeWorkingDirectory :: FilePath -> IO ()
+</verb></tscreen>
+
+@changeWorkingDirectory dir@ calls @chdir@ to change
+the current working directory to @dir@.
+
+<tscreen><verb>
+nullFileMode :: FileMode -- ---------
+ownerReadMode :: FileMode -- r--------
+ownerWriteMode :: FileMode -- -w-------
+ownerExecuteMode :: FileMode -- --x------
+groupReadMode :: FileMode -- ---r-----
+groupWriteMode :: FileMode -- ----w----
+groupExecuteMode :: FileMode -- -----x---
+otherReadMode :: FileMode -- ------r--
+otherWriteMode :: FileMode -- -------w-
+otherExecuteMode :: FileMode -- --------x
+setUserIDMode :: FileMode -- --S------
+setGroupIDMode :: FileMode -- -----S---
+
+stdFileMode :: FileMode -- rw-rw-rw-
+
+ownerModes :: FileMode -- rwx------
+groupModes :: FileMode -- ---rwx---
+otherModes :: FileMode -- ------rwx
+accessModes :: FileMode -- rwxrwxrwx
+
+unionFileModes :: FileMode -> FileMode -> FileMode
+intersectFileModes :: FileMode -> FileMode -> FileMode
+
+stdInput :: Fd
+stdInput = intToFd 0
+
+stdOutput :: Fd
+stdOutput = intToFd 1
+
+stdError :: Fd
+stdError = intToFd 2
+
+data OpenFileFlags =
+ OpenFileFlags {
+ append :: Bool,
+ exclusive :: Bool,
+ noctty :: Bool,
+ nonBlock :: Bool,
+ trunc :: Bool
+ }
+
+openFd :: FilePath
+ -> OpenMode
+ -> Maybe FileMode -- Just x => O_CREAT, Nothing => must exist
+ -> OpenFileFlags
+ -> IO Fd
+</verb></tscreen>
+
+@openFd path acc mode (OpenFileFlags app excl noctty nonblock trunc)@ calls
+@open@ to obtain a @Fd@ for the file @path@ with access
+mode @acc@. If @mode@ is @Just m@, the @O_CREAT@ flag is
+set and the file's permissions will be based on @m@ if it does not
+already exist; otherwise, the @O_CREAT@ flag is not set. The
+arguments @app@, @excl@, @noctty@, @nonblock@, and
+@trunc@ control whether or not the flags @O_APPEND@,
+@O_EXCL@, @O_NOCTTY@, @O_NONBLOCK@, and @O_TRUNC@ are set,
+respectively.
+
+<tscreen><verb>
+createFile :: FilePath -> FileMode -> IO Fd
+</verb></tscreen>
+
+@createFile path mode@ calls @creat@ to obtain a @Fd@
+for file @path@, which will be created with permissions based on
+@mode@ if it does not already exist.
+
+<tscreen><verb>
+setFileCreationMask :: FileMode -> IO FileMode
+</verb></tscreen>
+
+@setFileCreationMask mode@ calls @umask@ to set
+the process's file creation mask to @mode@. The previous file
+creation mask is returned.
+
+<tscreen><verb>
+createLink :: FilePath -> FilePath -> IO ()
+</verb></tscreen>
+
+@createLink old new@ calls @link@ to create a
+new path, @new@, linked to an existing file, @old@.
+<tscreen><verb>
+createDirectory :: FilePath -> FileMode -> IO ()
+</verb></tscreen>
+
+@createDirectory dir mode@ calls @mkdir@ to
+create a new directory, @dir@, with permissions based on
+@mode@.
+
+<tscreen><verb>
+createNamedPipe :: FilePath -> FileMode -> IO ()
+</verb></tscreen>
+
+@createNamedPipe fifo mode@ calls @mkfifo@ to
+create a new named pipe, @fifo@, with permissions based on
+@mode@.
+
+<tscreen><verb>
+removeLink :: FilePath -> IO ()
+</verb></tscreen>
+
+@removeLink path@ calls @unlink@ to remove the link
+named @path@.
+
+<tscreen><verb>
+removeDirectory :: FilePath -> IO ()
+</verb></tscreen>
+
+@removeDirectory dir@ calls @rmdir@ to remove the
+directory named @dir@.
+
+<tscreen><verb>
+rename :: FilePath -> FilePath -> IO ()
+</verb></tscreen>
+
+@rename old new@ calls @rename@ to rename a
+file or directory from @old@ to @new@.
+
+<tscreen><verb>
+fileMode :: FileStatus -> FileMode
+
+fileID :: FileStatus -> FileID
+deviceID :: FileStatus -> DeviceID
+
+linkCount :: FileStatus -> LinkCount
+
+fileOwner :: FileStatus -> UserID
+fileGroup :: FileStatus -> GroupID
+fileSize :: FileStatus -> FileOffset
+
+accessTime :: FileStatus -> EpochTime
+modificationTime :: FileStatus -> EpochTime
+statusChangeTime :: FileStatus -> EpochTime
+
+isDirectory :: FileStatus -> Bool
+isCharacterDevice :: FileStatus -> Bool
+isBlockDevice :: FileStatus -> Bool
+isRegularFile :: FileStatus -> Bool
+isNamedPipe :: FileStatus -> Bool
+
+getFileStatus :: FilePath -> IO FileStatus
+</verb></tscreen>
+
+@getFileStatus path@ calls @stat@ to get the
+@FileStatus@ information for the file @path@.
+
+<tscreen><verb>
+getFdStatus :: Fd -> IO FileStatus
+</verb></tscreen>
+
+@getFdStatus fd@ calls @fstat@ to get the
+@FileStatus@ information for the file associated with
+@Fd@ @fd@.
+
+<tscreen><verb>
+queryAccess :: FilePath -> Bool -> Bool -> Bool -> IO Bool
+</verb></tscreen>
+
+@queryAccess path r w x@ calls @access@ to test the access
+permissions for file @path@. The three arguments, @r@, @w@,
+and @x@ control whether or not @access@ is called with
+@R_OK@, @W_OK@, and @X_OK@ respectively.
+
+<tscreen><verb>
+queryFile :: FilePath -> IO Bool
+</verb></tscreen>
+
+@queryFile path@ calls @access@ with @F_OK@ to test for the
+existence for file @path@.
+
+<tscreen><verb>
+setFileMode :: FilePath -> FileMode -> IO ()
+</verb></tscreen>
+
+@setFileMode path mode@ calls @chmod@ to set the
+permission bits associated with file @path@ to @mode@.
+
+<tscreen><verb>
+setOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO ()
+</verb></tscreen>
+
+@setOwnerAndGroup path uid gid@ calls @chown@ to
+set the @UserID@ and @GroupID@ associated with file
+@path@ to @uid@ and @gid@, respectively.
+
+<tscreen><verb>
+setFileTimes :: FilePath -> EpochTime -> EpochTime -> IO ()
+</verb></tscreen>
+
+@setFileTimes path atime mtime@ calls @utime@ to
+set the access and modification times associated with file
+@path@ to @atime@ and @mtime@, respectively.
+
+<tscreen><verb>
+touchFile :: FilePath -> IO ()
+</verb></tscreen>
+
+@touchFile path@ calls @utime@ to
+set the access and modification times associated with file
+@path@ to the current time.
+
+<tscreen><verb>
+getPathVar :: PathVar -> FilePath -> IO Limit
+</verb></tscreen>
+
+@getPathVar var path@ calls @pathconf@ to obtain the
+dynamic value of the requested configurable file limit or option associated
+with file or directory @path@. For
+defined file limits, @getPathVar@ returns the associated
+value. For defined file options, the result of @getPathVar@
+is undefined, but not failure.
+The operation may fail with:
+<descrip>
+<tag>@NoSuchThing@</tag>
+The requested file limit or option is undefined.
+<tag>@SystemError@</tag>
+Various other causes.
+</descrip>
+
+
+<tscreen><verb>
+getFdVar :: PathVar -> Fd -> IO Limit
+</verb></tscreen>
+
+@getFdVar var fd@ calls @fpathconf@ to obtain the
+dynamic value of the requested configurable file limit or option associated
+with the file or directory attached to the open channel @fd@.
+For defined file limits, @getFdVar@ returns the associated
+value. For defined file options, the result of @getFdVar@
+is undefined, but not failure.
+
+The operation may fail with:
+
+<descrip>
+<tag>@NoSuchThing@</tag>
+The requested file limit or option is undefined.
+<tag>@SystemError@</tag>
+Various other causes.
+</descrip>
+
+<sect2>Posix Input and Output Primitives
+<label id="Inut Output">
+<p>
+<nidx>Posix, input/output</nidx>
+
+<tscreen><verb>
+createPipe :: IO (Fd, Fd)
+</verb></tscreen>
+
+@createPipe@ calls @pipe@ to create a pipe and returns a pair of
+@Fd@s, the first for writing and the second for reading.
+
+<tscreen><verb>
+dup :: Fd -> IO Fd
+</verb></tscreen>
+
+@dup fd@ calls @dup@ to duplicate @Fd@ @fd@ to
+another @Fd@.
+
+<tscreen><verb>
+dupTo :: Fd -> Fd -> IO ()
+</verb></tscreen>
+
+@dupTo src dst@ calls @dup2@ to duplicate @Fd@
+@src@ to @Fd@ @dst@.
+
+<tscreen><verb>
+fdClose :: Fd -> IO ()
+</verb></tscreen>
+
+@fdClose fd@ calls @close@ to close @Fd@ @fd@.
+
+<tscreen><verb>
+fdRead :: Fd -> ByteCount -> IO (String, ByteCount)
+</verb></tscreen>
+
+@fdRead fd nbytes@ calls @read@ to read at most @nbytes@
+bytes from @Fd@ @fd@, and returns the result as a string
+paired with the number of bytes actually read.
+
+The operation may fail with:
+
+<descrip>
+<tag>@EOF@</tag>
+End of file has been reached.
+<tag>@SystemError@</tag>
+Various other causes.
+</descrip>
+
+<tscreen><verb>
+fdWrite :: Fd -> String -> IO ByteCount
+</verb></tscreen>
+
+@fdWrite fd s@ calls @write@ to write
+the string @s@ to @Fd@ @fd@ as a
+contiguous sequence of bytes. It returns the number of bytes successfully
+written.
+
+<tscreen><verb>
+queryFdOption :: FdOption -> Fd -> IO Bool
+</verb></tscreen>
+
+@getFdOption opt fd@ calls @fcntl@ to determine whether or
+not the flag associated with @FdOption@ @opt@ is set for
+@Fd@ @fd@.
+
+<tscreen><verb>
+setFdOption :: Fd -> FdOption -> Bool -> IO ()
+</verb></tscreen>
+
+@setFdOption fd opt val@ calls @fcntl@ to set the flag
+associated with @FdOption@ @opt@ on @Fd@ @fd@ to
+@val@.
+
+<tscreen><verb>
+getLock :: Fd -> FileLock -> IO (Maybe (ProcessID, FileLock))
+</verb></tscreen>
+
+@getLock fd lock@ calls @fcntl@ to get the first @FileLock@
+for @Fd@ @fd@ which blocks the @FileLock@ @lock@. If
+no such @FileLock@ exists, @getLock@ returns @Nothing@.
+Otherwise, it returns @Just (pid, block)@, where @block@ is the
+blocking @FileLock@ and @pid@ is the @ProcessID@ of the
+process holding the blocking @FileLock@.
+
+
+<tscreen><verb>
+setLock :: Fd -> FileLock -> IO ()
+</verb></tscreen>
+
+@setLock fd lock@ calls @fcntl@ with @F_SETLK@ to set or
+clear a lock segment for @Fd@ @fd@ as indicated by the
+@FileLock@ @lock@. @setLock@ does not block, but fails with
+@SystemError@ if the request cannot be satisfied immediately.
+
+<tscreen><verb>
+waitToSetLock :: Fd -> FileLock -> IO ()
+</verb></tscreen>
+
+@waitToSetLock fd lock@ calls @fcntl@ with @F_SETLKW@ to set
+or clear a lock segment for @Fd@ @fd@ as indicated by the
+@FileLock@ @lock@. If the request cannot be satisfied
+immediately, @waitToSetLock@ blocks until the request can be
+satisfied.
+
+
+<tscreen><verb>
+fdSeek :: Fd -> SeekMode -> FileOffset -> IO FileOffset
+</verb></tscreen>
+
+@fdSeek fd whence offset@ calls @lseek@ to position the
+@Fd@ @fd@ at the given @offset@ from the starting location
+indicated by @whence@. It returns the resulting offset from the
+start of the file in bytes.
+
+<sect2>Posix, Device- and Class-Specific Functions
+<label id="Device Specific Functions">
+<p>
+<nidx>Posix, device and class-specific functions</nidx>
+
+<tscreen><verb>
+terminalMode :: TerminalMode -> TerminalAttributes -> Bool
+withMode :: TerminalAttributes -> TerminalMode -> TerminalAttributes
+withoutMode :: TerminalAttributes -> TerminalMode -> TerminalAttributes
+
+bitsPerByte :: TerminalAttributes -> Int
+withBits :: TerminalAttributes -> Int -> TerminalAttributes
+
+controlChar :: TerminalAttributes -> ControlCharacter -> Maybe Char
+withCC :: TerminalAttributes
+ -> (ControlCharacter, Char)
+ -> TerminalAttributes
+withoutCC :: TerminalAttributes
+ -> ControlCharacter
+ -> TerminalAttributes
+
+inputTime :: TerminalAttributes -> Int
+withTime :: TerminalAttributes -> Int -> TerminalAttributes
+
+minInput :: TerminalAttributes -> Int
+withMinInput :: TerminalAttributes -> Int -> TerminalAttributes
+
+inputSpeed :: TerminalAttributes -> BaudRate
+withInputSpeed :: TerminalAttributes -> BaudRate -> TerminalAttributes
+
+outputSpeed :: TerminalAttributes -> BaudRate
+withOutputSpeed :: TerminalAttributes -> BaudRate -> TerminalAttributes
+
+getTerminalAttributes :: Fd -> IO TerminalAttributes
+</verb></tscreen>
+
+@getTerminalAttributes fd@ calls @tcgetattr@ to obtain
+the @TerminalAttributes@ associated with @Fd@ @fd@.
+
+<tscreen><verb>
+setTerminalAttributes :: Fd
+ -> TerminalAttributes
+ -> TerminalState
+ -> IO ()
+</verb></tscreen>
+
+@setTerminalAttributes fd attr ts@ calls @tcsetattr@ to change
+the @TerminalAttributes@ associated with @Fd@ @fd@ to
+@attr@, when the terminal is in the state indicated by @ts@.
+
+<tscreen><verb>
+sendBreak :: Fd -> Int -> IO ()
+</verb></tscreen>
+
+@sendBreak fd duration@ calls @tcsendbreak@ to transmit a
+continuous stream of zero-valued bits on @Fd@ @fd@ for the
+specified implementation-dependent @duration@.
+
+<tscreen><verb>
+drainOutput :: Fd -> IO ()
+</verb></tscreen>
+
+@drainOutput fd@ calls @tcdrain@ to block until all output
+written to @Fd@ @fd@ has been transmitted.
+
+<tscreen><verb>
+discardData :: Fd -> QueueSelector -> IO ()
+</verb></tscreen>
+
+@discardData fd queues@ calls @tcflush@ to discard
+pending input and/or output for @Fd@ @fd@,
+as indicated by the @QueueSelector@ @queues@.
+
+<tscreen><verb>
+controlFlow :: Fd -> FlowAction -> IO ()
+</verb></tscreen>
+
+@controlFlow fd action@ calls @tcflow@ to control the
+flow of data on @Fd@ @fd@, as indicated by
+@action@.
+
+<tscreen><verb>
+getTerminalProcessGroupID :: Fd -> IO ProcessGroupID
+</verb></tscreen>
+
+@getTerminalProcessGroupID fd@ calls @tcgetpgrp@ to
+obtain the @ProcessGroupID@ of the foreground process group
+associated with the terminal attached to @Fd@ @fd@.
+
+<tscreen><verb>
+setTerminalProcessGroupID :: Fd -> ProcessGroupID -> IO ()
+</verb></tscreen>
+
+@setTerminalProcessGroupID fd pgid@ calls @tcsetpgrp@ to
+set the @ProcessGroupID@ of the foreground process group
+associated with the terminal attached to @Fd@
+@fd@ to @pgid@.
+
+<sect2>Posix System Databases
+<label id="System Database">
+<p>
+<nidx>Posix, system databases</nidx>
+
+<tscreen><verb>
+groupName :: GroupEntry -> String
+groupID :: GroupEntry -> GroupID
+groupMembers :: GroupEntry -> [String]
+
+getGroupEntryForID :: GroupID -> IO GroupEntry
+</verb></tscreen>
+
+@getGroupEntryForID gid@ calls @getgrgid@ to obtain
+the @GroupEntry@ information associated with @GroupID@
+@gid@.
+
+The operation may fail with:
+
+<descrip>
+<tag>@NoSuchThing@</tag>
+There is no group entry for the GroupID.
+</descrip>
+
+<tscreen><verb>
+getGroupEntryForName :: String -> IO GroupEntry
+</verb></tscreen>
+
+@getGroupEntryForName name@ calls @getgrnam@ to obtain
+the @GroupEntry@ information associated with the group called
+@name@.
+
+The operation may fail with:
+
+<descrip>
+<tag>@NoSuchThing@</tag>
+There is no group entry for the name.
+</descrip>
+
+<tscreen><verb>
+userName :: UserEntry -> String
+userID :: UserEntry -> UserID
+userGroupID :: UserEntry -> GroupID
+homeDirectory :: UserEntry -> String
+userShell :: UserEntry -> String
+
+getUserEntryForID :: UserID -> IO UserEntry
+</verb></tscreen>
+
+@getUserEntryForID gid@ calls @getpwuid@ to obtain
+the @UserEntry@ information associated with @UserID@
+@uid@.
+The operation may fail with:
+
+<descrip>
+<tag>@NoSuchThing@</tag>
+There is no user entry for the UserID.
+</descrip>
+
+<tscreen><verb>
+getUserEntryForName :: String -> IO UserEntry
+</verb></tscreen>
+
+@getUserEntryForName name@ calls @getpwnam@ to obtain
+the @UserEntry@ information associated with the user login
+@name@.
+
+The operation may fail with:
+
+<descrip>
+<tag>@NoSuchThing@</tag>
+There is no user entry for the name.
+</descrip>
+
+<sect2>POSIX Errors
+<label id="Error reporting and handling">
+<p>
+<nidx>Posix, errors</nidx>
+
+<tscreen><verb>
+getErrorCode :: IO ErrorCode
+</verb></tscreen>
+
+@getErrorCode@ returns the current value of the external
+variable @errno@. It never fails.
+
+<tscreen><verb>
+setErrorCode :: ErrorCode -> IO ()
+</verb></tscreen>
+
+@setErrorCode err@ sets the external
+variable @errno@ to @err@. It never fails.
+
+<tscreen><verb>
+noError :: ErrorCode
+noError = 0
+
+argumentListTooLong, e2BIG :: ErrorCode
+badFd, eBADF :: ErrorCode
+brokenPipe, ePIPE :: ErrorCode
+directoryNotEmpty, eNOTEMPTY :: ErrorCode
+execFormatError, eNOEXEC :: ErrorCode
+fileAlreadyExists, eEXIST :: ErrorCode
+fileTooLarge, eFBIG :: ErrorCode
+filenameTooLong, eNAMETOOLONG :: ErrorCode
+improperLink, eXDEV :: ErrorCode
+inappropriateIOControlOperation, eNOTTY :: ErrorCode
+inputOutputError, eIO :: ErrorCode
+interruptedOperation, eINTR :: ErrorCode
+invalidArgument, eINVAL :: ErrorCode
+invalidSeek, eSPIPE :: ErrorCode
+isADirectory, eISDIR :: ErrorCode
+noChildProcess, eCHILD :: ErrorCode
+noLocksAvailable, eNOLCK :: ErrorCode
+noSpaceLeftOnDevice, eNOSPC :: ErrorCode
+noSuchOperationOnDevice, eNODEV :: ErrorCode
+noSuchDeviceOrAddress, eNXIO :: ErrorCode
+noSuchFileOrDirectory, eNOENT :: ErrorCode
+noSuchProcess, eSRCH :: ErrorCode
+notADirectory, eNOTDIR :: ErrorCode
+notEnoughMemory, eNOMEM :: ErrorCode
+operationNotImplemented, eNOSYS :: ErrorCode
+operationNotPermitted, ePERM :: ErrorCode
+permissionDenied, eACCES :: ErrorCode
+readOnlyFileSystem, eROFS :: ErrorCode
+resourceBusy, eBUSY :: ErrorCode
+resourceDeadlockAvoided, eDEADLK :: ErrorCode
+resourceTemporarilyUnavailable, eAGAIN :: ErrorCode
+tooManyLinks, eMLINK :: ErrorCode
+tooManyOpenFiles, eMFILE :: ErrorCode
+tooManyOpenFilesInSystem, eNFILE :: ErrorCode
+
+</verb></tscreen>
+++ /dev/null
-%
-% Included by prof-options.lit and how_to_run.lit
-%
-
-To make use of the cost centre profiling system {\em all} modules must
-be compiled and linked with the \tr{-prof} option.\index{-prof option}
-Any \tr{_scc_} constructs you've put in your source will spring to life.
-
-Without a \tr{-prof} option, your \tr{_scc_}s are ignored; so you can
-compiled \tr{_scc_}-laden code without changing it.
-
-There are a few other profiling-related compilation options. Use them
-{\em in addition to} \tr{-prof}. These do not have to be used
-consistently for all modules in a program.
-
-\begin{description}
-\item[\tr{-auto}:]
-\index{-auto option}
-GHC will automatically add \tr{_scc_} constructs for
-all top-level, exported functions.
-
-\item[\tr{-auto-all}:]
-\index{-auto-all option}
-{\em All} top-level functions, exported or not, will be automatically
-\tr{_scc_}'d.
-
-\item[\tr{-caf-all}:]
-\index{-caf-all option}
-The costs of all CAFs in a module are usually attributed to one
-``big'' CAF cost-centre. With this option, all CAFs get their own cost-centre.
-An ``if all else fails'' option...
-
-%\item[\tr{-dict-all}:]
-%\index{-dict-all option}
-%Similarly, this option means that all ``dictionaries'' (internal
-%constructs to support Haskell overloading) should get their own
-%cost-centre. (Again, the costs are usually attributed to one ``big''
-%DICT cost-centre.)
-%
-%Incidentally, something is probably Bad Wrong (i.e., a GHC bug) if you
-%see big costs attributed to dictionaries.
-
-\item[\tr{-ignore-scc}:]
-\index{-ignore-scc option}
-Ignore any \tr{_scc_} constructs,
-so a module which already has \tr{_scc_}s can be
-compiled for profiling with the annotations ignored.
-
-\item[\tr{-G<group>}:]
-\index{-G<group> option}
-Specifies the \pl{<group>} to be attached to all the cost-centres
-declared in the module. If no group is specified it defaults to the
-module name.
-\end{description}
-
-In addition to the \tr{-prof} option your system might be setup to
-enable you to compile and link with the \tr{-prof-details}
-\index{\tr{-prof-details option}} option instead. This enables
-additional detailed counts to be reported with the \tr{-P} RTS option.
-%-prof-details should also enable age profiling if we get it going again ...
-
-%Alternative profiling semantics have also been implemented. To use
-%these the runtime system and prelude libraries must have been built
-%for the alternative profiling setup. This is done using a particular
-%UserWay setup. If your system has this been built for this profiling
-%system the alternative profiling system will normally be invoked using
-%the options:
-%\begin{description}
-%\item[\tr{-lex}:]
-%\index{-eval option}
-%for lexical profiling.
-%\item[\tr{-eval}:]
-%\index{-eval option}
-%for evaluation profiling.
-%\end{description}
-%All modules must be consistently compiled with the \tr{-lex} or
-%\tr{-eval} option instead of the \tr{-prof} option. The other
-%profiling options are still applicable.
-%
-%Finally we note that the options which dump the program source during
-%compilation may be useful to determine exactly what code is being
-%profiled. Useful options are:
-%\begin{description}
-%\item[\tr{-ddump-ds}:] dump after desugaring. Any automatic \tr{_scc_}
-%annotations will have been added.
-%\item[\tr{-ddump-simpl}:] dump after simplification.
-%\item[\tr{-ddump-stg}:] dump the STG-code immediately before code
-%generation.
-%\end{description}
-
+++ /dev/null
-%************************************************************************
-%* *
-\subsection[prof-compiler-options]{Compiling programs for profiling}
-\index{profiling options}
-\index{options, for profiling}
-%* *
-%************************************************************************
-
-\input{prof-compiler-options.lit}
-
-%************************************************************************
-%* *
-\subsection[prof-rts-options]{Controlling the profiler at runtime}
-\index{profiling RTS options}
-\index{RTS options, for profiling}
-%* *
-%************************************************************************
-
-\input{prof-rts-options.lit}
-
-%************************************************************************
-%* *
-\subsection[prof-graphs]{Producing graphical heap profiles}
-\index{heap profiles, producing}
-%* *
-%************************************************************************
-
-\input{prof-post-processors.lit}
-
-
+++ /dev/null
-%
-% Included by profiling.lit
-%
-
-When you run your profiled program with the \tr{-p} RTS option
-\index{\tr{-p<sort> RTS option (profiling)}}, you get the following
-information about your ``cost centres'':
-
-\begin{description}
-%-------------------------------------------------------------
-\item[\tr{COST CENTRE}:] The cost-centre's name.
-%-------------------------------------------------------------
-\item[\tr{MODULE}:]
-The module associated with the cost-centre;
-important mostly if you have identically-named cost-centres in
-different modules.
-%-------------------------------------------------------------
-\item[\tr{scc}:]
-How many times this cost-centre was entered; think
-of it as ``I got to the \tr{_scc_} construct this many times...''
-%-------------------------------------------------------------
-\item[\tr{%time}:]
-What part of the time was spent in this cost-centre (see also ``ticks,''
-below).
-%-------------------------------------------------------------
-\item[\tr{%alloc}:]
-What part of the memory allocation was done in this cost-centre
-(see also ``bytes,'' below).
-%-------------------------------------------------------------
-\item[\tr{inner}:]
-How many times this cost-centre ``passed control'' to an inner
-cost-centre; for example, \tr{scc=4} plus \tr{subscc=8} means
-``This \tr{_scc_} was entered four times, but went out to
-other \tr{_scc_s} eight times.''
-%-------------------------------------------------------------
-\item[\tr{cafs}:]
-How many CAFs this cost centre evaluated.
-%-------------------------------------------------------------
-\item[\tr{dicts}:]
-How many dictionaries this cost centre evaluated.
-\end{description}
-
-In addition you can use the \tr{-P} RTS option \index{\tr{-P<sort> RTS
- option (profiling)}} to get the following additional information:
-\begin{description}
-%-------------------------------------------------------------
-\item[\tr{ticks}:] The raw number of time ``ticks'' which were
-attributed to this cost-centre; from this, we get the \tr{%time}
-figure mentioned above.
-%-------------------------------------------------------------
-\item[\tr{bytes}:] Number of bytes allocated in the heap while in
-this cost-centre; again, this is the raw number from which we
-get the \tr{%alloc} figure mentioned above.
-\end{description}
-
-Finally if you built your program with \tr{-prof-details}
-\index{\tr{-prof-details option}} the \tr{-P} RTS option will also
-produce the following information:
-\begin{description}
-%-------------------------------------------------------------
-\item[\tr{closures}:]
-How many heap objects were allocated; these objects may be of varying
-size. If you divide the number of bytes (mentioned below) by this
-number of ``closures'', then you will get the average object size.
-(Not too interesting, but still...)
-%-------------------------------------------------------------
-\item[\tr{thunks}:]
-How many times we entered (evaluated) a thunk---an unevaluated
-object in the heap---while we were in this cost-centre.
-%-------------------------------------------------------------
-\item[\tr{funcs}:]
-How many times we entered (evaluated) a function while we we in this
-cost-centre. (In Haskell, functions are first-class values and may be
-passed as arguments, returned as results, evaluated, and generally
-manipulated just like data values)
-%-------------------------------------------------------------
-\item[\tr{PAPs}:]
-How many times we entered (evaluated) a partial application (PAP), i.e.,
-a function applied to fewer arguments than it needs. For example, \tr{Int}
-addition applied to one argument would be a PAP. A PAP is really
-just a particular form for a function.
-\end{description}
+++ /dev/null
-%
-% Included by prof-options.lit
-%
-
-Utility programs which produce graphical profiles.
-
-\subsubsection[hp2ps]{\tr{hp2ps}--heap profile to PostScript}
-\index{hp2ps (utility)}
-\index{heap profiles}
-\index{PostScript, from heap profiles}
-
-%\vspace{2ex}
-%\begin{quote}
-USAGE: \tr{hp2ps} [flags] [\pl{<file>}[\tr{.stat}]]
-%\end{quote}
-
-The program \tr{hp2ps}\index{hp2ps} converts a heap profile as
-produced by the \tr{-h<break-down>}\index{-h<break-down> RTS option}
-runtime option into a PostScript graph of the heap profile. By
-convention, the file to be processed by \tr{hp2ps} has a \tr{.hp}
-extension. The PostScript output is written to \pl{<file>}\tr{.ps}. If
-\pl{<file>} is omitted entirely, then the program behaves as a filter.
-
-\tr{hp2ps} is distributed in \tr{ghc/utils/hp2ps}. It was originally
-developed by Dave Wakeling as part of the HBC/LML heap
-profiler.
-
-
-The flags are:
-\begin{description}
-\item[\tr{-d}]
-In order to make graphs more readable, \tr{hp2ps} 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
-\tr{-d} option causes rougher bands (those representing series of
-values with the largest standard deviations) to be stacked on top of
-smoother ones.
-
-\item[\tr{-b}]
-Normally, \tr{hp2ps} 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
-\tr{hp2ps} will choose to use a big box instead. The \tr{-b}
-option forces \tr{hp2ps} to use a big box.
-
-\item[\tr{-e<float>[in|mm|pt]}]
-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 \tr{hp2ps} 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 \tr{-e} 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 \tr{dvips}.
-
-\item[\tr{-g}]
-Create output suitable for the \tr{gs} PostScript previewer (or
-similar). In this case the graph is printed in portrait mode without
-scaling. The output is unsuitable for a laser printer.
-
-\item[\tr{-l}]
-Normally a profile is limited to 20 bands with additional identifiers
-being grouped into an \tr{OTHER} band. The \tr{-l} 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.
-
-\item[\tr{-m<int>}]
-Normally a profile is limited to 20 bands with additional identifiers
-being grouped into an \tr{OTHER} band. The \tr{-m} flag specifies an
-alternative band limit (the maximum is 20).
-
-\tr{-m0} 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.
-
-\item[\tr{-p}]
-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 \tr{-p} flag causes
-the graph to be drawn using the parameters determined by a previous
-run of \tr{hp2ps} on \pl{file}. These are extracted from
-\pl{file}\tr{.aux}.
-
-\item[\tr{-s}] Use a small box for the title.
-
-\item[\tr{-t<float>}]
-Normally trace elements which sum to a total of less than 1\% of the
-profile are removed from the profile. The \tr{-t} option allows this
-percentage to be modified (maximum 5\%).
-
-\tr{-t0} requests no trace elements to be removed from the profile,
-ensuring that all the data will be displayed.
-
-\item[\tr{-?}] Print out usage information.
-\end{description}
-
-\subsubsection[stat2resid]{\tr{stat2resid}---residency info from GC stats}
-\index{stat2resid (utility)}
-\index{GC stats---residency info}
-\index{residency, from GC stats}
-
-%\vspace{2ex}
-%\begin{quote}
-USAGE: \tr{stat2resid} [\pl{<file>}[\tr{.stat}] [\pl{<outfile>}]]
-%\end{quote}
-
-The program \tr{stat2resid}\index{stat2resid} converts a detailed
-garbage collection statistics file produced by the
-\tr{-S}\index{-S RTS option} runtime option into a PostScript heap
-residency graph. The garbage collection statistics file can be
-produced without compiling your program for profiling.
-
-By convention, the file to be processed by \tr{stat2resid} has a
-\tr{.stat} extension. If the \pl{<outfile>} is not specified the
-PostScript will be written to \pl{<file>}\tr{.resid.ps}. If
-\pl{<file>} is omitted entirely, then the program behaves as a filter.
-
-The plot can not be produced from the statistics file for a
-generational collector, though a suitable stats file can be produced
-using the \tr{-F2s}\index{-F2s RTS option} runtime option when the
-program has been compiled for generational garbage collection (the
-default).
-
-\tr{stat2resid} is distributed in \tr{ghc/utils/stat2resid}.
+++ /dev/null
-What the bits of a profiling report mean.
+++ /dev/null
-%
-% Included by prof-options.lit and runtime_control.lit
-%
-
-It isn't enough to compile your program for profiling with \tr{-prof}!
-
-When you {\em run} your profiled program, you must tell the runtime system (RTS)
-what you want to profile (e.g., time and/or space), and how you wish
-the collected data to be reported. You also may wish to set the
-sampling interval used in time profiling.
-
-Executive summary: \tr{./a.out +RTS -pT} produces a time profile in
-\tr{a.out.prof}; \tr{./a.out +RTS -hC} produces space-profiling
-info which can be mangled by \tr{hp2ps} and viewed with \tr{ghostview}
-(or equivalent).
-
-Profiling runtime flags are passed to your program between the usual
-\tr{+RTS} and \tr{-RTS} options.
-
-\begin{description}
-\item[\tr{-p<sort>} or \tr{-P<sort>}:]
-\index{-p<sort> RTS option (profiling)}
-\index{-P<sort> RTS option (profiling)}
-\index{time profile}
-\index{serial time profile}
-The \tr{-p?} option produces a standard {\em time profile} report.
-It is written into the file \pl{<program>}\tr{.prof}.
-
-The \tr{-P?} option produces a more detailed report containing the
-actual time and allocation data as well. (Not used much.)
-
-The \tr{-P?} option also produces {\em serial time-profiling}
-information, in the file \pl{<program>}\tr{.time}. This can be
-converted into a (somewhat unsatisfactory) PostScript graph using
-\tr{hp2ps} (see \Sectionref{hp2ps}).
-
-???? -F2s needed for serial time profile??? ToDo
-
-The \pl{<sort>} indicates how the cost centres are to be sorted in the
-report. Valid \pl{<sort>} options are:
-\begin{description}
-\item[\tr{T}:] by time, largest first (the default);
-\item[\tr{A}:] by bytes allocated, largest first;
-\item[\tr{C}:] alphabetically by group, module and cost centre.
-\end{description}
-
-\item[\tr{-i<secs>}:]
-\index{-i<secs> RTS option (profiling)}
-Set the profiling (sampling) interval to \tr{<secs>} seconds (the
-default is 1~second).
-
-\item[\tr{-h<break-down>}:]
-\index{-h<break-down> RTS option (profiling)}
-\index{heap profile}
-Produce a detailed {\em space profile} of the heap occupied by live
-closures. The profile is written to the file \pl{<program>}\tr{.hp}
-from which a PostScript graph can be produced using \tr{hp2ps} (see
-\Sectionref{hp2ps}).
-
-The heap space profile may be broken down by different criteria:
-\begin{description}
-\item[\tr{-hC}:] cost centre which produced the closure (the default).
-\item[\tr{-hM}:] cost centre module which produced the closure.
-\item[\tr{-hG}:] cost centre group which produced the closure.
-\item[\tr{-hD}:] closure description --- a string describing the closure.
-\item[\tr{-hY}:] closure type --- a string describing the closure's type.
-%\item[\tr{-hT<ints>,<start>}:] the time interval the closure was
-%created. \tr{<ints>} specifies the no. of interval bands plotted
-%(default 18) and \tr{<start>} the number of seconds after which the
-%reported intervals start (default 0.0).
-\end{description}
-By default all live closures in the heap are profiled, but particular
-closures of interest can be selected (see below).
-\end{description}
-
-
-Heap (space) profiling uses hash tables. If these tables
-should fill the run will abort. The
-\tr{-z<tbl><size>}\index{-z<tbl><size> RTS option (profiling)} option is used to
-increase the size of the relevant hash table (\tr{C}, \tr{M},
-\tr{G}, \tr{D} or \tr{Y}, defined as for \pl{<break-down>} above). The
-actual size used is the next largest power of 2.
-
-The heap profile can be restricted to particular closures of interest.
-The closures of interest can selected by the attached cost centre
-(module:label, module and group), closure category (description, type,
-and kind) and closure age using the following options:
-\begin{description}
-\item[\tr{-c{<mod>:<lab>,<mod>:<lab>...}}:]
-\index{-c{<lab>} RTS option (profiling)}
-Selects individual cost centre(s).
-\item[\tr{-m{<mod>,<mod>...}}:]
-\index{-m{<mod>} RTS option (profiling)}
-Selects all cost centres from the module(s) specified.
-\item[\tr{-g{<grp>,<grp>...}}:]
-\index{-g{<grp>} RTS option (profiling)}
-Selects all cost centres from the groups(s) specified.
-\item[\tr{-d{<des>,<des>...}}:]
-\index{-d{<des>} RTS option (profiling)}
-Selects closures which have one of the specified descriptions.
-\item[\tr{-y{<typ>,<typ>...}}:]
-\index{-y{<typ>} RTS option (profiling)}
-Selects closures which have one of the specified type descriptions.
-\item[\tr{-k{<knd>,<knd>...}}:]
-\index{-k{<knd>} RTS option (profiling)}
-Selects closures which are of one of the specified closure kinds.
-Valid closure kinds are \tr{CON} (constructor), \tr{FN} (manifest
-function), \tr{PAP} (partial application), \tr{BH} (black hole) and
-\tr{THK} (thunk).
-%\item[\tr{-a<age>}:]
-%\index{-a<age> RTS option (profiling)}
-%Selects closures which have survived \pl{<age>} complete intervals.
-\end{description}
-The space occupied by a closure will be reported in the heap profile
-if the closure satisfies the following logical expression:
-\begin{display}
-([-c] or [-m] or [-g]) and ([-d] or [-y] or [-k]) %and [-a]
-\end{display}
-where a particular option is true if the closure (or its attached cost
-centre) is selected by the option (or the option is not specified).
+++ /dev/null
-\begin{onlystandalone}
-\documentstyle[11pt,literate]{article}
-\begin{document}
-\title{The Glorious Haskell Compilation System\\ Profiling Guide}
-\author{The GHC Team (Patrick M. Sansom)\\
-Department of Computing Science\\
-University of Glasgow\\
-Glasgow, Scotland\\
-G12 8QQ\\
-\\
-Email: glasgow-haskell-\{users,bugs\}-request\@dcs.gla.ac.uk}
-\maketitle
-\begin{rawlatex}
-\tableofcontents
-\end{rawlatex}
-\end{onlystandalone}
-
-\section[profiling]{Profiling Haskell programs}
-\index{profiling, with cost-centres}
-\index{cost-centre profiling}
-
-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.
-
-%This profiling system is still under development.
-%Please e-mail reports of any bugs you discover to
-%\tr{glasgow-haskell-bugs@dcs.gla.ac.uk}.
-
-Any comments, suggestions and/or improvements you have to are welcome.
-Recommended ``profiling tricks'' would be especially cool!
-
-\subsection[profiling-intro]{How to profile a Haskell program}
-
-The GHC approach to profiling is very simple: annotate the expressions
-you consider ``interesting'' with {\em cost centre} labels (strings);
-so, for example, you might have:
-
-\begin{verbatim}
-f x y
- = let
- output1 = _scc_ "Pass1" ( pass1 x )
- output2 = _scc_ "Pass2" ( pass2 output1 y )
- output3 = _scc_ "Pass3" ( pass3 (output2 `zip` [1 .. ]) )
- in concat output3
-\end{verbatim}
-
-The costs of the evaluating the expressions bound to \tr{output1},
-\tr{output2} and \tr{output3} will be attributed to the ``cost
-centres'' \tr{Pass1}, \tr{Pass2} and \tr{Pass3}, respectively.
-
-The costs of evaluating other expressions, e.g., \tr{concat output4},
-will be inherited by the scope which referenced the function \tr{f}.
-
-You can put in cost-centres via \tr{_scc_} constructs by hand, as in
-the example above. Perfectly cool. That's probably what you {\em
-would} do if your program divided into obvious ``passes'' or
-``phases'', or whatever.
-
-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 \tr{_scc_}
-constructs, automagically. Add an \tr{-auto} compilation flag to the
-usual \tr{-prof} option.
-
-Once you start homing in on the Guilty Suspects, you may well switch
-from automagically-inserted cost-centres to a few well-chosen ones of
-your own.
-
-To use profiling, you must {\em compile} and {\em run} with special
-options. (We usually forget the ``run'' magic!---Do as we say, not as
-we do...) Details follow.
-
-If you're serious about this profiling game, you should probably read
-one or more of the Sansom/Peyton Jones papers about the GHC profiling
-system. Just visit the Glasgow FP Web page...
-
-%************************************************************************
-%* *
-\subsection[prof-compiler-options]{Compiling programs for profiling}
-\index{profiling options}
-\index{options, for profiling}
-%* *
-%************************************************************************
-
-\input{prof-compiler-options.lit}
-
-%************************************************************************
-%* *
-\subsection[prof-rts-options]{How to control your profiled program at runtime}
-\index{profiling RTS options}
-\index{RTS options, for profiling}
-%* *
-%************************************************************************
-
-\input{prof-rts-options.lit}
-
-%************************************************************************
-%* *
-\subsection[prof-output]{What's in a profiling report?}
-\index{profiling report, meaning thereof}
-%* *
-%************************************************************************
-
-\input{prof-output.lit}
-
-%************************************************************************
-%* *
-\subsection[prof-graphs]{Producing graphical heap profiles}
-\index{heap profiles, producing}
-%* *
-%************************************************************************
-
-\input{prof-post-processors.lit}
-
-% \subsection[cost-centres]{Profiling by Cost Centres}
-%
-% Problems with lazy evaluation
-%
-% The central idea is to identify particular source code expressions of
-% interest. These expressions are annotated with a {\em cost
-% centre}\index{cost centre} label. Execution and allocation costs are
-% attributed to the cost centre label which encloses the expression
-% incurring the costs.
-%
-% Simple example
-%
-% (Note: the paper in \tr{ghc/docs/papers/profiling.ps} may have some
-% decent examples...)
-%
-% Costs are attribution to one cost centre.
-% Inheritance of un-profiled costs.
-%
-% Degree of evaluation
-% Unevaluated arguments
-% Optimisation and transformation
-% Evaluation of instances
-% escaping functions: evaluation vs lexical
-%
-% \subsection[prof-annotations]{Annotating your Haskell source}
-%
-% Explicit annotations
-% Automatic annotation
-%
-% \subsection[prof-information]{Profiling information}
-%
-% Cost Centre Label,Module,Group
-% Example time/alloc profile
-%
-% Description of heap profile
-% Closure Description, Type and Kind
-% \subsection[limitations]{Limitations of the current profiling system}
-%
-% There are a number of limitations and shortcomings of the current
-% profiling system. Any comments on the impact of these and any
-% suggested improvements would be greatly appreciated.
-%
-% \begin{onlylatex}
-% \subsubsection*{Explicit \tr{_scc_} annotations}
-% \end{onlylatex}
-% \begin{onlyinfo}
-% Explicit \tr{_scc_} annotations:
-% \end{onlyinfo}
-%
-% The explicit \tr{_scc_} source annotations cannot annotate entire
-% function declarations as the clauses, pattern matching are not part of
-% the expression syntax --- they are syntactic sugar. It is possible to
-% remove the syntactic sugar by hand, translating to a simple
-% declaration with case expressions on the rhs, but this is very
-% tiresome.
-%
-% We propose to introduce an additional annotation to enable a \tr{_scc_}
-% annotation to be placed around an entire declaration.
-%
-% To further ease the explicit annotation process we also propose to
-% provide annotations which instruct the compiler to annotate all the
-% declarations in a particular \tr{let} or \tr{where} clause with the
-% name of the declaration.
-%
-% Other annotation schemes are feasible. Any suggestions / requests?
-%
-%
-% \begin{onlylatex}
-% \subsubsection*{Closure descriptions}
-% \end{onlylatex}
-% \begin{onlyinfo}
-% Closure descriptions:
-% \end{onlyinfo}
-%
-% The closure descriptions are by no means perfect ...
-%
-% The descriptions for expressions are somewhat tedious as they reflect
-% some of the structure of the transformed STG code. This is largely to
-% provide additional information so use of the STG code can be made if
-% required (use the compiler option \tr{-ddump-stg}). This may be
-% removed if the name of the \pl{corner} is considered sufficient.
-%
-% Local bindings introduced by the compiler have a name \tr{?<tag>}.
-% Most of these are not related to the source in any meaningful way. For
-% example, the \tr{?stg} names are introduced during the CoreToStg pass.
-% Some other arbitrary compiler introduced names are: \tr{?ds},
-% \tr{?tpl}, \tr{?si}, \tr{?cs}, \tr{?ll}, and \tr{?sat}. Please let us
-% know if any of these turn out to be a problem. We could introduce a
-% more meaningful naming scheme into the compiler which assigns names
-% that reflect the nearest enclosing source binding. Another possibility
-% is to add the unique identifier so they aren't all clumped together as
-% one indistinguishable description.
-%
-% There is only one closure description and type for all black holes,
-% ``BH''. It might be useful to record the closure that is currently
-% being evaluated as part of the black hole description.
-%
-% Similarly there is only one partial application description, ``PAP''.
-% It might be useful to record the function being applied in the partial
-% application as part of the partial application description.
-%
-%
-% \begin{onlylatex}
-% \subsubsection*{Garbage collection and paging}
-% \end{onlylatex}
-% \begin{onlyinfo}
-% Garbage collection and paging:
-% \end{onlyinfo}
-%
-% Currently the profiling implementation requires the two-space
-% (\tr{-gc-2s}) garbage collector to be used. When using the \tr{-prof}
-% options a particular garbage collector should not be specified. This
-% imposes particular paging characteristics which may be different from
-% the garbage collector your program normally uses. These paging
-% characteristics may distort the user time profiling results, though we
-% do not believe this is a significant problem.
-%
-%
-% \subsection[references]{Papers describing this work}
-%
-% A discussion of our initial ideas are described in the paper
-% ``Profiling Lazy Functional Languages'' by Patrick Sansom and Simon
-% Peyton Jones.
-%
-% It is in the GHC distribution in \tr{ghc/docs/papers/profiling.ps},
-% or it can be retrieved using ftp from
-% \tr{ftp.dcs.gla.ac.uk} (\tr{[130.209.240.50]})
-% in the file
-% \tr{pub/glasgow-fp/papers/lazy-profiling.ps}.
-
-\begin{onlystandalone}
-\printindex
-\end{document}
-\end{onlystandalone}
--- /dev/null
+<sect1>Profiling
+<label id="profiling">
+<p>
+<nidx>profiling, with cost-centres</nidx>
+<nidx>cost-centre profiling</nidx>
+
+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.
+
+Any comments, suggestions and/or improvements you have to are welcome.
+Recommended ``profiling tricks'' would be especially cool!
+
+<sect2>How to profile a Haskell program
+<label id="profiling-intro">
+<p>
+
+The GHC approach to profiling is very simple: annotate the expressions
+you consider ``interesting'' with <em>cost centre</em> labels (strings);
+so, for example, you might have:
+
+<tscreen><verb>
+f x y
+ = let
+ output1 = _scc_ "Pass1" ( pass1 x )
+ output2 = _scc_ "Pass2" ( pass2 output1 y )
+ output3 = _scc_ "Pass3" ( pass3 (output2 `zip` [1 .. ]) )
+ in concat output3
+</verb></tscreen>
+
+The costs of the evaluating the expressions bound to @output1@,
+@output2@ and @output3@ will be attributed to the ``cost
+centres'' @Pass1@, @Pass2@ and @Pass3@, respectively.
+
+The costs of evaluating other expressions, e.g., @concat output4@,
+will be inherited by the scope which referenced the function @f@.
+
+You can put in cost-centres via @_scc_@ constructs by hand, as in the
+example above. Perfectly cool. That's probably what you
+<em>would</em> do if your program divided into obvious ``passes'' or
+``phases'', or whatever.
+
+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 @_scc_@
+constructs, automagically. Add an @-auto@ compilation flag to the
+usual @-prof@ option.
+
+Once you start homing in on the Guilty Suspects, you may well switch
+from automagically-inserted cost-centres to a few well-chosen ones of
+your own.
+
+To use profiling, you must <em>compile</em> and <em>run</em> with special
+options. (We usually forget the ``run'' magic!---Do as we say, not as
+we do...) Details follow.
+
+If you're serious about this profiling game, you should probably read
+one or more of the Sansom/Peyton Jones papers about the GHC profiling
+system. Just visit the <url name="Glasgow FP group web page"
+url="http://www.dcs.gla.ac.uk/fp/">...
+
+<sect2>Compiling programs for profiling
+<label id="prof-compiler-options">
+<p>
+<nidx>profiling options</nidx>
+<nidx>options, for profiling</nidx>
+
+To make use of the cost centre profiling system <em>all</em> modules must
+be compiled and linked with the @-prof@ option.<nidx>-prof option</nidx>
+Any @_scc_@ constructs you've put in your source will spring to life.
+
+Without a @-prof@ option, your @_scc_@s are ignored; so you can
+compiled @_scc_@-laden code without changing it.
+
+There are a few other profiling-related compilation options. Use them
+<em>in addition to</em> @-prof@. These do not have to be used
+consistently for all modules in a program.
+
+<descrip>
+<tag>@-auto@:</tag>
+<nidx>-auto option</nidx>
+<nidx>cost centres, automatically inserting</nidx>
+GHC will automatically add @_scc_@ constructs for
+all top-level, exported functions.
+
+<tag>@-auto-all@:</tag>
+<nidx>-auto-all option</nidx>
+<em>All</em> top-level functions, exported or not, will be automatically
+@_scc_@'d.
+
+<tag>@-caf-all@:</tag>
+<nidx>-caf-all option</nidx>
+The costs of all CAFs in a module are usually attributed to one
+``big'' CAF cost-centre. With this option, all CAFs get their own cost-centre.
+An ``if all else fails'' option...
+
+%<tag>@-dict-all@:</tag>
+%<nidx>-dict-all option</nidx>
+%Similarly, this option means that all ``dictionaries'' (internal
+%constructs to support Haskell overloading) should get their own
+%cost-centre. (Again, the costs are usually attributed to one ``big''
+%DICT cost-centre.)
+%
+%Incidentally, something is probably Bad Wrong (i.e., a GHC bug) if you
+%see big costs attributed to dictionaries.
+
+<tag>@-ignore-scc@:</tag>
+<nidx>-ignore-scc option</nidx>
+Ignore any @_scc_@ constructs,
+so a module which already has @_scc_@s can be
+compiled for profiling with the annotations ignored.
+
+<tag>@-G<group>@:</tag>
+<nidx>-G<group> option</nidx>
+Specifies the @<group>@ to be attached to all the cost-centres
+declared in the module. If no group is specified it defaults to the
+module name.
+</descrip>
+
+In addition to the @-prof@ option your system might be setup to enable
+you to compile and link with the @-prof-details@ <nidx>-prof-details
+option</nidx> option instead. This enables additional detailed counts
+to be reported with the @-P@ RTS option.
+
+%-prof-details should also enable age profiling if we get it going again ...
+
+<sect2>How to control your profiled program at runtime
+<label id="prof-rts-options">
+<p>
+<nidx>profiling RTS options</nidx>
+<nidx>RTS options, for profiling</nidx>
+
+It isn't enough to compile your program for profiling with @-prof@!
+
+When you <em>run</em> your profiled program, you must tell the runtime
+system (RTS) what you want to profile (e.g., time and/or space), and
+how you wish the collected data to be reported. You also may wish to
+set the sampling interval used in time profiling.
+
+Executive summary: @./a.out +RTS -pT@ produces a time profile in
+@a.out.prof@; @./a.out +RTS -hC@ produces space-profiling
+info which can be mangled by @hp2ps@ and viewed with @ghostview@
+(or equivalent).
+
+Profiling runtime flags are passed to your program between the usual
+@+RTS@ and @-RTS@ options.
+
+<descrip>
+<tag>@-p<sort>@ or @-P<sort>@:</tag>
+<nidx>-p<sort> RTS option (profiling)</nidx>
+<nidx>-P<sort> RTS option (profiling)</nidx>
+<nidx>time profile</nidx>
+<nidx>serial time profile</nidx>
+The @-p?@ option produces a standard <em>time profile</em> report.
+It is written into the file @<program>@@.prof@.
+
+The @-P?@ option produces a more detailed report containing the
+actual time and allocation data as well. (Not used much.)
+
+%The @-P?@ option also produces <em>serial time-profiling</em>
+%information, in the file @<program>@@.time@. This can be
+%converted into a (somewhat unsatisfactory) PostScript graph using
+%@hp2ps@ (see Section <ref name="hp2ps - heap profile to PostScript" id="hp2ps">).
+
+%???? -F2s needed for serial time profile??? ToDo
+
+The @<sort>@ indicates how the cost centres are to be sorted in the
+report. Valid @<sort>@ options are:
+<descrip>
+<tag>@T@:</tag> by time, largest first (the default);
+<tag>@A@:</tag> by bytes allocated, largest first;
+<tag>@C@:</tag> alphabetically by group, module and cost centre.
+</descrip>
+
+<tag>@-i<secs>@:</tag>
+<nidx>-i<secs> RTS option (profiling)</nidx>
+Set the profiling (sampling) interval to @<secs>@ seconds (the
+default is 1~second).
+
+<tag>@-h<break-down>@:</tag>
+<nidx>-h<break-down> RTS option (profiling)</nidx>
+<nidx>heap profile</nidx>
+
+Produce a detailed <em>space profile</em> of the heap occupied by live
+closures. The profile is written to the file @<program>@@.hp@ from
+which a PostScript graph can be produced using @hp2ps@ (see Section
+<ref name="hp2ps - heap profile to PostScript" id="hp2ps">).
+
+The heap space profile may be broken down by different criteria:
+<descrip>
+<tag>@-hC@:</tag> cost centre which produced the closure (the default).
+<tag>@-hM@:</tag> cost centre module which produced the closure.
+<tag>@-hG@:</tag> cost centre group which produced the closure.
+<tag>@-hD@:</tag> closure description --- a string describing the closure.
+<tag>@-hY@:</tag> closure type --- a string describing the closure's type.
+%<tag>@-hT<ints>,<start>@:</tag> the time interval the closure was
+%created. @<ints>@ specifies the no. of interval bands plotted
+%(default 18) and @<start>@ the number of seconds after which the
+%reported intervals start (default 0.0).
+</descrip>
+By default all live closures in the heap are profiled, but particular
+closures of interest can be selected (see below).
+</descrip>
+
+
+Heap (space) profiling uses hash tables. If these tables
+should fill the run will abort. The
+@-z<tbl><size>@<nidx>-z<tbl><size> RTS option (profiling)</nidx> option is used to
+increase the size of the relevant hash table (@C@, @M@,
+@G@, @D@ or @Y@, defined as for @<break-down>@ above). The
+actual size used is the next largest power of 2.
+
+The heap profile can be restricted to particular closures of interest.
+The closures of interest can selected by the attached cost centre
+(module:label, module and group), closure category (description, type,
+and kind) using the following options:
+
+<descrip>
+<tag>@-c{<mod>:<lab>,<mod>:<lab>...@}:</tag>
+<nidx>-c{<lab></nidx> RTS option (profiling)}
+Selects individual cost centre(s).
+<tag>@-m{<mod>,<mod>...@}:</tag>
+<nidx>-m{<mod></nidx> RTS option (profiling)}
+Selects all cost centres from the module(s) specified.
+<tag>@-g{<grp>,<grp>...@}:</tag>
+<nidx>-g{<grp></nidx> RTS option (profiling)}
+Selects all cost centres from the groups(s) specified.
+<tag>@-d{<des>,<des>...@}:</tag>
+<nidx>-d{<des></nidx> RTS option (profiling)}
+Selects closures which have one of the specified descriptions.
+<tag>@-y{<typ>,<typ>...@}:</tag>
+<nidx>-y{<typ></nidx> RTS option (profiling)}
+Selects closures which have one of the specified type descriptions.
+<tag>@-k{<knd>,<knd>...@}:</tag>
+<nidx>-k{<knd></nidx> RTS option (profiling)}
+Selects closures which are of one of the specified closure kinds.
+Valid closure kinds are @CON@ (constructor), @FN@ (manifest
+function), @PAP@ (partial application), @BH@ (black hole) and
+@THK@ (thunk).
+</descrip>
+
+The space occupied by a closure will be reported in the heap profile
+if the closure satisfies the following logical expression:
+
+<quote>
+([-c] or [-m] or [-g]) and ([-d] or [-y] or [-k])
+</quote>
+
+where a particular option is true if the closure (or its attached cost
+centre) is selected by the option (or the option is not specified).
+
+<sect2>What's in a profiling report?
+<label id="prof-output">
+<p>
+<nidx>profiling report, meaning thereof</nidx>
+
+When you run your profiled program with the @-p@ RTS option <nidx>-p
+RTS option</nidx>, you get the following information about your ``cost
+centres'':
+
+<descrip>
+%-------------------------------------------------------------
+<tag>@COST CENTRE@:</tag> The cost-centre's name.
+%-------------------------------------------------------------
+<tag>@MODULE@:</tag>
+The module associated with the cost-centre;
+important mostly if you have identically-named cost-centres in
+different modules.
+%-------------------------------------------------------------
+<tag>@scc@:</tag>
+How many times this cost-centre was entered; think
+of it as ``I got to the @_scc_@ construct this many times...''
+%-------------------------------------------------------------
+<tag>@%time@:</tag>
+What part of the time was spent in this cost-centre (see also ``ticks,''
+below).
+%-------------------------------------------------------------
+<tag>@%alloc@:</tag>
+What part of the memory allocation was done in this cost-centre
+(see also ``bytes,'' below).
+%-------------------------------------------------------------
+<tag>@inner@:</tag>
+How many times this cost-centre ``passed control'' to an inner
+cost-centre; for example, @scc=4@ plus @subscc=8@ means
+``This @_scc_@ was entered four times, but went out to
+other @_scc_s@ eight times.''
+%-------------------------------------------------------------
+<tag>@cafs@:</tag>
+<nidx>CAF, profiling</nidx>
+How many CAFs this cost centre evaluated.
+%-------------------------------------------------------------
+<tag>@dicts@:</tag>
+<nidx>Dictionaries, profiling</nidx>
+How many dictionaries this cost centre evaluated.
+</descrip>
+
+In addition you can use the @-P@ RTS option <nidx></nidx> to get the following additional information:
+<descrip>
+%-------------------------------------------------------------
+<tag>@ticks@:</tag> The raw number of time ``ticks'' which were
+attributed to this cost-centre; from this, we get the @%time@
+figure mentioned above.
+%-------------------------------------------------------------
+<tag>@bytes@:</tag> Number of bytes allocated in the heap while in
+this cost-centre; again, this is the raw number from which we
+get the @%alloc@ figure mentioned above.
+</descrip>
+
+Finally if you built your program with @-prof-details@
+<nidx></nidx> the @-P@ RTS option will also
+produce the following information:
+<descrip>
+%-------------------------------------------------------------
+<tag>@closures@:</tag>
+<nidx>closures, profiling</nidx>
+How many heap objects were allocated; these objects may be of varying
+size. If you divide the number of bytes (mentioned below) by this
+number of ``closures'', then you will get the average object size.
+(Not too interesting, but still...)
+%-------------------------------------------------------------
+<tag>@thunks@:</tag>
+<nidx>thunks, profiling</nidx>
+How many times we entered (evaluated) a thunk---an unevaluated
+object in the heap---while we were in this cost-centre.
+%-------------------------------------------------------------
+<tag>@funcs@:</tag>
+<nidx>functions, profiling</nidx>
+How many times we entered (evaluated) a function while we we in this
+cost-centre. (In Haskell, functions are first-class values and may be
+passed as arguments, returned as results, evaluated, and generally
+manipulated just like data values)
+%-------------------------------------------------------------
+<tag>@PAPs@:</tag>
+<nidx>partial applications, profiling</nidx>
+How many times we entered (evaluated) a partial application (PAP), i.e.,
+a function applied to fewer arguments than it needs. For example, @Int@
+addition applied to one argument would be a PAP. A PAP is really
+just a particular form for a function.
+</descrip>
+
+<sect2>Producing graphical heap profiles
+<label id="prof-graphs">
+<p>
+<nidx>heap profiles, producing</nidx>
+
+Utility programs which produce graphical profiles.
+
+<sect3>@hp2ps@--heap profile to PostScript
+<label id="hp2ps">
+<p>
+<nidx>hp2ps (utility)</nidx>
+<nidx>heap profiles</nidx>
+<nidx>PostScript, from heap profiles</nidx>
+
+Usage:
+
+<tscreen> <verb>
+hp2ps [flags] [<file>[.stat]]
+</verb> </tscreen>
+
+The program @hp2ps@<nidx>hp2ps program</nidx> converts a heap profile
+as produced by the @-h<break-down>@<nidx>-h<break-down> RTS
+option</nidx> runtime option into a PostScript graph of the heap
+profile. By convention, the file to be processed by @hp2ps@ has a
+@.hp@ extension. The PostScript output is written to @<file>@@.ps@. If
+@<file>@ is omitted entirely, then the program behaves as a filter.
+
+@hp2ps@ is distributed in @ghc/utils/hp2ps@ in a GHC source
+distribution. It was originally developed by Dave Wakeling as part of
+the HBC/LML heap profiler.
+
+The flags are:
+<descrip>
+<tag>@-d@</tag>
+In order to make graphs more readable, @hp2ps@ 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
+@-d@ option causes rougher bands (those representing series of
+values with the largest standard deviations) to be stacked on top of
+smoother ones.
+
+<tag>@-b@</tag>
+Normally, @hp2ps@ 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
+@hp2ps@ will choose to use a big box instead. The @-b@
+option forces @hp2ps@ to use a big box.
+
+<tag>@-e<float>[in|mm|pt]@</tag>
+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 @hp2ps@ 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 @-e@ 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 @dvips@.
+
+<tag>@-g@</tag>
+Create output suitable for the @gs@ PostScript previewer (or
+similar). In this case the graph is printed in portrait mode without
+scaling. The output is unsuitable for a laser printer.
+
+<tag>@-l@</tag>
+Normally a profile is limited to 20 bands with additional identifiers
+being grouped into an @OTHER@ band. The @-l@ 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.
+
+<tag>@-m<int>@</tag>
+Normally a profile is limited to 20 bands with additional identifiers
+being grouped into an @OTHER@ band. The @-m@ flag specifies an
+alternative band limit (the maximum is 20).
+
+@-m0@ 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.
+
+<tag>@-p@</tag>
+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 @-p@ flag causes
+the graph to be drawn using the parameters determined by a previous
+run of @hp2ps@ on @file@. These are extracted from
+@file@@.aux@.
+
+<tag>@-s@</tag> Use a small box for the title.
+
+<tag>@-t<float>@</tag>
+Normally trace elements which sum to a total of less than 1\% of the
+profile are removed from the profile. The @-t@ option allows this
+percentage to be modified (maximum 5\%).
+
+@-t0@ requests no trace elements to be removed from the profile,
+ensuring that all the data will be displayed.
+
+<tag>@-?@</tag> Print out usage information.
+</descrip>
+
+<sect3>@stat2resid@---residency info from GC stats
+<label id="stat2resid">
+<p>
+<nidx>stat2resid (utility)</nidx>
+<nidx>GC stats---residency info</nidx>
+<nidx>residency, from GC stats</nidx>
+
+Usage:
+
+<tscreen> <verb>
+stat2resid [<file>[.stat] [<outfile>]]
+</verb> </tscreen>
+
+The program @stat2resid@<nidx>stat2resid</nidx> converts a detailed
+garbage collection statistics file produced by the
+@-S@<nidx>-S RTS option</nidx> runtime option into a PostScript heap
+residency graph. The garbage collection statistics file can be
+produced without compiling your program for profiling.
+
+By convention, the file to be processed by @stat2resid@ has a
+@.stat@ extension. If the @<outfile>@ is not specified the
+PostScript will be written to @<file>@@.resid.ps@. If
+@<file>@ is omitted entirely, then the program behaves as a filter.
+
+The plot can not be produced from the statistics file for a
+generational collector, though a suitable stats file can be produced
+using the @-F2s@<nidx>-F2s RTS option</nidx> runtime option when the
+program has been compiled for generational garbage collection (the
+default).
+
+@stat2resid@ is distributed in @ghc/utils/stat2resid@ in a GHC source
+distribution.
+
+%************************************************************************
+%* *
+<sect2>Using ``ticky-ticky'' profiling (for implementors)
+<label id="ticky-ticky">
+<p>
+<nidx>ticky-ticky profiling (implementors)</nidx>
+%* *
+%************************************************************************
+
+(ToDo: document properly.)
+
+It is possible to compile Glasgow Haskell programs so that they will
+count lots and lots of interesting things, e.g., number of updates,
+number of data constructors entered, etc., etc. We call this
+``ticky-ticky'' profiling,<nidx>ticky-ticky profiling</nidx>%
+<nidx>profiling, ticky-ticky</nidx> because that's the sound a Sun4 makes
+when it is running up all those counters (<em>slowly</em>).
+
+Ticky-ticky profiling is mainly intended for implementors; it is quite
+separate from the main ``cost-centre'' profiling system, intended for
+all users everywhere.
+
+To be able to use ticky-ticky profiling, you will need to have built
+appropriate libraries and things when you made the system. See
+``Customising what libraries to build,'' in the installation guide.
+
+To get your compiled program to spit out the ticky-ticky numbers, use
+a @-r@ RTS option<nidx>-r RTS option</nidx>.
+++ /dev/null
-%************************************************************************
-%* *
-%* Stuff for : Real Soon Now *
-%* *
-%************************************************************************
-
-Below is a short list of things we hope to tackle soon. We welcome
-prodding, cajoling, large sums of money, offers of holidays in warm
-climates... Umm, excuse me, I got carried away....
-
-\begin{description}
-%-------------------------------------------------------------------
-\item[Compilation speed:]
-This is still our \#1 priority. (Actually, we {\em have} saved a lot
-on compilation time since~0.16; however, we've spent a goodly chunk of
-our winnings.)
-
-%-------------------------------------------------------------------
-\item[Revised I/O scheme:] We've {\em finally} figured out the right
-way to do this ``state'' stuff; see the Launchbury/Peyton Jones ``Lazy
-Functional State Threads'' paper (draft; check
-\tr{ghc/docs/abstracts/abstracts93.tex}).
-
-Simultaneously, the Haskell~1.3 I/O proposal is coming along. We hope
-to use the former to do the latter, if you know what I mean.
-
-%-------------------------------------------------------------------
-\item[More with unfoldings:]
-And our new simplifier. Both of these new pieces of machinery are
-still a bit ``raw.'' (The reason we don't quote performance numbers
-is because we haven't collected any yet.)
-
-%-------------------------------------------------------------------
-\item[Specialised instances:] Tedious and boring.
-
-%-------------------------------------------------------------------
-\item[More with ``semi-tagging'':]
-(which we haven't done much with yet...) and other code-generator-ish
-hacks. [It depends how close we let Simon get to the code.]
-
-%-------------------------------------------------------------------
-\item[More tuning:]
-We're {\em generally} happy with the time/space behaviour of Haskell
-programs compiled with this system. But there's always work to do.
-
-We still welcome a copy of any Haskell program for which a competing
-compiler generates better code. We want to stamp out these
-unfortunate anomalies!
-\end{description}
+++ /dev/null
-%************************************************************************
-%* *
-\section[separate-compilation]{Separate compilation}
-\index{separate compilation}
-\index{recompilation checker}
-\index{make and recompilation}
-%* *
-%************************************************************************
-
-This section describes how GHC supports separate compilation.
-
-\subsection[hi-files]{Interface files}
-
-When GHC compiles a source module @A@, it generates an object @A.o@, {\em and} a
-companion {\em interface file} @A.hi@. The interface file
-contains information needed by the compiler when it compiles any module @B@ that
-imports @A@, whether directly or indirectly. When compiling @B@, GHC will
-read @A.hi@ to find the details that it needs to know about things defined in @A@.
-
-Furthermore, when compiling module @C@ which imports @B@, GHC may decide that it
-needs to know something about @A@ --- for example, @B@ might export a function
-that involves a type defined in @A@. In this case, GHC will go and read @A.hi@ even
-though @C@ does not explicitly import @A@ at all.
-
-The interface file may contain all sorts of things that aren't explicitly
-exported from @A@ by the programmer. For example, even though a data type is exported
-abstractly, @A.hi@ will contain the full data type definition. For small function
-definitions, @A.hi@ will contain the complete definition of the function. For
-bigger functions, @A.hi@ will contain strictness information about the function. And so on.
-GHC puts much more information into @.hi@ files when you use @-O@. Without @-O@
-it puts in just the minimum; with @-O@ it lobs in a whole pile of stuff.
-
-@A.hi@ should really be thought of as a compiler-readable version of @A.o@.
-If you use a @.hi@ file that wasn't generated by the same compilation run that
-generates the @.o@ file the compiler may assume all sorts of incorrect things about @A@,
-resulting in core dumps and other unpleasant happenings.
-
-In the olden days, GHC compared the newly-generated @.hi@ 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 @.hi@ file were not recompiled.
-
-This doesn't work any more. In our earlier example, module @C@ does
-not import module @A@ directly, yet changes to @A.hi@ should force a
-recompilation of @C@. And some changes to @A@ (changing the
-definition of a function that appears in an inlining of a function
-exported by @B@, say) may conceivably not change @B.hi@ one jot. So
-now
-
-
-\subsection[recomp]{The recompilation checker}
-
-GHC keeps a version number on each interface file, and on each type
-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 @.o@ file's date (i.e. the source hasn't changed since the
-file was last compiled), and you give GHC the @-recomp@ flag, then GHC
-will be clever. It compares the version numbers on the things it
-needs this time with the version numbers on the things it needed last
-time (gleaned from the interface file of the module being compiled);
-if they are all the same it stops compiling rather early in the
-process saying ``Recompilation not required''. What a beautiful
-sight!
-
-It's still an experimental feature (that's why @-recomp@ is off by
-default), so tell us if you think it doesn't work.
-
-Patrick Sansom has a workshop paper about how all this is
-done. Ask him (email: \tr{sansom}) if you want a copy.
-
-\subsection{Using @make@}
-
-It is reasonably straightforward to set up a \tr{Makefile} to use with
-GHC, assuming you name your source files the same as your modules.
-Thus:
-\begin{verbatim}
-HC = ghc
-HC_OPTS = -cpp $(EXTRA_HC_OPTS)
-
-SRCS = Main.lhs Foo.lhs Bar.lhs
-OBJS = Main.o Foo.o Bar.o
-
-.SUFFIXES : .o .hi .lhs .hc .s
-
-cool_pgm : $(OBJS)
- $(RM) $@
- $(HC) -o $@ $(HC_OPTS) $(OBJS)
-
-# Standard suffix rules
-.o.hi:
- @:
-
-.lhs.o:
- $(RM) $@
- $(HC) -c $< $(HC_OPTS)
-
-.hs.o:
- $(RM) $@
- $(HC) -c $< $(HC_OPTS)
-
-# Optional
-.hc.o:
- $(RM) $@
- $(HC) -c $< $(HC_OPTS)
-
-# Optional
-.s.o:
- $(RM) $@
- $(HC) -c $< $(HC_OPTS)
-
-
-# Inter-module dependencies
-Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
-Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz
-\end{verbatim}
-
-(Sophisticated \tr{make} variants may achieve some of the above more
-elegantly. Notably, @gmake@'s pattern rules let you write the more comprehensible:
-\begin{verbatim}
-%.o : %.lhs
- $(RM) $@
- $(HC) -c $< $(HC_OPTS)
-\end{verbatim}
-What we've shown should work with any \tr{make}.)
-
-Note the cheesy \tr{.o.hi} rule: It records the dependency of the
-interface (\tr{.hi}) file on the source. The rule says a \tr{.hi}
-file can be made from a \tr{.o} file by doing... nothing. Which is
-true.
-
-Note the inter-module dependencies at the end of the Makefile, which take the form
-\begin{verbatim}
-Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
-\end{verbatim}
-They tell @make@ that if any of @Foo.o@, @Foo.hc@ or @Foo.s@ have
-an earlier modification date than @Baz.hi@, then the out-of-date
-file must be brought up to date. To bring it up to date, @make@ looks
-for a rule to do so; one of the preceding suffix rules does the job nicely.
-
-Putting inter-dependencies of the form \tr{Foo.o : Bar.hi} into your
-\tr{Makefile} by hand is rather error-prone. Don't worry---never
-fear, \tr{mkdependHS} is here! (and is distributed as part of GHC)
-Add the following to your \tr{Makefile}:
-\begin{verbatim}
-depend :
- mkdependHS -- $(HC_OPTS) -- $(SRCS)
-\end{verbatim}
-Now, before you start compiling, and any time you change the
-\tr{imports} in your program, do \tr{make depend} before you do
-\tr{make cool_pgm}. \tr{mkdependHS} will append the needed
-dependencies to your \tr{Makefile}. @mkdependHS@ is fully
-describe in \Sectionref{mkdependHS}.
-
-
-
-
-
-
-A few caveats about this simple scheme: (a)~You may need to compile
-some modules explicitly to create their interfaces in the first place
-(e.g., \tr{make Bar.o} to create \tr{Bar.hi}). (b)~You may have to
-type \tr{make} more than once for the dependencies to have full
-effect. However, a \tr{make} run that does nothing {\em does} mean
-``everything's up-to-date.'' (c) This scheme will work with
-mutually-recursive modules but, again, it may take multiple
-iterations to ``settle.''
-
-
-
+++ /dev/null
-\begin{onlystandalone}
-\documentstyle[11pt,literate]{article}
-\begin{document}
-\title{Release notes for Glasgow Haskell}
-\author{The GHC Team\\
-Department of Computing Science\\
-University of Glasgow\\
-Glasgow, Scotland\\
-G12 8QQ\\
-\\
-Email: glasgow-haskell-\{users,bugs\}-request\@dcs.gla.ac.uk}
-\maketitle
-\begin{rawlatex}
-\tableofcontents
-\end{rawlatex}
-\clearpage
-\end{onlystandalone}
-
-% NOTE TO MAINTAINERS: the way these notes are organized:
-% (1) What's new in the current release
-% (2) What's next ("real soon now")
-% (3) What was new in previous releases (reverse chronological order)
-% (4) anything else
-%
-% Remember: this isn't the compiler documentation! -- it's just
-% pointers to it. Mentioning something in the release notes is not
-% the same as documenting it.
-
-\section[release-notes]{Release notes}
-
-\subsection[release-3-00]{Release notes for version~3-00---1/97}
-\input{3-00-notes.lit}
-
-\subsection[release-2-10]{Release notes for version~2.10---12/97}
-\input{2-10-notes.lit}
-
-\subsection[release-2-09]{Release notes for version~2.09---11/97}
-\input{2-09-notes.lit}
-
-\subsection[release-2-08]{Release notes for version~2.08---10/97}
-\input{2-08-notes.lit}
-
-\subsection[release-2-06]{Release notes for version~2.06---9/97}
-\input{2-06-notes.lit}
-
-\subsection[release-2-04]{Release notes for version~2.04---6/97}
-\input{2-04-notes.lit}
-
-\subsection[release-2-03]{Release notes for version~2.03---4/97}
-\input{2-03-notes.lit}
-
-\subsection[release-2-02]{Release notes for version~2.02---3/97}
-\downsection
-\input{2-02-notes.lit}
-\upsection
-
-%\section[release-2-01]{Release notes for version~2.01---7/96}
-%\input{2-01-notes.lit}
-
-%\section[release-RSN]{What we hope to do Real Soon Now}
-%\downsection
-%\input{real-soon-now.lit}
-%\upsection
-
-%\section{Versions 0.26 through 0.29}
-
-%GHC~0.26 (7/95) was the last major release of GHC for Haskell~1.2.
-
-%GHC~0.27 (12/95) was a `` binary-only from-working-sources
-%no-guarantees snapshot ... for i386-unknown-linuxaout and
-%i386-unknown-solaris2 platforms...''
-
-%GHC~0.28 (5/96) was the same thing, for the i386-unknown-linux (ELF)
-%platform.
-
-%GHC~0.29 (7/96), released at the same time as 2.01, is just ``0.26
-%with bug fixes''; i.e., the current state-of-play on the Haskell~1.2
-%compiler development.
-
-\subsection[older-release-notes]{Old release notes}
-
-We used to include the release notes back to the dawn of time in this
-document. Made for a nice long document, but it wasn't that
-interesting. If you would like to see old release notes, just ask;
-we've still got 'em.
-
-\begin{onlystandalone}
-% \printindex
-\end{document}
-\end{onlystandalone}
--- /dev/null
+% NOTE TO MAINTAINERS: the way these notes are organized:
+% (1) What's new in the current release
+% (2) What's next ("real soon now")
+% (3) What was new in previous releases (reverse chronological order)
+% (4) anything else
+%
+% Remember: this isn't the compiler documentation! -- it's just
+% pointers to it. Mentioning something in the release notes is not
+% the same as documenting it.
+
+<sect>Release notes
+<label id="release-notes">
+<p>
%************************************************************************
%* *
-\section[runtime-control]{Controlling the run-time behaviour of your programs}
-\index{runtime control of Haskell programs}
-\index{RTS options}
+<sect1>Running a compiled program
+<label id="runtime-control">
+<p>
+<nidx>runtime control of Haskell programs</nidx>
+<nidx>running, compiled program</nidx>
+<nidx>RTS options</nidx>
%* *
%************************************************************************
You have some control over the behaviour of the RTS, by giving special
command-line arguments to your program.
-%You have some control over the behavior of the runtime system, either
-%by giving special command-line arguments to your program (the usual) or by
-%building in your own defaults at compile time (the exotic).
+When your Haskell program starts up, its RTS extracts command-line
+arguments bracketed between @+RTS@<nidx>+RTS option</nidx> and
+@-RTS@<nidx>-RTS option</nidx> as its own. For example:
-When your Haskell program starts up, its RTS extracts
-command-line arguments bracketed between \tr{+RTS}\index{+RTS option}
-and \tr{-RTS}\index{-RTS option} as its own. For example:
-\begin{verbatim}
+<tscreen><verb>
% ./a.out -f +RTS -pT -S -RTS -h foo bar
-\end{verbatim}
-The RTS will snaffle \tr{-pT -S} for itself,
-and the remaining arguments \tr{-f -h foo bar} will be handed
-to your program if/when it calls @System.getArgs@.
-
-No \tr{-RTS} option is required if the runtime-system options extend
-to the end of the command line, as in this example:
-\begin{verbatim}
+</verb></tscreen>
+
+The RTS will snaffle @-pT -S@ for itself, and the remaining arguments
+@-f -h foo bar@ will be handed to your program if/when it calls
+@System.getArgs@.
+
+No @-RTS@ option is required if the runtime-system options extend to
+the end of the command line, as in this example:
+
+<tscreen><verb>
% hls -ltr /usr/etc +RTS -H5m
-\end{verbatim}
+</verb></tscreen>
+
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
-\tr{--RTS}\index{--RTS option}.
+@--RTS@<nidx>--RTS option</nidx>.
-As always, for RTS options that take \tr{<size>}s: If the last
-character of \tr{size} is a K or k, multiply by 1000; if an M or m, by
+As always, for RTS options that take @<size>@s: If the last
+character of @size@ is a K or k, multiply by 1000; if an M or m, by
1,000,000; if a G or G, by 1,000,000,000. (And any wraparound in the
-counters is {\em your} fault!)
+counters is <em>your</em> fault!)
-Giving a \tr{+RTS -f}\index{-f RTS option} option will print out the
+Giving a @+RTS -f@<nidx>-f RTS option</nidx> option will print out the
RTS options actually available in your program (which vary, depending
on how you compiled).
%************************************************************************
%* *
-\subsection{Generally-available RTS options}
-\index{RTS options, general}
+<sect2>Generally-available RTS options
+<p>
+<nidx>RTS options, general</nidx>
%* *
%************************************************************************
The most important RTS options are:
-\begin{description}
-\item[\tr{-H<size>}:]
-\index{-H<size> RTS option}
-Set the heap size to \pl{<size>} bytes
+<descrip>
+<tag>@-H<size>@:</tag>
+<nidx>-H<size> RTS option</nidx>
+Set the heap size to @<size>@ bytes
[default: 4M].
-\item[\tr{-K<size>}:]
-\index{-K<size> RTS option}
-Set the stack size to \pl{<size>} bytes [default: 64K].
+<tag>@-K<size>@:</tag>
+<nidx>-K<size> RTS option</nidx>
+Set the stack size to @<size>@ bytes [default: 64K].
For concurrent/parallel programs, it is the stack size of the main
thread; generally speaking, c/p stacks are in heap.
Note: if your program seems to be consuming infinite stack space, it
is probably in a loop :-) Of course, if stacks are in the heap, make
-that infinite {\em heap} space...
+that infinite <em>heap</em> space...
-\item[\tr{-s<file>} or \tr{-S<file>}:]
-\index{-S<file> RTS option}
-\index{-s<file> RTS option}
-Write modest (\tr{-s}) or verbose (\tr{-S}) garbage-collector
-statistics into file \pl{<file>}. The default \pl{<file>} is
-\pl{<program>}\tr{.stat}. The \pl{<file>} \tr{stderr} is treated
-specially, with the output really being sent to \tr{stderr}.
-
-%Note that \tr{stdout} is flushed before each garbage collection so the
-%interleaving of \tr{stdout} and the garbage collection statistics will
-%be accurate.
-
-%Note that the same program will typically allocate more space with a
-%generational collector than with a non-generational collector.
+<tag>@-s<file>@ or @-S<file>@:</tag>
+<nidx>-S<file> RTS option</nidx>
+<nidx>-s<file> RTS option</nidx>
+Write modest (@-s@) or verbose (@-S@) garbage-collector
+statistics into file @<file>@. The default @<file>@ is
+@<program>@@.stat@. The @<file>@ @stderr@ is treated
+specially, with the output really being sent to @stderr@.
The amount of heap allocation will typically increase as the total
heap size is reduced. The reason for this odd behaviour is that
any pointers from the old generation to the new generation.
For some garbage collectors (not including the default one, sadly),
-you can convert the \tr{-S} output into a residency graph (in
-PostScript), using the \tr{stat2resid}\index{stat2resid} utility in
-the GHC distribution (\tr{ghc/utils/stat2resid}).
+you can convert the @-S@ output into a residency graph (in
+PostScript), using the @stat2resid@<nidx>stat2resid</nidx> utility in
+the GHC distribution (@ghc/utils/stat2resid@).
-\item[\tr{-N}:]
-\index{-N RTS option}
+<tag>@-N@:</tag>
+<nidx>-N RTS option</nidx>
Normally, the garbage collector black-holes closures which are being
evaluated, as a space-saving measure. That's exactly what you want
for ordinary Haskell programs.
When signal handlers are present, however, a computation may be
abandoned prematurely, leaving black holes behind. If the signal
handler shares one of these black-holed closures, disaster can result.
-Use the \tr{-N} option to prevent black-holing by the garbage
-collector if you suspect that your signal handlers may share {\em any}
+Use the @-N@ option to prevent black-holing by the garbage collector
+if you suspect that your signal handlers may share <em>any</em>
subexpressions with the top-level computation. Expect your heap usage
to increase, since the lifetimes of some closures may be extended.
-\end{description}
+</descrip>
%************************************************************************
%* *
-\subsection{RTS options to control the garbage-collector}
-\index{RTS options, garbage-collection}
+<sect2>RTS options to control the garbage-collector
+<p>
+<nidx>RTS options, garbage-collection</nidx>
%* *
%************************************************************************
-Besides the \tr{-H} (set heap size) and \tr{-S}/\tr{-s} (GC stats) RTS
+Besides the @-H@ (set heap size) and @-S@/@-s@ (GC stats) RTS
options, there are several options to give you precise control over
garbage collection.
-\begin{description}
-\item[\tr{-M<n>}:]
-\index{-M<n> RTS option}
-Minimum \% \pl{<n>} of heap which must be available for allocation.
+<descrip>
+<tag>@-M<n>@:</tag>
+<nidx>-M<n> RTS option</nidx>
+Minimum \% @<n>@ of heap which must be available for allocation.
The default is 3\%.
-\item[\tr{-A<size>}:]
-\index{-A<size> RTS option}
+<tag>@-A<size>@:</tag>
+<nidx>-A<size> RTS option</nidx>
Sets a limit on the size of the allocation area for generational
-garbage collection to \pl{<size>} bytes (\tr{-A} gives default of 64k). If
+garbage collection to @<size>@ bytes (@-A@ gives default of 64k). If
a negative size is given the size of the allocation is fixed to
--\pl{<size>}. For non-generational collectors, it fixes the minimum
+-@<size>@. For non-generational collectors, it fixes the minimum
heap which must be available after a collection, overriding the
-\tr{-M<n>} RTS option.
+@-M<n>@ RTS option.
-\item[\tr{-G<size>}:]
-\index{-G<size> RTS option}
+<tag>@-G<size>@:</tag>
+<nidx>-G<size> RTS option</nidx>
Sets the percentage of free space to be promoted before a major
-collection is invoked to \pl{<size>}\%. The default is 66\%. If a
+collection is invoked to @<size>@\%. The default is 66\%. If a
negative size is given it fixes the size of major generation threshold
-to -\pl{<size>} bytes.
+to -@<size>@ bytes.
-\item[\tr{-F2s}:]
-\index{-F2s RTS option}
-Forces a program compiled for generational GC to use two-space copying
-collection. The two-space collector may outperform the generational
-collector for programs which have a very low heap residency. It can
-also be used to generate a statistics file from which a basic heap
-residency profile can be produced (see Section \ref{stat2resid}).
+<tag>@-F2s@:</tag> <nidx>-F2s RTS option</nidx> Forces a program
+compiled for generational GC to use two-space copying collection. The
+two-space collector may outperform the generational collector for
+programs which have a very low heap residency. It can also be used to
+generate a statistics file from which a basic heap residency profile
+can be produced (see Section <ref name="stat2resid - residency info
+from GC stats" id="stat2resid">).
There will still be a small execution overhead imposed by the
generational compilation as the test for old generation updates will
still be executed (of course none will actually happen). This
overhead is typically less than 1\%.
-\item[\tr{-j<size>}:]
-\index{-j<size> RTS option}
-Force a major garbage collection every \pl{<size>} bytes. (Normally
+<tag>@-j<size>@:</tag>
+<nidx>-j<size> RTS option</nidx>
+Force a major garbage collection every @<size>@ bytes. (Normally
used because you're keen on getting major-GC stats, notably heap residency
info.)
-\end{description}
+</descrip>
%************************************************************************
%* *
-\subsection{RTS options for profiling and Concurrent/Parallel Haskell}
+<sect2>RTS options for profiling and Concurrent/Parallel Haskell
+<p>
%* *
%************************************************************************
-The RTS options related to profiling are described in
-\Sectionref{prof-rts-options};
-and those for concurrent/parallel stuff, in \Sectionref{parallel-rts-opts}.
+The RTS options related to profiling are described in Section <ref name="How to control your profiled program at runtime" id="prof-rts-options">; and those for concurrent/parallel stuff, in
+Section <ref name="RTS options for Concurrent/Parallel Haskell" id="parallel-rts-opts">.
%************************************************************************
%* *
-\subsection{RTS options for hackers, debuggers, and over-interested souls}
-\index{RTS options, hacking/debugging}
+<sect2>RTS options for hackers, debuggers, and over-interested souls
+<p>
+<nidx>RTS options, hacking/debugging</nidx>
%* *
%************************************************************************
``what's really happening'', or (c)~because you feel like it. Not
recommended for everyday use!
-\begin{description}
-\item[\tr{-B}:]
-\index{-B RTS option}
+<descrip>
+<tag>@-B@:</tag>
+<nidx>-B RTS option</nidx>
Sound the bell at the start of each (major) garbage collection.
Oddly enough, people really do use this option! Our pal in Durham
program] is in by the beep pattern. But the major use is for annoying
others in the same office...''
-% \item[\tr{-I}:]
-% Use the ``debugging mini-interpreter'' with sanity-checking; you have
-% to have an appropriately-compiled version of the prelude, etc.
-% Goes together nicely with GDB (GNU debugger)...
-% (OLD, REALLY)
-
-\item[\tr{-r<file>}:]
-\index{-r <file> RTS option}
+<tag>@-r<file>@:</tag>
+<nidx>-r <file> RTS option</nidx>
Produce ``ticky-ticky'' statistics at the end of the program run.
-The \tr{<file>} business works just like on the \tr{-S} RTS option (above).
+The @<file>@ business works just like on the @-S@ RTS option (above).
``Ticky-ticky'' statistics are counts of various program actions
(updates, enters, etc.)
The program must have been compiled using
-\tr{-fstg-reduction-counts}\index{-fstg-reduction-counts option}
+@-fstg-reduction-counts@<nidx>-fstg-reduction-counts option</nidx>
(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.
-\item[\tr{-T<num>}:]
-\index{-T RTS option}
+<tag>@-T<num>@:</tag>
+<nidx>-T RTS option</nidx>
An RTS debugging flag; varying quantities of output depending on which bits
-are set in \pl{<num>}.
+are set in @<num>@.
-\item[\tr{-Z}:]
-\index{-Z RTS option}
-Turn {\em off} ``update-frame squeezing'' at garbage-collection time.
+<tag>@-Z@:</tag>
+<nidx>-Z RTS option</nidx>
+Turn <em>off</em> ``update-frame squeezing'' at garbage-collection time.
(There's no particularly good reason to turn it off.)
-\end{description}
+</descrip>
%************************************************************************
%* *
-\subsection[rts-hooks]{``Hooks'' to change RTS behaviour}
-\index{hooks, RTS}
-\index{RTS hooks}
-\index{RTS behaviour, changing}
+<sect2>``Hooks'' to change RTS behaviour
+<label id="rts-hooks">
+<p>
+<nidx>hooks, RTS</nidx>
+<nidx>RTS hooks</nidx>
+<nidx>RTS behaviour, changing</nidx>
%* *
%************************************************************************
hooks, but by writing your own version and linking it on the GHC
command line, you can override the defaults.
-The function @defaultsHook@\index{defaultHook} lets you change various
+The function @defaultsHook@<nidx>defaultHook</nidx> 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 @-H8m -K1m@:
-\begin{verbatim}
+<tscreen><verb>
#include "rtsdefs.h"
void defaultsHook (void) {
RTSflags.GcFlags.stksSize = 1000002 / sizeof(W_);
RTSflags.GcFlags.heapSize = 8000002 / sizeof(W_);
}
-\end{verbatim}
+</verb></tscreen>
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
``blows up,'' e.g., on stack overflow. The hooks for these are as
follows:
-\begin{description}
-\item[\tr{void ErrorHdrHook (FILE *)}:]
-\index{ErrorHdrHook}
-What's printed out before the message from \tr{error}.
+<descrip>
+<tag>@void ErrorHdrHook (FILE *)@:</tag>
+<nidx>ErrorHdrHook</nidx>
+What's printed out before the message from @error@.
-\item[\tr{void OutOfHeapHook (unsigned long, unsigned long)}:]
-\index{OutOfHeapHook}
+<tag>@void OutOfHeapHook (unsigned long, unsigned long)@:</tag>
+<nidx>OutOfHeapHook</nidx>
The heap-overflow message.
-\item[\tr{void StackOverflowHook (long int)}:]
-\index{StackOverflowHook}
+<tag>@void StackOverflowHook (long int)@:</tag>
+<nidx>StackOverflowHook</nidx>
The stack-overflow message.
-\item[\tr{void MallocFailHook (long int)}:]
-\index{MallocFailHook}
-The message printed if \tr{malloc} fails.
+<tag>@void MallocFailHook (long int)@:</tag>
+<nidx>MallocFailHook</nidx>
+The message printed if @malloc@ fails.
-\item[\tr{void PatErrorHdrHook (FILE *)}:]
-\index{PatErrorHdrHook}
+<tag>@void PatErrorHdrHook (FILE *)@:</tag>
+<nidx>PatErrorHdrHook</nidx>
The message printed if a pattern-match fails (the failures
that were not handled by the Haskell programmer).
-\item[\tr{void PreTraceHook (FILE *)}:]
-\index{PreTraceHook}
-What's printed out before a \tr{trace} message.
+<tag>@void PreTraceHook (FILE *)@:</tag>
+<nidx>PreTraceHook</nidx>
+What's printed out before a @trace@ message.
-\item[\tr{void PostTraceHook (FILE *)}:]
-\index{PostTraceHook}
-What's printed out after a \tr{trace} message.
-\end{description}
+<tag>@void PostTraceHook (FILE *)@:</tag>
+<nidx>PostTraceHook</nidx>
+What's printed out after a @trace@ message.
+</descrip>
For example, here is the ``hooks'' code used by GHC itself:
-\begin{verbatim}
+<tscreen><verb>
#include <stdio.h>
#define W_ unsigned long int
#define I_ long int
{
fprintf(where, "\n"); /* not "Trace Off" */
}
-\end{verbatim}
-
-%************************************************************************
-%* *
-%\subsection[rts-control-shell-scripts]{Hiding the runtime-control mess with a shell script}
-%* *
-%************************************************************************
-
-%NOT DONE YET.
-
+</verb></tscreen>
%************************************************************************
%* *
-\section[sooner-faster-quicker]{Advice on: sooner, faster, smaller, stingier}
+<sect>Advice on: sooner, faster, smaller, stingier
+<label id="sooner-faster-quicker">
+<p>
%* *
%************************************************************************
%************************************************************************
%* *
-\subsection[sooner]{Sooner: producing a program more quickly}
-\index{compiling faster}
-\index{faster compiling}
+<sect1>Sooner: producing a program more quickly
+<label id="sooner">
+<p>
+<nidx>compiling faster</nidx>
+<nidx>faster compiling</nidx>
%* *
%************************************************************************
-\begin{description}
+<descrip>
%----------------------------------------------------------------
-\item[Don't use \tr{-O} or (especially) \tr{-O2}:]
+<tag>Don't use @-O@ or (especially) @-O2@:</tag>
By using them, you are telling GHC that you are willing to suffer
longer compilation times for better-quality code.
-GHC is surprisingly zippy for normal compilations without \tr{-O}!
+GHC is surprisingly zippy for normal compilations without @-O@!
%----------------------------------------------------------------
-\item[Use more memory:]
+<tag>Use more memory:</tag>
Within reason, more memory for heap space means less garbage
collection for GHC, which means less compilation time. If you use
-the \tr{-Rgc-stats} option, you'll get a garbage-collector report.
-(Again, you can use the cheap-and-nasty \tr{-optCrts-Sstderr} option to
+the @-Rgc-stats@ option, you'll get a garbage-collector report.
+(Again, you can use the cheap-and-nasty @-optCrts-Sstderr@ option to
send the GC stats straight to standard error.)
If it says you're using more than 20\% of total time in garbage
collecting, then more memory would help.
-You ask for more heap with the \tr{-H<size>}\index{-H<size> option}
-option; e.g.: \tr{ghc -c -O -H16m Foo.hs}.
+You ask for more heap with the @-H<size>@<nidx>-H<size> option</nidx>
+option; e.g.: @ghc -c -O -H16m Foo.hs@.
If GHC persists in being a bad memory citizen, please report it as a
bug.
%----------------------------------------------------------------
-\item[Don't use too much memory!]
+<tag>Don't use too much memory!</tag>
As soon as GHC plus its ``fellow citizens'' (other processes on your machine) start
-using more than the {\em real memory} on your machine, and the machine
-starts ``thrashing,'' {\em the party is over}. Compile times will be
-worse than terrible! Use something like the csh-builtin \tr{time}
+using more than the <em>real memory</em> on your machine, and the machine
+starts ``thrashing,'' <em>the party is over</em>. Compile times will be
+worse than terrible! Use something like the csh-builtin @time@
command to get a report on how many page faults you're getting.
If you don't know what virtual memory, thrashing, and page faults are,
-or you don't know the memory configuration of your machine, {\em
-don't} try to be clever about memory use: you'll just make your life a
+or you don't know the memory configuration of your machine, <em>don't</em> try to be clever about memory use: you'll just make your life a
misery (and for other people, too, probably).
%----------------------------------------------------------------
-\item[Try to use local disks when linking:]
+<tag>Try to use local disks when linking:</tag>
Because Haskell objects and libraries tend to be large, it can take
many real seconds to slurp the bits to/from an NFS filesystem (say).
-It would be quite sensible to {\em compile} on a fast machine using
-remotely-mounted disks; then {\em link} on a slow machine that had
+It would be quite sensible to <em>compile</em> on a fast machine using
+remotely-mounted disks; then <em>link</em> on a slow machine that had
your disks directly mounted.
%----------------------------------------------------------------
-\item[Don't derive/use \tr{Read} unnecessarily:]
+<tag>Don't derive/use @Read@ unnecessarily:</tag>
It's ugly and slow.
%----------------------------------------------------------------
-\item[GHC compiles some program constructs slowly:]
+<tag>GHC compiles some program constructs slowly:</tag>
Deeply-nested list comprehensions seem to be one such; in the past,
very large constant tables were bad, too.
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
-\tr{-fno-strictness}\index{-fno-strictness anti-option} and
-\tr{-fno-update-analysis}.\index{-fno-update-analysis anti-option}
+@-fno-strictness@<nidx>-fno-strictness anti-option</nidx> and
+@-fno-update-analysis@.<nidx>-fno-update-analysis anti-option</nidx>
-If \tr{-ddump-simpl} produces output after a reasonable time, but
-\tr{-ddump-stg} doesn't, then it's probably the update analyser
+If @-ddump-simpl@ produces output after a reasonable time, but
+@-ddump-stg@ doesn't, then it's probably the update analyser
slowing you down.
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.
-If \tr{-ddump-absC} produces output after a reasonable time, but
+If @-ddump-absC@ produces output after a reasonable time, but
nothing after that---it's probably the native-code generator. Bring
-on \tr{-fvia-C}\index{-fvia-C option} (not that GCC will be that quick about it, either).
+on @-fvia-C@<nidx>-fvia-C option</nidx> (not that GCC will be that quick about it, either).
%----------------------------------------------------------------
-\item[Avoid the consistency-check on linking:]
-Use \tr{-no-link-chk}\index{-no-link-chk}; saves effort. This is probably
+<tag>Avoid the consistency-check on linking:</tag>
+Use @-no-link-chk@<nidx>-no-link-chk</nidx>; saves effort. This is probably
safe in a I-only-compile-things-one-way setup.
%----------------------------------------------------------------
-\item[Explicit \tr{import} declarations:]
-Instead of saying \tr{import Foo}, say
-\tr{import Foo (...stuff I want...)}.
+<tag>Explicit @import@ declarations:</tag>
+Instead of saying @import Foo@, say
+@import Foo (...stuff I want...)@.
Truthfully, the reduction on compilation time will be very small.
-However, judicious use of \tr{import} declarations can make a
+However, judicious use of @import@ declarations can make a
program easier to understand, so it may be a good idea anyway.
-\end{description}
+</descrip>
%************************************************************************
%* *
-\subsection[faster]{Faster: producing a program that runs quicker}
-\index{faster programs, how to produce}
+<sect1>Faster: producing a program that runs quicker
+<label id="faster">
+<p>
+<nidx>faster programs, how to produce</nidx>
%* *
%************************************************************************
The key tool to use in making your Haskell program run faster are
GHC's profiling facilities, described separately in
-\sectionref{profiling}. There is {\em no substitute} for finding
-where your program's time/space is {\em really} going, as opposed
+Section <ref name="Profiling" id="profiling">. There is <em>no substitute</em> for finding
+where your program's time/space is <em>really</em> going, as opposed
to where you imagine it is going.
Another point to bear in mind: By far the best way to improve a
-program's performance {\em dramatically} is to use better algorithms.
+program's performance <em>dramatically</em> is to use better algorithms.
Once profiling has thrown the spotlight on the guilty
time-consumer(s), it may be better to re-think your program than to
try all the tweaks listed below.
Another extremely efficient way to make your program snappy is to use
-library code that has been Seriously Tuned By Someone Else. You {\em might} be able
+library code that has been Seriously Tuned By Someone Else. You <em>might</em> be able
to write a better quicksort than the one in the HBC library, but it
-will take you much longer than typing \tr{import QSort}.
+will take you much longer than typing @import QSort@.
(Incidentally, it doesn't hurt if the Someone Else is Lennart
Augustsson.)
definition of ``overly-slow'' is ``the HBC-compiled version ran
faster''...
-\begin{description}
+<descrip>
%----------------------------------------------------------------
-\item[Optimise, using \tr{-O} or \tr{-O2}:] This is the most basic way
+<tag>Optimise, using @-O@ or @-O2@:</tag> This is the most basic way
to make your program go faster. Compilation time will be slower,
-especially with \tr{-O2}.
+especially with @-O2@.
-At present, \tr{-O2} is nearly indistinguishable from \tr{-O}.
+At present, @-O2@ is nearly indistinguishable from @-O@.
-%At version 2.01, \tr{-O} is a dodgy proposition, no matter what.
+%At version 2.01, @-O@ is a dodgy proposition, no matter what.
%----------------------------------------------------------------
-\item[Compile via C and crank up GCC:] Even with \tr{-O}, GHC tries to
+<tag>Compile via C and crank up GCC:</tag> Even with @-O@, 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
allocation, etc.
-So, when we want very fast code, we use: \tr{-O -fvia-C -O2-for-C}.
+So, when we want very fast code, we use: @-O -fvia-C -O2-for-C@.
%----------------------------------------------------------------
-\item[Overloaded functions are not your friend:]
+<tag>Overloaded functions are not your friend:</tag>
Haskell's overloading (using type classes) is elegant, neat, etc.,
etc., but it is death to performance if left to linger in an inner
loop. How can you squash it?
-\begin{description}
-\item[Give explicit type signatures:]
+<descrip>
+<tag>Give explicit type signatures:</tag>
Signatures are the basic trick; putting them on exported, top-level
functions is good software-engineering practice, anyway.
The automatic specialisation of overloaded functions should take care
of overloaded local and/or unexported functions.
-\item[Use \tr{SPECIALIZE} pragmas:]
-\index{SPECIALIZE pragma}
-\index{overloading, death to}
+<tag>Use @SPECIALIZE@ pragmas:</tag>
+<nidx>SPECIALIZE pragma</nidx>
+<nidx>overloading, death to</nidx>
(UK spelling also accepted.) For key overloaded functions, you can
create extra versions (NB: more code space) specialised to particular
types. Thus, if you have an overloaded function:
-\begin{verbatim}
+<tscreen><verb>
hammeredLookup :: Ord key => [(key, value)] -> key -> value
-\end{verbatim}
-If it is heavily used on lists with \tr{Widget} keys, you could
+</verb></tscreen>
+If it is heavily used on lists with @Widget@ keys, you could
specialise it as follows:
-\begin{verbatim}
+<tscreen><verb>
{-# SPECIALIZE hammeredLookup :: [(Widget, value)] -> Widget -> value #-}
-\end{verbatim}
+</verb></tscreen>
To get very fancy, you can also specify a named function to use for
-the specialised value, by adding \tr{= blah}, as in:
-\begin{verbatim}
+the specialised value, by adding @= blah@, as in:
+<tscreen><verb>
{-# SPECIALIZE hammeredLookup :: ...as before... = blah #-}
-\end{verbatim}
-It's {\em Your Responsibility} to make sure that \tr{blah} really
-behaves as a specialised version of \tr{hammeredLookup}!!!
+</verb></tscreen>
+It's <em>Your Responsibility</em> to make sure that @blah@ really
+behaves as a specialised version of @hammeredLookup@!!!
-An example in which the \tr{= blah} form will Win Big:
-\begin{verbatim}
+An example in which the @= blah@ form will Win Big:
+<tscreen><verb>
toDouble :: Real a => a -> Double
toDouble = fromRational . toRational
{-# SPECIALIZE toDouble :: Int -> Double = i2d #-}
i2d (I# i) = D# (int2Double# i) -- uses Glasgow prim-op directly
-\end{verbatim}
-The \tr{i2d} function is virtually one machine instruction; the
-default conversion---via an intermediate \tr{Rational}---is obscenely
+</verb></tscreen>
+The @i2d@ function is virtually one machine instruction; the
+default conversion---via an intermediate @Rational@---is obscenely
expensive by comparison.
-By using the US spelling, your \tr{SPECIALIZE} pragma will work with
-HBC, too. Note that HBC doesn't support the \tr{= blah} form.
+By using the US spelling, your @SPECIALIZE@ pragma will work with
+HBC, too. Note that HBC doesn't support the @= blah@ form.
-A \tr{SPECIALIZE} pragma for a function can be put anywhere its type
+A @SPECIALIZE@ pragma for a function can be put anywhere its type
signature could be put.
-\item[Use \tr{SPECIALIZE instance} pragmas:]
+<tag>Use @SPECIALIZE instance@ pragmas:</tag>
Same idea, except for instance declarations. For example:
-\begin{verbatim}
+<tscreen><verb>
instance (Eq a) => Eq (Foo a) where { ... usual stuff ... }
{-# SPECIALIZE instance Eq (Foo [(Int, Bar)] #-}
-\end{verbatim}
+</verb></tscreen>
Compatible with HBC, by the way.
-See also: overlapping instances, in \Sectionref{glasgow-hbc-exts}.
-They are to \tr{SPECIALIZE instance} pragmas what \tr{= blah}
-hacks are to \tr{SPECIALIZE} (value) pragmas...
+% See also: overlapping instances, in Section <ref name="``HBC-ish''
+% extensions implemented by GHC" id="glasgow-hbc-exts">. They are to
+% @SPECIALIZE instance@ pragmas what @= blah@ hacks are to @SPECIALIZE@
+% (value) pragmas...
-\item[``How do I know what's happening with specialisations?'':]
+<tag>``How do I know what's happening with specialisations?'':</tag>
-The \tr{-fshow-specialisations}\index{-fshow-specialisations option}
+The @-fshow-specialisations@<nidx>-fshow-specialisations option</nidx>
will show the specialisations that actually take place.
-The \tr{-fshow-import-specs}\index{-fshow-import-specs option} will
-show the specialisations that GHC {\em wished} were available, but
+The @-fshow-import-specs@<nidx>-fshow-import-specs option</nidx> will
+show the specialisations that GHC <em>wished</em> were available, but
were not. You can add the relevant pragmas to your code if you wish.
You're a bit stuck if the desired specialisation is of a Prelude
Prelude code, rename it, and then SPECIALIZE that to your heart's
content.
-\item[``But how do I know where overloading is creeping in?'':]
+<tag>``But how do I know where overloading is creeping in?'':</tag>
A low-tech way: grep (search) your interface files for overloaded
type signatures; e.g.,:
-\begin{verbatim}
+<tscreen><verb>
% egrep '^[a-z].*::.*=>' *.hi
-\end{verbatim}
-\end{description}
+</verb></tscreen>
+</descrip>
%----------------------------------------------------------------
-\item[Strict functions are your dear friends:]
+<tag>Strict functions are your dear friends:</tag>
and, among other things, lazy pattern-matching is your enemy.
(If you don't know what a ``strict function'' is, please consult a
explanation here probably would not do much good.)
Consider these two code fragments:
-\begin{verbatim}
+<tscreen><verb>
f (Wibble x y) = ... # strict
f arg = let { (Wibble x y) = arg } in ... # lazy
-\end{verbatim}
+</verb></tscreen>
The former will result in far better code.
-A less contrived example shows the use of \tr{cases} instead
-of \tr{lets} to get stricter code (a good thing):
-\begin{verbatim}
+A less contrived example shows the use of @cases@ instead
+of @lets@ to get stricter code (a good thing):
+<tscreen><verb>
f (Wibble x y) # beautiful but slow
= let
(a1, b1, c1) = unpackFoo x
case (unpackFoo y) of { (a2, b2, c2) ->
...
}}
-\end{verbatim}
+</verb></tscreen>
%----------------------------------------------------------------
-\item[GHC loves single-constructor data-types:]
+<tag>GHC loves single-constructor data-types:</tag>
It's all the better if a function is strict in a single-constructor
type (a type with only one data-constructor; for example, tuples are
single-constructor types).
%----------------------------------------------------------------
-\item[``How do I find out a function's strictness?'']
+<tag>``How do I find out a function's strictness?''</tag>
Don't guess---look it up.
Look for your function in the interface file, then for the third field
-in the pragma; it should say \tr{_S_ <string>}. The \tr{<string>}
-gives the strictness of the function's arguments. \tr{L} is lazy
-(bad), \tr{S} and \tr{E} are strict (good), \tr{P} is ``primitive'' (good),
-\tr{U(...)} is strict and
-``unpackable'' (very good), and \tr{A} is absent (very good).
+in the pragma; it should say @_S_ <string>@. The @<string>@
+gives the strictness of the function's arguments. @L@ is lazy
+(bad), @S@ and @E@ are strict (good), @P@ is ``primitive'' (good),
+@U(...)@ is strict and
+``unpackable'' (very good), and @A@ is absent (very good).
-For an ``unpackable'' \tr{U(...)} argument, the info inside
+For an ``unpackable'' @U(...)@ argument, the info inside
tells the strictness of its components. So, if the argument is a
-pair, and it says \tr{U(AU(LSS))}, that means ``the first component of the
+pair, and it says @U(AU(LSS))@, 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).''
-If the function isn't exported, just compile with the extra flag \tr{-ddump-simpl};
+If the function isn't exported, just compile with the extra flag @-ddump-simpl@;
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!)
%----------------------------------------------------------------
-\item[Force key functions to be \tr{INLINE}d (esp. monads):]
+<tag>Force key functions to be @INLINE@d (esp. monads):</tag>
-GHC (with \tr{-O}, as always) tries to inline (or ``unfold'')
+GHC (with @-O@, 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.
use.
The sledgehammer you can bring to bear is the
-\tr{INLINE}\index{INLINE pragma} pragma, used thusly:
-\begin{verbatim}
+@INLINE@<nidx>INLINE pragma</nidx> pragma, used thusly:
+<tscreen><verb>
key_function :: Int -> String -> (Bool, Double)
#ifdef __GLASGOW_HASKELL__
{-# INLINE key_function #-}
#endif
-\end{verbatim}
+</verb></tscreen>
(You don't need to do the C pre-processor carry-on unless you're going
-to stick the code through HBC---it doesn't like \tr{INLINE} pragmas.)
+to stick the code through HBC---it doesn't like @INLINE@ pragmas.)
-The major effect of an \tr{INLINE} pragma is to declare a function's
+The major effect of an @INLINE@ pragma is to declare a function's
``cost'' to be very low. The normal unfolding machinery will then be
very keen to inline it.
-An \tr{INLINE} pragma for a function can be put anywhere its type
+An @INLINE@ pragma for a function can be put anywhere its type
signature could be put.
-\tr{INLINE} pragmas are a particularly good idea for the
-\tr{then}/\tr{return} (or \tr{bind}/\tr{unit}) functions in a monad.
+@INLINE@ pragmas are a particularly good idea for the
+@then@/@return@ (or @bind@/@unit@) functions in a monad.
For example, in GHC's own @UniqueSupply@ monad code, we have:
-\begin{verbatim}
+<tscreen><verb>
#ifdef __GLASGOW_HASKELL__
{-# INLINE thenUs #-}
{-# INLINE returnUs #-}
#endif
-\end{verbatim}
+</verb></tscreen>
-GHC reserves the right to {\em disallow} any unfolding, even if you
+GHC reserves the right to <em>disallow</em> any unfolding, even if you
explicitly asked for one. That's because a function's body may
-become {\em unexportable}, because it mentions a non-exported value,
+become <em>unexportable</em>, because it mentions a non-exported value,
to which any importing module would have no access.
If you want to see why candidate unfoldings are rejected, use the
-\tr{-freport-disallowed-unfoldings}
-\index{-freport-disallowed-unfoldings}
+@-freport-disallowed-unfoldings@
+<nidx>-freport-disallowed-unfoldings</nidx>
option.
%----------------------------------------------------------------
-\item[Explicit \tr{export} list:]
+<tag>Explicit @export@ list:</tag>
If you do not have an explicit export list in a module, GHC must
assume that everything in that module will be exported. This has
various pessimising effect. For example, if a bit of code is actually
-{\em unused} (perhaps because of unfolding effects), GHC will not be
+<em>unused</em> (perhaps because of unfolding effects), GHC will not be
able to throw it away, because it is exported and some other module
may be relying on its existence.
they are not exported.
%----------------------------------------------------------------
-\item[Look at the Core syntax!]
+<tag>Look at the Core syntax!</tag>
(The form in which GHC manipulates your code.) Just run your
-compilation with \tr{-ddump-simpl} (don't forget the \tr{-O}).
+compilation with @-ddump-simpl@ (don't forget the @-O@).
If profiling has pointed the finger at particular functions, look at
-their Core code. \tr{lets} are bad, \tr{cases} are good, dictionaries
-(\tr{d.<Class>.<Unique>}) [or anything overloading-ish] are bad,
+their Core code. @lets@ are bad, @cases@ are good, dictionaries
+(@d.<Class>.<Unique>@) [or anything overloading-ish] are bad,
nested lambdas are bad, explicit data constructors are good, primitive
-operations (e.g., \tr{eqInt#}) are good, ...
+operations (e.g., @eqInt#@) are good, ...
%----------------------------------------------------------------
-\item[Use unboxed types (a GHC extension):]
-When you are {\em really} desperate for speed, and you want to
+<tag>Use unboxed types (a GHC extension):</tag>
+When you are <em>really</em> desperate for speed, and you want to
get right down to the ``raw bits.''
-Please see \sectionref{glasgow-unboxed} for some information about
+Please see Section <ref name="Unboxed types" id="glasgow-unboxed"> for some information about
using unboxed types.
%----------------------------------------------------------------
-\item[Use \tr{_ccall_s} (a GHC extension) to plug into fast libraries:]
+<tag>Use @_ccall_s@ (a GHC extension) to plug into fast libraries:</tag>
This may take real work, but... There exist piles of
massively-tuned library code, and the best thing is not
to compete with it, but link with it.
-\Sectionref{glasgow-ccalls} says a little about how to use C calls.
+Section <ref name="Calling~C directly from Haskell" id="glasgow-ccalls"> says a little about how to use C calls.
%----------------------------------------------------------------
-\item[Don't use \tr{Float}s:]
-We don't provide specialisations of Prelude functions for \tr{Float}
-(but we do for \tr{Double}). If you end up executing overloaded
+<tag>Don't use @Float@s:</tag>
+We don't provide specialisations of Prelude functions for @Float@
+(but we do for @Double@). If you end up executing overloaded
code, you will lose on performance, perhaps badly.
-\tr{Floats} (probably 32-bits) are almost always a bad idea, anyway,
+@Floats@ (probably 32-bits) are almost always a bad idea, anyway,
unless you Really Know What You Are Doing. Use Doubles. There's
rarely a speed disadvantage---modern machines will use the same
-floating-point unit for both. With \tr{Doubles}, you are much less
+floating-point unit for both. With @Doubles@, you are much less
likely to hang yourself with numerical errors.
%----------------------------------------------------------------
-\item[Use a bigger heap!]
-If your program's GC stats (\tr{-S}\index{-S RTS option} RTS option)
+<tag>Use a bigger heap!</tag>
+If your program's GC stats (@-S@<nidx>-S RTS option</nidx> RTS option)
indicate that it's doing lots of garbage-collection (say, more than
20\% of execution time), more memory might help---with the
-\tr{-H<size>}\index{-H<size> RTS option} RTS option.
+@-H<size>@<nidx>-H<size> RTS option</nidx> RTS option.
%----------------------------------------------------------------
-\item[Use a smaller heap!]
+<tag>Use a smaller heap!</tag>
Some programs with a very small heap residency (toy programs, usually)
actually benefit from running the heap size way down. The
-\tr{-H<size>} RTS option, as above.
+@-H<size>@ RTS option, as above.
%----------------------------------------------------------------
-\item[Use a smaller ``allocation area'':]
+<tag>Use a smaller ``allocation area'':</tag>
If you can get the garbage-collector's youngest generation to fit
entirely in your machine's cache, it may make quite a difference.
-The effect is {\em very machine dependent}. But, for example,
-a \tr{+RTS -A128k}\index{-A<size> RTS option} option on one of our
+The effect is <em>very machine dependent</em>. But, for example,
+a @+RTS -A128k@<nidx>-A<size> RTS option</nidx> option on one of our
DEC Alphas was worth an immediate 5\% performance boost.
-\end{description}
+</descrip>
%************************************************************************
%* *
-\subsection[smaller]{Smaller: producing a program that is smaller}
-\index{smaller programs, how to produce}
+<sect1>Smaller: producing a program that is smaller
+<label id="smaller">
+<p>
+<nidx>smaller programs, how to produce</nidx>
%* *
%************************************************************************
Decrease the ``go-for-it'' threshold for unfolding smallish expressions.
-Give a \tr{-funfolding-use-threshold0}\index{-funfolding-use-threshold0 option}
+Give a @-funfolding-use-threshold0@<nidx>-funfolding-use-threshold0 option</nidx>
option for the extreme case. (``Only unfoldings with zero cost should proceed.'')
(Note: I have not been too successful at producing code smaller
-than that which comes out with \tr{-O}. WDP 94/12)
+than that which comes out with @-O@. WDP 94/12)
-Avoid \tr{Read}.
+Avoid @Read@.
-Use \tr{strip} on your executables.
+Use @strip@ on your executables.
%************************************************************************
%* *
-\subsection[stingier]{Stingier: producing a program that gobbles less heap space}
-\index{memory, using less heap}
-\index{space-leaks, avoiding}
-\index{heap space, using less}
+<sect1>Stingier: producing a program that gobbles less heap space
+<label id="stingier">
+<p>
+<nidx>memory, using less heap</nidx>
+<nidx>space-leaks, avoiding</nidx>
+<nidx>heap space, using less</nidx>
%* *
%************************************************************************
``I think I have a space leak...'' Re-run your program with
-\tr{+RTS -Sstderr},\index{-Sstderr RTS option} and remove all doubt!
+@+RTS -Sstderr@,<nidx>-Sstderr RTS option</nidx> and remove all doubt!
(You'll see the heap usage get bigger and bigger...) [Hmmm... this
-might be even easier with the \tr{-F2s}\index{-F2s RTS option} RTS
-option; so... \tr{./a.out +RTS -Sstderr -F2s}...]
+might be even easier with the @-F2s@<nidx>-F2s RTS option</nidx> RTS
+option; so... @./a.out +RTS -Sstderr -F2s@...]
-Once again, the profiling facilities (\sectionref{profiling}) are the
+Once again, the profiling facilities (Section <ref name="Profiling" id="profiling">) are the
basic tool for demystifying the space behaviour of your program.
Strict functions are good to space usage, as they are for time, as
If you have a true blue ``space leak'' (your program keeps gobbling up
memory and never ``lets go''), then 7 times out of 10 the problem is
-related to a {\em CAF} (constant applicative form). Real people call
+related to a <em>CAF</em> (constant applicative form). Real people call
them ``top-level values that aren't functions.'' Thus, for example:
-\begin{verbatim}
+<tscreen><verb>
x = (1 :: Int)
f y = x
ones = [ 1, (1 :: Float), .. ]
-\end{verbatim}
-\tr{x} and \tr{ones} are CAFs; \tr{f} is not.
+</verb></tscreen>
+@x@ and @ones@ are CAFs; @f@ is not.
The GHC garbage collectors are not clever about CAFs. The part of the
heap reachable from a CAF is never collected. In the case of
-\tr{ones} in the example above, it's {\em disastrous}. For this
+@ones@ in the example above, it's <em>disastrous</em>. For this
reason, the GHC ``simplifier'' tries hard to avoid creating CAFs, but
it cannot subvert the will of a determined CAF-writing programmer (as
in the case above).
+++ /dev/null
-%************************************************************************
-%* *
-\section[syslibs]{System libraries}
-\index{system libraries}
-\index{libraries, system}
-%* *
-
-This section gives an overview of the interfaces provided
-by the different {\em syslibs} that comes bundled with GHC.
-
-At the moment, there four different collections of system libraries:
-
-\begin{itemize}
-\item The GHC system library - collection of interfaces that mainly
-have grown out of abstractions used to implement GHC itself.
-\item Parts of the HBC libraries.
-\item The Posix interface - a mostly complete interface to OS functionality as
-specified by {\tt POSIX 1003.1}. Sadly, this library isn't a standard
-Haskell library...yet.
-\item The contrib libraries - oodles of numeric codes..
-\end{itemize}
-
-If you provide a \tr{-syslib <name>}\index{-syslib <name> option}
-option on the command line, then the interfaces for that library will
-come into scope (and may be \tr{import}ed), and the code will be added
-in at link time.
-
-
-%************************************************************************
-%* *
-\subsection[GHC-library]{The GHC system library}
-\index{library, GHC}
-\index{GHC library}
-%* *
-%************************************************************************
-
-We have started to put together a ``GHC system library.''
-
-At the moment, the library is made of generally-useful bits of the
-compiler itself.
-
-To use this library, just give a \tr{-syslib ghc}\index{-syslib ghc option}
-option to GHC, both for compiling and linking.
-
-%************************************************************************
-%* *
-\subsubsection[Bag]{The @Bag@ type}
-\index{Bag module (GHC syslib)}
-%* *
-%************************************************************************
-
-A {\em bag} is an unordered collection of elements which may contain
-duplicates. To use, \tr{import Bag}.
-
-\begin{verbatim}
-data Bag elt -- abstract
-
-emptyBag :: Bag elt
-unitBag :: elt -> Bag elt
-
-consBag :: elt -> Bag elt -> Bag elt
-snocBag :: Bag elt -> elt -> Bag elt
-
-unionBags :: Bag elt -> Bag elt -> Bag elt
-unionManyBags :: [Bag elt] -> Bag elt
-
-isEmptyBag :: Bag elt -> Bool
-elemBag :: Eq elt => elt -> Bag elt -> Bool
-
-filterBag :: (elt -> Bool) -> Bag elt -> Bag elt
-partitionBag :: (elt -> Bool) -> Bag elt-> (Bag elt, Bag elt)
- -- returns the elements that do/don't satisfy the predicate
-
-concatBag :: Bag (Bag a) -> Bag a
-foldBag :: (r -> r -> r) -> (a -> r) -> r -> Bag a -> r
-mapBag :: (a -> b) -> Bag a -> Bag b
-
-listToBag :: [elt] -> Bag elt
-bagToList :: Bag elt -> [elt]
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsubsection[FiniteMap]{The @FiniteMap@ type}
-\index{FiniteMap module (GHC syslib)}
-%* *
-%************************************************************************
-
-What functional programmers call a {\em finite map}, everyone else
-calls a {\em lookup table}.
-
-Out code is derived from that in this paper:
-\begin{display}
-S Adams
-"Efficient sets: a balancing act"
-Journal of functional programming 3(4) Oct 1993, pages 553-562
-\end{display}
-Guess what? The implementation uses balanced trees.
-
-\begin{verbatim}
-data FiniteMap key elt -- abstract
-
--- BUILDING
-emptyFM :: FiniteMap key elt
-unitFM :: key -> elt -> FiniteMap key elt
-listToFM :: Ord key => [(key,elt)] -> FiniteMap key elt
- -- In the case of duplicates, the last is taken
-
--- ADDING AND DELETING
- -- Throws away any previous binding
- -- In the list case, the items are added starting with the
- -- first one in the list
-addToFM :: Ord key => FiniteMap key elt -> key -> elt -> FiniteMap key elt
-addListToFM :: Ord key => FiniteMap key elt -> [(key,elt)] -> FiniteMap key elt
-
- -- Combines with previous binding
- -- In the combining function, the first argument is
- -- the "old" element, while the second is the "new" one.
-addToFM_C :: Ord key => (elt -> elt -> elt)
- -> FiniteMap key elt -> key -> elt
- -> FiniteMap key elt
-addListToFM_C :: Ord key => (elt -> elt -> elt)
- -> FiniteMap key elt -> [(key,elt)]
- -> FiniteMap key elt
-
- -- Deletion doesn't complain if you try to delete something
- -- which isn't there
-delFromFM :: Ord key => FiniteMap key elt -> key -> FiniteMap key elt
-delListFromFM :: Ord key => FiniteMap key elt -> [key] -> FiniteMap key elt
-
--- COMBINING
- -- Bindings in right argument shadow those in the left
-plusFM :: Ord key => FiniteMap key elt -> FiniteMap key elt
- -> FiniteMap key elt
-
- -- Combines bindings for the same thing with the given function
-plusFM_C :: Ord key => (elt -> elt -> elt)
- -> FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
-
-minusFM :: Ord key => FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
- -- (minusFM a1 a2) deletes from a1 any bindings which are bound in a2
-
-intersectFM :: Ord key => FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
-intersectFM_C :: Ord key => (elt -> elt -> elt)
- -> FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
-
--- MAPPING, FOLDING, FILTERING
-foldFM :: (key -> elt -> a -> a) -> a -> FiniteMap key elt -> a
-mapFM :: (key -> elt1 -> elt2) -> FiniteMap key elt1 -> FiniteMap key elt2
-filterFM :: Ord key => (key -> elt -> Bool)
- -> FiniteMap key elt -> FiniteMap key elt
-
--- INTERROGATING
-sizeFM :: FiniteMap key elt -> Int
-isEmptyFM :: FiniteMap key elt -> Bool
-
-elemFM :: Ord key => key -> FiniteMap key elt -> Bool
-lookupFM :: Ord key => FiniteMap key elt -> key -> Maybe elt
-lookupWithDefaultFM
- :: Ord key => FiniteMap key elt -> elt -> key -> elt
- -- lookupWithDefaultFM supplies a "default" elt
- -- to return for an unmapped key
-
--- LISTIFYING
-fmToList :: FiniteMap key elt -> [(key,elt)]
-keysFM :: FiniteMap key elt -> [key]
-eltsFM :: FiniteMap key elt -> [elt]
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsubsection[ListSetOps]{The @ListSetOps@ type}
-\index{ListSetOps module (GHC syslib)}
-%* *
-%************************************************************************
-
-Just a few set-sounding operations on lists. If you want sets, use
-the \tr{Set} module.
-
-\begin{verbatim}
-unionLists :: Eq a => [a] -> [a] -> [a]
-intersectLists :: Eq a => [a] -> [a] -> [a]
-minusList :: Eq a => [a] -> [a] -> [a]
-disjointLists :: Eq a => [a] -> [a] -> Bool
-intersectingLists :: Eq a => [a] -> [a] -> Bool
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsubsection[Maybes]{The @Maybes@ type}
-\index{Maybes module (GHC syslib)}
-%* *
-%************************************************************************
-
-The \tr{Maybe} type is in the Haskell 1.4 prelude. Moreover, the
-required \tr{Maybe} library provides many useful functions on
-\tr{Maybe}s. This (pre-1.3) module provides some more:
-
-An \tr{Either}-like type called \tr{MaybeErr}:
-\begin{verbatim}
-data MaybeErr val err = Succeeded val | Failed err
-\end{verbatim}
-
-Some operations to do with \tr{Maybe} (some commentary follows):
-\begin{verbatim}
-maybeToBool :: Maybe a -> Bool -- Nothing => False; Just => True
-allMaybes :: [Maybe a] -> Maybe [a]
-firstJust :: [Maybe a] -> Maybe a
-findJust :: (a -> Maybe b) -> [a] -> Maybe b
-
-assocMaybe :: Eq a => [(a,b)] -> a -> Maybe b
-mkLookupFun :: (key -> key -> Bool) -- Equality predicate
- -> [(key,val)] -- The assoc list
- -> (key -> Maybe val) -- A lookup fun to use
-mkLookupFunDef :: (key -> key -> Bool) -- Equality predicate
- -> [(key,val)] -- The assoc list
- -> val -- Value to return on failure
- -> key -- The key
- -> val -- The corresponding value
-
- -- a monad thing
-thenMaybe :: Maybe a -> (a -> Maybe b) -> Maybe b
-returnMaybe :: a -> Maybe a
-failMaybe :: Maybe a
-mapMaybe :: (a -> Maybe b) -> [a] -> Maybe [b]
-\end{verbatim}
-
-NB: @catMaybes@ which used to be here, is now available via the
-standard @Maybe@ interface (@Maybe@ is an instance of @MonadPlus@).
-
-@allMaybes@ collects a list of @Justs@ into a single @Just@, returning
-@Nothing@ if there are any @Nothings@.
-
-@firstJust@ takes a list of @Maybes@ and returns the
-first @Just@ if there is one, or @Nothing@ otherwise.
-
-@assocMaybe@ looks up in an association list, returning
-@Nothing@ if it fails.
-
-Now, some operations to do with \tr{MaybeErr} (comments follow):
-\begin{verbatim}
- -- a monad thing (surprise, surprise)
-thenMaB :: MaybeErr a err -> (a -> MaybeErr b err) -> MaybeErr b err
-returnMaB :: val -> MaybeErr val err
-failMaB :: err -> MaybeErr val err
-
-listMaybeErrs :: [MaybeErr val err] -> MaybeErr [val] [err]
-foldlMaybeErrs :: (acc -> input -> MaybeErr acc err)
- -> acc
- -> [input]
- -> MaybeErr acc [err]
-\end{verbatim}
-
-@listMaybeErrs@ takes a list of @MaybeErrs@ and, if they all succeed,
-returns a @Succeeded@ of a list of their values. If any fail, it
-returns a @Failed@ of the list of all the errors in the list.
-
-@foldlMaybeErrs@ 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.
-
-%************************************************************************
-%* *
-\subsubsection[PackedString]{The @PackedString@ type}
-\index{PackedString module (GHC syslib)}
-%* *
-%************************************************************************
-
-You need to \tr{import PackedString} and heave in your
-\tr{-syslib ghc} to use \tr{PackedString}s.
-
-The basic type and functions available are:
-\begin{verbatim}
-data PackedString -- abstract
-
-packString :: [Char] -> PackedString
-packStringST :: [Char] -> ST s PackedString
-packCBytesST :: Int -> Addr -> ST s PackedString
-packBytesForCST :: [Char] -> ST s (ByteArray Int)
-byteArrayToPS :: ByteArray Int -> PackedString
-unsafeByteArrayToPS :: ByteArray a -> Int -> PackedString
-psToByteArray :: PackedString -> ByteArray Int
-psToByteArrayST :: PackedString -> ST s (ByteArray Int)
-
-unpackPS :: PackedString -> [Char]
-\end{verbatim}
-
-We also provide a wad of list-manipulation-like functions:
-\begin{verbatim}
-nilPS :: PackedString
-consPS :: Char -> PackedString -> PackedString
-
-headPS :: PackedString -> Char
-tailPS :: PackedString -> PackedString
-nullPS :: PackedString -> Bool
-appendPS :: PackedString -> PackedString -> PackedString
-lengthPS :: PackedString -> Int
-indexPS :: PackedString -> Int -> Char
- -- 0-origin indexing into the string
-mapPS :: (Char -> Char) -> PackedString -> PackedString
-filterPS :: (Char -> Bool) -> PackedString -> PackedString
-foldlPS :: (a -> Char -> a) -> a -> PackedString -> a
-foldrPS :: (Char -> a -> a) -> a -> PackedString -> a
-takePS :: Int -> PackedString -> PackedString
-dropPS :: Int -> PackedString -> PackedString
-splitAtPS :: Int -> PackedString -> (PackedString, PackedString)
-takeWhilePS :: (Char -> Bool) -> PackedString -> PackedString
-dropWhilePS :: (Char -> Bool) -> PackedString -> PackedString
-spanPS :: (Char -> Bool) -> PackedString -> (PackedString, PackedString)
-breakPS :: (Char -> Bool) -> PackedString -> (PackedString, PackedString)
-linesPS :: PackedString -> [PackedString]
-wordsPS :: PackedString -> [PackedString]
-reversePS :: PackedString -> PackedString
-concatPS :: [PackedString] -> PackedString
-elemPS :: Char -> PackedString -> Bool
- -- Perl-style split&join
-splitPS :: Char -> PackedString -> [PackedString]
-splitWithPS :: (Char -> Bool) -> PackedString -> [PackedString]
-joinPS :: PackedString -> [PackedString] -> PackedString
-
-substrPS :: PackedString -> Int -> Int -> PackedString
- -- pluck out a piece of a PackedString
- -- start and end chars you want; both 0-origin-specified
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsubsection[Pretty]{The @Pretty@ type}
-\index{Pretty module (GHC syslib)}
-%* *
-%************************************************************************
-
-This is the pretty-printer that is currently used in GHC:
-
-\begin{verbatim}
-type Pretty
-
-ppShow :: Int{-width-} -> Pretty -> [Char]
-
-pp'SP :: Pretty -- "comma space"
-ppComma :: Pretty -- ,
-ppEquals :: Pretty -- =
-ppLbrack :: Pretty -- [
-ppLparen :: Pretty -- (
-ppNil :: Pretty -- nothing
-ppRparen :: Pretty -- )
-ppRbrack :: Pretty -- ]
-ppSP :: Pretty -- space
-ppSemi :: Pretty -- ;
-
-ppChar :: Char -> Pretty
-ppDouble :: Double -> Pretty
-ppFloat :: Float -> Pretty
-ppInt :: Int -> Pretty
-ppInteger :: Integer -> Pretty
-ppRational :: Rational -> Pretty
-ppStr :: [Char] -> Pretty
-
-ppAbove :: Pretty -> Pretty -> Pretty
-ppAboves :: [Pretty] -> Pretty
-ppBeside :: Pretty -> Pretty -> Pretty
-ppBesides :: [Pretty] -> Pretty
-ppCat :: [Pretty] -> Pretty
-ppHang :: Pretty -> Int -> Pretty -> Pretty
-ppInterleave :: Pretty -> [Pretty] -> Pretty -- spacing between
-ppIntersperse :: Pretty -> [Pretty] -> Pretty -- no spacing between
-ppNest :: Int -> Pretty -> Pretty
-ppSep :: [Pretty] -> Pretty
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsubsection[Set]{The @Set@ type}
-\index{Set module (GHC syslib)}
-%* *
-%************************************************************************
-
-Our implementation of {\em sets} (key property: no duplicates) is just
-a variant of the \tr{FiniteMap} module.
-
-\begin{verbatim}
-data Set -- abstract
- -- instance of: Eq
-
-emptySet :: Set a
-mkSet :: Ord a => [a] -> Set a
-setToList :: Set a -> [a]
-unitSet :: a -> Set a
-singletonSet :: a -> Set a -- deprecated, use unitSet.
-
-union :: Ord a => Set a -> Set a -> Set a
-unionManySets :: Ord a => [Set a] -> Set a
-minusSet :: Ord a => Set a -> Set a -> Set a
-mapSet :: Ord a => (b -> a) -> Set b -> Set a
-intersect :: Ord a => Set a -> Set a -> Set a
-
-elementOf :: Ord a => a -> Set a -> Bool
-isEmptySet :: Set a -> Bool
-
-cardinality :: Set a -> Int
-
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsubsection[BitSet]{The @BitSet@ interface}
-\index{Bitset interface (GHC syslib)}
-%* *
-%************************************************************************
-
-Bit sets are a fast implementation of sets of integers ranging from 0
-to one less than the number of bits in a machine word (typically 31).
-If any element exceeds the maximum value for a particular machine
-architecture, the results of these operations are undefined. You have
-been warned.
-
-\begin{verbatim}
-data BitSet -- abstract
- -- instance of:
-
-emptyBS :: BitSet
-mkBS :: [Int] -> BitSet
-unitBS :: Int -> BitSet
-unionBS :: BitSet -> BitSet -> BitSet
-minusBS :: BitSet -> BitSet -> BitSet
-isEmptyBS :: BitSet -> Bool
-intersectBS :: BitSet -> BitSet -> BitSet
-elementBS :: Int -> BitSet -> Bool
-listBS :: BitSet -> [Int]
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsubsection[Util]{The @Util@ type}
-\index{Util module (GHC syslib)}
-%* *
-%************************************************************************
-
-Stuff that has been generally useful to use in writing the compiler.
-Don't be too surprised if this stuff moves/gets-renamed/etc.
-
-\begin{verbatim}
--- general list processing
-forall :: (a -> Bool) -> [a] -> Bool
-exists :: (a -> Bool) -> [a] -> Bool
-
-nOfThem :: Int -> a -> [a]
-lengthExceeds :: [a] -> Int -> Bool
-isSingleton :: [a] -> Bool
-
---paranoid zip'ing (equal length lists)
-zipEqual :: [a] -> [b] -> [(a,b)]
-zipWithEqual :: String -> (a->b->c) -> [a]->[b]->[c]
-zipWith3Equal :: String -> (a->b->c->d) -> [a]->[b]->[c]->[d]
-zipWith4Equal :: String -> (a->b->c->d->e) -> [a]->[b]->[c]->[d]->[e]
--- lazy in second argument
-zipLazy :: [a] -> [b] -> [(a,b)]
-
-mapAndUnzip :: (a -> (b, c)) -> [a] -> ([b], [c])
-mapAndUnzip3 :: (a -> (b, c, d)) -> [a] -> ([b], [c], [d])
-
--- prefix and suffix matching on lists of characters.
-startsWith :: {-prefix-}String -> String -> Maybe String
-endsWith :: {-suffix-}String -> String -> Maybe String
-
--- association lists
-assoc :: Eq a => String -> [(a, b)] -> a -> b
-
--- duplicate handling
-hasNoDups :: Eq a => [a] -> Bool
-equivClasses :: (a -> a -> Ordering) -> [a] -> [[a]]
-runs :: (a -> a -> Bool) -> [a] -> [[a]]
-removeDups :: (a -> a -> Ordering) -> [a] -> ([a], [[a]])
-
--- sorting (don't complain of no choice...)
-quicksort :: (a -> a -> Bool) -> [a] -> [a]
-sortLt :: (a -> a -> Bool) -> [a] -> [a]
-stableSortLt :: (a -> a -> Bool) -> [a] -> [a]
-mergesort :: (a -> a -> _CMP_TAG) -> [a] -> [a]
-mergeSort :: Ord a => [a] -> [a]
-naturalMergeSort :: Ord a => [a] -> [a]
-mergeSortLe :: Ord a => [a] -> [a]
-naturalMergeSortLe :: Ord a => [a] -> [a]
-
--- transitive closures
-transitiveClosure :: (a -> [a]) -- Successor function
- -> (a -> a -> Bool) -- Equality predicate
- -> [a]
- -> [a] -- The transitive closure
-
--- accumulating (Left, Right, Bi-directional)
-mapAccumL :: (acc -> x -> (acc, y))
- -- Function of elt of input list and
- -- accumulator, returning new accumulator and
- -- elt of result list
- -> acc -- Initial accumulator
- -> [x] -- Input list
- -> (acc, [y]) -- Final accumulator and result list
-
-mapAccumR :: (acc -> x -> (acc, y)) -> acc -> [x] -> (acc, [y])
-
-mapAccumB :: (accl -> accr -> x -> (accl, accr,y))
- -> accl -> accr -> [x]
- -> (accl, accr, [y])
-
---list comparison with explicit element comparer.
-cmpList :: (a -> a -> Ordering) -> [a] -> [a] -> Ordering
-
--- pairs
-applyToPair :: ((a -> c), (b -> d)) -> (a, b) -> (c, d)
-applyToFst :: (a -> c) -> (a, b) -> (c, b)
-applyToSnd :: (b -> d) -> (a, b) -> (a, d)
-foldPair :: (a->a->a, b->b->b) -> (a, b) -> [(a, b)] -> (a, b)
-unzipWith :: (a -> b -> c) -> [(a, b)] -> [c]
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsection[C-interfaces]{Interfaces to C libraries}
-\index{C library interfaces}
-\index{interfaces, C library}
-%* *
-%************************************************************************
-
-The GHC system library (\tr{-syslib ghc}) also provides interfaces to
-several useful C libraries, mostly from the GNU project.
-
-%************************************************************************
-%* *
-\subsubsection[Readline]{The @Readline@ interface}
-\index{Readline library (GHC syslib)}
-\index{command-line editing library}
-%* *
-%************************************************************************
-
-(Darren Moffat supplied the \tr{Readline} interface.)
-
-The \tr{Readline} module is a straightforward interface to the GNU
-Readline library. As such, you will need to look at the GNU
-documentation (and have a \tr{libreadline.a} file around somewhere...)
-
-You'll need to link any Readlining program with \tr{-lreadline -ltermcap},
-besides the usual \tr{-syslib ghc} (and \tr{-fhaskell-1.3}).
-
-The main function you'll use is:
-\begin{verbatim}
-readline :: String{-the prompt-} -> IO String
-\end{verbatim}
-
-If you want to mess around with Full Readline G(l)ory, we also
-provide:
-\begin{verbatim}
-rlInitialize, addHistory,
-
-rlBindKey, rlAddDefun, RlCallbackFunction(..),
-
-rlGetLineBuffer, rlSetLineBuffer, rlGetPoint, rlSetPoint, rlGetEnd,
-rlSetEnd, rlGetMark, rlSetMark, rlSetDone, rlPendingInput,
-
-rlPrompt, rlTerminalName, rlSetReadlineName, rlGetReadlineName
-\end{verbatim}
-(All those names are just Haskellised versions of what you
-will see in the GNU readline documentation.)
-
-%************************************************************************
-%* *
-\subsubsection[Regexp]{The @Regexp@ and @MatchPS@ interfaces}
-\index{Regex library (GHC syslib)}
-\index{MatchPS library (GHC syslib)}
-\index{regular-expressions library}
-%* *
-%************************************************************************
-
-(Sigbjorn Finne supplied the regular-expressions interface.)
-
-The \tr{Regex} library provides quite direct interface to the GNU
-regular-expression library, for doing manipulation on
-\tr{PackedString}s. You probably need to see the GNU documentation
-if you are operating at this level.
-
-The datatypes and functions that \tr{Regex} provides are:
-\begin{verbatim}
-data PatBuffer # just a bunch of bytes (mutable)
-
-data REmatch
- = REmatch (Array Int GroupBounds) -- for $1, ... $n
- GroupBounds -- for $` (everything before match)
- GroupBounds -- for $& (entire matched string)
- GroupBounds -- for $' (everything after)
- GroupBounds -- for $+ (matched by last bracket)
-
--- GroupBounds hold the interval where a group
--- matched inside a string, e.g.
---
--- matching "reg(exp)" "a regexp" returns the pair (5,7) for the
--- (exp) group. (PackedString indices start from 0)
-
-type GroupBounds = (Int, Int)
-
-re_compile_pattern
- :: PackedString -- pattern to compile
- -> Bool -- True <=> assume single-line mode
- -> Bool -- True <=> case-insensitive
- -> PrimIO PatBuffer
-
-re_match :: PatBuffer -- compiled regexp
- -> PackedString -- string to match
- -> Int -- start position
- -> Bool -- True <=> record results in registers
- -> PrimIO (Maybe REmatch)
-
--- Matching on 2 strings is useful when you're dealing with multiple
--- buffers, which is something that could prove useful for
--- PackedStrings, as we don't want to stuff the contents of a file
--- into one massive heap chunk, but load (smaller chunks) on demand.
-
-re_match2 :: PatBuffer -- 2-string version
- -> PackedString
- -> PackedString
- -> Int
- -> Int
- -> Bool
- -> PrimIO (Maybe REmatch)
-
-re_search :: PatBuffer -- compiled regexp
- -> PackedString -- string to search
- -> Int -- start index
- -> Int -- stop index
- -> Bool -- True <=> record results in registers
- -> PrimIO (Maybe REmatch)
-
-re_search2 :: PatBuffer -- Double buffer search
- -> PackedString
- -> PackedString
- -> Int -- start index
- -> Int -- range (?)
- -> Int -- stop index
- -> Bool -- True <=> results in registers
- -> PrimIO (Maybe REmatch)
-\end{verbatim}
-
-The \tr{MatchPS} module provides Perl-like ``higher-level'' facilities
-to operate on \tr{PackedStrings}. The regular expressions in
-question are in Perl syntax. The ``flags'' on various functions can
-include: \tr{i} for case-insensitive, \tr{s} for single-line mode, and
-\tr{g} for global. (It's probably worth your time to peruse the
-source code...)
-
-\begin{verbatim}
-matchPS :: PackedString -- regexp
- -> PackedString -- string to match
- -> [Char] -- flags
- -> Maybe REmatch -- info about what matched and where
-
-searchPS :: PackedString -- regexp
- -> PackedString -- string to match
- -> [Char] -- flags
- -> Maybe REmatch
-
--- Perl-like match-and-substitute:
-substPS :: PackedString -- regexp
- -> PackedString -- replacement
- -> [Char] -- flags
- -> PackedString -- string
- -> PackedString
-
--- same as substPS, but no prefix and suffix:
-replacePS :: PackedString -- regexp
- -> PackedString -- replacement
- -> [Char] -- flags
- -> PackedString -- string
- -> PackedString
-
-match2PS :: PackedString -- regexp
- -> PackedString -- string1 to match
- -> PackedString -- string2 to match
- -> [Char] -- flags
- -> Maybe REmatch
-
-search2PS :: PackedString -- regexp
- -> PackedString -- string to match
- -> PackedString -- string to match
- -> [Char] -- flags
- -> Maybe REmatch
-
--- functions to pull the matched pieces out of an REmatch:
-
-getMatchesNo :: REmatch -> Int
-getMatchedGroup :: REmatch -> Int -> PackedString -> PackedString
-getWholeMatch :: REmatch -> PackedString -> PackedString
-getLastMatch :: REmatch -> PackedString -> PackedString
-getAfterMatch :: REmatch -> PackedString -> PackedString
-
--- (reverse) brute-force string matching;
--- Perl equivalent is index/rindex:
-findPS, rfindPS :: PackedString -> PackedString -> Maybe Int
-
--- Equivalent to Perl "chop" (off the last character, if any):
-chopPS :: PackedString -> PackedString
-
--- matchPrefixPS: tries to match as much as possible of strA starting
--- from the beginning of strB (handy when matching fancy literals in
--- parsers):
-matchPrefixPS :: PackedString -> PackedString -> Int
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsubsection[Socket]{Network-interface toolkit---@Socket@ and @SocketPrim@}
-\index{SocketPrim interface (GHC syslib)}
-\index{Socket interface (GHC syslib)}
-\index{network-interface library}
-\index{sockets library}
-\index{BSD sockets library}
-%* *
-%************************************************************************
-
-(Darren Moffat supplied the network-interface toolkit.)
-
-Your best bet for documentation is to look at the code---really!---
-normally in \tr{hslibs/ghc/src/{BSD,Socket,SocketPrim}.lhs}.
-
-The \tr{BSD} module provides functions to get at system-database info;
-pretty straightforward if you're into this sort of thing:
-\begin{verbatim}
-getHostName :: IO String
-
-getServiceByName :: ServiceName -> IO ServiceEntry
-getServicePortNumber:: ServiceName -> IO PortNumber
-getServiceEntry :: IO ServiceEntry
-setServiceEntry :: Bool -> IO ()
-endServiceEntry :: IO ()
-
-getProtocolByName :: ProtocolName -> IO ProtocolEntry
-getProtocolByNumber :: ProtocolNumber -> IO ProtcolEntry
-getProtocolNumber :: ProtocolName -> ProtocolNumber
-getProtocolEntry :: IO ProtocolEntry
-setProtocolEntry :: Bool -> IO ()
-endProtocolEntry :: IO ()
-
-getHostByName :: HostName -> IO HostEntry
-getHostByAddr :: Family -> HostAddress -> IO HostEntry
-getHostEntry :: IO HostEntry
-setHostEntry :: Bool -> IO ()
-endHostEntry :: IO ()
-\end{verbatim}
-
-The \tr{SocketPrim} interface provides quite direct access to the
-socket facilities in a BSD Unix system, including all the
-complications. We hope you don't need to use it! See the source if
-needed...
-
-The \tr{Socket} interface is a ``higher-level'' interface to sockets,
-and it is what we recommend. Please tell us if the facilities it
-offers are inadequate to your task!
-
-The interface is relatively modest:
-\begin{verbatim}
-connectTo :: Hostname -> PortID -> IO Handle
-listenOn :: PortID -> IO Socket
-
-accept :: Socket -> IO (Handle, HostName)
-sendTo :: Hostname -> PortID -> String -> IO ()
-
-recvFrom :: Hostname -> PortID -> IO String
-socketPort :: Socket -> IO PortID
-
-data PortID -- PortID is a non-abstract type
- = Service String -- Service Name eg "ftp"
- | PortNumber Int -- User defined Port Number
- | UnixSocket String -- Unix family socket in file system
-
-type Hostname = String
-\end{verbatim}
-
-Various examples of networking Haskell code are provided in
-%\tr{ghc/misc/examples/}, notably the \tr{net???/Main.hs} programs.
-
-%************************************************************************
-%* *
-\subsection[Posix-library]{The Posix system library}
-\index{Posix system library}
-\index{system library, Posix}
-%* *
-%************************************************************************
-
-The @Posix@ interface gives you access to the set of OS services
-standardised by POSIX 1003.1b (or the {\em IEEE Portable Operating System
-Interface for Computing Environments} - IEEE Std. 1003.1). The
-interface is accessed by \tr{import Posix} and adding
-\tr{-syslib posix} on your command-line.
-
-\subsubsection[Posix data types]{Posix data types}
-\index{Posix, data types}
-
-
-\begin{verbatim}
-data ByteCount -- instances of : Eq Ord Num Real Integral Ix Enum Show
-\end{verbatim}
-
-A \tr{ByteCount} is a primitive of type \tr{unsigned}. At a minimum,
-an conforming implementation must support values in the range
-\tr{[0, UINT_MAX]}.
-
-\begin{verbatim}
-data ClockTick -- instances of : Eq Ord Num Real Integral Ix Enum Show
-\end{verbatim}
-
-A \tr{ClockTick} is a primitive of type \tr{clock_t}, which
-is used to measure intervals of time in fractions of a second. The
-resolution is determined by \tr{getSysVar ClockTick}.
-
-\begin{verbatim}
-data DeviceID -- instances of : Eq Ord Num Real Integral Ix Enum Show
-\end{verbatim}
-
-A \tr{DeviceID} is a primitive of type \tr{dev_t}. It must
-be an arithmetic type.
-
-\begin{verbatim}
-data EpochTime -- instances of : Eq Ord Num Real Integral Ix Enum Show
-\end{verbatim}
-
-A \tr{EpochTime} is a primitive of type \tr{time_t}, which is
-used to measure seconds since the Epoch. At a minimum, the implementation
-must support values in the range \tr{[0, INT_MAX]}.
-
-\begin{verbatim}
-data FileID -- instances of : Eq Ord Num Real Integral Ix Enum Show
-\end{verbatim}
-
-A \tr{FileID} is a primitive of type \tr{ino_t}. It must
-be an arithmetic type.
-
-\begin{verbatim}
-data FileMode -- instances of : Eq Ord Num Real Integral Ix Enum Show
-\end{verbatim}
-
-A \tr{FileMode} is a primitive of type \tr{mode_t}.
-It must be an arithmetic type.
-
-\begin{verbatim}
-data FileOffset -- instances of : Eq Ord Num Real Integral Ix Enum Show
-\end{verbatim}
-
-A \tr{FileOffset} is a primitive of type \tr{off_t}. It must
-be an arithmetic type.
-
-\begin{verbatim}
-data GroupID -- instances of : Eq Ord Num Real Integral Ix Enum Show
-\end{verbatim}
-
-A \tr{GroupID} is a primitive of type \tr{gid_t}. It must
-be an arithmetic type.
-\begin{verbatim}
-data Limit -- instances of : Eq Ord Num Real Integral Ix Enum Show
-\end{verbatim}
-
-A \tr{Limit} is a primitive of type \tr{long}.
-At a minimum, the implementation must support values in the range
-\tr{[LONG_MIN, LONG_MAX]}.
-
-\begin{verbatim}
-data LinkCount -- instances of : Eq Ord Num Real Integral Ix Enum Show
-\end{verbatim}
-
-A \tr{LinkCount} is a primitive of type \tr{nlink_t}. It must
-be an arithmetic type.
-
-\begin{verbatim}
-data ProcessID -- instances of : Eq Ord Num Real Integral Ix Enum Show
-type ProcessGroupID = ProcessID
-\end{verbatim}
-
-A \tr{ProcessID} is a primitive of type \tr{pid_t}. It
-must be a signed arithmetic type.
-\begin{verbatim}
-data UserID -- instances of : Eq Ord Num Real Integral Ix Enum Show
-\end{verbatim}
-
-A \tr{UserID} is a primitive of type \tr{uid_t}. It
-must be an arithmetic type.
-
-\begin{verbatim}
-data DirStream
-\end{verbatim}
-A \tr{DirStream} is a primitive of type \tr{DIR *}.
-
-\begin{verbatim}
-data FileStatus
-\end{verbatim}
-A \tr{FileStatus} is a primitive of type \tr{struct stat}.
-
-\begin{verbatim}
-data GroupEntry
-\end{verbatim}
-
-A \tr{GroupEntry} is a primitive of type \tr{struct group}.
-\begin{verbatim}
-data ProcessTimes
-\end{verbatim}
-
-\tr{ProcessTimes} is a primitive structure containing a
-\tr{clock_t} and a \tr{struct tms}.
-
-\begin{verbatim}
-data SignalSet
-\end{verbatim}
-
-An \tr{SignalSet} is a primitive of type \tr{sigset_t}.
-
-\begin{verbatim}
-data SystemID
-\end{verbatim}
-
-A \tr{SystemID} is a primitive of type \tr{struct utsname}.
-
-\begin{verbatim}
-data TerminalAttributes
-\end{verbatim}
-\tr{TerminalAttributes} is a primitive of type \tr{struct termios}.
-
-\begin{verbatim}
-data UserEntry
-\end{verbatim}
-
-A \tr{UserEntry} is a primitive of type \tr{struct passwd}.
-
-\begin{verbatim}
-data BaudRate = B0 | B50 | B75 | B110 | B134 | B150 | B200 | B300 | B600
- | B1200 | B1800 | B2400 | B4800 | B9600 | B19200 | B38400
- deriving (Eq, Show)
-
-data Fd
-
-intToFd :: Int -> Fd -- use with care.
-
-data FdOption = AppendOnWrite
- | CloseOnExec
- | NonBlockingRead
-
-data ControlCharacter = EndOfFile
- | EndOfLine
- | Erase
- | Interrupt
- | Kill
- | Quit
- | Suspend
- | Start
- | Stop
-
-type ErrorCode = Int
-
-type FileLock = (LockRequest, SeekMode, FileOffset, FileOffset)
--- whence start length
-
-data FlowAction = SuspendOutput | RestartOutput | TransmitStop | TransmitStart
-
-data Handler = Default | Ignore | Catch (IO ())
-
-data LockRequest = ReadLock | WriteLock | Unlock
- deriving (Eq, Show)
-
-data OpenMode = ReadOnly | WriteOnly | ReadWrite
-
-data PathVar = LinkLimit
- | InputLineLimit
- | InputQueueLimit
- | FileNameLimit
- | PathNameLimit
- | PipeBufferLimit
- | SetOwnerAndGroupIsRestricted
- | FileNamesAreNotTruncated
-
-data QueueSelector = InputQueue | OutputQueue | BothQueues
-
-type Signal = Int
-
-data SysVar = ArgumentLimit
- | ChildLimit
- | ClockTick
- | GroupLimit
- | OpenFileLimit
- | PosixVersion
- | HasSavedIDs
- | HasJobControl
-
-data TerminalMode = InterruptOnBreak -- BRKINT
- | MapCRtoLF -- ICRNL
- | IgnoreBreak -- IGNBRK
- | IgnoreCR -- IGNCR
- | IgnoreParityErrors -- IGNPAR
- | MapLFtoCR -- INLCR
- | CheckParity -- INPCK
- | StripHighBit -- ISTRIP
- | StartStopInput -- IXOFF
- | StartStopOutput -- IXON
- | MarkParityErrors -- PARMRK
- | ProcessOutput -- OPOST
- | LocalMode -- CLOCAL
- | ReadEnable -- CREAD
- | TwoStopBits -- CSTOPB
- | HangupOnClose -- HUPCL
- | EnableParity -- PARENB
- | OddParity -- PARODD
- | EnableEcho -- ECHO
- | EchoErase -- ECHOE
- | EchoKill -- ECHOK
- | EchoLF -- ECHONL
- | ProcessInput -- ICANON
- | ExtendedFunctions -- IEXTEN
- | KeyboardInterrupts -- ISIG
- | NoFlushOnInterrupt -- NOFLSH
- | BackgroundWriteInterrupt -- TOSTOP
-
-data TerminalState = Immediately | WhenDrained | WhenFlushed
-
-data ProcessStatus = Exited ExitCode
- | Terminated Signal
- | Stopped Signal
- deriving (Eq, Show)
-\end{verbatim}
-
-\subsubsection[Process Primitives]{Posix Process Primitives}
-
-\begin{verbatim}
-forkProcess :: IO (Maybe ProcessID)
-\end{verbatim}
-
-\tr{forkProcess} calls \tr{fork}, returning
-\tr{Just pid} to the parent, where \tr{pid} is the
-ProcessID of the child, and returning \tr{Nothing} to the
-child.
-
-\begin{verbatim}
-executeFile :: FilePath -- Command
- -> Bool -- Search PATH?
- -> [String] -- Arguments
- -> Maybe [(String, String)] -- Environment
- -> IO ()
-\end{verbatim}
-
-\tr{executeFile cmd args env} calls one of the
-\tr{execv*} 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 \tr{execv*} as \tr{arg[0]};
-the argument list passed to \tr{executeFile} therefore begins
-with \tr{arg[1]}.
-
-\begin{verbatim}
-Search PATH? Supersede environ? Call
-~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~ ~~~~~~~
-False False execv
-False True execve
-True False execvp
-True True execvpe*
-\end{verbatim}
-
-Note that \tr{execvpe} 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.
-
-A successful \tr{executeFile} overlays the current process image with
-a new one, so it only returns on failure.
-\begin{verbatim}
-runProcess :: FilePath -- Command
- -> [String] -- Arguments
- -> Maybe [(String, String)] -- Environment (Nothing -> Inherited)
- -> Maybe FilePath -- Working directory (Nothing -> inherited)
- -> Maybe Handle -- stdin (Nothing -> inherited)
- -> Maybe Handle -- stdout (Nothing -> inherited)
- -> Maybe Handle -- stderr (Nothing -> inherited)
- -> IO ()
-\end{verbatim}
-
-\tr{runProcess} is our candidate for the high-level OS-independent
-primitive.
-
-\tr{runProcess cmd args env wd inhdl outhdl errhdl} runs \tr{cmd}
-(searching the current \tr{PATH}) with arguments \tr{args}. If
-\tr{env} is \tr{Just pairs}, the command is executed with the
-environment specified by \tr{pairs} of variables and values;
-otherwise, the command is executed with the current environment. If
-\tr{wd} is \tr{Just dir}, the command is executed with working
-directory \tr{dir}; otherwise, the command is executed in the current
-working directory. If \tr{{in,out,err}hdl} is \tr{Just handle}, the
-command is executed with the \tr{Fd} for \tr{std{in,out,err}}
-attached to the specified \tr{handle}; otherwise, the \tr{Fd} for
-\tr{std{in,out,err}} is left unchanged.
-
-\begin{verbatim}
-getProcessStatus :: Bool -- Block?
- -> Bool -- Stopped processes?
- -> ProcessID
- -> IO (Maybe ProcessStatus)
-\end{verbatim}
-
-\tr{getProcessStatus blk stopped pid} calls \tr{waitpid}, returning
-\tr{Just tc}, the \tr{ProcessStatus} for process \tr{pid} if it is
-available, \tr{Nothing} otherwise. If \tr{blk} is \tr{False}, then
-\tr{WNOHANG} is set in the options for \tr{waitpid}, otherwise not.
-If \tr{stopped} is \tr{True}, then \tr{WUNTRACED} is set in the
-options for \tr{waitpid}, otherwise not.
-
-\begin{verbatim}
-getGroupProcessStatus :: Bool -- Block?
- -> Bool -- Stopped processes?
- -> ProcessGroupID
- -> IO (Maybe (ProcessID, ProcessStatus))
-\end{verbatim}
-
-\tr{getGroupProcessStatus blk stopped pgid} calls \tr{waitpid},
-returning \tr{Just (pid, tc)}, the \tr{ProcessID} and
-\tr{ProcessStatus} for any process in group \tr{pgid} if one is
-available, \tr{Nothing} otherwise. If \tr{blk} is \tr{False}, then
-\tr{WNOHANG} is set in the options for \tr{waitpid}, otherwise not.
-If \tr{stopped} is \tr{True}, then \tr{WUNTRACED} is set in the
-options for \tr{waitpid}, otherwise not.
-
-\begin{verbatim}
-getAnyProcessStatus :: Bool -- Block?
- -> Bool -- Stopped processes?
- -> IO (Maybe (ProcessID, ProcessStatus))
-\end{verbatim}
-
-\tr{getAnyProcessStatus blk stopped} calls \tr{waitpid}, returning
-\tr{Just (pid, tc)}, the \tr{ProcessID} and \tr{ProcessStatus} for any
-child process if one is available, \tr{Nothing} otherwise. If
-\tr{blk} is \tr{False}, then \tr{WNOHANG} is set in the options for
-\tr{waitpid}, otherwise not. If \tr{stopped} is \tr{True}, then
-\tr{WUNTRACED} is set in the options for \tr{waitpid}, otherwise not.
-
-\begin{verbatim}
-exitImmediately :: ExitCode -> IO ()
-\end{verbatim}
-
-\tr{exitImmediately status} calls \tr{_exit} to terminate the process
-with the indicated exit \tr{status}.
-The operation never returns.
-
-\begin{verbatim}
-getEnvironment :: IO [(String, String)]
-\end{verbatim}
-
-\tr{getEnvironment} parses the environment variable mapping provided by
-\tr{environ}, returning \tr{(variable, value)} pairs.
-The operation never fails.
-
-\begin{verbatim}
-setEnvironment :: [(String, String)] -> IO ()
-\end{verbatim}
-
-\tr{setEnvironment} replaces the process environment with the provided
-mapping of \tr{(variable, value)} pairs.
-
-\begin{verbatim}
-getEnvVar :: String -> IO String
-\end{verbatim}
-
-\tr{getEnvVar var} returns the value associated with variable \tr{var}
-in the current environment (identical functionality provided through
-standard Haskell library function @System.getEnv@).
-
-The operation may fail with:
-
-\begin{itemize}
-\item[\tr{NoSuchThing}]
-The variable has no mapping in the current environment.
-\end{itemize}
-
-\begin{verbatim}
-setEnvVar :: String -> String -> IO ()
-\end{verbatim}
-
-\tr{setEnvVar var val} sets the value associated with variable \tr{var}
-in the current environment to be \tr{val}. Any previous mapping is
-superseded.
-
-\begin{verbatim}
-removeEnvVar :: String -> IO ()
-\end{verbatim}
-
-\tr{removeEnvVar var} removes any value associated with variable \tr{var}
-in the current environment. Deleting a variable for which there is no mapping
-does not generate an error.
-
-\begin{verbatim}
-nullSignal :: Signal
-nullSignal = 0
-
-backgroundRead, sigTTIN :: Signal
-backgroundWrite, sigTTOU :: Signal
-continueProcess, sigCONT :: Signal
-floatingPointException, sigFPE :: Signal
-illegalInstruction, sigILL :: Signal
-internalAbort, sigABRT :: Signal
-keyboardSignal, sigINT :: Signal
-keyboardStop, sigTSTP :: Signal
-keyboardTermination, sigQUIT :: Signal
-killProcess, sigKILL :: Signal
-lostConnection, sigHUP :: Signal
-openEndedPipe, sigPIPE :: Signal
-processStatusChanged, sigCHLD :: Signal
-realTimeAlarm, sigALRM :: Signal
-segmentationViolation, sigSEGV :: Signal
-softwareStop, sigSTOP :: Signal
-softwareTermination, sigTERM :: Signal
-userDefinedSignal1, sigUSR1 :: Signal
-userDefinedSignal2, sigUSR2 :: Signal
-
-signalProcess :: Signal -> ProcessID -> IO ()
-\end{verbatim}
-
-\tr{signalProcess int pid} calls \tr{kill} to signal
-process \tr{pid} with interrupt signal \tr{int}.
-
-\begin{verbatim}
-raiseSignal :: Signal -> IO ()
-\end{verbatim}
-
-\tr{raiseSignal int} calls \tr{kill} to signal the current process
-with interrupt signal \tr{int}.
-
-\begin{verbatim}
-signalProcessGroup :: Signal -> ProcessGroupID -> IO ()
-\end{verbatim}
-
-\tr{signalProcessGroup int pgid} calls \tr{kill} to signal
-all processes in group \tr{pgid} with interrupt signal \tr{int}.
-
-\begin{verbatim}
-setStoppedChildFlag :: Bool -> IO Bool
-\end{verbatim}
-
-\tr{setStoppedChildFlag bool} sets a flag which controls whether or
-not the \tr{NOCLDSTOP} option will be used the next time a signal
-handler is installed for \tr{SIGCHLD}. If \tr{bool} is \tr{True} (the
-default), \tr{NOCLDSTOP} will not be used; otherwise it will be. The
-operation never fails.
-
-\begin{verbatim}
-queryStoppedChildFlag :: IO Bool
-\end{verbatim}
-
-\tr{queryStoppedChildFlag} queries the flag which
-controls whether or not the \tr{NOCLDSTOP} option will be used
-the next time a signal handler is installed for \tr{SIGCHLD}.
-If \tr{NOCLDSTOP} will be used, it returns \tr{False};
-otherwise (the default) it returns \tr{True}.
-The operation never fails.
-
-\begin{verbatim}
-emptySignalSet :: SignalSet
-fullSignalSet :: SignalSet
-addSignal :: Signal -> SignalSet -> SignalSet
-deleteSignal :: Signal -> SignalSet -> SignalSet
-inSignalSet :: Signal -> SignalSet -> Bool
-
-installHandler :: Signal
- -> Handler
- -> Maybe SignalSet -- other signals to block
- -> IO Handler -- old handler
-\end{verbatim}
-
-\tr{installHandler int handler iset} calls \tr{sigaction} to install
-an interrupt handler for signal \tr{int}. If \tr{handler} is
-\tr{Default}, \tr{SIG_DFL} is installed; if \tr{handler} is
-\tr{Ignore}, \tr{SIG_IGN} is installed; if \tr{handler} is
-\tr{Catch action}, a handler is installed which will invoke \tr{action} as a
-replacement for \tr{main}. If \tr{iset} is \tr{Just s}, then the
-\tr{sa_mask} of the \tr{sigaction} structure is set to \tr{s};
-otherwise it is cleared. The previously installed signal handler for
-\tr{int} is returned.
-
-\begin{verbatim}
-getSignalMask :: IO SignalSet
-\end{verbatim}
-
-\tr{getSignalMask} calls \tr{sigprocmask} to determine the
-set of interrupts which are currently being blocked.
-
-\begin{verbatim}
-setSignalMask :: SignalSet -> IO SignalSet
-\end{verbatim}
-
-\tr{setSignalMask mask} calls \tr{sigprocmask} with
-\tr{SIG_SETMASK} to block all interrupts in \tr{mask}. The
-previous set of blocked interrupts is returned.
-
-\begin{verbatim}
-blockSignals :: SignalSet -> IO SignalSet
-\end{verbatim}
-
-\tr{setSignalMask mask} calls \tr{sigprocmask} with
-\tr{SIG_BLOCK} to add all interrupts in \tr{mask} to the
-set of blocked interrupts. The previous set of blocked interrupts is returned.
-
-\begin{verbatim}
-unBlockSignals :: SignalSet -> IO SignalSet
-\end{verbatim}
-
-\tr{setSignalMask mask} calls \tr{sigprocmask} with
-\tr{SIG_UNBLOCK} to remove all interrupts in \tr{mask} from the
-set of blocked interrupts. The previous set of blocked interrupts is returned.
-
-\begin{verbatim}
-getPendingSignals :: IO SignalSet
-\end{verbatim}
-
-\tr{getPendingSignals} calls \tr{sigpending} to obtain
-the set of interrupts which have been received but are currently blocked.
-
-\begin{verbatim}
-awaitSignal :: Maybe SignalSet -> IO ()
-\end{verbatim}
-
-\tr{awaitSignal iset} suspends execution until an interrupt is received.
-If \tr{iset} is \tr{Just s}, \tr{awaitSignal} calls
-\tr{sigsuspend}, installing \tr{s} as the new signal mask before
-suspending execution; otherwise, it calls \tr{pause}. If successful,
-\tr{awaitSignal} does not return.
-
-\begin{verbatim}
-scheduleAlarm :: Int -> IO Int
-\end{verbatim}
-
-\tr{scheduleAlarm i} calls \tr{alarm} to schedule a real time
-alarm at least \tr{i} seconds in the future.
-
-\begin{verbatim}
-sleep :: Int -> IO ()
-\end{verbatim}
-
-\tr{sleep i} calls \tr{sleep} to suspend execution of the
-program until at least \tr{i} seconds have elapsed or a signal is
-received.
-
-\subsubsection[Process Environment]{Posix Process Environment}
-\index{Posix, process environment}
-
-\begin{verbatim}
-getProcessID :: IO ProcessID
-\end{verbatim}
-
-\tr{getProcessID} calls \tr{getpid} to obtain the \tr{ProcessID} for
-the current process.
-
-\begin{verbatim}
-getParentProcessID :: IO ProcessID
-\end{verbatim}
-
-\tr{getProcessID} calls \tr{getppid} to obtain the \tr{ProcessID} for
-the parent of the current process.
-
-\begin{verbatim}
-getRealUserID :: IO UserID
-\end{verbatim}
-
-\tr{getRealUserID} calls \tr{getuid} to obtain the real \tr{UserID}
-associated with the current process.
-
-\begin{verbatim}
-getEffectiveUserID :: IO UserID
-\end{verbatim}
-
-\tr{getRealUserID} calls \tr{geteuid} to obtain the effective
-\tr{UserID} associated with the current process.
-
-\begin{verbatim}
-setUserID :: UserID -> IO ()
-\end{verbatim}
-
-\tr{setUserID uid} calls \tr{setuid} to set the real, effective, and
-saved set-user-id associated with the current process to \tr{uid}.
-
-\begin{verbatim}
-getLoginName :: IO String
-\end{verbatim}
-
-\tr{getLoginName} calls \tr{getlogin} to obtain the login name
-associated with the current process.
-
-\begin{verbatim}
-getRealGroupID :: IO GroupID
-\end{verbatim}
-
-\tr{getRealGroupID} calls \tr{getgid} to obtain the real \tr{GroupID}
-associated with the current process.
-
-\begin{verbatim}
-getEffectiveGroupID :: IO GroupID
-\end{verbatim}
-
-\tr{getEffectiveGroupID} calls \tr{getegid} to obtain the effective
-\tr{GroupID} associated with the current process.
-
-\begin{verbatim}
-setGroupID :: GroupID -> IO ()
-\end{verbatim}
-
-\tr{setGroupID gid} calls \tr{setgid} to set the real, effective, and
-saved set-group-id associated with the current process to \tr{gid}.
-
-\begin{verbatim}
-getGroups :: IO [GroupID]
-\end{verbatim}
-
-\tr{getGroups} calls \tr{getgroups} to obtain the list of
-supplementary \tr{GroupID}s associated with the current process.
-
-\begin{verbatim}
-getEffectiveUserName :: IO String
-\end{verbatim}
-
-\tr{getEffectiveUserName} calls \tr{cuserid} to obtain a name
-associated with the effective \tr{UserID} of the process.
-
-\begin{verbatim}
-getProcessGroupID :: IO ProcessGroupID
-\end{verbatim}
-
-\tr{getProcessGroupID} calls \tr{getpgrp} to obtain the
-\tr{ProcessGroupID} for the current process.
-
-\begin{verbatim}
-createProcessGroup :: ProcessID -> IO ProcessGroupID
-\end{verbatim}
-
-\tr{createProcessGroup pid} calls \tr{setpgid} to make
-process \tr{pid} a new process group leader.
-
-\begin{verbatim}
-joinProcessGroup :: ProcessGroupID -> IO ProcessGroupID
-\end{verbatim}
-
-\tr{joinProcessGroup pgid} calls \tr{setpgid} to set the
-\tr{ProcessGroupID} of the current process to \tr{pgid}.
-
-\begin{verbatim}
-setProcessGroupID :: ProcessID -> ProcessGroupID -> IO ()
-\end{verbatim}
-
-\tr{setProcessGroupID pid pgid} calls \tr{setpgid} to set the
-\tr{ProcessGroupID} for process \tr{pid} to \tr{pgid}.
-
-\begin{verbatim}
-createSession :: IO ProcessGroupID
-\end{verbatim}
-
-\tr{createSession} calls \tr{setsid} to create a new session
-with the current process as session leader.
-
-\begin{verbatim}
-systemName :: SystemID -> String
-nodeName :: SystemID -> String
-release :: SystemID -> String
-version :: SystemID -> String
-machine :: SystemID -> String
-
-getSystemID :: IO SystemID
-\end{verbatim}
-
-\tr{getSystemID} calls \tr{uname} to obtain information
-about the current operating system.
-
-\begin{verbatim}
-> epochTime :: IO EpochTime
-\end{verbatim}
-
-\tr{epochTime} calls \tr{time} to obtain the number of
-seconds that have elapsed since the epoch (Jan 01 00:00:00 GMT 1970).
-
-\begin{verbatim}
-elapsedTime :: ProcessTimes -> ClockTick
-userTime :: ProcessTimes -> ClockTick
-systemTime :: ProcessTimes -> ClockTick
-childUserTime :: ProcessTimes -> ClockTick
-childSystemTime :: ProcessTimes -> ClockTick
-
-getProcessTimes :: IO ProcessTimes
-\end{verbatim}
-
-\tr{getProcessTimes} calls \tr{times} to obtain time-accounting
-information for the current process and its children.
-
-\begin{verbatim}
-getControllingTerminalName :: IO FilePath
-\end{verbatim}
-
-\tr{getControllingTerminalName} calls \tr{ctermid} to obtain
-a name associated with the controlling terminal for the process. If a
-controlling terminal exists,
-\tr{getControllingTerminalName} returns the name of the
-controlling terminal.
-
-The operation may fail with:
-
-\begin{itemize}
-\item[\tr{NoSuchThing}]
-There is no controlling terminal, or its name cannot be determined.
-\item[\tr{SystemError}]
-Various other causes.
-\end{itemize}
-
-\begin{verbatim}
-getTerminalName :: Fd -> IO FilePath
-\end{verbatim}
-
-\tr{getTerminalName fd} calls \tr{ttyname} to obtain a name associated
-with the terminal for \tr{Fd} \tr{fd}. If \tr{fd} is associated
-with a terminal, \tr{getTerminalName} returns the name of the
-terminal.
-
-The operation may fail with:
-
-\begin{itemize}
-\item[\tr{InappropriateType}]
-The channel is not associated with a terminal.
-\item[\tr{NoSuchThing}]
-The channel is associated with a terminal, but it has no name.
-\item[\tr{SystemError}]
-Various other causes.
-\end{itemize}
-
-\begin{verbatim}
-queryTerminal :: Fd -> IO Bool
-\end{verbatim}
-
-\tr{queryTerminal fd} calls \tr{isatty} to determine whether or
-not \tr{Fd} \tr{fd} is associated with a terminal.
-
-\begin{verbatim}
-getSysVar :: SysVar -> IO Limit
-\end{verbatim}
-
-\tr{getSysVar var} calls \tr{sysconf} to obtain the
-dynamic value of the requested configurable system limit or option.
-For defined system limits, \tr{getSysVar} returns the associated
-value. For defined system options, the result of \tr{getSysVar}
-is undefined, but not failure.
-
-The operation may fail with:
-
-\begin{itemize}
-\item[\tr{NoSuchThing}]
-The requested system limit or option is undefined.
-\end{itemize}
-
-\subsubsection[Files and Directories]{Posix operations on files and directories}
-\index{Posix, files and directories}
-
-\begin{verbatim}
-openDirStream :: FilePath -> IO DirStream
-\end{verbatim}
-
-\tr{openDirStream dir} calls \tr{opendir} to obtain a
-directory stream for \tr{dir}.
-
-\begin{verbatim}
-readDirStream :: DirStream -> IO String
-\end{verbatim}
-
-\tr{readDirStream dp} calls \tr{readdir} to obtain the
-next directory entry (\tr{struct dirent}) for the open directory
-stream \tr{dp}, and returns the \tr{d_name} member of that
-structure.
-
-The operation may fail with:
-
-\begin{itemize}
-\item[\tr{EOF}]
-End of file has been reached.
-\item[\tr{SystemError}]
-Various other causes.
-\end{itemize}
-
-\begin{verbatim}
-rewindDirStream :: DirStream -> IO ()
-\end{verbatim}
-
-\tr{rewindDirStream dp} calls \tr{rewinddir} to reposition
-the directory stream \tr{dp} at the beginning of the directory.
-
-\begin{verbatim}
-closeDirStream :: DirStream -> IO ()
-\end{verbatim}
-
-\tr{closeDirStream dp} calls \tr{closedir} to close
-the directory stream \tr{dp}.
-
-\begin{verbatim}
-getWorkingDirectory :: IO FilePath
-\end{verbatim}
-
-\tr{getWorkingDirectory} calls \tr{getcwd} to obtain the name
-of the current working directory.
-
-\begin{verbatim}
-changeWorkingDirectory :: FilePath -> IO ()
-\end{verbatim}
-
-\tr{changeWorkingDirectory dir} calls \tr{chdir} to change
-the current working directory to \tr{dir}.
-
-\begin{verbatim}
-nullFileMode :: FileMode -- ---------
-ownerReadMode :: FileMode -- r--------
-ownerWriteMode :: FileMode -- -w-------
-ownerExecuteMode :: FileMode -- --x------
-groupReadMode :: FileMode -- ---r-----
-groupWriteMode :: FileMode -- ----w----
-groupExecuteMode :: FileMode -- -----x---
-otherReadMode :: FileMode -- ------r--
-otherWriteMode :: FileMode -- -------w-
-otherExecuteMode :: FileMode -- --------x
-setUserIDMode :: FileMode -- --S------
-setGroupIDMode :: FileMode -- -----S---
-
-stdFileMode :: FileMode -- rw-rw-rw-
-
-ownerModes :: FileMode -- rwx------
-groupModes :: FileMode -- ---rwx---
-otherModes :: FileMode -- ------rwx
-accessModes :: FileMode -- rwxrwxrwx
-
-unionFileModes :: FileMode -> FileMode -> FileMode
-intersectFileModes :: FileMode -> FileMode -> FileMode
-
-stdInput :: Fd
-stdInput = intToFd 0
-
-stdOutput :: Fd
-stdOutput = intToFd 1
-
-stdError :: Fd
-stdError = intToFd 2
-
-data OpenFileFlags =
- OpenFileFlags {
- append :: Bool,
- exclusive :: Bool,
- noctty :: Bool,
- nonBlock :: Bool,
- trunc :: Bool
- }
-
-openFd :: FilePath
- -> OpenMode
- -> Maybe FileMode -- Just x => O_CREAT, Nothing => must exist
- -> OpenFileFlags
- -> IO Fd
-\end{verbatim}
-
-\tr{openFd path acc mode (OpenFileFlags app excl noctty nonblock trunc)} calls
-\tr{open} to obtain a \tr{Fd} for the file \tr{path} with access
-mode \tr{acc}. If \tr{mode} is \tr{Just m}, the \tr{O_CREAT} flag is
-set and the file's permissions will be based on \tr{m} if it does not
-already exist; otherwise, the \tr{O_CREAT} flag is not set. The
-arguments \tr{app}, \tr{excl}, \tr{noctty}, \tr{nonblock}, and
-\tr{trunc} control whether or not the flags \tr{O_APPEND},
-\tr{O_EXCL}, \tr{O_NOCTTY}, \tr{O_NONBLOCK}, and \tr{O_TRUNC} are set,
-respectively.
-
-\begin{verbatim}
-createFile :: FilePath -> FileMode -> IO Fd
-\end{verbatim}
-
-\tr{createFile path mode} calls \tr{creat} to obtain a \tr{Fd}
-for file \tr{path}, which will be created with permissions based on
-\tr{mode} if it does not already exist.
-
-\begin{verbatim}
-setFileCreationMask :: FileMode -> IO FileMode
-\end{verbatim}
-
-\tr{setFileCreationMask mode} calls \tr{umask} to set
-the process's file creation mask to \tr{mode}. The previous file
-creation mask is returned.
-
-\begin{verbatim}
-createLink :: FilePath -> FilePath -> IO ()
-\end{verbatim}
-
-\tr{createLink old new} calls \tr{link} to create a
-new path, \tr{new}, linked to an existing file, \tr{old}.
-\begin{verbatim}
-createDirectory :: FilePath -> FileMode -> IO ()
-\end{verbatim}
-
-\tr{createDirectory dir mode} calls \tr{mkdir} to
-create a new directory, \tr{dir}, with permissions based on
-\tr{mode}.
-
-\begin{verbatim}
-createNamedPipe :: FilePath -> FileMode -> IO ()
-\end{verbatim}
-
-\tr{createNamedPipe fifo mode} calls \tr{mkfifo} to
-create a new named pipe, \tr{fifo}, with permissions based on
-\tr{mode}.
-
-\begin{verbatim}
-removeLink :: FilePath -> IO ()
-\end{verbatim}
-
-\tr{removeLink path} calls \tr{unlink} to remove the link
-named \tr{path}.
-
-\begin{verbatim}
-removeDirectory :: FilePath -> IO ()
-\end{verbatim}
-
-\tr{removeDirectory dir} calls \tr{rmdir} to remove the
-directory named \tr{dir}.
-
-\begin{verbatim}
-rename :: FilePath -> FilePath -> IO ()
-\end{verbatim}
-
-\tr{rename old new} calls \tr{rename} to rename a
-file or directory from \tr{old} to \tr{new}.
-
-\begin{verbatim}
-fileMode :: FileStatus -> FileMode
-
-fileID :: FileStatus -> FileID
-deviceID :: FileStatus -> DeviceID
-
-linkCount :: FileStatus -> LinkCount
-
-fileOwner :: FileStatus -> UserID
-fileGroup :: FileStatus -> GroupID
-fileSize :: FileStatus -> FileOffset
-
-accessTime :: FileStatus -> EpochTime
-modificationTime :: FileStatus -> EpochTime
-statusChangeTime :: FileStatus -> EpochTime
-
-isDirectory :: FileStatus -> Bool
-isCharacterDevice :: FileStatus -> Bool
-isBlockDevice :: FileStatus -> Bool
-isRegularFile :: FileStatus -> Bool
-isNamedPipe :: FileStatus -> Bool
-
-getFileStatus :: FilePath -> IO FileStatus
-\end{verbatim}
-
-\tr{getFileStatus path} calls \tr{stat} to get the
-\tr{FileStatus} information for the file \tr{path}.
-
-\begin{verbatim}
-getFdStatus :: Fd -> IO FileStatus
-\end{verbatim}
-
-\tr{getFdStatus fd} calls \tr{fstat} to get the
-\tr{FileStatus} information for the file associated with
-\tr{Fd} \tr{fd}.
-
-\begin{verbatim}
-queryAccess :: FilePath -> Bool -> Bool -> Bool -> IO Bool
-\end{verbatim}
-
-\tr{queryAccess path r w x} calls \tr{access} to test the access
-permissions for file \tr{path}. The three arguments, \tr{r}, \tr{w},
-and \tr{x} control whether or not \tr{access} is called with
-\tr{R_OK}, \tr{W_OK}, and \tr{X_OK} respectively.
-
-\begin{verbatim}
-queryFile :: FilePath -> IO Bool
-\end{verbatim}
-
-\tr{queryFile path} calls \tr{access} with \tr{F_OK} to test for the
-existence for file \tr{path}.
-
-\begin{verbatim}
-setFileMode :: FilePath -> FileMode -> IO ()
-\end{verbatim}
-
-\tr{setFileMode path mode} calls \tr{chmod} to set the
-permission bits associated with file \tr{path} to \tr{mode}.
-
-\begin{verbatim}
-setOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO ()
-\end{verbatim}
-
-\tr{setOwnerAndGroup path uid gid} calls \tr{chown} to
-set the \tr{UserID} and \tr{GroupID} associated with file
-\tr{path} to \tr{uid} and \tr{gid}, respectively.
-
-\begin{verbatim}
-setFileTimes :: FilePath -> EpochTime -> EpochTime -> IO ()
-\end{verbatim}
-
-\tr{setFileTimes path atime mtime} calls \tr{utime} to
-set the access and modification times associated with file
-\tr{path} to \tr{atime} and \tr{mtime}, respectively.
-
-\begin{verbatim}
-touchFile :: FilePath -> IO ()
-\end{verbatim}
-
-\tr{touchFile path} calls \tr{utime} to
-set the access and modification times associated with file
-\tr{path} to the current time.
-
-\begin{verbatim}
-getPathVar :: PathVar -> FilePath -> IO Limit
-\end{verbatim}
-
-\tr{getPathVar var path} calls \tr{pathconf} to obtain the
-dynamic value of the requested configurable file limit or option associated
-with file or directory \tr{path}. For
-defined file limits, \tr{getPathVar} returns the associated
-value. For defined file options, the result of \tr{getPathVar}
-is undefined, but not failure.
-The operation may fail with:
-\begin{itemize}
-\item[\tr{NoSuchThing}]
-The requested file limit or option is undefined.
-\item[\tr{SystemError}]
-Various other causes.
-\end{itemize}
-
-
-\begin{verbatim}
-getFdVar :: PathVar -> Fd -> IO Limit
-\end{verbatim}
-
-\tr{getFdVar var fd} calls \tr{fpathconf} to obtain the
-dynamic value of the requested configurable file limit or option associated
-with the file or directory attached to the open channel \tr{fd}.
-For defined file limits, \tr{getFdVar} returns the associated
-value. For defined file options, the result of \tr{getFdVar}
-is undefined, but not failure.
-
-The operation may fail with:
-
-\begin{itemize}
-\item[\tr{NoSuchThing}]
-The requested file limit or option is undefined.
-\item[\tr{SystemError}]
-Various other causes.
-\end{itemize}
-
-\subsubsection[Inut Output]{Posix Input and Output Primitives}
-\index{Posix, input/output}
-
-\begin{verbatim}
-createPipe :: IO (Fd, Fd)
-\end{verbatim}
-
-\tr{createPipe} calls \tr{pipe} to create a pipe and returns a pair of
-\tr{Fd}s, the first for writing and the second for reading.
-
-\begin{verbatim}
-dup :: Fd -> IO Fd
-\end{verbatim}
-
-\tr{dup fd} calls \tr{dup} to duplicate \tr{Fd} \tr{fd} to
-another \tr{Fd}.
-
-\begin{verbatim}
-dupTo :: Fd -> Fd -> IO ()
-\end{verbatim}
-
-\tr{dupTo src dst} calls \tr{dup2} to duplicate \tr{Fd}
-\tr{src} to \tr{Fd} \tr{dst}.
-
-\begin{verbatim}
-fdClose :: Fd -> IO ()
-\end{verbatim}
-
-\tr{fdClose fd} calls \tr{close} to close \tr{Fd} \tr{fd}.
-
-\begin{verbatim}
-fdRead :: Fd -> ByteCount -> IO (String, ByteCount)
-\end{verbatim}
-
-\tr{fdRead fd nbytes} calls \tr{read} to read at most \tr{nbytes}
-bytes from \tr{Fd} \tr{fd}, and returns the result as a string
-paired with the number of bytes actually read.
-
-The operation may fail with:
-
-\begin{itemize}
-\item[\tr{EOF}]
-End of file has been reached.
-\item[\tr{SystemError}]
-Various other causes.
-\end{itemize}
-
-\begin{verbatim}
-fdWrite :: Fd -> String -> IO ByteCount
-\end{verbatim}
-
-\tr{fdWrite fd s} calls \tr{write} to write
-the string \tr{s} to \tr{Fd} \tr{fd} as a
-contiguous sequence of bytes. It returns the number of bytes successfully
-written.
-
-\begin{verbatim}
-queryFdOption :: FdOption -> Fd -> IO Bool
-\end{verbatim}
-
-\tr{getFdOption opt fd} calls \tr{fcntl} to determine whether or
-not the flag associated with \tr{FdOption} \tr{opt} is set for
-\tr{Fd} \tr{fd}.
-
-\begin{verbatim}
-setFdOption :: Fd -> FdOption -> Bool -> IO ()
-\end{verbatim}
-
-\tr{setFdOption fd opt val} calls \tr{fcntl} to set the flag
-associated with \tr{FdOption} \tr{opt} on \tr{Fd} \tr{fd} to
-\tr{val}.
-
-\begin{verbatim}
-getLock :: Fd -> FileLock -> IO (Maybe (ProcessID, FileLock))
-\end{verbatim}
-
-\tr{getLock fd lock} calls \tr{fcntl} to get the first \tr{FileLock}
-for \tr{Fd} \tr{fd} which blocks the \tr{FileLock} \tr{lock}. If
-no such \tr{FileLock} exists, \tr{getLock} returns \tr{Nothing}.
-Otherwise, it returns \tr{Just (pid, block)}, where \tr{block} is the
-blocking \tr{FileLock} and \tr{pid} is the \tr{ProcessID} of the
-process holding the blocking \tr{FileLock}.
-
-
-\begin{verbatim}
-setLock :: Fd -> FileLock -> IO ()
-\end{verbatim}
-
-\tr{setLock fd lock} calls \tr{fcntl} with \tr{F_SETLK} to set or
-clear a lock segment for \tr{Fd} \tr{fd} as indicated by the
-\tr{FileLock} \tr{lock}. \tr{setLock} does not block, but fails with
-\tr{SystemError} if the request cannot be satisfied immediately.
-
-\begin{verbatim}
-waitToSetLock :: Fd -> FileLock -> IO ()
-\end{verbatim}
-
-\tr{waitToSetLock fd lock} calls \tr{fcntl} with \tr{F_SETLKW} to set
-or clear a lock segment for \tr{Fd} \tr{fd} as indicated by the
-\tr{FileLock} \tr{lock}. If the request cannot be satisfied
-immediately, \tr{waitToSetLock} blocks until the request can be
-satisfied.
-
-
-\begin{verbatim}
-fdSeek :: Fd -> SeekMode -> FileOffset -> IO FileOffset
-\end{verbatim}
-
-\tr{fdSeek fd whence offset} calls \tr{lseek} to position the
-\tr{Fd} \tr{fd} at the given \tr{offset} from the starting location
-indicated by \tr{whence}. It returns the resulting offset from the
-start of the file in bytes.
-
-\subsubsection[Device Specific Functions]{Posix, Device- and Class-Specific Functions}
-\index{Posix, device and class-specific functions}
-
-\begin{verbatim}
-terminalMode :: TerminalMode -> TerminalAttributes -> Bool
-withMode :: TerminalAttributes -> TerminalMode -> TerminalAttributes
-withoutMode :: TerminalAttributes -> TerminalMode -> TerminalAttributes
-
-bitsPerByte :: TerminalAttributes -> Int
-withBits :: TerminalAttributes -> Int -> TerminalAttributes
-
-controlChar :: TerminalAttributes -> ControlCharacter -> Maybe Char
-withCC :: TerminalAttributes
- -> (ControlCharacter, Char)
- -> TerminalAttributes
-withoutCC :: TerminalAttributes
- -> ControlCharacter
- -> TerminalAttributes
-
-inputTime :: TerminalAttributes -> Int
-withTime :: TerminalAttributes -> Int -> TerminalAttributes
-
-minInput :: TerminalAttributes -> Int
-withMinInput :: TerminalAttributes -> Int -> TerminalAttributes
-
-inputSpeed :: TerminalAttributes -> BaudRate
-withInputSpeed :: TerminalAttributes -> BaudRate -> TerminalAttributes
-
-outputSpeed :: TerminalAttributes -> BaudRate
-withOutputSpeed :: TerminalAttributes -> BaudRate -> TerminalAttributes
-
-getTerminalAttributes :: Fd -> IO TerminalAttributes
-\end{verbatim}
-
-\tr{getTerminalAttributes fd} calls \tr{tcgetattr} to obtain
-the \tr{TerminalAttributes} associated with \tr{Fd} \tr{fd}.
-
-\begin{verbatim}
-setTerminalAttributes :: Fd
- -> TerminalAttributes
- -> TerminalState
- -> IO ()
-\end{verbatim}
-
-\tr{setTerminalAttributes fd attr ts} calls \tr{tcsetattr} to change
-the \tr{TerminalAttributes} associated with \tr{Fd} \tr{fd} to
-\tr{attr}, when the terminal is in the state indicated by \tr{ts}.
-
-\begin{verbatim}
-sendBreak :: Fd -> Int -> IO ()
-\end{verbatim}
-
-\tr{sendBreak fd duration} calls \tr{tcsendbreak} to transmit a
-continuous stream of zero-valued bits on \tr{Fd} \tr{fd} for the
-specified implementation-dependent \tr{duration}.
-
-\begin{verbatim}
-drainOutput :: Fd -> IO ()
-\end{verbatim}
-
-\tr{drainOutput fd} calls \tr{tcdrain} to block until all output
-written to \tr{Fd} \tr{fd} has been transmitted.
-
-\begin{verbatim}
-discardData :: Fd -> QueueSelector -> IO ()
-\end{verbatim}
-
-\tr{discardData fd queues} calls \tr{tcflush} to discard
-pending input and/or output for \tr{Fd} \tr{fd},
-as indicated by the \tr{QueueSelector} \tr{queues}.
-
-\begin{verbatim}
-controlFlow :: Fd -> FlowAction -> IO ()
-\end{verbatim}
-
-\tr{controlFlow fd action} calls \tr{tcflow} to control the
-flow of data on \tr{Fd} \tr{fd}, as indicated by
-\tr{action}.
-
-\begin{verbatim}
-getTerminalProcessGroupID :: Fd -> IO ProcessGroupID
-\end{verbatim}
-
-\tr{getTerminalProcessGroupID fd} calls \tr{tcgetpgrp} to
-obtain the \tr{ProcessGroupID} of the foreground process group
-associated with the terminal attached to \tr{Fd} \tr{fd}.
-
-\begin{verbatim}
-setTerminalProcessGroupID :: Fd -> ProcessGroupID -> IO ()
-\end{verbatim}
-
-\tr{setTerminalProcessGroupID fd pgid} calls \tr{tcsetpgrp} to
-set the \tr{ProcessGroupID} of the foreground process group
-associated with the terminal attached to \tr{Fd}
-\tr{fd} to \tr{pgid}.
-
-\subsubsection[System Database]{Posix System Databases}
-\index{Posix, system databases}
-
-\begin{verbatim}
-groupName :: GroupEntry -> String
-groupID :: GroupEntry -> GroupID
-groupMembers :: GroupEntry -> [String]
-
-getGroupEntryForID :: GroupID -> IO GroupEntry
-\end{verbatim}
-
-\tr{getGroupEntryForID gid} calls \tr{getgrgid} to obtain
-the \tr{GroupEntry} information associated with \tr{GroupID}
-\tr{gid}.
-
-The operation may fail with:
-
-\begin{itemize}
-\item[\tr{NoSuchThing}]
-There is no group entry for the GroupID.
-\end{itemize}
-
-\begin{verbatim}
-getGroupEntryForName :: String -> IO GroupEntry
-\end{verbatim}
-
-\tr{getGroupEntryForName name} calls \tr{getgrnam} to obtain
-the \tr{GroupEntry} information associated with the group called
-\tr{name}.
-
-The operation may fail with:
-
-\begin{itemize}
-\item[\tr{NoSuchThing}]
-There is no group entry for the name.
-\end{itemize}
-
-\begin{verbatim}
-userName :: UserEntry -> String
-userID :: UserEntry -> UserID
-userGroupID :: UserEntry -> GroupID
-homeDirectory :: UserEntry -> String
-userShell :: UserEntry -> String
-
-getUserEntryForID :: UserID -> IO UserEntry
-\end{verbatim}
-
-\tr{getUserEntryForID gid} calls \tr{getpwuid} to obtain
-the \tr{UserEntry} information associated with \tr{UserID}
-\tr{uid}.
-The operation may fail with:
-
-\begin{itemize}
-\item[\tr{NoSuchThing}]
-There is no user entry for the UserID.
-\end{itemize}
-
-\begin{verbatim}
-getUserEntryForName :: String -> IO UserEntry
-\end{verbatim}
-
-\tr{getUserEntryForName name} calls \tr{getpwnam} to obtain
-the \tr{UserEntry} information associated with the user login
-\tr{name}.
-
-The operation may fail with:
-
-\begin{itemize}
-\item[\tr{NoSuchThing}]
-There is no user entry for the name.
-\end{itemize}
-
-\subsubsection[Error reporting and handling]{POSIX Errors}
-\index{Posix, errors}
-
-\begin{verbatim}
-getErrorCode :: IO ErrorCode
-\end{verbatim}
-
-\tr{getErrorCode} returns the current value of the external
-variable \tr{errno}. It never fails.
-
-\begin{verbatim}
-setErrorCode :: ErrorCode -> IO ()
-\end{verbatim}
-
-\tr{setErrorCode err} sets the external
-variable \tr{errno} to \tr{err}. It never fails.
-
-\begin{verbatim}
-noError :: ErrorCode
-noError = 0
-
-argumentListTooLong, e2BIG :: ErrorCode
-badFd, eBADF :: ErrorCode
-brokenPipe, ePIPE :: ErrorCode
-directoryNotEmpty, eNOTEMPTY :: ErrorCode
-execFormatError, eNOEXEC :: ErrorCode
-fileAlreadyExists, eEXIST :: ErrorCode
-fileTooLarge, eFBIG :: ErrorCode
-filenameTooLong, eNAMETOOLONG :: ErrorCode
-improperLink, eXDEV :: ErrorCode
-inappropriateIOControlOperation, eNOTTY :: ErrorCode
-inputOutputError, eIO :: ErrorCode
-interruptedOperation, eINTR :: ErrorCode
-invalidArgument, eINVAL :: ErrorCode
-invalidSeek, eSPIPE :: ErrorCode
-isADirectory, eISDIR :: ErrorCode
-noChildProcess, eCHILD :: ErrorCode
-noLocksAvailable, eNOLCK :: ErrorCode
-noSpaceLeftOnDevice, eNOSPC :: ErrorCode
-noSuchOperationOnDevice, eNODEV :: ErrorCode
-noSuchDeviceOrAddress, eNXIO :: ErrorCode
-noSuchFileOrDirectory, eNOENT :: ErrorCode
-noSuchProcess, eSRCH :: ErrorCode
-notADirectory, eNOTDIR :: ErrorCode
-notEnoughMemory, eNOMEM :: ErrorCode
-operationNotImplemented, eNOSYS :: ErrorCode
-operationNotPermitted, ePERM :: ErrorCode
-permissionDenied, eACCES :: ErrorCode
-readOnlyFileSystem, eROFS :: ErrorCode
-resourceBusy, eBUSY :: ErrorCode
-resourceDeadlockAvoided, eDEADLK :: ErrorCode
-resourceTemporarilyUnavailable, eAGAIN :: ErrorCode
-tooManyLinks, eMLINK :: ErrorCode
-tooManyOpenFiles, eMFILE :: ErrorCode
-tooManyOpenFilesInSystem, eNFILE :: ErrorCode
-
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsection[HBC-library]{The HBC system library}
-\index{HBC system library}
-\index{system library, HBC}
-%* *
-%************************************************************************
-
-This documentation is stolen directly from the HBC distribution. The
-modules that GHC does not support (because they require HBC-specific
-extensions) are omitted.
-
-\begin{description}
-\item[\tr{Either}:]
-\index{Either module (HBC library)}%
-A binary sum data type:
-\begin{verbatim}
-data Either a b = Left a | Right b
-\end{verbatim}
-The constructor \tr{Left} is typically used for errors; it can be
-renamed to \tr{Wrong} on import.
-
-\item[\tr{Maybe}:]
-\index{Maybe module (HBC library)}%
-A type for failure or success:
-\begin{verbatim}
-data Maybe a = Nothing | Just a
-thenM :: Maybe a -> (a -> Maybe b) -> Maybe b
- -- apply a function that may fail
-\end{verbatim}
-
-\item[\tr{Option}:]
-\index{Option module (HBC library)}%
-An alias for \tr{Maybe}:
-\begin{verbatim}
-data Option a = None | Some a
-thenO :: Option a -> (a -> Option b) -> Option b
-\end{verbatim}
-
-\item[\tr{ListUtil}:]
-\index{ListUtil module (HBC library)}%
-Various useful functions involving lists that are missing from the
-\tr{Prelude}:
-\begin{verbatim}
-assoc :: (Eq c) => (a -> b) -> b -> [(c, a)] -> c -> b
- -- assoc f d l k looks for k in the association list l, if it
- -- is found f is applied to the value, otherwise d is returned.
-concatMap :: (a -> [b]) -> [a] -> [b]
- -- flattening map (LML's concmap)
-unfoldr :: (a -> (b, a)) -> (a -> Bool) -> a -> [b]
- -- unfoldr f p x repeatedly applies f to x until (p x) holds.
- -- (f x) should give a list element and a new x.
-mapAccuml :: (a -> b -> (a, c)) -> a -> [b] -> (a, [c])
- -- mapAccuml f s l maps f over l, but also threads the state s
- -- through (LML's mapstate).
-union :: (Eq a) => [a] -> [a] -> [a]
- -- union of two lists
-intersection :: (Eq a) => [a] -> [a] -> [a]
- -- intersection of two lists
-chopList :: ([a] -> (b, [a])) -> [a] -> [b]
- -- LMLs choplist
-assocDef :: (Eq a) => [(a, b)] -> b -> a -> b
- -- LMLs assocdef
-lookup :: (Eq a) => [(a, b)] -> a -> Option b
- -- lookup l k looks for the key k in the association list l
- -- and returns an optional value
-tails :: [a] -> [[a]]
- -- return all the tails of a list
-rept :: (Integral a) => a -> b -> [b]
- -- repeat a value a number of times
-groupEq :: (a->a->Bool) -> [a] -> [[a]]
- -- group list elements according to an equality predicate
-group :: (Eq a) => [a] -> [[a]]
- -- group according to} ==
-readListLazily :: (Text a) => String -> [a]
- -- read a list in a lazy fashion
-\end{verbatim}
-
-\item[\tr{Pretty}:]
-\index{Pretty module (HBC library)}%
-John Hughes's pretty printing library.
-\begin{verbatim}
-type Context = (Bool, Int, Int, Int)
-type IText = Context -> [String]
-text :: String -> IText -- just text
-(~.) :: IText -> IText -> IText -- horizontal composition
-(^.) :: IText -> IText -> IText -- vertical composition
-separate :: [IText] -> IText -- separate by spaces
-nest :: Int -> IText -> IText -- indent
-pretty :: Int -> Int -> IText -> String -- format it
-\end{verbatim}
-
-\item[\tr{QSort}:]
-\index{QSort module (HBC library)}%
-A sort function using quicksort.
-\begin{verbatim}
-sortLe :: (a -> a -> Bool) -> [a] -> [a]
- -- sort le l sorts l with le as less than predicate
-sort :: (Ord a) => [a] -> [a]
- -- sort l sorts l using the Ord class
-\end{verbatim}
-
-\item[\tr{Random}:]
-\index{Random module (HBC library)}%
-Random numbers.
-\begin{verbatim}
-randomInts :: Int -> Int -> [Int]
- -- given two seeds gives a list of random Int
-randomDoubles :: Int -> Int -> [Double]
- -- random Double with uniform distribution in (0,1)
-normalRandomDoubles :: Int -> Int -> [Double]
- -- random Double with normal distribution, mean 0, variance 1
-\end{verbatim}
-
-\item[\tr{Trace}:]
-Simple tracing. (Note: This comes with GHC anyway.)
-\begin{verbatim}
-trace :: String -> a -> a -- trace x y prints x and returns y
-\end{verbatim}
-
-\item[\tr{Miranda}:]
-\index{Miranda module (HBC library)}%
-Functions found in the Miranda library.
-(Note: Miranda is a registered trade mark of Research Software Ltd.)
-
-\item[\tr{Word}:]
-\index{Word module (HBC library)}
-Bit manipulation. (GHC doesn't implement absolutely all of this.
-And don't count on @Word@ being 32 bits on a Alpha...)
-\begin{verbatim}
-class Bits a where
- bitAnd :: a -> a -> a -- bitwise and
- bitOr :: a -> a -> a -- bitwise or
- bitXor :: a -> a -> a -- bitwise xor
- bitCompl :: a -> a -- bitwise negation
- bitRsh :: a -> Int -> a -- bitwise right shift
- bitLsh :: a -> Int -> a -- bitwise left shift
- bitSwap :: a -> a -- swap word halves
- bit0 :: a -- word with least significant bit set
- bitSize :: a -> Int -- number of bits in a word
-
-data Byte -- 8 bit quantity
-data Short -- 16 bit quantity
-data Word -- 32 bit quantity
-
-instance Bits Byte, Bits Short, Bits Word
-instance Eq Byte, Eq Short, Eq Word
-instance Ord Byte, Ord Short, Ord Word
-instance Text Byte, Text Short, Text Word
-instance Num Byte, Num Short, Num Word
-wordToShorts :: Word -> [Short] -- convert a Word to two Short
-wordToBytes :: Word -> [Byte] -- convert a Word to four Byte
-bytesToString :: [Byte] -> String -- convert a list of Byte to a String (bit by bit)
-wordToInt :: Word -> Int -- convert a Word to Int
-shortToInt :: Short -> Int -- convert a Short to Int
-byteToInt :: Byte -> Int -- convert a Byte to Int
-\end{verbatim}
-
-\item[\tr{TimeUtil}:]
-\index{Time module (HBC library)}%
-Manipulate time values (a Double with seconds since 1970).
-[7/97 -- this lib has been more or less superceeded by the standard Time
- interface]
-
-\begin{verbatim}
--- year mon day hour min sec dec-sec weekday
-data Time = Time Int Int Int Int Int Int Double Int
-dblToTime :: Double -> Time -- convert a Double to a Time
-timeToDbl :: Time -> Double -- convert a Time to a Double
-timeToString :: Time -> String -- convert a Time to a readable String
-\end{verbatim}
-
-\item[\tr{Hash}:]
-\index{Hash module (HBC library)}%
-Hashing functions.
-\begin{verbatim}
-class Hashable a where
- hash :: a -> Int -- hash a value, return an Int
--- instances for all Prelude types
-hashToMax :: (Hashable a) => Int -> a -> Int -- hash into interval [0..x-1]
-\end{verbatim}
-
-\item[\tr{NameSupply}:]
-\index{NameSupply module (HBC library)}%
-Functions to generate unique names (Int).
-\begin{verbatim}
-type Name = Int
-initialNameSupply :: NameSupply
- -- The initial name supply (may be different every
- -- time the program is run.
-splitNameSupply :: NameSupply -> (NameSupply,NameSupply)
- -- split the namesupply into two
-getName :: NameSupply -> Name
- -- get the name associated with a name supply
-\end{verbatim}
-
-\item[\tr{Parse}:]
-\index{Parse module (HBC library)}%
-Higher order functions to build parsers. With a little care these
-combinators can be used to build efficient parsers with good error
-messages.
-\begin{verbatim}
-infixr 8 +.+ , ..+ , +..
-infix 6 `act` , >>> , `into` , .>
-infixr 4 ||| , ||! , |!!
-data ParseResult a b
-type Parser a b = a -> Int -> ParseResult a b
-(|||) :: Parser a b -> Parser a b -> Parser a b
- -- Alternative
-(||!) :: Parser a b -> Parser a b -> Parser a b
- -- Alternative, but with committed choice
-(|!!) :: Parser a b -> Parser a b -> Parser a b
- -- Alternative, but with committed choice
-(+.+) :: Parser a b -> Parser a c -> Parser a (b,c)
- -- Sequence
-(..+) :: Parser a b -> Parser a c -> Parser a c
- -- Sequence, throw away first part
-(+..) :: Parser a b -> Parser a c -> Parser a b
- -- Sequence, throw away second part
-act :: Parser a b -> (b->c) -> Parser a c
- -- Action
-(>>>) :: Parser a (b,c) -> (b->c->d) -> Parser a d
- -- Action on two items
-(.>) :: Parser a b -> c -> Parse a c
- -- Action ignoring value
-into :: Parser a b -> (b -> Parser a c) -> Parser a c
- -- Use a produced value in a parser.
-succeed b :: Parser a b
- -- Always succeeds without consuming a token
-failP :: Parser a b
- -- Always fails.
-many :: Parser a b -> Parser a [b]
- -- Kleene star
-many1 :: Parser a b -> Parser a [b]
- -- Kleene plus
-count :: Parser a b -> Int -> Parser a [b]
- -- Parse an exact number of items
-sepBy1 :: Parser a b -> Parser a c -> Parser a [b]
- -- Non-empty sequence of items separated by something
-sepBy :: Parser a b -> Parser a c -> Parser a [b]
- -- Sequence of items separated by something
-lit :: (Eq a, Text a) => a -> Parser [a] a
- -- Recognise a literal token from a list of tokens
-litp :: String -> (a->Bool) -> Parser [a] a
- -- Recognise a token with a predicate.
- -- The string is a description for error messages.
-testp :: String -> (a -> Bool) -> (Parser b a) -> Parser b a
- -- Test a semantic value.
-token :: (a -> Either String (b, a)) -> Parser a b
- -- General token recogniser.
-parse :: Parser a b -> a -> Either ([String], a) [(b, a)]
- -- Do a parse. Return either error (possible tokens and rest
- -- of tokens) or all possible parses.
-sParse :: (Text a) => (Parser [a] b) -> [a] -> Either String b
- -- Simple parse. Return error message or result.
-\end{verbatim}
-
-%%%simpleLex :: String -> [String] -- A simple (but useful) lexical analyzer
-
-\item[\tr{Native}:]
-\index{Native module (HBC library)}%
-Functions to convert the primitive types \tr{Int}, \tr{Float}, and \tr{Double} to
-their native representation as a list of bytes (\tr{Char}). If such a list
-is read/written to a file it will have the same format as when, e.g.,
-C read/writes the same kind of data.
-\begin{verbatim}
-type Bytes = [Char] -- A byte stream is just a list of characters
-
-class Native a where
- showBytes :: a -> Bytes -> Bytes
- -- prepend the representation of an item the a byte stream
- listShowBytes :: [a] -> Bytes -> Bytes
- -- prepend the representation of a list of items to a stream
- -- (may be more efficient than repeating showBytes).
- readBytes :: Bytes -> Maybe (a, Bytes)
- -- get an item from the stream and return the rest,
- -- or fail if the stream is to short.
- listReadBytes :: Int -> Bytes -> Maybe ([a], Bytes)
- -- read n items from a stream.
-
-instance Native Int
-instance Native Float
-instance Native Double
-instance (Native a, Native b) => Native (a,b)
- -- juxtaposition of the two items
-instance (Native a, Native b, Native c) => Native (a, b, c)
- -- juxtaposition of the three items
-instance (Native a) => Native [a]
- -- an item count in an Int followed by the items
-
-shortIntToBytes :: Int -> Bytes -> Bytes
- -- Convert an Int to what corresponds to a short in C.
-bytesToShortInt :: Bytes -> Maybe (Int, Bytes)
- -- Get a short from a byte stream and convert to an Int.
-
-showB :: (Native a) => a -> Bytes -- Simple interface to showBytes.
-readB :: (Native a) => Bytes -> a -- Simple interface to readBytes.
-\end{verbatim}
-
-\item[\tr{Number}:]
-\index{Number module (HBC library)}%
-Simple numbers that belong to all numeric classes and behave like
-a naive user would expect (except that printing is still ugly).
-(NB: GHC does not provide a magic way to use \tr{Numbers} everywhere,
-but you should be able to do it with normal \tr{import}ing and
-\tr{default}ing.)
-\begin{verbatim}
-data Number -- The type itself.
-instance ... -- All reasonable instances.
-isInteger :: Number -> Bool -- Test if a Number is an integer.
-\end{verbatim}
-\end{description}
+++ /dev/null
-%************************************************************************
-%* *
-\section[ticky-ticky]{Using ``ticky-ticky'' profiling (for implementors)}
-\index{ticky-ticky profiling (implementors)}
-%* *
-%************************************************************************
-
-(ToDo: document properly.)
-
-It is possible to compile Glasgow Haskell programs so that they will
-count lots and lots of interesting things, e.g., number of updates,
-number of data constructors entered, etc., etc. We call this
-``ticky-ticky'' profiling,\index{ticky-ticky profiling}%
-\index{profiling, ticky-ticky} because that's the sound a Sun4 makes
-when it is running up all those counters ({\em slowly}).
-
-Ticky-ticky profiling is mainly intended for implementors; it is quite
-separate from the main ``cost-centre'' profiling system, intended for
-all users everywhere.
-
-To be able to use ticky-ticky profiling, you will need to have built
-appropriate libraries and things when you made the system. See
-``Customising what libraries to build,'' in the installation guide.
-
-To get your compiled program to spit out the ticky-ticky numbers, use
-a \tr{-r} RTS option\index{-r RTS option}.
+++ /dev/null
-%
-% $Header: /srv/cvs/cvs.haskell.org/fptools/ghc/docs/users_guide/Attic/tutorial.lit,v 1.1 1996/01/08 20:25:11 partain Exp $
-%
-\section[compiler-tutorial]{Tutorial material about this compilation system}
-
-This guide assumes quite a bit of knowledge about UNIX compilers and
-their conventional use. This section has a little extra information
-for those who are new at this racket.
-
-%************************************************************************
-%* *
-\subsection[batch-system-parts]{The (batch) compilation system components}
-%* *
-%************************************************************************
-
-The Glorious Haskell Compilation System, as with most UNIX (batch)
-compilation systems, has several interacting parts:
-\begin{enumerate}
-\item
-A {\em driver}\index{driver program} \tr{ghc}\index{ghc}---which you
-usually think of as ``the compiler''---is a program that merely
-invokes/glues-together the other pieces of the system (listed below),
-passing the right options to each, slurping in the right libraries,
-etc.
-
-\item
-A {\em literate pre-processor}
-\index{literate pre-processor}
-\index{pre-processor, literate}
-\tr{unlit}\index{unlit} that extracts Haskell
-code from a literate script; used if you believe in that sort of
-thing.
-
-\item
-The {\em Haskellised C pre-processor}
-\index{Haskellised C pre-processor}
-\index{C pre-processor, Haskellised}
-\index{pre-processor, Haskellised C}
-\tr{hscpp},\index{hscpp} only needed by people requiring conditional
-compilation, probably for large systems. The ``Haskellised'' part
-just means that \tr{#line} directives in the output have been
-converted into proper Haskell \tr{{-# LINE ... -}} pragmas.
-
-You must give an explicit \tr{-cpp} option
-\index{-cpp option} for the C pre-processor to be invoked.
-
-\item
-The {\em Haskell compiler}
-\index{Haskell compiler}
-\index{compiler, Haskell}
-\tr{hsc},\index{hsc}
-which---in normal use---takes its input from the C pre-processor
-and produces assembly-language output (sometimes: ANSI C output).
-
-\item
-The {\em ANSI~C Haskell high-level assembler :-)}
-\index{ANSI C compiler}
-\index{high-level assembler}
-\index{assembler, high-level}
-compiles \tr{hsc}'s C output into assembly language for a particular
-target architecture. (It doesn't have to be an ANSI C compiler, but
-that's preferred; to go fastest, you need GNU C, version 2.x.)
-
-\item
-The {\em assembler}\index{assembler}---a standard UNIX one, probably
-\tr{as}\index{as}.
-
-\item
-The {\em linker}\index{linker}---a standard UNIX one, probably
-\tr{ld}.\index{ld}
-
-\item
-A {\em runtime system},\index{runtime system} including (most notably)
-a storage manager; the linker links in the code for this.
-
-\item
-The {\em Haskell standard prelude}\index{standard prelude}, a
-large library of standard functions, is linked in as well.
-
-\item
-Parts of other {\em installed libraries} that you have at your site
-may be linked in also.
-\end{enumerate}
-
-%************************************************************************
-%* *
-\subsection[compile-what-really-happens]{What really happens when I ``compile'' a Haskell program?}
-%* *
-%************************************************************************
-
-You invoke the Glasgow Haskell compilation system through the
-driver program \tr{ghc}.\index{ghc} For example, if you had typed a
-literate ``Hello, world!'' program into \tr{hello.lhs}, and you then
-invoked:
-\begin{verbatim}
-ghc hello.lhs
-\end{verbatim}
-
-the following would happen:
-\begin{enumerate}
-\item
-The file \tr{hello.lhs} is run through the literate-program
-code extractor \tr{unlit}\index{unlit}, feeding its output to
-
-\item
-The Haskell compiler proper \tr{hsc}\index{hsc}, which produces
-input for
-
-\item
-The assembler (or that ubiquitous ``high-level assembler,'' a C
-compiler), which produces an object file and passes it to
-
-\item
-The linker, which links your code with the appropriate libraries
-(including the standard prelude), producing an executable program in
-the default output file named \tr{a.out}.
-\end{enumerate}
-
-You have considerable control over the compilation process. You feed
-command-line arguments (call them ``options,'' for short) to the
-driver, \tr{ghc}; the ``types'' of the input files (as encoded in
-their names' suffixes) also matter.
-
-Here's hoping this is enough background so that you can read the rest
-of this guide!
-
-% The ``style'' of the driver program \tr{ghc} follows that of the GNU C
-% compiler driver \tr{gcc}. The use of environment variables to provide
-% defaults is more extensive in this compilation system.
+++ /dev/null
-\begin{onlystandalone}
-\documentstyle[11pt,literate]{article}
-\begin{document}
-\title{The Glorious Glasgow Haskell Compilation System\\ Version~2.04\\ User's Guide}
-\author{The GHC Team\\
-Department of Computing Science\\
-University of Glasgow\\
-Glasgow, Scotland\\
-G12 8QQ\\
-\\
-Email: glasgow-haskell-\{bugs,users\}-request\@dcs.gla.ac.uk}
-\maketitle
-\begin{rawlatex}
-\tableofcontents
-\pagebreak
-\end{rawlatex}
-\end{onlystandalone}
-
-\input{intro.lit}
-\input{release.lit}
-\input{how_to_run.lit}
-\input{runtime_control.lit}
-\input{sooner.lit}
-\input{profiling.lit}
-\input{glasgow_exts.lit}
-\input{libraries.lit}
-\input{syslib.lit}
-\input{parallel.lit}
-\input{gone_wrong.lit}
-\input{backwards.lit}
-\input{vs_haskell.lit}
-\input{recomp.lit}
-\input{utils.lit}
-\input{ticky.lit}
-\input{tutorial.lit}
-
-\begin{onlystandalone}
-\printindex
-\end{document}
-\end{onlystandalone}
--- /dev/null
+<!doctype linuxdoc system>
+<article>
+
+<title>The Glasgow Haskell Compiler User's Guide, Version~3.00
+<author>The GHC Team,
+Department of Computing Science,
+University of Glasgow,
+Glasgow, Scotland,
+G12 8QQ
+
+Email: @glasgow-haskell-{bugs,users}-request@@dcs.gla.ac.uk@
+
+<toc>
--- /dev/null
+<sect> Using GHC
+<label id="using-GHC">
+<p>
+<nidx>GHC, using</nidx>
+<nidx>using GHC</nidx>
+
+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 @make@ 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.
+
+%************************************************************************
+%* *
+<sect1> Overall command-line structure
+<label id="command-line-structure">
+<p>
+<nidx>structure, command-line</nidx>
+<nidx>command-line structure</nidx>
+%* *
+%************************************************************************
+
+An invocation of GHC takes the following form:
+
+<tscreen> <verb>
+ghc [argument...]
+</verb> </tscreen>
+
+Command-line arguments are either options or file names.
+
+Command-line options begin with @-@. They may <em>not</em> be
+grouped: @-vO@ is different from @-v -O@. Options need not
+precede filenames: e.g., @ghc *.o -o foo@. All options are
+processed and then applied to all files; you cannot, for example, invoke
+@ghc -c -O1 Foo.hs -O2 Bar.hs@ to apply different optimisation
+levels to the files @Foo.hs@ and @Bar.hs@. For conflicting
+options, e.g., @-c -S@, we reserve the right to do anything we
+want. (Usually, the last one applies.)
+
+%************************************************************************
+%* *
+<sect1>Meaningful file suffixes
+<label id="file-suffixes">
+<p>
+<nidx>suffixes, file</nidx>
+<nidx>file suffixes for GHC</nidx>
+%* *
+%************************************************************************
+
+File names with ``meaningful'' suffixes (e.g., @.lhs@ or @.o@)
+cause the ``right thing'' to happen to those files.
+
+<descrip>
+<tag>@.lhs@:</tag>
+<nidx>lhs suffix</nidx>
+A ``literate Haskell'' module.
+
+<tag>@.hs@:</tag>
+A not-so-literate Haskell module.
+
+<tag>@.hi@:</tag>
+A Haskell interface file, probably compiler-generated.
+
+<tag>@.hc@:</tag>
+Intermediate C file produced by the Haskell compiler.
+
+<tag>@.c@:</tag>
+A C~file not produced by the Haskell compiler.
+
+% <tag>@.i@:</tag>
+% C code after it has be preprocessed by the C compiler (using the
+% @-E@ flag).
+
+<tag>@.s@:</tag>
+An assembly-language source file, usually
+produced by the compiler.
+
+<tag>@.o@:</tag>
+An object file, produced by an assembler.
+</descrip>
+
+Files with other suffixes (or without suffixes) are passed straight
+to the linker.
+
+%************************************************************************
+%* *
+<sect1>Help and verbosity options
+<label id="options-help">
+<p>
+<nidx>help options (GHC)</nidx>
+<nidx>verbose option (GHC)</nidx>
+%* *
+%************************************************************************
+
+A good option to start with is the @-help@ (or @-?@) option.
+<nidx>-help option</nidx>
+<nidx>-? option</nidx>
+GHC spews a long message to standard output and then exits.
+
+The @-v@<nidx>-v option</nidx> option makes GHC <em>verbose</em>: it
+reports its version number and shows (on stderr) exactly how it invokes each
+phase of the compilation system. Moreover, it passes
+the @-v@ flag to most phases; each reports
+its version number (and possibly some other information).
+
+Please, oh please, use the @-v@ option when reporting bugs!
+Knowing that you ran the right bits in the right order is always the
+first thing we want to verify.
+
+If you're just interested in the compiler version number, the
+@--version@<nidx>--version option</nidx> option prints out a
+one-line string containing the requested info.
+
+%************************************************************************
+%* *
+<sect1>Running the right phases in the right order
+<label id="options-order">
+<p>
+<nidx>order of passes in GHC</nidx>
+<nidx>pass ordering in GHC</nidx>
+%* *
+%************************************************************************
+
+The basic task of the @ghc@ driver is to run each input file
+through the right phases (parsing, linking, etc.).
+
+The first phase to run is determined by the input-file suffix, and the
+last phase is determined by a flag. If no relevant flag is present,
+then go all the way through linking. This table summarises:
+
+<tabular ca="llll">
+Phase of the | Suffix saying | Flag saying | (suffix of) @@
+compilation system | ``start here''| ``stop after''| output file @@
+@@
+literate pre-processor | .lhs | - | - @@
+C pre-processor (opt.) | - | - | - @@
+Haskell compiler | .hs | -C, -S | .hc, .s @@
+C compiler (opt.) | .hc or .c | -S | .s @@
+assembler | .s | -c | .o @@
+linker | other | - | a.out @@
+</tabular>
+<nidx>-C option</nidx>
+<nidx>-S option</nidx>
+<nidx>-c option</nidx>
+
+Thus, a common invocation would be: @ghc -c Foo.hs@
+
+Note: What the Haskell compiler proper produces depends on whether a
+native-code generator is used (producing assembly language) or not
+(producing C).
+
+The option @-cpp@<nidx>-cpp option</nidx> 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.
+
+The option @-E@<nidx>-E option</nidx> 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 @-cpp@, the
+output is the de-litted version of the original source.
+
+The option @-optcpp-E@<nidx>-optcpp-E option</nidx> runs just the
+pre-processing stage of the C-compiling phase, sending the result to
+stdout. (For debugging or obfuscation contests, usually.)
+
+%************************************************************************
+%* *
+<sect1>Re-directing the compilation output(s)
+<label id="options-output">
+<p>
+<nidx>output-directing options</nidx>
+%* *
+%************************************************************************
+
+GHC's compiled output normally goes into a @.hc@, @.o@, etc., file,
+depending on the last-run compilation phase. The option @-o
+foo@<nidx>-o option</nidx> re-directs the output of that last-run
+phase to file @foo@.
+
+Note: this ``feature'' can be counterintuitive:
+@ghc -C -o foo.o foo.hs@ will put the intermediate C code in the
+file @foo.o@, name notwithstanding!
+
+EXOTICA: But the @-o@ option isn't of much use if you have
+<em>several</em> 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 @-odir <dir>@<nidx>-odir <dir> option</nidx> (the
+``Oh, dear'' option). For example:
+
+<tscreen><verb>
+% ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
+</verb></tscreen>
+
+The output files, @Foo.o@, @Bar.o@, and @Bumble.o@ would be
+put into a subdirectory named after the architecture of the executing
+machine (@sun4@, @mips@, etc). The directory must already
+exist; it won't be created.
+
+Note that the @-odir@ option does <em>not</em> affect where the
+interface files are put. In the above example, they would still be
+put in @parse/Foo.hi@, @parse/Bar.hi@, and @gurgle/Bumble.hi@.
+
+MORE EXOTICA: The @-osuf <suffix>@<nidx>-osuf <suffix>
+option</nidx> will change the @.o@ file suffix for object files to
+whatever you specify. (We use this in compiling the prelude.).
+Similarly, the @-hisuf <suffix>@<nidx>-hisuf <suffix>
+option</nidx> will change the @.hi@ file suffix for non-system
+interface files (see Section <ref name="Other options related to
+interface files" id="hi-options">).
+
+The @-hisuf@/@-osuf@ 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 @.hi@/@.o@ suffixes; add @-hisuf g_hi -osuf g_o@ to your
+@make@ rule for GHC compiling...
+
+FURTHER EXOTICA: If you are doing a normal @.hs@-to-@.o@ compilation
+but would like to hang onto the intermediate @.hc@ C file, just
+throw in a @-keep-hc-file-too@ option<nidx>-keep-hc-file-too option</nidx>.
+If you would like to look at the assembler output, toss in a
+@-keep-s-file-too@,<nidx>-keep-s-file-too option</nidx> too.
+
+<sect2> Saving GHC's standard error output
+<label id="saving-ghc-stderr">
+<p>
+<nidx>standard error, saving</nidx>
+
+Sometimes, you may cause GHC to be rather chatty on standard error;
+with @-fshow-import-specs@, for example. You can instruct GHC to
+<em>append</em> this output to a particular log file with a @-odump
+<blah>@<nidx>-odump <blah> option</nidx> option.
+
+<sect2> Redirecting temporary files
+<label id="temp-files">
+<p>
+<nidx>temporary files, redirecting</nidx>
+
+If you have trouble because of running out of space in @/tmp@ (or
+wherever your installation thinks temporary files should go), you may
+use the @-tmpdir <dir>@<nidx>-tmpdir <dir> option</nidx> option
+to specify an alternate directory. For example, @-tmpdir .@ says to
+put temporary files in the current working directory.
+
+Alternatively, use your @TMPDIR@ environment variable.<nidx>TMPDIR
+environment variable</nidx> Set it to the name of the directory where
+temporary files should be put. GCC and other programs will honour the
+@TMPDIR@ variable as well.
+
+Even better idea: Set the @TMPDIR@ variable when building GHC, and
+never worry about @TMPDIR@ again. (see the build documentation).
+
+%************************************************************************
+%* *
+<sect1>Warnings and sanity-checking
+<label id="options-sanity">
+<p>
+<nidx>sanity-checking options</nidx>
+<nidx>warnings</nidx>
+%* *
+%************************************************************************
+
+GHC has a number of options that select which types of non-fatal error
+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:
+@-fwarn-overlpapping-patterns@, @-fwarn-duplicate-exports@, and
+@-fwarn-missing-methods@. The following flags are simple ways to
+select standard ``packages'' of warnings:
+
+<descrip>
+
+<tag>@-Wnot@:</tag>
+<nidx>-Wnot option</nidx>
+
+Turns off all warnings, including the standard ones.
+
+<tag>@-w@:</tag>
+<nidx>-w option</nidx>
+
+Synonym for @-Wnot@.
+
+<tag>@-W@:</tag>
+<nidx>-W option</nidx>
+
+Provides the standard warnings plus @-fwarn-incomplete-patterns@
+and @-fwarn-unused-names@.
+
+<tag>@-Wall@:</tag>
+<nidx>-Wall option</nidx>
+
+Turns on all warning options.
+
+</descrip>
+
+The full set of warning options is described below. To turn off any
+warning, simply give the corresponding @-fno-warn-...@ option on
+the command line.
+
+<descrip>
+
+<tag>@-fwarn-name-shadowing@:</tag>
+<nidx>-fwarn-name-shadowing option</nidx>
+<nidx>shadowing, warning</nidx>
+
+This option causes a warning to be emitted whenever an inner-scope
+value has the same name as an outer-scope value, i.e. the inner value
+shadows the outer one. This can catch typographical errors that turn
+into hard-to-find bugs, e.g., in the inadvertent cyclic definition
+@let x = ... x ... in@.
+
+Consequently, this option does <em>not</em> allow cyclic recursive
+definitions.
+
+<tag>@-fwarn-overlapping-patterns@:</tag>
+<nidx>-fwarn-overlapping-patterns option</nidx>
+<nidx>overlapping patterns, warning</nidx>
+<nidx>patterns, overlapping</nidx>
+
+By default, the compiler will warn you if a set of patterns are either
+incomplete (i.e., you're only matching on a subset of an algebraic
+data type's constructors), or overlapping, i.e.,
+
+<tscreen><verb>
+f :: String -> Int
+f [] = 0
+f (_:xs) = 1
+f "2" = 2
+
+g [] = 2
+</verb></tscreen>
+
+where the last pattern match in @f@ 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.
+
+<tag>@-fwarn-incomplete-patterns@:</tag>
+<nidx>-fwarn-incomplete-patterns option</nidx>
+<nidx>incomplete patterns, warning</nidx>
+<nidx>patterns, incomplete</nidx>
+
+Similarly for incomplete patterns, the function @g@ will fail when
+applied to non-empty lists, so the compiler will emit a warning about
+this when this option is enabled.
+
+<tag>@-fwarn-missing-methods@:</tag>
+<nidx>-fwarn-missing-methods option</nidx>
+<nidx>missing methods, warning</nidx>
+<nidx>methods, missing</nidx>
+
+This option is on by default, and warns you whenever an instance
+declaration is missing one or more methods, and the corresponding
+class declaration has no default declaration for them.
+
+<tag>@-fwarn-unused-names@:</tag>
+<nidx>-fwarn-unused-names option</nidx>
+<nidx>unused names, warning</nidx>
+<nidx>names, unused</nidx>
+
+Have the renamer report which locally defined names are not used/exported.
+
+<tag>@-fwarn-duplicate-exports@:</tag>
+<nidx>-fwarn-duplicate-exports option</nidx>
+<nidx>duplicate exports, warning</nidx>
+<nidx>export lists, duplicates</nidx>
+
+Have the compiler warn about duplicate entries in export lists. This
+is useful information if you maintain large export lists, and want to
+avoid the continued export of a definition after you've deleted (one)
+mention of it in the export list.
+
+This option is on by default.
+
+</descrip>
+
+If you would like GHC to check that every top-level value has a type
+signature, use the @-fsignatures-required@
+option.<nidx>-fsignatures-required option</nidx>
+
+If you're feeling really paranoid, the @-dcore-lint@
+option<nidx>-dcore-lint option</nidx> is a good choice. It turns on
+heavyweight intra-pass sanity-checking within GHC. (It checks GHC's
+sanity, not yours.)
+
+%************************************************************************
+%* *
+<sect1>Separate compilation
+<label id="separate-compilation">
+<p>
+<nidx>separate compilation</nidx>
+<nidx>recompilation checker</nidx>
+<nidx>make and recompilation</nidx>
+%* *
+%************************************************************************
+
+This section describes how GHC supports separate compilation.
+
+<sect2>Interface files
+<label id="hi-files">
+<p>
+<nidx>interface files</nidx>
+<nidx>.hi files</nidx>
+
+When GHC compiles a source file @F@ which contains a module @A@, say,
+it generates an object @F.o@, <em>and</em> a companion <em>interface
+file</em> @A.hi@.
+
+NOTE: Having the name of the interface file follow the module name and
+not the file name, means that working with tools such as @make(1)@
+become harder. @make@ 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
+recommend you stick to using the same file name as the module name.
+
+The interface file for @A@ contains information needed by the compiler
+when it compiles any module @B@ that imports @A@, whether directly or
+indirectly. When compiling @B@, GHC will read @A.hi@ to find the
+details that it needs to know about things defined in @A@.
+
+Furthermore, when compiling module @C@ which imports @B@, GHC may
+decide that it needs to know something about @A@ --- for example, @B@
+might export a function that involves a type defined in @A@. In this
+case, GHC will go and read @A.hi@ even though @C@ does not explicitly
+import @A@ at all.
+
+The interface file may contain all sorts of things that aren't
+explicitly exported from @A@ by the programmer. For example, even
+though a data type is exported abstractly, @A.hi@ will contain the
+full data type definition. For small function definitions, @A.hi@
+will contain the complete definition of the function. For bigger
+functions, @A.hi@ will contain strictness information about the
+function. And so on. GHC puts much more information into @.hi@ files
+when optimisation is turned on with the @-O@ flag. Without @-O@ it
+puts in just the minimum; with @-O@ it lobs in a whole pile of stuff.
+<nidx>optimsation, effect on .hi files</nidx>
+
+@A.hi@ should really be thought of as a compiler-readable version of
+@A.o@. If you use a @.hi@ file that wasn't generated by the same
+compilation run that generates the @.o@ file the compiler may assume
+all sorts of incorrect things about @A@, resulting in core dumps and
+other unpleasant happenings.
+
+%************************************************************************
+%* *
+<sect2>Finding interface files
+<label id="options-finding-imports">
+<p>
+<nidx>interface files, finding them</nidx>
+<nidx>finding interface files</nidx>
+%* *
+%************************************************************************
+
+In your program, you import a module @Foo@ by saying
+@import Foo@. GHC goes looking for an interface file, @Foo.hi@.
+It has a builtin list of directories (notably including @.@) where
+it looks.
+
+The @-i<dirs>@ option<nidx>-i<dirs> option</nidx> prepends a
+colon-separated list of @dirs@ to the ``import directories'' list.
+
+A plain @-i@ resets the ``import directories'' list back to nothing.
+
+GHC normally imports @Prelude.hi@ files for you. If you'd rather
+it didn't, then give it a @-fno-implicit-prelude@
+option<nidx>-fno-implicit-prelude option</nidx>. You are unlikely to get
+very far without a Prelude, but, hey, it's a free country.
+
+If you are using a system-supplied non-Prelude library (e.g., the HBC
+library), just use a @-syslib hbc@<nidx>-syslib <lib> option</nidx>
+option (for example). The right interface files should then be
+available.
+
+Once a Haskell module has been compiled to C (@.hc@ file), you may
+wish to specify where GHC tells the C compiler to look for @.h@
+files. (Or, if you are using the @-cpp@ option<nidx>-cpp option</nidx>,
+where it tells the C pre-processor to look...) For this purpose, use
+a @-I<dir>@<nidx>-I<dir> option</nidx> in the usual C-ish way.
+
+%************************************************************************
+%* *
+<sect2>Other options related to interface files
+<label id="hi-options">
+<p>
+<nidx>interface files, options</nidx>
+%* *
+%************************************************************************
+
+The interface output may be directed to another file
+@bar2/Wurble.iface@ with the option @-ohi bar2/Wurble.iface@<nidx>-ohi
+<file> option</nidx> (not recommended).
+
+To avoid generating an interface file at all, use a @-nohi@
+option.<nidx>-nohi option</nidx>
+
+The compiler does not overwrite an existing @.hi@ interface file if
+the new one is byte-for-byte the same as the old one; this is friendly
+to @make@. When an interface does change, it is often enlightening to
+be informed. The @-hi-diffs@<nidx>-hi-diffs option</nidx> option will
+make @ghc@ run @diff@ on the old and new @.hi@ files. You can also
+record the difference in the interface file itself, the
+@-keep-hi-diffs@<nidx>-keep-hi-diffs</nidx> option takes care of that.
+
+The @.hi@ 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
+@-hi-diffs-with-usages@<nidx>-hi-diffs-with-usages option</nidx>
+option.
+
+Interface files are normally jammed full of compiler-produced
+<em>pragmas</em>, 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
+@-fignore-interface-pragmas@<nidx>-fignore-interface-pragmas
+option</nidx> option.
+
+When compiling without optimisations on, the compiler is extra-careful
+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 @-fno-prune-tydecls@ and @-fno-prune-instdecls@.
+<nidx>-fno-prune-tydecls option</nidx><nidx>-fno-prune-instdecls
+option</nidx>
+
+See also Section <ref name="Linking and consistency-checking" id="options-linker">, which describes how the linker
+finds standard Haskell libraries.
+
+%************************************************************************
+%* *
+<sect2>The recompilation checker
+<label id="recomp">
+<p>
+<nidx>recompilation checker</nidx>
+%* *
+%************************************************************************
+
+In the olden days, GHC compared the newly-generated @.hi@ 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 @.hi@ file were not
+recompiled.
+
+This doesn't work any more. In our earlier example, module @C@ does
+not import module @A@ directly, yet changes to @A.hi@ should force a
+recompilation of @C@. And some changes to @A@ (changing the
+definition of a function that appears in an inlining of a function
+exported by @B@, say) may conceivably not change @B.hi@ one jot. So
+now...
+
+GHC keeps a version number on each interface file, and on each type
+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 @.o@ file's date (i.e. the source hasn't changed since the
+file was last compiled), and you give GHC the @-recomp@<nidx>-recomp
+option</nidx> flag, then GHC will be clever. It compares the version
+numbers on the things it needs this time with the version numbers on
+the things it needed last time (gleaned from the interface file of the
+module being compiled); if they are all the same it stops compiling
+rather early in the process saying ``Compilation IS NOT required''.
+What a beautiful sight!
+
+It's still an experimental feature (that's why @-recomp@ is off by
+default), so tell us if you think it doesn't work.
+
+Patrick Sansom has a workshop paper about how all this is done. Ask
+him (email: <htmlurl name="sansom@@dcs.gla.ac.uk"
+url="mailto:sansom@@dcs.gla.ac.uk">) if you want a copy.
+
+%************************************************************************
+%* *
+<sect2>Using @make@
+<label id="using-make">
+<p>
+<ncdx>make</ncdx>
+%* *
+%************************************************************************
+
+It is reasonably straightforward to set up a @Makefile@ to use with
+GHC, assuming you name your source files the same as your modules.
+Thus:
+
+<tscreen><verb>
+HC = ghc
+HC_OPTS = -cpp $(EXTRA_HC_OPTS)
+
+SRCS = Main.lhs Foo.lhs Bar.lhs
+OBJS = Main.o Foo.o Bar.o
+
+.SUFFIXES : .o .hi .lhs .hc .s
+
+cool_pgm : $(OBJS)
+ rm $@
+ $(HC) -o $@ $(HC_OPTS) $(OBJS)
+
+# Standard suffix rules
+.o.hi:
+ @:
+
+.lhs.o:
+ $(HC) -c $< $(HC_OPTS)
+
+.hs.o:
+ $(HC) -c $< $(HC_OPTS)
+
+# Inter-module dependencies
+Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
+Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz
+</verb></tscreen>
+
+(Sophisticated @make@ variants may achieve some of the above more
+elegantly. Notably, @gmake@'s pattern rules let you write the more
+comprehensible:
+
+<tscreen><verb>
+%.o : %.lhs
+ $(HC) -c $< $(HC_OPTS)
+</verb></tscreen>
+
+What we've shown should work with any @make@.)
+
+Note the cheesy @.o.hi@ rule: It records the dependency of the
+interface (@.hi@) file on the source. The rule says a @.hi@ file can
+be made from a @.o@ file by doing... nothing. Which is true.
+
+Note the inter-module dependencies at the end of the Makefile, which
+take the form
+
+<tscreen><verb>
+Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
+</verb></tscreen>
+
+They tell @make@ that if any of @Foo.o@, @Foo.hc@ or @Foo.s@ have an
+earlier modification date than @Baz.hi@, then the out-of-date file
+must be brought up to date. To bring it up to date, @make@ looks for
+a rule to do so; one of the preceding suffix rules does the job
+nicely.
+
+Putting inter-dependencies of the form @Foo.o : Bar.hi@ into your
+@Makefile@ by hand is rather error-prone. Don't worry---never fear,
+@mkdependHS@ is here! (and is distributed as part of GHC) Add the
+following to your @Makefile@:
+
+<tscreen><verb>
+depend :
+ mkdependHS -- $(HC_OPTS) -- $(SRCS)
+</verb></tscreen>
+
+Now, before you start compiling, and any time you change the @imports@
+in your program, do @make depend@ before you do @make cool_pgm@.
+@mkdependHS@ will append the needed dependencies to your @Makefile@.
+@mkdependHS@ is fully describe in Section <ref name="Makefile
+dependencies in Haskell: using mkdependHS" id="mkdependHS">.
+
+A few caveats about this simple scheme:
+
+<itemize>
+
+<item> You may need to compile some modules explicitly to create their
+interfaces in the first place (e.g., @make Bar.o@ to create @Bar.hi@).
+
+<item> You may have to type @make@ more than once for the dependencies
+to have full effect. However, a @make@ run that does nothing
+<em>does</em> mean ``everything's up-to-date.''
+
+<item> This scheme will work with mutually-recursive modules but,
+again, it may take multiple iterations to ``settle.''
+
+</itemize>
+
+%************************************************************************
+%* *
+<sect1>Optimisation (code improvement)
+<label id="options-optimise">
+<p>
+<nidx>optimisation (GHC)</nidx>
+<nidx>improvement, code (GHC)</nidx>
+%* *
+%************************************************************************
+
+The @-O*@ options specify convenient ``packages'' of optimisation
+flags; the @-f*@ options described later on specify
+<em>individual</em> optimisations to be turned on/off; the @-m*@
+options specify <em>machine-specific</em> optimisations to be turned
+on/off.
+
+%----------------------------------------------------------------------
+<sect2>@-O*@: convenient ``packages'' of optimisation flags.
+<label id="optimise-pkgs">
+<p>
+<nidx>-O options</nidx>
+
+There are <em>many</em> options that affect the quality of code
+produced by GHC. Most people only have a general goal, something like
+``Compile quickly'' or ``Make my program run like greased lightning.''
+The following ``packages'' of optimisations (or lack thereof) should
+suffice.
+
+Once you choose a @-O*@ ``package,'' stick with it---don't chop and
+change. Modules' interfaces <em>will</em> change with a shift to a new
+@-O*@ option, and you may have to recompile a large chunk of all
+importing modules before your program can again be run
+safely (see Section <ref name="The recompilation checker" id="recomp">).
+
+<descrip>
+<tag>No @-O*@-type option specified:</tag>
+<nidx>-O* not specified</nidx>
+This is taken to mean: ``Please compile quickly; I'm not over-bothered
+about compiled-code quality.'' So, for example: @ghc -c Foo.hs@
+
+<tag>@-O@ or @-O1@:</tag>
+<nidx>-O option</nidx>
+<nidx>-O1 option</nidx>
+<nidx>optimise normally</nidx>
+Means: ``Generate good-quality code without taking too long about it.''
+Thus, for example: @ghc -c -O Main.lhs@
+
+<tag>@-O2@:</tag>
+<nidx>-O2 option</nidx>
+<nidx>optimise aggressively</nidx>
+Means: ``Apply every non-dangerous optimisation, even if it means
+significantly longer compile times.''
+
+The avoided ``dangerous'' optimisations are those that can make
+runtime or space <em>worse</em> if you're unlucky. They are
+normally turned on or off individually.
+
+At the moment, @-O2@ is <em>unlikely</em> to produce
+better code than @-O@.
+
+<tag>@-O2-for-C@:</tag>
+<nidx>-O2-for-C option</nidx>
+<nidx>gcc, invoking with -O2</nidx>
+
+Says to run GCC with @-O2@, which may be worth a few percent in
+execution speed. Don't forget @-fvia-C@, lest you use the native-code
+generator and bypass GCC altogether!
+
+<tag>@-Onot@:</tag>
+<nidx>-Onot option</nidx>
+<nidx>optimising, reset</nidx>
+
+This option will make GHC ``forget'' any -Oish options it has seen so
+far. Sometimes useful; for example: @make all EXTRA_HC_OPTS=-Onot@.
+
+<tag>@-Ofile <file>@:</tag>
+<nidx>-Ofile <file> option</nidx>
+<nidx>optimising, customised</nidx>
+
+For those who need <em>absolute</em> control over <em>exactly</em>
+what options are used (e.g., compiler writers, sometimes :-), a list
+of options can be put in a file and then slurped in with @-Ofile@.
+
+In that file, comments are of the @#@-to-end-of-line variety; blank
+lines and most whitespace is ignored.
+
+Please ask if you are baffled and would like an example of @-Ofile@!
+</descrip>
+
+At Glasgow, we don't use a @-O*@ flag for day-to-day work. We use
+@-O@ to get respectable speed; e.g., when we want to measure
+something. When we want to go for broke, we tend to use @-O -fvia-C
+-O2-for-C@ (and we go for lots of coffee breaks).
+
+The easiest way to see what @-O@ (etc) ``really mean'' is to run with
+@-v@, then stand back in amazement. Alternatively, just look at the
+@HsC_minus<blah>@ lists in the @ghc@ driver script.
+
+%----------------------------------------------------------------------
+<sect2>@-f*@: platform-independent flags
+<p>
+<nidx>-f* options (GHC)</nidx>
+<nidx>-fno-* options (GHC)</nidx>
+
+Flags can be turned <em>off</em> individually. (NB: I hope you have a
+good reason for doing this....) To turn off the @-ffoo@ flag, just use
+the @-fno-foo@ flag.<nidx>-fno-<opt> anti-option</nidx> So, for
+example, you can say @-O2 -fno-strictness@, which will then drop out
+any running of the strictness analyser.
+
+The options you are most likely to want to turn off are:
+@-fno-strictness@<nidx>-fno-strictness option</nidx> (strictness
+analyser [because it is sometimes slow]),
+@-fno-specialise@<nidx>-fno-specialise option</nidx> (automatic
+specialisation of overloaded functions [because it makes your code
+bigger]) [US spelling also accepted], and
+@-fno-update-analyser@<nidx>-fno-update-analyser option</nidx>
+(update analyser, because it sometimes takes a <em>long</em> time).
+
+Should you wish to turn individual flags <em>on</em>, you are advised
+to use the @-Ofile@ 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.
+
+Here are some ``dangerous'' optimisations you <em>might</em> want to try:
+<descrip>
+%------------------------------------------------------------------
+<tag>@-fvia-C@:</tag>
+<nidx>-fvia-C option</nidx>
+<nidx>native code generator, turning off</nidx>
+
+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 @_ccall_gc_@s or
+@_casm_@s, you probably <em>have to</em> use @-fvia-C@.
+
+The lower-case incantation, @-fvia-c@, is synonymous.
+
+<tag>@-funfolding-creation-threshold<n>@:</tag>
+<nidx>-funfolding-creation-threshold option</nidx>
+<nidx>inlining, controlling</nidx>
+<nidx>unfolding, controlling</nidx>
+(Default: 30) By raising or lowering this number, you can raise or
+lower the amount of pragmatic junk that gets spewed into interface
+files. (An unfolding has a ``size'' that reflects the cost in terms
+of ``code bloat'' of expanding that unfolding in another module. A
+bigger Core expression would be assigned a bigger cost.)
+
+<tag>@-funfolding-use-threshold<n>@:</tag>
+<nidx>-funfolding-use-threshold option</nidx>
+<nidx>inlining, controlling</nidx>
+<nidx>unfolding, controlling</nidx>
+(Default: 3) By raising or lowering this number, you can make the
+compiler more or less keen to expand unfoldings.
+
+OK, folks, these magic numbers `30' and `3' are mildly arbitrary; they
+are of the ``seem to be OK'' variety. The `3' is the more critical
+one; it's what determines how eager GHC is about expanding unfoldings.
+
+% <tag>@-funfolding-override-threshold<n>@:</tag>
+% (Default: 8) [Pretty obscure]
+W hen deciding what unfoldings from a module should be made available
+% to the rest of the world (via this module's interface), the compiler
+% normally likes ``small'' expressions.
+
+% For example, if it sees @foo = bar@, it will decide that the very
+% small expression @bar@ is a great unfolding for @foo@. But if
+% @bar@ turns out to be @(True,False,True)@, we would probably
+% prefer <em>that</em> for the unfolding for @foo@.
+
+% Should we ``override'' the initial small unfolding from @foo=bar@
+% with the bigger-but-better one? Yes, if the bigger one's ``size'' is
+% still under the ``override threshold.'' You can use this flag to
+% adjust this threshold (why, I'm not sure).
+
+% <tag>@-fliberated-case-threshold<n>@:</tag>
+% (Default: 12) [Vastly obscure: NOT IMPLEMENTED YET]
+% ``Case liberation'' lifts evaluation out of recursive functions; it
+% does this by duplicating code. Done without constraint, you can get
+% serious code bloat; so we only do it if the ``size'' of the duplicated
+% code is smaller than some ``threshold.'' This flag can fiddle that
+% threshold.
+
+<tag>@-fsemi-tagging@:</tag>
+This option (which <em>does not work</em> with the native-code generator)
+tells the compiler to add extra code to test for already-evaluated
+values. You win if you have lots of such values during a run of your
+program, you lose otherwise. (And you pay in extra code space.)
+
+We have not played with @-fsemi-tagging@ enough to recommend it.
+(For all we know, it doesn't even work anymore... Sigh.)
+</descrip>
+
+%----------------------------------------------------------------------
+<sect2>@-m*@: platform-specific flags
+<p>
+<nidx>-m* options (GHC)</nidx>
+<nidx>platform-specific options</nidx>
+<nidx>machine-specific options</nidx>
+
+Some flags only make sense for particular target platforms.
+
+<descrip>
+<tag>@-mv8@:</tag>
+(SPARC machines)<nidx>-mv8 option (SPARC only)</nidx>
+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 @-m*@ GCC options for SPARC also work, actually.
+
+<tag>@-mlong-calls@:</tag>
+(HPPA machines)<nidx>-mlong-calls option (HPPA only)</nidx>
+Means to pass the like-named option to GCC. Required for Very Big
+modules, maybe. (Probably means you're in trouble...)
+
+<tag>@-monly-[32]-regs@:</tag>
+(iX86 machines)<nidx>-monly-N-regs option (iX86 only)</nidx>
+GHC tries to ``steal'' four registers from GCC, for performance
+reasons; it almost always works. However, when GCC is compiling some
+modules with four stolen registers, it will crash, probably saying:
+<tscreen><verb>
+Foo.hc:533: fixed or forbidden register was spilled.
+This may be due to a compiler bug or to impossible asm
+statements or clauses.
+</verb></tscreen>
+Just give some registers back with @-monly-N-regs@. Try `3' first,
+then `2'. If `2' doesn't work, please report the bug to us.
+</descrip>
+
+%----------------------------------------------------------------------
+<sect2>Code improvement by the C compiler.
+<label id="optimise-C-compiler">
+<p>
+<nidx>optimisation by GCC</nidx>
+<nidx>GCC optimisation</nidx>
+
+The C~compiler (GCC) is run with @-O@ turned on. (It has
+to be, actually).
+
+If you want to run GCC with @-O2@---which may be worth a few
+percent in execution speed---you can give a
+@-O2-for-C@<nidx>-O2-for-C option</nidx> option.
+
+%************************************************************************
+%* *
+<sect1>Options related to a particular phase
+<label id="options-phases">
+<p>
+%* *
+%************************************************************************
+
+<sect2> The C pre-processor
+<label id="c-pre-processor">
+<p>
+<nidx>pre-processing: cpp</nidx>
+<nidx>C pre-processor options</nidx>
+<nidx>cpp, pre-processing with</nidx>
+
+The C pre-processor @cpp@ is run over your Haskell code only if the
+@-cpp@ option <nidx>-cpp option</nidx> is given. Unless you are
+building a large system with significant doses of conditional
+compilation, you really shouldn't need it.
+<descrip>
+<tag>@-D<foo>@:</tag>
+<nidx>-D<name> option</nidx>
+Define macro @<foo>@ in the usual way. NB: does <em>not</em> affect
+@-D@ macros passed to the C~compiler when compiling via C! For
+those, use the @-optc-Dfoo@ hack...
+
+<tag>@-U<foo>@:</tag>
+<nidx>-U<name> option</nidx>
+Undefine macro @<foo>@ in the usual way.
+
+<tag>@-I<dir>@:</tag>
+<nidx>-I<dir> option</nidx>
+Specify a directory in which to look for @#include@ files, in
+the usual C way.
+</descrip>
+
+The @ghc@ driver pre-defines several macros:
+<descrip>
+<tag>@__HASKELL1__@:</tag>
+<nidx>__HASKELL1__ macro</nidx>
+If defined to $n$, that means GHC supports the
+Haskell language defined in the Haskell report version $1.n$.
+Currently 4.
+
+NB: This macro is set both when pre-processing Haskell source and
+when pre-processing generated C (@.hc@) files.
+
+<tag>@__GLASGOW_HASKELL__@:</tag>
+<nidx>__GLASGOW_HASKELL__ macro</nidx>
+For version $n$ of the GHC system, this will be @#define@d to
+$100 \times n$. So, for version~3.00, it is 300.
+
+This macro is <em>only</em> set when pre-processing Haskell source.
+(<em>Not</em> when pre-processing generated C.)
+
+With any luck, @__GLASGOW_HASKELL__@ will be undefined in all other
+implementations that support C-style pre-processing.
+
+(For reference: the comparable symbols for other systems are:
+@__HUGS__@ for Hugs and @__HBC__@ for Chalmers.)
+
+<tag>@__CONCURRENT_HASKELL__@:</tag>
+<nidx>__CONCURRENT_HASKELL__ macro</nidx>
+Only defined when @-concurrent@ is in use!
+This symbol is defined when pre-processing Haskell (input) and
+pre-processing C (GHC output).
+
+<tag>@__PARALLEL_HASKELL__@:</tag>
+<nidx>__PARALLEL_HASKELL__ macro</nidx>
+Only defined when @-parallel@ is in use! This symbol is defined when
+pre-processing Haskell (input) and pre-processing C (GHC output).
+</descrip>
+
+Options other than the above can be forced through to the C
+pre-processor with the @-opt@ flags (see
+Section <ref name="Forcing options to a particular phase." id="forcing-options-through">).
+
+A small word of warning: @-cpp@ is not friendly to ``string
+gaps''.<nidx>-cpp vs string gaps</nidx><nidx>string gaps vs -cpp</nidx>. In
+other words, strings such as the following:
+
+<tscreen><verb>
+ strmod = "\
+ \ p \
+ \ "
+</verb></tscreen>
+
+don't work with @-cpp@; @/usr/bin/cpp@ elides the
+backslash-newline pairs.
+
+However, it appears that if you add a space at the end of the line,
+then @cpp@ (at least GNU @cpp@ and possibly other @cpp@s)
+leaves the backslash-space pairs alone and the string gap works as
+expected.
+
+%************************************************************************
+%* *
+<sect2>Options affecting the C compiler (if applicable)
+<label id="options-C-compiler">
+<p>
+<nidx>include-file options</nidx>
+<nidx>C compiler options</nidx>
+<nidx>GCC options</nidx>
+%* *
+%************************************************************************
+
+At the moment, quite a few common C-compiler options are passed on
+quietly to the C compilation of Haskell-compiler-generated C files.
+THIS MAY CHANGE. Meanwhile, options so sent are:
+
+<tabular ca="ll">
+@-ansi@ | do ANSI C (not K&R) @@
+@-pedantic@ | be so@@
+@-dgcc-lint@ | (hack) short for ``make GCC very paranoid''@@
+</tabular>
+<nidx>-ansi option (for GCC)</nidx>
+<nidx>-pedantic option (for GCC)</nidx>
+<nidx>-dgcc-lint option (GCC paranoia)</nidx>
+
+If you are compiling with lots of @ccalls@, etc., you may need to
+tell the C~compiler about some @#include@ files. There is no real
+pretty way to do this, but you can use this hack from the
+command-line:
+
+<tscreen><verb>
+% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
+</verb></tscreen>
+
+
+%************************************************************************
+%* *
+<sect2>Linking and consistency-checking
+<label id="options-linker">
+<p>
+<nidx>linker options</nidx>
+<nidx>ld options</nidx>
+%* *
+%************************************************************************
+
+GHC has to link your code with various libraries, possibly including:
+user-supplied, GHC-supplied, and system-supplied (@-lm@ math
+library, for example).
+
+<descrip>
+<tag>@-l<FOO>@:</tag>
+<nidx>-l<lib> option</nidx>
+Link in a library named @lib<FOO>.a@ which resides somewhere on the
+library directories path.
+
+Because of the sad state of most UNIX linkers, the order of such
+options does matter. Thus: @ghc -lbar *.o@ is almost certainly
+wrong, because it will search @libbar.a@ <em>before</em> it has
+collected unresolved symbols from the @*.o@ files.
+@ghc *.o -lbar@ is probably better.
+
+The linker will of course be informed about some GHC-supplied
+libraries automatically; these are:
+
+<tabular ca="ll">
+<bf>-l equivalent</bf> | <bf>description</bf> @@
+@@
+@-lHSrts,-lHSclib@ | basic runtime libraries @@
+@-lHS@ | standard Prelude library @@
+@-lHS_cbits@ | C support code for standard Prelude library @@
+@-lgmp@ | GNU multi-precision library (for Integers)@@
+</tabular>
+
+<nidx>-lHS library</nidx>
+<nidx>-lHS_cbits library</nidx>
+<nidx>-lHSrts library</nidx>
+<nidx>-lgmp library</nidx>
+
+<tag>@-syslib <name>@:</tag>
+<nidx>-syslib <name> option</nidx>
+
+If you are using a Haskell ``system library'' (e.g., the POSIX
+library), just use the @-syslib posix@ option, and the correct code
+should be linked in.
+
+<tag>@-L<dir>@:</tag>
+<nidx>-L<dir> option</nidx>
+Where to find user-supplied libraries... Prepend the directory
+@<dir>@ to the library directories path.
+
+<tag>@-static@:</tag>
+<nidx>-static option</nidx>
+Tell the linker to avoid shared libraries.
+
+<tag>@-no-link-chk@ and @-link-chk@:</tag>
+<nidx>-no-link-chk option</nidx>
+<nidx>-link-chk option</nidx>
+<nidx>consistency checking of executables</nidx>
+By default, immediately after linking an executable, GHC verifies that
+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 @.o@ file was compiled
+for a parallel machine and the others weren't.) You may turn off this
+check with @-no-link-chk@. You can turn it (back) on with
+@-link-chk@ (the default).
+</descrip>
+
+%************************************************************************
+%* *
+<sect1>Using Concurrent Haskell
+<p>
+<nidx>Concurrent Haskell---use</nidx>
+%* *
+%************************************************************************
+
+To compile a program as Concurrent Haskell, use the @-concurrent@
+option,<nidx>-concurrent option</nidx> both when compiling <em>and
+linking</em>. You will probably need the @-fglasgow-exts@ option, too.
+
+Three RTS options are provided for modifying the behaviour of the
+threaded runtime system. See the descriptions of @-C[<us>]@, @-q@,
+and @-t<num>@ in Section <ref name="RTS options for Concurrent/Parallel Haskell" id="parallel-rts-opts">.
+
+%************************************************************************
+%* *
+<sect2>Potential problems with Concurrent Haskell
+<label id="concurrent-problems">
+<p>
+<nidx>Concurrent Haskell problems</nidx>
+<nidx>problems, Concurrent Haskell</nidx>
+%* *
+%************************************************************************
+
+The main thread in a Concurrent Haskell program is given its own
+private stack space, but all other threads are given stack space from
+the heap. Stack space for the main thread can be
+adjusted as usual with the @-K@ RTS
+option,<nidx>-K RTS option (concurrent, parallel)</nidx> but if this
+private stack space is exhausted, the main thread will switch to stack
+segments in the heap, just like any other thread. Thus, problems
+which would normally result in stack overflow in ``sequential Haskell''
+can be expected to result in heap overflow when using threads.
+
+The concurrent runtime system uses black holes as synchronisation
+points for subexpressions which are shared among multiple threads. In
+``sequential Haskell'', a black hole indicates a cyclic data
+dependency, which is a fatal error. However, in concurrent execution, a
+black hole may simply indicate that the desired expression is being
+evaluated by another thread. Therefore, when a thread encounters a
+black hole, it simply blocks and waits for the black hole to be
+updated. Cyclic data dependencies will result in deadlock, and the
+program will fail to terminate.
+
+Because the concurrent runtime system uses black holes as
+synchronisation points, it is not possible to disable black-holing
+with the @-N@ RTS option.<nidx>-N RTS option</nidx> Therefore, the use
+of signal handlers (including timeouts) with the concurrent runtime
+system can lead to problems if a thread attempts to enter a black hole
+that was created by an abandoned computation. The use of signal
+handlers in conjunction with threads is strongly discouraged.
+
+
+%************************************************************************
+%* *
+<sect1>Using Parallel Haskell
+<p>
+<nidx>Parallel Haskell---use</nidx>
+%* *
+%************************************************************************
+
+[You won't be able to execute parallel Haskell programs unless PVM3
+(Parallel Virtual Machine, version 3) is installed at your site.]
+
+To compile a Haskell program for parallel execution under PVM, use the
+@-parallel@ option,<nidx>-parallel option</nidx> both when compiling
+<em>and linking</em>. You will probably want to @import Parallel@
+into your Haskell modules.
+
+To run your parallel program, once PVM is going, just invoke it ``as
+normal''. The main extra RTS option is @-N<n>@, to say how many
+PVM ``processors'' your program to run on. (For more details of
+all relevant RTS options, please see Section <ref name="RTS options for Concurrent/Parallel Haskell" id="parallel-rts-opts">.)
+
+In truth, running Parallel Haskell programs and getting information
+out of them (e.g., parallelism profiles) is a battle with the vagaries of
+PVM, detailed in the following sections.
+
+%************************************************************************
+%* *
+<sect2>Dummy's guide to using PVM
+<p>
+<nidx>PVM, how to use</nidx>
+<nidx>Parallel Haskell---PVM use</nidx>
+%* *
+%************************************************************************
+
+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 @.cshrc@ or equivalent:
+<tscreen><verb>
+setenv PVM_ROOT /wherever/you/put/it
+setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
+setenv PVM_DPATH $PVM_ROOT/lib/pvmd
+</verb></tscreen>
+
+Creating and/or controlling your ``parallel machine'' is a purely-PVM
+business; nothing specific to Parallel Haskell.
+
+You use the @pvm@<nidx>pvm command</nidx> command to start PVM on your
+machine. You can then do various things to control/monitor your
+``parallel machine;'' the most useful being:
+
+\begin{tabular}{ll}
+@Control-D@ & exit @pvm@, leaving it running \\
+@halt@ & kill off this ``parallel machine'' \& exit \\
+@add <host>@ & add @<host>@ as a processor \\
+@delete <host>@ & delete @<host>@ \\
+@reset@ & kill what's going, but leave PVM up \\
+@conf@ & list the current configuration \\
+@ps@ & report processes' status \\
+@pstat <pid>@ & status of a particular process \\
+\end{tabular}
+
+The PVM documentation can tell you much, much more about @pvm@!
+
+%************************************************************************
+%* *
+<sect2>Parallelism profiles
+<p>
+<nidx>parallelism profiles</nidx>
+<nidx>profiles, parallelism</nidx>
+<nidx>visualisation tools</nidx>
+%* *
+%************************************************************************
+
+With Parallel Haskell programs, we usually don't care about the
+results---only with ``how parallel'' it was! We want pretty pictures.
+
+Parallelism profiles (\`a la @hbcpp@) can be generated with the
+@-q@<nidx>-q RTS option (concurrent, parallel)</nidx> RTS option. The
+per-processor profiling info is dumped into files named
+@<full-path><program>.gr@. These are then munged into a PostScript picture,
+which you can then display. For example, to run your program
+@a.out@ on 8 processors, then view the parallelism profile, do:
+
+<tscreen><verb>
+% ./a.out +RTS -N8 -q
+% grs2gr *.???.gr > temp.gr # combine the 8 .gr files into one
+% gr2ps -O temp.gr # cvt to .ps; output in temp.ps
+% ghostview -seascape temp.ps # look at it!
+</verb></tscreen>
+
+The scripts for processing the parallelism profiles are distributed
+in @ghc/utils/parallel/@.
+
+%************************************************************************
+%* *
+<sect2>Other useful info about running parallel programs
+<p>
+%* *
+%************************************************************************
+
+The ``garbage-collection statistics'' RTS options can be useful for
+seeing what parallel programs are doing. If you do either
+@+RTS -Sstderr@<nidx>-Sstderr RTS option</nidx> or @+RTS -sstderr@, 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 @/tmp/pvml.nnn@, courtesy of PVM.
+
+Whether doing @+RTS -Sstderr@ or not, a handy way to watch
+what's happening overall is: @tail -f /tmp/pvml.nnn@.
+
+%************************************************************************
+%* *
+<sect2>RTS options for Concurrent/Parallel Haskell
+<label id="parallel-rts-opts">
+<p>
+<nidx>RTS options, concurrent</nidx>
+<nidx>RTS options, parallel</nidx>
+<nidx>Concurrent Haskell---RTS options</nidx>
+<nidx>Parallel Haskell---RTS options</nidx>
+%* *
+%************************************************************************
+
+Besides the usual runtime system (RTS) options
+(Section <ref name="Running a compiled program" id="runtime-control">), there are a few options particularly
+for concurrent/parallel execution.
+
+<descrip>
+<tag>@-N<N>@:</tag>
+<nidx>-N<N> RTS option (parallel)</nidx>
+(PARALLEL ONLY) Use @<N>@ PVM processors to run this program;
+the default is 2.
+
+<tag>@-C[<us>]@:</tag>
+<nidx>-C<us> RTS option</nidx>
+Sets the context switch interval to @<us>@ microseconds. A context
+switch will occur at the next heap allocation after the timer expires.
+With @-C0@ or @-C@, 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
+the finest granularity possible, short of a context switch at every
+heap allocation.
+
+<tag>@-q[v]@:</tag>
+<nidx>-q RTS option</nidx>
+Produce a quasi-parallel profile of thread activity, in the file
+@<program>.qp@. In the style of @hbcpp@, this profile records
+the movement of threads between the green (runnable) and red (blocked)
+queues. If you specify the verbose suboption (@-qv@), 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 @hbcpp@
+profiling tools or if you are context switching at every heap check
+(with @-C@).
+
+<tag>@-t<num>@:</tag>
+<nidx>-t<num> RTS option</nidx>
+Limit the number of concurrent threads per processor to @<num>@.
+The default is 32. Each thread requires slightly over 1K <em>words</em>
+in the heap for thread state and stack objects. (For 32-bit machines,
+this translates to 4K bytes, and for 64-bit machines, 8K bytes.)
+
+<tag>@-d@:</tag>
+<nidx>-d RTS option (parallel)</nidx>
+(PARALLEL ONLY) Turn on debugging. It pops up one xterm (or GDB, or
+something...) per PVM processor. We use the standard @debugger@
+script that comes with PVM3, but we sometimes meddle with the
+@debugger2@ script. We include ours in the GHC distribution,
+in @ghc/utils/pvm/@.
+
+<tag>@-e<num>@:</tag>
+<nidx>-e<num> RTS option (parallel)</nidx>
+(PARALLEL ONLY) Limit the number of pending sparks per processor to
+@<num>@. The default is 100. A larger number may be appropriate if
+your program generates large amounts of parallelism initially.
+
+<tag>@-Q<num>@:</tag>
+<nidx>-Q<num> RTS option (parallel)</nidx>
+(PARALLEL ONLY) Set the size of packets transmitted between processors
+to @<num>@. The default is 1024 words. A larger number may be
+appropriate if your machine has a high communication cost relative to
+computation speed.
+</descrip>
+
+%************************************************************************
+%* *
+<sect2>Potential problems with Parallel Haskell
+<label id="parallel-problems">
+<p>
+<nidx>Parallel Haskell---problems</nidx>
+<nidx>problems, Parallel Haskell</nidx>
+%* *
+%************************************************************************
+
+The ``Potential problems'' for Concurrent Haskell also apply for
+Parallel Haskell. Please see Section <ref name="Potential problems with Concurrent Haskell" id="concurrent-problems">.
%************************************************************************
%* *
-\section[utils]{Other Haskell utility programs}
-\index{utilities, Haskell}
+<sect>Other Haskell utility programs
+<label id="utils">
+<p>
+<nidx>utilities, Haskell</nidx>
%* *
%************************************************************************
%************************************************************************
%* *
-\subsection[mkdependHS]{Makefile dependencies in Haskell: using \tr{mkdependHS}}
-\index{mkdependHS}
-\index{Makefile dependencies}
-\index{dependencies in Makefiles}
+<sect1>Makefile dependencies in Haskell: using @mkdependHS@
+<label id="mkdependHS">
+<p>
+<nidx>mkdependHS</nidx>
+<nidx>Makefile dependencies</nidx>
+<nidx>dependencies in Makefiles</nidx>
%* *
%************************************************************************
You run @mkdependHS@ like this:
-\begin{verbatim}
+<tscreen><verb>
mkdependHS [mkdependHS options] [-- GHC options --] srcfile1 [srcfile2 ...]
-\end{verbatim}
+</verb></tscreen>
or
-\begin{verbatim}
+<tscreen><verb>
ghc -M [mkdependHS options(prefix with -optdep)] [ GHC options ] srcfile1 [srcfile2 ...]
-\end{verbatim}
-To see \tr{mkdependHS}'s command-line flags, give it a duff flag,
-e.g., \tr{mkdependHS -help}.
+</verb></tscreen>
+To see @mkdependHS@'s command-line flags, give it a duff flag,
+e.g., @mkdependHS -help@.
In general, if module @A@ contains the line
-\begin{verbatim}
+<tscreen><verb>
import B ...blah...
-\end{verbatim}
+</verb></tscreen>
then @mkdependHS@ will generate a dependency line of the form:
-\begin{verbatim}
+<tscreen><verb>
A.o : B.hi
-\end{verbatim}
+</verb></tscreen>
If module @A@ contains the line
-\begin{verbatim}
+<tscreen><verb>
import {-# SOURCE #-} B ...blah...
-\end{verbatim}
+</verb></tscreen>
then @mkdependHS@ will generate a dependency line of the form:
-\begin{verbatim}
+<tscreen><verb>
A.o : B.hi-boot
-\end{verbatim}
-(See \Sectionref{hi-files} for details of interface files.)
+</verb></tscreen>
+(See Section <ref name="Interface files" id="hi-files"> for details of interface files.)
If @A@ imports multiple modules, then there will be multiple lines with @A.o@ as the
target.
It understands the following ones. Any options between @--@ brackets
that it doesn't understand are simply ignored; this way you can feed your
Makefile's standard GHC options to @mkdependHS@ un-filtered.
-\begin{description}
+<descrip>
-\item[@-D<blah>@] A cpp @#define@; usual meaning.
+<tag>@-D<blah>@</tag> A cpp @#define@; usual meaning.
-\item[@-i<dirs>@] Add @<dirs>@ (colon-separated) to list of directories
+<tag>@-i<dirs>@</tag> Add @<dirs>@ (colon-separated) to list of directories
to search for "import"ed modules.
-\item[@-I<dir>@] Add @<dir>@ to list of directories to search for
+<tag>@-I<dir>@</tag> Add @<dir>@ to list of directories to search for
.h files (i.e., usual meaning).
-\item[@-syslib <blah>@] This program uses this GHC system library; take
+<tag>@-syslib <blah>@</tag> This program uses this GHC system library; take
appropriate action (e.g., recognise when they are
"import"ing a module from that library).
-
-\item[@-ignore <mod>@]
-\end{description}
+</descrip>
Here are the @mkdependHS@-specific options (not between @--@'s):
-\begin{description}
-\item[@-v@] Be verbose.
-\item[@-v -v@] Be very verbose.
-\item[@-w@] Turn off warnings about interface file shadowing.
-\item[@-f blah@]
+<descrip>
+<tag>@-v@</tag> Be verbose.
+<tag>@-v -v@</tag> Be very verbose.
+<tag>@-w@</tag> Turn off warnings about interface file shadowing.
+<tag>@-f blah@</tag>
Use @blah@ as the makefile, rather than @makefile@
or @Makefile@. If @blah@ doesn't exist, @mkdependHS@ creates it.
We often use @-f .depend@ to put the dependencies in @.depend@ and
then @include@ the file @.depend@ into @Makefilpe@.
-\item[@-o <osuf>@]
+<tag>@-o <osuf>@</tag>
Use @.<osuf>@ as the "target file" suffix ( default: @o@).
Multiple @-o@ flags are permitted (GHC2.05 onwards). Thus "@-o hc -o o@"
will generate dependencies for @.hc@ and @.o@ files.
-\item[@-s <suf>@]
+<tag>@-s <suf>@</tag>
Make extra dependencies that declare that files with
suffix @.<suf>_<osuf>@ depend on interface files with suffix @.<suf>_hi@, or
(for @{-# SOURCE #-}@ imports) on @.hi-boot@.
make dependencies for @.hc@ on @.hi@, @.a_hc@ on @.a_hi@, and @.b_hc@ on @.b_hi@.
(Useful in conjunction with NoFib "ways".)
-\item[@--exclude-module=<file>@]
+<tag>@--exclude-module=<file>@</tag>
Regard @<file>@ as "stable"; i.e., exclude it from having
dependencies on it.
-\item[@-x@] same as @--exclude-module@
+<tag>@-x@</tag> same as @--exclude-module@
-\item[@--exclude-directory=<dirs>@]
+<tag>@--exclude-directory=<dirs>@</tag>
Regard the colon-separated list of directories @<dirs>@ as containing stable,
don't generate any dependencies on modules therein.
-\item[@-Xdirs@] same as @--exclude-directory@.
+<tag>@-Xdirs@</tag> same as @--exclude-directory@.
-\item[@--include-module=<file>@]
+<tag>@--include-module=<file>@</tag>
Regard @<file>@ as not "stable"; i.e., generate dependencies
on it (if any). This option is normally used in conjunction
with the @--exclude-directory@ option.
-\item[@--include-prelude@]
+<tag>@--include-prelude@</tag>
Regard prelude libraries as unstable, i.e., generate dependencies
- on the prelude modules used (including \tr{Prelude}).
+ on the prelude modules used (including @Prelude@).
This option is normally only used by the various system libraries. If
- a \tr{-syslib} option is used, dependencies will also be
+ a @-syslib@ option is used, dependencies will also be
generated on the library's interfaces.
-\end{description}
+</descrip>
%************************************************************************
%* *
-\subsection[hstags]{Emacs `TAGS' for Haskell: \tr{hstags}}
-\index{hstags}
-\index{TAGS for Haskell}
+<sect1>Emacs `TAGS' for Haskell: @hstags@
+<label id="hstags">
+<p>
+<nidx>hstags</nidx>
+<nidx>TAGS for Haskell</nidx>
%* *
%************************************************************************
that index to jump around among these definitions.
Rather than scratch your head, saying ``Now where did we define
-`foo'?'', you just do (in Emacs) \tr{M-. foo RET}, and You're There!
+`foo'?'', you just do (in Emacs) @M-. foo RET@, and You're There!
Some people go wild over this stuff...
-GHC comes with a program \tr{hstags}, which build Emacs-able TAGS
+GHC comes with a program @hstags@, which build Emacs-able TAGS
files. The invocation syntax is:
-\begin{verbatim}
+<tscreen><verb>
hstags [GHC-options] file [files...]
-\end{verbatim}
+</verb></tscreen>
The best thing is just to feed it your GHC command-line flags.
A good Makefile entry might be:
-\begin{verbatim}
+<tscreen><verb>
tags:
$(RM) TAGS
hstags $(GHC_FLAGS) *.lhs
-\end{verbatim}
+</verb></tscreen>
-The only flags of its own are: \tr{-v} to be verbose; \tr{-a} to
+The only flags of its own are: @-v@ to be verbose; @-a@ to
**APPEND** to the TAGS file, rather than write to it.
Shortcomings: (1)~Instance declarations don't get into the TAGS file
is probably just as well. (2)~Data-constructor definitions don't get
in. Go for the corresponding type constructor instead.
-(Actually, GHC also comes with \tr{etags} [for C], and \tr{perltags}
+(Actually, GHC also comes with @etags@ [for C], and @perltags@
[for You Know What]. And---I cannot tell a lie---there is Denis
-Howe's \tr{fptags} [for Haskell, etc.] in the \tr{ghc/CONTRIB}
+Howe's @fptags@ [for Haskell, etc.] in the @ghc/CONTRIB@
section...)
%************************************************************************
%* *
-\subsection[happy]{``Yacc for Haskell'': \tr{happy}}
-\index{happy}
-\index{Yacc for Haskell}
-\index{parser generator for Haskell}
+<sect1>``Yacc for Haskell'': @happy@
+<label id="happy">
+<p>
+<nidx>happy</nidx>
+<nidx>Yacc for Haskell</nidx>
+<nidx>parser generator for Haskell</nidx>
%* *
%************************************************************************
Andy Gill and Simon Marlow have written a parser-generator for
-Haskell, called \tr{happy}.\index{happy parser generator} \tr{Happy}
-is to Haskell what \tr{Yacc} is to C.
+Haskell, called @happy@.<nidx>happy parser generator</nidx> @Happy@
+is to Haskell what @Yacc@ is to C.
-You can get \tr{happy} by FTP from \tr{ftp.dcs.gla.ac.uk} in
-\tr{pub/haskell/happy}, the file \tr{happy-0.8.tar.gz}.
+You can get @happy@ by FTP from @ftp.dcs.gla.ac.uk@ in
+@pub/haskell/happy@, the file @happy-0.8.tar.gz@.
-\tr{Happy} is at its shining best when compiled by GHC.
+@Happy@ is at its shining best when compiled by GHC.
%************************************************************************
%* *
-\subsection[pphs]{Pretty-printing Haskell: \tr{pphs}}
-\index{pphs}
-\index{pretty-printing Haskell code}
+<sect1>Pretty-printing Haskell: @pphs@
+<label id="pphs">
+<p>
+<nidx>pphs</nidx>
+<nidx>pretty-printing Haskell code</nidx>
%* *
%************************************************************************
Andrew Preece has written
-\tr{pphs},\index{pphs}\index{pretty-printing Haskell}
+@pphs@,<nidx>pphs</nidx><nidx>pretty-printing Haskell</nidx>
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
very tiresome to do by hand.
-The code is distributed with GHC in \tr{ghc/CONTRIB/pphs}.
+The code is distributed with GHC in @ghc/CONTRIB/pphs@.
%************************************************************************
%* *
-\section[vs-Haskell-defn]{Haskell~1.3 vs.~Glasgow Haskell~2.02: language non-compliance}
-\index{GHC vs the Haskell 1.4 language}
-\index{Haskell 1.4 language vs GHC}
+<sect1>Haskell~1.4 vs.~Glasgow Haskell~3.00: language non-compliance
+<label id="vs-Haskell-defn">
+<p>
+<nidx>GHC vs the Haskell 1.4 language</nidx>
+<nidx>Haskell 1.4 language vs GHC</nidx>
%* *
%************************************************************************
This section lists Glasgow Haskell infelicities in its implementation
of Haskell~1.4. See also the ``when things go wrong'' section
-(\sectionref{wrong}) for information about crashes, space leaks, and
-other undesirable phenomena.
-
-GHC~2.02 does not have a ``Haskell~1.2 compatibility mode.'' If
-enough people yelled loudly and long enough, it could conceivably
-happen...
+(Section <ref name="What to do when something goes wrong" id="wrong">)
+for information about crashes, space leaks, and other undesirable
+phenomena.
The limitations here are listed in Haskell-Report order (roughly).
-%Limitations related to Glasgow extensions (unboxed numbers, etc.) are
-%given thereafter (\sectionref{infelicities-Glasgow-exts}).
%************************************************************************
%* *
-\subsection[infelicities-exprs-pats]{Expressions and patterns}
+<sect2>Expressions and patterns
+<label id="infelicities-exprs-pats">
+<p>
%* *
%************************************************************************
-\begin{description}
-%-------------------------------------------------------------------
-%\item[No @n+k@ patterns:]
-%We took them out of GHC, because we thought they weren't going to
-%survive into Haskell~1.3. But they did. And we haven't put them
-%back. Yet.
+<descrip>
%-------------------------------------------------------------------
-\item[Very long @String@ constants:]
+<tag>Very long @String@ constants:</tag>
May not go through. If you add a ``string gap'' every
few thousand characters, then the strings can be as long
as you like.
-Bear in mind that string gaps and the \tr{-cpp}\index{-cpp option}
-option don't mix. The C-preprocessor may munch the backslashes.
+Bear in mind that string gaps and the @-cpp@<nidx>-cpp option</nidx>
+option don't mix very well (see Section <ref id="c-pre-processor"
+name="The C pre-processor">).
%-------------------------------------------------------------------
-\item[Very long literal lists:]
+<tag>Very long literal lists:</tag>
These may tickle a ``yacc stack overflow'' error in the parser.
(It depends on the Yacc used to build your parser.)
%-------------------------------------------------------------------
-\item[Single quotes in module names:]
+<tag>Single quotes in module names:</tag>
It might work, but it's just begging for trouble.
-\end{description}
+</descrip>
%************************************************************************
%* *
-\subsection[infelicities-decls]{Declarations and bindings}
+<sect2>Declarations and bindings
+<label id="infelicities-decls">
+<p>
%* *
%************************************************************************
-\begin{description}
+<descrip>
%-------------------------------------------------------------------
-\item[Derived instances of @Read@ and @Show@ for infix constructors:]
+<tag>Derived instances of @Read@ and @Show@ for infix constructors:</tag>
All the carry-on about derived @readsPrec@ and @showsPrec@ for infix
constructors---we don't do it (yet). We treat them the same way as
all other constructors.
%-------------------------------------------------------------------
-\item[Derived instances for records:] Hmmm.
-\end{description}
+<tag>Derived instances for records:</tag> Hmmm.
+</descrip>
%************************************************************************
%* *
-\subsection[infelicities-Modules]{Module system and interface files}
+<sect2>Module system and interface files
+<label id="infelicities-Modules">
+<p>
%* *
%************************************************************************
-\begin{description}
+<descrip>
+%-------------------------------------------------------------------
+<tag> Namespace pollution </tag>
+
+Several modules internal to GHC are visible in the standard namespace.
+All of these modules begin with @Prel@, so the rule is: don't use any
+modules beginning with @Prel@ in your programl, or you will be
+comprehensively screwed.
+
%-------------------------------------------------------------------
-\item[Can't export primitives types (e.g., \tr{Int#}):]
+<tag>Can't export primitive types (e.g., @Int#@):</tag>
Don't even try...
-\end{description}
+</descrip>
%************************************************************************
%* *
-\subsection[infelicities-numbers]{Numbers, basic types, and built-in classes}
+<sect2>Numbers, basic types, and built-in classes
+<label id="infelicities-numbers">
+<p>
%* *
%************************************************************************
-\begin{description}
+<descrip>
%-------------------------------------------------------------------
-\item[Very large/small fractional constants:]
+<tag>Very large/small fractional constants:</tag>
(i.e., with a decimal point somewhere) GHC does not check that these
are out of range (e.g., for a @Float@), and bad things will inevitably
follow. (To be corrected?)
-This problem does {\em not} exist for integral constants.
+This problem does <em>not</em> exist for integral constants.
For very large/small fractional constants near the limits of your
floating-point precision, things may go wrong. (It's better than it
used to be.) Please report any such bugs.
%-------------------------------------------------------------------
-\item[Unchecked arithmetic:]
-Arguably {\em not} an infelicity, but... Bear in mind that operations
-on \tr{Int}, \tr{Float}, and \tr{Double} numbers are {\em unchecked}
-for overflow, underflow, and other sad occurrences.
+<tag>Unchecked arithmetic:</tag>
-Use \tr{Integer}, \tr{Rational}, etc., numeric types if this stuff
+Arguably <em>not</em> an infelicity, but... Bear in mind that
+operations on @Int@, @Float@, and @Double@ numbers are
+<em>unchecked</em> for overflow, underflow, and other sad occurrences.
+(note, however that some architectures trap floating-point overflow
+and loss-of-precision and report a floating-point exception).
+
+Use @Integer@, @Rational@, etc., numeric types if this stuff
keeps you awake at night.
%-------------------------------------------------------------------
-\item[Multiply-defined array elements---not checked:]
-This code fragment {\em should} elicit a fatal error, but it does not:
-\begin{verbatim}
+<tag>Multiply-defined array elements---not checked:</tag>
+This code fragment <em>should</em> elicit a fatal error, but it does not:
+<tscreen><verb>
main = print (array (1,1) [ 1:=2, 1:=3 ])
-\end{verbatim}
-\end{description}
+</verb></tscreen>
+</descrip>
%************************************************************************
%* *
-\subsection[infelicities-Prelude]{In Prelude support}
+<sect2>In Prelude support
+<label id="infelicities-Prelude">
+<p>
%* *
%************************************************************************
-\begin{description}
-%-------------------------------------------------------------------
-\item[Polymorphic @seq@:]
-Required by the Haskell~1.3 prelude; not done yet. Consequently,
-the @strict@ function doesn't really do what you want either.
-
+<descrip>
%-------------------------------------------------------------------
-\item[Arbitrary-sized tuples:]
-Plain old tuples of arbitrary size {\em do} work. Note that lots of
+<tag>Arbitrary-sized tuples:</tag>
+Plain old tuples of arbitrary size <em>do</em> work. Note that lots of
overloading can give rise to large tuples ``under the hood'' of your
program.
HOWEVER: standard instances for tuples (@Eq@, @Ord@, @Bounded@, @Ix@
-@Read@, and @Show@) are available {\em only} up to 5-tuples.
+@Read@, and @Show@) are available <em>only</em> up to 5-tuples.
These limitations are easily subvertible, so please ask if you get
stuck on them.
%-------------------------------------------------------------------
-\item[Unicode character set:]
-Haskell~1.4 embraces the Unicode character set, but GHC~2.02 does
+<tag>Unicode character set:</tag>
+Haskell~1.4 embraces the Unicode character set, but GHC~3.00 doesn't
handle it. Yet.
-%-------------------------------------------------------------------
-\item[class @Enum@:]
-In Haskell~1.4, @Ord@ is dropped as a superclass of @Enum@. GHC~2.02
-still has the @Ord@ constraint.
-\end{description}
+</descrip>
projects / ghc-hetmet.git / commitdiff