Skip to content

GitLab

Commit 7bcdfdba authored by simonmar's avatar simonmar
Browse files

[project @ 2002-06-25 12:05:14 by simonmar] 

Various hacking on the User's Guide to knock it into shape for the release.

Committers: please take a look at the 5.04 release notes and feel free
to tweak or embelish the description for your favourite new feature.
parent f482977c
Hide whitespace changes
Inline Side-by-side
Showing with 249 additions and 428 deletions
ghc/docs/users_guide/5-02-notes.sgml
View file @ 7bcdfdba
<sect1 id="release-5-02">
<title>Release notes for version 5.02</title>
<sect1 id="release-5-04">
<title>Release notes for version 5.04</title>
<sect2>
<title>User-visible compiler changes</title>
<itemizedlist>
<listitem>
<para>Majorly improved support for Windows platforms. Binary
builds are now entirely freestanding. There is no longer any
need to install Cygwin or Mingwin to use it. It's a
one-click-install-and-off-you-go story now.</para>
</listitem>
<listitem>
<para>Several small changes to bring GHC into line with the
newest Haskell&nbsp;98 report.</para>
</listitem>
<listitem>
<para>RTS options can now be specified using the environment
variable <envar>GHCRTS</envar>.</para>
</listitem>
<listitem>
<para>The maximum heap size, set with
<literal>+RTS -M<replaceable>size</replaceable></literal>,
now defaults to unlimited. We recommend however that you set
a maximum heap size appropriate for your machine using the
<envar>GHCRTS</envar> variable.</para>
</listitem>
<listitem>
<para>Thanks to the heroic efforts of Ken Shan
<email>ken@digitas.harvard.edu</email>, GHC now works again on
the Alpha architecture (just Tru64 at the moment), and many
64-bit bugs have been shaken out. Interactive mode and the
native code generator do not currently work, sorry.</para>
</listitem>
<listitem>
<para>New option: <option>-fno-code</option> which causes GHC
to omit code generation and all future compilation stages (see
<xref linkend="options-codegen">).</para>
</listitem>
<listitem>
<para>New option <option>-package-conf
<replaceable>file</replaceable></option>. This makes GHC read
additional package descriptions from
<replaceable>file</replaceable>. See <xref
linkend="using-local-packages">.</para>
</listitem>
<listitem>
<para><option>+RTS
-i<replaceable>seconds</replaceable></option> flag reinstated for heap
profiling. See <xref linkend="rts-options-heap-prof">.</para>
</listitem>
<listitem>
<para><option>-funbox-strict-fields</option> now works
correctly. See <xref linkend="options-f">.</para>
</listitem>
<listitem>
<para>
Many bug fixes related to implicit-parameter support.</para>
<para></para>
</listitem>
<listitem>
<para>
Data declarations with no constructors are allowed. This
facilitates types whose only value is bottom, and which have
no representation.</para>
</listitem>
<listitem>
<para>
You can disconnect numeric syntax from the Prelude syntax.
Doing this means you can define your own arithmetic. The
relevant flag is <option>-fno-implicit-prelude</option>. See
<xref linkend="options-language">.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>User-visible interpreter (GHCi) changes</title>
<itemizedlist>
<listitem>
<para>GHCi now works on Windows.</para>
</listitem>
<listitem>
<para>Partial FFI support in GHCi. At the moment, foreign
import (static and dynamic) are supported on x86 and sparc
platforms.</para>
<para></para>
</listitem>
<listitem>
<para>New interpreter command <literal>:add</literal>, to add
modules to the current bunch. See
<xref linkend="ghci-commands">.</para>
</listitem>
<listitem>
<para>New interpreter command <literal>:info</literal>, to provide
information on values, types and classes, a la Hugs. See
<xref linkend="ghci-commands">.</para>
</listitem>
<listitem>
<para>Multiple target modules are supported. You may specify
multiple modules for the <literal>:add</literal> and
<literal>:load</literal> commands. From the command line, you
may specify multiple modules when starting GHCi and when
compiling in <option>&ndash;&ndash;make</option> mode. See
<xref linkend="ghci-commands">.</para>
</listitem>
<listitem>
<para>New flags <option>-ignore-dot-ghci</option> and
<option>-read-dot-ghci</option>. See
<xref linkend="ghci-dot-files">.</para>
</listitem>
<listitem>
<para>When starting GHCi from the command line, you may now
use the flags
<option>-L<replaceable>library-path</replaceable></option> and
<option>-l<replaceable>library-name</replaceable></option> to
specify libraries to be loaded into the interactive
session. See <xref linkend="ghci-invokation">.</para>
</listitem>
</itemizedlist>
</sect2>
......@@ -145,134 +23,16 @@
<title>User-visible library changes</title>
<itemizedlist>
<listitem>
<para>The <literal>SocketPrim</literal> and
<literal>BSD</literal> modules in the <literal>net</literal>
package have been re-written to use the FFI, be more portable,
and be more thread-safe. There are minor user-visible
changes: the functions <function>writeSocket</function>,
<function>readSocket</function> and
<function>readSocketAll</function> have been removed (use
<function>socketToHandle</function> and
<literal>Handle</literal> operations instead).</para>
</listitem>
<listitem>
<para>New function: <function>Exception.throwDynTo</function>.
See <xref linkend="sec-Dynamic-Exceptions">.</para>
</listitem>
<listitem>
<para><literal>BlockedOnDeadMVar</literal> and
<literal>ThreadKilled</literal> exceptions no longer generate
any output by default for forked threads.</para>
</listitem>
<listitem>
<para><literal>Weak.addForeignFinalizer</literal> is
deprecated; use the <literal>ForeignPtr</literal> library
instead.</para>
</listitem>
<listitem>
<para>The I/O library has been completely rewritten, using the
new FFI libraries and <command>hsc2hs</command>. The main
improvement is to the way streams are handled: simultaneous
read and write with multiple threads using a socket or FIFO is
now possible, whereas before it was necessary to use two
separate handles.</para>
</listitem>
<listitem>
<para>As a result of the I/O rewrite, the extensions
<literal>IOExts.hConnectTo</literal> and
<literal>IOExts.withHandleFor</literal> have been removed.
Also, <literal>hGetBuf</literal> and
<literal>hPutBuf</literal> have been removed, and
<literal>hGetBufFull</literal> and
<literal>hPutBufFull</literal> have been renamed to
<literal>hGetBuf</literal> and <literal>hPutBuf</literal>
respectively (similary for the <literal>BA</literal>
versions of these functions).</para>
</listitem>
<listitem>
<para><literal>System.exitWith</literal> now throws
<literal>ExitException</literal> rather than causing the
program to exit immediately. <literal>ExitException</literal>
is by default caught by the top level exception handler in the
main thread, where it causes the program to exit. Hence, calling
<literal>System.exitWith</literal> in GHCi no longer causes
GHCi itself to exit.</para>
</listitem>
<listitem>
<para>New function: <literal>MVar.addMVarFinalizer</literal>
(see <xref linkend="sec-MVars">).</para>
</listitem>
<listitem>
<para>New module <literal>SystemExts</literal> for useful
system-ish functionality (see <xref
linkend="sec-SystemExts">).</para>
</listitem>
<listitem>
<para><literal>SocketPrim</literal>: added instances of
<literal>Eq</literal> and <literal>Show</literal> for the
<literal>Socket</literal> type.</para>
</listitem>
<listitem>
<para>The implementation of
<literal>MarsalAlloc.allocaBytes</literal> now uses GHC's
internal allocator and is much faster than before. As a
result, the <literal>UnsafeCString</literal> type and
functions are no longer necessary and have been removed from
<literal>CString</literal>.</para>
<para></para>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>New experimental features</title>
<itemizedlist>
<!-- don't forget: 31-bit support -->
<listitem>
<para>Partial support for hierarchical module names.</para>
</listitem>
<listitem>
<para>Mucho hacking on the .NET code generator, including
some FFI extensions for .NET interop. It's still
severely b0rk3d, so won't do anything useful. Yet.</para>
</listitem>
<listitem>
<para>Emission of external Core format. The goal is for
other tools to be able to grab the Core resulting from GHC's
front end manglings and optimisations. Core format is
formally defined by the document <ulink url="http://www.haskell.org/ghc/docs/papers/core.ps.gz"
<citetitle>An External Representation for the GHC Core Language</citetitle></ulink>.
We also have sample
tools for reading, writing and typechecking external Core,
available in the source distribution directory <literal>/fptools/ghc/utils/ext-core</literal>.
Ultimately we plan that Core files can also be read by
GHC. The relevant flag is <option>-fext-core</option>.
</para>
</listitem>
<listitem>
<para>A compacting garbage collector has been added. It isn't
on by default, because it is somewhat slower than the existing
copying collector, but can be automatically enabled when
memory gets tight by setting the maximum heap size (see <xref
linkend="rts-options-gc">). Compaction works together with
the existing generational scheme: it is only used on the
oldest generation. Despite the "experimental"
classification, we've jumped up and down quite significantly
on this code, and it seems stable.</para>
<para></para>
</listitem>
</itemizedlist>
</sect2>
......@@ -281,24 +41,8 @@
<title>Internal changes</title>
<itemizedlist>
<listitem>
<para>The implementation of the <literal>Array</literal>,
<literal>IArray</literal> and <literal>MArray</literal>
libraries have been rewritten so that bulk operations like
<literal>listArray</literal> and <literal>elems</literal> do
less range checking and hence go faster.</para>
</listitem>
<listitem>
<para>The <literal>CPUTime</literal> library has been replaced
by one written using the FFI. No externally visible
changes.</para>
</listitem>
<listitem>
<para>The compiler has a new strictness-and-absence analyser,
which is alleged to help it generate better code.</para>
<para></para>
</listitem>
</itemizedlist>
</sect2>
......
ghc/docs/users_guide/ffi-chap.sgml
View file @ 7bcdfdba
......@@ -30,9 +30,9 @@
</listitem>
</itemizedlist>
<para>The FFI libraries are documented in <xref
linkend="sec-Foreign">.</para>
<para>The FFI libraries are documented in the accompanying library
documentation; see for example the <literal>Foreign</literal>
module.</para>
<sect1 id="sec-ffi-ghcexts">
<title>GHC extensions to the FFI Addendum</title>
......
ghc/docs/users_guide/flags.sgml
View file @ 7bcdfdba
......@@ -299,6 +299,14 @@
<entry>dynamic</entry>
<entry>-</entry>
</row>
<row>
<entry><option>--show-iface</option> <replaceable>file</replaceable></entry>
<entry>Read the interface in
<replaceable>file</replaceable> and dump it as text to
<literal>stdout</literal>.</entry>
<entry>static</entry>
<entry>-</entry>
</row>
</tbody>
</tgroup>
</informaltable>
......@@ -1092,17 +1100,17 @@
<entry>-</entry>
</row>
<row>
<entry><option>-framework</option> <replaceable>name</replaceable></endtry>
<entry><option>-framework</option> <replaceable>name</replaceable></entry>
<entry>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
This option corresponds to the <option>-framework</option> option for Apple's Linker.
This option corresponds to the <option>-framework</option> option for Apple's Linker.</entry>
<entry>static</entry>
<entry>-</entry>
</row>
<row>
<entry><option>-framework-path</option> <replaceable>name</replaceable></endtry>
<entry><option>-framework-path</option> <replaceable>name</replaceable></entry>
<entry>On Darwin/MacOS X only, add <replaceable>dir</replaceable> to the list of
directories searched for frameworks.
This option corresponds to the <option>-F</option> option for Apple's Linker.
This option corresponds to the <option>-F</option> option for Apple's Linker.</entry>
<entry>static</entry>
<entry>-</entry>
</row>
......
ghc/docs/users_guide/ghci.sgml
View file @ 7bcdfdba
......@@ -9,11 +9,11 @@
</footnote>
is GHC's interactive environment, in which Haskell expressions can
be interactively evaluated and programs can be interpreted. If
you're famililar with Hugs<indexterm><primary>Hugs</primary>
you're famililar with <ulink url="http://www.haskell.org/hugs/">Hugs</ulink><indexterm><primary>Hugs</primary>
</indexterm>, then you'll be right at home with GHCi. However, GHCi
also has support for interactively loading compiled code, as well as
supporting all<footnote><para>except <literal>foreign export</literal>, at the moment</para>
</footnote>the language extensions that GHC provides.</para>
</footnote> the language extensions that GHC provides.</para>
<indexterm><primary>FFI</primary><secondary>GHCi support</secondary></indexterm>
<indexterm><primary>Foreign Function Interface</primary><secondary>GHCi support</secondary></indexterm>
......@@ -27,11 +27,12 @@
$ ghci
___ ___ _
/ _ \ /\ /\/ __(_)
/ /_\// /_/ / / | | GHC Interactive, version 5.00, For Haskell 98.
/ /_\// /_/ / / | | GHC Interactive, version 5.04, for Haskell 98.
/ /_\\/ __ / /___| | http://www.haskell.org/ghc/
\____/\/ /_/\____/|_| Type :? for help.
Loading package std ... linking ... done.
Loading package base ... linking ... done.
Loading package haskell98 ... linking ... done.
Prelude>
</screen>
......@@ -42,23 +43,37 @@ Prelude>
<screen>
Commands available from the prompt:
&lt;stmt&gt; evaluate/run &lt;stmt&gt;
:cd &lt;dir&gt; change directory to &lt;dir&gt;
:def &lt;cmd&gt; &lt;expr&gt; define a macro :&lt;cmd&gt;
:help, :? display this list of commands
:load &lt;filename&gt; load a module (and it dependents)
:module &lt;mod&gt; set the context for expression evaluation to &lt;mod&gt;
:reload reload the current module set
:set &lt;option&gt; ... set options
:type &lt;expr&gt; show the type of &lt;expr&gt;
:unset &lt;option&gt; ... unset options
:quit exit GHCi
:!&lt;command&gt; run the shell command &lt;command&gt;
%lt;stmt&gt; evaluate/run %lt;stmt&gt;
:add %lt;filename&gt; ... add module(s) to the current target set
:browse [*]%lt;module&gt; display the names defined by %lt;module&gt;
:cd %lt;dir&gt; change directory to %lt;dir&gt;
:def %lt;cmd&gt; %lt;expr&gt; define a command :%lt;cmd&gt;
:help, :? display this list of commands
:info [%lt;name&gt; ...] display information about the given names
:load %lt;filename&gt; ... load module(s) and their dependents
:module [+/-] [*]%lt;mod&gt; ... set the context for expression evaluation
:reload reload the current module set
:set %lt;option&gt; ... set options
:set args %lt;arg&gt; ... set the arguments returned by System.getArgs
:set prog %lt;progname&gt; set the value returned by System.getProgName
:show modules show the currently loaded modules
:show bindings show the current bindings made at the prompt
:type %lt;expr&gt; show the type of %lt;expr&gt;
:undef %lt;cmd&gt; undefine user-defined command :%lt;cmd&gt;
:unset %lt;option&gt; ... unset options
:quit exit GHCi
:!%lt;command&gt; run the shell command %lt;command&gt;
Options for `:set' and `:unset':
+r revert top-level expressions after each evaluation
+s print timing/memory stats after each evaluation
+t print type after evaluation
-&lt;flag&gt; most GHC command line flags can also be set here
-%lt;flags&gt; most GHC command line flags can also be set here
(eg. -v2, -fglasgow-exts, etc.)
</screen>
......@@ -203,8 +218,8 @@ Ok, modules loaded: Main.
normally converted to byte-code and run using the interpreter.
However, interpreted code can also run alongside compiled code in
GHCi; indeed, normally when GHCi starts, it loads up a compiled
copy of package <literal>std</literal>, which contains the Prelude
and standard libraries.</para>
copy of the <literal>base</literal> package, which contains the
<literal>Prelude</literal>.</para>
<para>Why should we want to run compiled code? Well, compiled
code is roughly 10x faster than interpreted code, but takes about
......@@ -526,8 +541,9 @@ Prelude>
</screen>
<para>Any exceptions raised during the evaluation or execution
of the statement are caught and printed by the GHCi command line
interface (see <xref linkend="sec-Exception"> for more
information on GHC's Exception support).</para>
interface (for more information on exceptions, see the module
<literal>Control.Exception</literal> in the libraries
documentation).</para>
<para>Every new binding shadows any existing bindings of the
same name, including entities that are in scope in the current
......@@ -640,28 +656,25 @@ $ ghci Main.hs
<indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm>
<para>GHCi can make use of all the packages that come with GHC,
For example, to start up GHCi with the <literal>text</literal>
For example, to start up GHCi with the <literal>network</literal>
package loaded:</para>
<screen>
$ ghci -package text
$ ghci -package network
___ ___ _
/ _ \ /\ /\/ __(_)
/ /_\// /_/ / / | | GHC Interactive, version 5.00, For Haskell 98.
/ /_\// /_/ / / | | GHC Interactive, version 5.04, for Haskell 98.
/ /_\\/ __ / /___| | http://www.haskell.org/ghc/
\____/\/ /_/\____/|_| Type :? for help.
Loading package std ... linking ... done.
Loading package lang ... linking ... done.
Loading package text ... linking ... done.
Loading package base ... linking ... done.
Loading package haskell98 ... linking ... done.
Loading package network ... linking ... done.
Prelude>
</screen>
<para>Note that GHCi also loaded the <literal>lang</literal>
package even though we didn't ask for it: that's because the
<literal>text</literal> package makes use of one or more of the
modules in <literal>lang</literal>, and therefore has a
dependency on it.</para>
<para>Note that GHCi will also automatically load any packages
on which the requested package depends.</para>
<para>The following command works to load new packages into a
running GHCi:</para>
......
ghc/docs/users_guide/glasgow_exts.sgml
View file @ 7bcdfdba
......@@ -19,8 +19,9 @@ performance because of the implementation costs of Haskell's
Before you get too carried away working at the lowest level (e.g.,
sloshing <literal>MutableByteArray&num;</literal>s around your
program), you may wish to check if there are libraries that provide a
&ldquo;Haskellised veneer&rdquo; over the features you want. See
<xref linkend="book-hslibs">.
&ldquo;Haskellised veneer&rdquo; over the features you want. The
separate libraries documentation describes all the libraries that come
with GHC.
</para>
<!-- LANGUAGE OPTIONS -->
......@@ -163,14 +164,16 @@ program), you may wish to check if there are libraries that provide a
<para>With the <option>-fglasgow-exts</option> flag, GHC lets you declare
a data type with no constructors. For example:</para>
<programlisting>
data S -- S :: *
data T a -- T :: * -> *
</programlisting>
<para>Syntactically, the declaration lacks the "= constrs" part. The
type can be parameterised, but only over ordinary types, of kind *; since
Haskell does not have kind signatures, you cannot parameterise over higher-kinded
types.</para>
type can be parameterised over types of any kind, but if the kind is
not <literal>*</literal> then an explicit kind annotation must be used
(see <xref linkend="sec-kinding">).</para>
<para>Such data types have only one value, namely bottom.
Nevertheless, they can be useful when defining "phantom types".</para>
......@@ -894,21 +897,19 @@ is <literal>(?x::a) => (a,a)</literal>, and not
class constraints.
</para>
<para>
An implicit parameter is bound using an expression of the form
<emphasis>expr</emphasis> <literal>with</literal> <emphasis>binds</emphasis>,
where <literal>with</literal> is a new keyword. This form binds the implicit
parameters arising in the body, not the free variables as a <literal>let</literal> or
<literal>where</literal> would do. For example, we define the <literal>min</literal> function by binding
<literal>cmp</literal>.
An implicit parameter is bound using the standard
<literal>let</literal> binding form, where the bindings must be a
collection of simple bindings to implicit-style variables (no
function-style bindings, and no type signatures); these bindings are
neither polymorphic or recursive. This form binds the implicit
parameters arising in the body, not the free variables as a
<literal>let</literal> or <literal>where</literal> would do. For
example, we define the <literal>min</literal> function by binding
<literal>cmp</literal>.</para>
<programlisting>
min :: [a] -> a
min = least with ?cmp = (<=)
min = let ?cmp = (<=) in least
</programlisting>
Syntactically, the <emphasis>binds</emphasis> part of a <literal>with</literal> construct must be a
collection of simple bindings to variables (no function-style
bindings, and no type signatures); these bindings are neither
polymorphic or recursive.
</para>
<para>
Note the following additional constraints:
<itemizedlist>
......@@ -1379,7 +1380,7 @@ for rank-2 types.
</sect3>
</sect2>
<sect2>
<sect2 id="type-synonyms">
<title>Liberalised type synonyms
</title>
......@@ -2346,21 +2347,24 @@ assert pred val ==> assertError "Main.hs|15" pred val
<para>
The rewrite is only performed by the compiler when it spots
applications of <function>Exception.assert</function>, so you can still define and
use your own versions of <function>assert</function>, should you so wish. If not,
import <literal>Exception</literal> to make use <function>assert</function> in your code.
applications of <function>Control.Exception.assert</function>, so you
can still define and use your own versions of
<function>assert</function>, should you so wish. If not, import
<literal>Control.Exception</literal> to make use
<function>assert</function> in your code.
</para>
<para>
To have the compiler ignore uses of assert, use the compiler option
<option>-fignore-asserts</option>. <indexterm><primary>-fignore-asserts option</primary></indexterm> That is,
expressions of the form <literal>assert pred e</literal> will be rewritten to <literal>e</literal>.
<option>-fignore-asserts</option>. <indexterm><primary>-fignore-asserts
option</primary></indexterm> That is, expressions of the form
<literal>assert pred e</literal> will be rewritten to
<literal>e</literal>.
</para>
<para>
Assertion failures can be caught, see the documentation for the
<literal>Exception</literal> library (<xref linkend="sec-Exception">)
for the details.
<literal>Control.Exception</literal> library for the details.
</para>
</sect1>
......@@ -2369,6 +2373,53 @@ for the details.
<sect1 id="syntax-extns">
<title>Syntactic extensions</title>
<!-- ====================== HIERARCHICAL MODULES ======================= -->
<sect2 id="hierarchical-modules">
<title>Hierarchical Modules</title>
<para>GHC supports a small extension to the syntax of module
names: a module name is allowed to contain a dot
<literal>&lsquo;.&rsquo;</literal>. This is also known as the
&ldquo;hierarchical module namespace&rdquo; extension, because