Commit abdd55c9 authored by simonm's avatar simonm
Browse files

[project @ 1998-01-30 17:01:49 by simonm]

New SGML User Guide, first cut.
parent 5e1ab44b
......@@ -4,7 +4,7 @@ It represents a major step forward in GHC development since GHC~0.26
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!
......@@ -14,13 +14,17 @@ Installation Guide. Since 0.26, we've improved our support for iX86
%************************************************************************
%* *
\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>
%* *
%************************************************************************
......@@ -31,49 +35,53 @@ are described there (and not repeated here).
%************************************************************************
%* *
\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.
......@@ -82,9 +90,9 @@ changed from 1.2, even if the user is unlikely to notice.
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
......@@ -92,31 +100,35 @@ will very likely change again. All processing of interface
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>
%* *
%************************************************************************
......@@ -129,10 +141,10 @@ eventually look like...
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
......@@ -147,49 +159,53 @@ appendChanPrimIO :: String -> String -> PrimIO ()
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
......@@ -197,6 +213,8 @@ 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!
......@@ -10,13 +14,17 @@ Installation Guide. Since 2.01, we've added support for Win32
%************************************************************************
%* *
\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>
%* *
%************************************************************************
......@@ -27,96 +35,108 @@ user-visible changes are described there (and not repeated here).
%************************************************************************
%* *
\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>
%* *
%************************************************************************
......@@ -126,32 +146,34 @@ interface generator for Haskell. More details elsewhere...
%************************************************************************
%* *
\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
......@@ -31,45 +35,45 @@ irritating you.
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
......@@ -38,28 +42,28 @@ data constructors and instance declarations). The upshot of this
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}