[[project @ 2002-06-25 12:05:14 by simonmar] simonmar**20020625120515 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. ] { hunk ./ghc/docs/users_guide/5-02-notes.sgml 1 - - Release notes for version 5.02 + + Release notes for version 5.04 hunk ./ghc/docs/users_guide/5-02-notes.sgml 6 - hunk ./ghc/docs/users_guide/5-02-notes.sgml 7 - - - 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. - - - - Several small changes to bring GHC into line with the - newest Haskell 98 report. - - - - RTS options can now be specified using the environment - variable GHCRTS. - - - - The maximum heap size, set with - +RTS -Msize, - now defaults to unlimited. We recommend however that you set - a maximum heap size appropriate for your machine using the - GHCRTS variable. - - - - Thanks to the heroic efforts of Ken Shan - ken@digitas.harvard.edu, 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. - - - - New option: which causes GHC - to omit code generation and all future compilation stages (see - ). - - - - New option . This makes GHC read - additional package descriptions from - file. See . - - - - flag reinstated for heap - profiling. See . - - - - now works - correctly. See . - - hunk ./ghc/docs/users_guide/5-02-notes.sgml 8 - - Many bug fixes related to implicit-parameter support. + hunk ./ghc/docs/users_guide/5-02-notes.sgml 10 - - - - Data declarations with no constructors are allowed. This - facilitates types whose only value is bottom, and which have - no representation. - - - - - You can disconnect numeric syntax from the Prelude syntax. - Doing this means you can define your own arithmetic. The - relevant flag is . See - . - - - hunk ./ghc/docs/users_guide/5-02-notes.sgml 15 - hunk ./ghc/docs/users_guide/5-02-notes.sgml 17 - GHCi now works on Windows. - - - - Partial FFI support in GHCi. At the moment, foreign - import (static and dynamic) are supported on x86 and sparc - platforms. + hunk ./ghc/docs/users_guide/5-02-notes.sgml 19 - - - New interpreter command :add, to add - modules to the current bunch. See - . - - - - New interpreter command :info, to provide - information on values, types and classes, a la Hugs. See - . - - - - Multiple target modules are supported. You may specify - multiple modules for the :add and - :load commands. From the command line, you - may specify multiple modules when starting GHCi and when - compiling in mode. See - . - - - - New flags and - . See - . - - - - When starting GHCi from the command line, you may now - use the flags - and - to - specify libraries to be loaded into the interactive - session. See . - - hunk ./ghc/docs/users_guide/5-02-notes.sgml 26 - The SocketPrim and - BSD modules in the net - 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 writeSocket, - readSocket and - readSocketAll have been removed (use - socketToHandle and - Handle operations instead). - - - - New function: Exception.throwDynTo. - See . - - - - BlockedOnDeadMVar and - ThreadKilled exceptions no longer generate - any output by default for forked threads. - - - - Weak.addForeignFinalizer is - deprecated; use the ForeignPtr library - instead. - - - - The I/O library has been completely rewritten, using the - new FFI libraries and hsc2hs. 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. - - - - As a result of the I/O rewrite, the extensions - IOExts.hConnectTo and - IOExts.withHandleFor have been removed. - Also, hGetBuf and - hPutBuf have been removed, and - hGetBufFull and - hPutBufFull have been renamed to - hGetBuf and hPutBuf - respectively (similary for the BA - versions of these functions). - - - - System.exitWith now throws - ExitException rather than causing the - program to exit immediately. ExitException - is by default caught by the top level exception handler in the - main thread, where it causes the program to exit. Hence, calling - System.exitWith in GHCi no longer causes - GHCi itself to exit. - - - - New function: MVar.addMVarFinalizer - (see ). - - - - New module SystemExts for useful - system-ish functionality (see ). - - - - SocketPrim: added instances of - Eq and Show for the - Socket type. - - - - The implementation of - MarsalAlloc.allocaBytes now uses GHC's - internal allocator and is much faster than before. As a - result, the UnsafeCString type and - functions are no longer necessary and have been removed from - CString. + hunk ./ghc/docs/users_guide/5-02-notes.sgml 33 - hunk ./ghc/docs/users_guide/5-02-notes.sgml 34 - - - - Partial support for hierarchical module names. - - hunk ./ghc/docs/users_guide/5-02-notes.sgml 35 - 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. - - - - 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 An External Representation for the GHC Core Language. - We also have sample - tools for reading, writing and typechecking external Core, - available in the source distribution directory /fptools/ghc/utils/ext-core. - Ultimately we plan that Core files can also be read by - GHC. The relevant flag is . - - - - - 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 ). 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. + hunk ./ghc/docs/users_guide/5-02-notes.sgml 44 - The implementation of the Array, - IArray and MArray - libraries have been rewritten so that bulk operations like - listArray and elems do - less range checking and hence go faster. - - - - The CPUTime library has been replaced - by one written using the FFI. No externally visible - changes. - - - - The compiler has a new strictness-and-absence analyser, - which is alleged to help it generate better code. + hunk ./ghc/docs/users_guide/5-02-notes.sgml 46 - hunk ./ghc/docs/users_guide/ffi-chap.sgml 33 - The FFI libraries are documented in . - + The FFI libraries are documented in the accompanying library + documentation; see for example the Foreign + module. hunk ./ghc/docs/users_guide/flags.sgml 302 + + file + Read the interface in + file and dump it as text to + stdout. + static + - + hunk ./ghc/docs/users_guide/flags.sgml 1103 - name + name hunk ./ghc/docs/users_guide/flags.sgml 1105 - This option corresponds to the option for Apple's Linker. + This option corresponds to the option for Apple's Linker. hunk ./ghc/docs/users_guide/flags.sgml 1110 - name + name hunk ./ghc/docs/users_guide/flags.sgml 1113 - This option corresponds to the option for Apple's Linker. + This option corresponds to the option for Apple's Linker. hunk ./ghc/docs/users_guide/ghci.sgml 12 - you're famililar with HugsHugs + you're famililar with HugsHugs hunk ./ghc/docs/users_guide/ghci.sgml 16 - the language extensions that GHC provides. + the language extensions that GHC provides. hunk ./ghc/docs/users_guide/ghci.sgml 30 - / /_\// /_/ / / | | GHC Interactive, version 5.00, For Haskell 98. + / /_\// /_/ / / | | GHC Interactive, version 5.04, for Haskell 98. hunk ./ghc/docs/users_guide/ghci.sgml 34 -Loading package std ... linking ... done. +Loading package base ... linking ... done. +Loading package haskell98 ... linking ... done. hunk ./ghc/docs/users_guide/ghci.sgml 46 - <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> + hunk ./ghc/docs/users_guide/ghci.sgml 72 + hunk ./ghc/docs/users_guide/ghci.sgml 76 - -<flag> most GHC command line flags can also be set here + -%lt;flags> most GHC command line flags can also be set here hunk ./ghc/docs/users_guide/ghci.sgml 221 - copy of package std, which contains the Prelude - and standard libraries. + copy of the base package, which contains the + Prelude. hunk ./ghc/docs/users_guide/ghci.sgml 544 - interface (see for more - information on GHC's Exception support). + interface (for more information on exceptions, see the module + Control.Exception in the libraries + documentation). hunk ./ghc/docs/users_guide/ghci.sgml 659 - For example, to start up GHCi with the text + For example, to start up GHCi with the network hunk ./ghc/docs/users_guide/ghci.sgml 663 -$ ghci -package text +$ ghci -package network hunk ./ghc/docs/users_guide/ghci.sgml 666 - / /_\// /_/ / / | | GHC Interactive, version 5.00, For Haskell 98. + / /_\// /_/ / / | | GHC Interactive, version 5.04, for Haskell 98. hunk ./ghc/docs/users_guide/ghci.sgml 670 -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. hunk ./ghc/docs/users_guide/ghci.sgml 676 - Note that GHCi also loaded the lang - package even though we didn't ask for it: that's because the - text package makes use of one or more of the - modules in lang, and therefore has a - dependency on it. + Note that GHCi will also automatically load any packages + on which the requested package depends. hunk ./ghc/docs/users_guide/glasgow_exts.sgml 22 -“Haskellised veneer” over the features you want. See -. +“Haskellised veneer” over the features you want. The +separate libraries documentation describes all the libraries that come +with GHC. hunk ./ghc/docs/users_guide/glasgow_exts.sgml 167 + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 172 + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 174 -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. +type can be parameterised over types of any kind, but if the kind is +not * then an explicit kind annotation must be used +(see ). hunk ./ghc/docs/users_guide/glasgow_exts.sgml 900 -An implicit parameter is bound using an expression of the form -expr with binds, -where with is a new keyword. This form binds the implicit -parameters arising in the body, not the free variables as a let or -where would do. For example, we define the min function by binding -cmp. +An implicit parameter is bound using the standard +let 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 +let or where would do. For +example, we define the min function by binding +cmp. hunk ./ghc/docs/users_guide/glasgow_exts.sgml 911 - min = least with ?cmp = (<=) + min = let ?cmp = (<=) in least hunk ./ghc/docs/users_guide/glasgow_exts.sgml 913 -Syntactically, the binds part of a with 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. - hunk ./ghc/docs/users_guide/glasgow_exts.sgml 1383 - + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 2350 -applications of Exception.assert, so you can still define and -use your own versions of assert, should you so wish. If not, -import Exception to make use assert in your code. +applications of Control.Exception.assert, so you +can still define and use your own versions of +assert, should you so wish. If not, import +Control.Exception to make use +assert in your code. hunk ./ghc/docs/users_guide/glasgow_exts.sgml 2359 -. -fignore-asserts option That is, -expressions of the form assert pred e will be rewritten to e. +. -fignore-asserts +option That is, expressions of the form +assert pred e will be rewritten to +e. hunk ./ghc/docs/users_guide/glasgow_exts.sgml 2367 -Exception library () -for the details. +Control.Exception library for the details. hunk ./ghc/docs/users_guide/glasgow_exts.sgml 2376 + + + + Hierarchical Modules + + GHC supports a small extension to the syntax of module + names: a module name is allowed to contain a dot + ‘.’. 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. + + 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 ) for an imported module, GHC + interprets the dot as a path separator. So for example, if a + module A.B.C is imported, then for each + directory D on the search path (see the + option, ), GHC will look in the + directory D/A/BOn Windows, + this would be D\A\B. for an + interface file called C.hi or a source file + C.hs or C.lhs. + + 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 + module keyword at the beginning of the + module; for example, the module A.B.C must + begin + +module A.B.C + + 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 core libraries used by several Haskell + compilers, and the libraries that GHC comes with represent the + current status of that project. For more details, see . + + + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 2608 - Your may want to - define your own numeric class hierarchy. It completely - defeats that purpose if the literal "1" means - "Prelude.fromInteger 1", which is what - the Haskell Report specifies. So the - flag causes the - following pieces of built-in syntax to refer to whatever - is in scope, not the Prelude versions: + GHC allows most kinds of built-in syntax to be rebound by + the user, to facilitate replacing the Prelude + with a home-grown version, for example. + + You may want to define your own numeric class + hierarchy. It completely defeats that purpose if the + literal "1" means "Prelude.fromInteger + 1", which is what the Haskell Report specifies. + So the flag causes + the following pieces of built-in syntax to refer to + whatever is in scope, not the Prelude + versions: hunk ./ghc/docs/users_guide/glasgow_exts.sgml 2645 - "Do" notation is translated using whatever functions - (>>=), (>>), fail, - and return, are in scope (not the Prelude versions). - List comprehensions, and parallel array comprehensions, are unaffected. - + "Do" notation is translated using whatever + functions (>>=), + (>>), fail, and + return, are in scope (not the Prelude + versions). List comprehensions, and parallel array + comprehensions, are unaffected. hunk ./ghc/docs/users_guide/gone_wrong.sgml 177 - - If you are interested in hard-core debugging of a - crashing GHC-compiled program, please see . hunk ./ghc/docs/users_guide/installing.sgml 47 - RedHat Linux/x86 + RedHat or SuSE Linux/x86 hunk ./ghc/docs/users_guide/installing.sgml 49 - RPM source & binary packages for RedHat Linux (x86 - only) are available for most major releases. + RPM source & binary packages for RedHat and SuSE + Linux (x86 only) are available for most major + releases. hunk ./ghc/docs/users_guide/installing.sgml 99 -Then you should find a single directory, fptools, with the following -structure: +Then you should find a single directory, +ghc-version, with the +following structure: hunk ./ghc/docs/users_guide/intro.sgml 44 - everything from parser combinators to networking. These are all - described in . + everything from parser combinators to networking. The libraries are + described in separate documentation. hunk ./ghc/docs/users_guide/intro.sgml 386 -&relnotes +&relnotes; hunk ./ghc/docs/users_guide/packages.sgml 16 - GHC comes with several packages (see ), and packages can be added to or removed + GHC comes with several packages (see the accompanying + library documentation), and packages can be added to or removed hunk ./ghc/docs/users_guide/packages.sgml 537 - package. This corresponds to the option. hunk ./ghc/docs/users_guide/parallel.sgml 65 -about concurrent Haskell, see . +about concurrent Haskell, see the module +Control.Concurrent in the library documentation. hunk ./ghc/docs/users_guide/phases.sgml 485 - 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 hunk ./ghc/docs/users_guide/primitives.sgml 1175 -Please see for more details. +Please see the module Foreign.StablePtr in the +library documentation for more details. hunk ./ghc/docs/users_guide/primitives.sgml 1192 -Please see for more details. +Please see module Foreign.ForeignPtr in the library +documentatation for more details. hunk ./ghc/docs/users_guide/separate_compilation.sgml 21 - A.hi. 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. - + A.hi. 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 can see the contents of an + interface file by using GHC with the + option (see , below). + hunk ./ghc/docs/users_guide/separate_compilation.sgml 169 + + + + file + + + + Where file is the name of + an interface file, dumps the contents of that interface in + a human-readable (ish) format. + + hunk ./ghc/docs/users_guide/separate_compilation.sgml 182 - + hunk ./ghc/docs/users_guide/separate_compilation.sgml 569 -__interface A 1 0 where -__export A TA{MkTA} ; -1 newtype TA = MkTA PrelBase.Int ; +module A where +newtype TA = MkTA GHC.Base.Int hunk ./ghc/docs/users_guide/separate_compilation.sgml 573 - The syntax is essentially the same as a normal - .hi file (unfortunately), so you can - usually tailor an existing .hi file to make - a .hi-boot file. + The syntax is similar to a normal Haskell source file, but + with some important differences: + + + + Non-local entities must be qualified with their + original defining module. Qualifying + by a module which just re-exports the entity won't do. In + particular, most Prelude entities aren't + actually defined in the Prelude (see for + example GHC.Base.Int in the above + example). + + + Only data, type, + newtype, class, and + type signature declarations may be included. + + hunk ./ghc/docs/users_guide/separate_compilation.sgml 598 - 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 hi-boot file turns - off this check. - - The number “1” at the beginning of a - declaration is the version number of that - declaration: for the purposes of .hi-boot - files these can all be set to 1. All names must be fully - qualified with the original module that an - object comes from: for example, the reference to - Int in the interface for A - comes from PrelBase, which is a module - internal to GHC's prelude. It's a pain, but that's the way it - is. - hunk ./ghc/docs/users_guide/separate_compilation.sgml 604 -__interface A 1 0 where -__export A TA; -1 data TA +module A where +data TA hunk ./ghc/docs/users_guide/separate_compilation.sgml 610 - - Note: 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. hunk ./ghc/docs/users_guide/ug-book.sgml 2 -The Glasgow Haskell Compiler User's Guide, Version 5.02 +The Glasgow Haskell Compiler User's Guide, Version 5.04 hunk ./ghc/docs/users_guide/ug-ent.sgml 6 - + hunk ./ghc/docs/users_guide/using.sgml 366 - /usr/local/lib/ghc-5.02 on Unix). This + /usr/local/lib/ghc-5.04 on Unix). This hunk ./ghc/docs/users_guide/using.sgml 1411 - + hunk ./ghc/docs/users_guide/using.sgml 1413 - -&phases; - - + + &phases; + + hunk ./ghc/docs/users_guide/using.sgml 1419 - -Concurrent Haskell—use - + Concurrent Haskell—use hunk ./ghc/docs/users_guide/using.sgml 1422 -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. Concurrent and friends), use the - option. - +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 +Control.Concurrent (details are in the accompanying +library documentation). hunk ./ghc/docs/users_guide/using.sgml 1429 -Three RTS options are provided for modifying the behaviour of the -threaded runtime system. See the descriptions of -, , and - in . +RTS options are provided for modifying the behaviour of the threaded +runtime system. See . hunk ./ghc/docs/users_guide/using.sgml 1434 -Concurrent Haskell is described in more detail in . +Concurrent Haskell is described in more detail in the documentation +for the Control.Concurrent module. hunk ./ghc/docs/users_guide/utils.sgml 452 - given C struct (see ). + given C struct (see the + Foreign.Storable module in the library + documentation). hunk ./ghc/docs/users_guide/vs_haskell.sgml 242 - Word variants), see and . - + Word variants), see the modules + Data.Int and Data.Word + in the library documentation. }