diff options
| author | simonmar <unknown> | 2002-06-25 12:05:15 +0000 |
|---|---|---|
| committer | simonmar <unknown> | 2002-06-25 12:05:15 +0000 |
| commit | 7bcdfdba58be3bd3159a87ca8413c28e3c64d147 (patch) | |
| tree | f98840157b65b14c4444bed66b5364e6964c3309 | |
| parent | f482977cba3daaaf2347f5a11d55cdbeae6ac13c (diff) | |
| download | haskell-7bcdfdba58be3bd3159a87ca8413c28e3c64d147.tar.gz | |
[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.
| -rw-r--r-- | ghc/docs/users_guide/5-02-notes.sgml | 270 | ||||
| -rw-r--r-- | ghc/docs/users_guide/ffi-chap.sgml | 6 | ||||
| -rw-r--r-- | ghc/docs/users_guide/flags.sgml | 16 | ||||
| -rw-r--r-- | ghc/docs/users_guide/ghci.sgml | 77 | ||||
| -rw-r--r-- | ghc/docs/users_guide/glasgow_exts.sgml | 132 | ||||
| -rw-r--r-- | ghc/docs/users_guide/gone_wrong.sgml | 4 | ||||
| -rw-r--r-- | ghc/docs/users_guide/installing.sgml | 12 | ||||
| -rw-r--r-- | ghc/docs/users_guide/intro.sgml | 6 | ||||
| -rw-r--r-- | ghc/docs/users_guide/packages.sgml | 6 | ||||
| -rw-r--r-- | ghc/docs/users_guide/parallel.sgml | 3 | ||||
| -rw-r--r-- | ghc/docs/users_guide/phases.sgml | 2 | ||||
| -rw-r--r-- | ghc/docs/users_guide/primitives.sgml | 6 | ||||
| -rw-r--r-- | ghc/docs/users_guide/separate_compilation.sgml | 86 | ||||
| -rw-r--r-- | ghc/docs/users_guide/ug-book.sgml | 2 | ||||
| -rw-r--r-- | ghc/docs/users_guide/ug-ent.sgml | 2 | ||||
| -rw-r--r-- | ghc/docs/users_guide/using.sgml | 37 | ||||
| -rw-r--r-- | ghc/docs/users_guide/utils.sgml | 4 | ||||
| -rw-r--r-- | ghc/docs/users_guide/vs_haskell.sgml | 6 |
18 files changed, 249 insertions, 428 deletions
diff --git a/ghc/docs/users_guide/5-02-notes.sgml b/ghc/docs/users_guide/5-02-notes.sgml index 8a64c0719f..d577841484 100644 --- a/ghc/docs/users_guide/5-02-notes.sgml +++ b/ghc/docs/users_guide/5-02-notes.sgml @@ -1,143 +1,21 @@ -<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 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>––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> diff --git a/ghc/docs/users_guide/ffi-chap.sgml b/ghc/docs/users_guide/ffi-chap.sgml index 9009a509f4..4534b07000 100644 --- a/ghc/docs/users_guide/ffi-chap.sgml +++ b/ghc/docs/users_guide/ffi-chap.sgml @@ -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> diff --git a/ghc/docs/users_guide/flags.sgml b/ghc/docs/users_guide/flags.sgml index 8514c48a47..aaf87bf189 100644 --- a/ghc/docs/users_guide/flags.sgml +++ b/ghc/docs/users_guide/flags.sgml @@ -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> diff --git a/ghc/docs/users_guide/ghci.sgml b/ghc/docs/users_guide/ghci.sgml index 14c1126aa2..0919b20394 100644 --- a/ghc/docs/users_guide/ghci.sgml +++ b/ghc/docs/users_guide/ghci.sgml @@ -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: - <stmt> evaluate/run <stmt> - :cd <dir> change directory to <dir> - :def <cmd> <expr> define a macro :<cmd> - :help, :? display this list of commands - :load <filename> load a module (and it dependents) - :module <mod> set the context for expression evaluation to <mod> - :reload reload the current module set - :set <option> ... set options - :type <expr> show the type of <expr> - :unset <option> ... unset options - :quit exit GHCi - :!<command> run the shell command <command> + + %lt;stmt> evaluate/run %lt;stmt> + :add %lt;filename> ... add module(s) to the current target set + :browse [*]%lt;module> display the names defined by %lt;module> + :cd %lt;dir> change directory to %lt;dir> + :def %lt;cmd> %lt;expr> define a command :%lt;cmd> + :help, :? display this list of commands + :info [%lt;name> ...] display information about the given names + :load %lt;filename> ... load module(s) and their dependents + :module [+/-] [*]%lt;mod> ... set the context for expression evaluation + :reload reload the current module set + + :set %lt;option> ... set options + :set args %lt;arg> ... set the arguments returned by System.getArgs + :set prog %lt;progname> 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> show the type of %lt;expr> + :undef %lt;cmd> undefine user-defined command :%lt;cmd> + :unset %lt;option> ... unset options + :quit exit GHCi + :!%lt;command> run the shell command %lt;command> + 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 - -<flag> most GHC command line flags can also be set here + -%lt;flags> 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> diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml index 49d378b259..012f922c89 100644 --- a/ghc/docs/users_guide/glasgow_exts.sgml +++ b/ghc/docs/users_guide/glasgow_exts.sgml @@ -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#</literal>s around your program), you may wish to check if there are libraries that provide a -“Haskellised veneer” over the features you want. See -<xref linkend="book-hslibs">. +“Haskellised veneer” 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>‘.’</literal>. This is also known as the + “hierarchical module namespace” extension, because + it extends the normally flat Haskell module namespace into a + more flexible hierarchy of modules.</para> + + <para>A module name in the extended syntax consists of a + sequence of components, each separated by a dot. When searching + for an interface file (or a source file, in the case of GHCi or + when using <option>--make</option>) for an imported module, GHC + interprets the dot as a path separator. So for example, if a + module <literal>A.B.C</literal> is imported, then for each + directory <literal>D</literal> on the search path (see the + <option>-i</option> option, <xref + linkend="options-finding-imports">), GHC will look in the + directory <literal>D/A/B</literal><footnote><para>On Windows, + this would be <literal>D\A\B</literal>.</para></footnote> for an + interface file called <filename>C.hi</filename> or a source file + <filename>C.hs</filename> or <filename>C.lhs</filename>.</para> + + <para>Note that as far as the compiler is concerned, module + names are always fully qualified; the hierarchy only has a + special meaning when searching for interface files and source + files in the filesystem. In particular, this means that the + full module name must be given after the + <literal>module</literal> keyword at the beginning of the + module; for example, the module <literal>A.B.C</literal> must + begin</para> + +<programlisting>module A.B.C</programlisting> + + <para>GHC comes with a large collection of libraries arranged + hierarchically; see the accompanying library documentation. + There is an ongoing project to create and maintain a stable set + of <quote>core</quote> libraries used by several Haskell + compilers, and the libraries that GHC comes with represent the + current status of that project. For more details, see <ulink + url="http://www.haskell.org/~simonmar/libraries/libraries.html">.</ulink></para> + + </sect2> + <!-- ====================== PATTERN GUARDS ======================= --> <sect2 id="pattern-guards"> @@ -2554,14 +2605,18 @@ qualifier list has just one element, a boolean expression. <title>Rebindable syntax</title> - <para> Your may want to - define your own numeric class hierarchy. It completely - defeats that purpose if the literal "1" means - "<literal>Prelude.fromInteger 1</literal>", which is what - the Haskell Report specifies. So the - <option>-fno-implicit-prelude</option> flag causes the - following pieces of built-in syntax to refer to <emphasis>whatever - is in scope</emphasis>, not the Prelude versions:</para> + <para>GHC allows most kinds of built-in syntax to be rebound by + the user, to facilitate replacing the <literal>Prelude</literal> + with a home-grown version, for example.</para> + + <para>You may want to define your own numeric class + hierarchy. It completely defeats that purpose if the + literal "1" means "<literal>Prelude.fromInteger + 1</literal>", which is what the Haskell Report specifies. + So the <option>-fno-implicit-prelude</option> flag causes + the following pieces of built-in syntax to refer to + <emphasis>whatever is in scope</emphasis>, not the Prelude + versions:</para> <itemizedlist> <listitem> @@ -2587,11 +2642,12 @@ qualifier list has just one element, a boolean expression. </listitem> <listitem> - <para>"Do" notation is translated using whatever functions - <literal>(>>=)</literal>, <literal>(>>)</literal>, <literal>fail</literal>, - and <literal>return</literal>, are in scope (not the Prelude versions). - List comprehensions, and parallel array comprehensions, are unaffected. - </para></listitem> + <para>"Do" notation is translated using whatever + functions <literal>(>>=)</literal>, + <literal>(>>)</literal>, <literal>fail</literal>, and + <literal>return</literal>, are in scope (not the Prelude + versions). List comprehensions, and parallel array + comprehensions, are unaffected. </para></listitem> </itemizedlist> <para>Be warned: this is an experimental facility, with fewer checks than diff --git a/ghc/docs/users_guide/gone_wrong.sgml b/ghc/docs/users_guide/gone_wrong.sgml index 93585da1a4..2f0321cd8f 100644 --- a/ghc/docs/users_guide/gone_wrong.sgml +++ b/ghc/docs/users_guide/gone_wrong.sgml @@ -174,10 +174,6 @@ <para>Of course, if you have foreign calls in your program then all bets are off, because you can trash the heap, the stack, or whatever.</para> - - <para>If you are interested in hard-core debugging of a - crashing GHC-compiled program, please see <xref - linkend="hard-core-debug">.</para> </listitem> </varlistentry> diff --git a/ghc/docs/users_guide/installing.sgml b/ghc/docs/users_guide/installing.sgml index 15d5aa85df..42f48c1390 100644 --- a/ghc/docs/users_guide/installing.sgml +++ b/ghc/docs/users_guide/installing.sgml @@ -44,10 +44,11 @@ but it's useful if you are changing the implementation. </para> </listitem> <variablelist> <varlistentry> - <term>RedHat Linux/x86</term> + <term>RedHat or SuSE Linux/x86</term> <listitem> - <para>RPM source & binary packages for RedHat Linux (x86 - only) are available for most major releases.</para> + <para>RPM source & binary packages for RedHat and SuSE + Linux (x86 only) are available for most major + releases.</para> </listitem> </varlistentry> @@ -95,8 +96,9 @@ Binary distributions come in “bundles,” one bundle per file called </Para> <Para> -Then you should find a single directory, <Literal>fptools</Literal>, with the following -structure: +Then you should find a single directory, +<Literal>ghc-<replaceable>version</replaceable></Literal>, with the +following structure: </Para> <Para> diff --git a/ghc/docs/users_guide/intro.sgml b/ghc/docs/users_guide/intro.sgml index d1f838e78d..6e877b45cd 100644 --- a/ghc/docs/users_guide/intro.sgml +++ b/ghc/docs/users_guide/intro.sgml @@ -41,8 +41,8 @@ details.</para> <para>GHC comes with a large collection of libraries, with - everything from parser combinators to networking. These are all - described in <xref linkend="book-hslibs">.</para> + everything from parser combinators to networking. The libraries are + described in separate documentation.</para> <Sect1 id="mailing-lists-GHC"> <Title>Meta-information: Web sites, mailing lists, etc.</Title> @@ -383,7 +383,7 @@ </sect1> -&relnotes +&relnotes; </Chapter> diff --git a/ghc/docs/users_guide/packages.sgml b/ghc/docs/users_guide/packages.sgml index b778a503b9..6faac0aaf6 100644 --- a/ghc/docs/users_guide/packages.sgml +++ b/ghc/docs/users_guide/packages.sgml @@ -13,8 +13,8 @@ are also a good way to provide convenient access to a Haskell layer over a C library.</para> - <para>GHC comes with several packages (see <xref - linkend="book-hslibs">), and packages can be added to or removed + <para>GHC comes with several packages (see the accompanying + library documentation), and packages can be added to or removed from an existing GHC installation, using the supplied <literal>ghc-pkg</literal><indexterm><primary><literal>ghc-pkg</literal></primary> </indexterm> tool, described in <xref @@ -534,7 +534,7 @@ <secondary>package specification</secondary></indexterm> <listitem> <para>On Darwin/MacOS X, a list of directories containing frameworks for this - package. This corresponds to the <option>-framework-path</options> option. + package. This corresponds to the <option>-framework-path</option> option. It is ignored on all other platforms.</para> </listitem> </varlistentry> diff --git a/ghc/docs/users_guide/parallel.sgml b/ghc/docs/users_guide/parallel.sgml index a7739bf2ea..9a6502ac41 100644 --- a/ghc/docs/users_guide/parallel.sgml +++ b/ghc/docs/users_guide/parallel.sgml @@ -62,7 +62,8 @@ Web Page. <Para> Some details about Parallel Haskell follow. For more information -about concurrent Haskell, see <xref linkend="sec-Concurrent">. +about concurrent Haskell, see the module +<literal>Control.Concurrent</literal> in the library documentation. </Para> <Sect2> diff --git a/ghc/docs/users_guide/phases.sgml b/ghc/docs/users_guide/phases.sgml index b3f488339c..81f529731b 100644 --- a/ghc/docs/users_guide/phases.sgml +++ b/ghc/docs/users_guide/phases.sgml @@ -482,7 +482,7 @@ strmod = "\ This option corresponds to the <option>-framework</option> option for Apple's Linker. Please note that frameworks and packages are two different things - frameworks don't contain any haskell code. Rather, they are Apple's way of packaging shared libraries. - To link to Apple's “Carbon&qdquo; API, for example, you'd use + To link to Apple's “Carbon” API, for example, you'd use <option>-framework Carbon</option>. </para> </listitem> diff --git a/ghc/docs/users_guide/primitives.sgml b/ghc/docs/users_guide/primitives.sgml index aa68d27fd5..f84794a2b4 100644 --- a/ghc/docs/users_guide/primitives.sgml +++ b/ghc/docs/users_guide/primitives.sgml @@ -1172,7 +1172,8 @@ C. </para> <para> -Please see <xref LinkEnd="sec-stable-pointers"> for more details. +Please see the module <literal>Foreign.StablePtr</literal> in the +library documentation for more details. </para> </listitem> </varlistentry> @@ -1188,7 +1189,8 @@ memory when you're done with it.” </para> <para> -Please see <xref LinkEnd="sec-ForeignObj"> for more details. +Please see module <literal>Foreign.ForeignPtr</literal> in the library +documentatation for more details. </para> </listitem> </varlistentry> diff --git a/ghc/docs/users_guide/separate_compilation.sgml b/ghc/docs/users_guide/separate_compilation.sgml index 45e6c9c251..5e0ce6ce2f 100644 --- a/ghc/docs/users_guide/separate_compilation.sgml +++ b/ghc/docs/users_guide/separate_compilation.sgml @@ -18,11 +18,14 @@ which contains a module <literal>A</literal>, say, it generates an object <filename>A.o</filename>, <emphasis>and</emphasis> a companion <emphasis>interface file</emphasis> - <filename>A.hi</filename>. The interface file is not intended - for human consumption, as you'll see if you take a look at one. - It's merely there to help the compiler compile other modules in - the same program.</para> - + <filename>A.hi</filename>. The interface file is merely there + to help the compiler compile other modules in the same program. + Interfaces are in a binary format, so don't try to look at one; + however you <emphasis>can</emphasis> see the contents of an + interface file by using GHC with the + <option>--show-iface</option> option (see <xref + linkend="hi-options">, below).</para> + <para>NOTE: In general, the name of a file containing module <literal>M</literal> should be named <filename>M.hs</filename> or <literal>M.lhs</literal>. The only exception to this rule is @@ -163,8 +166,20 @@ the labour.</para> </listitem> </varlistentry> + + <varlistentry> + <term><option>--show-iface</option> + <replaceable>file</replaceable></term> + <indexterm><primary><option>--show-iface</option></primary> + </indexterm> + <listitem> + <para>Where <replaceable>file</replaceable> is the name of + an interface file, dumps the contents of that interface in + a human-readable (ish) format.</para> + </listitem> + </varlistentry> </variablelist> - + </sect2> <sect2 id="recomp"> @@ -551,60 +566,47 @@ import {-# SOURCE #-} A would look like the following:</para> <ProgramListing> -__interface A 1 0 where -__export A TA{MkTA} ; -1 newtype TA = MkTA PrelBase.Int ; +module A where +newtype TA = MkTA GHC.Base.Int </ProgramListing> - <para>The syntax is essentially the same as a normal - <filename>.hi</filename> file (unfortunately), so you can - usually tailor an existing <filename>.hi</filename> file to make - a <filename>.hi-boot</filename> file.</para> + <para>The syntax is similar to a normal Haskell source file, but + with some important differences:</para> + + <itemizedlist> + <listitem> + <para>Non-local entities must be qualified with their + <emphasis>original</emphasis> defining module. Qualifying + by a module which just re-exports the entity won't do. In + particular, most <literal>Prelude</literal> entities aren't + actually defined in the <literal>Prelude</literal> (see for + example <literal>GHC.Base.Int</literal> in the above + example).</para> + </listitem> + <listitem> + <para>Only <literal>data</literal>, <literal>type</literal>, + <literal>newtype</literal>, <literal>class</literal>, and + type signature declarations may be included.</para> + </listitem> + </itemizedlist> <para>Notice that we only put the declaration for the newtype <literal>TA</literal> in the <literal>hi-boot</literal> file, not the signature for <Function>f</Function>, since <Function>f</Function> isn't used by <literal>B</literal>.</para> - <para>The number “1” after - “__interface A” gives the version - number of module A; it is incremented whenever anything in A's - interface file changes. In a normal interface file, the - “0” is the version number of the compiler which - generated the interface file; it is used to ensure that we don't - mix-and-match interface files between compiler versions. - Leaving it as zero in an <literal>hi-boot</literal> file turns - off this check.</para> - - <para>The number “1” at the beginning of a - declaration is the <emphasis>version number</emphasis> of that - declaration: for the purposes of <filename>.hi-boot</filename> - files these can all be set to 1. All names must be fully - qualified with the <emphasis>original</emphasis> module that an - object comes from: for example, the reference to - <literal>Int</literal> in the interface for <literal>A</literal> - comes from <literal>PrelBase</literal>, which is a module - internal to GHC's prelude. It's a pain, but that's the way it - is.</para> - <para>If you want an <literal>hi-boot</literal> file to export a data type, but you don't want to give its constructors (because the constructors aren't used by the SOURCE-importing module), you can write simply:</para> <ProgramListing> -__interface A 1 0 where -__export A TA; -1 data TA +module A where +data TA </ProgramListing> <para>(You must write all the type parameters, but leave out the '=' and everything that follows it.)</para> - - <para><emphasis>Note:</emphasis> This is all a temporary - solution, a version of the compiler that handles mutually - recursive modules properly without the manual construction of - interface files, is (allegedly) in the works.</para> </sect2> diff --git a/ghc/docs/users_guide/ug-book.sgml b/ghc/docs/users_guide/ug-book.sgml index 10dc11ecb0..cf5dd38818 100644 --- a/ghc/docs/users_guide/ug-book.sgml +++ b/ghc/docs/users_guide/ug-book.sgml @@ -1,5 +1,5 @@ <BookInfo> -<Title>The Glasgow Haskell Compiler User's Guide, Version 5.02</Title> +<Title>The Glasgow Haskell Compiler User's Guide, Version 5.04</Title> <Author><OtherName>The GHC Team</OtherName></Author> <Address> <Email>glasgow-haskell-{bugs,users}-request@haskell.org</Email> diff --git a/ghc/docs/users_guide/ug-ent.sgml b/ghc/docs/users_guide/ug-ent.sgml index 56b36f8386..ba5c6173d0 100644 --- a/ghc/docs/users_guide/ug-ent.sgml +++ b/ghc/docs/users_guide/ug-ent.sgml @@ -3,7 +3,7 @@ <!ENTITY flags SYSTEM "flags.sgml"> <!ENTITY license SYSTEM "license.sgml"> <!ENTITY intro SYSTEM "intro.sgml" > -<!ENTITY relnotes SYSTEM "5-02-notes.sgml" > +<!ENTITY relnotes SYSTEM "5-04-notes.sgml" > <!ENTITY installing SYSTEM "installing.sgml" > <!ENTITY using SYSTEM "using.sgml" > <!ENTITY runtime SYSTEM "runtime_control.sgml" > diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml index 2eaa640692..41c467d8ae 100644 --- a/ghc/docs/users_guide/using.sgml +++ b/ghc/docs/users_guide/using.sgml @@ -363,7 +363,7 @@ module X where <para>Print the path to GHC's library directory. This is the top of the directory tree containing GHC's libraries, interfaces, and include files (usually something like - <literal>/usr/local/lib/ghc-5.02</literal> on Unix). This + <literal>/usr/local/lib/ghc-5.04</literal> on Unix). This is the value of <literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary> </indexterm>in the package configuration file (see <xref @@ -1408,36 +1408,31 @@ data S = S !Int !Int </variablelist> </sect2> - + </sect1> - -&phases; - -<Sect1 id="sec-using-concurrent"> + + &phases; + + <sect1 id="sec-using-concurrent"> <title>Using Concurrent Haskell</title> -<para> -<indexterm><primary>Concurrent Haskell—use</primary></indexterm> -</para> + <indexterm><primary>Concurrent Haskell—use</primary></indexterm> <para> -GHC (as of version 4.00) supports Concurrent Haskell by default, -without requiring a special option or libraries compiled in a certain -way. To get access to the support libraries for Concurrent Haskell -(i.e. <literal>Concurrent</literal> and friends), use the -<option>-package concurrent</option> option. -</para> +GHC supports Concurrent Haskell by default, without requiring a +special option or libraries compiled in a certain way. To get access +to the support libraries for Concurrent Haskell, just import +<literal>Control.Concurrent</literal> (details are in the accompanying +library documentation).</para> <para> -Three RTS options are provided for modifying the behaviour of the -threaded runtime system. See the descriptions of -<option>-C[<us>]</option>, <option>-q</option>, and -<option>-t<num></option> in <XRef LinkEnd="parallel-rts-opts">. +RTS options are provided for modifying the behaviour of the threaded +runtime system. See <XRef LinkEnd="parallel-rts-opts">. </para> <para> -Concurrent Haskell is described in more detail in <XRef -LinkEnd="sec-Concurrent">. +Concurrent Haskell is described in more detail in the documentation +for the <literal>Control.Concurrent</literal> module. </para> </Sect1> diff --git a/ghc/docs/users_guide/utils.sgml b/ghc/docs/users_guide/utils.sgml index d58752ed1b..5260a1f16f 100644 --- a/ghc/docs/users_guide/utils.sgml +++ b/ghc/docs/users_guide/utils.sgml @@ -449,7 +449,9 @@ tags: The intention is that <literal>#peek</literal> and <literal>#poke</literal> can be used for implementing the operations of class <literal>Storable</literal> for a - given C struct (see <xref linkend="sec-Storable">).</para> + given C struct (see the + <literal>Foreign.Storable</literal> module in the library + documentation).</para> </listitem> </varlistentry> diff --git a/ghc/docs/users_guide/vs_haskell.sgml b/ghc/docs/users_guide/vs_haskell.sgml index f9e8481c6d..9eb771ee1c 100644 --- a/ghc/docs/users_guide/vs_haskell.sgml +++ b/ghc/docs/users_guide/vs_haskell.sgml @@ -239,9 +239,9 @@ main = print (array (1,1) [(1,2), (1,3)])</programlisting> integral types (<literal>Int8</literal>, <literal>Int16</literal>, <literal>Int32</literal>, <literal>Int64</literal> and the unsigned - <literal>Word</literal> variants), see <xref - linkend="sec-Int"> and <xref linkend="sec-Word">.</para> - + <literal>Word</literal> variants), see the modules + <literal>Data.Int</literal> and <literal>Data.Word</literal> + in the library documentation.</para> </listitem> </varlistentry> |