diff options
| author | partain <unknown> | 1996-01-08 20:28:12 +0000 |
|---|---|---|
| committer | partain <unknown> | 1996-01-08 20:28:12 +0000 |
| commit | e7d21ee4f8ac907665a7e170c71d59e13a01da09 (patch) | |
| tree | 93715bf4e6e4bbe8049e4d8d4d3fbd19158a88d6 /ghc/docs | |
| parent | e48474bff05e6cfb506660420f025f694c870d38 (diff) | |
| download | haskell-e7d21ee4f8ac907665a7e170c71d59e13a01da09.tar.gz | |
[project @ 1996-01-08 20:28:12 by partain]
Initial revision
Diffstat (limited to 'ghc/docs')
94 files changed, 20249 insertions, 0 deletions
diff --git a/ghc/docs/ANNOUNCE-0.06 b/ghc/docs/ANNOUNCE-0.06 new file mode 100644 index 0000000000..8a1b6334c3 --- /dev/null +++ b/ghc/docs/ANNOUNCE-0.06 @@ -0,0 +1,116 @@ + The Glasgow Haskell Compiler + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Version 0.06 --- Hackers' release + +As many of you know, we have been working hard at Glasgow on a modular +Haskell compiler. We are proud to announce its first public release. + +We are calling it a "Hackers' release" because it is not yet suitable +for Haskell *programmers*. It is intended for *implementors* who are +interested in using our compiler as a substrate for their own work. +(A later version will indeed be a "Programmers' release".) We also +hope that some *porters*, people who would like to see Haskell running +on their system, will help us debug any Sun dependencies in our +generated C files. Finally, the *curious* may simply want to see the +World's Largest Haskell Program (40,000 lines?)! + +The compiler has the following characteristics: + + * It is written in Haskell. + + * It generates C as its target code. + + * It is specifically designed to be modular, so that others can + use it as a "motherboard" into which they can "plug in" their + latest whizzy strictness analyser, profiler, or whatever. + + * Internally, it uses the polymorphic second-order lambda calculus + as a way to preserve correct type information in the face of + substantial program transformations. + + * It implements unboxed values as described in [1]. In + particular, the implementation of arithmetic and the exploitation + of strictness analysis is handled just as described there. + + * Its back end is based on the Spineless Tagless G-machine, an + abstract machine for non-strict functional languages. There is a + detailed paper describing this work [2]. + + * It plants code to gather quite a lot of simple profiling + information. + + * Its runtime system is heavily configurable. For example, it + comes complete with three different garbage collectors: two-space, + one-space compacting, and Appel-style generational. Adding extra + fields to heap objects (for debugging or profiling for example) is + just a question of altering C macros; the Haskell source doesn't + need to be recompiled. (Caveat: you have to alter them *right*!) + +The compiler also suffers its fair share of deficiencies: + + * The compiler itself is large and slow. + + * The code it generates is very, very unoptimised. Any + comparisons you make of runtime speed with good existing compilers + will be deeply unflattering. (Our next priority is optimisation.) + + * Several language features aren't dealt with. This has not + prevented us from compiling and running several quite large + Haskell programs. + +Please follow the pointers in the top-level README file to find all of +the documentation in and about this release. Distribution info +follows below. + +We hope you enjoy this system, and we look forward to hearing about +your successes with it! Please report bugs to +glasgow-haskell-bugs@dcs.glasgow.ac.uk and direct general queries to +glasgow-haskell-request@<same>. + +Simon Peyton Jones +(and his GRASPing colleagues) +...................................................................... + +References +~~~~~~~~~~ +[1] Simon L Peyton Jones and John Launchbury, "Unboxed values as first +class citizens", Functional Programming Languages and Computer +Architecture, Boston, ed Hughes, LNCS 523, Springer Verlag, Sept 1991. + +[2] Simon L Peyton Jones, "Implementing lazy functional languages on +stock hardware: the Spineless Tagless G-machine", Journal of +Functional Programming (to appear). Also obtainable by anonymous FTP +from ftp.dcs.glasgow.ac.uk:pub/glasgow-fp/stg.dvi. + +Distribution +~~~~~~~~~~~~ +This release is available, in whole or in part, from the usual Haskell +anonymous FTP sites, in the directory pub/haskell/glasgow: + + nebula.cs.yale.edu (128.36.13.1) + ftp.dcs.glasgow.ac.uk (130.209.240.50) + animal.cs.chalmers.se (129.16.225.66) + +(Beleaguered NIFTP users within the UK can get the same files by using +a <FP>/haskell/glasgow prefix, instead of pub/haskell/glasgow.) + +These are the available files (for the ON DEMAND ones, please ask): + +ghc-0.06-src.tar.Z the basic source distribution; assumes you + will compile it with Chalmers HBC, version + 0.997.3 or later. + +ghc-0.06-proto-hi-files.tar.Z + An "overlay" of .hi interface files, to be + used when compiling with the *prototype* + Glasgow Haskell compiler (version 0.411 or + later). + +ghc-0.06-hc-files.tar.Z An "overlay" of .hc generated-C files; used + either to save you the trouble of compiling + the prelude, or because your only interest is + porting the C to + +ghc-0.06-tests.tar.Z Some of our test files we have used in getting + this beast going. We hope to grow them into a + semi-respectable benchmark suite. diff --git a/ghc/docs/ANNOUNCE-0.10 b/ghc/docs/ANNOUNCE-0.10 new file mode 100644 index 0000000000..04062f1c73 --- /dev/null +++ b/ghc/docs/ANNOUNCE-0.10 @@ -0,0 +1,135 @@ + The Glasgow Haskell Compiler + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We are happy to announce the first full release of the Glasgow Haskell +Compiler (GHC, version 0.10). It is freely available by FTP; details +appear below. + +To run this release, you need a Sun4, probably with 16+MB memory, and +GNU C (gcc), version 2.1 or greater, and "perl". If building from +source, you will need Chalmers HBC, version 0.998.x. + +We hope you enjoy this system, and we look forward to hearing about +your successes with it! Please report bugs to +glasgow-haskell-bugs@dcs.glasgow.ac.uk and direct general queries to +glasgow-haskell-request@<same>. + +Simon Peyton Jones +(and his GRASPing colleagues) + +Why a Haskell programmer might want to use GHC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Almost all of Haskell is implemented. In particular, the full range + of data types is supported: arbitrary precision integers, rationals, + double-precision floats, and "real" arrays with O(1) access time. + (The release notes list all unimplemented language features.) + +* An extensible I/O system is provided, based on a "monad" [1]. (The + standard Haskell I/O system is built on this foundation.) + +* A number of significant language extensions are implemented: + - Fully fledged unboxed data types [2]. + - Ability to write arbitrary in-line C-language code, using + the I/O monad to retain referential transparency. + - Incrementally-updatable arrays, also embedded in a monad. + - Mutable reference types. + +* By default, the system uses a generational garbage collector which + lets you run programs whose live data is significantly larger than + the physical memory size before thrashing occurs. (Conventional + 2-space GC starts thrashing when the live data gets to about half + the physical memory size.) + +* A new profiling system is supplied, which enables you to find out which + bits of your program are eating both *time* and the *space* [3]. + +* Good error messages. Well, fairly good error messages. Line + numbers are pretty accurate, and during type checking you get + several (accurate) error reports rather than just one. + +* Performance: programs compiled with GHC "usually" beat + Chalmers-HBC-compiled ones. If you find programs where HBC wins, + send them to us :-). + +* We have a pretty good test suite, and this version passes + practically all of it. (Yes, it can compile itself, too.) We hope + you will find the system to be robust. + +Why a functional-language implementor might want to use GHC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* We have tried very hard to write the compiler in a modular and + well-documented way, so that other researchers can modify and extend + it. One of our goals is specifically to provide a framework to + support others' work. Several people are already using it in this + way. + +* Highly configurable runtime system. Heavy use of C macros means + that you can modify much of the storage representation without + telling the compiler. For example, the system comes with 4 + different garbage collectors! (all working) + +* Internals: extensive use of the second-order lambda calculus as an + intermediate code; the Spineless Tagless G-machine as evaluation + model [4]. + +* Various performance-measurement hooks. + +Main shortcomings +~~~~~~~~~~~~~~~~~ +* No interactive system. This is a batch compiler only. (Any + volunteers?) + +* Compiler is greedy on resources. Going via C doesn't help here. + +* This system should run on any Unix box. We haven't had time to do + any non-Sun4 ports. Help or prodding welcome. + +References +~~~~~~~~~~ +All these papers come with the distribution [in ghc/docs/papers]. + +[1] "Imperative functional programming", Peyton Jones & Wadler, POPL '93 + +[2] "Unboxed data types as first-class citizens", Peyton Jones & + Launchbury, FPCA '91 + +[3] "Profiling lazy functional languages", Sansom & Peyton Jones, + Glasgow workshop '92 + +[4] "Implementing lazy functional languages on stock hardware", Peyton + Jones, Journal of Functional Programming, Apr 1992 + +How to get it +~~~~~~~~~~~~~ +This release is available, in whole or in part, from the usual Haskell +anonymous FTP sites, in the directory pub/haskell/glasgow: + + nebula.cs.yale.edu (128.36.13.1) + ftp.dcs.glasgow.ac.uk (130.209.240.50) + animal.cs.chalmers.se (129.16.225.66) + +(Beleaguered NIFTP users within the UK can get the same files from +Glasgow by using a <FP>/haskell/glasgow prefix, instead of +pub/haskell/glasgow. Also, we are mirrored by src.doc.ic.ac.uk, in +languages/haskell/glasgow, and you can get files from there by every +means known to humanity.) + +These are the available files: + +ghc-0.10-src.tar.Z The basic source distribution; assumes you + will compile it with Chalmers HBC, version + 0.998.n, on a Sun4, for which you have GNU C + (gcc) version 2.1 or greater. About 3MB. + +ghc-0.10-bin-sun4.tar.Z A binary distribution -- avoid compiling + altogether! For SunOS 4.1.x; assumes you + have GNU C (gcc) version 2.x around... + +ghc-0.10-patch-* Patches to the original distribution. There + are none to start with, of course, but there + might be by the time you grab the files. + Please check for them. + +Once you have the distribution, please follow the pointers in the +ghc/README file to find all of the documentation in and about this +release. diff --git a/ghc/docs/ANNOUNCE-0.16 b/ghc/docs/ANNOUNCE-0.16 new file mode 100644 index 0000000000..f6425661e4 --- /dev/null +++ b/ghc/docs/ANNOUNCE-0.16 @@ -0,0 +1,146 @@ + The Glasgow Haskell Compiler -- version 0.16 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The second public release of the Glasgow Haskell Compiler is now +available (GHC, version 0.16). Binaries (recommended) and source are +freely available by FTP; details appear below. + +GHC 0.16 is still alpha-quality software. This release in an interim +measure, not as solid as I would prefer. However, a lot has gone in +since December. The profiling system is Way Cool. The compiler now +has a strictness analyser and an update analyser. Compiled programs +tend to run faster. Compilation speed is worse. Bugs remain, but +they tend to be work-around-able. + +To run this release, you need a Sun4 or Sun3, probably with 16+MB +memory, and GNU C (gcc), version 2.1 or greater, and "perl". + +This system can be built from source using: itself (most likely to +succeed), the previous GHC release (0.10) [least likely], or the +Chalmers HBC compiler [in-between]. Please see the appropriate +documentation for details. + +Please report bugs to glasgow-haskell-bugs@dcs.glasgow.ac.uk and +direct general queries to glasgow-haskell-request@<same>. + +Will Partain +(typist for the AQUA [formerly GRASP] project) + +.................................................................... + +Why a Haskell programmer might want to use GHC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* GHC provides an extensible I/O system, based on a "monad" [1]. (The + standard Haskell I/O system is built on this foundation.) + +* A number of significant language extensions are implemented: + - Fully fledged unboxed data types [2]. + - Ability to write arbitrary in-line C-language code, using + the I/O monad to retain referential transparency. + - Incrementally-updatable arrays, also embedded in a monad. + - Mutable reference types. + +* A new profiling system is supplied, which enables you to find out + which bits of your program are eating both *time* and the *space* [3]. + +* By default, the system uses a generational garbage collector which + lets you run programs whose live data is significantly larger than + the physical memory size before thrashing occurs. (Conventional + 2-space GC starts thrashing when the live data gets to about half + the physical memory size.) + +* Good error messages. Well, fairly good error messages. Line + numbers are pretty accurate, and during type checking you get + several (accurate) error reports rather than just one. + +* Performance: programs compiled with GHC "often" beat + Chalmers-HBC-compiled ones. If you find programs where HBC wins, + please report it to us, as a bug :-). + +Why a functional-language implementor might want to use GHC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* We have tried very hard to write the compiler in a modular and + well-documented way, so that other researchers can modify and extend + it. One of our goals is specifically to provide a framework to + support others' work. Several people are already using it in this + way. + +* Highly configurable runtime system. Heavy use of C macros means + that you can modify much of the storage representation without + telling the compiler. For example, the system comes with 4 + different garbage collectors! (all working) + +* Internals: extensive use of the second-order lambda calculus as an + intermediate code; the Spineless Tagless G-machine as evaluation + model [4]. + +* Various performance-measurement hooks. + +Main shortcomings +~~~~~~~~~~~~~~~~~ +* No interactive system. This is a batch compiler only. (Any + volunteers?) + +* Compiler is greedy on resources. Going via C doesn't help here. + +* This system should run on any Unix box. We haven't had time to do + any non-Sun ports. Help or prodding welcome. + +References +~~~~~~~~~~ +All these papers come with the distribution [in ghc/docs/papers]. + +[1] "Imperative functional programming", Peyton Jones & Wadler, POPL '93 + +[2] "Unboxed data types as first-class citizens", Peyton Jones & + Launchbury, FPCA '91 + +[3] "Profiling lazy functional languages", Sansom & Peyton Jones, + Glasgow workshop '92 + +[4] "Implementing lazy functional languages on stock hardware", Peyton + Jones, Journal of Functional Programming, Apr 1992 + +How to get it +~~~~~~~~~~~~~ +This release is available, in whole or in part, from the usual Haskell +anonymous FTP sites, in the directory pub/haskell/glasgow: + + ftp.dcs.glasgow.ac.uk (130.209.240.50) + ftp.cs.chalmers.se (129.16.225.66) + nebula.cs.yale.edu (128.36.13.1) + +We are mirrored by src.doc.ic.ac.uk, in +computing/programming/languages/haskell/glasgow, and you can get files +from there by every means known to humanity. + +These are the available files (.Z for compressed, .gz for gzipped) -- +some are `on demand', ask if you don't see them: + +ghc-0.16-bin-sun4.tar.{Z,gz} A binary distribution -- avoid compiling + altogether! For SunOS 4.1.x; assumes you have + GNU C (gcc) version 2.x around... + +ghc-0.16-src.tar.gz The basic source distribution; about 3MB. + +ghc-0.16-hi-files-{hbc,ghc-0.10}.tar.gz + Interface files for the compiler proper + (ghc/compiler/*/*.hi), to be used if booting + with either HBC or GHC version 0.10. (The + distributed .hi files assume GHC version + 0.16.) + +ghc-0.16-hc-files.tar.gz The intermediate C files for the compiler + proper, the prelude, and `Hello, world'. + Used when porting. + +ghc-0.16-patch-* Patches to the original distribution. There + are none to start with, of course, but there + might be by the time you grab the files. + Please check for them. + +There are no diffs from version 0.10, as they would be laughably huge. + +Once you have the distribution, please follow the pointers in the +ghc/README file to find all of the documentation in and about this +release. diff --git a/ghc/docs/ANNOUNCE-0.19 b/ghc/docs/ANNOUNCE-0.19 new file mode 100644 index 0000000000..6f0523f384 --- /dev/null +++ b/ghc/docs/ANNOUNCE-0.19 @@ -0,0 +1,130 @@ + The Glasgow Haskell Compiler -- version 0.19 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + "What a great system!" + +The third public release of the Glasgow Haskell Compiler is now +available (GHC, version 0.19). Binaries and sources are freely +available by FTP; details below. + +Highlights of what's new in 0.19 since 0.16 (July 1993): + * Somewhat faster compilation times. + * Still better error messages. + * Better Haskell 1.2 compliance, including more derived instances, + `default' declarations, renaming, etc. + * Native-code generator for SPARC. + * Unfoldings across module boundaries. + * Automatic specialisation of overloaded functions. + * Better strictness analysis, including "looking inside tuples" and + "absence analysis" (arguments that aren't used). + * New "simplifier" (program-transformation engine). + +Please see the release notes for a more complete list (including +Backward Incompatibilities to watch out for). + +To run this release, you need a machine with 16+MB memory, GNU C +(`gcc') [version 2.1 or greater], and `perl'. We have seen GHC work +in *some* form or fashion on: Sun4s, Sun3s, DECstations, DEC Alphas, +HP-PA boxes. Sun4s, our development platform, are by far the best +supported. We will distribute binaries as we build them. + +Once you have the distribution, please follow the pointers in +ghc/README to find all of the documentation in and about this release. + +Please report bugs to glasgow-haskell-bugs@dcs.glasgow.ac.uk and +direct general queries to glasgow-haskell-request@<same>. + +We are very grateful to everyone who has sent a bug report, sent a +"look at this weird result" report, lent us a machine on which to try +a port, or (best of all) contributed code. Keep up the good work. + +Simon Peyton Jones + +Dated: 93/12/16 +.................................................................... + +"Should I start using GHC 0.19?" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* If you're using a previous release of GHC: YES. (Recompile everything.) + +* If you want to hack on a Haskell compiler: YES. + +* If you're new to Haskell: Try Gofer (an interpreter for a + Haskell-like language) first; then come back and say YES. + +* If you want time profiling as well as space profiling: YES. + +* If you need the Glasgow Haskell extensions, i.e., calling C, unboxed + datatypes, monadic I/O etc.: YES. (ghc/README says a little more + about these features.) + +* If you're using HBC at the moment: not a clear YES or NO. *We* + really like having both compilers to play against each other. For + example, HBC has better compilation times, but you'll like GHC's + error messages. And you can try them both before submitting a bug + report for either one. + +* If you want simulated parallel execution on a uniprocessor: NO. + (Use the "hbcpp" variant of HBC from York.) + +.................................................................... + +How to make sure every release of GHC will run your program (well) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +*Please* send us a copy! Part of our work is to collect and study +large and *realistic* Haskell programs. Only you can provide them. +They need not be final, polished versions -- they just have to run. + +Among other things, we run every release against our entire +collection, so if your program's in there... + +.................................................................... + +How to get it +~~~~~~~~~~~~~ +This release is available, in whole or in part, from the usual Haskell +anonymous FTP sites, in the directory pub/haskell/glasgow: + + ftp.dcs.glasgow.ac.uk (130.209.240.50) + ftp.cs.chalmers.se (129.16.225.66) + nebula.cs.yale.edu (128.36.13.1) + +We are mirrored by src.doc.ic.ac.uk, in +computing/programming/languages/haskell/glasgow, and you can get files +from there by every means known to humanity. + +These are the available files (.Z for compressed, .gz for gzipped) -- +some are `on demand', ask if you don't see them: + +ghc-0.19-bin-sun4.tar.{Z,gz} A binary distribution -- unpack & run! + For SunOS 4.1.x; assumes you have GNU C (gcc) + version 2.x around... + +ghc-0.19-bin-<other>.tar.gz Other binary distributions -- we will + make them available as we go along; they + will be announced on the Haskell mailing list + (not elsewhere). + +ghc-0.19-src.tar.gz The basic source distribution; about 3MB. + +ghc-0.19-hc-files.tar.gz The intermediate C (.hc) files for the + compiler proper, the prelude, and `Hello, + world'. + +ghc-0.19.ANNOUNCE This file + +ghc-0.19.{README,RELEASE-NOTES} From the distribution; for those who + want to peek before FTPing... + +ghc-0.19-ps-docs.tar.gz Main GHC documents in PostScript format; in + case your TeX setup doesn't agree with our + DVI files... + +ghc-0.19-hi-files-hbc.tar.gz + Interface files for the compiler proper + (ghc/compiler/*/*.hi), to be used if booting + with either HBC. (The distributed .hi files + assume GHC version 0.19.) + +There are no diffs from version 0.16, as they would be laughably huge. diff --git a/ghc/docs/ANNOUNCE-0.20 b/ghc/docs/ANNOUNCE-0.20 new file mode 100644 index 0000000000..2e7f274cb2 --- /dev/null +++ b/ghc/docs/ANNOUNCE-0.20 @@ -0,0 +1,55 @@ +This is version 0.20 of the Glorious Glasgow Haskell compilation +system (GHC). + +Version 0.20 is an "internal" release, intended *ONLY* for the most +fanatical GHC hackers. + +* Many things about it may be broken, though it +does compile and run most programs. + +* I/O and ccall scheme re-done; any such low-level code probably needs + fixing; I/O attempts to follow 1.3 I/O proposal. All ccall + arguments and results are automagically "boxed". + +* PrimOps fiddled; any code that uses them directly will probably need + attention. + +* We've renamed some things, so as to move to a we-don't-steal-user- + name-space policy. Thus "tagCmp" has become "_tagCmp". Names starting + with underscores are now cool if -fglasgow-exts. + + You might want to see our "state-interface" document if you mess + with all this low-level/non-standard stuff; I'll try to remember to + put a copy up for FTP. + +* No promises about profiling. + +* Documentation is untouched since 0.19. + +Version 0.19 was the last public release. It has held up pretty well +and should be available wherever you got 0.20 from. I commend 0.19 to +all sane people. + +Configuring 0.20 is a little different than 0.19: + + % cd <very-top> + % ./configure --with-boot=c + % ./STARTUP-ghc std + % cd ghc; make + +Things to note: + +* It's wrong for jmake to tell you "0: unknown flag -traditional"; but + it is harmless. + +* The 0.20 compiler seems more likely to run out of stack; use + -Rmax-stksize2m (or something) to increase; within the distribution, + probably something like... + + % make EXTRA_HC_OPTS="-H20m -Rmax-stksize4m" + +See the "configure" script if you want to know what other options are +-- there is no other documentation at this time! + +Will Partain, AQUA project typist +partain@dcs.glasgow.ac.uk diff --git a/ghc/docs/ANNOUNCE-0.22 b/ghc/docs/ANNOUNCE-0.22 new file mode 100644 index 0000000000..d7fed2c9fa --- /dev/null +++ b/ghc/docs/ANNOUNCE-0.22 @@ -0,0 +1,109 @@ + The Glasgow Haskell Compiler -- version 0.22 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A new public release of the Glasgow Haskell Compiler is now +available (GHC, version 0.22). Binaries and sources are freely +available by FTP; details below. + +Highlights of what's new in 0.22 since 0.19 (December 1993): + + * Faster compilation times (now about 40% slower than HBC if not + using -O [on a Sun4]). + * Revamped state-tranformer stuff, which affects arrays, calling out + to C, and I/O (preparing for Haskell 1.3). + * "Threads" stuff -- can do quasi-parallel execution on a + uniprocessor. + * No more space leaks from lazy pattern-matching. + * Alastair Reid's "stable pointers" and "malloc pointers"; friendly + interaction with "C Land". + * Time profiling no longer attributes great chunks + of time to "CAF". (However, because of the many recent changes, + profiling is probably *less* reliable than before.) + * New "GHC system library" (analogous to the "HBC system library"); + not much there, but stay tuned. + * Fully supported on DEC Alphas. Some other porting progress. + * Much improved configuration. + * Less user namespace pollution by the system. + * New mailing lists about Glasgow Haskell. + + - The "glasgow-haskell-users" list is for GHC users to chat among + themselves. Subscribe by sending mail to + "glasgow-haskell-users-request@dcs.glasgow.ac.uk". Messages for the + list go to "glasgow-haskell-users". + + - The "glasgow-haskell-bugs" list is for submission of bug reports + and discussion thereof. Subscribe via + "glasgow-haskell-bugs-request@dcs.glasgow.ac.uk"; send bug + reports and rumination thereupon go to "glasgow-haskell-bugs". + +Please see the release notes for a complete discussion of What's New. + +To run this release, you need a machine with 16+MB memory, GNU C +(`gcc') [version 2.1 or greater], and `perl'. We have seen GHC work +in *some* form or fashion on: Sun4s, DEC Alphas, Sun3s, NeXTs, +DECstations, HP-PA and SGI boxes. Sun4s and Alphas, our development +platforms, are fully supported. We distribute binaries for them. + +*** LATE NEWS: Don't use GCC 2.6.0 on the Alpha *** + +Once you have the distribution, please follow the pointers in +ghc/README to find all of the documentation in and about this release. + +Please report bugs to glasgow-haskell-bugs@dcs.glasgow.ac.uk and +direct general queries to glasgow-haskell-request@<same>. + +Simon Peyton Jones + +Dated: 94/07/27 +.................................................................... + +How to get it +~~~~~~~~~~~~~ +This release is available, in whole or in part, from the usual Haskell +anonymous FTP sites, in the directory pub/haskell/glasgow: + + ftp.dcs.glasgow.ac.uk (130.209.240.50) + ftp.cs.chalmers.se (129.16.225.66) + nebula.cs.yale.edu (128.36.13.1) + +The Glasgow site is mirrored by src.doc.ic.ac.uk, in +computing/programming/languages/haskell/glasgow. + +These are the available files (.gz files are gzipped) -- some are `on +demand', ask if you don't see them: + +ghc-0.22-bin-sun4.tar.gz A binary distribution -- unpack & run! + For SunOS 4.1.x; assumes you have GNU C (gcc) + version 2.x around... + +ghc-0.22-bin-alpha.tar.gz A binary distribution -- unpack & run! + Built on OSF1 V2.0; assumes you have GNU C (gcc). + +ghc-0.22-bin-<other>.tar.gz Other binary distributions -- we will + make them available as we go along; they + will be announced on the Haskell mailing list + (not elsewhere). + +ghc-0.22-src.tar.gz The basic source distribution; about 3MB. + +ghc-0.22-hc-files.tar.gz The intermediate C (.hc) files for the + compiler proper, the prelude, and `Hello, + world'. About 4MB. + +ghc-0.22.ANNOUNCE This file + +ghc-0.22.{README,RELEASE-NOTES} From the distribution; for those who + want to peek before FTPing... + +ghc-0.22-ps-docs.tar.gz Main GHC documents in PostScript format; in + case your TeX setup doesn't agree with our + DVI files... + +ghc-0.22-hi-files-hbc.tar.gz + Interface files for the compiler proper + (ghc/compiler/*/*.hi), to be used if booting + with HBC. Not recommended, but some might + want to. (The distributed .hi files assume + GHC version 0.22.) + +There are no diffs from version 0.19, as they would be monstrous. diff --git a/ghc/docs/ANNOUNCE-0.23 b/ghc/docs/ANNOUNCE-0.23 new file mode 100644 index 0000000000..d7e7d942a3 --- /dev/null +++ b/ghc/docs/ANNOUNCE-0.23 @@ -0,0 +1,124 @@ + The Glasgow Haskell Compiler -- version 0.23 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A new public release of the Glasgow Haskell Compiler is now available +(GHC, version 0.23). Binaries and sources are freely available by +anonymous FTP; details below. + +Haskell is "the" standard lazy functional programming language [see +SIGPLAN Notices, May 1992]. The current language version is 1.2. + +GHC is a state-of-the-art batch compiler. For some idea of how it +compares against the competition, see Pieter Hartel's recent revision +of his FPCA '93 paper. Reference attached. Summary: we win! + +Highlights of what's new in GHC 0.23 since 0.22 (July 1994): + + * Faster compilation times (less than 10% slower than HBC if not + using -O [on a Sun4]). + + * Produces 10-15% smaller executables. The main compiler binary is + 1MB smaller than in 0.22. + + * >>> USER-VISIBLE changes <<< to "monadic I/O", because we are + switching to the Haskell 1.3 *draft* I/O proposal. Please see the + relevant bit of the User's Guide before doing monadic I/O things + with 0.23. + + * Native-code generator for DEC Alphas. + + * A _selective_ lambda lifter. + + * The yacc-based parser is now called directly from Haskell. + + * Configuration changed enough that "the same old thing" *won't* work. + Configuring binary distributions should be trivial now. + + * Quite a few bugs fixed; the usual big wad of code added. + +Please see the release notes for a complete discussion of What's New. + +Should you upgrade to 0.23? If you are a contented 0.22 user, +probably not. Otherwise, probably yes. + +To run this release, you need a machine with 16+MB memory, GNU C +(`gcc'), and `perl'. We have seen GHC work in *some* form or fashion +on: Sun4s, DEC Alphas, Sun3s, NeXTs, DECstations, HP-PA and SGI boxes. +Sun4s and Alphas, our development platforms, are fully supported; we +distribute binaries for them. The release notes give a full +what-ports-work report. + +Once you have the distribution, please follow the pointers in +ghc/README to find all of the documentation in and about this release. +NB: preserve modification times when un-tarring (no `m' option for +tar, please)! + +We run mailing lists for GHC users and bug reports; to subscribe, send +mail to glasgow-haskell-{users,bugs}-request@dcs.glasgow.ac.uk. +Please send bug reports to glasgow-haskell-bugs. + +Simon Peyton Jones + +Dated: 94/12/21 + +====================================================================== +Hartel reference: + +@techreport{Har94g, + author = {P. H. Hartel}, + title = {Benchmarking implementations of lazy functional + languages {II} -- Two years later}, + institution = {Dept. of Comp. Sys, Univ. of Amsterdam}, + type = {Technical report}, + number = {Cs-94-21}, + month = {Dec}, + year = {1994}} + +The paper is available from ftp.fwi.uva.nl, +file: pub/computer-systems/functional/reports/benchmarkII.ps.Z + +The programs are in file: pub/computer-systems/functional/packages/benchmark.tar.Z + +====================================================================== +How to get GHC: + +This release is available, in whole or in part, from the usual Haskell +anonymous FTP sites, in the directory pub/haskell/glasgow: + + ftp.dcs.glasgow.ac.uk (130.209.240.50) + ftp.cs.chalmers.se (129.16.227.140) + haskell.cs.yale.edu (128.36.11.43) + +The Glasgow site is mirrored by src.doc.ic.ac.uk (155.198.191.4), in +computing/programming/languages/haskell/glasgow. + +These are the available files (.gz files are gzipped) -- some are `on +demand', ask if you don't see them: + +ghc-0.23-bin-sun4.tar.gz A binary distribution -- unpack & run! + For SunOS 4.1.x; assumes you have GNU C (gcc) + +ghc-0.23-bin-alpha.tar.gz A binary distribution -- unpack & run! + Built on OSF1 V2.0; assumes you have GNU C (gcc). + +ghc-0.23-bin-<other>.tar.gz Other binary distributions -- we will + make them available as we go along; they + will be announced on the Haskell mailing list + (not elsewhere). + +ghc-0.23-src.tar.gz The basic source distribution; about 3MB. + +ghc-0.23-hc-files.tar.gz The intermediate C (.hc) files for the + compiler proper, the prelude, and `Hello, + world'. About 4MB. + +ghc-0.23.ANNOUNCE This file + +ghc-0.23.{README,RELEASE-NOTES} From the distribution; for those who + want to peek before FTPing... + +ghc-0.23-ps-docs.tar.gz Main GHC documents in PostScript format; in + case your TeX setup doesn't agree with our + DVI files... + +There are no diffs from version 0.22, as they would be monstrous. diff --git a/ghc/docs/ANNOUNCE-0.25 b/ghc/docs/ANNOUNCE-0.25 new file mode 100644 index 0000000000..a3da0c2e6a --- /dev/null +++ b/ghc/docs/ANNOUNCE-0.25 @@ -0,0 +1,54 @@ +A binary-only from-working-sources no-guarantees snapshot of the +Glasgow Haskell compiler (GHC) for Linux x86 machines is now available +by FTP from ftp.dcs.glasgow.ac.uk, in +pub/haskell/glasgow/ghc-0.25-linux.tar.gz. + +This release is the first, long-awaited "registerized" GHC for Linux, +which produces code of reasonable size and speed. We use our normal +technique of "stealing registers" with GCC's +global-variables-in-registers facility. We "steal" six of the x86's +eight general-purpose registers, including the C stack-pointer (%esp), +which we use for the heap pointer (Hp). + +To use this GHC, you need a special version of GCC, which is also +provided in the distribution (under "gcc-linux-to-linux"). Whatever +you do, please do *not* report any "bugs" in this GCC to bug-gcc -- +report them to *me* instead. + +One special thing you must watch out for: If GCC "crashes" with a +message about spilling registers, it is *not* a GCC problem. It means +you must get GHC to "back off" in its register "stealing". First try +a -monly-4-regs flag, then -monly-3-regs, and as a last resort, +-monly-2-regs. As far as we know, all Haskell code goes through GHC +with a -monly-2-regs flag (but it produces substantially worse code +with that flag). + +Profiling is not provided in this release. + +Please report any bugs to glasgow-haskell-bugs@dcs.glasgow.ac.uk. + +Will Partain +AQUA project (slave) + +Dated: 95/04/01 + +=== INSTALLATION NOTES ============================================== + +Unpack the distribution. + +Move "gcc-linux-to-linux" and "ghc-0.25-linux" wherever you like. + +Alter the "gcc" script to point to wherever you've put +"gcc-linux-to-linux", and put the "gcc" script wherever you wish in +your PATH. + +Make a link to ghc-0.25-linux/ghc/driver/ghc, so that "ghc" will be in +your PATH. + +Change *all* hardwired paths in ghc/driver/ghc and in +ghc/utils/hscpp/hscpp to point to where things are on your system. +Notably: where "perl" is (first line of each script), where $TopPwd is +(ghc script), where your gcc cpp is (hscpp script). + +GHC should then work. Try "ghc -v" on something simple, to make sure +it compiles and links a program correctly. diff --git a/ghc/docs/Jmakefile b/ghc/docs/Jmakefile new file mode 100644 index 0000000000..6bbeb2537a --- /dev/null +++ b/ghc/docs/Jmakefile @@ -0,0 +1,19 @@ +#define IHaveSubdirs + +/* just documents here */ +#define NoAllTargetForSubdirs +#define NoRunTestsTargetForSubdirs +#define NoInstallTargetForSubdirs +#define NoTagTargetForSubdirs + +SUBDIRS = add_to_compiler \ + users_guide \ + install_guide \ + release_notes + +XCOMM developers_guide ? +XCOMM interfaces ? +XCOMM pragmas ? + +XCOMM grasp_overview ? +XCOMM style_guide ? diff --git a/ghc/docs/NOTES.adding-PrimOp b/ghc/docs/NOTES.adding-PrimOp new file mode 100644 index 0000000000..2d5b475ec1 --- /dev/null +++ b/ghc/docs/NOTES.adding-PrimOp @@ -0,0 +1,51 @@ +This is a short note describing how I (ADR <areid@dcs.glasgow.ac.uk>) +added a new primitive operation (makeStablePtr#) to the compiler. It +serves as documentation of what I did and as a guide to anyone else +wanting to try it. + +1) Change compiler/prelude/PrimOps.lhs: + + - add @MakeStablePtrOp@ to the datatype @PrimitiveOp@. + + - add the following case to @primOpInfo@ + + primOpInfo MakeStablePtrOp + = AlgResult "makeStablePtr#" [] + [(ioWorldTy `UniFun` intPrimAndIoWorldTy), ioWorldTy] + intPrimAndIoWorldTyCon [] + -- makeStablePtr# :: IO_Int# -> IO_Int# + -- == makeStablePtr# :: (IoWorld -> (Int#, IoWorld)) -> (IoWorld -> (Int#, IoWorld)) + +2) Change compiler/prelude/AbsPrel.lhs: + + - add @MakeStablePtrOp@ to an appropriate place in @list_of_val_assoc_lists@ + + (This makes the operation visible to the programmer). + + Since this is a glasgow extension, I added it to one of + @extra_known_vals_2@, @unboxed_ops@, @boxed_ops@. @unboxed_ops@ + is made up of several lists of operators including + @prim_ops_used_unboxed_only@. By inspection I decided that this + (@prim_ops_used_unboxed_only@) was the one to go for. + +At this point I started recompiling the compiler - this took a long +time since the change to @PrimitiveOp@ changed the @.hi@ file +resulting in a complete (or near as makes no odds) recmpilation of the +compiler. (Is there a way of using fastmake that avoids this? + +3) Change imports/StgMacros.lh to generate code for @MakeStablePtr#@ + + - this is just adding a macro that calls the appropriate operation. + + (I suspect I could omit this step if I wanted since all this does + (ahem, will do) is call a function in the runtime system.) + +4) Change runtime/storage/SMap.lc to implement the new operation. + + I won't bother describing this just now. + + +This is a little untidy. I should perhaps add a new flag to the system +which turns my extension off and checks that it is only used in +conjunction with the Appel generational collector. But we're going to +do the same to every collector eventually aren't we? diff --git a/ghc/docs/NOTES.arbitary-ints b/ghc/docs/NOTES.arbitary-ints new file mode 100644 index 0000000000..964a2cf5be --- /dev/null +++ b/ghc/docs/NOTES.arbitary-ints @@ -0,0 +1,54 @@ + +Boxed structure of BigInts + + +----> Info1 Pointer + | Pointer passed to BigNum package + | | + \/ \/ + Info2 Size Integer .... + + (size excludes info ptr & size field) + +Unboxed (Compiler must place on pointer stack not data stack + Must also tell GC if it is in a register when GC invoked) + +----> Info2 Size Integer + + + +Info1: + SPEC_INFO_TABLE(Info1, BigNum_entry, 1, 1); (Min Size 2 ?) + + Entering this returns the BigNum using agreed return convention + +Info2: + DATA_INFO_TABLE(Info2, Dummy_entry); + + This never actually entered -- just required for GC. + +------------------------------------------------------------------------------ + +Boxed structure of BigInts (the alternative one) + + Pointer passed to BigNum package + | + \/ +----> Info Size Integer .... + + (size excludes info ptr & size field) + +Unboxed (Compiler must place on pointer stack not data stack + Must also tell GC if it is in a register when GC invoked) + + +Info: + DATA_INFO_TABLE(Info, BigNum_entry); + + Entering this returns the BigNum using agreed return convention + + + +Note that the Boxed and Unboxed representation are identical !!! + +(unboxing represents evaluationhood, not pointerhood) diff --git a/ghc/docs/NOTES.c-optimisation b/ghc/docs/NOTES.c-optimisation new file mode 100644 index 0000000000..3320ae1d3d --- /dev/null +++ b/ghc/docs/NOTES.c-optimisation @@ -0,0 +1,2361 @@ +Optimisation of C-code (runtime and compiled) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Placing of STG registers in machine registers +- Optimisation of interpreter loop (tail calls) + +/* TODO: flags */ +-OC flag to ghc causes optimisation + + +ANSI C +~~~~~~ +For functions with no args we declare them as + + foo( STG_NO_ARGS ) + +rather than foo(), because you can tell ANSI C a little more +by making STG_NO_ARGS expand to void. Maybe something to do with +forward declarations? + + +Optimisation with GCC +~~~~~~~~~~~~~~~~~~~~~ + +We are concentrating most optimisation with gcc which allows +suitable global register declarations. + + +REGISTERS: + +See StgOpt.h for a description of register usage + +Note that all modules that reference the STG registers must be +compiled the same way so they look at the registers and not the +global variables. + + +TAIL CALLS: + +Seperate modules for tail call optimisations are required. +Requitre to partition runtime system code. + +.hc: + Modules with tail call routines (most runtime and all compiled) + are labeled .hc (literate = .lhc). + These are compiled to assember with tail call optimisation on + and then post processed with sed (Yuk!) + + All routines which return a continuation (STGJUMP) must be + compiled this way. + + (The only exeption to this is continuations which exit/abort which + may live in .c files) + +.c: + These modules are not compiled with the tail call optimisation + and don't have sed processing. + Sed processing would destroy the code! + + All routines which are not continuations (called and return + conventionally) must be compiled this way. + + This includes various parts of the runtime system. + + + + +See Also ~sansom/work/gcstats/OBSERVATIONS + + + + +Info Recieved from Eliot Miranda: + +Received: from dcs.glasgow.ac.uk (tutuila) by vanuata.dcs.glasgow.ac.uk; Thu, 4 Jul 91 09:40:34 BST +Message-Id: <15456.9107040841@dcs.glasgow.ac.uk> +X-Comment1: ############################################################# +X-Comment2: # uk.ac.glasgow.cs has changed to uk.ac.glasgow.dcs # +X-Comment3: # If this address does not work please ask your mail # +X-Comment4: # administrator to update your NRS & mailer tables. # +X-Comment5: ############################################################# +To: simonpj +Cc: sansom +Subject: Miranda's original msg +Date: Thu, 04 Jul 91 09:41:19 +0100 +From: Simon L Peyton Jones <simonpj> + + + + + +>From eliot@.cs.qmw.ac.uk Mon Apr 1 11:16:06 1991 +From: eliot@.cs.qmw.ac.uk (Eliot Miranda) +Newsgroups: comp.compilers +Subject: Portable Fast Direct Threaded Code +Keywords: interpreter, design +Date: 28 Mar 91 12:20:06 GMT +Reply-To: Eliot Miranda <eliot@.cs.qmw.ac.uk> +Organization: Computer Science Dept, QMW, University of London, UK. + +Various people have asked me for details on how I do threaded code +in my dynamic translation Smalltalk-80 VM. So here's the gory details +as well as the first published benchmarks for the system. + + How to do "Machine-Independent" Fast Direct Threaded Code: + + +First off, use C (although other flexible machine-oriented imperative +languages would probably work too). + +Global registers: + If you can use GCC >v1.33 you can use global register variables to +hold the threaded code machine's registers. If you have various forms of +stupid C compiler then you can get global register variables by declaring +your globals as register variables in every function, and later editing the +assembler generated by the C compiler to remove global register saves & +restores (details in [Miranda]). + + +Threaded Code: + Threaded code instructions (TCIs) are written as C procedures. +They are compiled to assembler by the C compiler. Subsequently a simple +editor script is run on the assembler to remove the prologues and epilogues +from the threaded code procedures, and possibly to insert direct threaded +code jumps. + +How to Identify Threaded Code Instructions: + The method I prefer is to segregate TCIs from other procedures & +functions in the machine by placing related groups of TCIs in separate +source files. I give my threaded code source files the .tc extension and +they have a rule in the makefile that will run the editor script on the +assembler. An alternative is to identify each threaded code procedure with +a special prefix which is spotted by the editor script. This is probably +more error prone & doesn't fit well with leaf-routine optimization (see +below). + +How to Write Threaded Code Instructions: +Each TCI is writen an a void function of no arguments. It is wise to start +and end each TCI with two special macros to replace '{' and '}'. So, using +GCC on the SPARC, given some declarations: + + + typedef void (*TCODE)(); /* a TCODE is a pointer to a function */ + typedef ???? ObjectPointer; + + . . . + + register TCODE *tcip asm("%g7"); /*threaded code instruction pointer*/ + register ObjectPointer *stackPointer asm("%g5"); + +e.g. popStack would be written: + + void popStack() + TBEGIN + stackPointer--; + TEND + +With GCC TBEGIN is + + #define TBEGIN { + +With stupid C compilers it can be defined to be the list of global register +variables. Further, if you want to build a debuger for your threaded code +machine you could compile the system with + + #define TBEGIN { int frig = checkForBreakPoint(); + +and ignore lots of warnings about variable frig being unused :-). + +TEND has to do a direct threaded code jump. In my system I want an indirect +post-increment jump on tcip; i.e. jump to *tcip++. On the SPARC with tcip +in %g7 the jump is + + ld [%g7],%o0 ! get *tcip + jmpl %o0,%g0 ! jump to it + add %g7,4,%g7 ! increment tcip in the jump's delay slot + +On the 68k with tcip in a5 the jump is + + movl a5@+,a0 + jmp a0@ + +With GCC this is implemented by the JUMPNEXT macro. On the SPARC: + #define JUMPNEXT do{ \ + asm("ld [%g7],%o0; jmpl %o0,%g0; add %g7,4,%g7");\ + return;}while(0) + +Note the return, it tells the compiler that control does not pass this point. +On the 68k: + /* SBD = Silent But Deadly = Stack Bug Dummy. gcc has a bug with + no-defer-pop. it always depers the pop of the last function call in + a routine. SBD is a dummy call to ensure no other previous call gets + its pop deferred. + */ + extern void SBD P((void)); + + #define JUMPNEXT do{ \ + asm("movl a5@+,a0; jmp a0@");\ + SBD();return;}while(0) + +SBD is then removed by the editor script. + +So TEND is defined to be + #define TEND JUMPNEXT; } + +On the SPARC popStack is expanded to + void popStack() + { + stackPointer--; + do{asm("ld [%g7],%o0; jmpl %o0,%g0; add +%g7,4,%g7");return;}while(0); + } + +Its compiled to: + _popStack: + !#PROLOGUE# 0 + save %sp,-80,%sp + !#PROLOGUE# 1 + add %g5,-4,%g5 + ld [%g7],%o0; jmpl %o0,%g0; add %g7,4,%g7 + ret + restore +The editor script then reduces this to:` + _popStack: + ! [gotcher] + add %g5,-4,%g5 + ld [%g7],%o0; jmpl %o0,%g0; add %g7,4,%g7 + +On the 68k you end up with: + .globl _popStack + _popStack: + subqw #4,a3 + movl a5@+,a0; jmp a0@ + +Global Register Variables and Stupid C Compilers: + Some C compilers are stupid enough to provide straight-forward global +registers. A C compiler on a nat-semi based system I used just allocated +registers in the order they were declared. The assembler syntax was very +simple to edit. Global register variables could thus be obtained easily. + + Some C compilers are stupid but think they're clever. Sun's SUN3 +compiler is a case in point. It also allocates registers in the order declared. +However, it tries to be clever by removing 'dead assignments' (assignments to +subsequently unused register variables). These compilers are easy to fool. +Simply arrange that the register variables are always used before leaving a +function. I do this by always writing RETURN or RETURNV(e) instead of +return and return e. On systems with such stupid C compilers RETURN(e) +is defined thus: + + #define RETURNV(e) do{DummyUseRegs(GR1,GR2,GR3); return e;}while(1) + +The call on DummyUseRegs fools the compiler into thinking the registers +are live & hence saves assignments to them. The editor scripts can then +remove calls on DumyUseRegs. + + Of course on systems with marginally clever C compilers (SUN4 +HP-UX etc) +you're stuffed. However, in clever C compilers like GCC and Acorn's C compiler +you can declare global registers & everything is clean & wholesome :-). + + + +Conditional TCODE Jumps: + Say we wanted a conditional tcode jump. This might be writen: + void skipIfTrue() + TBEGIN + if (*stackPointer-- == TrueObject) { + tcip += 1; + JUMPNEXT; + } + TEND + +How this All Works: +With the above scheme, each threaded code procedure runs in the same C +stack frame, and jumps directly to the next procedure, eliminating an +unnecessary <epilogue, return>, <call, prolog> pair. Once we establish a +stack frame and call the first function away we go. Assuming that you've +produced your first threaded code method (a sequence of pointers to +threaded code procedures), and that tcip points at the start, then +StartTCMachine might be defined as follows: + + volatile void + StartTCMachine() + { char *enoughSpaceForAllTCIStackFrames; + + enoughSpaceForAllTCIStackFrames = alloca(1024); + + while(1) { (*tcip++)(); } + } + +The alloca allocates space on the stack. After the first (*tcip++)() +control goes off into threaded code land and never returns. + +Leaf Routine Optimization: +The threaded code machine will make calls on support routines e.g. +graphics, garbage collector etc. Any group of routines that dont access +the global registers and don't directly or indirectly call routines that +need to access the global registers can be optimized. These routines +should be compiled without declaring the global registers. These routines +will then use as many registers as the compiler will give them and will +save & restore any registers they use, preserving the values of the global +register variables. + + +Details of my Smalltalk Threaded Code Machine: + I use a pair of words for each TCI, a pointer to the procedure followed +by an optional operand. This avoids going out of line to access arguments. +e.g. pushLiteral is: + void pushLit() + TBEGIN + *++stackPointer = (OOP)*tcip++; + TEND +where OOP is an ordinary object pointer. So on entry to push lit we have: + <pointer to pushLit> + tcip-> <object pointer> + <pointer to next TCI> + <next TCI's operand> +and popStack must therefore be written + void popStack() + TBEGIN + stackPointer--; + tcip++; + TEND + +I dynamically compile Smalltalk-80 bytecodes to threaded code. I use 128k +bytes of memory to hold all threaded code. This 'tspace' is periodically +scavenged to reclaim space. The architecture is similar to +[DeutschSchiffman]. Using an eighth of the space used by the Deutch +Schifman machine I get around 75% of the performance on the non-graphics +benchmarks. Here are the Smalltalk macro benchmarks for BrouHaHa +Smalltalk-80 v2.3.2t running on a monochrome SUN3/60 (20MHz 68020): + + BitBLT 76.7308 + TextScanning 222.857 + ClassOrganizer 80.6667 + PrintDefinition 59.0278 + PrintHierachy 142.857 + AllCallsOn 112.5 + AllImplementors 130.0 + Inspect 116.667 + Compiler 86.4341 + Decompiler 101.639 + KeyboardLookAhead 212.5 + KeyboardSingle 302.778 + TextDisplay 148.837 + TextFormatting 273.81 + TextEditing 180.342 + Performance Rating 134.198 + +and on the same machine under the same conditions are the timings for +ParcPlace Smalltalk-80 V2.3: + + BitBLT 99.75 + TextScanning 390.0 + ClassOrganizer 155.128 + PrintDefinition 137.097 + PrintHierachy 192.308 + AllCallsOn 120.0 + AllImplementors 108.333 + Inspect 146.774 + Compiler 118.617 + Decompiler 129.167 + KeyboardLookAhead 303.571 + KeyboardSingle 473.913 + TextDisplay 172.973 + TextFormatting 442.308 + TextEditing 285.135 + Performance Rating 189.504 + +134.198/189.504 = 0.708154 + +WARNING!! These systems ARE different, these benchmarks are included only +to give a feeling for ball-park performance. +Example differences: + BrouHaHa ParcPlace + closures blue-book BlockContexts + immediates: + characters, smallints, fixedpoints immediate smallintegers + 5844 compiled methods 5136 compiled methods + (5026 ordinary methods) (4798 ordinary methods) + (818 quick methods) (338 quick methods) + + + +More Portable File Organization: +To keep the code as clean looking as possible all machine-dependencies are +isolated in separate files. e.g. tcode.h gives machine independent +definitions for TCODE. It includes machine dependencies from another file: + + /* for debugging purposes; single step breakpoint at start of +each tcode + */ + #define DEBUG_FETCH_BREAK int frig = fetchBrk(); + + #ifdef FAST + # include "fasttcode.h" + #else + + TCODE *tcip; /* the tcode ip points at TCODEs */ + + # define JUMPNEXT return + # ifdef BIDebug + # define TBEGIN { DEBUG_FETCH_BREAK + # else + # define TBEGIN { + # endif + # define TEND } + #endif + +GCC/SPARC/fasttcode.h: + /* tcodeip in g7 */ + register TCODE *tcip asm("%g7"); + + #define JUMPNEXT do{asm("ld [%g7],%o0; jmpl %o0,%g0; add +%g7,4,%g7");return;}while(0) + + #ifdef BIDebug + # define TBEGIN { DEBUG_FETCH_BREAK + #else + # define TBEGIN { + #endif + #define TEND JUMPNEXT; } + +I also don't want to include the necessary definitions for the global registers +in every file. So for those non-leaf routines that must avoid using the +global registers there's a fastglobal.h file that gives dummy definitions for +these registers. e.g. GCC/SPARC/fastglobal.h: + /* machine specific FAST defines. + Gnu C 1.33 systems can use nice compiler provided global registers. + */ + + #define BEGIN { + #define END } + #define RETURN(e) return e + #define RETURNV return + + register char *GlobRegDummy1 asm("a5"); + register char *GlobRegDummy2 asm("a4"); + register char *GlobRegDummy3 asm("a3"); + register char *GlobRegDummy4 asm("d6"); + + #ifdef MASKREGISTER + register char *GlobRegDummy5 asm("d7"); + #endif + +I use symbolic links to set up the machine dependent include files. +This has the +advantage that if you add a new machine you don't have to remake all +the others. + + +The Tedious Bit: +The only tedious bit is writing the sed-scripts. For the SPARC this took 1 day. +Here are the sed scripts I use for SUN 3, MAC2AUX (using GAS) and SUN4, +all using GCC (v1.33 upwards). There's a problem on the SPARC in that the ABI +does not seem to define the status of the global registers. Some math and +library routines stomp on the global registers (beware getwd!), so I've +included +GCC/SUN4/sed.globreg.bugfix as an example of how to spot the offending math +routines: + +SUN3/GCC/lib/sed.tcode.opt: +# script to strip prolog & epilog from threaded code under gcc. +# WARNING the script may strip a push of a register argument if a call is the +# first statement of a function!! +# +/^_.*:$/{n +N +N +s/ link a6,#[^\n]*\n// +/ fmovem #[^\n]*,sp@-/{ +N +s/ fmovem #[^\n]*,sp@-\n// +} +s/ moveml .*,sp@-\n// +s/ movel [ad][0-7],sp@-\n// +} +/ moveml a6@(-[1-9][0-9]*),#/{N +s/ moveml a6@(-[1-9][0-9]*),#[^\n]*\n unlk a6// +} +/ movel a6@(-[1-9][0-9]*),[ad][0-7]/{N +s/ movel a6@(-[1-9][0-9]*),[ad][0-7]\n unlk a6// +} +/ movel sp@+,/d +/ moveml sp@+,#/d +/ unlk a6/d +/ rts/d +/ jbsr _SBD/d + +MAC2AUX/GCC/lib.gas/sed.tcode.opt: +/COMMENT/{ +i\ + script to strip prolog & epilog from threaded code under gcc. WARNING \ + the script may strip a push of a register argument if a call is the\ + first statement of a function!! +} +/^gcc_compiled:/d +/^.[^%].*:$/{ n +/ link %a6/{ +N +N +s/ link %a6,#[x0-9-]*\n// +/ fmovem #[^\n]*,%sp@-/{ +N +s/ fmovem #[^\n]*,%sp@-\n// +} +s/ moveml #[x0-9a-f]*,%sp@-\n// +s/ movel %[ad][0-7],%sp@-\n// +n +} +} +/ moveml -[1-9][0-9]*%a6@,#/{ N +s/ moveml -[1-9][0-9]*%a6@,#[x0-9a-f-]*\n unlk %a6// +} +/ movel -[1-9][0-9]*%a6@,%[ad][0-7]/{ N +s/ movel -[1-9][0-9]*%a6@,%[ad][0-7]\n unlk %a6// +} +/ movel %sp@+,%/d +/ moveml %sp@+,#/d +/ movel %d0,%a0/{ +N +s/ movel %d0,%a0\n unlk %a6// +/ movem*l %a6/{ +N +s/ movel %d0,%a0\n movem*l %a6.*\n unlk %a6// +/ fmovem %a6/{ +N +s/ movel %d0,%a0\n movem*l %a6.*\n fmovem %a6.*\n unlk %a6// +} +} +} +/ unlk %a6/d +/ rts/d +/ jbsr SBD/d + + +SUN4/GCC/lib/sed.tcode.opt: +# script to strip prolog & epilog from threaded code under gcc. +# +/^_.*:$/{n +N +N +s/ !#PROLOGUE# 0\n save %sp,[-0-9]*,%sp\n !#PROLOGUE# 1/ ! [gotcher]/ +} +/ ret/d +/ restore/d + +SUN4/GCC/lib/sed.globreg.bugfix: +# Some of the libc builtin routines (.rem .urem .div & .udiv so far known) +# stamp on %g3 which is the maskReg (it contains 0x7FFFFF). +# This script reassigns the value of maskReg after each of these routines +# has been called. +/call[ ]\.div,[0-9]/{n +n +i\ + sethi %hi(0x7FFFFF),%g3 ![globregfix]\ + or %lo(0x7FFFFF),%g3,%g3 +} +/call[ ]\.udiv,[0-9]/{n +n +i\ + sethi %hi(0x7FFFFF),%g3 ![globregfix]\ + or %lo(0x7FFFFF),%g3,%g3 +} +/call[ ]\.rem,[0-9]/{n +n +i\ + sethi %hi(0x7FFFFF),%g3 ![globregfix]\ + or %lo(0x7FFFFF),%g3,%g3 +} +/call[ ]\.urem,[0-9]/{n +n +i\ + sethi %hi(0x7FFFFF),%g3 ![globregfix]\ + or %lo(0x7FFFFF),%g3,%g3 +} + + +You can now see why I put "Machine-Independent" in quotes. Here's the count +of machine dependent code for the SPARC: + + 25 99 786 fastcache.h + 68 262 1882 fastglobal.h + 31 112 906 fasttcode.h + 28 80 595 ../tcsrc/SUN4/GCC/lib/sed.globreg.bugfix + 5 34 222 ../tcsrc/SUN4/GCC/lib/sed.peep.opt + 9 30 173 ../tcsrc/SUN4/GCC/lib/sed.tcode.opt + 166 617 4564 total + +Of these 166 lines 51 lines are banner headers. 100 odd lines are +machine dependent. A whole VM is around the 20k lines mark. So +machine dependencies are down in the 0.5% range. + + + +Use this stuff as part of what ever you like. If you try & assert ownership +I'll fight & batter you over the head with the GPL ('bout time we had some +serious steel in that thar GPL). + +Share And Enjoy! + +P.S. The BrouHaHa machine is available to educational institutions with a +valid ParcPlace Smalltalk-80 licence, subject to a strict non-disclosure +agreement. email me if you want it. I am slow to answer requests! +-- +Send compilers articles to compilers@iecc.cambridge.ma.us or +{ima | spdcc | world}!iecc!compilers. Meta-mail to compilers-request. + +>From crowl@cs.rochester.edu Tue Apr 2 10:34:53 1991 +From: crowl@cs.rochester.edu (Lawrence Crowl) +Newsgroups: comp.compilers +Subject: Re: Portable Fast Direct Threaded Code +Keywords: interpreter, design +Date: 31 Mar 91 18:06:35 GMT +Reply-To: crowl@cs.rochester.edu (Lawrence Crowl) +Organization: Computer Science Department University of Rochester + +In article <3035@redstar.cs.qmw.ac.uk> +Eliot Miranda <eliot@.cs.qmw.ac.uk> writes: +>The threaded code machine will make calls on support routines, e.g. graphics, +>garbage collector etc. Any group of routines that don't access the global +>registers and don't directly or indirectly call routines that need to access +>the global registers can be optimized. These routines should be compiled +>without declaring the global registers. These routines will then use as many +>registers as the compiler will give them and will save & restore any +>registers they use, preserving the values of the global register variables. + +This scheme assumes that procedure calls use a "callee saves" register +convention, and does not work if you allocate the global register +variables out of the "caller saves" set of registers. The problem is that +the caller does not save the register (because it is global) and the +callee writes over the register (because the caller saved it). In this +situation, the programmer must insert explicit saves and restores of the +global register variables. + +The obvious solution to this problem is to allocate all global register +variables out of the "callee saves" set of registers. However, the +Alliant has _no_ callee saves registers. Library routines on the Alliant +will trash every register you have. In addition, implicit library calls +to routines like bcopy will also trash your registers. (I learned this +the hard way.) + +The lesson is that calling library routines with global register variables in +caller saves registers requires special handling. It is not automagic. +-- + Lawrence Crowl 716-275-9499 University of Rochester + crowl@cs.rochester.edu Computer Science Department + ...!rutgers!rochester!crowl Rochester, New York, 14627-0226 +-- +Send compilers articles to compilers@iecc.cambridge.ma.us or +{ima | spdcc | world}!iecc!compilers. Meta-mail to compilers-request. + +>From Tom.Lane@G.GP.CS.CMU.EDU Wed Apr 3 10:38:09 1991 +From: Tom.Lane@G.GP.CS.CMU.EDU +Newsgroups: comp.compilers +Subject: Re: Portable Fast Direct Threaded Code +Keywords: interpreter, design +Date: 1 Apr 91 15:21:14 GMT +Reply-To: Tom.Lane@G.GP.CS.CMU.EDU +Organization: Compilers Central + +Lawrence Crowl points out one important problem with Eliot Miranda's +scheme for global register use in C. There's an even more fundamental +problem, though: there is *no guarantee whatever* that the compiler will +assign the same registers to the global variables in every routine. + +Compilers that do intelligent allocation of variables to registers may +refuse to honor the "register" declarations at all if the global variables +are not heavily used in a given routine, and in any case the globals need +not be assigned to the same registers every time. Miranda's scheme thus +relies heavily on the assumption of a dumb register allocator (or else a +compiler that supports global register variable declarations). + +This scheme may be "fast" direct threaded code, but it's hardly "portable". +-- + tom lane +Internet: tgl@cs.cmu.edu BITNET: tgl%cs.cmu.edu@cmuccvma +[GCC lets you specify what register to use for global register variables, but +that is of course both machine and compiler specific. -John] +-- +Send compilers articles to compilers@iecc.cambridge.ma.us or +{ima | spdcc | world}!iecc!compilers. Meta-mail to compilers-request. + +>From pardo@cs.washington.edu Thu Apr 4 17:34:39 1991 +From: pardo@cs.washington.edu (David Keppel) +Newsgroups: comp.compilers +Subject: Re: Portable Fast Direct Threaded Code +Keywords: interpreter, design, bibliography +Date: 2 Apr 91 19:21:25 GMT +Reply-To: pardo@cs.washington.edu (David Keppel) +Organization: Computer Science & Engineering, U. of Washington, Seattle + +metzger@watson.ibm.com (Perry E. Metzger) writes: +>[I'd like a reference on threaded code interpreters.] + +3 citations follow: + +%A James R. Bell +%T Threaded Code +%J Communications of the ACM (CACM) +%V 16 +%N 2 +%D June 1973 +%P 370-372 +%X Describes the basic idea of threaded code. +Compares to hard code (subroutine calls) and interpreters. + +%A Richard H. Eckhouse Jr. +%A L. Robert Morris +%T Minicomputer Systems Organization, Programming, and Applications +(PDP-11). 2nd Ed. +%I Prentice-Hall, Inc. +%P 290-298 +%X Describes threaded code and ``knotted code''. I (pardo) think that +this is a very clear introduction to threaded code. + +%A Peter M. Kogge +%T An Architectural Trail to Threaded Code Systems +%J IEEE Computer +%P 22-33 +%D March 1982 +%W rrh (original) +%W Pardo (copy) +%X Describes how to build a threaded code interpeter/compiler from +scratch. + * Direct threaded/indirect threaded. + * Less than 2:1 performance hit of threading compared to full +compilation. + * Note about bad compilers contributing to relative OK-ness of +threaded code. + * Ease of rewriting stuff. + * Ease of tuning. + +My favorite of the three is Eckhouse & Morris; however I don't know +where to get it. The pages that I have are photocopies graciously +sent to me by a friend. As the title implies, this book is several +years old and undoubtedly out-of-print. + + ;-D on ( Following this thread of the discussion... ) Pardo +-- +Send compilers articles to compilers@iecc.cambridge.ma.us or +{ima | spdcc | world}!iecc!compilers. Meta-mail to compilers-request. + +>From simonpj Fri Apr 5 09:52:33 1991 +Received: from tutuila.dcs.glasgow.ac.uk by vanuata.cs.glasgow.ac.uk; +Fri, 5 Apr 91 09:52:27 BST +Message-Id: <2763.9104050851@tutuila.dcs.glasgow.ac.uk> +X-Comment1: ############################################################# +X-Comment2: # uk.ac.glasgow.cs has changed to uk.ac.glasgow.dcs # +X-Comment3: # If this address does not work please ask your mail # +X-Comment4: # administrator to update your NRS & mailer tables. # +X-Comment5: ############################################################# +From: Simon L Peyton Jones <simonpj> +To: eliot@cs.qmw.ac.uk +Cc: simonpj, partain +Subject: Threaded code +Date: Fri, 05 Apr 91 09:51:48 +0100 + + +Eliot + +I saw your article about threaded code. Like you and others, we are +using C as an assembler, only for a pure functional language, Haskell. +I have some brief questions. + +1. By telling GCC not to use a frame pointer, one can eliminate +the prolog entirely, can't one? So why edit it out? + +I guess the answer is going to be local variables, allocated once for +all by the StartTCMachine routine. Still, it seems quite a pain. I guess +one could sacrifice some (perhaps slight) speed by using a bunch of +globals instead. + +2. You edit out the epilogue for tidiness only, I take it. It doesn't +cause any problems if you leave it in, does it? + +3. Why do you use no-defer-pop (with the associated bug)? + +4. Why does JUMPNEXT have a loop? Surely the jump leaves the loop right +away. Presumably you are tricking the compiler somehow. + +Thanks + +Simon L Peyton Jones +Glasgow University + + + + +Simon +============================= Address change ======================= +My email address is now officially: simonpj@dcs.glasgow.ac.uk +This may fail if your local site has out-of-date mail tables. +The old address (simonpj@cs.glasgow.ac.uk) will work for quite a long while, +so stay with the old one if the new one fails. +==================================================================== + +>From eliot@cs.qmw.ac.uk Fri Apr 5 12:18:18 1991 +Via: uk.ac.qmw.cs; Fri, 5 Apr 91 12:18:06 BST +Received: from aux47 by redstar.cs.qmw.ac.uk id aa26828; 5 Apr 91 12:17 BST +Reply-To: eliot@cs.qmw.ac.uk +In-Reply-To: Simon L Peyton Jones's mail message +<2763.9104050851@tutuila.dcs.glasgow.ac.uk> +Message-Id: <9104051217.aa26828@uk.ac.qmw.cs.redstar> +From: Eliot Miranda <eliot@cs.qmw.ac.uk> +To: simonpj +Cc: partain +Subject: re: Threaded code +Date: Fri, 5 Apr 91 10:54:25 BST + +> +>Eliot +> +>I saw your article about threaded code. Like you and others, we are +>using C as an assembler, only for a pure functional language, Haskell. +>I have some brief questions. +> +>1. By telling GCC not to use a frame pointer, one can eliminate +>the prolog entirely, can't one? So why edit it out? +No, registers local to the procedure will still be saved & stack space +allocated for automatic variables. This IS a problem since the +threaded-code jump at the end of the procedure will miss the register +restores before the epilogue. Consequently the stack will grow unless +these register saves & stack-space allocations are removed. +> +>I guess the answer is going to be local variables, allocated once for +>all by the StartTCMachine routine. Still, it seems quite a pain. I guess +>one could sacrifice some (perhaps slight) speed by using a bunch of +>globals instead. +For certain routines, not using register variables will be expensive +(e.g. a simple integer arithmetic primitive). +> +>2. You edit out the epilogue for tidiness only, I take it. It doesn't +>cause any problems if you leave it in, does it? +No, but given that the prologue has to be removed & removing the epilogue +is as easy (& given finite memory :-) one might as well remove it. +> +>3. Why do you use no-defer-pop (with the associated bug)? +OK. This is again to avoid stack growth. On conventional stack architectures +gcc will try & combine the argument popping code of a sequence of +procedure calls. +e.g. +extern long a, b, c; +void doit() { + foo(a); bar(b); baz(c); +} + +with -O -no-defer-pop one might expect gcc to generate + + link %a6,#0 + movel a,%sp@- + jbsr foo + addqw #4,%sp + movel b,%sp@- + jbsr bar + addqw #4,%sp + movel c,%sp@- + jbsr baz + addqw #4,%sp + unlk %a6 + rts + +but because gcc knows that the unlk instruction will roll back the stack +in fact gcc generates: + + link %a6,#0 + movel a,%sp@- + jbsr foo + addqw #4,%sp + movel b,%sp@- + jbsr bar + addqw #4,%sp + movel c,%sp@- + jbsr baz + unlk %a6 + rts + +With -O -fdefer-pop gcc optimizes out the pops completely & generates: + + link %a6,#0 + movel a,%sp@- + jbsr foo + movel b,%sp@- + jbsr bar + movel c,%sp@- + jbsr baz + unlk %a6 + rts + +with -O -fomit-frame-pointer -fdefer-pop gcc generates: + + movel a,%sp@- + jbsr foo + movel b,%sp@- + jbsr bar + movel c,%sp@- + jbsr baz + addw #12,%sp + rts + +& with -O -fomit-frame-pointer -fno-defer-pop gcc generates: + + movel a,%sp@- + jbsr foo + addqw #4,%sp + movel b,%sp@- + jbsr bar + addqw #4,%sp + movel c,%sp@- + jbsr baz + addqw #4,%sp + rts + +All the above cases are as one would wish. The elimination of all +defered pops in the unlk instruction is especially clever. + +However, in the presence of the threaded-code jump the waters darken! +Consider what gcc generates for: + + register void (**tcip)() asm("%a5"); + + #define JUMPNEXT do{asm("movl %a5@+,%a0; jmp %a0@");return;}while(0) + + extern long a, b; + void doit() { + foo(a); bar(b); JUMPNEXT; + } +with -O -fdefer-pop gcc generates + +doit: + link %a6,#0 + movel a,%sp@- + jbsr foo + movel b,%sp@- + jbsr bar +#APP + movl %a5@+,%a0; jmp %a0@ +#NO_APP + unlk %a6 + rts + +This is clearly no good because the arguments to both foo & bar +will never be popped. Every time doit() is executed the stack will grow +by 8 bytes. Soon your program will dump core with a very large stack +segment! + +with -O -fno-defer-pop gcc generates: + + link %a6,#0 + movel a,%sp@- + jbsr foo + addqw #4,%sp + movel b,%sp@- + jbsr bar +#APP + movl %a5@+,%a0; jmp %a0@ +#NO_APP + unlk %a6 + rts + +Again useless because bar's pop has been folded into the unlk +which won't be executed. + +with -O -fdefer-pop -fomit-frame-pointer gcc generates + + movel a,%sp@- + jbsr foo + movel b,%sp@- + jbsr bar + addqw #8,%sp +#APP + movl %a5@+,%a0; jmp %a0@ +#NO_APP + rts + +This is great. However, not all functions are susceptible to +the omit-frame-pointer optimization (i.e. functions +with local variables). E.g. the code generated for: + + register void (**tcip)() asm("%a5"); + + #define JUMPNEXT do{asm("movl %a5@+,%a0; jmp %a0@");return;}while(0) + + extern long a, b; + void doit() { + char large[1024]; + foo(a,large); bar(b); JUMPNEXT; + } + +with -O -fomit-frame-pointer -fdefer-pop is: + + link %a6,#-1024 + pea %a6@(-1024) + movel a,%sp@- + jbsr foo + movel b,%sp@- + jbsr bar +#APP + movl %a5@+,%a0; jmp %a0@ +#NO_APP + unlk %a6 + rts + +so in general one can't rely on -fomit-frame-pointer. +For the above example both + -O -fomit-frame-pointer -fno-defer-pop +and + -O -fno-defer-pop +generate: + +doit: + link %a6,#-1024 + pea %a6@(-1024) + movel a,%sp@- + jbsr foo + addqw #8,%sp + movel b,%sp@- + jbsr bar +#APP + movl %a5@+,%a0; jmp %a0@ +#NO_APP + unlk %a6 + rts + +This is also useless because bar's argument pop has been folded away. +The problem is that gcc will always fold away the last call's argument +pop if the function has a frame pointer, and -fomit-frame-pointer +can't allways get rid of the frame pointer. In fact, in the presence +of variable sized automatic variables or calls on alloca it would be +very hard (impossible for recursive functions?) to do. + +The eatest solution I've come up with is to use -fno-defer-pop +and a dummy function call between the threaded-code jump and +the return: + + register void (**tcip)() asm("%a5"); + + #define JUMPNEXT do{asm("movl %a5@+,%a0; jmp +%a0@");SBD();return;}while(0) + + extern long a, b; + void doit() { + foo(a); bar(b); JUMPNEXT; + } +with -O -fno-defer-pop gcc generates: + + link %a6,#0 + movel a,%sp@- + jbsr foo + addqw #4,%sp + movel b,%sp@- + jbsr bar + addqw #4,%sp +#APP + movl %a5@+,%a0; jmp %a0@ +#NO_APP + jbsr SBD + unlk %a6 + rts + +Now bar's argument pop is not folded because its no longer the last +call in the routine, SBD is. +So the call to SBD + a) prevents gcc's 'last call argument pop fold into unlk' optimization + which prevents uncontrolled stack growth. + b) doesn't get executed because of the jump + c) is trivial to remove from the assembler with a sed-script + + +>4. Why does JUMPNEXT have a loop? Surely the jump leaves the loop right +>away. Presumably you are tricking the compiler somehow. +> +This is old C lore. The problem is + 'How do you write a macro that is a sequence of statements + that can be used wherever a single statement can?' + +take the following definition of JUMPNEXT: +#define JUMPNEXT asm("movl %a5@+,%a0; jmp %a0@");return; + +Now invoke it here: + if (its_time_to_jump) + JUMPNEXT; + do_something_else(); + +This expands to: + if (its_time_to_jump) + asm("movl %a5@+,%a0; jmp %a0@"); + return; + do_something_else(); + +Not at all whats intended! + +There are two tricks I know of (the first I saw in Berkely Smalltalk, +the second in Richard Stallman's gcc manual. I expect they're both +quite old). +The first is to surround your statements with +if (TRUE){statements}else +i.e. +#define JUMPNEXT if(1){asm("movl %a5@+,%a0; jmp %a0@");return;}else +So now we get: + if (its_time_to_jump) + if (1){ + asm("movl %a5@+,%a0; jmp %a0@"); + return; + else; + do_something_else(); + +which works because C binds elses innermost first. However, some +compilers will whine about dangling elses. The second scheme is +more elegant (-: + +Surround your statements with +do{statements}while(FALSE); +which will execute statements precisely once (its NOT a loop). +i.e. +#define JUMPNEXT do{asm("movl %a5@+,%a0; jmp %a0@");SBD();return;}while(0) +expands to + + if (its_time_to_jump) + do { + asm("movl %a5@+,%a0; jmp %a0@"); + return; + while(0); + do_something_else(); + +which does what's wanted and doesn't incur compiler whines. + + +>Thanks +> +>Simon L Peyton Jones +>Glasgow University + +Eliot Miranda email: eliot@cs.qmw.ac.uk +Dept of Computer Science Tel: 071 975 5229 (+44 71 975 5229) +Queen Mary Westfield College ARPA: eliot%cs.qmw.ac.uk@nsf.ac.uk +Mile End Road UUCP: eliot@qmw-cs.uucp +LONDON E1 4NS + +>From vestal@SRC.Honeywell.COM Fri Apr 5 12:26:11 1991 +From: vestal@SRC.Honeywell.COM (Steve Vestal) +Newsgroups: comp.compilers +Subject: Re: Portable Fast Direct Threaded Code +Keywords: interpreter, performance, design +Date: 3 Apr 91 18:23:34 GMT +Reply-To: vestal@SRC.Honeywell.COM (Steve Vestal) +Organization: Honeywell Systems & Research Center +In-Reply-To: pardo@cs.washington.edu's message of 2 Apr 91 19:21:25 GMT + +In article <1991Apr2.192125.7464@beaver.cs.washington.edu> +pardo@cs.washington.edu (David Keppel) writes: +[references about threaded code, much stuff deleted] + +David> %X Describes how to build a threaded code interpeter/compiler from +David> scratch. +David> * Less than 2:1 performance hit of threading compared to full +David> compilation. + +I have a question about this. Numbers like this are often cited for +threaded-type code, but in Bell's paper this was for the PDP-11 (whose +addressing modes made it a natural for threaded code). Paul Klint's +"Interpretation Techniques" paper (Software P&E, v11, 1981) cites a +significant difference for interpreter fetch/decode times on different +architectures. He cited numbers around 2:1 for the PDP-11, but something +more like 9:1 for a Cyber. I did a Q&D evaluation of this for a RISC, and +the ratio I guestemated was closer to that Klint gave for the Cyber than +for the PDP-11 (not unexpectedly). + +How architecturally dependent is the performance of these techniques +(relative to compiling to native code)? + +Steve Vestal +Mail: Honeywell S&RC MN65-2100, 3660 Technology Drive, Minneapolis MN 55418 +Phone: (612) 782-7049 Internet: vestal@src.honeywell.com +-- +Send compilers articles to compilers@iecc.cambridge.ma.us or +{ima | spdcc | world}!iecc!compilers. Meta-mail to compilers-request. + +>From E.Ireland@massey.ac.nz Fri Apr 5 12:29:20 1991 +From: E.Ireland@massey.ac.nz (Evan Ireland) +Newsgroups: comp.lang.functional +Subject: Three address code +Date: 4 Apr 91 21:49:21 GMT +Reply-To: E.Ireland@massey.ac.nz +Organization: Information Sciences, Massey University, New Zealand + +I've had no luck with mail, so this is for csdw at Rhodes University. + +> +>In an attempt to optimize a functional language, I would like to +>turn the stack based intermediate code into three address code. +> +>Has anyone done similar conversions? Any references would be +>greatly appreciated. + +I do not have any references, but I thought that one aspect of my FAM +implementation might be of interest. + +A number of interpreters and compilers that I have seen implement a stack +pointer in a register or global variable. Then to implement various stack +operations, they use auto-increment or auto-decrement operations on the stack +pointer register. Since I generate portable C, and thus cannot assume I have + + DATA *f (register DATA *fp) + { + .... + } + +Thus I pass to each function the current pointer to top of stack, from which it +can index downwards to find its arguments. Within the function, I use indexing +operations on fp, e.g. fp[3] = fp[1], to manipulate values on the stack, so I +am not continually manipulating the stack pointer. If "f" calls another +function, it will pass the address of the current top of stack, e.g. g (&f[5]). + +The advantage to me is that I have a register for a stack pointer even though I +am generating portable C code. + +Now the relationship to three-address code. If you adopt such a scheme, and +your three address instructions allow some indexing, you can sometimes generate + + ADD fp[3],f[4],fp[3] + +I hope this helps. +_______________________________________________________________________________ + +E.Ireland@massey.ac.nz Evan Ireland, School of Information Sciences, + +64 63 69099 x8541 Massey University, Palmerston North, New Zealand. + +>From pardo@cs.washington.edu Sat Apr 6 14:32:24 1991 +From: pardo@cs.washington.edu (David Keppel) +Newsgroups: comp.compilers +Subject: Re: Portable Fast Direct Threaded Code +Keywords: interpreter, performance, design +Date: 4 Apr 91 17:10:55 GMT +Reply-To: pardo@cs.washington.edu (David Keppel) +Organization: Computer Science & Engineering, U. of Washington, Seattle + +>>>[Threaded code vs. compilation] + +>pardo@cs.washington.edu (David Keppel) writes: +>>[Less than 2:1 performance hit of threading vs. full compilation.] + +Note also that the reference that claimed 2:1 (Peter M. Kogge, IEEE +Computer pp 22-33 March 1982) also attributed part of that ratio to the +poor state of compiler optimization. + + +vestal@SRC.Honeywell.COM (Steve Vestal) writes: +>[Klint says 2:1 for PDP-11 v. 9:1 for Cyber. +> How architecturally dependent are these techniques?] + +Suppose that the statically-compiled code fragments that are threaded +together are called `primitives'. + + +When the execution time of a primitive is large, then the overhead for the +interpreter can be large and still have a small effect on performance. +The performance of the interpreted code is dominated by the time in a +primitive vs. the overhead of moving between primitives. + +When the execution time of the primitives is small, then the overhead for +moving between primitives can be a large fraction of the total execution +time. Overhead comes from at least two sources: + + * Control flow: the address of the the next primitive is loaded + from data memory and the processor executes an indirect jump. + + * Register allocation: a primitive is essentially a function with + a fast calling convention (no stack adjustment). Thus, all the + traditional problems with interprocedural register allocation. + +Examples of `large primitives' are ``draw circle'' and ``interpolate +spline''. Examplees of small primitives are ``push'', ``add'', etc. + + +* Architectural dependency of control flow + +Examples: + + Direct jumps in full compilation: + + op1 + op2 + br next // direct jump + + Indirect jumps for threading for a CISC: + + op1 + op2 + br *(r0)+ // load, increment, jump + + Indirect jumps for threading for a RISC: + + ld *r0, r1 // scheduled load + op1 + op2 + br *r1 // jump + add r1, #4, r1 // delay slot increment + +Direct jumps in full compilation can frequently use one instruction (a +``near branch'') both to find the address of the next code fragment and +perform the control transfer. On a CISC, branches are typically two or +three bytes. On a RISC, branches are typically four bytes. The threaded +indirect (load, increment, jump) is typically three bytes on a CISC and +twelve bytes (three instructions) on a RISC. + +Direct jumps in full compilation take typically one instruction time. +Indirect jumps take at least the following operations: load, increment, +jump indirect. On a CISC, the three operations can typically be `folded' +in to one instruction. There may be a load penalty of one instruction +time but the increment is overlapped, so the total time is three machine +units (one `unit' is about one register->register operation). On a RISC, +the total penalty is three machine units. + +Direct jumps take one (I-cache) cycle to fetch both the branch instruction +and the address of the branch target. Indirect jumps take a D-cache cycle +to fetch the address of the branch target and an I-cache cycle to fetch +the branch instruction. + +Direct jumps can take advantage of instruction prefetching since the +address of the next instruction is known at the time that the instruction +prefetch reads the direct jump. Threaded indirects require an indirect +branch off of a register. Current RISC and CISC machines are about +equivalent in that they do little prefetching. Some machines being +designed do more prefetching so the threading overhead for them will be +greater. + + +* Architectural dependency of register allocation + +In a machine with a small number of registers, many of the registers are +in-use in each primitive and the best possible register allocation will +contain many loads and stores. In a machine with a large number of +registers, the full-compilation implementation can make much better use of +registers than the threaded primitives implementation (again, for small +primitives). The savings from full compilation are exactly analagous to +the improvements in register allocation from doing inlining of small +procedures. + + +* Other points to ponder + +In some cases the threaded code implementation is substantially smaller +than the full-compilation implementation. For large functions or a +machine with small caches, the loss of performance from threading might be +overwhelmed by the gain in cache performance. + +On RISC machines, procedure call/return is about twice the cost of other +control flow, except for the overhead of register management. Thus, +call-dense RISC code from full compilation may behave about the same as +threaded code. +-- +Send compilers articles to compilers@iecc.cambridge.ma.us or +{ima | spdcc | world}!iecc!compilers. Meta-mail to compilers-request. + +>From airs!ian@uunet.UU.NET Sat Apr 6 14:32:56 1991 +From: airs!ian@uunet.UU.NET (Ian Lance Taylor) +Newsgroups: comp.compilers +Subject: Threaded code +Keywords: books, interpreter, design +Date: 4 Apr 91 07:19:41 GMT +Reply-To: airs!ian@uunet.UU.NET (Ian Lance Taylor) +Organization: Compilers Central + +The book ``Threaded Interpretive Languages'' has a quite complete +implementation of a threaded version of Forth in Z80 assembler. It's +a very complete description of why threaded implementations exist and +how to implement them easily. It's by R. G. Loeliger and was +published by Byte Books (ISBN 0-07-038360-X). It was published in +1981, though, and I'm sure it's long out of print. + +Ian Taylor airs!ian@uunet.uu.net uunet!airs!ian +-- +Send compilers articles to compilers@iecc.cambridge.ma.us or +{ima | spdcc | world}!iecc!compilers. Meta-mail to compilers-request. + +>From firth@sei.cmu.edu Sun Apr 7 14:33:13 1991 +From: firth@sei.cmu.edu (Robert Firth) +Newsgroups: comp.compilers +Subject: Re: Portable Fast Direct Threaded Code +Keywords: interpreter, performance, design +Date: 4 Apr 91 13:27:21 GMT +Reply-To: firth@sei.cmu.edu (Robert Firth) +Organization: Software Engineering Institute, Pittsburgh, PA + +In article <1991Apr3.182334.16164@src.honeywell.com> +vestal@SRC.Honeywell.COM (Steve Vestal) writes: + +>How architecturally dependent is the performance of these techniques +>(relative to compiling to native code)? + +[cost of threaded code on PDP-11, RISC &c] + +We might have a misunderstanding here, because what I think of as threaded +code doesn't have a decoding and interpretation step. But I'll talk of +what I know. + +A program in threaded code is just an array of addresses, possibly +interspersed with operands. So the fragment + + c := a + b + +becomes something like + + address of 'load' + address of 'a' + address of 'load' + address of 'b' + address of '+' + address of 'store' + address of 'c' + +This implies a very simple virtual stack machine - you can get more clever +by implementing a virtual register machine. + +The basic execution thread then does this. We point a global register at +the table of addresses, and each primitive has the form + + treg := treg + address'size + ... + jump (treg) + +As you can see, this is great on the PDP-11, since that reduces to one +instruction + + MOV (treg)+,PC ; NOTE TO MAINTAINER: FASTER THAN JMP - DON'T TOUCH! + +On a typical RISC machine, it's two cycles, since you can put almost +anything in the delay slot(s) after the jump. + +Now, the load instruction, for instance, would say + +load: treg := treg + address'size + load (treg) into tempreg + treg := treg + address'size + push (tempreg) onto simulated stack + jump (treg) + +On the PDP-11, that's + + MOV @(treg)+, -(SP) + MOV (treg)+, PC + +On a RISC, it's much more like + + L R0, 4(treg) ; get operand address + L R0, 0(R0) ; dereference to get operand + SUBI SP, #4 ; decrement simulated SP + S R0, 0(SP) ; push operand on stack + ADDI treg, #8 ; step over two addresses (mine & operands) + JR (treg) ; over to you, Moriarty! + +[to fill delay slots, shuffle the above to 132564] + +Well, if you have one load delay slot and one branch delay slot, you can +fill all three of them, so that's 6 cycles. Given that a typical load is +only 1.1 cycles in direct code (90% of the delays filled), this is +certainly a lot more than a 2:1 overhead! When you add the cost of a +simulated stack (lots of needless loads and stores), I can well believe +10:1 time expansion for simple code. + +In fact, it was more than that on the PDP-11, if you compared threaded +code with direct code from a decent compiler. The big win in the Fortran +compiler came from (a) very compact threaded code, and (b) the floating +point operations were implemented in software, so the overhead of threaded +code was swamped by the cost of floating addition, subtraction &c. + +Here's the full code of the above example, so you can see for yourself + +Direct: + MOV a, R0 + ADD b, R0 + MOV R0, c + +Threaded: + MOV @(treg)+, -(SP) + MOV (treg)+, PC +* MOV @(treg)+, -(SP) +* MOV (treg)+, PC +* ADD (SP)+,(SP) + MOV (treg)+, PC + MOV (SP)+, @(treg)+ + MOV (treg)+, PC + +Note that, if you implement a one-address add, you save two instructions, +since the *** bit reduces to + + ADD @(treg)+, (SP) + +But even then, it's coming out at over 4:1. + +What architectural features make threaded code more efficient? The +fundamental one is main memory that is fast (or not too slow) relative to +registers, since you're doing a lot more fetching. Another is a set of +address modes with double indirection, since you're accessing most +operands one level of indirection further back. And good old +autoincrement helps a little, too. Alas, none of that says 'risc', and +much of it says '1960s'. + +Incidentally, if I were to do this again today, I'd definitely simulate a +general-register machine and use a subset of the real machine's registers. +If you take 8 of them, you then have 8 loads and stores, one for each +register, but if you make an absolute rule that nobody even thinks about +touching one of those 8 that doesn't belong to him, then all the good +tricks about register allocation, slaving &c will still work. If you then +implement the operations as one-address general-register, you have again 8 +versions (add into R0, add into R1, ...) and lo! you're programming a very +familiar old friend. + +"But that was in another country, and besides, the machine is dead..." + +Robert Firth +-- +Send compilers articles to compilers@iecc.cambridge.ma.us or +{ima | spdcc | world}!iecc!compilers. Meta-mail to compilers-request. + +>From bpendlet@bambam.es.com Tue Apr 9 20:35:22 1991 +From: bpendlet@bambam.es.com (Bob Pendleton) +Newsgroups: comp.compilers +Subject: Re: Portable Fast Direct Threaded Code +Keywords: interpreter, design +Date: 8 Apr 91 19:48:00 GMT +Reply-To: bpendlet@bambam.es.com (Bob Pendleton) +Organization: Compilers Central + +In article <23613@as0c.sei.cmu.edu> you write: + +> A program in threaded code is just an array of addresses, possibly +> interspersed with operands. So the fragment +> +> c := a + b +> +> becomes something like +> +> address of 'load' +> address of 'a' +> address of 'load' +> address of 'b' +> address of '+' +> address of 'store' +> address of 'c' +> +> This implies a very simple virtual stack machine - you can get more clever +> by implementing a virtual register machine. + +About 10 years ago I was working on a lisp compler that compiled to +threaded code. I was trying to get small code and still have some +performance. (Since I wanted to run the code on a Z80 or 8080 small was +important. My how things change :-) + +I found that the 3 most common operations in threaded code were load, +store, and execute. So I put those operations with the operands. This +made the operands look rather like classes with load, store, and +execute as virtual functions. If you let the evaluate operation +subsume the load and execute operations the threaded code for + + c := a + b; + +becomes + + address of 'a.evaluate()' + address of 'b.evaluate()' + address of '+' + address of 'c.store()' + +and + + g := F(x, y); + +becomes + + address of 'x.evaluate()' + address of 'y.evaluate()' + address of 'F.evaluate()' + address of 'g.store()' + + +Which is much smaller than the original version of threaded code. + +Later, while working on a homebrew version of FORTH I gave up on +threaded code completely. I found, like most who have expolored it, +that symbolic execution of RPN code is a nice way to generated machine +code. Machine code that runs much faster than threaded code, and that +the machine code, even on an 8080, was only about 25% bigger than +threaded code. +-- + Bob Pendleton + bpendlet@dsd.es.com or decwrl!esunix!bpendlet or utah-cs!esunix!bpendlet +[The DEC PDP-11 Fortran compiler did something similar, writing load routines +for commonly used variables. -John] +-- +Send compilers articles to compilers@iecc.cambridge.ma.us or +{ima | spdcc | world}!iecc!compilers. Meta-mail to compilers-request. + +>From pardo@june.cs.washington.edu Wed Apr 24 09:26:32 1991 +From: pardo@june.cs.washington.edu (David Keppel) +Newsgroups: comp.compilers +Subject: Re: Fast Interpreted Code +Keywords: interpreter, threaded code +Date: 23 Apr 91 02:06:21 GMT +Reply-To: pardo@june.cs.washington.edu (David Keppel) +Organization: Computer Science & Engineering, U. of Washington, Seattle + +ssinghani@viewlogic.com (Sunder Singhani) writes: +>[Our threaded code isn't fast enough. What's faster?] + +As far as I know, threaded code gives the fastest primitives/second +dispatch rate on a variety of architectures. The general techniques for +making things faster (that I know of!) are to change things so that the +dispatch rate can go down without changing the work that gets done (or use +hardware, but we'll ignore that for the moment.) + +* Use a different v-machine instruction set + + The overhead of interpreting is almost nothing in generic PostScript + imaging code because all the time is spent in non-interpretded + primitives. If you can characterize your key operations (perhaps + info in [Davidson & Fraser ??, Fraser, Myers & Wendt 84] can help + you analyze for common operations instead of the more normal time in + routines) then you can re-code your virtual instruction set to have + as primintives oeprations that are performed frequently. + +* Dynamic compilation to native machine code + + This is what is done in ParcPlace System's Smalltalk-80 + implementation, [Deutsch & Schiffman 84] also Insignia Solution's + 8086 interpreter. + + Dynamic compilation suffers from the need to do compilation at + runtime: a compiler that produces better code will take longer to + run and the compile time contributes to the overall program runtime. + Also, program text isn't shared, even if multiple instances are + running simultaneously. + +* Native-coding key routines + + If you believe that your program spends 80% of its time in a few key + routines, then compiling just these routines -- statically, adding + them to the primitive set, statically adding them as library + routines, or dynamically -- can improve performance substantially + [Pittman 87]. + + +5 Citations follow: + +%A Robert Bedichek +%T Some Efficient Architecture Simulation Techniques +%J Winter '90 USENIX Conference +%D 26 October, 1989 +%W Robert Bedichek. +%W Pardo has a copy. +%X Describes a simulator that uses threaded-code techniques to emulate +a Motorola 88000. Each 88k instruction is executed in about 20 host +(68020) instructions. Discusses techniques used to get the simulation +down from several thousand host instructions in many other +simulators. + +%A Jack W. Davidson +%A Chris W. Fraser +%T Eliminating Redundant Object Code +%J POPL9 +%P 128-132 + +%A Peter Deutsch +%A Alan M. Schiffman +%T Efficient Implementation of the Smalltalk-80 System +%J 11th Annual Symposium on Principles of Programming Languages +(POPL 11) +%D January 1984 +%P 297-302 +%X Dynamic translatin of p-code to n-code (native code). +Resons for not using straight p-code or straight n-code: + * p-code is smaller than n-code (<= 5X). + * The debugger can debug p-code, improving portability. + * Native code is faster (<= 2X). Reasons include +special fetch/decode/dispatch hardware; +p-machine and n-machine may be very different, e.g., +stack machine vs. register-oriented. + * Threaded code does reduce the cost of p-code fetch/decode. +Does not help with operand decoding. +Does not allow optimizations to span more than one instruction. +[pardo: that's not technically true, but each optimized +instruction must exist in addition to the unoptimized version. +That leads to exponential blowup of the p-code. Example: delayed +branch and non-delayed branch versions of Robert Bedichek's 88k +simulator.] + The system characteristics: + * The time to translate to n-code via macro expansion is about the +same as the execute time to interpret the p-code. + * (pg 300:) Self-modifying code (SMC) is deprecated but used in a +``well-confined'' way. Could indirect at more cost. Use SMC on the +machines where it works, indirection where SMC. +doesn't. + * Performance is compared to a ``straightforward'' interpreter. +What's that? + +%A Christopher W. Fraser +%A Eugene W. Myers +%A Alan L. Wendt +%T Analyzing and Compressing Assembly Code +%J CCC84 +%P 117-121 + +%A Thomas Pittman +%T Two-Level Hybrid Interpreter/Native Code Execution for Combined +Space-Time Program Efficiency +%D 1987 +%J ACM SIGPLAN +%P 150-152 +%X Talks about native code execution vs. various kinds of interpreting +and encoding of key routines in assembly. + + +Hope this helps! + + ;-D on ( This is all open to interpretation ) Pardo +-- +Send compilers articles to compilers@iecc.cambridge.ma.us or +{ima | spdcc | world}!iecc!compilers. Meta-mail to compilers-request. + +>From eliot@cs.qmw.ac.uk Tue Apr 30 15:55:17 1991 +From: eliot@cs.qmw.ac.uk (Eliot Miranda) +Newsgroups: comp.compilers,gnu.gcc.bug,alt.sources +Subject: re: Threaded Code +Keywords: design, interpreter +Date: 5 Apr 91 11:43:51 GMT +Reply-To: Eliot Miranda <eliot@cs.qmw.ac.uk> +Followup-To: comp.compilers +Organization: Computer Science Dept, QMW, University of London, UK. + +I recently posted articles to comp.compilers & alt.sources on how +to write threaded code machines in C. I received the following questions +from Simon Peyton Jones at Glasgow. They are specific to GCC. +Since they have non-obvious answers & since the answers suggest +augmentation of the GCC compiler I'm posting my response to Simon. + +>From: Simon L Peyton Jones <simonpj@cs.gla.ac.uk> +> +>I saw your article about threaded code. Like you and others, we are +>using C as an assembler, only for a pure functional language, Haskell. +>I have some brief questions. +> +>1. By telling GCC not to use a frame pointer, one can eliminate +>the prolog entirely, can't one? So why edit it out? + +No, registers local to the procedure will still be saved & stack space +allocated for automatic variables. This IS a problem since the +threaded-code jump at the end of the procedure will miss the register +restores before the epilogue. Consequently the stack will grow unless +these register saves & stack-space allocations are removed. Also +GCC can not always eliminate the frame pointer. + +>I guess the answer is going to be local variables, allocated once for +>all by the StartTCMachine routine. Still, it seems quite a pain. I guess +>one could sacrifice some (perhaps slight) speed by using a bunch of +>globals instead. +For certain routines, not using register variables will be expensive +(e.g. a simple integer arithmetic primitive). + +>2. You edit out the epilogue for tidiness only, I take it. It doesn't +>cause any problems if you leave it in, does it? +No, but given that the prologue has to be removed & removing the epilogue +is as easy (& given finite memory :-) one might as well remove it. +> +>3. Why do you use no-defer-pop (with the associated bug)? +OK. This is again to avoid stack growth. On conventional stack architectures +gcc will try & combine the argument popping code of a sequence of +procedure calls. +e.g. +extern long a, b, c; +void doit() { + foo(a); bar(b); baz(c); +} + +with -O -no-defer-pop one might expect gcc to generate + + link %a6,#0 + movel a,%sp@- + jbsr foo + addqw #4,%sp + movel b,%sp@- + jbsr bar + addqw #4,%sp + movel c,%sp@- + jbsr baz + addqw #4,%sp + unlk %a6 + rts + +but because gcc knows that the unlk instruction will roll back the stack +in fact gcc generates: + + link %a6,#0 + movel a,%sp@- + jbsr foo + addqw #4,%sp + movel b,%sp@- + jbsr bar + addqw #4,%sp + movel c,%sp@- + jbsr baz + unlk %a6 + rts + +With -O -fdefer-pop gcc optimizes out the pops completely & generates: + + link %a6,#0 + movel a,%sp@- + jbsr foo + movel b,%sp@- + jbsr bar + movel c,%sp@- + jbsr baz + unlk %a6 + rts + +with -O -fomit-frame-pointer -fdefer-pop gcc generates: + + movel a,%sp@- + jbsr foo + movel b,%sp@- + jbsr bar + movel c,%sp@- + jbsr baz + addw #12,%sp + rts + +& with -O -fomit-frame-pointer -fno-defer-pop gcc generates: + + movel a,%sp@- + jbsr foo + addqw #4,%sp + movel b,%sp@- + jbsr bar + addqw #4,%sp + movel c,%sp@- + jbsr baz + addqw #4,%sp + rts + +All the above cases are as one would wish. The elimination of all +defered pops in the unlk instruction is especially clever. + +However, in the presence of the threaded-code jump the waters darken! +Consider what gcc generates for: + + register void (**tcip)() asm("%a5"); + + #define JUMPNEXT do{asm("movl %a5@+,%a0; jmp %a0@");return;}while(0) + + extern long a, b; + void doit() { + foo(a); bar(b); JUMPNEXT; + } +with -O -fdefer-pop gcc generates + +doit: + link %a6,#0 + movel a,%sp@- + jbsr foo + movel b,%sp@- + jbsr bar +#APP + movl %a5@+,%a0; jmp %a0@ +#NO_APP + unlk %a6 + rts + +This is clearly no good because the arguments to both foo & bar +will never be popped. Every time doit() is executed the stack will grow +by 8 bytes. Soon your program will dump core with a very large stack +segment! + +with -O -fno-defer-pop gcc generates: + + link %a6,#0 + movel a,%sp@- + jbsr foo + addqw #4,%sp + movel b,%sp@- + jbsr bar +#APP + movl %a5@+,%a0; jmp %a0@ +#NO_APP + unlk %a6 + rts + +Again useless because bar's pop has been folded into the unlk +which won't be executed. + +with -O -fdefer-pop -fomit-frame-pointer gcc generates + + movel a,%sp@- + jbsr foo + movel b,%sp@- + jbsr bar + addqw #8,%sp +#APP + movl %a5@+,%a0; jmp %a0@ +#NO_APP + rts + +This is great. However, not all functions are susceptible to +the omit-frame-pointer optimization (i.e. functions +with local variables). E.g. the code generated for: + + register void (**tcip)() asm("%a5"); + + #define JUMPNEXT do{asm("movl %a5@+,%a0; jmp %a0@");return;}while(0) + + extern long a, b; + void doit() { + char large[1024]; + foo(a,large); bar(b); JUMPNEXT; + } + +with -O -fomit-frame-pointer -fdefer-pop is: + + link %a6,#-1024 + pea %a6@(-1024) + movel a,%sp@- + jbsr foo + movel b,%sp@- + jbsr bar +#APP + movl %a5@+,%a0; jmp %a0@ +#NO_APP + unlk %a6 + rts + +so in general one can't rely on -fomit-frame-pointer. +For the above example both + -O -fomit-frame-pointer -fno-defer-pop +and + -O -fno-defer-pop +generate: + +doit: + link %a6,#-1024 + pea %a6@(-1024) + movel a,%sp@- + jbsr foo + addqw #8,%sp + movel b,%sp@- + jbsr bar +#APP + movl %a5@+,%a0; jmp %a0@ +#NO_APP + unlk %a6 + rts + +This is also useless because bar's argument pop has been folded away. The +problem is that gcc will always fold away the last call's argument pop if +the function has a frame pointer, and -fomit-frame-pointer can't allways +get rid of the frame pointer. In fact, in the presence of variable sized +automatic variables or calls on alloca it would be very hard (impossible +for recursive functions?) to do. + +The neatest solution I've come up with is to use -fno-defer-pop and a +dummy function call between the threaded-code jump and the return: + + register void (**tcip)() asm("%a5"); + + #define JUMPNEXT do{asm("movl %a5@+,%a0; jmp +%a0@");SBD();return;}while(0) + + extern long a, b; + void doit() { + foo(a); bar(b); JUMPNEXT; + } +with -O -fno-defer-pop gcc generates: + + link %a6,#0 + movel a,%sp@- + jbsr foo + addqw #4,%sp + movel b,%sp@- + jbsr bar + addqw #4,%sp +#APP + movl %a5@+,%a0; jmp %a0@ +#NO_APP + jbsr SBD + unlk %a6 + rts + +Now bar's argument pop is not folded because its no longer the last +call in the routine, SBD is. +So the call to SBD + a) prevents gcc's 'last call argument pop fold into unlk' optimization + which prevents uncontrolled stack growth. + b) doesn't get executed because of the jump + c) is trivial to remove from the assembler with a sed-script + + +One an try to use -fcaller-saves, but this surrounds calls with unnecessary +register saves & restores that for the code to be optimal have to be +edited out. + +>4. Why does JUMPNEXT have a loop? Surely the jump leaves the loop right +>away. Presumably you are tricking the compiler somehow. + +This is old C lore. The problem is + 'How do you write a macro that is a sequence of statements + that can be used wherever a single statement can?' + +take the following definition of JUMPNEXT: +#define JUMPNEXT asm("movl %a5@+,%a0; jmp %a0@");return; + +Now invoke it here: + if (its_time_to_jump) + JUMPNEXT; + do_something_else(); + +This expands to: + if (its_time_to_jump) + asm("movl %a5@+,%a0; jmp %a0@"); + return; + do_something_else(); + +Not at all whats intended! + +There are two tricks I know of (the first I saw in Berkely Smalltalk, +the second in Richard Stallman's gcc manual. I expect they're both +quite old). +The first is to surround your statements with +if (TRUE){statements}else +i.e. +#define JUMPNEXT if(1){asm("movl %a5@+,%a0; jmp %a0@");return;}else +So now we get: + if (its_time_to_jump) + if (1){ + asm("movl %a5@+,%a0; jmp %a0@"); + return; + else; + do_something_else(); + +which works because C binds elses innermost first. However, some +compilers will whine about dangling elses. The second scheme is +more elegant (-: + +Surround your statements with +do{statements}while(FALSE); +which will execute statements precisely once (its NOT a loop). +i.e. +#define JUMPNEXT do{asm("movl %a5@+,%a0; jmp %a0@");SBD();return;}while(0) +expands to + + if (its_time_to_jump) + do { + asm("movl %a5@+,%a0; jmp %a0@"); + return; + while(0); + do_something_else(); + +which does what's wanted and doesn't incur compiler whines. + + +>Thanks +> +>Simon L Peyton Jones, Glasgow University + +More and more people are taking the 'use C as an assembler' route, and +more and more people are using GCC to do it (because its code quality is +good, it had global register variables, and it has an excellent asm +facility). The threaded-code in C idea is also becomming more popular. +But as the code above demonstrates, one does have to side-step +optimizations and develop system-specific assembler editing scripts. + +I'd like to ask Richard Stallman & the GCC development team for + -fno-prolog -fno-epilog +flags that instruct gcc to generate + a) no register saves or restores + b) no automatic variable allocation + c) no procedure linkage/frame creation + +Then the optimal 'Threaded-Code Machine in GCC C' can be compiled without +any assembler editing scripts at all. + +Also nice would be a way of telling GCC that an asm statement +changed the flow of control so GCC could + a) warn about not-reached code + b) eliminate unnecessary code (do more code folding) +-- +Eliot Miranda email: eliot@cs.qmw.ac.uk +Dept of Computer Science Tel: 071 975 5229 (+44 71 975 5229) +Queen Mary Westfield College ARPA: eliot%cs.qmw.ac.uk@nsf.ac.uk +Mile End Road UUCP: eliot@qmw-cs.uucp +LONDON E1 4NS +-- +Send compilers articles to compilers@iecc.cambridge.ma.us or +{ima | spdcc | world}!iecc!compilers. Meta-mail to compilers-request. + +>From brennan@bcsaic.boeing.com Sat May 4 11:28:41 1991 +From: brennan@bcsaic.boeing.com (Michael D Brennan) +Newsgroups: comp.compilers +Subject: re: Threaded code +Keywords: interpreter, design +Date: 2 May 91 19:50:23 GMT +Reply-To: brennan@bcsaic.boeing.com (Michael D Brennan) +Organization: Boeing Aerospace & Electronics, Seattle WA + +Another method for obtaining threaded byte code for an interpreter +is to edit the assembler output of a big switch +rather than editing the prologue and epilogue off functions calls. + +You don't need gcc, global vars in registers, works with smart and +dumb compilers, and all optimization can be turned on. + +For example: + +This C routine executes (unthreaded) byte code for an interpreter +that can add, subtract and print. + +#define HALT 0 +#define PUSH 1 +#define ADD 2 +#define SUB 3 +#define PRINT 4 + +static int stack[32] ; + +void execute(code_ptr) + register int *code_ptr ; +{ + register int *stack_ptr = stack - 1 ; + + + while ( 1 ) + { + switch( *code_ptr++ ) + { + case HALT : return ; + case PUSH : + * ++ stack_ptr = *code_ptr++ ; + break ; + + case ADD : + stack_ptr-- ; + *stack_ptr += stack_ptr[1] ; + break ; + + case SUB : + stack_ptr-- ; + *stack_ptr -= stack_ptr[1] ; + break ; + + case PRINT : + printf("%d\n", *stack_ptr--); + break ; + } + } +} + +------------------------------------------------------- + +to interpret 2 + (3 - 4) + +the front end "compiles" in int code[] + +PUSH, 2, PUSH, 3, PUSH, 4, SUB, ADD, PRINT, HALT + +and calls execute(code). + +------------------------------------------------------ + +The difference between this and the threaded code discussed over +the last few weeks is the switch gets compiled as + + jmp TABLE[ *code_ptr++ ] + +where TABLE is the jump table generated by the compiler which holds +the addresses of the case labels. + +With threading, the transitions between functions become + + jmp *code_ptr++ + + +but this is easy to get by editing the assembler output to +export the case label and recode the switch. + +-------------------------------------------------- + +For example on a SPARC: + +code_ptr is %o0 +stack_ptr is %i5 + + + ..... + ! case PUSH +L77004: + ld [%i0],%o1 + inc 4,%i5 + inc 4,%i0 + b L77008 + st %o1,[%i5] + + ..... + + ! the switch, doesn't change structure + ! as you add new op codes + +L77008: + mov %i0,%i4 + ld [%i4],%i4 + inc 4,%i0 + cmp %i4,4 + bgu L77008 + sll %i4,2,%i4 + sethi %hi(L2000000),%o1 + or %o1,%lo(L2000000),%o1 ! [internal] + ld [%i4+%o1],%o0 + jmp %o0 + nop +L2000000: ! the jump TABLE + .word L77003 ! HALT etc + .word L77004 + .word L77005 + .word L77006 + .word L77007 + + +------------------------------------------- +modify by adding global labels and edit the switch + + + + ..... + ! case PUSH +_push : +L77004: + ld [%i0],%o1 + inc 4,%i5 + inc 4,%i0 + b L77008 + st %o1,[%i5] + + ..... + + ! the edited switch +L77008: + mov %i0,%i4 + ld [%i4],%i4 + inc 4,%i0 + jmp %i4 + nop + ! remove TABLE + +------------------------------------------- + +For another example on an Intel 8088 + +stack_ptr is si +code_ptr is di + + ; while ( 1 ) + ; { + ; switch( *code_ptr++ ) + ; +@1@50: + mov bx,di + inc di + inc di + mov bx,word ptr [bx] + cmp bx,3 + ja short @1@50 + shl bx,1 + jmp word ptr cs:@1@C738[bx] + + +@1@122: + ; + ; case PUSH : + ; * ++ stack_ptr = *code_ptr++ ; + ; + inc si + inc si + mov ax,word ptr [di] + mov word ptr [si],ax + inc di + inc di + ; + ; break ; + ; + jmp short @1@50 + ; + + .... + +@1@C738 label word ; jump TABLE + dw @1@194 ; HALT + dw @1@122 ; PUSH etc + dw @1@146 + + .... + +------------------------------------------------ + +edited the jump can be computed inline + + ; while ( 1 ) + ; { + ; switch( *code_ptr++ ) + ; +@1@50: ; switch code is replaced by code only executed once + + inc di + inc di + jmp [di-2] + + ..... + +_push : +@1@122: + ; + ; case PUSH : + ; * ++ stack_ptr = *code_ptr++ ; + ; + inc si + inc si + mov ax,word ptr [di] + mov word ptr [si],ax + inc di + inc di + ; + ; break ; + ; + inc di ; jmp to *code_ptr++ inline + inc di + jmp [di-2] + ; + .... + +---------------------------------------------- + +the "front end" has defines + +typedef void (*TCODE)() ; + +extern void halt(), push(), add(), sub(), print() ; + +TCODE code[CODESIZE] ; + +in the array code[], the front end compiles + + +push, 2, push, 3, push, 4, sub, add, print, halt + +and calls execute(code). + + +-- +Mike Brennan +brennan@bcsaic.boeing.com +-- +Send compilers articles to compilers@iecc.cambridge.ma.us or +{ima | spdcc | world}!iecc!compilers. Meta-mail to compilers-request. + + diff --git a/ghc/docs/NOTES.core-overview b/ghc/docs/NOTES.core-overview new file mode 100644 index 0000000000..8f222994cb --- /dev/null +++ b/ghc/docs/NOTES.core-overview @@ -0,0 +1,94 @@ +\documentstyle[11pt,a4wide]{article} +\begin{document} + +%**************************************** +%* * +%* The Core language * +%* * +%**************************************** + + +\title{The Core language} +\author{Simon L Peyton Jones \and +Will Partain \and +Patrick Sansom} + +\maketitle + +\section{Introduction} + +This document describes the Glasgow Haskell Core-language data type +in sufficient detail for an implementor to be able to use it. + +\section{Overview} + +The Core language is, roughly speaking, the second-order polymorphic +lambda calculus, augmented with @let@, @letrec@ and @case@. +It is a Haskell data type (defined shortly), but for convenience in this +document we give it the concrete syntax given in Figure~\ref{fig:core-syntax}. + +Here are some of its important characteristics: +\begin{description} +\item[The Core language includes the second-order lambda calculus.] +That is, type abstraction and type application are provided. +\item[Constructors and primitive operators are always saturated.] +This is easily done by adding extra lambdas and performing $\eta$-expansion. +\item[All pattern-matching is done by simple @case@ expressions.] +The @case@ expressions are simple in the sense that their patterns +have only one level. +\item[Every identifier includes its type.] +This is not immediately obvious from the syntax, but will be fleshed out +later. The point is that it is easy to tell the type of any identifier or, +in general, any Core expression. +\item[There is no shadowing.] +Identifiers may not be globally unique, +but there are no ``holes in the scope'' of any identifier. +\end{description} +All these properties should be maintained by programs which manipulate Core-langauge +programs. + +\section{Identifiers: the type @Id@} + +Identifiers have the (abstract) type @Id@. +\begin{description} +\item[Equality.] +Identifiers have a unique number inside them, +so they can be compared efficiently for equality. +They are an instance of the class @Eq@. +\item[Type.] +The function +\begin{verbatim} + getIdUniType :: Id -> UniType +\end{verbatim} + gets the type of an identifer. + \end{description} + + \section{Types: the type @UniType@} + + \subsection{@TyCon@} + + The type @TyCon@ ranges over {\em data} type constructors, + not over the function type constructor. + + A @TyCon@ can be one of: + \begin{itemize} + \item A primitive type. + \item A tuple type. + \item An algebraic data type (other than tuples). + \end{itemize} + + \section{The Core language data type} + + \subsection{@coreExpr@} + +Tycon in @case@. + +\subsection{@coreBinding@} + +\subsection{@coreProgram@} + +\subsection{@plainCore@ things} + + + +\end{document} diff --git a/ghc/docs/NOTES.desugar b/ghc/docs/NOTES.desugar new file mode 100644 index 0000000000..b9e6ce7a57 --- /dev/null +++ b/ghc/docs/NOTES.desugar @@ -0,0 +1,323 @@ +(91/08/08: OLD!) + +These are notes about a _simple_ but complete pattern-matching +compiler for Haskell. I presume familiarity with Phil's +pattern-matching stuff in Simon's book and use roughly the same notation. + +Abbreviations: "p" for pattern, "e" (or "E") for expression, "g" for +guard, "v" for variable, "u" for new variable I made up. "[]" for +FATBAR. + +Subscripts: "p11" is really short for "p_{1,1}". Sometimes I'll use +a "?", as in "pm1 ... pm?", to mean the second subscript goes up to +something I'm really not worried about. + +NB: LETRECS NOT DEALT WITH YET. + +--------------------------------------------------------------------- +We need a slightly souped-up "match" for Haskell (vs the Phil-chapter +one). Simon suggested a re-arrangement of things, which I have then +further re-arranged... + +Proposal (Simon) +~~~~~~~~ + +Eliminate default arg of match (3rd arg in Phil-chapter match) in +favour of returning the variable (not special value) fail. Thus a +possible translation for + + f [] [] = e1 + f x y = e2 + +would be + + f p q = case p of + [] -> case q of + [] -> e1 + _ -> fail + _ -> fail + where + fail = e2 + +Now the issue of whether to duplicate code or share it becomes whether +to substitute copies of e2 or not. This is a decision we need to take +anyway for all other let-bound things, so why not for fail too? If +fail is used only once, we will certainly substitute for it. + +We could even detect that fail is used only in a head position, so it +can be implemented as a stack-adjust then a jump. This might well +apply to other let-bound things too. + +Now here's a proposal for the "match" function. The main difference is + 1) no default argument + 2) [contra simon's suggestion] Patterns are still per-row as in + Phil's chapter. + 3) [partain] even the input exprs are CoreExprs + +OK, for a "match" for m equations each with n patterns: + +match :: [Name] + -- n (variable) names, one per pattern column, bound + -- to the n expressions we are matching against the + -- patterns + + -> [([Pat], CoreExpr)] + -- one pair for each of the m equations: the n + -- patterns in that equation, then the CoreExpr that + -- is evaluated if we get a match. The CoreExpr may + -- contain free "fail"s; some hackery required to + -- ensure that is OK; see below + + -> CoreExpr + -- the resulting code to do the matching + +In words, + takes + (1) a list of n (match-expression, pattern-column) pairs + (2) a list of m post-match expressions, expr i to be inserted + immediately after equation i's lhs matches + returns + (1) a desugared expr equivalent of the whole "match" + +Meaning +~~~~~~~ + match [u1, ..., un] + [([p11, ..., p1n], e1), ..., ([pm1, ..., pmn], em)] + + match [ (e1, [p11, ...,pm1]), ..., (en, [p1n, ...,pmn])] + [ E1, ... Em ] + + ********* MEANS ********* + + case (u1, ..., un) of + (p11, ..., p1n) -> e1 + _ -> fail + where + fail = case (u1, ..., un) of + (p21, ..., p2n) -> e2 + _ -> fail + ... and so on ... + +Alternatively, this specification could be given in terms of +pattern-matching lambdas, as in Phil's chapter. + +NOT CHANGED BEYOND HERE + +------------------------------------------------------------------- +Cranking through a good old function definition with the above: + + f p11 p12 ... p1n | g11 = e11 + | g12 = e12 + ... + | g1? = e1? + ... + f pm1 pm2 ... pmn | gm1 = em1 + ... + | gm? = em? + +The "match" equivalent is: + +f = \u1.\u2...\un -> + match [ (u1, [p11, ...,pm1]), ..., (un, [p1n, ...,pmn])] + [ E1, ..., Em ] + where fail = error "pattern-match for f failed\n" + E1 = if g11 then e11 else if g12 then ... else fail + ... + Em = if gm1 then em1 else if gm2 then ... else fail + +Boring, huh? + +------------------------------------------------------------------- +It is helpful to me to think about the simple/base cases for this +complicated "match". + +ALL LISTS EMPTY + + match [] [] + + corresponds to the syntactically bogus (zero equations!?) + + case () of + () -> {- nothing!! -} + _ -> fail + + +EMPTY RULE -- no more patterns + + match [] [ ([], E1), ..., ([], Em) ] + + [where, incidentally, each Ei will be of the form + (not that it has to be...) + + Ei = let x1 = e1 in + let x2 = e2 in + ... + let x? = e? in + if g1 then e'1 + else if g2 then + ... + else if g? then e'? + else fail + ] + + becomes ("E1 [] E2 [] ... [] Em" in Phil's chapter...) + + E1 + where + fail = E2 + where + ... + fail = Em-1 + where fail = Em + + with any "fail" in Em being bound from an outer scope; perhaps it's + easier to see written as: + + let fail = Em + in let fail = Em-1 + in ... + let fail = E2 in E1 +------------------------------------------------------------------- +HANDLING LAZY ("TWIDDLE") PATTERNS + +For Haskell, the "mixture rule" (p.~88) looks at a pattern-column and +splits the equations into groups, depending on whether it sees + + * all constructors, or + * all variables _OR LAZY PATTERNS_ + +The following example shows what "match" does when confronted by one +of these variables/lazy-patterns combinations. Note the use of the +binding lists. + + f v | g11 = e11 + ... + | g1? = e1? + f ~p | g21 = e21 + ... + | g2? = e2? + +is + + f = \ u1 -> + match [(u1, [ v, ~p ])] + [ if g11 then e11 else if ... else fail, -- E1 + if g21 then e21 else if ... else fail -- E2 + ] + where fail = error "no match in f\n" + +which transmogrifies into + + f = \ u1 -> + let u2 = u1 in + match [] + [ -- E1 -- + let v = u2 + in + if g11 then e11 else if ... else fail + + ,-- E2 -- + let free_var1_of_p = match [(u2, [ p ])] [ free_var1_of_p ] + ... + free_var?_of_p = match [(u2, [ p ])] [ free_var?_of_p ] + in + if g21 then e21 else if ... else fail -- E2 + + ] + where fail = error "no match in f\n" + +For more specific match-failure error messages, one could insert +"let fail = ..."'s in strategic places. + +------------------------------------------------------------------- +"match" EQUIVALENTS FOR VARIOUS HASKELL CONSTRUCTS + +* function definition -- shown above + +* pattern-matching lambda (souped up version in static semantics) + + \ p1 p2 ... pn | g1 -> e1 + | g2 -> e2 + ... + | gm -> em + + is the same as + + \ u1.\u2 ... \un -> + match [ (u1, [p1]), ..., (un, [pn])] + [ if g1 then e1 else if ... then em else fail + ] + where fail = error "no match in pattern-matching lambda at line 293\n" + +* pattern-matching (simple, non-recursive) "let" + + let p = e + in E + + corresponds to + + case e of + ~p -> E + + which has a "match" equivalent of + + match [(e, [~p])] [ E ] + + The full-blown Haskell "let" is more horrible: + + let p | g1 = e1 + ... + | gn = en + in E + + corresponds to + + case ( if g1 then e1 else... else if gn then en else error "?" ) of + ~p -> E + + thinking about which I am not able to sleep well at night. + (Won't those g's have things bound from inside p ?) + +* pattern-matching (not-quite-so simple, non-recursive) "let" + +<mumble> + +* pattern binding + + p | g1 = e1 + | g2 = e2 + ... + | gm = em + + That's the same as + + p = if g1 then e1 else if ... else if gm then em else fail + where fail = "...some appropriate thing..." + + which corresponds to + + match [ (if g1 ... then em else fail, [ ~p ]) ] + [ {-nothing-} ] + where fail = "...some appropriate thing..." + +* "case" expressions (souped up version in static semantics) + + case e0 of + p1 | g11 -> e11 + ... + | g1? -> e1? + ... + pm | gm1 -> em1 + ... + | gm? -> em? + + is the same as + + match [ (e0, [p1, ..., pm]) ] + [ if g11 then e11 else if ... else fail -- E1 + , ... , + if gm1 then em1 else if ... else fail + ] + where fail = error "pattern-matching case at line xxx failed\n" + +* list comprehensions diff --git a/ghc/docs/NOTES.garbage.collection b/ghc/docs/NOTES.garbage.collection new file mode 100644 index 0000000000..3260df1aae --- /dev/null +++ b/ghc/docs/NOTES.garbage.collection @@ -0,0 +1,206 @@ + + GARBAGE COLLECTION + ~~~~~~~~~~~~~~~~~~ + +The following discussion outlines how the GC is organised and what C +the compiler needs to produce to use it. + +The files associated with GC are: + + StgGC.h header file -- macros and externs + StgCreate.lc GC init routines + StgOverflow.lhc Overflow routines -- interface to GC + GC2s.lhc } + GC1s.lhc } GC control routines + GCdm.lhc } for each particular GC + GCap.lhc } + GCevac.lc Evacuation code fragments (copying GC) + GCscav.lhc Scavenging code fragments (copying GC) + GCcompact.lhc Inplace Compacting GC code fragments + GCmark.lhc Marking code fragments + +Other files: + + In gctest/ + gctest.c GC Small detail test bed program + + In gcstat/ + Performance evaluation stuff + + +Basic Requirements of the C code Produced by the Haskell Compiler +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two main aspects of the compiler generated code that +interact with GC: + +1) Compiled haskell code calls the garbage collection routine when the + heap overflows by entering the appropriate _HEAP_OVERFLOW_... routine. + + These routines isolate register usage and calls the GC control + routine that was defined at compile time. + + For a description of the heap overflow conventions see: + + ~grasp/ghc/compiler/absCSyn/RTSLabels.lhs + + + The following must be adhered to by the mutator: + + REQUIREMENT COLLECTOR + SpA and SpB point to A and B stacks all + + Hp must point to last word allocated dual,comp + All updated closures must "know" their original dual,comp + size + + HpLim must point to one beyond top of root stack appel + Updated closures in the old generation must "know" appel + their original size + + The GC Control routines have to know about the pointer stack and + Update Stack. + +2) The info tables that are pointed to by closures must have the + appropriate GC routines within them. This is achieved by using the + following C Macros to declare them: + + table_name -- the name given to the info table + entry_code -- the name of the normal evaluation + entry code required for the closure + size -- the No of free var words in the closure + ptrs -- the number of pointers in the closure + + + SPEC_INFO_TABLE(table_name,entry_code,size,ptrs); + + Declares an info table with specialiazed code fragments + These are currently available for the following closure + configurations: size, ptrs + 1,0 2,0 3,0 4,0 5,0 + 1,1 2,1 3,1 + 2,2 + 3,3 + 4,4 + 5,5 + ... + 11,11 + + GEN_INFO_TABLE(table_name,entry_code,size,ptrs); + + Declares an info table that uses generic code fragments and + places data to drive these routines in the info table. + These are available for all combinations of size,ptrs (even + those for which SPEC routines are provided). + + + STATIC_INFO_TABLE(table_name,entry_code); + + Declares an info table suitable for a static closure. + + + DATA_INFO_TABLE(table_name,entry_code); + + Declares an info table suitable for a data closure. + This closure contains no heap pointers and its size + (of data and size field) in its first word + + See NOTES.arbitary-ints + + + IND_INFO_TABLE(table_name,ind_code); + + Declares an info table suitable for an indirection. + But see below !! (ToDo) + + +Using a Particular Garbage Collection Scheme +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When deciding which collector to use there are two decision points. + +At compile time it must be decided which code fragments are going to +be attached to closures. This will limit the possible choice of GC +schemes at run time. + +To compile the GC code and compiler-produced C Code for a particular +set of code fragments an appropriate define (-D) directive is given +to the compiler. + +Possible directives are: + + Code Fragments GC Control Routines + +-DGC2s Copying Two Space Collection + +-DGC1s Marking & Compacting Inplace Compaction + +-DGCdm Copying, Marking DualMode Collection + & Compaction (+ TwoSpace and Compaction) +-DGCap Copying, Marking Appels Collector + & Compaction (+ Compaction) + +If none of these are defined the result will be No Collection Schame. +Heap will be allocated but the program will die if it is ever filled. + +Other Directives: + +-D_GC_DEBUG Provides detailed GC debugging trace output + (if showGCTrace set) + +Note that the GC code will eventually be set up already compiled for +the different schemes and all that will be required will be to link +with the appropriate object files. The compiler produced C will still +need to be compiled with the appropriate define. + + +Trace and Statistics Info +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are a couple of variables that can be set to provide info about +GC. + +showGCTrace -- Provides detailed trace of GC and closure movement + TRUE -- Summary about GC invokation and heap location + & 2 -- Detailed trace of copying AND compacting collection + & 4 -- More detail about linked location lists during compaction + & 8 -- Detalied info about marking + + The & options are only available if compiled with -D_GC_DEBUG + +showGCStats -- Provides summary statistics about GC performance + (ToDo) + +ToDo: These should eventually be able to be set by runtime flages + + +Compiler Extensions Required for Compacting Collection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are a number of additional requirements required of the STG +machine and the resulting C code for Inplace Compaction to work. + +The most important and awkward arises from the fact that updated nodes +will be scanned. This requires updated nodes (blackholes, indirections +or inplace updates) to know how big the original closure was (so the +location of the next closure can be determined). + +Implications (Suggestions -- Still to be done): + + Need specialized black holes info pointers which know their size. + + Code on the Update Stack needs to know the orig closure size. Either + record this size or have specialised update code fragments. + + Updated closures need to know orig size. Possible solns are: + + Create dummy garbage closures at the end to fill the hole. + + Store size of closure in free space beyond and have GC + routines which look here for the size. + + Specialised indirections that know their size. + + May be able to search beyond the end of the closure for the next + info pointer. Possibly blanking out the unused portion of the + closure. diff --git a/ghc/docs/NOTES.import b/ghc/docs/NOTES.import new file mode 100644 index 0000000000..30e65c4221 --- /dev/null +++ b/ghc/docs/NOTES.import @@ -0,0 +1,90 @@ + Notes on imports + ~~~~~~~~~~~~~~~~ + SLPJ 15 March 91 + + +Distinguish three kinds of things in interfaces: + + - type, data, class, instance, value decls at top level + + - the same but imported. Syntax + import B renaming C to D where + data C = ... + + - imports, which serve just to attach original names + import B(X,Y) + + +The third group are syntactically stuck at the beginning; the second two +can be intermingled. + +Pass 1 +~~~~~~ +Process each imported interface, and the implementation being compiled, +scanning *headers of* + + type, data and class decls (incl imported ones in interfaces) + +giving the following environments for each + + type/data info {(ModStr,TyConStr) -> arity} + class info {(ModStr,ClassStr)} + +These are filtered (*but not renamed*) by the imports specified in the +impl (ignore dotdot parts and parts in parens), to give a grand +environment E1 of the same shape. It gives the original names of in-scope +types and classes. + +Pass 2 +~~~~~~ +Process each imported interface and the implementation being compiled: + + - scan its imports and use them to filter and rename E1, to give + + {TyConStr -> arity} + {ClassStr} + + - scan type, data, class decls, headers of instance decls + and value type sigs in interfaces + +giving for each: + + class info (CE) {ClassStr -> (ClassId, [ClassOpStr])} + inst info (GIE) {(ClassId,TyConId) -> (Context, GlobalId)} + (info from both class and instance decls) + + type/data info (TCE) {TyConStr -> (TyConId, [ConstrStr])} + + + value info (GVE) {ValStr -> GlobalId} + (info from value sigs, and constructors from data decls) + +Filter and rename the environments gotten from each import to make a grand +environment E2. + +Pass 3 +~~~~~~ +Check E2 for class cycles, and type synonym cycles. + +Pass 4 +~~~~~~ +Process the value decls in the impl, giving {ValStr -> GlobalId}, and some +code. + +Pass 5 +~~~~~~ +Process the bodies of instance decls, to generate code for methods. + + + + + + + UNRESOLVED + ~~~~~~~~~~ +1. Who generates the interface? + +2. Where is dependency analysis done? + + + diff --git a/ghc/docs/NOTES.interface b/ghc/docs/NOTES.interface new file mode 100644 index 0000000000..dfe2d61b83 --- /dev/null +++ b/ghc/docs/NOTES.interface @@ -0,0 +1,54 @@ + +What gets done when printing an interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Basically, we do three things: + +A) Create the import decls. For classes and values, this is easy. We + filter the CE and GVE for all exported objects that were not declared + in the module. For types, this is a pain because we may have something + which is exported and which refers to a type that isn't. For example, + the interface + interface C where + ... + f :: A -> B + may export B, but A may be expected to come from somewhere else when + C is imported. So, we have to go through all envs which have ranges that + may refer to a type. This means the TCE, CE (the class op types), + GIE_inst (instance types) and GVE (types in the sigs). AND we have to + filter out prelude defined types from the resulting list. + + Finally, we print the import decls, using the conventions that the renamer + expects (no explicit constructors/ class ops, etc.) + +B) Print the fixity decls for whatever constructors/ functions are exported + +C) Print the rest of the decls needed. + 1) Type decls - contents of TCE with export flags + 2) Class decls - contents of CE with export flags + 3) Instance decls - contents of GIE_inst that refer to either + an exported type or an exported class + (filter then print) + 4) Value decls - contents of GVE which are not constructors and + which have an export flag + +Issues +~~~~~~ + +Type synonyms - to expand or not? Let's not, and complain if a type sig. is + used but not defined + +Canonical form for interfaces - to get rid of perl post-processing! + +Deriving for an abstract data type - shall we worry about this now or later? + +Printing issues +~~~~~~~~~~~~~~~ + +It's convenient to make all ranges of environments know how to print themselves +(they do now) and decide whether to do so by looking at the export flag +in their Name fields. Presumably the constructors of a data type that is +exported abstractly will decide not to print themselves, so no special code +is needed. + + diff --git a/ghc/docs/NOTES.mkworld2 b/ghc/docs/NOTES.mkworld2 new file mode 100644 index 0000000000..3969d82aba --- /dev/null +++ b/ghc/docs/NOTES.mkworld2 @@ -0,0 +1,48 @@ +Include order: + +# platform info +# discrim on "trigger" symbols in plat-TRIGGER.jm +# then slurp in plat-<platform>.jm +# *-GEN has defaults [if any] + +plat-TRIGGER.jm +plat-<platform>.jm +plat-GEN.jm + +# site overrides + +site-<project>-<setup>.jm +site-<project>.jm +site-GEN.jm + +# <thing>s just for a <project> and its various <setup>s + +<thing>-<project>-<setup>.jm +<thing>-<project>.jm + +# things that many projects are likely to use + +<thing>-GEN.jm + +# finally, the directory-specific stuff + +Jmakefile + +------------------------------------------------------------------- +must specify platform explicitly +setup "std", project "none": nothing included + +------------------------------------------------------------------- +<Things> that we have files for: + +rules: macros related to the main "make" targets + excpt suffix, everything to make "make" do something is here + org by principal make target (all, install, etc.) + +suffix: things to do w/ make suffix rules (i.e., implicit rules) + +utils: utilities that are used in the build process + (where they are & default options for them) + (proj file must say which sysutils it wants) + (the proj files say whether src with or not ==> INeedXXX) +install: where things are installed, flags for installing diff --git a/ghc/docs/NOTES.part-of-book b/ghc/docs/NOTES.part-of-book new file mode 100644 index 0000000000..551dd94aac --- /dev/null +++ b/ghc/docs/NOTES.part-of-book @@ -0,0 +1,73 @@ +E.g., for the typechecker sources of the compiler. + +% cd compiler/typechecker/ + +* make a Jmakefile that is NOT plugged into the overall make-world + system; it will probably look like this: + +------------------------------ +/* this is a standalone Jmakefile; NOT part of ghc "make world" */ + +LitDocRootTargetWithNamedOutput(root,lit,root-standalone) +------------------------------ + +* make a "root file", root.lit, to glue the modules together. + + At the beginning you'll have something like: + + \begin{onlystandalone} + \documentstyle[11pt,literate,a4wide]{article} + \begin{document} + \title{The Glasgow \Haskell{} typechecker} + \author{The GRASP team} + \date{October 1991} + \maketitle + \tableofcontents + \end{onlystandalone} + + \begin{onlypartofdoc} + \section[Typechecker]{The typechecker} + \downsection + \end{onlypartofdoc} + + At the end of the file, you'll need something like: + + \begin{onlypartofdoc} + \upsection + \end{onlypartofdoc} + + \begin{onlystandalone} + \printindex + \end{document} + \end{onlystandalone} + + In between, simply \input all the modules, possibly adding some + sectioning hierarchy: + + \section[Typechecker-core]{Typechecking the abstract syntax} + \downsection + \input{XXXXXXX.lhs} + \input{YYYYYYY.lhs} + \upsection + + \section[Typechecker-support]{Typechecker: supporting modules} + \downsection + \input{AAAAAAAAAAA.lhs} + \input{BBBBBBBBBBB.lhs} + \upsection + +* To make your Makefile, do: + + % jmkmf -P ghc + + (because of a bug, you may have to do it twice :-) + +* Then do "make depend". + +* Now you are ready for business: + + % make root.info + + or + + % make root.dvi diff --git a/ghc/docs/NOTES.rename b/ghc/docs/NOTES.rename new file mode 100644 index 0000000000..cca29322ec --- /dev/null +++ b/ghc/docs/NOTES.rename @@ -0,0 +1,109 @@ + + + +Questions concerning the meaning of hiding in certain contexts: + +1) Suppose we have the interface + interface A where + data T = B | C + + and the module + module H where + import A hiding T + + Should this be an error (because T isn't an abstract type in the module) + or does it just mean the same thing as would + import A hiding (T (B,C)) + or + import A hiding (T (..)) + (in other words, hide all of T) + Will require the user to be precise and flag it as an error - otherwise + the user may not know that the type is not abstract, thinking that it is. + +2) Clearly, we can't allow (assuming the interface above) + module H where + import A hiding (T (B)) + + since that means that a data type with a subset of the constructors is + exported - similarly for classes + +3) Suppose an interface exports an abstract type H. Can H be referred + to as H (..), or is that an error? Let's require precision and call it + an error. + +--------------- new design for renamer ------------------- + +Changes to abstract syntax + +1) ClsSigs becomes Sigs + +2) Instances need new syntax (bool) distinguishing between those which +come from an interface and those which come from a module. + +The renamer is factored into four passes, as follows: + +1) FLATTEN INTERFACES - + insert original names into interfaces. All of the decls imported + from the interfaces are collected and returned, in an otherwise + unchanged module. No interfaces exist after this pass. + +2) Do consistency checks (equality). Return the module including the surviving declarations. + +3) build the global name function, which will maintain two separate + namespaces. + +4) assign names to the entire module, and do dependency analysis. + +As the prelude environments will yield names, the first pass will replace +QuickStrings with constructors of the ProtoName type, defined as + +data ProtoName = Unknown QuickString + -- note that this is the name local to the module + | Imported QuickString QuickString QuickString + | Prelude Name + +The parser will initially make all QuickStrings Unknown. + +Modules must now include signatures for value decls at top level. + +The entire set of passes have the following types: + +type PrelNameFuns = (GlobalNameFun, GlobalNameFun) + +type GlobalNameFun = ProtoName -> Maybe Name + +renameModule :: PrelNameFuns -> ProtoNameModule -> RenameMonad RenamedModule + +renameModule1 :: PrelNameFuns -> ProtoNameModule -> RenameMonad ProtoNameModule + +processModImports1 :: PrelNameFuns -> ProtoNameImportDecls + -> RenameMonad (ProtoNameFixityDecls, ProtoNameTyDecls, + ProtoNameClassDecls, ProtoNameInstDecls, + ProtoNameSigDecls) + +renameModule2 :: ProtoNameModule -> RenameMonad ProtoNameModule + +renameModule3 :: PrelNameFuns -> ProtoNameModule -> GlobalNameFun + +renameModule4 :: GlobalNameFun -> ProtoNameModule -> RenameMonad RenamedModule + +renameModule :: PrelNameFuns -> ProtoNameModule -> RenameMonad RenamedModule +renameModule pnf mod + = (renameModule1 pnf mod) `thenRenameM` (\ mod_with_orig_interfaces -> + (renameModule2 mod_with_orig_interfaces) + `thenRenameM` (\ mod_minus_interfaces -> + (renameModule3 pnf mod_minus_interfaces) + `thenRenameM` (\ global_name_fun -> + (renameModule4 mod_minus_interfaces global_name_fun)))) + +Namespace confusion: According to the report (1.1), `An identifier must +not be used as the name of a type constructor and a class in the same +scope.' This is apparently the only constraint on the namespace, other +than those implied by the conventions for identifiers. So, what are the +namespaces? + +1) variables and class operations, constructors + +2) type constructors and classes (because of the statement above) + + diff --git a/ghc/docs/NOTES.saving-space b/ghc/docs/NOTES.saving-space new file mode 100644 index 0000000000..cd43c37f64 --- /dev/null +++ b/ghc/docs/NOTES.saving-space @@ -0,0 +1,250 @@ +Ways to save code space +~~~~~~~~~~~~~~~~~~~~~~~ +SLPJ/BOS 16 Sept 94 + + + + + +Heap entry points +~~~~~~~~~~~~~~~~~ +We have lots of thunks of the form + + let + x = f p q r + in ... + +where f is know function of arity 3 (ie saturated). +At the moment we generate special code for this one closure, +which: + pushes an update frame + loads p,q,r into registers from the closure (or using + immediate loads if they are literals), + jumps to f_fast. + +Since there are quite a lot of thunks of this form, the idea is to +generate some code (and its info table) just once, *with the +definition of f*, which does exactly as described above. We can then +use this code for every thunk of (exactly) this form. Call this +the "heap entry" for f: + + slow entry: args on stack + fast entry: args in regs + heap entry: args in closure pointed to by Node + +So the thunk for x would look like this: + + ----------------- + x = | * | p | q | r | + --|-------------- + | + | common heap entry code for f + ------> push update frame + R2 := R1[2] -- Second arg + R3 := R1[3] -- Third arg + R1 := R1[1] -- First arg + goto f_fast + +The jump to f_fast can be implemented as a fall-through. (The +slow entry point can take a jump instead!) + +Of course there are also lots of thunks which *aren't* of the heap-entry +form: + x = case y of ... + x = let v = ... in ... + etc + +Things to watch out for: + +* Literal args. Consider + + x = f 2 p 4 + +We don't *have* to use the heap entry for f (we could generate special +code+info table as we do now), but we *can* use it provided we +generate a thunk with 2 and 4 stored in it as well as p: + + ----------------- + | * | 2 | p | 4 | + --|-------------- + | + | common heap entry code for f + ------> push update frame + R2 := R1[2] -- Second arg + R3 := R1[3] -- Third arg + R1 := R1[1] -- First arg + goto f_fast + +(If we have special code the thunk needs only p stored in it, because +the special code can use immediate constants for 2 and 4: + + --------- + | * | p | + --|------ + | + | special code for x + ----> push update frame + R2 := R1[1] -- Second arg + R3 := 4 -- Third arg + R1 := 2 -- First arg + goto f_fast + + +* Single-entry thunks. If x is a single-entry thunk, there's no need to +push an update frame. That suggests: + + --------------- + x = | * | 2 | p 4 | + --|------------ + | + | heap entry code for f + ----> -- NO! NO! push update frame + R2 := R1[2] -- Second arg + R3 := R1[3] -- Third arg + R1 := R1[1] -- First arg + goto f_fast + +Let's call the two variants the + standard heap entry +and no-update heap entry + +We can't fall through from the standard heap-entry code (which pushes +an update frame) to the arg-loading code, because both need an info table. +We have to take a jump. + +For non-exported functions we may be able to see that only one of the +two heap entries is required. + +* Local functions. When f is a *local* (ie not top-level) function, its +fast-entry convention is that + R1 = the function closure + R2.. = the args + +For example: + + top p q = let + f = \r -> ..r..p...q... + in + let + x = f q + in + ... + + +The shape of the heap-entry closure for f must be + + ------------- + x = | * | f | q | + --|---------- + | + -------> heap entry code + must load *f* into R1 as well as q and + the other args + + + + + +Avoiding generating entries and info tables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +At present, for every function we generate all of the following, +just in case. But they aren't always all needed, as noted below: + +[NB: all of this applies only to *functions*. Thunks always +have closure, info table, and entry code.] + + +* Fast-entry code ALWAYS NEEDED + +* Slow-entry code + Needed iff (a) we have any un-saturated calls to the function + OR (b) the function is passed as an arg + +* The function closure + Needed iff (a) we have any un-saturated calls to the function + OR (b) the function is passed as an arg + OR (c) if the function has free vars (ie top level) + + Why case (a) here? Because if the arg-satis check fails, + UpdatePAP stuffs a pointer to the function closure in the PAP. + [Could be changed; UpdatePAP could stuff in a code ptr instead, + but doesn't seem worth it.] + + [NB: these conditions imply that we might need the closure + without the slow-entry code. Here's how. + + f x y = let g w = ...x..y..w... + in + ...(g t)... + + Here we need a closure for g which contains x and y, + but since the calls are all saturated we just jump to the + fast entry point for g, with R1 pointing to the closure for g.] + + +* Slow-entry info table + Needed iff (a) we have any un-saturated calls to the function + OR (b) the function is passed as an arg + OR (c) the function has free vars (ie top level) + + NB. (c) is only required so that the function closure has + an info table to point to, to keep the storage manager happy. + If (c) alone is true we could fake up an info table by choosing + one of a standard family of info tables, whose entry code just + bombs out. + + If (c) is retained, then we'll sometimes generate an info table + (for storage mgr purposes) without slow-entry code. Then we need + to use an error label in the info table to substitute for the absent + slow entry code. + +* Standard heap-entry code + Standard heap-entry info table + Needed iff we have any updatable thunks of the standard heap-entry shape. + +* Single-update heap-entry code + Single-update heap-entry info table + Needed iff we have any non-updatable thunks of the + standard heap-entry shape. + + +All are needed if the function is exported, just to play safe. + +Idea: generate just the stuff we need! + + + +\begin{code} +staticClosureRequired -- Assumption: it's a top-level, no-free-var binding + :: StgBinderInfo + -> [Id] -- Args + -> Bool +staticClosureRequired (StgBinderInfo arg_occ unsat_occ _ _) args + = arg_occ || -- There's an argument occurrence + unsat_occ || -- There's an unsaturated call + null args -- It's a thunk + +staticClosureRequired NoStgBinderInfo args = True + + + +slowFunEntryCodeRequired -- Assumption: it's a function, not a thunk. + :: StgBinderInfo + -> Bool +slowFunEntryCodeRequired (StgBinderInfo arg_occ unsat_occ _ _) + = arg_occ || -- There's an argument occurrence + unsat_occ -- There's an unsaturated call +slowFunEntryCodeRequired NoStgBinderInfo = True + + +funInfoTableRequired -- Assumption: it's a function, not a thunk. + :: Bool -- Top level? + -> StgBinderInfo + -> Bool +funInfoTableRequired top_level (StgBinderInfo arg_occ unsat_occ _ _) + = not top_level || + arg_occ || -- There's an argument occurrence + unsat_occ -- There's an unsaturated call + +funInfoTableRequired top_level NoStgBinderInfo = True +\end{code} diff --git a/ghc/docs/NOTES.update-mechanism b/ghc/docs/NOTES.update-mechanism new file mode 100644 index 0000000000..5072cd87d5 --- /dev/null +++ b/ghc/docs/NOTES.update-mechanism @@ -0,0 +1,195 @@ + The Glorious New Update Mechanism + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Simon & Jim Dec 93 + +Return convention +~~~~~~~~~~~~~~~~~ +When a constructor returns it makes sure that + + R2 contains the info pointer for the constructor + R1,R3.. contain the components (if return in regs) + R1 points to the constructor object itself (if return in heap) + +The info table for a constructor contains a pointer to the +constructor's update code. If a constructor returns to an +update frame, the update frame's code just jumps direct to the +constructor's update code, via the info pointer in R2. + +This penalises slightly the return of a new constructor, +because we have to load R2 with the info ptr. [Fact: in runs +of the compiler, 20-30% of all returns are of a new constructor; +70-80% are existing constructors.] + +Info tables +~~~~~~~~~~~ +Each dynamic-heap-allocated constructor has *two* info tables: + +* the "NewCon" info table is put into R2 when returning a new + constructor, which does not yet exist in the heap; R1 is dead! + The "NewCon" info table has no GC entries, because it's only ever used + when returning in regs, never installed in a real constructor. + + The NewCon table also needs a valid tag field (see taggery below) + +* the "ExistingCon" info table is used for all constructors allocated + in the heap. + +The update code for a constructor +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The update code for a constructor actually performs the update +right away. [At present, the update is deferred until we get +back to the case expression.] It knows how to do the update +because the update code is constructor-specific. + +Once it's done the update, it makes R1 point to the constructor object +in the heap (which'll either be freshly-allocated, if big, or the +updated thing itself), and (for non-niladic constructors) makes R2 point +to the "ExistingCon" info table for the constructor. (Of course the new +constructor will also have an ExistingCon info ptr.) For niladic +constructors, we do *not* use the "ExistingCon" info table. We continue +to overwrite updatees in-place, because this saves us an indirection +prior to garbage collection (and the extra niladic constructors disappear +during the next garbage collection anyway). + +The update code in the ExistingCon info table simply updates with an +indirection, using R1. I *think* this can be one standard piece of +code. The only doubt here concerns GC; if updating with an +indirection can cause GC (possible on GRIP? or generational GC?), +then we need to know which regs are live. We can solve this by +putting a liveness mask in the info table too. [Arguably we want +that anyway; consider returning to the bottom of a stack object.] +So a liveness mask in the info table is probably a good idea. + +Constructors which return in heap return with an ExistingCon info +ptr. They don't need a NewCon info table at all. + +Notice that this means that when we return an *existing* constructor, +to an update frame, the update is done with an indirection, rather +than [as now] copying the constructor afresh. This solves the space duplication +problem which shows up in "clausify". + +GC: R1 might be dead; R2 is a non-ptr. So this return convention +relies on using liveness masks for GC reg-liveness info, not the +old no-of-live-ptrs info. + +Taggery +~~~~~~~ + + [Current: For unvectored returns with more than one constructor, we + currently load TagReg, and scrutinise it in the case expression. + Worse, we also have to scrutinise TagReg in the update entry of the + return vector.] + +In the new world, updates are handled without any nonsense. No need +to look at any register, becase we just jump to the constructor +specific update code. + +Since we have an info ptr in R2, we can get the tag out of the info +table, thus getting rid of TagReg altogether. (This could conceivably +be a *lose* on a machine with lots of regs, because it replaces a +immediate small-const load by a memory fetch of the tag from the info +table. + +Not clear whether this is worth trying to improve. Could + + a) #define TagReg to be a register or an offset from R2 + b) issue a SET_TAG macro in the entry code for a constructor, + which usually expands to nothing + +[NB 75-95% of all returns are vectored in runs of the compiler itself.] + +The entry code for a constructor +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The real reason the registers are assigned as above is to make the +entry code for a constructor simple. When the entry code is executed, +we have a new entry convention: + + R1 points to the object + R2 is its info pointer + +(Why? because we usually enter it by indirecting through its info +table, so it seems a shame to load the info ptr from memory twice.) + +So all the entry code has to do is to return (perhaps vectored-ly). +(Maybe load TagReg, usually not --- see above.) + +NB this entry convention applies, of course, to all thunks as +well as constructors -- whenever we enter an unknown object via R1 (Node). + +Case expressions +~~~~~~~~~~~~~~~~ +Return vectors no longer need update code. + +Unvectored returns can therefore be *direct* to the code, +rather than *indirect* via a 2-entry vector. + +Penalty for this improvement: "polymorphic" return vectors, +notably that in an update frame, needs to accomodate either +a direct or a vectored return. So it has to look like: + + UpdVec: jmp UnvectoredUpd + .word UpdVec0 + .word UpdVec1 + ... + +that is, the return vector is offset by some fixed amount +from the pointer put on the stack. Or, it could be done +backwards: + + ... + .word UpdVec1 + .word UpdVec0 + UpdVec: ...code for UnvectoredUpd... + +and then vectored returns would use negative offsets. + +This grunge is necessary *only* for a fixed set of polymorphic return +vectors, part of the runtime system: + + - update frames + - restore cost centres + - seq, par + - thread base + - stack object base + +Case expressions generate either a direct return, or a vector, +but never a combination. + +Update Frames +~~~~~~~~~~~~~ + +Standard update frames are still required if we don't know the type of +the constructor being returned. However, we often do know the type. In +this case, we can generate a type-specific updating return-vector to place +in the update frame rather than the StdUpdRetVector. This saves us one +level of indirection. + +Partial applications +~~~~~~~~~~~~~~~~~~~~ +PAPs are basically handled just the same way as at present. + +Changes from now +~~~~~~~~~~~~~~~~ +* UpdReg dies. +* TagReg dies. +* RetVecReg dies. (Previously needed to do return after update.) +* Return vectors have half the number of entries. +* Unvectored returns go direct. +* Polymorphic seq/par and friends. +* No space duplication problem (cf clausify) + + +Glosses +~~~~~~~ +Tag and update code are needed only for constructor info tables. +It seems a shame to take up space in other info tables (ie 99% of them). + +Possibilities: + +- use an indirection to GC code, so the vari-sized gc stuff becomes + fixed +- put the tag/upd code ptrs before the start of the info table. (or + between the info table and code when reversing info tables...) + + +Looks tricky to me. diff --git a/ghc/docs/Prefix_Form b/ghc/docs/Prefix_Form new file mode 100644 index 0000000000..43daaba644 --- /dev/null +++ b/ghc/docs/Prefix_Form @@ -0,0 +1,294 @@ + Haskell Prefix Form + =================== + +This defines the interface between the Haskell lexer/parser "hsp" +(written in lex/yacc/C) and the Haskell compiler proper, "hsc" +(written in Haskell). + +White space in the form of spaces, tabs and newlines may occur between +prefix items (I wouldn't recommend it [WDP]). A literal tab +terminates a string constant (and by extension also an integer +constant, character constant, identifier or infix operator). + +There is a general list form, where L indicates a Cons node and N +indicates Nil. Elements in a list may be of arbitrary type. + +KH, 22/08/91: Changed for Haskell 1.1+ -- this is where Haskell and LML + finally part company... + +JH, 09/07/92: {0,5,6,I,O,u,v,w} Used in Data Parallel Haskell variant + (Jonathan Hill, QMW) + +WDP, 02/04/93: Added full-blown pragmas. +WDP, 15/08/93: Added even more full-blown pragmas. + +`Tag' namespace already used: + +#$%()+,-.012356789:=>@ABCDEGILMNOPQRSTUWXZ_abcdefghijklmnopstuvwxyz~ + + Meta-Syntactic Items + -------------------- + +Lists (l) +--------- + +L el l List constructor el : l +N Null List [] + + +Strings (s) +----------- + +#chars<TAB> String of characters before <TAB> + + + + + Syntactic Items + --------------- + +Expressions or Patterns (e or p) +-------------------------------- + +M L s s b [op] [ix] [ei] + Haskell module: + (name, file, binding, fixities, imports, exports) + +4 s Integer Constant 0, 1, ... +H s Unboxed Integer constant 0#, 1#, ... /* WDP */ +F s Floating Point Constant 0.1, 0.2e-3, ... +J s Unboxed Double Constant 0.1##, 0.2e-3##, ... /* WDP */ +K s Unboxed Float Constant 0.1#, 0.2e-3#, ... /* WDP */ +C s Character Constant '...' +P s Unboxed character constant ???????? /* WDP */ +S s String Constant "..." +V s String# Constant "..."# /* WDP */ +Y s "Literal C" Constant ``printf'' /* WDP */ +I s "no rep" Integer (unfoldings) +R s s "no rep" Rational (numerator, denominator) +s s "no rep" String constant (unfoldings) + +i id Identifiers +C literal Literal constant + +a e1 e2 Function application (e1 e2) +@ e1 id e2 Infix Application e1 `op` e2 +( e id Left section (e op) +) id e Right Section (op e) + +l L [p] e Lambda Expressions \ p1 ... pn -> e +c e [pb] Case Expression case e of pb1 ... pbn +b e1 e2 e3 If expression if e1 then e2 else e3 +E b e Let Expression let b in e + +: [e] Explicit List [ e1, ..., en ] +Z e [q] List Comprehension [ e | q ] +. e1 [e2] [e3] Enumeration (e2/e3 may be []) [e1,e2..e3] + +, [e] Explicit Tuple ( e1, ..., en ) + +R e t Type Constraint e :: t + +- e Negation - e + +j id s [e] C Call/Asm (ccall/asm id/str e1 ... en) + s == "n" --> ccall, non-ptrs only + s == "p" --> ccall, ptrs allowed + s == "N" --> casm, non-ptrs only + s == "P" --> casm, ptrs allowed +k s e Set Cost Centre (scc s e) + +s id p As Pattern id @ p +~ p Irrefutable Pattern ~ p ++ p e Plus Pattern n + k + /*WDP: why a "p" on the plus pat? (KH: historical reasons) */ +_ Wildcard Pattern _ + + + +Qualifiers (q) +-------------- + +G p e Generator p <- e +g e Guard e + +Bindings (b) +------------ + +t L C [id] t [d] iprag DataType Binding data C => t = d1 | ... | dn + deriving (id1, ..., idm) +n L t1 t2 iprag Type Synonym type t1 = t2 +p L [pb] Pattern Binding pb1 ; ... ; pbn +f L [pb] Function Binding pb1 ; ... ; pbn +A b1 b2 Multiple Definitions b1 ; b2 +$ L C t b iprag Class class C => t [where b] +% L C id t b iprag Instance instance C => id t [where b] +D L [ty] Default default (ty1, ..., tyn) + +St L [id] t iprag Type Signature id1, ...., idn :: t +Ss L id [t] Pragma: value specialis'ns {-# SPECIALISE id :: t1, ... tn #-} +SS L id t Pragma: instance specialis'n {-# SPECIALISE instance id t #-} +Si L id [id] Pragma: inline -- id [howto] {-# INLINE id [id]{0,1} #-} +Su L id Pragma: magic unfolding {-# MAGIC_UNFOLDING id #-} +Sa L id Pragma: abstract synonym {-# ABSTRACT id #-} + +7 L id [ei] [rn] Import module (Interface only) import id (eis) renaming rn +B null binding + + +Fixity declarations (op) +-------------- +/* WDP: most suspicious how these don't appear in interfaces */ +/* WDP: need line numbers? */ + + s1 s2 s3 s1 is the operator name + s2 is either "infix", "infixl" or "infixr" + s3 is the precedence + +Types (t) +--------- + +T id [t] Type Constructor id t1 ... tn +: t Explicit List Type [t] +, [t] Explicit Tuple Type (t1, ..., tn) +> t1 t2 Explicit Function Type t1 -> t2 +y id Type Variable id +3 C t Type Context C => t + +2A id t "UniDict": class, type (core unfoldings only) +2B id "UniTyVarTemplate" +2C [id] t "UniForall" tv1 ... tvN => type + +2D Nothing (Maybe UniType) +2E t Just t (ditto) + +Contexts (C) +------------ + + [t] Haskell context: t1, ..., tn + + +Data Types (d) +-------------- + +1 L id [t] Data constructor id st1 ... stn + + +Pattern Bindings (pb) +--------------------- + +W L id p [ge] b Single grhs p | g1 = e1 ... where b + (L,id) = (Line,Function) + + +Guarded Expressions (ge) +------------------------ + + g e g | e (unguarded comes in with an + unsavoury (Var "_otherwise") `guard') + + +Identifiers (id) +---------------- + + s An identifier is just a string + + +Import declarations (ix) +------------------------ + +e L s id [ei] [rn] b Line, File Name, Module name, imported entities, + renamings, interface body +h L s id [ei] [rn] b Hiding clause, as above... + + +Renamings (rn) +-------------- + + id id From name, to name + + +Exported/Imported Identifers (ei) +--------------------------------- + +x id ExImport Variable +X id ExImport Constructor/Type/Class +z id ExImport Class/Type plus all ops/cons +8 id [id] ExImport Type(C1,..Cn) +9 id [id] ExImport Class(o1,..on) +m id Export Module + + +Interface pragmas (iprag) +------------------------- + + User pragmas come in as "signatures"; see Bindings. + +PN Null/empty pragma + +Pd [d] Data pragma: otherwise-hidden data constructors +Pt Type pragma: synonym is *abstract* +Pc [gprag] Class pragma: one gprag per superclass +Po gprag gprag Class op pragma: gprags for dsel & defm + OUT: Pv gprag [2prag] Value pragma: gprag + specialisations +Pis id gprag Instance pragma (simple): id is module name, gprag for dfun +Pic id gprag [1prag] Ditto (constant methods): also gprags for classops +PiS id gprag [3prag] Ditto (specialised): also (type, instance-prag) pairs + +Pg Aprag uprag Sprag Uprag + General ("gprag"): arity, update, strictness, unfolding + +PA id Arity ("Aprag"): arity +Pu id Update ("uprag"): update spec +PS id gprag Strictness ("Sprag"): strictness spec, gprag for worker +PM id id Magic unfolding ("Uprag"): var, magic-name string +PU id core Unfolding ("Uprag"): "guidance", corexpr-unfolding + +Px Unfold always (these are "guidance" ones...) +Py id id Unfold if applied to "m" ty args, "n" val args +Pz id id Unfold if applied to "m" ty args, & cons in marked val positions + (e.g., "CXXCXX" ==> in 1st & 4th arg positions) + +P1 id gprag ("1prag"): (name, gen-pragma) pair +P2 t gprag ("2prag"): (type, gen-pragma) pair +P3 t gprag [iprag] ("3prag"): (type, [(gen-pragma, instance-pragma)]) pair + + +Core syntax [in iprags] (core) +------------------------------ + +Fa +Fb +<etc -- lots of this stuff> + +Used in Data Parallel Haskell variant (Jonathan Hill, QMW) +---------------------------------------------------------- + + ** Expressions ** + +5 e [parqual] Parallel ZF expression << e | [parquals] >> +6 [e] Pod Literal << e1,...,ek>> +O [e] e Processor (|e1,...,ek;e|) + + ** Types ** + +u [t] t Explicit Processor Type (|t1,..tn;t|) +v [t] Explicit Pod Type <<t>> + + ** Parallel Qualifiers ** + +0 e e Drawn From Generator exp <<- exp +w e e Indexed From Generator exp <<= exp +I e Guard + + + Other Items + ----------- + +Line Numbers (L) +---------------- + + s Haskell line number + + +Kevin Hammond @ 22nd. August 1991 diff --git a/ghc/docs/README b/ghc/docs/README new file mode 100644 index 0000000000..d9c06dde52 --- /dev/null +++ b/ghc/docs/README @@ -0,0 +1,71 @@ +Herein are bits of documentation for, or related to, the Glorious +Glasgow Haskell compilation system. Unless specified otherwise, they +are nestled in the ghc/docs directory of the distribution. + +== semi-proper documentation ========================================== + +install_guide/* + A step-by-step guide on how to configure, build, and install + the system. + +users_guide/* + The User's Guide for the system. Describes how to "drive" the + system, how to deal with common problems, how to use the + profiling tools, what is Known to be Broken, how to use the + Glasgow extensions, etc. + +release_notes/* + Release notes for the system. What's new in each release, and + what's coming Real Soon Now. + +io-1.3/* + The *draft* Haskell 1.3 I/O proposal at December 1994. In + HTML format. Unstructured.html gives you the whole thing in + one big wad. + +state-interface.dvi + "GHC prelude: types and operations", an addendum to the Peyton + Jones/Launchbury "state" paper, is the definitive reference + (bar the compiler source :-) of GHC's lowest-level interfaces + (primitive ops, etc.). + +add_to_compiler/paper.dvi + An overview of how to add a piece to the compiler. + +simple-monad.lhs + A *simple* introduction to the common use of monads in Haskell + programming. No fancy stuff whatsoever. By Will Partain. + +../../mkworld/docs/mkworld_guide/* + A guide to the ``make world'' configuration system ... ``for + the brave.'' The "configure" script (versions 0.22ff) make + this a little less visible than before. + +../../literate/doc/* + The documentation for the ``literate programming'' stuff, if + you're interested. + +== relevant papers and abstracts ====================================== + +Consult ghc/docs/abstracts/abstracts<year>.tex for information about +Glasgow work related to the GHC system. Other relevant material is +listed here. All of it is available by FTP. + +Haskell report, version 1.2 (the latest) + It was in your May, 1992, SIGPLAN Notices. Not in the + distribution but in ~ftp/pub/haskell/report/ (the usual + places). + +Haskell tutorial, by Paul Hudak and Joe Fasel + Ditto. In ~ftp/pub/haskell/tutorial/; usual places. + +== notes and things =================================================== + +NOTES.* Random collections of notes on topics *. Check the + modification dates to see what's new... Don't believe + everything you read. + +MAIL* Files holding some relevant correspondence. + +README files + A few of these actually exist and tell the truth. diff --git a/ghc/docs/abstracts/README b/ghc/docs/abstracts/README new file mode 100644 index 0000000000..a3c07a8729 --- /dev/null +++ b/ghc/docs/abstracts/README @@ -0,0 +1,4 @@ +A straight copy of ~grasp/docs/abstracts/*.{tex,sty}. + +Will Partain +partain@dcs.glasgow.ac.uk diff --git a/ghc/docs/abstracts/abstracts.sty b/ghc/docs/abstracts/abstracts.sty new file mode 100644 index 0000000000..0965be647e --- /dev/null +++ b/ghc/docs/abstracts/abstracts.sty @@ -0,0 +1,30 @@ +\newcounter{refnumber}[section] + +\renewcommand{\therefnumber}{\arabic{refnumber}} + +\newcommand{\reference}[4]{ % authors, title, details, abstract +\refstepcounter{refnumber} +\large +{\bf \therefnumber.} #1, {\em #2}, #3. +\normalsize +\begin{quote} +#4 +\end{quote} +\vspace{0.2in} +} + +\newcommand{\shortreference}[3]{ % authors, title, details +\large +$\bullet$ #1, {\em #2}, #3. +} + + +\newcommand{\GlasgowNinetyTwo}[1] + {Functional Programming, Glasgow 1992, Springer Verlag Workshops in Computing} +\newcommand{\GlasgowNinetyThree}[1] + {Glasgow Functional Programming Group Workshop, Ayr, July 1993} +\newcommand{\GlasgowNinetyOne} + {Functional Programming, Glasgow 1991, Springer Verlag Workshops in Computing} + +% \newcommand{\Haskell}[1]{{\sc Haskell}} + diff --git a/ghc/docs/abstracts/abstracts89.tex b/ghc/docs/abstracts/abstracts89.tex new file mode 100644 index 0000000000..e4fe15e542 --- /dev/null +++ b/ghc/docs/abstracts/abstracts89.tex @@ -0,0 +1,487 @@ +\documentstyle[11pt,slpj]{article} + +\newcommand{\reference}[4]{ % authors, title, details, abstract +\large +#1, {\em #2}, #3. +\normalsize +\begin{quotation} +#4 +\end{quotation} +\vspace{0.2in} +} + +\newcommand{\Haskell}[1]{{\sc Haskell}} + +\begin{document} + +\title{Abstracts of GRIP/GRASP-related papers and reports till 1989\\ +Dept of Computing Science \\ +University of Glasgow G12 8QQ} + +\author{ +Cordelia Hall (cvh@cs.glasgow.ac.uk) \and +Kevin Hammond (kh@cs.glasgow.ac.uk) \and +Will Partain (partain@cs.glasgow.ac.uk) \and +Simon L Peyton Jones (simonpj@cs.glasgow.ac.uk) \and +Phil Wadler (wadler@cs.glasgow.ac.uk) +} + +\maketitle + +\begin{abstract} +We present a list of papers and reports related to the GRIP +and GRASP projects, +covering {\em the design, compilation technology, +and parallel implementations of functional programming languages, especially +\Haskell{}}. + +Most of them can be obtained by writing to +Teresa Currie, Dept of Computing Science, +University of Glasgow G12 8QQ, UK. Her electronic mail address is +teresa@uk.ac.glasgow.cs. + +Those marked ($\spadesuit$) can be obtained from the School of Information +Systems, University of East Anglia, Norwich, UK. +Those marked ($\clubsuit$) can be obtained from Chris Clack at the +Department of Computer Science, University College London, Gower St, +London WC1E 6BT, UK. +\end{abstract} + +\section{Published papers} + +\reference{Simon L Peyton Jones and Jon Salkild} +{The Spineless Tagless G-machine} +{Proc IFIP Symposium on Functional Programming Languages and Computer +Architecture, London, Sept 1989} +{ +The Spineless Tagless G-machine is an abstract machine based on graph +reduction, designed as a target for compilers for non-strict functional +languages. +As its name implies, it is a development of earlier work, especially +the G-machine and Tim. + +It has a number of unusual features: the abstract machine code is +rather higher-level than is common, allowing better code generation; +the representation of the graph eliminates most interpretive overheads; +vectored returns from data structures give fast case-analysis; +and the machine is readily extended for a parallel implementation. + +The resulting implementation runs at least 75\% faster +than the Chalmers G-machine. +} + +\reference{Simon L Peyton Jones} +{Parallel implementations of functional programming languages} +{Computer Journal 32(2), pp175-186, April 1989} +{ +It is now very nearly as easy to build a parallel computer +as to build a sequential one, and there are strong incentives to do so: +parallelism seems to offer the opportunity to improve both the +absolute performance level and the cost/performance ratio of our machines. + +One of the most attractive features of functional programming languages +is their suitability for programming such parallel computers. +This paper is devoted to a discussion of this claim. + +First of all, we discuss parallel functional programming +from the programmer's point of view. +Most parallel functional language implementations are based on graph reduction, +we proceed to a discussion of some implementation issues raised by parallel +graph reduction. +The paper concludes with a case study of a particular parallel graph reduction +machine, GRIP, and a brief survey of other similar machines. +} + +\reference{Kevin Hammond} +{Implementing Functional Languages for Parallel Machines} +{PhD thesis, University of East Anglia, 1989 ($\spadesuit$)} +{Commencing with the Standard ML language, dialects XSML and PSML are +defined, which permit parallel evaluation of functional programs. XSML +is Standard ML with a novel mechanism for handling exceptions; PSML is a +side-effect free version of XSML. A formal semantics for PSML and a +translation algorithm from this language into Dactl, a compiler target +language based on the theory of graph-rewriting, are presented. The +thesis proves that a simplified version of this translation preserves +meaning for flat domains, and that the strategy for reduction to normal +form is correct. + +The implementation of standard compilation techniques such as strictness +analysis, maximal free sub-expression elision and common sub-expresssion +elimination is considered with respect to Dactl, and problems +highlighted. Techniques are also presented for compiling +exception-handling correctly in a parallel environment, and for +compiling side-effect for a parallel machine. Metrics for performance +evaluation are presented and results obtained using the Dactl reference +interpreter are presented.} + + +\reference{Simon L Peyton Jones, Chris Clack and Jon Salkild} +{High-performance parallel graph reduction} +{Proc Parallel Architectures and Languages Europe (PARLE), LNCS 365, pp193-207, +July 1989} +{ +Parallel graph reduction is an attractive implementation for functional +programming languages because of its simplicity and inherently distributed +nature. +This paper outlines some of the issues raised by parallel compiled +graph reduction, and presents the solutions we have adopted to produce an +efficient implementation. + +We concentrate on two particular issues: +the efficient control of parallelism, resulting in an ability to alter +the granularity of parallelism +{\em dynamically}; +and the efficient use of the memory hierachy to improve locality. +} + +\reference +{Phil Trinder and Philip Wadler} +{Improving list comprehension database queries} +{{\em TENCON '89\/} (IEEE Region 10 Conference), +Bombay, India, November 1989.} +{ +The task of increasing the efficiency of database queries has recieved +considerable attention. In this paper we describe the improvement of +queries expressed as list comprehensions in a lazy functional +language. The database literature identifies four algebraic and two +implementation-based improvement strategies. For each strategy we show +an equivalent improvement for queries expressed as list +comprehensions. This means that well-developed database algorithms +that improve queries using several of these strategies can be emulated +to improve comprehension queries. We are also able to improve queries +which require greater power than that provided by the relational +algebra. Most of the improvements entail transforming a simple, +inefficient query into a more complex, but more efficient form. We +illustrate each improvement using examples drawn from the database +literature. +} + +\reference{Kevin Hammond} +{Exception Handling in a Parallel Functional Language: PSML} +{Proc TENCON '89, Bombay, India, Nov 1989} +{ +Handling exception occurrences during computation is a problem in most +functional programming languages, even when the computation is eager and +sequential. This paper presents a version of the error value method +which allows lazy computation with deterministic semantics for parallel +evaluation even in the presence of errors. The realisation of this +technique is illustrated by reference to PSML, a referentially +transparent variant of Standard ML designed for parallel evaluation. +} + +\reference +{Philip Wadler} +{Theorems for free!} +{{\em 4'th International Conference on Functional Programming +Languages and Computer Architecture}, London, September 1989.} +{ +From the type of a polymorphic function we can derive a theorem +that it satisfies. Every function of the same type satisfies the same +theorem. This provides a free source of useful theorems, +courtesy of Reynolds' abstraction theorem for the polymorphic lambda +calculus. +} + +\reference +{Philip Wadler and Stephen Blott} +{How to make {\em ad-hoc\/} polymorphism less {\em ad hoc}} +{{\em 16'th ACM Symposium on Principles of Programming Languages}, +Austin, Texas, January 1989.} +{ +This paper presents {\em type classes}, a new approach to {\em +ad-hoc\/} polymorphism. Type classes permit overloading of arithmetic +operators such as multiplication, and generalise the ``eqtype variables'' +of Standard ML. +Type classes extend the Hindley\X Milner polymorphic type system, and +provide a new approach to issues that arise in object-oriented +programming, bounded type quantification, and abstract data types. +This paper provides an informal introduction to type classes, and +defines them formally by means of type inference rules. +} + +\reference{Kevin Hammond} +{Implementing Type Classes for Haskell} +{Proc Glasgow Workshop on Functional Programming, Fraserburgh, Aug 1989} +{ +This paper describes the implementation of the type class mechanism for +the functional language Haskell, which has been undertaken at Glasgow +University. A simple introduction to type classes discusses the methods +used to select operators and dictionaries in the Glasgow Haskell +compiler. A solution to the problem of selecting super-class +dictionaries, not considered by the original paper on type class, is +also presented. The modifications which must be made to the standard +Hindley/Milner type-checking algorithm to permit the translation of +operators are described, and a revised definition of algorithm W is +provided. Finally, a set of performance figures compares the run-time +efficiency of Haskell and LML programs, indicating the overhead inherent +in the original, naive method of operator selection, and the improvement +which may be obtained through simple optimisations. +} + +\reference{Simon L Peyton Jones} +{FLIC - a functional language intermediate code} +{SIGPLAN Notices 23(8) 1988, revised 1989} +{ +FLIC is a Functional Language Intermediate Code, intended to +provide a common intermediate language between diverse +implementations of functional languages, including parallel +ones. +This paper gives a formal definition of FLIC's syntax and +semantics, in the hope that its existence may encourage greater +exchange of programs and benchmarks between research groups. +} + +\reference{Simon L Peyton Jones, Chris Clack, Jon Salkild, Mark Hardie} +{Functional programming on the GRIP multiprocessor} +{Proc IEE Seminar on Digital Parallel Processors, Lisbon, Portugal, 1988} +{ +Most MIMD computer architectures can be classified as +tightly-coupled or loosely-coupled, +depending on the relative latencies seen by a processor accessing different +parts of its address space. + +By adding microprogrammable functionality to the memory units, we have +developed a MIMD computer architecture which explores the middle region +of this spectrum. +This has resulted in an unusual and flexible bus-based multiprocessor, +which we are using as a base for our research in parallel functional programming +languages. + +In this paper we introduce parallel functional programming, and describe +the architecture of the GRIP multiprocessor. +} + +\reference{Geoffrey Burn, Simon L Peyton Jones, and John Robson} +{The spineless G-machine} +{Proc ACM Conference on Lisp and Functional Programming, Snowbird, pp244-258, +August 1988} +{ +Recent developments in functional language implementations have +resulted in the G-machine, a programmed graph-reduction machine. +Taking this as a basis, we introduce an optimised method of +performing graph reduction, which does not need to build the +spine of the expression being reduced. +This Spineless G-machine only updates shared expressions, and +then only when they have been reduced to weak head normal form. +It is thus more efficient than the standard method of performing +graph reduction. + +We begin by outlining the philosophy and key features of the +Spineless G-machine, and comparing it with the standard +G-machine. +Simulation results for the two machines are then presented and +discussed. + +The Spineless G-machine is also compared with Tim, giving a +series of transformations by which they can be interconverted. +These open up a wide design space for abstract graph reduction +machines, which was previously unknown. + +A full specification of the machine is given in the appendix, +together with compilation rules for a simple functional language. +} + +\reference{Chris Hankin, Geoffrey Burn, and Simon L Peyton Jones} +{A safe approach to parallel combinator reduction} +{Theoretical Computer Science 56, pp17-36, North Holland, 1988} +{ +In this paper we present the results of two pieces of work which, when +combined, allow us to take a program text of a functional langauge and +produce a parallel implementation of that program. +We present the techniques for discovering sources of parallelism in +a program at compile time, and then show how this parallelism is +naturally mapped onto a parallel combinator set that we will define. + +To discover sources of parallelism in a program, we use +{\em abstract interpretation} a compile-time technique which is used +to gain information about a program which may then be used to optimise +the program's execution. +A particular use of abstract interpretation is in +{\em strictness analysis} +of functional program. +In a language that has lazy semantics, the main potential for parallelism +arises in the evaluation of arguments of strict operators. + +Having identified the sources of parallelism at compile time, it is +necessary to communicate these to the run-time system. +In the second part of the paper we introduce an extended set of combinators, +including some parallel combinators, to achieve this purpose. +} + +\reference{Simon L Peyton Jones} +{GRIP - a parallel processor for functional languages} +{Electronics and Power, pp633-636, Oct 1987; +also in ICL Technical Journal 5(3), May 1987} +{ +A brief 4-page article about the GRIP architecture. +} + +\reference{Simon L Peyton Jones, Chris Clack, Jon Salkild, and Mark Hardie} +{GRIP - a high-performance architecture for parallel graph reduction} +{Proc IFIP conference on Functional Programming Languages and +Computer Architecture, Portland, +ed Kahn, Springer Verlag LNCS 274, pp98-112, Sept 1987} +{ +GRIP is a high-performance parallel machine designed to execute +functional programs using supercombinator graph reduction. +It uses a high-bandwidth bus to provide access to a +large, distributed shared memory, using intelligent memory units and +packet-switching protocols to increase the number of processors +which the bus can support. +GRIP is also being programmed to support parallel Prolog and +DACTL. + +We outline GRIP's architecture and firmware, discuss the major design +issues, and describe the current state of the project and +our plans for the future. +} + +\reference{Simon L Peyton Jones and Chris Clack} +{Finding fixpoints in abstract interpretation} +{in Abstract Interpretation of Declarative Languages, +ed Hankin \& Abramsky, Ellis Horwood, pp246-265, 1987.} +{ +Abstract interpretation is normally used as the basis for +a static, compile-time analysis of a program. +For example, strictness analysis attempts to establish which +functions in the program are strict (we will use strictness +analysis as a running example). + +Using abstract interpretation in this way requires the +compile-time evaluation of expressions in the abstract domain. +It is obviously desirable that this evaluation should +always terminate, since otherwise the compiler would risk +non-termination. +In the case of non-recursive functions there is no problem, and +termination is guaranteed. +Recursive functions, however, present more of a problem, and it +is the purpose of this paper to explain the problem and to +offer some practical solutions. +} + +\reference{Chris Clack and Simon L Peyton Jones} +{The four-stroke reduction engine} +{Proc ACM Conference on Lisp and Functional Programming, +Boston, pp220-232, Aug 1986} +{ +Functional languages are widely claimed to be amenable to concurrent +execution by multiple processors. This paper presents an algorithm for +the parallel graph reduction of a functional program. +The algorithm supports transparent management of parallel +tasks with no explicit +communication between processors. +} + +\reference{Simon L Peyton Jones} +{Functional programming languages as a software engineering tool} +{in Software Engineering - the critical decade D Ince, +Peter Peregrinus, pp124-151, 1986} +{ +It is the purpose of this paper to suggest that functional +languages are an appropriate tool for supporting the activity +of programming in the large, and to present a justification of +this claim. +} + +\reference{Simon L Peyton Jones} +{Using Futurebus in a fifth generation computer architecture} +{Microprocessors and Microsystems 10(2), March 1986} +{ +Despite the bandwidth limitations of a bus, we present a design +for a parallel computer (GRIP) based on Futurebus, which limits bus +bandwidth requirements by using intelligent memories. + +Such a machine offers higher performance than a uniprocessor +and lower cost than a more extensible multiprocessor, as well +as serving as a vehicle for research in parallel architectures. +} + + +\section{Internal reports} + +\reference{Kevin Hammond and John Glauert} +{Implementing Pattern-Matching Functional Languages using Dactl} +{University of Glasgow, 1989} +{ +This paper describes the implementation of a family of pattern-matching +functional languages in the parallel graph-rewriting language Dactl. +Attention is focussed on the direct implementation of the +pattern-matching constructs in the context of various reduction +strategies: eager, lazy, and lazy with strictness analysis. Two new +reduction strategies combining lazy evaluation with a technique for +compiling non-overlapping patterns are also illustrated. The latter +strategies provide improved termination properties compared with +conventional functional language implementations for non-overlapping +patterns. The implementations described here cover all pattern-matching +constructs found in Standard ML, including named patterns and deep +patterns. The use of Dactl renders explicit the complexities of +pattern-matching which are obscured by implementation in a conventional +intermediate language or abstract machine. +} + +\reference{Simon L Peyton Jones} +{A practical technique for designing asynchronous finite-state machines} +{Proc Glasgow Workshop on Functional Programming, Fraserburgh,Aug 1989} +{ +The literature on asynchronous logic design is mostly of a fairly theoretical +nature. We present a practical technique for generating asynchronous finite-state +machines from a description of their states and transitions. The technique +has been used successfully to design a number of state machines in +the GRIP mulitprocessor. +} + +\reference{Kevin Hammond} +{A Proposal for an Implementation of Full Dactl on a Meiko Transputer Rack} +{SYS-C89-02, University of East Anglia, 1989} +{ +The design of an abstract machine instruction set for Dactl is +described. The instruction set is sufficient to encapsulate all Dactl +constructs; it will also permit parallel execution where applicable. +The paper considers the difficulties involved in the implementation of +this abstract instruction set on the UEA Meiko M40 transputer rack, +using a ZAPP-style kernel. Part of the code for a simulation of this +instruction set is included as an appendix to the report. +} + +\reference{Chris Clack} +{Tuning the four-stroke reduction engine} +{University College London, January 1989 ($\clubsuit$)} +{ +This paper analyses the current implementation of the four-stroke reduction +engine (a virtual machine for parallel graph reduction). +The current implementation is shown to be inefficient, and a number of +enhancements are suggested. +This paper proposes that major performance benefits will accrue from +increasing the intelligence of the memory units and giving them a more +important role in the four-stroke cycle. +} + +\reference{Chris Clack} +{Performance cost accounting for GRIP} +{University College London, January 1989 ($\clubsuit$)} +{ +This paper presents a general model for efficiency anakysis of shared-memory +parallel graph reduction architectures. +The efficiency of the GRIP implementation of the four-stroke reduction engine +is subsequently analysed by approtioning costs to the various components +of the general model. + +In particular, attention is focussed on the two aspects of execution +profiling, and analysis of resource utilsation. +} + +\reference{Chris Clack} +{Diagnosis and cure for dislocated spines} +{University College London, June 1988 ($\clubsuit$)} +{ +Locality of reference is a key issue for parallel machines, and especially +for parallel implementations of graph reduction. +If locality can be achieved then communications costs fall, +and we are better able to exploit distributed architectures. +This paper analyses a particular implementation of graph reduction -- +the four-stroke reduction engine -- and introduces the concept of +spine-locality as a basis for graph building and task-scheduling strategies +that enhance locality. +} + +\end{document} diff --git a/ghc/docs/abstracts/abstracts90.tex b/ghc/docs/abstracts/abstracts90.tex new file mode 100644 index 0000000000..4bf6c657f0 --- /dev/null +++ b/ghc/docs/abstracts/abstracts90.tex @@ -0,0 +1,153 @@ +\documentstyle[11pt,slpj,abstracts]{article} + +\begin{document} + +\title{Abstracts of GRIP/GRASP-related papers and reports, 1990 +} + +\author{The GRASP team \\ Department of Computing Science \\ +University of Glasgow G12 8QQ +} + +\maketitle + +\begin{abstract} +We present a list of papers and reports related to the GRIP +and GRASP projects, +covering {\em the design, compilation technology, +and parallel implementations of functional programming languages, especially +\Haskell{}}. + +Most of them can be obtained by FTP. Connect to {\tt ftp.dcs.glasgow.ac.uk}, +and look in {\tt pub/glasgow-fp/papers}, {\tt pub/glasgow-fp/drafts}, {\tt pub/glasgow-fp/tech\_reports}, +or {\tt pub/glasgow-fp/grasp-and-aqua-docs}. + +They can also be obtained by writing to +Alexa Stewart, Department of Computing Science, +University of Glasgow G12 8QQ, UK. Her electronic mail address is +alexa@dcs.glasgow.ac.uk. +\end{abstract} + +\section{Published papers} + +\reference +{Philip Wadler} +{Comprehending monads} +{{\em ACM Conference on Lisp and Functional Programming}, +Nice, France, pp.\ 61--78, June 1990.} +{ +Category theorists invented {\em monads\/} in the 1960's +to concisely express certain aspects of universal algebra. +Functional programmers invented {\em list comprehensions\/} +in the 1970's to concisely express certain programs involving lists. +This paper shows how list comprehensions may be generalised +to an arbitrary monad, and how the resulting programming feature +can concisely express in a pure functional language some +programs that manipulate state, +handle exceptions, parse text, or invoke continuations. +A new solution to the old problem +of destructive array update is also presented. +No knowledge of category theory is assumed. +} + +\reference +{Philip Wadler} +{Linear types can change the world!} +{{\em IFIP TC 2 Working Conference on Programming +Concepts and Methods}, Sea of Galilee, Israel, April 1990.} +{ +The linear logic of J.-Y.~Girard suggests a new type +system for functional languages, one which supports operations +that ``change the world''. +Values belonging to a linear type must be used exactly once: +like the world, they cannot be duplicated or destroyed. +Such values require no reference counting or garbage collection, +and safely admit destructive array update. +Linear types extend Schmidt's notion of single threading; +provide an alternative to Hudak and Bloss' update analysis; +and offer a practical complement to Lafont and Holmstr\"om's elegant +linear languages. +} + +\reference{K Hammond and SL Peyton Jones} +{Some early experiments on the GRIP parallel reducer} +{Proc Nijmegen Workshop on Parallel Implementations of Functional Languages, TR 90-16, Dept +of Informatics, University of Nijmegen, ed Plasmeijer, 1990, pp51-72} +{ +GRIP is a multiprocessor designed to execute functional programs in +parallel using graph reduction. We have implemented a compiler for +GRIP, based on the Spineless Tagless G-machine +and can now run parallel functional programs with substantial absolute +speedup over the same program running on a uniprocessor Sun. + +Parallel functional programming shifts some of the burden of resource +allocation from the programmer to the system. Examples of such +decisions include: when to create a new concurrent activity (or {\em +thread}), when to execute such threads, where to execute them, and so +on. + +It is clearly desirable that the system should take such decisions, +{\em provided it does +a good enough job}. For example, a paged virtual memory system +almost always does an adequate job, and a programmer very seldom +has to intefere with it. +The big question for parallel functional programming is whether good +resource-allocation strategies exist, and how well they perform under a +variety of conditions. + +Now that we have an operational system, we are starting to carry out +experiments to develop resource-allocation strategies, and measure +their effectiveness. This paper reports on some very preliminary +results. They mainly concern the question of when, or even whether, +to create a new thread. This is an aspect which has so far received +little attention --- existing work has focused mainly +on load sharing rather than on thread creation. +} + + +\section{Technical reports} + +\reference +{Simon L Peyton Jones and Philip Wadler} +{A static semantics for \Haskell{}} +{Dept of Computing Science, University of Glasgow} +{ +This paper gives a static semantics for a large subset of \Haskell{}, including +giving a translation into a language without overloading. +It is our intention to cover the complete language in due course. + +One innovative aspect is the use of ideas from the second-order lambda +calculus to record type information in the program. + +The paper is long (40 pages) and is more of a reference document than +a narrative one. +} + +\reference +{Philip Wadler} +{A simple type inference algorithm} +{Dept of Computing Science, University of Glasgow} +{ +This program is intended as a showcase for Haskell's +literate programming facility and for the monadic style +of programming. It implements Hindley-Milner type inference. +Monads are used for parsing and to simplify ``plumbing'' in the type +checker. The monads for parsing, exceptions, and state as well +as the routines for unparsing are designed to be of general utility. +} + +\reference{The Grasp team} +{The Glasgow Haskell I/O system} +{Dept of Computing Science, University of Glasgow, Nov 1991} +{ +Most input/output systems for non-strict functional languages +feature a rather large ``operating system +The Glasgow Haskell system implements input and output +very largely within Haskell itself, without the conventional +enclosing ``printing mechanism''. This paper explains how the +IO system works in some detail. +} + +\end{document} + + diff --git a/ghc/docs/abstracts/abstracts91.tex b/ghc/docs/abstracts/abstracts91.tex new file mode 100644 index 0000000000..913007e3ba --- /dev/null +++ b/ghc/docs/abstracts/abstracts91.tex @@ -0,0 +1,232 @@ +\documentstyle[11pt,slpj,abstracts]{article} + +\begin{document} + +\title{Abstracts of GRIP/GRASP-related papers and reports, 1991 +} + +\author{The GRASP team \\ Department of Computing Science \\ +University of Glasgow G12 8QQ +} + +\maketitle + +\begin{abstract} +We present a list of papers and reports related to the GRIP +and GRASP projects, +covering {\em the design, compilation technology, +and parallel implementations of functional programming languages, especially +\Haskell{}}. + +Most of them can be obtained by FTP. Connect to {\tt ftp.dcs.glasgow.ac.uk}, +and look in {\tt pub/glasgow-fp/papers}, {\tt pub/glasgow-fp/drafts}, {\tt pub/glasgow-fp/tech\_reports}, +or {\tt pub/glasgow-fp/grasp-and-aqua-docs}. + +They can also be obtained by writing to +Alexa Stewart, Department of Computing Science, +University of Glasgow G12 8QQ, UK. Her electronic mail address is +alexa@dcs.glasgow.ac.uk. +\end{abstract} + +\section{Published papers} + +\reference +{Simon L Peyton Jones and David Lester} +{A modular fully-lazy lambda lifter in \Haskell{}} +{{\em Software Practice and Experience}, 21(5) (May 1991)} +{An important step in many compilers for functional languages is +{\em lambda lifting}. In his thesis, Hughes showed that by doing lambda +lifting in a particular way, a useful property called {\em full laziness} +can be preserved; +full laziness has been seen as intertwined with +lambda lifting ever since. + +We show that, on the contrary, full laziness can be regarded as a completely +separate process to lambda lifting, thus making it easy to use different +lambda lifters following a full-laziness transformation, or to use +the full-laziness transformation in compilers which do not require lambda +lifting. + +On the way, we present the complete code for our modular fully-lazy +lambda lifter, written in the \Haskell{} functional programming language. +} + +\reference{Simon L Peyton Jones and Mark Hardie} +{A Futurebus interface from off-the-shelf parts} +{IEEE Micro, Feb 1991} +{ +As part of the GRIP project we have designed a Futurebus interface using +off-the-shelf parts. +We describe our implementation, which is unusual in its use of fully +asynchronous finite-state machines. +Based on this experience we draw some lessons for future designs. +} + +\reference{Simon L Peyton Jones and John Launchbury} +{Unboxed values as first class citizens} +{Functional Programming Languages and Computer Architecture (FPCA), Boston, +ed Hughes, Springer LNCS 523, Sept 1991, pp636--666} +{The code compiled from a non-strict functional program usually +manipulates heap-allocated {\em boxed} numbers. +Compilers for such languages often go to considerable trouble to +optimise operations on boxed numbers into simpler operations +on their unboxed forms. These optimisations are usually handled +in an {\em ad hoc} manner in +the code generator, because earlier phases of the compiler have +no way to talk about unboxed values. + +We present a new approach, which makes unboxed values into (nearly) first-class +citizens. The language, including its type system, is extended to +handle unboxed values. The optimisation of boxing and unboxing operations +can now be reinterpreted as a set of correctness-preserving program +transformations. Indeed the particular transformations +required are ones which a compiler would want to implement anyway. +The compiler becomes both simpler and more modular. + +Two other benefits accrue. +Firstly, the results of strictness analysis can be exploited within +the same uniform transformational framework. +Secondly, new algebraic data types with +unboxed components can be declared. Values of these types can be +manipulated much more efficiently than the corresponding boxed versions. + +Both a static and a dynamic semantics are given for the augmented language. +The denotational dynamic semantics is notable for its use of +{\em unpointed domains}. +} + +\reference{Philip Wadler} +{Is there a use for linear logic?} +{ACM/IFIP Symposium on Partial Evaluation +and Semantics Based Program Manipulation (PEPM), Yale +University, June 1991} +{ +Past attempts to apply Girard's linear logic have either had a clear +relation to the theory (Lafont, Holmstr\"om, Abramsky) or a clear +practical value (Guzm\'an and Hudak, Wadler), but not both. This paper +defines a sequence of languages based on linear logic that span the gap +between theory and practice. Type reconstruction in a linear type +system can derive information about sharing. An approach to linear type +reconstruction based on {\em use types\/} is presented. Applications +to the {\em array update\/} problem are considered. +} + +\reference{Simon L Peyton Jones} +{The Spineless Tagless G-machine: a second attempt} +{Proc Workshop on Parallel Implementations of Functional Languages, +University of Southampton, ed Glaser \& Hartel, June 1991} +{The Spineless Tagless G-machine is an abstract machine designed +to support functional languages. This presentation of the machine +falls into two parts. Firstly, we present the {\em STG language}, +an austere but recognisably-functional language, which as well as +a {\em denotational} meaning has a well-defined {\em operational} semantics. +The STG language is the ``abstract machine code'' for the Spineless +Tagless G-machine, but it is sufficiently abstract that it can readily be +compiled into G-machine Gcode or TIM code instead. + +Secondly, we discuss the mapping of the STG language onto stock hardware. +The success of an abstract machine model depends largely on how efficient +this mapping can be made, though this topic is often relegated to a short +section. Instead, we give a detailed discussion of the design issues and +the choices we have made. Our principal target is the C language, treating +the C compiler as a portable assembler. + +A revised version is in preparation for the Journal of Functional Programming. +} + +\reference{Gert Akerholt, Kevin Hammond, Simon Peyton Jones and Phil Trinder} +{A parallel functional database on GRIP} +{\GlasgowNinetyOne{}, pp1-24} +{ +GRIP is a shared-memory multiprocessor designed for efficient parallel +evaluation of functional languages, using compiled graph reduction. +In this paper, we consider the feasibility of implementing a database +manager on GRIP, and present results obtained from a pilot +implementation. A database implemented in a pure functional language +must be modified {\em non-destructively}, i.e.\ the original database +must be preserved and a new copy constructed. The naive +implementation provides evidence for the feasibility of a pure +functional database in the form of modest real-time speed-ups, and +acceptable real-time performance. This performance can be tentatively +compared with results for existing machines running a more +sophisticated database benchmark. +The functional database is also used to investigate the GRIP +architecture, compared with an idealised machine. The particular +features investigated are the thread-creation costs and caching of +GRIP's distributed memory. +} + +\reference{PM Sansom} +{Combining single-space and two-space compacting garbage collectors} +{\GlasgowNinetyOne{}, pp312-324} +{The garbage collector presented in this paper makes use of +two well known compaction garbage collection algorithms with very +different performance characteristics: Cheney's two-space copying +collector and Jon\-ker's single-space sliding compaction collector. We +propose a scheme which allows either collector to be used. The +run-time memory requirements of the program being executed are used to +determine the most appropriate collector. This enables us to achieve a +fast collector for heap requirements less than half of the heap memory +but allows the heap utilization to increase beyond this threshold. +Using these ideas we develop a particularly attractive extension to +Appel's generational collector. +} + +\reference{PM Sansom} +{Dual-mode garbage collection} +{Proc Workshop on the Parallel Implementation of Functional Languages, Southampton, +ed Glaser \& Hartel, pp283-310} +{ +The garbage collector presented in this paper makes use of two well +known compaction garbage collection algorithms with very different +performance characteristics: Cheney's two-space copying collector and +Jonker's sliding compaction collector. We propose a scheme which +allows either collector to be used. The run-time memory requirements +of the program being executed are used to determine the most +appropriate collector. This enables us to achieve a fast collector for +heap requirements less than half of the heap memory but allows the +heap utilization to increase beyond this threshold. Using these ideas +we develop a particularly attractive extension to Appel's generational +collector. + +We also describe a particularly fast implementation of the garbage +collector which avoids interpreting the structure and current state of +closures by attaching specific code to heap objects. This code {\em +knows} the structure and current state of the object and performs the +appropriate actions without having to test any flag or arity fields. +The result is an implementation of these collection schemes which does +not require any additional storage to be associated with the heap +objects. + +This paper is an earlier, and fuller, version of ``Combining +single-space and two-space compacting garbage collectors'' above. +} + +\reference{K Hammond} +{Efficient type inference using monads} +{\GlasgowNinetyOne{}, pp146-157} +{{\em Efficient} type inference algorithms are based on +graph-rewriting techniques. Consequently, at first sight they seem +unsuitable for functional language implementation. In fact, most +compilers written in functional languages use substitution-based +algorithms, at a considerable cost in performance. In this paper, we +show how monads may be used to transform a substutition-based inference +algorithm into one using a graph representation. The resulting +algorithm is faster than the corresponding substitution-based one.} + + +\section{Technical reports} + +\reference{The Grasp team} +{The Glasgow Haskell I/O system} +{Dept of Computing Science, University of Glasgow, Nov 1991} +{ +Most input/output systems for non-strict functional languages +feature a rather large ``operating system +The Glasgow Haskell system implements input and output +very largely within Haskell itself, without the conventional +enclosing ``printing mechanism''. This paper explains how the +IO system works in some detail. +} + +\end{document} diff --git a/ghc/docs/abstracts/abstracts92.tex b/ghc/docs/abstracts/abstracts92.tex new file mode 100644 index 0000000000..6c25d665bc --- /dev/null +++ b/ghc/docs/abstracts/abstracts92.tex @@ -0,0 +1,292 @@ +\documentstyle[11pt,slpj,abstracts]{article} +\begin{document} + +% ====================================================== + +\title{Abstracts of GRIP/GRASP-related papers and reports, 1992 +} + +\author{The GRASP team \\ Department of Computing Science \\ +University of Glasgow G12 8QQ +} + +\maketitle + +\begin{abstract} +We present a list of papers and reports related to the GRIP +and GRASP projects, +covering {\em the design, compilation technology, +and parallel implementations of functional programming languages, especially +\Haskell{}}. + +Most of them can be obtained by FTP. Connect to {\tt ftp.dcs.glasgow.ac.uk}, +and look in {\tt pub/glasgow-fp/papers}, {\tt pub/glasgow-fp/drafts}, {\tt pub/glasgow-fp/tech\_reports}, +or {\tt pub/glasgow-fp/grasp-and-aqua-docs}. + +They can also be obtained by writing to +Alexa Stewart, Department of Computing Science, +University of Glasgow G12 8QQ, UK. Her electronic mail address is +alexa@dcs.glasgow.ac.uk. +\end{abstract} + +\section{Book} + +\reference{Simon Peyton Jones and David Lester} +{Implementing functional languages} +{Prentice Hall, 1992} +{ +This book gives a practical approach to understanding implementations +of non-strict functional languages using lazy graph reduction. + +An unusual feature of the book is that the text of each chapter is +itself a directly-executable Miranda(TM) program, constituting a +minimal but complete compiler and interpreter for a particular +abstract machine. The complete source code for the book, and a +Tutor's Guide containing solutions to the exercises, is available in +machine-readable form by network file transfer (FTP). + +Written to allow the reader to modify, extend and experiment with the +implementations provided in the text, this book will help to make a +course on functional-langauge implementation "come alive". + +{\bf Contents}. The Core Language. Template instantiation. The G-machine. +The Three Instruction Machine. A parallel G-machine. Lambda lifting +and full laziness. Appendices. Bibliography. Index. +} + + +\section{Published papers} + +\reference{Simon L Peyton Jones} +{Implementing lazy functional languages on stock hardware: +the Spineless Tagless G-machine} +{Journal of Functional Programming 2(2) (Apr 1992)} +{The Spineless Tagless G-machine is an abstract machine designed +to support non-strict higher-order +functional languages. This presentation of the machine +falls into three parts. Firstly, we give a general discussion of +the design issues involved in implementing non-strict functional +languages. + +Next, we present the {\em STG language}, +an austere but recognisably-functional language, which as well as +a {\em denotational} meaning has a well-defined {\em operational} semantics. +The STG language is the ``abstract machine code'' for the Spineless +Tagless G-machine. + +Lastly, we discuss the mapping of the STG language onto stock hardware. +The success of an abstract machine model depends largely on how efficient +this mapping can be made, though this topic is often relegated to a short +section. Instead, we give a detailed discussion of the design issues and +the choices we have made. Our principal target is the C language, treating +the C compiler as a portable assembler. + +This paper used to be called ``The Spineless Tagless G-machine: a second +attempt'', but has been retitled and substantially expanded with new +material which tries to set the machine in the context of compiler +technology for other languages. The paper is very long (65 pages) and +has an index. +} + +\reference{Philip Wadler} +{The essence of functional programming} +{Invited talk, 19'th Annual Symposium on Principles of +Programming Languages, Santa Fe, New Mexico, Jan 1992} +{ +This paper explores the use monads to structure functional programs. +No prior knowledge of monads or category theory is required. + +Monads increase the ease with which programs may be modified. They can +mimic the effect of impure features such as exceptions, state, and +continuations; and also provide effects not easily achieved with such +features. The types of a program reflect which effects occur. + +The first section is an extended example of the use of monads. A +simple interpreter is modified to support various extra features: error +messages, state, output, and non-deterministic choice. The second +section describes the relation between monads and continuation-passing +style. The third section sketches how monads are used in a compiler +for Haskell that is written in Haskell. +} + +\reference{A Santos and SL Peyton Jones} +{On program transformation and the Glasgow Haskell compiler} +{\GlasgowNinetyTwo{}, pp240-251} +{We describe a series of program transformations that are implemented +in the Glasgow Haskell Compiler. They are semantics preserving +transformations and suitable for automatic application by a compier. +We describe the transformations, how they interact, and their impact +on the time/space behaviour of some programs.} + +\reference{P Sansom and SL Peyton Jones} +{Profiling lazy functional languages} +{\GlasgowNinetyTwo{}, pp227-239} +{Profiling tools, which measure and display the dynamic space +and time behaviour of programs, are essential for identifying +execution bottlenecks. A variety of such tools exist for conventional +languages, but almost none for non-strict functional languages. There +is a good reason for this: lazy evaluation means that the program is +executed in an order which is not immediately apparent from the source +code, so it is difficult to relate dynamically-gathered statistics +back to the original source. + +We present a new technique which solves this problem. The framework is +general enough to profile both space and time behaviour. Better still, +it is cheap to implement, and we describe how to do so in the +context of the Spineless Tagless G-machine. +} + +\reference{CV Hall, K Hammond, WD Partain, SL Peyton Jones, and PL Wadler} +{The Glasgow Haskell Compiler: a retrospective} +{\GlasgowNinetyTwo{}, pp62-71} +{We've spent much of our time over the last +two years implementing a new compiler for the functional language Haskell +In this effort, we've been joined by Andy Gill, who has implemented a +strictness analyser, Andre Santos, who has contributed a `simplifier', and +Patrick Sansom, who wrote garbage collectors for our runtime system. + +This paper describes some of the things we have learned, what we might +do differently, and where we go from here. +} + +\reference{D King and PL Wadler} +{Combining monads} +{\GlasgowNinetyTwo{}, pp134-143} +{Monads provide a way of structuring functional programs. +Most real applications require a combination of primitive monads. +Here we describe how some monads may be combined with others to +yield a {\em combined monad}.} + +\reference{J Launchbury, A Gill, RJM Hughes, S Marlow, SL Peyton Jones, and PL Wadler} +{Avoiding unnecessary updates} +{\GlasgowNinetyTwo{}, pp144-153} +{Graph reduction underlies most implementations of lazy functional +languages, allowing separate computations to share results when +sub-terms are evaluated. Once a term is evaluated, the node of the +graph representing the computation is {\em updated} with the value of +the term. However, in many cases, no other computation requires this +value, so the update is unnecessary. In this paper we take some steps +towards an analysis for determining when these updates may be omitted. +} + +\reference{S Marlow and PL Wadler} +{Deforestation for higher-order functions} +{\GlasgowNinetyTwo{}, pp154-165} +{Deforestation is an automatic transformation scheme for functional +programs which attempts to remove unnecessary intermediate data +structures. The algorithm presented here is a variant of the original, +adapted for a higher order language. A detailed description of how +this may be implemented in an optimising compiler is also given. +} + +\reference{WD Partain} +{The nofib benchmark suite of Haskell programs} +{\GlasgowNinetyTwo{}, pp195-202} +{This position paper describes the need for, make-up of, and +``rules of the game'' for a benchmark suite of Haskell programs. (It +does not include results from running the suite.) Those of us working +on the Glasgow Haskell compiler hope this suite will encourage sound, +quantitative assessment of lazy functional programming systems. This +version of this paper reflects the state of play at the initial +pre-release of the suite. +} + +\reference{PL Wadler} +{Monads for functional programming} +{Proceedings of the Marktoberdorf Summer School on Programming Calculi, +ed M Broy, July-August 1992, Springer Verlag} +{The use of monads to structure functional programs is +described. Monads provide a convenient framework for simulating +effects found in other languages, such as global state, exception +handling, output, or non-determinism. Three case studies are looked at +in detail: how monads ease the modification of a simple evaluator; +how monads act as the basis of a datatype of arrays subject to in-place +update; and how monads can be used to build parsers. +} + +\reference{K Hammond, P Trinder, P Sansom and D McNally} +{Improving persistent data manipulation for functional languages} +{\GlasgowNinetyTwo{}, pp72-85} +{Although there is a great deal of academic interest in +functional languages, there are very few large-scale functional +applications. The poor interface to the file system seems to be a +major factor preventing functional languages being used for +large-scale programming tasks. The interfaces provided by some +widely-used languages are described and some problems encountered with +using these interfaces to access persistent data are discussed. Three +means of improving the persistent data manipulation facilities of +functional languages are considered: an improved interface to the file +system, including a good binary file implementation; an interface to a +database; and the provision of orthogonal persistence. Concrete +examples are given using the functional programming language, Haskell. +} + +\reference{Kevin Hammond and Simon Peyton Jones} +{Profiling scheduling strategies on the GRIP parallel reducer} +{Proc 1992 Workshop on Parallel Implementations of Functional Languages, Aachen, +ed Kuchen, Sept 1992} +{It is widely claimed that functional languages are particularly +suitable for programming parallel computers. A claimed advantage is +that the programmer is not burdened with details of task creation, +placement, scheduling, and synchronisation, these decisions being +taken by the system instead. + +Leaving aside the question of whether a pure functional language is +expressive enough to encompass all the parallel algorithms we might +wish to program, there remains the question of how effectively the +compiler and run-time system map the program onto a real parallel +system, a task usually carried out mostly by the programmer. This is +the question we address in our paper. + +We first introduce the system architecture of GRIP, a shared-memory +parallel machine supporting an implementation of the functional +language Haskell. GRIP executes functional programs in parallel using +compiled supercombinator graph reduction, a form of +declarative rule system. + +We then to describe several strategies for run-time resource +control which we have tried, presenting comprehensive measurements of +their effectiveness. We are particularly concerned with strategies +controlling task creation, in order to improve task granularity and +minimise communication overheads. This is, so far as we know, one of +the first attempts to make a systematic study of task-control +strategies in a high-performance parallel functional-language system. +GRIP's high absolute performance render these results credible for +real applications. +} + +\section{Technical reports} + +\reference{CV Hall, K Hammond, SL Peyton Jones, PL Wadler} +{Type classes in Haskell} +{Department of Computing Science, University of Glasgow} +{This paper defines a set of type inference rules for resolving +overloading introduced by type classes. Programs including type +classes are transformed into ones which may be typed by the +Hindley-Milner inference rules. In contrast to an other work on type +classes, the rules presented here relate directly to user programs. An +innovative aspect of this work is the use of second-order lambda +calculus to record type information in the program. +} + +\shortreference{CV Hall} +{A transformed life: introducing optimised lists automatically} +{submitted to FPCA 93} +{} + +\shortreference{K Hammond} +{The Spineless Tagless G-machine --- NOT!} +{submitted to FPCA 93} + +\shortreference{CV Hall} +{An optimists view of Life} +{submitted to Journal of Functional Programming, 1993} +{} +% ~cvh/Public/Papers/An_Optimists_View.dvi + +\end{document} + + + + + diff --git a/ghc/docs/abstracts/abstracts93.tex b/ghc/docs/abstracts/abstracts93.tex new file mode 100644 index 0000000000..fa15bebdde --- /dev/null +++ b/ghc/docs/abstracts/abstracts93.tex @@ -0,0 +1,326 @@ +\documentstyle[11pt,slpj,abstracts]{article} + +\begin{document} + +% ====================================================== + +\title{Abstracts of GRIP/GRASP/AQUA-related papers and reports, 1993 +} + +\author{The AQUA team \\ Department of Computing Science \\ +University of Glasgow G12 8QQ +} + +\maketitle + +\begin{abstract} +We present a list of papers and reports related to the GRIP, GRASP and AQUA projects, +covering {\em the design, compilation technology, +and parallel implementations of functional programming languages, especially +\Haskell{}}. + +Most of them can be obtained by FTP. Connect to {\tt ftp.dcs.glasgow.ac.uk}, +and look in {\tt pub/glasgow-fp/papers}, {\tt pub/glasgow-fp/drafts}, {\tt pub/glasgow-fp/tech\_reports}, +or {\tt pub/glasgow-fp/grasp-and-aqua-docs}. + +They can also be obtained by writing to +Alexa Stewart, Department of Computing Science, +University of Glasgow G12 8QQ, UK. Her electronic mail address is +alexa@dcs.glasgow.ac.uk. +\end{abstract} + +\section{Published papers} + +\reference{CV Hall} +{Using overloading to express distinctions} +{Information Processing Letters (to appear)} +{ +Evaluators, also called ``interpreters'', play a variety of roles +in the study of programming languages. Given this, it's surprising +that we don't have a better framework for developing evaluators and +specifying their relationship to each other. This paper +shows that type classes in Haskell provide an excellent +framework for exploring relationships between evaluators, using +abstract interpretation as a motivating example. +} + +\reference{A Gill, J Launchbury and SL Peyton Jones} +{A short cut to deforestation} +{ACM Conference on Functional Programming and Computer Architecture, Copenhagen, pp223-232} +{Lists are often used as ``glue'' to connect +separate parts of a program together. +We propose an automatic technique for +improving the efficiency of such programs, +by removing many of these intermediate lists, +based on a single, simple, local transformation. +We have implemented the method in the Glasgow Haskell compiler. +} + +\reference{P Sansom and SL Peyton Jones} +{Generational garbage collection for Haskell} +{ACM Conference on Functional Programming and Computer Architecture, Copenhagen, pp106-116} +{This paper examines the use of generational garbage collection +techniques for a lazy implementation of a non-strict functional +language. Detailed measurements which demonstrate that a generational +garbage collector can substantially out-perform non-generational +collectors, despite the frequency of write operations in the +underlying implementation, are presented. + +Our measurements are taken from a state-of-the-art compiled +implementation for Haskell, running substantial benchmark programs. +We make measurements of dynamic properties (such as object lifetimes) +which affect generational collectors, study their interaction with a +simple generational scheme, make direct performance comparisons with +simpler collectors, and quantify the interaction with a paging system. + +The generational collector is demonstrably superior. At least for our +benchmarks, it reduces the net storage management overhead, and it +allows larger programs to be run on a given machine before thrashing +ensues.} + +\reference{J Launchbury} +{Lazy imperative programming} +{Proc ACM Sigplan Workshop on State in Programming Languages, Copenhagen, June 1993 (available as +YALEU/DCS/RR-968, Yale University), pp46-56} +{ +In this paper we argue for the importance of lazy state, that is, +sequences of imperative (destructive) actions in which the actions are +delayed until their results are required. This enables state-based +computations to take advantage of the control power of lazy evaluation. +We provide some examples of its use, and describe an implementation +within Glasgow Haskell. +} + +\reference{G Akerholt, K Hammond, P Trinder and SL Peyton Jones} +{Processing transactions on GRIP, a parallel graph reducer} +{Proc Parallel Architectures and Languages Europe (PARLE), Munich, June 1993, pp634-647} +{ +The GRIP architecture allows efficient execution of functional +programs on a multi-processor built from standard hardware components. +State-of-the-art compilation techniques are combined with +sophisticated runtime resource-control to give good parallel +performance. This paper reports the results of running GRIP on an +application which is apparently unsuited to the basic functional +model: a database transaction manager incorporating updates as well as +lookup transactions. The results obtained show good relative speedups +for GRIP, with real performance advantages over the same application +executing on sequential machines. +} + +\reference{SL Peyton Jones and PL Wadler} +{Imperative functional programming} +{ACM conference on Principles of Programming Languages, Charleston, Jan 1993} +{We present a new model, based on monads, for performing input/output +in a non-strict, purely functional language. It +is composable, extensible, efficient, requires no extensions +to the type system, and extends smoothly to incorporate mixed-language +working and in-place array updates. +} + +\reference{J Launchbury} +{An operational semantics for lazy evaluation} +{ACM conference on Principles of Programming Languages, Charleston, Jan 1993} +{We define an operational semantics for lazy evaluation which provides +an accurate model for sharing. The only computational structure +we introduce is a set of bindings which corresponds closely to a +heap. The semantics is set at a considerably higher level of abstraction +than operational semantics for particular abstract machines, so is +more suitable for a variety of proofs. Furthermore, because a heap +is explicitly modelled, the semantics provides a suitable framework +for studies about space behaviour of terms under lazy evaluation. +} + +\reference{SL Peyton Jones, CV Hall, K Hammond, WD Partain, and PL Wadler} +{The Glasgow Haskell compiler: a technical overview} +{JFIT Technical Conference, Keele, March 1993} +{We give an overview of the Glasgow Haskell compiler, +focusing especially on way in which we have been able +to exploit the rich theory of functional languages to give +very practical improvements in the compiler. + +The compiler is portable, modular, generates good code, and is +freely available. +} + +\reference{PL Wadler} +{A syntax for linear logic} +{Mathematical Foundations of +Programming Language Semantics, New Orleans, April 1993} +{There is a standard syntax for Girard's linear logic, due +to Abramsky, and a standard semantics, due to Seely. Alas, the +former is incoherent with the latter: different derivations of +the same syntax may be assigned different semantics. This paper +reviews the standard syntax and semantics, and discusses the problem +that arises and a standard approach to its solution. A new solution +is proposed, based on ideas taken from Girard's Logic of Unity. +The new syntax is based on pattern matching, allowing for concise +expression of programs.} + +\reference{SL Peyton Jones, J Hughes, J Launchbury} +{How to give a good research talk} +{SIGPLAN Notices 28(11), Nov 1993, 9-12} +{ +Giving a good research talk is not easy. We try to identify some things +which we have found helpful, in the hope that they may be useful to you. +} + + +\section{Workshop papers and technical reports} + +The 1993 Glasgow Functional Programming Workshop papers exist in +the draft proceedings at the moment. They are being refereed, and will +be published by Springer Verlag in due course. + +\reference{DJ King and J Launchbury} +{Lazy Depth-First Search and Linear Graph Algorithms in Haskell} +{\GlasgowNinetyThree{}} +{ +Depth-first search is the key to a wide variety of graph algorithms. +In this paper we explore the implementation of depth first search in a +lazy functional language. For the first time in such languages we +obtain a linear-time implementation. But we go further. Unlike +traditional imperative presentations, algorithms are constructed from +individual components, which may be reused to create new +algorithms. Furthermore, the style of program is quite amenable to +formal proof, which we exemplify through a calculational-style proof +of a strongly-connected components algorithm. + +{\em This paper has been submitted to Lisp \& Functional Programming 1994.} +} + +\reference{K Hammond, GL Burn and DB Howe} +{Spiking your caches} +{\GlasgowNinetyThree{}} +{ +Despite recent advances, predicting the performance of functional +programs on real machines remains something of a black art. This +paper reports on one particularly unexpected set of results where +small variations in the size of a dynamic heap occasionally gave rise +to 50\% differences in CPU performance. These performance {\em +spikes} can be traced to the cache architecture of the machine being +benchmarked, the widely-used Sun Sparcstation~1. A major contribution +of our work is the provision of a tool which allows cache conflicts +to be located by the type of access (heap, stack etc.). This can +be used to improve the functional language implementation, or to +study the memory access patterns of a particular program. +} + +\reference{S Marlow} +{Update avoidance analysis} +{\GlasgowNinetyThree{}} +{ +A requirement of lazy evaluation is that the value of any +subexpression in the program is calculated no more than once. This is +achieved by updating an expression with its value, once computed. The +problem is that updating is a costly operation, and experimentation +has shown that it is only necessary in about 30\% of cases (that is, +70\% of expressions represent values that are only ever required once +during execution). The aim of the analysis presented in this paper is +to discover expressions that do not need to be updated, and thus +reduce the execution time of the program. The analysis has been +implemented in the Glasgow Haskell Compiler, and results are given. + +FTP: @pub/glasgow-fp/authors/Simon_Marlow/update-avoidance.ps.gz@ +} + +\reference{SL Peyton Jones and WD Partain} +{Measuring the effectiveness of a simple strictness analyser} +{\GlasgowNinetyThree{}} +{ +A lot has been written about strictness analysis for non-strict +functional programs, usually in the hope that the results of the +analysis can be used to reduce runtime. On the other hand, few papers +present measurements of how well it works in practice. Usually, all +that is presented are the run-times of a variety of (usually small) +programs, with and without strictness analysis enabled. The goal of +this paper is to provide detailed quantitative insight about the +effectiveness of a simple strictness analyser, in the context of a +state-of-the art compiler running serious application programs. +} + +\reference{J Mattson} +{Local speculative evaluation for distributed graph reduction} +{\GlasgowNinetyThree{}} +{ +Speculative evaluation attempts to increase parallelism by +performing potentially useful computations before they are known to be +necessary. Speculative computations may be coded explicitly in a +program, or they may be scheduled implicitly by the reduction system +as idle processors become available. A general approach to both kinds +of speculation incurs a great deal of overhead which may outweigh the +benefits of speculative evaluation for fine-grain speculative tasks. + +Suppose that implicit speculative computations are restricted to +execution on the local processor, with the hope of performing +potentially useful work while the local mandatory tasks are all +blocked. This restriction greatly simplifies the problems of +speculative task management, and it opens the door for fine-grain +speculative tasks. More complex mechanisms for distributing +and managing coarse-grain speculative tasks can later be added on top of +the basic foundation provided for local speculative evaluation. +} + +\reference{PM Sansom} +{Time profiling a lazy functional compiler} +{\GlasgowNinetyThree{}} +{ +Recent years has seen the development of profiling tools for lazy +functional language implementations. This paper presents the results +of using a time profiler to profile the Glasgow Haskell compiler. +} + +\reference{D King and J Launchbury} +{Functional graph algorithms with depth-first search} +{\GlasgowNinetyThree{}} +{Performing a depth-first search of a graph is one of the fundamental +approaches for solving a variety of graph algorithms. Implementing +depth-first search efficiently in a pure functional language has only +become possible with the advent of imperative functional programming. +In this paper we mix the techniques of pure functional programming in +the same cauldron as depth-first search, to yield a more lucid +approach to viewing a variety of graph algorithms. This claim will be +illustrated with several examples.} + +\reference{A Santos and SL Peyton Jones} +{Tuning a compiler's allocation policy} +{\GlasgowNinetyThree{}} +{There are many different costs involved in the allocation of +closures during the execution of functional programs. Even more so +for closures that are not in normal form, as they have to be +allocated and then possibley entered and updated. We compare several +different policies for closure allocation, trying to minimise these +costs. The issues of laziness and full laziness are discussed. +} + +\reference{CV Hall} +{A framework for optimising abstract data types} +{\GlasgowNinetyThree{}} +{Two trends have been developing in functional programming language +research. First, compilers are supporting optimisations of data +types, such as unboxed types and parallel bags. Second, functional +programmers are increasingly writing code in a style that treats +data types as if they were abstract. Abstract data types offer +opportunities for optimisation because the representation of the +type can be optimised without affecting the program, allowing the +programmer to use operations on it and improve performance. At the +same time, the original type is often required by some part of the +program, and the programmer is left to figure out which to use +where. + +This paper presents a general framework in which good functional +style automatically supports the efficient implementation of data +types. It has been implemented in the Glasgow Haskell compiler +specifically to introduce an optimised list representation, and +this has been shown to cut execution time in half on a Sun +SPARCstation-1 for a substantial program. Recent tests show that +it improves performance by more than a factor of 4 on the GRIP +parallel processor for short tests, however more experiments will +be necessary before we can assert that this speedup holds in +general. +} +\end{document} + + + + + diff --git a/ghc/docs/abstracts/abstracts94.tex b/ghc/docs/abstracts/abstracts94.tex new file mode 100644 index 0000000000..7ee257db60 --- /dev/null +++ b/ghc/docs/abstracts/abstracts94.tex @@ -0,0 +1,187 @@ +\documentstyle[11pt,slpj,abstracts]{article} + +\begin{document} + +% ====================================================== + +\title{Abstracts of GRIP/GRASP/AQUA-related papers and reports, 1994 +} + +\author{The AQUA team \\ Department of Computing Science \\ +University of Glasgow G12 8QQ +} + +\maketitle + +\begin{abstract} +We present a list of papers and reports related to the GRIP, GRASP and AQUA projects, +covering {\em the design, compilation technology, +and parallel implementations of functional programming languages, especially +\Haskell{}}. + +Most of them can be obtained by FTP. Connect to {\tt ftp.dcs.glasgow.ac.uk}, +and look in {\tt pub/glasgow-fp/papers}, {\tt pub/glasgow-fp/drafts}, {\tt pub/glasgow-fp/tech\_reports}, +or {\tt pub/glasgow-fp/grasp-and-aqua-docs}. + +Another useful place to look is on the Functional Programming Group WWW page: +{\tt ftp://ftp.dcs.glasgow.ac.uk/pub/glasgow-fp/glasgow-fp.html}. + +They can also be obtained by writing to +Helen McNee, Department of Computing Science, +University of Glasgow G12 8QQ, UK. Her electronic mail address is +helen@dcs.glasgow.ac.uk. +\end{abstract} + +\section{Published papers} + +\reference{J Launchbury and SL Peyton Jones} +{State in Haskell} +{To appear in Lisp and Symbolic Computation (50 pages)} +{ +Some algorithms make critical internal use of updatable state, even +though their external specification is purely functional. Based on +earlier work on monads, we present a way of securely encapsulating +stateful computations that manipulate multiple, named, mutable +objects, in the context of a non-strict, purely-functional language. +The security of the encapsulation is assured by the type system, using +parametricity. The same framework is also used to handle input/output +operations (state changes on the external world) and calls to C. + +FTP: {\tt pub/glasgow-fp/drafts/state-lasc.ps.Z} +} + +\reference{P Sansom and SL Peyton Jones} +{Time and space profiling for non-strict higher-order functional languages} +{To appear in POPL 95} +{ +We present the first profiler for a compiled, non-strict, higher-order, +purely functional language capable of measuring {\em time} +as well as {\em space} usage. Our profiler is implemented +in a production-quality optimising compiler for Haskell, +has low overheads, and can successfully profile large applications. + +A unique feature of our approach is that we give a formal +specification of the attribution of execution costs to cost centres. +This specification enables us to discuss our design decisions in a +precise framework. Since it is not obvious how to map this +specification onto a particular implementation, we also present an +implementation-oriented operational semantics, and prove it equivalent +to the specification. +} + + +% pub/glasgow-fp/authors/Philip_Wadler/monads-for-fp.dvi + +\reference{Philip Wadler} +{Monads for functional programming} +{in M. Broy (editor), +{\em Program Design Calculi}, proceedings of the International +Summer School directed by F. L. Bauer, M. Broy, E. W. Dijkstra, D. +Gries, and C. A. R. Hoare. Springer Verlag, NATO ASI series, Series +F: Computer and System Sciences, Volume 118, 1994} +{ +The use of monads to structure functional programs is +described. Monads provide a convenient framework for simulating +effects found in other languages, such as global state, exception +handling, output, or non-determinism. Three case studies are looked at +in detail: how monads ease the modification of a simple evaluator; +how monads act as the basis of a datatype of arrays subject to in-place +update; and how monads can be used to build parsers. +} + +% pub/glasgow-fp/authors/Philip_Wadler/taste-of-linear-logic.dvi +\reference{Philip Wadler} +{A taste of linear logic} +{{\em Mathematical Foundations of Computer Science}, +Gdansk, Poland, August 1993, Springer Verlag, LNCS 711} +{This tutorial paper provides an introduction to intuitionistic logic +and linear logic, and shows how they correspond to type systems for +functional languages via the notion of `Propositions as Types'. The +presentation of linear logic is simplified by basing it on the Logic +of Unity. An application to the array update problem is briefly +discussed. +} + +% It's in +% /local/grasp/docs/short-static-semantics/new-paper/kevins-latest-version + +\reference{Cordelia Hall, Kevin Hammond, Simon Peyton Jones and Philip Wadler} +{Type classes in Haskell} +{European Symposium on Programming, 1994} +{ +This paper defines a set of type inference rules for resolving +overloading introduced by type classes. Programs including type +classes are transformed into ones which may be typed by the +Hindley-Milner inference rules. In contrast to other work on type +classes, the rules presented here relate directly to user programs. +An innovative aspect of this work is the use of second-order lambda +calculus to record type information in the program. +} + +\reference{PL Wadler} +{Monads and composable continuations} +{Lisp and Symbolic Computation 7(1)} +{Moggi's use of monads to factor semantics is used to model the +composable continuations of Danvy and Filinski. This yields some +insights into the type systems proposed by Murthy and by Danvy and +Filinski. Interestingly, modelling some aspects of composable +continuations requires a structure that is almost, but not quite, a +monad. +} + +\reference{J Launchbury and SL Peyton Jones} +{Lazy Functional State Threads} +{Programming Languages Design and Implementation, Orlando, June 1994} +{ +Some algorithms make critical internal use of updatable state, even +though their external specification is purely functional. Based on +earlier work on monads, we present a way of securely encapsulating +such stateful computations, in the context of a non-strict, +purely-functional language. + +There are two main new developments in this paper. First, we show how +to use the type system to securely encapsulate stateful computations, +including ones which manipulate multiple, named, mutable objects. +Second, we give a formal semantics for our system. + +FTP: {\tt pub/glasgow-fp/papers/state.ps.Z} +} + +\reference{K Hammond, JS Mattson Jr. and SL Peyton Jones} +{Automatic spark strategies and granularity for a parallel functional language reducer} +{CONPAR, Sept 1994} +{ +This paper considers the issue of dynamic thread control in the context +of a parallel Haskell implementation on the GRIP multiprocessor. +For the first time we report the effect of our thread control strategies +on thread granularity, as measured by dynamic heap allocation. This +gives us a concrete means of measuring the effectiveness of these strategies, +other than wall-clock timings which are notoriously uninformative. + +FTP: {\tt pub/glasgow-fp/papers/spark-strategies-and-granularity.ps.Z} +} + +\reference{K Hammond} +{Parallel Functional Programming: an Introduction} +{PASCO '94, Sept. 1994 (Invited Paper)} + +This paper introduces the general area of parallel functional +programming, surveying the current state of research and suggesting +areas which could profitably be explored in the future. No new +results are presented. The paper contains 97 references selected from +the 500 or so publications in this field. + +FTP: {\tt pub/glasgow-fp/papers/parallel-introduction.ps.Z} + +% \section{Workshop papers and technical reports} + +% The 1994 Glasgow Functional Programming Workshop papers exist in +% the draft proceedings at the moment. They are being refereed, and will +% be published by Springer Verlag in due course. + +\end{document} + + + + + diff --git a/ghc/docs/abstracts/before90.tex b/ghc/docs/abstracts/before90.tex new file mode 100644 index 0000000000..ae3d95d600 --- /dev/null +++ b/ghc/docs/abstracts/before90.tex @@ -0,0 +1,471 @@ +\documentstyle[11pt,slpj]{article} + +\newcommand{\reference}[4]{ % authors, title, details, abstract +\large +#1, {\em #2}, #3. +\normalsize +\begin{quotation} +#4 +\end{quotation} +\vspace{0.2in} +} + +\newcommand{\Haskell}[1]{{\sc Haskell}} + +\begin{document} + +\title{Abstracts of GRIP/GRASP-related papers and reports before 1990\\ +Dept of Computing Science \\ +University of Glasgow G12 8QQ} + +\author{ +Cordelia Hall (cvh@cs.glasgow.ac.uk) \and +Kevin Hammond (kh@cs.glasgow.ac.uk) \and +Will Partain (partain@cs.glasgow.ac.uk) \and +Simon L Peyton Jones (simonpj@cs.glasgow.ac.uk) \and +Phil Wadler (wadler@cs.glasgow.ac.uk) +} + +\maketitle + +\begin{abstract} +We present a list of papers and reports related to the GRIP +and GRASP projects, +covering {\em the design, compilation technology, +and parallel implementations of functional programming languages, especially +\Haskell{}}. + +Most of them can be obtained by writing to +Teresa Currie, Dept of Computing Science, +University of Glasgow G12 8QQ, UK. Her electronic mail address is +teresa@uk.ac.glasgow.cs. + +Those marked ($\spadesuit$) can be obtained from the School of Information +Systems, University of East Anglia, Norwich, UK. +\end{abstract} + +\section{Published papers} +%Nov +\reference{Cordelia Hall and David Wise} +{Generating Function Versions with Rational Strictness Patterns} +{Science of Computer Programming 12 (1989)} +{Expression evaluation in lazy applicative languages is usually implemented +by an expensive mechanism requiring time and space which may be wasted +if the expression eventually needs the values anyway. Strictness analysis, +which has been successfully applied to flat domains and higher order functions, +is used here to annotate programs in a first order language containing +lazy list constructors so that they retain their original behavior, but +run more efficiently. In practice, the strictness in fields within these +constructors often follows regular patterns that can be finitely +represented, especially in programs that manipulate such useful structures +as finite or infinite trees. The approach presented here typically generates +efficient, mutually recursive function versions for these programs. +Weak and strong safety are defined and discussed, and the compiler +is shown to be weakly safe. Termination is guaranteed by several factors, +including a finite resource which controls the increase in code size, +and a regularity constraint placed upon the strictness patterns +propagated during compilation.} + +\reference{Kevin Hammond} +{Exception Handling in a Parallel Functional Language: PSML} +{Proc TENCON '89, Bombay, India, Nov 1989} +{ +Handling exception occurrences during computation is a problem in most +functional programming languages, even when the computation is eager and +sequential. This paper presents a version of the error value method +which allows lazy computation with deterministic semantics for parallel +evaluation even in the presence of errors. The realisation of this +technique is illustrated by reference to PSML, a referentially +transparent variant of Standard ML designed for parallel evaluation. +} + +\reference +{Phil Trinder and Philip Wadler} +{Improving list comprehension database queries} +{{\em TENCON '89\/} (IEEE Region 10 Conference), +Bombay, India, November 1989.} +{ +The task of increasing the efficiency of database queries has recieved +considerable attention. In this paper we describe the improvement of +queries expressed as list comprehensions in a lazy functional +language. The database literature identifies four algebraic and two +implementation-based improvement strategies. For each strategy we show +an equivalent improvement for queries expressed as list +comprehensions. This means that well-developed database algorithms +that improve queries using several of these strategies can be emulated +to improve comprehension queries. We are also able to improve queries +which require greater power than that provided by the relational +algebra. Most of the improvements entail transforming a simple, +inefficient query into a more complex, but more efficient form. We +illustrate each improvement using examples drawn from the database +literature. +} + +%Sept + + +\reference{Simon L Peyton Jones and Jon Salkild} +{The Spineless Tagless G-machine} +{Proc IFIP Symposium on Functional Programming Languages and Computer +Architecture, London, Sept 1989} +{ +The Spineless Tagless G-machine is an abstract machine based on graph +reduction, designed as a target for compilers for non-strict functional +languages. +As its name implies, it is a development of earlier work, especially +the G-machine and Tim. + +It has a number of unusual features: the abstract machine code is +rather higher-level than is common, allowing better code generation; +the representation of the graph eliminates most interpretive overheads; +vectored returns from data structures give fast case-analysis; +and the machine is readily extended for a parallel implementation. + +The resulting implementation runs at least 75\% faster +than the Chalmers G-machine. +} + +\reference +{Philip Wadler} +{Theorems for free!} +{{\em 4'th International Conference on Functional Programming +Languages and Computer Architecture}, London, September 1989.} +{ +From the type of a polymorphic function we can derive a theorem +that it satisfies. Every function of the same type satisfies the same +theorem. This provides a free source of useful theorems, +courtesy of Reynolds' abstraction theorem for the polymorphic lambda +calculus. +} + +%Aug + +\reference{Kevin Hammond} +{Implementing Type Classes for Haskell} +{Proc Glasgow Workshop on Functional Programming, Fraserburgh, Aug 1989} +{ +This paper describes the implementation of the type class mechanism for +the functional language Haskell, which has been undertaken at Glasgow +University. A simple introduction to type classes discusses the methods +used to select operators and dictionaries in the Glasgow Haskell +compiler. A solution to the problem of selecting super-class +dictionaries, not considered by the original paper on type class, is +also presented. The modifications which must be made to the standard +Hindley/Milner type-checking algorithm to permit the translation of +operators are described, and a revised definition of algorithm W is +provided. Finally, a set of performance figures compares the run-time +efficiency of Haskell and LML programs, indicating the overhead inherent +in the original, naive method of operator selection, and the improvement +which may be obtained through simple optimisations. +} + +\reference{Simon L Peyton Jones} +{FLIC - a functional language intermediate code} +{SIGPLAN Notices 23(8) 1988, revised 1989} +{ +FLIC is a Functional Language Intermediate Code, intended to +provide a common intermediate language between diverse +implementations of functional languages, including parallel +ones. +This paper gives a formal definition of FLIC's syntax and +semantics, in the hope that its existence may encourage greater +exchange of programs and benchmarks between research groups. +} + +%July +\reference{Simon L Peyton Jones, Chris Clack and Jon Salkild} +{High-performance parallel graph reduction} +{Proc Parallel Architectures and Languages Europe (PARLE), LNCS 365, pp193-207, +July 1989} +{ +Parallel graph reduction is an attractive implementation for functional +programming languages because of its simplicity and inherently distributed +nature. +This paper outlines some of the issues raised by parallel compiled +graph reduction, and presents the solutions we have adopted to produce an +efficient implementation. + +We concentrate on two particular issues: +the efficient control of parallelism, resulting in an ability to alter +the granularity of parallelism +{\em dynamically}; +and the efficient use of the memory hierachy to improve locality. +} +%April + +\reference{Simon L Peyton Jones} +{Parallel implementations of functional programming languages} +{Computer Journal 32(2), pp175-186, April 1989} +{ +It is now very nearly as easy to build a parallel computer +as to build a sequential one, and there are strong incentives to do so: +parallelism seems to offer the opportunity to improve both the +absolute performance level and the cost/performance ratio of our machines. + +One of the most attractive features of functional programming languages +is their suitability for programming such parallel computers. +This paper is devoted to a discussion of this claim. + +First of all, we discuss parallel functional programming +from the programmer's point of view. +Most parallel functional language implementations are based on graph reduction, +we proceed to a discussion of some implementation issues raised by parallel +graph reduction. +The paper concludes with a case study of a particular parallel graph reduction +machine, GRIP, and a brief survey of other similar machines. +} +%Jan +\reference +{Philip Wadler and Stephen Blott} +{How to make {\em ad-hoc\/} polymorphism less {\em ad hoc}} +{{\em 16'th ACM Symposium on Principles of Programming Languages}, +Austin, Texas, January 1989.} +{ +This paper presents {\em type classes}, a new approach to {\em +ad-hoc\/} polymorphism. Type classes permit overloading of arithmetic +operators such as multiplication, and generalise the ``eqtype variables'' +of Standard ML. +Type classes extend the Hindley\X Milner polymorphic type system, and +provide a new approach to issues that arise in object-oriented +programming, bounded type quantification, and abstract data types. +This paper provides an informal introduction to type classes, and +defines them formally by means of type inference rules. +} +%88 + +\reference{Chris Hankin, Geoffrey Burn, and Simon L Peyton Jones} +{A safe approach to parallel combinator reduction} +{Theoretical Computer Science 56, pp17-36, North Holland, 1988} +{ +In this paper we present the results of two pieces of work which, when +combined, allow us to take a program text of a functional langauge and +produce a parallel implementation of that program. +We present the techniques for discovering sources of parallelism in +a program at compile time, and then show how this parallelism is +naturally mapped onto a parallel combinator set that we will define. + +To discover sources of parallelism in a program, we use +{\em abstract interpretation} a compile-time technique which is used +to gain information about a program which may then be used to optimise +the program's execution. +A particular use of abstract interpretation is in +{\em strictness analysis} +of functional program. +In a language that has lazy semantics, the main potential for parallelism +arises in the evaluation of arguments of strict operators. + +Having identified the sources of parallelism at compile time, it is +necessary to communicate these to the run-time system. +In the second part of the paper we introduce an extended set of combinators, +including some parallel combinators, to achieve this purpose. +} + + +\reference{John T. O'Donnell and Cordelia Hall} +{Debugging in Applicative Languages} +{Lisp and Symbolic Computation, 1988} +{Applicative programming languages have several properties that appear +to make debugging difficult. First, the absence of assignment +statements complicates the notion of changing a program while +debugging. Second, the absence of imperative input and output +makes it harder to obtain information about what the program is doing. +Third, the presence of lazy evaluation prevents the user from +knowing much about the order in which events occur. Some solutions to +these problems involve nonapplicative extensions to the language. +Fortunately, the same features of applicative languages that cause +problems for traditional debugging also support an idiomatic +applicative style of programming, and effective debugging techniques +can be implemented using that style. This paper shows how to implement +tracing and interactive debugging tools in a purely applicative +style. This approach is more flexible, extensive and portable +than debugging tools that require modification to the language +implementation.} + +\reference{Simon L Peyton Jones, Chris Clack, Jon Salkild, Mark Hardie} +{Functional programming on the GRIP multiprocessor} +{Proc IEE Seminar on Digital Parallel Processors, Lisbon, Portugal, 1988} +{ +Most MIMD computer architectures can be classified as +tightly-coupled or loosely-coupled, +depending on the relative latencies seen by a processor accessing different +parts of its address space. + +By adding microprogrammable functionality to the memory units, we have +developed a MIMD computer architecture which explores the middle region +of this spectrum. +This has resulted in an unusual and flexible bus-based multiprocessor, +which we are using as a base for our research in parallel functional programming +languages. + +In this paper we introduce parallel functional programming, and describe +the architecture of the GRIP multiprocessor. +} + +\reference{Geoffrey Burn, Simon L Peyton Jones, and John Robson} +{The spineless G-machine} +{Proc ACM Conference on Lisp and Functional Programming, Snowbird, pp244-258, +August 1988} +{ +Recent developments in functional language implementations have +resulted in the G-machine, a programmed graph-reduction machine. +Taking this as a basis, we introduce an optimised method of +performing graph reduction, which does not need to build the +spine of the expression being reduced. +This Spineless G-machine only updates shared expressions, and +then only when they have been reduced to weak head normal form. +It is thus more efficient than the standard method of performing +graph reduction. + +We begin by outlining the philosophy and key features of the +Spineless G-machine, and comparing it with the standard +G-machine. +Simulation results for the two machines are then presented and +discussed. + +The Spineless G-machine is also compared with Tim, giving a +series of transformations by which they can be interconverted. +These open up a wide design space for abstract graph reduction +machines, which was previously unknown. + +A full specification of the machine is given in the appendix, +together with compilation rules for a simple functional language. +} +%87 + +\reference{Simon L Peyton Jones and Chris Clack} +{Finding fixpoints in abstract interpretation} +{in Abstract Interpretation of Declarative Languages, +ed Hankin \& Abramsky, Ellis Horwood, pp246-265, 1987.} +{ +Abstract interpretation is normally used as the basis for +a static, compile-time analysis of a program. +For example, strictness analysis attempts to establish which +functions in the program are strict (we will use strictness +analysis as a running example). + +Using abstract interpretation in this way requires the +compile-time evaluation of expressions in the abstract domain. +It is obviously desirable that this evaluation should +always terminate, since otherwise the compiler would risk +non-termination. +In the case of non-recursive functions there is no problem, and +termination is guaranteed. +Recursive functions, however, present more of a problem, and it +is the purpose of this paper to explain the problem and to +offer some practical solutions. +} + +\reference{Simon L Peyton Jones} +{GRIP - a parallel processor for functional languages} +{Electronics and Power, pp633-636, Oct 1987; +also in ICL Technical Journal 5(3), May 1987} +{ +A brief 4-page article about the GRIP architecture. +} + +\reference{Simon L Peyton Jones, Chris Clack, Jon Salkild, and Mark Hardie} +{GRIP - a high-performance architecture for parallel graph reduction} +{Proc IFIP conference on Functional Programming Languages and +Computer Architecture, Portland, +ed Kahn, Springer Verlag LNCS 274, pp98-112, Sept 1987} +{ +GRIP is a high-performance parallel machine designed to execute +functional programs using supercombinator graph reduction. +It uses a high-bandwidth bus to provide access to a +large, distributed shared memory, using intelligent memory units and +packet-switching protocols to increase the number of processors +which the bus can support. +GRIP is also being programmed to support parallel Prolog and +DACTL. + +We outline GRIP's architecture and firmware, discuss the major design +issues, and describe the current state of the project and +our plans for the future. +} +%86 +\reference{Chris Clack and Simon L Peyton Jones} +{The four-stroke reduction engine} +{Proc ACM Conference on Lisp and Functional Programming, +Boston, pp220-232, Aug 1986} +{ +Functional languages are widely claimed to be amenable to concurrent +execution by multiple processors. This paper presents an algorithm for +the parallel graph reduction of a functional program. +The algorithm supports transparent management of parallel +tasks with no explicit +communication between processors. +} + +\reference{Simon L Peyton Jones} +{Functional programming languages as a software engineering tool} +{in Software Engineering - the critical decade D Ince, +Peter Peregrinus, pp124-151, 1986} +{ +It is the purpose of this paper to suggest that functional +languages are an appropriate tool for supporting the activity +of programming in the large, and to present a justification of +this claim. +} + +\reference{Simon L Peyton Jones} +{Using Futurebus in a fifth generation computer architecture} +{Microprocessors and Microsystems 10(2), March 1986} +{ +Despite the bandwidth limitations of a bus, we present a design +for a parallel computer (GRIP) based on Futurebus, which limits bus +bandwidth requirements by using intelligent memories. + +Such a machine offers higher performance than a uniprocessor +and lower cost than a more extensible multiprocessor, as well +as serving as a vehicle for research in parallel architectures. +} + +\section{Internal reports} + + +\reference{Kevin Hammond} +{A Proposal for an Implementation of Full Dactl on a Meiko Transputer Rack} +{SYS-C89-02, University of East Anglia, 1989} +{ +The design of an abstract machine instruction set for Dactl is +described. The instruction set is sufficient to encapsulate all Dactl +constructs; it will also permit parallel execution where applicable. +The paper considers the difficulties involved in the implementation of +this abstract instruction set on the UEA Meiko M40 transputer rack, +using a ZAPP-style kernel. Part of the code for a simulation of this +instruction set is included as an appendix to the report. +} + + +\reference{Kevin Hammond and John Glauert} +{Implementing Pattern-Matching Functional Languages using Dactl} +{University of Glasgow, 1989} +{ +This paper describes the implementation of a family of pattern-matching +functional languages in the parallel graph-rewriting language Dactl. +Attention is focussed on the direct implementation of the +pattern-matching constructs in the context of various reduction +strategies: eager, lazy, and lazy with strictness analysis. Two new +reduction strategies combining lazy evaluation with a technique for +compiling non-overlapping patterns are also illustrated. The latter +strategies provide improved termination properties compared with +conventional functional language implementations for non-overlapping +patterns. The implementations described here cover all pattern-matching +constructs found in Standard ML, including named patterns and deep +patterns. The use of Dactl renders explicit the complexities of +pattern-matching which are obscured by implementation in a conventional +intermediate language or abstract machine. +} + +\reference{Simon L Peyton Jones} +{A practical technique for designing asynchronous finite-state machines} +{Proc Glasgow Workshop on Functional Programming, Fraserburgh,Aug 1989} +{ +The literature on asynchronous logic design is mostly of a fairly theoretical +nature. We present a practical technique for generating asynchronous finite-state +machines from a description of their states and transitions. The technique +has been used successfully to design a number of state machines in +the GRIP mulitprocessor. +} + +\end{document} diff --git a/ghc/docs/abstracts/reports.tex b/ghc/docs/abstracts/reports.tex new file mode 100644 index 0000000000..fc8a332900 --- /dev/null +++ b/ghc/docs/abstracts/reports.tex @@ -0,0 +1,111 @@ +\documentstyle[11pt,slpj]{article} + +\newcommand{\reference}[4]{ % authors, title, details, abstract +\large +#1, {\em #2}, #3. +\normalsize +\begin{quotation} +#4 +\end{quotation} +\vspace{0.2in} +} + +\newcommand{\Haskell}[1]{{\sc Haskell}} + +\begin{document} + +\title{Abstracts of GRIP/GRASP-related design documents and manuals \\ +Dept of Computing Science \\ +University of Glasgow G12 8QQ} + +\author{ +Cordelia Hall (cvh@cs.glasgow.ac.uk) \and +Kevin Hammond (kh@cs.glasgow.ac.uk) \and +Will Partain (partain@cs.glasgow.ac.uk) \and +Simon L Peyton Jones (simonpj@cs.glasgow.ac.uk) \and +Phil Wadler (wadler@cs.glasgow.ac.uk) +} + +\maketitle + +\begin{abstract} +This list covers internal design documents and manuals for the GRIP +and GRASP projects. +They are mainly intended for internal consumption, or for brave friends. + +Reports and papers designed for more general consumption are given in +a separate list. + +They of them can be obtained by writing to +Teresa Currie, Dept of Computing Science, +University of Glasgow G12 8QQ, UK. Her electronic mail address is +teresa@uk.ac.glasgow.cs. +\end{abstract} + + +\section{Manuals, design documents and guides} + +\reference{Kevin Hammond and Simon L Peyton Jones} +{Mail server guide} +{Nov 1990} +{ +A guide to the GRIP Mail Server +} + +\reference{Kevin Hammond, Simon L Peyton Jones and Jon Salkild} +{GLOS 2.0 - The GRIP Lightweight Operating System} +{University College London, January 1989} +{ +GLOS is a lightweight multitasking non-preemptive operating +for the GRIP multiprocessor. +This paper describes the operating system from the programmer's point of +view. +} + +\reference{Simon L Peyton Jones and Jon Salkild} +{GRIP system user manual} +{University College London, January 1989} +{ +This document describes how to configure, boot and run the GRIP system, +using the sys2 system mangement program. +} + +\reference{Simon L Peyton Jones} +{The BIP front panel user manual} +{University College London, January 1989} +{ +This document describes {bsim} the program which runs on the GRIP host +Unix machine, and provides a front-panel interface to the BIP. +It assumes familiarity with the BIP architecture. +} + +\reference{Chris Clack} +{The GRIP Intelligent Memory Unit microprogrammer's guide} +{University College London, January 1989} +{ +This paper encapsulates the spectrum of knowledge required to microprogram +the GRIP Intelligent Memory Units (IMUs). It gives a detailed +description of the IMU hardware and its microassembler, together with +the library of predefined microcode macros. +An overview of the the Bus Interface +Processor (BIP) hardware and its interface protocols is also provided. +} + +\reference{Chris Clack} +{Diagnostic control and simulation of GRIP Intelligent Memory Units - the +msH user guide} +{University College London, January 1989} +{ +Software has been written to facilitate interaction with the diagnostic +hardware embedded in each GRIP Intelligent Memory Unit (IMU). +The msS program precisely emulates an IMU, and can be used to help +debug IMU microcode in the absence of real hardware. +The msH program interfaces directly to the actual hardware. +Both msS and msH are driven by the same interactive front panel, which +both acts a command interpreter and manages the display screen. + +The paper is mainly concerned with a description of the front-panel and +how to use it, but also gives a brief overview of the IMU architecture. +} + +\end{document} diff --git a/ghc/docs/abstracts/slpj.sty b/ghc/docs/abstracts/slpj.sty new file mode 100644 index 0000000000..9027eabbd4 --- /dev/null +++ b/ghc/docs/abstracts/slpj.sty @@ -0,0 +1,41 @@ +% Style file for Simon's documents + +\batchmode +\sloppy + +%**************************************************************** +%* * +%* Page and paragraph format * +%* * +%**************************************************************** + +% Margins and page layout + +\input{a4wide.sty} + +%\setlength{\topmargin}{-1cm} +%\setlength{\oddsidemargin}{-0.5cm} +%\setlength{\evensidemargin}{-0.5cm} +%\setlength{\headheight}{0cm} +%\setlength{\headsep}{0cm} +%\setlength{\textwidth}{17cm} +%\setlength{\textheight}{23.5cm} + +\setlength{\marginparwidth}{1.5cm} + +% Block paragraphs + +\setlength{\parskip}{0.25cm} +\setlength{\parsep}{0.25cm} +\setlength{\topsep}{0cm} % Reduces space before and after verbatim, + % which is implemented using trivlist +\setlength{\parindent}{0cm} + +\renewcommand{\textfraction}{0.2} +\renewcommand{\floatpagefraction}{0.7} + + +\input{useful.sty} + + + diff --git a/ghc/docs/abstracts/useful.sty b/ghc/docs/abstracts/useful.sty new file mode 100644 index 0000000000..bc901a359a --- /dev/null +++ b/ghc/docs/abstracts/useful.sty @@ -0,0 +1,186 @@ +%**************************************************************** +%* * +%* GENERALLY USEFUL MACROS * +%* * +%**************************************************************** + + +%**************************************************************** +%* * +%* Some standard abbreviations * +%* * +%**************************************************************** + +% Haskell name +\newcommand{\Haskell}[1]{Haskell} + +% \ba \ea: Abbreviations for begin and end array +% +\newcommand{\ba}{\begin{array}} +\newcommand{\ea}{\end{array}} + + +%**************************************************************** +%* * +%* Keeping text together * +%* * +%**************************************************************** + +% Use \begin{together} (or \bt) +% \end{together} (or \et) +% +% to keep a paragraph together on a single page. + +\newenvironment{together}% + {\begin{flushleft}\begin{minipage}{\textwidth}}% + {\end{minipage}\end{flushleft}} + +\newcommand{\bt}{\begin{together}} +\newcommand{\et}{\end{together}} + + +%**************************************************************** +%* * +%* ToDo macro (cf showtodo.sty) * +%* * +%**************************************************************** + +\newcommand{\ToDo}[1]{} + + +%**************************************************************** +%* * +%* Making boxes round things * +%* * +%**************************************************************** + +% \outline{text} typesets text in a centred framed box of the width +% of the page. +% +\newcommand{\outline}[1]{ + \begin{center} + \fbox{ + \begin{minipage}{\linewidth} + #1 + \end{minipage} + } + \end{center} +} + +%**************************************************************** +%* * +%* Math codes * +%* * +%**************************************************************** + +% The mathcodes for the letters A, ..., Z, a, ..., z are changed to +% generate text italic rather than math italic by default. This makes +% multi-letter identifiers look better. The mathcode for character c +% is set to "7000 (variable family) + "400 (text italic) + c. +% + + +% Old Latex +% +%\def\@setmcodes#1#2#3{{\count0=#1 \count1=#3 +% \loop \global\mathcode\count0=\count1 \ifnum \count0<#2 +% \advance\count0 by1 \advance\count1 by1 \repeat}} +% +%\@setmcodes{`A}{`Z}{"7441} +%\@setmcodes{`a}{`z}{"7461} + + +% Should work with Latex 3.0 +% +%{\catcode`\= 11 +% \gdef\mathrm{\use@mathgroup \=cmr \z@} +% %\gdef\mit{\use@mathgroup \=cmm \@ne} +% \gdef\mit{\use@mathgroup \=cmt \@ne} +% \gdef\cal{\use@mathgroup \=cmsy \tw@} +% } + +\@ifundefined{selectfont} + {} + {\newmathalphabet{\textit} + \addtoversion{normal}{\textit}{cmr}{m}{it} + \addtoversion{bold}{\textit}{cmr}{bx}{it} + \everymath{\textit} + \everydisplay{\textit} + } + +%**************************************************************** +%* * +%* Definitions for macros used in figures * +%* These are produced by fig2dev, so we need defns for them * +%* * +%**************************************************************** + +% These ones work for 11-pt typesetting + +\@ifundefined{selectfont} %DL is MS scheme present? +{}{ +\def\fiverm{\rm\tiny} % Five pt +\def\sevrm{\rm\scriptsize} % Seven pt + +\def\nintt{\tt\footnotesize} +\def\ninrm{\rm\footnotesize} + +\def\tenrm{\rm\small} % Ten pt +\def\tentt{\tt\small} % Ten pt + +\def\elvrm{\rm\normalsize} % Eleven pt +\def\elvit{\em\normalsize} + +\def\twlbf{\bf\large} % Twelve pt +\def\twlit{\em\large} +\def\twltt{\tt\large} +\def\twlrm{\rm\large} +\def\twfvtt{\tt\large} + +\def\frtnrm{\rm\Large} % Fourteen pt +\def\frtnbf{\bf\Large} +\def\frtnit{\em\Large} +\def\frtntt{\tt\Large} + +\def\svtnsf{\sf\huge} % Seventeen pt + + +% cant remember why I need these +\def\egt{\size{8}{9} } +\def\elv{\size{11}{12} } +\def\five{\size{5}{7} } +\def\fiv{\size{5}{6} } +\def\frtn{\size{14}{15} } +\def\nin{\size{9}{10} } +\def\sev{\size{7}{8} } +\def\six{\size{6}{7} } +\def\svtn{\size{17}{18} } +\def\ten{\size{10}{11} } +\def\twfv{\size{25}{27} } +\def\twl{\size{12}{14} } +\def\twty{\size{20}{22} } +} + +%**************************************************************** +%* * +%* Useful symbols * +%* * +%**************************************************************** + + +% Semantic brackets +% +% \leftsembrac [[ left semantic bracket +% \rightsembrac ]] right semantic bracket +% \sembrac{x} [[x]] enclose arg in semantic brackets +% \semfun{E}{x} E[[x]] make E curly +% +\newcommand{\leftsembrac}{[\![} +\newcommand{\rightsembrac}{]\!]} +\newcommand{\sembrac}[1]{\leftsembracb#1\rightsembrac} +\newcommand{\semfun}[2]{{\cal #1}\db{#2}\,} + +% \plusplus ++ run together +% +\def\plusplus{\mathrel{+\!\!\!+}} + diff --git a/ghc/docs/add_to_compiler/Jmakefile b/ghc/docs/add_to_compiler/Jmakefile new file mode 100644 index 0000000000..ec85333bc6 --- /dev/null +++ b/ghc/docs/add_to_compiler/Jmakefile @@ -0,0 +1,22 @@ +/* this is a standalone Jmakefile; NOT part of ghc "make world" */ + +DocProcessingSuffixRules() + +SRCS_VERB = \ + paper.verb \ + state-of-play.verb \ + overview.verb \ + overview-fig.verb \ + front-end.verb \ + back-end.verb \ + core-syntax.verb \ + core-summary-fig.verb \ + stg-summary-fig.verb \ + howto-add.verb +SRCS_TEX = $(SRCS_VERB:.verb=.tex) + +docs:: paper.dvi + +paper.dvi: $(SRCS_TEX) + +ExtraStuffToClean( $(SRCS_TEX) ) diff --git a/ghc/docs/add_to_compiler/back-end.verb b/ghc/docs/add_to_compiler/back-end.verb new file mode 100644 index 0000000000..2e61e5aa2f --- /dev/null +++ b/ghc/docs/add_to_compiler/back-end.verb @@ -0,0 +1,41 @@ +%************************************************************************ +%* * +\subsection{The back end of the compiler} +\label{sec:back-end} +%* * +%************************************************************************ + +The back end of the compiler begins once the typechecker's +output has been desugared into the so-called Core syntax. Core syntax +is discussed in Section~\ref{sec:core-syntax}. + +We intend the back end to be a sequence of highly effective +CoreSyntax-to-CoreSyntax and STGsyntax-to-STGsyntax transformation +passes, making it possible for the +CoreSyntax$\Rightarrow$StgSyntax$\Rightarrow$Abstract~C (and on to +machine code) denouement to produce really good code. + +{\em It is with these transformation passes that we are hoping for +your enthusiastic help!} There are also some examples in the +GHC distribution, written by people other than the original compiler +authors---so it can be done... + +We already have a pretty good {\em simplifier}\srcloc{simplCore/} to +do local transformations, written mainly by Andr\'e Santos. Among +other things, it unfolds basic arithmetic operations and constants, +exposing the underlying unboxed values. Those interested in the +merits of these transformations should consult Peyton Jones and +Launchbury's paper, ``Unboxed values as first class citizens in a +non-strict functional language'' \cite{peyton-jones91b}. + +The reader interested in the final code-generation parts of the +compiler, from Core syntax to STG syntax\srcloc{stgSyn/CoreToStg.lhs} +to Abstract~C,\srcloc{codeGen/} should consult Peyton Jones's recent +paper, ``Implementing lazy functional languages on stock hardware: the +Spineless Tagless G-machine'' \cite{peyton-jones92a}. + +Further note: We have found that the STG +syntax\srcloc{stgSyn/StgSyn.lhs} is the better medium for a few +transformations.\srcloc{stgSyn/SimplStg.lhs} This is fine---STG syntax +is a just-as-manipulable functional language as Core syntax, even if +it's a bit messier. diff --git a/ghc/docs/add_to_compiler/core-summary-fig.verb b/ghc/docs/add_to_compiler/core-summary-fig.verb new file mode 100644 index 0000000000..7e339ea8a0 --- /dev/null +++ b/ghc/docs/add_to_compiler/core-summary-fig.verb @@ -0,0 +1,45 @@ +\begin{figure} \fbox{ +$\begin{array}{lrcll} +%\\ +%\mbox{Program} & program & \rightarrow & binds & \\ +%\\ +\mbox{Bindings} & binds & \rightarrow & bind_1@;@ \ldots @;@~bind_n & n \geq 1 \\ + & bind & \rightarrow & @nonrec@~ var ~@=@~ expr \\ + && | & @rec@~ var_1 ~@=@~ expr_1 @;@ \ldots @;@~ var_n ~@=@~ expr_n & n \geq 1 \\ +\\ +\mbox{Expression} & expr + & \rightarrow & expr_1 ~ expr_2 & \mbox{Application} \\ + && | & expr ~ type & \mbox{Type application} \\ + && | & @\@~ var~ @->@ ~ expr & \mbox{Lambda abstraction} \\ + && | & @/\@~ tyvar~ @->@ ~ expr & \mbox{Type abstraction} \\ + && | & @case@ ~expr~ @of@ ~ alts & \mbox{Case expression} \\ + && | & @let@~ bind ~@in@~ expr & \mbox{Local definition(s)} \\ + && | & con~expr_1 \ldots expr_n & \mbox{Saturated constructor} \\ + && | & prim~expr_1 \ldots expr_n & \mbox{Saturated primitive} \\ + && | & var & \mbox{Variable} \\ + && | & literal & \\ +\\ +\mbox{Alternatives} & alts & \rightarrow + & calt_1@;@ \ldots @;@~calt_n@; default ->@~ expr + & n \geq 0~\mbox{(Boxed)} \\ + && | & lalt_1@;@ \ldots @;@~lalt_n@;@~var ~@->@~ expr + & n \geq 0~\mbox{(Unboxed)} \\ +\\ +\mbox{Constructor alt} + & calt & \rightarrow & con~var_1 \ldots var_n~@->@~expr & n \geq 0 \\ +\mbox{Literal alt} + & lalt & \rightarrow & literal~@->@~expr & \\ +\\ +\mbox{Literals} & literal + & \rightarrow & integer & \mbox{machine-level numbers} \\ + && | & \ldots & \\ +\\ +\mbox{Primitives} & prim + & \rightarrow & @+@ ~|~ @-@ ~|~ @*@ ~|~ @/@ & \mbox{machine-level ops} \\ + && | & \ldots & \\ +\\ +\end{array}$ +} +\caption{Abstract syntax of the Core language} +\label{fig:core-syntax} +\end{figure} diff --git a/ghc/docs/add_to_compiler/core-syntax.verb b/ghc/docs/add_to_compiler/core-syntax.verb new file mode 100644 index 0000000000..11b80d0ffd --- /dev/null +++ b/ghc/docs/add_to_compiler/core-syntax.verb @@ -0,0 +1,142 @@ +%************************************************************************ +%* * +\section{Core syntax, and transformations on it} +\label{sec:core-syntax} +%* * +%************************************************************************ + +The @CoreSyntax@ datatype is intended to be the {\em lingua franca} of +the back end of the compiler; a summary is shown in +Figure~\ref{fig:core-syntax}. +\input{core-summary-fig} +As you can see, the Core syntax is a simple +functional language. + +\subsection{Second-order polymorphic lambda calculus} +\label{sec:second-order} + +Core syntax is essentially the second-order polymorphic lambda +calculus. This is reflected in the fact that Core expressions can be +{\em type applications} or {\em type abstractions} (the types in +question are represented as @UniTypes@, of course).\footnote{An +interesting point: there are Core-syntax programs that cannot be +written in Haskell! Core syntax +is the {\em more expressive} language. One could imagine writing a +front end (parser, etc.) for a richer programming language and still +being able to use this compiler's back-end machinery without change.} + +Having explicit type application and abstraction (NB: added by +the typechecker during translation) gives us a uniform, +well-understood, non-{\em ad hoc} way to express the types of +Core expressions. Given that variables (i.e., @Ids@) and other +basic entities have their types memoised in them, it is then easy to +work out the type of {\em any Core expression}. For example, in the +expression\ToDo{example here} +\begin{verbatim} +... <example to be supplied> ... +\end{verbatim} +@a@ is a type variable, @(<???>)@ is a type application, and, assuming +the type of @??@ is $some\ math\ mode\ here...$, then the type of the +expression is @...@. + +The truly great thing about using the second-order polymorphic lambda +calculus is that it is {\em easy to preserve types +in the face of transformation passes}, however drastic their mangling +of the original program. + +\ToDo{example here} + +\subsection{Parameterised and annotated Core syntax} +\label{sec:parameterised-core} + +As we saw with the ``abstract syntax'' (in +Section~\ref{sec:AbsSyntax}), the Core syntax is also {\em +parameterised}, this time with respect to binders and bound-variables +(or ``bindees''). The definition of a Core expression +begins:\srcloc{coreSyn/CoreSyn.lhs} +\begin{tightcode} +data CoreExpr binder bindee + = CoVar bindee + | CoLit CoreLiteral + ... +type PlainCoreBinder = Id +type PlainCoreBindee = Id +type PlainCoreExpr = CoreExpr PlainCoreBinder PlainCoreBindee +\end{tightcode} +Most back-end passes use the parameterisation shown above, namely +@PlainCoreExprs@,\srcloc{coreSyn/PlainCore.lhs} parameterised on @Id@ +for both binders and bindees. + +An example of a pass that uses a different parameterisation is +occurrence analysis,\srcloc{simplCore/OccurAnal.lhs} which gathers +up info about the {\em occurrences} of bound variables. It uses: +\begin{tightcode} +data BinderInfo {\dcd\rm-- various things to record about binders...} +type TaggedBinder tag = (Id, tag) +type TaggedCoreExpr tag = CoreExpr (TaggedBinder tag) Id + +substAnalyseExpr :: PlainCoreExpr -> TaggedCoreExpr BinderInfo +\end{tightcode} +The pass's expression-mangling function then has the unsurprising type +shown above. + +Core syntax has a ``twin'' datatype that is also sometimes useful: +{\em annotated} Core syntax.\srcloc{coreSyn/AnnCoreSyn.lhs} This is a +datatype identical in form to Core syntax, but such that every +``node'' of a Core expression can be annotated with some information +of your choice. As an example, the type of a pass that attaches a +@Set@ of free variables to every subexpression in a Core expression +might be:\srcloc{coreSyn/FreeVars.lhs} +\begin{tightcode} +freeVars :: PlainCoreExpr -> AnnCoreExpr Id Id (Set Id) + {\dcd\rm-- parameterised on binders, bindees, and annotation} +\end{tightcode} + +\subsection{Unboxing and other Core syntax details} +\label{sec:unboxing} + +One facet of the Core syntax summary in Figure~\ref{fig:core-syntax} +that may have caught your eye is the separation of case-alternatives +into those for boxed entities (ordinary data constructors) and unboxed +entities (real machine-level things). The ``literals'' and +``primitives'' mentioned there are also machine-level constructs. It +is for this reason that all applications of constructors and +primitives are {\em saturated}; what use, for example, is +a machine-level addition if you do not +have two arguments to feed to it? (Most machines do not offer curried +arithmetic in their hardware.) + +The handling of unboxed values in the back end of the compiler follows +the design described in the Peyton Jones/Launchbury paper on the +subject \cite{peyton-jones91b}. You, the enthusiastic optimiser, only +need to be aware that this is the ``level of discourse.'' You will +also probably want to be sure that your optimisations can take full +advantage of the explicitness of the unboxery. + +\subsection{``Core Lint''---your dear friend} +\label{sec:core-lint} + +ToDo ToDo + +% \subsection{STG syntax} +% \label{sec:stg-syntax} +% +% As mentioned earlier, the compiler converts Core syntax into ``STG +% syntax'' (named for the Spineless Tagless G-machine) before finally +% making its move into the dark world we call ``Abstract~C''. +% +% Figure~\ref{fig:stg-syntax} shows the STG syntax, +% \input{stg-summary-fig} +% mainly so that you can compare it with Core syntax. (It is at least +% conceivable that you might to perform your optimisation pass at this +% level.) +% +% STG syntax is a truly austere functional language. In places where +% Core syntax allows "exprs", STG syntax insists on "vars"---everything +% has been flattened out. Type information (abstractions and +% applications) have been thrown overboard. Other than that, STG syntax +% is the ``same'' as Core syntax, with some extra non-essential +% annotations on bindings: update flags and free-variable information. +% +% You will want to consult the revised Spineless Tagless G-machine paper +% \cite{peyton-jones92a} if you wish to spend any time in the STG world. diff --git a/ghc/docs/add_to_compiler/front-end.verb b/ghc/docs/add_to_compiler/front-end.verb new file mode 100644 index 0000000000..affd2fac95 --- /dev/null +++ b/ghc/docs/add_to_compiler/front-end.verb @@ -0,0 +1,304 @@ +%************************************************************************ +%* * +\subsection{The front end of the compiler} +\label{sec:front-end} +%* * +%************************************************************************ + +The previous section covered the main points about the front end of +the compiler: it is dominated by a ``renamer'' and a typechecker +working directly at the Haskell source level. In this section, we +will look at some basic datatypes used or introduced in the front +end---ones that you may see as input to your optimisation pass. + +\subsubsection{``Abstract syntax'', a source-level datatype} +\label{sec:AbsSyntax} + +As Figure~\ref{fig:overview} shows, the typechecker both reads and +writes a collection of datatypes we call ``Abstract syntax.'' +This is misleading in that what +goes into the typechecker is quite different from what comes out. + +Let's first consider this fragment of the abstract-syntax +definition,\srcloc{abstractSyn/HsExpr.lhs} for Haskell explicit-list +expressions (Haskell report, section~3.5 +\cite{hudak91a}):\nopagebreak[4] +\begin{tightcode} +data Expr var pat = + ... + | ExplicitList [Expr var pat] + | ExplicitListOut UniType [Expr var pat] + ... + +type ProtoNameExpr = Expr ProtoName ProtoNamePat +type RenamedExpr = Expr Name RenamedPat +type TypecheckedExpr = Expr Id TypecheckedPat +\end{tightcode} +an @ExplicitList@ appears only in typechecker input; an @ExplicitListOut@ +is the corresponding construct that appears +only in the output, with the inferred type information attached. + +The fragment above also shows how abstract syntax is {\em parameterised} +with respect to variables and patterns. The idea is the same for +both; let's just consider variables. + +The renamer converts @ProtoNameExprs@ (expressions with +@ProtoNames@\srcloc{basicTypes/ProtoName.lhs} as variables---little +more than just strings) into @RenamedExprs@, which have all naming sorted out +(using @Names@\srcloc{abstractSyn/Name.lhs}). A @Name@ is known to be +properly bound, isn't duplicated, etc.; it's known if it's bound to a +built-in standard-prelude entity. + +(The renamer also does dependency analysis, which is required to +maximise polymorphism in a Hindley-Milner type system.) + +The typechecker reads the @RenamedExprs@, sorts out the types, and +spits out @TypecheckedExprs@, with variables represented by +@Ids@\srcloc{basicTypes/Id.lhs}. You can find out just about anything +you want to know about a variable from its @Id@. + +To see what GHC makes of some Haskell, in a file @Foo.hs@, say: +try @ghc -noC -ddump-rn4 Foo.hs@, to see what comes out of the renamer [pass~4]; +try @ghc -noC -ddump-tc Foo.hs@, to see what comes out of the typechecker. + +\subsubsection{Basic datatypes in the compiler} + +None of the internal datatypes in the example just given are +particularly interesting except @Ids@.\srcloc{basicTypes/Id.lhs} A +program variable, which enters the typechecker as a string, emerges as +an @Id@. + +The important thing about @Id@---and the datatypes representing other +basic program entities (type variables, type constructors, classes, +etc.)---is that they often include {\em memoised} information that can +be used throughout the rest of the compiler. + +Let us take a cursory look at @Ids@, as a representative example of +these basic data types. (Don't be too scared---@Ids@ are the hairiest +entities in the whole compiler!) +Here we go: +\begin{tightcode}\codeallowbreaks{} +data Id + = Id Unique {\dcd\rm-- key for fast comparison} + UniType {\dcd\rm-- Id's type; used all the time;} + IdInfo {\dcd\rm-- non-essential info about this Id;} + PragmaInfo {\dcd\rm-- user-specified pragmas about this Id;} + IdDetails {\dcd\rm-- stuff about individual kinds of Ids.} +\end{tightcode} + +So, every @Id@ comes with: +\begin{enumerate} +\item +A @Unique@,\srcloc{basicTypes/Unique.lhs} essentially a unique +@Int@, for fast comparison; +\item +A @UniType@ (more on them below... section~\ref{sec:UniType}) giving the variable's +type---this is the most useful memoised information. +\item +A @PragmaInfo@, which is pragmatic stuff the user specified for +this @Id@; e.g., @INLINE@ it; GHC does not promise to honour these +pragma requests, but this is where it keeps track of them. +\item +An @IdInfo@ (more on {\em them} below... section~\ref{sec:IdInfo}), +which tells you all the extra things +that the compiler doesn't {\em have} to know about an @Id@, but it's jolly nice... +This corresponds pretty closely to the @GHC_PRAGMA@ cross-module info that you will +see in any interface produced using @ghc -O@. +An example of some @IdInfo@ +would be: that @Id@'s unfolding; or its arity. +\end{enumerate} + +Then the fun begins with @IdDetails@... +\begin{tightcode}\codeallowbreaks{} +data IdDetails + + {\dcd\rm---------------- Local values} + + = LocalId ShortName {\dcd\rm-- mentioned by the user} + + | SysLocalId ShortName {\dcd\rm-- made up by the compiler} + + {\dcd\rm---------------- Global values} + + | ImportedId FullName {\dcd\rm-- Id imported from an interface} + + | PreludeId FullName {\dcd\rm-- Prelude things the compiler ``knows'' about} + + | TopLevId FullName {\dcd\rm-- Top-level in the orig source pgm} + {\dcd\rm-- (not moved there by transformations).} + + {\dcd\rm---------------- Data constructors} + + | DataConId FullName + ConTag + [TyVarTemplate] ThetaType [UniType] TyCon + {\dcd\rm-- split-up type: the constructor's type is:} + {\dcd\rm-- $\forall~tyvars . theta\_ty \Rightarrow$} + {\dcd\rm-- $unitype_1 \rightarrow~ ... \rightarrow~ unitype_n \rightarrow~ tycon tyvars$} + + | TupleCon Int {\dcd\rm-- its arity} + + {\dcd\rm-- There are quite a few more flavours of {\tt IdDetails}...} +\end{tightcode} + +% A @ShortName@,\srcloc{basicTypes/NameTypes.lhs} which includes a name string +% and a source-line location for the name's binding occurrence; + +In short: everything that later parts of the compiler might want to +know about a local @Id@ is readily at hand. The same principle holds +true for imported-variable and data-constructor @Ids@ (tuples are an +important enough case to merit special pleading), as well as for other +basic program entities. Here are a few further notes about the @Id@ +fragments above: +\begin{itemize} +\item +A @FullName@\srcloc{basicTypes/NameTypes.lhs} is one that may be +globally visible, with a module-name as well; it may have been +renamed. +\item +@DataConKey@\srcloc{prelude/PrelUniqs.lhs} is a specialised +fast-comparison key for data constructors; there are several of these +kinds of things. +\item +The @UniType@ for @DataConIds@ is given in {\em two} ways: once, just as +a plain type; secondly, split up into its component parts. This is to +save frequently re-splitting such types. +\item +Similarly, a @TupleCon@ has a type attached, even though we could +construct it just from the arity. +\end{itemize} + +\subsubsection{@UniTypes@, representing types in the compiler} +\label{sec:UniType} + +Let us look further at @UniTypes@.\srcloc{uniType/} Their definition +is: +\begin{tightcode}\codeallowbreaks{} +data UniType + = UniTyVar TyVar + + | UniFun UniType {\dcd\rm-- function type} + UniType + + | UniData TyCon {\dcd\rm-- non-synonym datatype} + [UniType] + + | UniSyn TyCon {\dcd\rm-- type synonym} + [UniType] {\dcd\rm--\ \ unexpanded form} + UniType {\dcd\rm--\ \ expanded form} + + | UniDict Class {\dcd\rm-- for types with overloading} + UniType + + {\dcd\rm-- The next two are to do with universal quantification.} + | UniTyVarTemplate TyVarTemplate + + | UniForall TyVarTemplate + UniType +\end{tightcode} +When the typechecker processes a source module, it adds @UniType@ +information to all the basic entities (e.g., @Ids@), among other +places (see Section~\ref{sec:second-order} for more details). These +types are used throughout the compiler. + +The following example shows several things about @UniTypes@. +If a programmer wrote @(Eq a) => a -> [a]@, it would be represented +as:\footnote{The internal structures of @Ids@, +@Classes@, @TyVars@, and @TyCons@ are glossed over here...} +\begin{tightcode}\codeallowbreaks{} +UniForall {\dcd$\alpha$} + (UniFun (UniDict {\dcd\em Eq} (UniTyVar {\dcd$\alpha$})) + (UniFun (UniTyVarTemplate {\dcd$\alpha$}) + (UniData {\dcd\em listTyCon} + [UniTyVarTemplate {\dcd$\alpha$}]))) +\end{tightcode} +From this example we see: +\begin{itemize} +\item +The universal quantification of the type variable $\alpha$ is made explicit +(with a @UniForall@). +\item +The class assertion @(Eq a)@ is represented with a @UniDict@ whose +second component is a @UniType@---this +reflects the fact that we expect @UniType@ to be used in a stylized +way, avoiding nonsensical constructs (e.g., +@(UniDict f (UniDict g (UniDict h ...)))@). +\item +The ``double arrow'' (@=>@) of the Haskell source, indicating an +overloaded type, is represented by the usual +@UniFun@ ``single arrow'' (@->@), again in a stylized way. +This change reflects the fact that each class assertion in a +function's type is implemented by adding an extra dictionary argument. +\item +In keeping with the memoising tradition we saw with @Ids@, type +synonyms (@UniSyns@) keep both the unexpanded and expanded forms handy. +\end{itemize} + +\subsubsection{@IdInfo@: extra pragmatic info about an @Id@} +\label{sec:IdInfo} + +[New in 0.16.] All the nice-to-have-but-not-essential information +about @Ids@ is now hidden in the +@IdInfo@\srcloc{basicTypes/IdInfo.lhs} datatype. It looks something +like: +\begin{tightcode}\codeallowbreaks{} +data IdInfo + = NoIdInfo {\dcd\rm-- OK, we know nothing...} + + | MkIdInfo + ArityInfo {\dcd\rm-- its arity} + DemandInfo {\dcd\rm-- whether or not it is definitely demanded} + InliningInfo {\dcd\rm-- whether or not we should inline it} + SpecialisationInfo {\dcd\rm-- specialisations of this overloaded} + {\dcd\rm-- function which exist} + StrictnessInfo {\dcd\rm-- strictness properties, notably} + {\dcd\rm-- how to conjure up ``worker'' functions} + WrapperInfo {\dcd\rm-- ({\em informational only}) if an Id is} + {\dcd\rm-- a ``worker,'' this says what Id it's} + {\dcd\rm-- a worker for, i.e., ``who is my wrapper''} + {\dcd\rm-- (used to match up workers/wrappers)} + UnfoldingInfo {\dcd\rm-- its unfolding} + UpdateInfo {\dcd\rm-- which args should be updated} + SrcLocation {\dcd\rm-- source location of definition} +\end{tightcode} +As you can see, we may accumulate a lot of information about an Id! +(The types for all the sub-bits are given in the same place...) + +\subsubsection{Introducing dictionaries for overloading} + +The major novel feature of the Haskell language is its systematic +overloading using {\em type classes}; Wadler and Blott's paper is the +standard reference \cite{wadler89a}. + +To implement type classes, the typechecker not only checks the Haskell +source program, it also {\em translates} it---by inserting code to +pass around in {\em dictionaries}. These dictionaries +are essentially tuples of functions, from which the correct code may +be plucked at run-time to give the desired effect. Kevin Hammond +wrote and described the first working implementation of type +classes \cite{hammond89a}, and the ever-growing static-semantics paper +by Peyton Jones and Wadler is replete with the glories of dictionary +handling \cite{peyton-jones90a}. (By the way, the typechecker's +structure closely follows the static semantics paper; inquirers into +the former will become devoted students of the latter.) + +Much of the abstract-syntax datatypes are given +over to output-only translation machinery. Here are a few more +fragments of the @Expr@ type, all of which appear only in typechecker +output: +\begin{tightcode} +data Expr var pat = + ... + | DictLam [DictVar] (Expr var pat) + | DictApp (Expr var pat) [DictVar] + | Dictionary [DictVar] [Id] + | SingleDict DictVar + ... +\end{tightcode} +You needn't worry about this stuff: +After the desugarer gets through with such constructs, there's nothing +left but @Ids@, tuples, tupling functions, etc.,---that is, ``plain +simple stuff'' that should make the potential optimiser's heart throb. +Optimisation passes don't deal with dictionaries explicitly but, in +some cases, quite a bit of the code passed through to them will be for +dictionary-handling. diff --git a/ghc/docs/add_to_compiler/howto-add.verb b/ghc/docs/add_to_compiler/howto-add.verb new file mode 100644 index 0000000000..c5dfcf65b2 --- /dev/null +++ b/ghc/docs/add_to_compiler/howto-add.verb @@ -0,0 +1,353 @@ +%************************************************************************ +%* * +\section{How to add an optimisation pass} +%* * +%************************************************************************ +\subsection{Summary of the steps required} + +Well, with all the preliminaries out of the way, here is all that it +takes to add your optimisation pass to the new glorious Glasgow +Haskell compiler: +\begin{enumerate} +\item +Select the input and output types for your pass; these will very +likely be particular parameterisations of the Core or annotated Core +data types. There is a small chance you will prefer to work at the +STG-syntax level. (If these data types are inadequate to this +purpose, {\em please} let us know!) + +\item +Depending on exactly how you want your pass to work, set up some +monad-ery, so as to avoid lots of horrible needless plumbing. The +whole compiler is written in a monadic style, and there are plenty of +examples from which you may steal. Section~\ref{sec:monadic-style} +gives further details about how you might do this. + +\item +Write your optimisation pass, and... + +{\em Do} use the existing types in the compiler, e.g., @UniType@, +and the ``approved'' interfaces to them. + +{\em Don't} rewrite lots of utility code! Scattered around in various +sometimes-obvious places, there is considerable code already written +for the mangling and massaging of expressions, types, variables, etc. + +Section~\ref{sec:reuse-code} says more about how to re-use existing +compiler bits. + +\item +Follow our naming conventions \smiley{} Seriously, it may lead to greater +acceptance of our code and yours if readers find a system written with +at least a veneer of uniformity. +\ToDo{mention Style Guide, if it ever really exists.} + +\item +To hook your pass into the compiler, either add something directly to +the @Main@ module of the compiler,\srcloc{main/Main.lhs} or into the +Core-to-Core simplification driver,\srcloc{simplCore/SimplCore.lhs} or +into the STG-to-STG driver.\srcloc{simplStg/SimplStg.lhs} + +Also add something to the compilation-system +driver\srcloc{ghc/driver/ghc.lprl} +(called @ghc@ here) so that appropriate user-provided command-line +options will be transmogrified into the correct options fed to the +@Main@ module. + +\item +Add some appropriate documentation to the user's guide, +@ghc/docs/users_guide@. + +\item +Run your optimisation on {\em real programs}, measure, and improve. +(Separate from this compiler's distribution, we provide a ``NoFib'' +suite of ``real Haskell programs'' \cite{partain92a}. We strongly +encourage their use, so you can more readily compare your work with +others'.) + +\item +Send us your contribution so we can add it to the distribution! We +will be happy to include anything semi-reasonable. +This will practically ensure fame, if +not fortune, and---with a little luck---considerable notoriety. +\end{enumerate} + +%************************************************************************ +%* * +\subsection{Using monadic code}\label{sec:monadic-style} +%* * +%************************************************************************ + +{\em Monads} are one way of structuring functional programs. Phil +Wadler is their champion, and his recent papers on the subject are a +good place to start your investigations. ``The essence of functional +programming'' even has a section about the use of monads in this +compiler \cite{wadler92a}! An earlier paper describes ``monad +comprehensions'' \cite{wadler90a}. For a smaller self-contained +example, see his ``literate typechecker'' \cite{wadler90b}. + +We use monads extensively in this compiler, mainly as a way to plumb +state around. The simplest example is a monad to plumb a +@UniqueSupply@\srcloc{basicTypes/Unique.lhs} (i.e., name supply) +through a function. + +\ToDo{Actually describe one monad thing completely.} + +We encourage you to use a monadic style, where appropriate, in +the code you add to the compiler. To this end, here is a list of +monads already in use in the compiler: +\begin{description} +\item[@UniqueSupply@ monad:] \srcloc{basicTypes/Unique.lhs} +To carry a name supply around; do a @getUnique@ when you +need one. Used in several parts of the compiler. + +\item[Typechecker monad:] \srcloc{typecheck/TcMonad.lhs} +Quite a complicated monad; carries around a substitution, some +source-location information, and a @UniqueSupply@; also plumbs +typechecker success/failure back up to the right place. + +\item[Desugarer monad:] \srcloc{deSugar/DsMonad.lhs} +Carries around a @UniqueSupply@ and source-location information (to +put in pattern-matching-failure error messages). + +\item[Code-generator monad:] \srcloc{codeGen/CgMonad.lhs} +Carries around an environment that maps variables to addressing modes +(e.g., ``in this block, @f@ is at @Node@ offset 3''); also, carries +around stack- and heap-usage information. Quite tricky plumbing, in +part so that the ``Abstract~C'' output will be produced lazily. + +\item[Monad for underlying I/O machinery:] \srcloc{ghc/lib/io/GlaIOMonad.lhs} +This is the basis of our I/O implementation. See the paper about it +\cite{peyton-jones92b}. +\end{description} + +%************************************************************************ +%* * +\subsection{Adding a new @PrimitiveOp@}\label{sec:add-primop} +%* * +%************************************************************************ + +You may find yourself wanting to add a new +@PrimitiveOp@\srcloc{prelude/PrimOps.lhs} to the compiler's +repertoire: these are the lowest-level operations that cannot be +expressed in Haskell---in our case, things written in C. + +What you would need to do to add a new op: +\begin{itemize} +\item +Add it to the @PrimitiveOp@ datatype in @prelude/PrimOps.lhs@; it's +just an enumeration type. +\item +Most importantly, add an entry in the @primOpInfo@ function for your +new primitive. +\item +If you want your primitive to be visible to some other part of the +compiler, export it via the @AbsPrel@\srcloc{prelude/AbsPrel.lhs} +interface (and import it from there). +\item +If you want your primitive to be visible to the user (modulo some +``show-me-nonstd-names'' compiler flag...), add your primitive to one +or more of the appropriate lists in @buildinNameFuns@, in +@prelude/AbsPrel.lhs@. +\item +If your primitive can be implemented with just a C macro, add it to +@ghc/imports/StgMacros.lh@. If it needs a C function, put that in +@ghc/runtime/prims/@, somewhere appropriate; you might need to put a +declaration of some kind in a C header file in @ghc/imports/@. +\item +If these steps are not enough, please get in touch. +\end{itemize} + +%************************************************************************ +%* * +\section{How to add a new ``PrimOp'' (primitive operation)} +%* * +%************************************************************************ + +%************************************************************************ +%* * +\section{How to add a new ``user pragma''} +%* * +%************************************************************************ + +%************************************************************************ +%* * +\section{GHC utilities and re-usable code}\label{sec:reuse-code} +%* * +%************************************************************************ + +%************************************************************************ +%* * +\subsection{Reuse existing utilities} +%* * +%************************************************************************ + +Besides the utility functions provided in Haskell's standard prelude, +we have several modules of generally-useful utilities in \mbox{\tt utils/} +(no need to re-invent them!): +\begin{description} +\item[@Maybe@ and @MaybeErr@:] +Two very widely used types (and some operations on them): +\begin{verbatim} +data Maybe a = Nothing | Just a +data MaybeErr a b = Succeeded a | Failed b +\end{verbatim} + +\item[@Set@:] +A simple implementation of sets (an abstract type). The things you +want to have @Sets@ of must be in class @Ord@. + +\item[@ListSetOps@:] +A module providing operations on lists that have @Set@-sounding names; +e.g., @unionLists@. + +\item[@Digraph@:] +A few functions to do with directed graphs, notably finding +strongly-connected components (and cycles). + +\item[@Util@:] +General grab-bag of utility functions not provided by the standard +prelude. +\end{description} + +Much of the compiler is structured around major datatypes, e.g., +@UniType@ or @Id@. These datatypes (often ``abstract''---you can't +see their actual constructors) are packaged with many useful +operations on them. So, again, look around a little for these +functions before rolling your own. Section~\ref{sec:reuse-datatypes} +goes into this matter in more detail. + +%************************************************************************ +%* * +\subsection{Use pretty-printing and forcing machinery} +%* * +%************************************************************************ + +All of the non-trivial datatypes in the compiler are in class +@Outputable@, meaning you can pretty-print them (method: @ppr@) or +force them (method: @frc@). + +Pretty-printing is by far the more common operation. @ppr@ takes a +``style'' as its first argument; it can be one of @PprForUser@, +@PprDebug@, or @PprShowAll@, which---in turn---are intended to show +more and more detail. For example, @ppr PprForUser@ on a @UniType@ +should print a type that would be recognisable to a Haskell user; +@ppr PprDebug@ prints a type in the way an implementer would normally +want to see it (e.g., with all the ``for all...''s), and +@ppr PprShowAll@ prints everything you could ever want to know about that +type. + +@ppr@ produces a @Pretty@, which should eventually wend its way to +@main@. @main@ can then peruse the program's command-line options to +decide on a @PprStyle@ and column width in which to print. In +particular, it's bad form to @ppShow@ the @Pretty@ into a @String@ +deep in the bowels of the compiler, where the user cannot control the +printing. + +If you introduce non-trivial datatypes, please make them instances of +class @Outputable@. + +%************************************************************************ +%* * +\subsection{Use existing data types appropriately}\label{sec:reuse-datatypes} +%* * +%************************************************************************ + +The compiler uses many datatypes. Believe it or not, these have +carefully structured interfaces to the ``outside world''! Unfortunately, +the current Haskell module system does not let us enforce proper +access to these datatypes to the extent we would prefer. Here is a +list of datatypes (and their operations) you should feel free to use, +as well as how to access them. + +The first major group of datatypes are the ``syntax datatypes,'' the +various ways in which the program text is represented as it makes its +way through the compiler. These are notable in that you are allowed +to see/make-use-of all of their constructors: +\begin{description} +\item[Prefix form:]\srcloc{reader/PrefixSyn.lhs} You shouldn't need +this. + +\item[Abstract Haskell syntax:]\srcloc{abstractSyn/AbsSyn.lhs} Access +via the @AbsSyn@ interface. An example of what you should {\em not} +do is import the @AbsSynFuns@ (or @HsBinds@ or ...) interface +directly. @AbsSyn@ tells you what you're supposed to see. + +\item[Core syntax:]\srcloc{coreSyn/*Core.lhs} Core syntax is +parameterised, and you should access it {\em via one of the +parameterisations}. The most common is @PlainCore@; another is +@TaggedCore@. Don't use @CoreSyn@, though. + +\item[STG syntax:]\srcloc{stgSyn/StgSyn.lhs} Access via the @StgSyn@ interface. + +\item[Abstract~C syntax:]\srcloc{absCSyn/AbsCSyn.lhs} Access via the +@AbsCSyn@ interface. +\end{description} + +The second major group of datatypes are the ``basic entity'' +datatypes; these are notable in that you don't need to know their +representation to use them. Several have already been mentioned: +\begin{description} +\item[UniTypes:]\srcloc{uniType/AbsUniType.lhs} This is a gigantic +interface onto the world of @UniTypes@; accessible via the +@AbsUniType@ interface. You should import operations on all the {\em +pieces} of @UniTypes@ (@TyVars@, @TyVarTemplates@, @TyCons@, +@Classes@, and @ClassOps@) from here as well---everything for the +``type world.'' + +{\em Please don't grab type-related functions from internal modules, +behind @AbsUniType@'s back!} (Otherwise, we won't discover the +shortcomings of the interface...) + +\item[Identifiers:]\srcloc{basicTypes/Id.lhs} Interface: @Id@. + +\item[``Core'' literals:]\srcloc{basicTypes/CoreLit.lhs} These are +the unboxed literals used in Core syntax onwards. Interface: @CoreLit@. + +\item[Environments:]\srcloc{envs/GenericEnv.lhs} +A generic environment datatype, plus a generally useful set of +operations, is provided via the @GenericEnv@ interface. We encourage +you to use this, rather than roll your own; then your code will +benefit when we speed up the generic code. All of the typechecker's +environment stuff (of which there is plenty) is built on @GenericEnv@, +so there are plenty of examples to follow. + +\item[@Uniques@:]\srcloc{basicTypes/Unique.lhs} Essentially @Ints@. +When you need something unique for fast comparisons. Interface: +@Unique@. This interface also provides a simple @UniqueSupply@ monad; +often just the thing... + +\item[Wired-in standard prelude knowledge:]\srcloc{prelude/} The +compiler has to know a lot about the standard prelude. What it knows +is in the @compiler/prelude@ directory; all the rest of the compiler +gets its prelude knowledge through the @AbsPrel@ interface. + +The prelude stuff can get hairy. There is a separate document about +it. Check the @ghc/docs/README@ list for a pointer to it... +\end{description} + +The above list isn't exhaustive. By all means, ask if you think +``Surely a function like {\em this} is in here somewhere...'' + + +%************************************************************************ +%* * +\section{Cross-module pragmatic info: the mysteries revealed} +%* * +%************************************************************************ + +ToDo: mention wired-in info. + +%************************************************************************ +%* * +\section{GHC hacking tips and ``good practice''} +%* * +%************************************************************************ + +ASSERT + +%************************************************************************ +%* * +\section{Glasgow pragmatics: build trees, etc.} +%* * +%************************************************************************ diff --git a/ghc/docs/add_to_compiler/overview-fig.fig b/ghc/docs/add_to_compiler/overview-fig.fig new file mode 100644 index 0000000000..a68a0daa69 --- /dev/null +++ b/ghc/docs/add_to_compiler/overview-fig.fig @@ -0,0 +1,136 @@ +#FIG 2.1 +80 2 +6 264 49 379 119 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 312 69 376 69 376 101 312 101 312 69 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 272 93 328 117 344 117 344 101 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 344 69 344 53 328 53 268 73 9999 9999 +-6 +6 269 149 384 219 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 317 169 381 169 381 201 317 201 317 169 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 277 193 333 217 349 217 349 201 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 349 169 349 153 333 153 273 173 9999 9999 +-6 +1 1 0 1 -1 0 0 0 0.000 1 0.000 82 324 49 17 82 324 129 340 +1 1 0 1 -1 0 0 0 0.000 1 0.000 80 36 49 17 80 36 128 52 +1 1 0 1 -1 0 0 0 0.000 1 0.000 82 228 49 17 82 228 129 244 +1 1 0 1 -1 0 0 0 0.000 1 0.000 82 419 49 17 82 419 129 435 +1 1 0 1 -1 0 0 0 0.000 1 0.000 79 133 49 17 79 133 127 149 +1 1 0 1 -1 0 0 0 0.000 1 0.000 235 180 49 17 235 180 283 196 +1 1 0 1 -1 0 0 0 0.000 1 0.000 232 372 49 17 232 372 280 388 +1 1 0 1 -1 0 0 0 0.000 1 0.000 233 276 49 17 233 276 281 292 +1 1 0 1 -1 0 0 0 0.000 1 0.000 232 85 49 17 232 85 280 101 +1 1 0 1 -1 0 0 0 0.000 1 0.000 233 467 49 17 233 467 281 483 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 81 292 81 308 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 81 244 81 260 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 33 260 129 260 129 292 33 292 33 260 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 33 164 129 164 129 196 33 196 33 164 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 81 101 81 117 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 81 53 81 69 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 81 148 81 164 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 81 196 81 212 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 33 69 129 69 129 101 33 101 33 69 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 33 356 129 356 129 388 33 388 33 356 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 33 451 129 451 129 483 33 483 33 451 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 81 388 81 403 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 81 435 81 451 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 81 340 81 356 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 81 483 81 499 161 499 161 49 212 49 212 69 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 185 308 280 308 280 340 185 340 185 308 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 232 37 232 69 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 232 101 232 117 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 185 117 280 117 280 148 185 148 185 117 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 185 403 280 403 280 435 185 435 185 403 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 232 196 232 212 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 232 244 232 260 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 232 292 232 308 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 232 340 232 356 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 232 388 232 403 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 232 435 232 451 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 232 148 232 164 9999 9999 +2 1 0 1 -1 0 0 0 0.000 0 1 0 + 0 0 1.000 4.000 8.000 + 272 284 312 308 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 189 212 284 212 284 244 189 244 189 212 9999 9999 +2 4 0 3 -1 0 0 0 0.000 7 0 0 + 13 13 13 515 400 515 400 13 13 13 9999 9999 +4 0 0 10 0 -1 0 0.000 4 10 45 61 328 AbsSyntax +4 0 0 10 0 -1 0 0.000 4 7 60 53 41 Haskell source +4 0 0 10 0 -1 0 0.000 4 10 45 61 232 AbsSyntax +4 0 0 10 0 -1 0 0.000 4 10 50 57 376 Typechecker +4 0 0 10 0 -1 0 0.000 4 10 45 61 423 AbsSyntax +4 0 0 10 0 -1 0 0.000 4 10 42 57 471 Desugarer +4 0 0 10 0 -1 0 0.000 4 7 43 61 137 Prefix form +4 0 0 10 0 -1 0 0.000 4 7 29 69 184 Reader +4 0 0 10 0 -1 0 0.000 4 7 36 65 280 Renamer +4 0 0 10 0 -1 0 0.000 4 7 38 216 232 CodeGen +4 0 0 10 0 -1 0 0.000 4 8 43 308 328 generators +4 0 0 10 0 -1 0 0.000 4 7 44 308 320 Other code +4 0 0 10 0 -1 0 0.000 4 10 43 212 137 CoreToStg +4 0 0 10 0 -1 0 0.000 4 10 47 212 89 CoreSyntax +4 0 0 10 0 -1 0 0.000 4 10 41 212 184 StgSyntax +4 0 0 10 0 -1 0 0.000 4 7 44 208 280 Abstract C +4 0 0 10 0 -1 0 0.000 4 7 30 216 328 Flatten +4 0 0 10 0 -1 0 0.000 4 7 6 228 376 C +4 0 0 10 0 -1 0 0.000 4 10 42 212 423 C compiler +4 0 0 10 0 -1 0 0.000 4 7 48 212 471 Native code +4 0 0 10 0 -1 0 0.000 4 10 32 328 89 Simplify +4 0 0 10 0 -1 0 0.000 4 7 65 201 33 Other front ends +4 0 0 10 0 -1 0 0.000 4 10 65 42 89 Lex/Yacc parser +4 0 0 10 0 -1 0 0.000 4 10 32 333 189 Simplify diff --git a/ghc/docs/add_to_compiler/overview.verb b/ghc/docs/add_to_compiler/overview.verb new file mode 100644 index 0000000000..32e0c4a985 --- /dev/null +++ b/ghc/docs/add_to_compiler/overview.verb @@ -0,0 +1,70 @@ +%************************************************************************ +%* * +\section{Overview of the Glasgow Haskell compiler} +%* * +%************************************************************************ + +Figure~\ref{fig:overview} shows a schematic overview of the Glasgow +Haskell compiler (GHC), including all the major datatypes and most +existing passes. +\begin{figure} +\centering +\input{overview-fig} +%\psfig{figure=closure.ps} +\caption{Compiler overview} +\label{fig:overview} +\end{figure} +The compiler is itself written in Haskell. As of now, the compiler is +made up of about 200?~modules, with roughly 40,000?~lines of +Haskell code, excluding comments and blank lines. + +The compiler divides unsurprisingly into a {\em front end} and a {\em +back end}, corresponding to the left and right columns of +Figure~\ref{fig:overview}, respectively. + +The front end, discussed further in Section~\ref{sec:front-end}, is +the part that may report errors back to the user. The two main pieces +are a {\em renamer},\srcloc{renamer/} which handles naming issues, +including support of the Haskell module system, and the {\em +typechecker}.\srcloc{typecheck/} + +The front end operates on a collection of data types that we call +``abstract syntax.''\srcloc{abstractSyn/} These types +match the Haskell language, construct for construct. For example, +if you write @... [ x | x <- [1..n] ] ...@, the typechecker +will actually see something like: +\begin{verbatim} +ListComp + (Var x) + (GeneratorQual (VarPatIn x) + (ArithSeq (FromTo (Lit (IntLit 1)) (Var n)))) +\end{verbatim} +So, the renamer and typechecker work on unrestructured Haskell source +rather than its desugared equivalent. The compiler should be {\em +quicker} to find errors (because the source is much smaller and time +hasn't been taken desugaring), and it should report errors more +lucidly, in terms of the original program text. + +A conventional desugaring pass\srcloc{deSugar/} (basically Wadler's +Chapter~5 of Peyton Jones's 1987 implementation book +\cite{peyton-jones87b}) converts the typechecker's abstract-syntax output +(with types attached) into the ``CoreSyntax''\srcloc{coreSyn/} data +type. This data type is little more than the second-order polymorphic +lambda calculus and is intended to be the {\em lingua franca} of the +compiler's back end, including almost all of the optimisation passes. +Core syntax is explained at length in Section~\ref{sec:core-syntax}. + +The back end of the compiler, discussed further in +Section~\ref{sec:back-end}, takes a successfully-typechecked module +and produces executable code for it. The back end consists of zero or +more Core-to-Core transformation passes, followed by conversion to STG +syntax\srcloc{stgSyn/} (a very low-level functional language, named +after the intended Spineless Tagless G-machine\footnote{Oops! Make +that ``shared term graph'' language! (Who's fooling who here, +Simon?)} target architecture), then some STG-to-STG transformations, +and finally out of the functional world\srcloc{codeGen/} into +``Abstract~C,''\srcloc{absCSyn/} a datatype intended as an adequate +launching pad into both portable C and into get-your-hands-{\em +really}-dirty native-code generation for a particular instruction-set +architecture. We can generate C, or native-code for SPARCs and DEC +Alphas. diff --git a/ghc/docs/add_to_compiler/paper.bbl b/ghc/docs/add_to_compiler/paper.bbl new file mode 100644 index 0000000000..7f2437a524 --- /dev/null +++ b/ghc/docs/add_to_compiler/paper.bbl @@ -0,0 +1,72 @@ +\begin{thebibliography}{10} + +\bibitem{hudak91a} +Report on the programming language {Haskell}, a non-strict purely functional + language ({Version} 1.1), August, 1991. +\newblock Computing Science Department, Glasgow University, forthcoming. + +\bibitem{hammond89a} +Kevin Hammond. +\newblock Implementing type classes for {Haskell}. +\newblock In {\em Proceedings of the Glasgow Workshop on Functional + Programming}, page ????, Fraserburgh, Scotland, August, 1989. + +\bibitem{partain92a} +Will Partain. +\newblock The {\tt nofib} benchmark suite of {Haskell} programs, 1992. + +\bibitem{peyton-jones87b} +Simon~L. {Peyton Jones}. +\newblock {\em The Implementation of Functional Programming Languages}. +\newblock Prentice-Hall, 1987. + +\bibitem{peyton-jones92a} +Simon~L. {Peyton Jones}. +\newblock Implementing lazy functional languages on stock hardware: the + {Spineless Tagless G-machine}. +\newblock {\em Journal of Functional Programming}, 1992. +\newblock To appear. + +\bibitem{peyton-jones91b} +Simon~L. {Peyton Jones} and John Launchbury. +\newblock Unboxed values as first class citizens in a non-strict functional + language. +\newblock In John Hughes, editor, {\em Functional Programming Languages and + Computer Architecture (FPCA)}, volume 523 of {\em Lecture Notes in Computer + Science}, pages 636--666, Cambridge, MA, August 26--30, 1991. + Springer-Verlag. + +\bibitem{peyton-jones90a} +Simon~L. {Peyton Jones} and Philip Wadler. +\newblock A static semantics for {Haskell}, 1990. +\newblock Dept.~of Computing Science, University of Glasgow. + +\bibitem{peyton-jones92b} +Simon~L. {Peyton Jones} and Philip Wadler. +\newblock Imperative functional programming (extended abstract), 1992. +\newblock To be in POPL~'93. + +\bibitem{wadler90a} +Philip Wadler. +\newblock Comprehending monads. +\newblock In {\em Proceedings of the 1990 ACM Conference on {LISP} and + Functional Programming}, pages 61--78, Nice, France, June 27--29, 1990. + +\bibitem{wadler90b} +Philip Wadler. +\newblock A simple type inference algorithm, 1990. +\newblock Dept.~of Computing Science, University of Glasgow. + +\bibitem{wadler92a} +Philip Wadler. +\newblock The essence of functional programming. +\newblock In {\em 19th ACM Symposium on Principles of Programming Languages + (POPL)}, page ?????, Santa Fe, NM, January ????, 1992. + +\bibitem{wadler89a} +Philip~L. Wadler and Stephen Blott. +\newblock How to make {\em ad-hoc\/} polymorphism less {\em ad hoc\/}. +\newblock In {\em 16th ACM Symposium on Principles of Programming Languages + (POPL)}, pages 60--76, Austin, TX, January 11--13, 1989. + +\end{thebibliography} diff --git a/ghc/docs/add_to_compiler/paper.verb b/ghc/docs/add_to_compiler/paper.verb new file mode 100644 index 0000000000..39a82c65c7 --- /dev/null +++ b/ghc/docs/add_to_compiler/paper.verb @@ -0,0 +1,77 @@ +\documentstyle[11pt,../grasp,code]{article} +%\documentstyle[12pt,springer-wcs,oldfontnames,code]{article} +\setlength{\marginparwidth}{1.5cm} +\setlength{\parskip}{0.25cm} +\setlength{\parindent}{0cm} +\renewcommand{\textfraction}{0.2} +\renewcommand{\floatpagefraction}{0.7} +% +\newcommand{\freevars}[1]{fvs(#1)} +% +% to avoid src-location marginpars, comment in/out the out/in defns. +%\newcommand{\srcloc}[1]{} +%\newcommand{\onlyIfSrcLocs}[1]{} +% +\newcommand{\onlyIfSrcLocs}[1]{#1} +% +\begin{document} +\title{How to Add an Optimisation Pass\\ +to the Glasgow Haskell compiler\\ +(two months before version~0.23)} +\author{Will Partain, acting as AQUA Project scribe\\ +e-mail contact: partain@@dcs.glasgow.ac.uk} +\renewcommand{\today}{October, 1994} +\maketitle +% temporarily.... +\tableofcontents +%\clearpage +\begin{abstract} +A major purpose of the new Glasgow Haskell compiler (written in +Haskell) is to be freely available in source form so that others can +use it as ``root stock'' onto which they may graft their own wonderful +bits. This document is a field guide for the aspiring +better-compiler grower, particularly one who wishes to add an +optimisation pass. +\end{abstract} + +\onlyIfSrcLocs{Throughout this paper, pointers to the relevant +source-code are given in the margins. This code is in the {\tt +ghc/compiler/} part of the distribution; names ending in {\tt /} are +directories. We assume you already know Haskell.} + +% \input{state-of-play} + +\input{overview} + +\input{front-end} +\input{back-end} + +\input{core-syntax} + +\input{howto-add} + +%************************************************************************ +%* * +\section{For further information} +%* * +%************************************************************************ + +Besides the documents listed in the References below, there are +several internal compiler documents that come with the GHC +distribution.\srcloc{ghc/docs/README} + +If you are hacking GHC, you should be on the @glasgow-haskell-users@ +mailing list. Send mail to +@glasgow-haskell-users-request@@dcs.glasgow.ac.uk@ to subscribe. +You may wish to subscribe to our ``bugs channel'' ( +@glasgow-haskell-bugs-request@@dcs.glasgow.ac.uk@) as well, if you +are a glutton for punishment. + +Further suggestions as to how we can make your job easier will be most +appreciated. + +\bibliographystyle{wpplain} % wpplain, wplong, wpannote, ... +\bibliography{wp_abbrevs,comp} + +%\printindex +\end{document} diff --git a/ghc/docs/add_to_compiler/slides-root.tex b/ghc/docs/add_to_compiler/slides-root.tex new file mode 100644 index 0000000000..163cc3d856 --- /dev/null +++ b/ghc/docs/add_to_compiler/slides-root.tex @@ -0,0 +1,8 @@ +\documentstyle{slides} +\pagestyle{empty} +%\onlyslides{1-99} +%\onlynotes{1-99} +\begin{document} +\blackandwhite{slides} +%\input{slides} +\end{document} diff --git a/ghc/docs/add_to_compiler/slides.tex b/ghc/docs/add_to_compiler/slides.tex new file mode 100644 index 0000000000..947adcb12a --- /dev/null +++ b/ghc/docs/add_to_compiler/slides.tex @@ -0,0 +1,86 @@ +%01 title +\begin{slide}{} +\begin{center} +{\Large +How To Add\\ +An Optimisation Pass To\\ +The Glasgow Haskell Compiler\\[40pt] +} +{\large +Will Partain\\ +(GRASP Project scribe) +} +\end{center} +\end{slide} + +%02 hello, world +\begin{slide}{} +{\Large The state of play} + +\begin{verbatim} +sun3% time gcc -c hello.c +0.240u 0.520s 0:01.00 76.0% 0+51k 0+9io 0pf+0w + +sun3% time nlmlc -c hello.m +3.320u 1.740s 0:05.65 89.5% 0+240k 1+21io 1pf+0w + +sun3% time nhc -c hello.hs +26.680u 2.860s 0:32.00 92.3% 0+950k 2+31io 18pf+0w + +sun3% time do100x # C +6.980u 7.880s 0:14.93 99.5% 0+50k 0+0io 0pf+0w + +sun3% time do100x # LML +7.880u 10.500s 0:18.50 99.3% 0+57k 1+0io 1pf+0w + +sun3% time do100x # haskell +7.760u 10.440s 0:18.48 98.4% 0+56k 1+0io 1pf+0w +\end{verbatim} +\end{slide} +%% % time hello100 > /dev/null +%% 0.060u 0.100s 0:00.16 100.0% 0+51k 0+0io 0pf+0w + +%03 analyses +\begin{slide}{} +{\Large Analyses (FPCA~'89, PLDI~'91)} + +binding-time analysis\\ +closure analysis\\ +complexity analysis\\ +demand analysis\\ +facet analysis\\ +interference analysis\\ +lifetime analysis\\ +liveness analysis\\ +path analysis\\ +polymorphic-instance analysis\\ +stacklessness anaysis\\ +strictness analysis\\ +time analysis\\ +update analysis +\end{slide} + +\begin{note} +Contrast with conventional-compiler concerns: + +use of runtime feedback\\ +matching w/ low-level hardware concerns\\ +work very hard for their extra information +\end{note} + +\begin{slide}{} +{\Large Optimisations in use: LML} + +\begin{itemize} +\item +constant folding, arithmetic simplification +\item +many local transformations (case of case...) +\item +inlining, $\beta$-reduction +\item +strictness analysis +\item +G-code and m-code optimisation +\end{itemize} +\end{slide} diff --git a/ghc/docs/add_to_compiler/state-of-play.NOTES b/ghc/docs/add_to_compiler/state-of-play.NOTES new file mode 100644 index 0000000000..cdfa7d83f0 --- /dev/null +++ b/ghc/docs/add_to_compiler/state-of-play.NOTES @@ -0,0 +1,73 @@ +analyses: + strictness & binding-time analysis (\cite{launchbury91a}) + polymorphic-instance analysis (pldi 91; referred \cite{launchbury91a}, p 86 top left) + facet analysis (part of [higher-order offline] parameterized partial evaluation) + (pldi 91: \cite{consel91a}) + binding-time analysis (fpca89; \cite{mogensen91}) + strictness analysis (\cite{wadler87a}) + update analysis (fpca; \cite{bloss89b}) + path analysis (fpca; \cite{bloss89b}) + interference, closure, and lifetime analysis (fpca; \cite{sestoft89a}) + stacklessness anaysis (fpca; \cite{lester89b}) + liveness analysis (AHU, reffed by lester89b) + complexity analysis (fpca, \cite{rosendahl89a}) + demand analysis + time analysis + +type systems: + refinement types (pldi 91; \cite{freeman91a}) + soft typing (pldi 91; \cite{cartwright91a}) + +other: + +done in LML compiler: + llift lambda lifter + /Bconv + simpl + /asimpl arithmetic simplifications + /casetr case of case ... (& a couple of others ?) + /mlet mlet (inlining) ? + /simpl constant folding, casefold, Esimpl, simpl, + force arity, movelam + strict very simple strictness analysis + transform + /case caseelim + /casep condjoin + /constr constrtr + /lettrans let transformations + unrec + Gopt G-code optimiser + mopt m-code optimiser + +done in yale compiler: + (in flic) + optimization : \beta-redn (constant propagation & inlining) + constant folding + dead code elim + strictness analysis + +the competition: + + (mips compiler) + compiles to "ucode" (symbolic assembler) + optimisations on both ucode and binary assembler + -O2 global ucode optimizer + -O3 global register alloc + -feedback file + -cord procedure re-arranger ; reduce cache conflicts + pixie adds things to binary for profiling + pixstats generate exec stats from a pixified pgm + prof analyse profile data (pc-sampling, basic-blk counting) + + data dependence analysis (pldi 91; \cite{maydan91a}) + (nice table of stats-- pldi 91; \cite{goff91a}, p 25) + + tiling for better cache hits (pldi 91: \cite{wolf91a}) + + using real or estimated runtime profiles (pldi 91: \cite{wall91a}) + + procedure merging w/ instruction caches (pldi 91: \cite{mcfarling91a}) + + fortran @ 10 Gflops (pldi 91: \cite{bromley91a}) + + global instr scheduling for superscalar machines (pldi 91: \cite{bernstein91a}) diff --git a/ghc/docs/add_to_compiler/state-of-play.verb b/ghc/docs/add_to_compiler/state-of-play.verb new file mode 100644 index 0000000000..301b2524db --- /dev/null +++ b/ghc/docs/add_to_compiler/state-of-play.verb @@ -0,0 +1,14 @@ +%************************************************************************ +%* * +\section{The state of play} +%* * +%************************************************************************ + +\ToDo{This section will describe the state of play: where +functional-language compilers are; compared to their imperative +cousins.} + +%The burden of proof remains with us functional programmers. We +%encourage you to help solve this problem by contributing compiler +%passes that optimise real programs written in a standard non-toy +%language effectively. diff --git a/ghc/docs/add_to_compiler/stg-summary-fig.verb b/ghc/docs/add_to_compiler/stg-summary-fig.verb new file mode 100644 index 0000000000..99dad9cc03 --- /dev/null +++ b/ghc/docs/add_to_compiler/stg-summary-fig.verb @@ -0,0 +1,55 @@ +\begin{figure} \fbox{ +$\begin{array}{lrcll} +%\mbox{Program} & prog & \rightarrow & binds & \\ +%\\ +\mbox{Bindings} & binds & \rightarrow + & bind_1 @;@ \ldots @;@~ bind_n & n \geq 1 \\ +& bind & \rightarrow & var ~@=@~ vars_f ~@\@ upd~ vars_a ~@->@~expr + & \mbox{Closure} \\ + &&&& (vars_f = \freevars{expr} \setminus vars_a) \\ +\\ +\mbox{Update flag} & upd & \rightarrow & @u@ & \mbox{Updatable} \\ + && | & @n@ & \mbox{Not updatable} \\ +\\ +\mbox{Expression} & expr + & \rightarrow & @let@~binds~@in@~ expr + & \mbox{Local definition} \\ + && | & @letrec@~binds~@in@~expr + & \mbox{Local recursive definition} \\ + && | & @case@~expr~@of@~alts + & \mbox{Case expression} \\ + && | & var~vars & \mbox{Application}\\ + && | & con~vars + & \mbox{Saturated constructor} \\ + && | & prim~vars + & \mbox{Saturated primitive} \\ + && | & literal & \\ +\\ + +\mbox{Alternatives} & alts & \rightarrow + & calt_1@;@ \ldots @;@~calt_n@; default ->@~ expr + & n \geq 0~\mbox{(Boxed)} \\ + && | & lalt_1@;@ \ldots @;@~lalt_n@;@~var ~@->@~ expr + & n \geq 0~\mbox{(Unboxed)} \\ +\\ +\mbox{Constructor alt} + & calt & \rightarrow & con~vars~@->@~expr & \\ +\mbox{Literal alt} + & lalt & \rightarrow & literal~@->@~expr & \\ +\\ +\mbox{Literals} & literal + & \rightarrow & integer & \\ + && | & \ldots & \\ +\\ +\mbox{Primitives} & prim + & \rightarrow & @+@ ~|~ @-@ ~|~ @*@ ~|~ @/@ \\ + && | & \ldots & \\ +\\ +\mbox{Variable lists} & vars & \rightarrow & + @[@var_1@,@ \ldots @,@~var_n@]@ & n \geq 0 \\ +\\ +\end{array}$ +} +\caption{Syntax of the STG language} +\label{fig:stg-syntax} +\end{figure} diff --git a/ghc/docs/grasp.sty b/ghc/docs/grasp.sty new file mode 100644 index 0000000000..920783a53b --- /dev/null +++ b/ghc/docs/grasp.sty @@ -0,0 +1,177 @@ +% GRASP style file + +% +% Apart from settings of page size and margins, and +% setting appropriate math-mode italics, +% the following macros are provided: +% +% \ToDo{x} Highlighted note for something left to do +% \srcloc{x} Marginal note of source file x. x is set in +% typewriter font +% \smiley Well, you need one of these sometimes :-) + +%**************************************************************** +%* * +%* Page and paragraph format * +%* * +%**************************************************************** + +% Margins and page layout + +\sloppy % Reduce complaints + +\setlength{\marginparwidth}{1.5cm} + +% Block paragraphs + +\setlength{\parskip}{0.25cm} +\setlength{\parsep}{0.25cm} +\setlength{\topsep}{0cm} % Reduces space before and after verbatim, + % which is implemented using trivlist +\setlength{\parindent}{0cm} + +\renewcommand{\textfraction}{0.2} +\renewcommand{\floatpagefraction}{0.7} + + + +%**************************************************************** +%* * +%* ToDo * +%* * +%**************************************************************** + +\newcommand{\ToDo}[1]{$\spadesuit$~{\bf ToDo:} {\em #1} $\spadesuit$} + + +%**************************************************************** +%* * +%* srcloc * +%* * +%**************************************************************** + +\newcommand{\srcloc}[1]{\marginpar{\footnotesize\tt #1}} +% +% to avoid src-location marginpars, put this in your doc's pre-amble. +%\renewcommand{\srcloc}[1]{} + + +%**************************************************************** +%* * +%* smiley * +%* * +%**************************************************************** + +\newcommand{\smiley}{% +\hbox{$\bigcirc\mskip-13.3mu{}^{..} +\mskip-11mu\scriptscriptstyle\smile\ $}} + +%%\setbox0=\hbox{$\bigcirc$} +%%\dimen0=\wd0 +%%\newbox\smileybox +%%\setbox\smileybox=\hbox{\box0 \kern-.5\dimen0 +%% \lower .25ex\hbox to 0pt{\hss\vpt$\smile$\hss}% +%% \raise .25ex\hbox to 0pt{\hss\$\cdot\kern 0.1em\cdot$\hss}} +%%\wd\smileybox=\dimen0 +%%\def\smiley{\copybox\smileybox} +%% +%%Of course, you can substitute \frown for \smile :-) (but you may need +%%to adjust the spacing) :-( +%%-- +%%Andrew Innes (aci10@eng.cam.ac.uk) +%%Engineering Dept. +%%Cambridge University + + +%**************************************************************** +%* * +%* Math codes * +%* * +%**************************************************************** + +% The mathcodes for the letters A, ..., Z, a, ..., z are changed to +% generate text italic rather than math italic by default. This makes +% multi-letter identifiers look better. The mathcode for character c +% is set to "7000 (variable family) + "400 (text italic) + c. +% + + +% LaTeX with New Font Selection Scheme (NFSS) + +\@ifundefined{selectfont} + {} + {\newmathalphabet{\textit} + \addtoversion{normal}{\textit}{cmr}{m}{it} + \addtoversion{bold}{\textit}{cmr}{bx}{it} + \everymath{\textit} + \everydisplay{\textit} + } + +% LaTeX without NFSS +% +%\def\@setmcodes#1#2#3{{\count0=#1 \count1=#3 +% \loop \global\mathcode\count0=\count1 \ifnum \count0<#2 +% \advance\count0 by1 \advance\count1 by1 \repeat}} +% +%\@setmcodes{`A}{`Z}{"7441} +%\@setmcodes{`a}{`z}{"7461} + + +%**************************************************************** +%* * +%* Definitions for macros used in figures * +%* These are produced by fig2dev, so we need defns for them * +%* * +%**************************************************************** + +% These ones work for 11-pt typesetting + +\@ifundefined{selectfont} %DL is MS scheme present? +{}{ +\def\fiverm{\rm\tiny} % Five pt +\def\sevrm{\rm\scriptsize} % Seven pt + +\def\nintt{\tt\footnotesize} +\def\ninrm{\rm\footnotesize} + +\def\tenrm{\rm\small} % Ten pt +\def\tentt{\tt\small} % Ten pt + +\def\elvrm{\rm\normalsize} % Eleven pt +\def\elvit{\em\normalsize} + +\def\twlbf{\bf\large} % Twelve pt +\def\twlit{\em\large} +\def\twltt{\tt\large} +\def\twlrm{\rm\large} +\def\twfvtt{\tt\large} + +\def\frtnrm{\rm\Large} % Fourteen pt +\def\frtnbf{\bf\Large} +\def\frtnit{\em\Large} +\def\frtntt{\tt\Large} + +\def\svtnsf{\sf\huge} % Seventeen pt + + +% cant remember why I need these +\def\egt{\size{8}{9} } +\def\elv{\size{11}{12} } +\def\five{\size{5}{7} } +\def\fiv{\size{5}{6} } +\def\frtn{\size{14}{15} } +\def\nin{\size{9}{10} } +\def\sev{\size{7}{8} } +\def\six{\size{6}{7} } +\def\svtn{\size{17}{18} } +\def\ten{\size{10}{11} } +\def\twfv{\size{25}{27} } +\def\twl{\size{12}{14} } +\def\twty{\size{20}{22} } +} + + + + + + diff --git a/ghc/docs/install_guide/Jmakefile b/ghc/docs/install_guide/Jmakefile new file mode 100644 index 0000000000..29b42b4ea6 --- /dev/null +++ b/ghc/docs/install_guide/Jmakefile @@ -0,0 +1,7 @@ +LitStuffNeededHere(docs depend) +InfoStuffNeededHere(docs) + +LiterateSuffixRules() +DocProcessingSuffixRules() + +LitDocRootTarget(installing,lit) diff --git a/ghc/docs/install_guide/installing.lit b/ghc/docs/install_guide/installing.lit new file mode 100644 index 0000000000..13df5b500a --- /dev/null +++ b/ghc/docs/install_guide/installing.lit @@ -0,0 +1,2133 @@ +% +% $Header: /srv/cvs/cvs.haskell.org/fptools/ghc/docs/install_guide/Attic/installing.lit,v 1.1 1996/01/08 20:25:19 partain Exp $ +% +\begin{onlystandalone} +\documentstyle[11pt,literate]{article} +\begin{document} +\title{Installing the Glasgow Functional Programming Tools\\ +Version~0.26} +\author{The AQUA Team (scribe: Will Partain)\\ +Department of Computing Science\\ +University of Glasgow\\ +Glasgow, Scotland\\ +G12 8QQ\\ +\\ +Email: glasgow-haskell-\{request,bugs\}\@dcs.glasgow.ac.uk} +\maketitle +\begin{rawlatex} +\tableofcontents +\end{rawlatex} +\clearpage +\end{onlystandalone} + +%************************************************************************ +%* * +\section[install-intro]{Introduction} +%* * +%************************************************************************ + +For most people, it should be easy to install one or more of the +Glasgow functional-programming tools (the `Glasgow tools'), most often +just the Glasgow Haskell compiler (GHC). This document will guide you +through the installation process, and point out the known pitfalls. + +Note: As of version~0.26, this document describes how to build {\em +all} of the Glasgow tools, not just the Haskell compiler. The +\tr{configure} script, etc., has changed to cope with this wider +mandate; something to bear in mind... + +%************************************************************************ +%* * +\subsection[install-strategy]{What to install? Starting from what?} +%* * +%************************************************************************ + +Building the Glasgow tools {\em can} be complicated, mostly because +there are so many permutations of what/why/how, e.g., ``Build Happy +with HBC, everything else with GHC, leave out profiling, and test it +all on the `real' NoFib programs.'' Yeeps! + +Happily, such complications don't apply to most people. A few common +``strategies'' serve most purposes. Pick one and proceed +as suggested: +\begin{description} +\item[Install from binary ``bundles'':] You have one of the supported +platforms (e.g., Sun4 or DEC Alpha), and you just want a Haskell +compiler, and you don't want to do anything fancy... This choice +is for you. Proceed to +\sectionref{installing-bin-distrib}. HIGHLY RECOMMENDED! + +\item[Build some Glasgow tools using GHC itself:] You have a supported +platform, but (a)~you like the warm fuzzy feeling of compiling things +yourself; (b)~you want to build something ``extra''---e.g., a set of +libraries with strictness-analysis turned off; or (c)~you want to hack +on GHC yourself. + +In this case, you should install a binary distribution +(as described in \sectionref{installing-bin-distrib}), +then build GHC with it (as described in \sectionref{building-GHC}). + +\item[Build GHC from intermediate C \tr{.hc} files:] You cannot get a +pre-built GHC, so you have no choice but to ``bootstrap'' up from the +intermediate C (\tr{.hc}) files that we provide. +Building GHC on an unsupported platform falls into this category. +Please see \sectionref{booting-from-C}. + +Once you have built GHC, you can build the other Glasgow tools with +it. + +\item[Build GHC with another Haskell compiler (e.g., HBC):] Not +recommended, but see \sectionref{building-with-HBC}. +\end{description} + +%************************************************************************ +%* * +\subsection[port-info]{What machines the Glasgow tools, version~0.26, run on} +\index{ports, GHC} +\index{GHC ports} +\index{supported platforms} +\index{platforms, supported} +%* * +%************************************************************************ + +The main question is whether or not the Haskell compiler (GHC) runs on +your machine. + +Bear in mind that certain ``bundles'', e.g. parallel Haskell, may not +work on all machines for which basic Haskell compiling is supported. + +Some libraries may only work on a limited number of platforms; for +example, a sockets library is of no use unless the operating system +supports the underlying BSDisms. + +%************************************************************************ +%* * +\subsubsection{What machines the Haskell compiler (GHC) runs on} +%* * +%************************************************************************ +\index{fully-supported platforms} +\index{native-code generator} +\index{registerised ports} +\index{unregisterised ports} + +The GHC hierarchy of Porting Goodness: (a)~Best is a native-code +generator; (b)~next best is a ``registerised'' +port; (c)~the bare minimum is an ``unregisterised'' port. +``Unregisterised'' Haskell programs are much bigger and slower, +but the port is much easier to get going. + +With GHC~0.26, we add ``registerised'' support for some HP-PA, iX86, +and MIPS platforms. + +We use Sun4s running SunOS~4.1.3 and DEC~Alphas running OSF/1~V2.0, +so those are the ``fully-supported'' platforms, unsurprisingly. Both +have native-code generators, for quicker compilations. + +Here's everything that's known about GHC ports, as of 0.26. We +identify platforms by their ``canonical GNU-style'' names. We +identify + +Note that some ports are fussy about which GCC version you use; or +require GAS; or ... + +\begin{description} +%------------------------------------------------------------------- +\item[\tr{alpha-dec-osf1}:] +\index{alpha-dec-osf1: fully supported} +(We have OSF/1 V2.0.) Fully supported, including native-code generator. +We recommend GCC 2.6.x or later. + +%------------------------------------------------------------------- +\item[\tr{sparc-sun-sunos4}:] +\index{sparc-sun-sunos4: fully supported} +Fully supported, including native-code generator. + +%------------------------------------------------------------------- +\item[\tr{sparc-sun-solaris2}:] +\index{sparc-sun-solaris2: fully supported} +Fully supported, including native-code generator. A couple of quirks, +though: (a)~the profiling libraries are bizarrely huge; (b)~the +default \tr{xargs} program is atrociously bad for building GHC +libraries (see \sectionref{Pre-supposed} for details). + +%------------------------------------------------------------------- +\item[HP-PA box running HP/UX 9.x:] +\index{hppa1.1-hp-hpux: registerised port} +GHC~0.26 works registerised. No native-code generator. +For GCC, you're best off with one of the Utah releases of +GCC~2.6.3 (`u3' or later), from \tr{jaguar.cs.utah.edu}. +We don't know if straight GCC 2.7.x works or not. + +Concurrent/Parallel Haskell probably don't work (yet). +\index{hppa1.1-hp-hpux: concurrent---no} +\index{hppa1.1-hp-hpux: parallel---no} + +%------------------------------------------------------------------- +\item[\tr{i386-*-linuxaout} (PCs running Linux---\tr{a.out} format):] +\index{i386-*-linuxaout: registerised port} +GHC~0.26 works registerised (no native-code generator). +You {\em must} have GCC 2.7.x or later. + +Concurrent/Parallel Haskell probably don't work (yet). +\index{i386-*-linuxaout: concurrent---no} +\index{i386-*-linuxaout: parallel---no} +\index{i386-*-linuxaout: profiling---maybe} +Profiling might work, but it is untested. + +%------------------------------------------------------------------- +\item[\tr{mips-sgi-irix5}:] +\index{mips-sgi-irix5: registerised port} +GHC~0.26 works registerised (no native-code generator). +I suspect any GCC~2.6.x (or later) is OK. The GCC that I used +was built with \tr{--with-gnu-as}. + +Concurrent/Parallel Haskell probably don't work (yet). +Profiling might work, but it is untested. +\index{mips-sgi-irix5: concurrent---no} +\index{mips-sgi-irix5: parallel---no} +\index{mips-sgi-irix5: profiling---maybe} + +%------------------------------------------------------------------- +\item[\tr{m68k-apple-macos7} (Mac, using MPW):] +\index{m68k-apple-macos7: historically ported} +Once upon a time, David Wright in Tasmania has actually +gotten GHC to run on a Macintosh. Ditto James Thomson here at Glasgow. +You may be able to get Thomson's from here. (Not sure that it will +excite you to death, but...) + +No particularly recent GHC is known to work on a Mac. + +%------------------------------------------------------------------- +\item[\tr{m68k-next-nextstep3}:] +\index{m68k-next-nextstep3: historically ported} +Carsten Schultz succeeded with a ``registerised'' port of GHC~0.19. +There's probably a little bit-rot since then, but otherwise it should +still be fine. Had a report that things were basically OK at 0.22. + +Concurrent/Parallel Haskell probably won't work (yet). +\index{m68k-next-nextstep3: concurrent---no} +\index{m68k-next-nextstep3: parallel---no} + +%------------------------------------------------------------------- +\item[\tr{m68k-sun-sunos4} (Sun3):] +\index{m68k-sun-sunos4: registerised port} +GHC~0.26 works registerised. No native-code generator. + +Concurrent/Parallel Haskell probably don't work (yet). +\index{m68k-sun-sunos4: concurrent---no} +\index{m68k-sun-sunos4: parallel---no} +\end{description} + +%************************************************************************ +%* * +\subsubsection{What machines the other tools run on} +%* * +%************************************************************************ + +Unless you hear otherwise, the other tools work if GHC works. + +Haggis requires Concurrent Haskell to work. +\index{Haggis, Concurrent Haskell} + +%************************************************************************ +%* * +\subsection{Things to check before you start typing} +%* * +%************************************************************************ + +\begin{enumerate} +\item +\index{disk space needed} +Disk space needed: About 30MB (five hamburgers' worth) of disk space +for the most basic binary distribution of GHC; more for some +platforms, e.g., Alphas. An extra ``bundle'' (e.g., concurrent +Haskell libraries) might take you to 8--10 hamburgers. + +You'll need over 100MB (say, 20 hamburgers' worth) if you need to +build the basic stuff from scratch. + +I don't yet know the disk requirements for the non-GHC tools. + +All of the above are {\em estimates} of disk-space needs. + +\item +Use an appropriate machine, compilers, and things. + +SPARC boxes and DEC Alphas running OSF/1 are fully supported. +\Sectionref{port-info} gives the full run-down on ports or lack +thereof. + +\item +Be sure that the ``pre-supposed'' utilities are installed. + +For GHC, you must have \tr{perl} to get anywhere at all. If you're +going for Parallel Haskell, you'll need PVM, version 3. You will +probably need a reasonably up-to-date GCC (GNU C compiler), +too---\sectionref{port-info} lists any specific requirements in this +regard. + +If you are going to be making documents [unlikely], you'll need +\tr{makeindex} as well, and maybe \tr{tgrind} [unlikely]. If you edit +the one or two \tr{flex} files in GHC, you'll need \tr{flex}, too +[unlikely]. + +If you end up yacc'ing the Haskell parser [unlikely], Sun's standard +\tr{/bin/yacc} won't cut it. Either the unbundled \tr{/usr/lang/yacc} +or \tr{bison} will do fine. Berkeley yacc (\tr{byacc}) won't do. + +\item +If you have any problem when building or installing the Glasgow tools, +please check the ``known pitfalls'' (\sectionref{build-pitfalls}). If +you feel there is still some shortcoming in our procedure or +instructions, please report it. + +For GHC, please see the bug-reporting section of the User's guide +(separate document), to maximise the usefulness of your report. + +If in doubt, please send a message to +\tr{glasgow-haskell-bugs@dcs.glasgow.ac.uk}. +\end{enumerate} + +%************************************************************************ +%* * +\section[installing-bin-distrib]{Installing from binary distributions (the most common case)} +\index{binary installations} +\index{installation, of binaries} +%* * +%************************************************************************ + +Installing from binary distributions is easiest, and recommended! + +%************************************************************************ +%* * +\subsection[GHC-bin-distrib]{GHC from binary distributions} +\index{GHC installation, from binaries} +\index{installation, GHC from binaries} +%* * +%************************************************************************ + +(Why binaries? Because GHC is a Haskell compiler written in Haskell, +so you've got to ``bootstrap'' it, somehow. We provide +machine-generated C-files-from-Haskell for this purpose, but it's +really quite a pain to use them. If you must build GHC from its +sources, using a binary-distributed GHC to do so is a sensible way to +proceed.) + +Binary distributions come in ``bundles,''\index{bundles of binary stuff} +one bundle per \tr{.tar.gz} file. + +A basic GHC ``bundle'' gives you the compiler and the standard, +sequential libraries. The files are called +\tr{ghc-0.26-<platform>.tar.gz}, where \tr{<platform>} is one of: +alpha-dec-osf2, hppa1.1-hp-hpux9, i386-unknown-linuxaout, +% i386-unknown-solaris2, +m68k-sun-sunos4, mips-sgi-irix5, +sparc-sun-sunos4, sparc-sun-solaris2. + +There are plenty of ``non-basic'' GHC bundles. The files for them are +called \tr{ghc-0.26-<bundle>-<platform>.tar.gz}, where the +\tr{<platform>} is as above, and \tr{<bundle>} is one of these: +\begin{description} +\item[\tr{prof}:] Profiling with cost-centres. You probably want this. + +\item[\tr{conc}:] Concurrent Haskell features. You may want this. + +\item[\tr{par}:] Parallel Haskell features (sits on top of PVM). +You'll want this if you're into that kind of thing. + +\item[\tr{gran}:] The ``GranSim'' parallel-Haskell simulator +(hmm... mainly for implementors). + +\item[\tr{ticky}:] ``Ticky-ticky'' profiling; very detailed +information about ``what happened when I ran this program''---really +for implementors. + +\item[\tr{prof-conc}:] Cost-centre profiling for Concurrent Haskell. + +\item[\tr{prof-ticky}:] Ticky-ticky profiling for Concurrent Haskell. +\end{description} + +One likely scenario is that you will grab {\em three} binary +bundles---basic, profiling, and concurrent. Once you have them, +unpack them all together in the same place, thusly: + +\begin{verbatim} +cd /put/them/in/here +gunzip < ghc-0.26-sparc-sun-sunos4.tar.gz | tar xf - +gunzip < ghc-0.26-prof-sparc-sun-sunos4.tar.gz | tar xf - +gunzip < ghc-0.26-conc-sparc-sun-sunos4.tar.gz | tar xf - +\end{verbatim} + +If you unpacked the files in a way that does {\em not} preserve +modification times (e.g., used the \tr{m} option to \tr{tar}---why on +earth you might do this, I cannot imagine), then please unpack them +again :-) The timestamps on the files are (regrettably) important. + +%To check that you have all the pre-supposed utilities, please see +%\sectionref{Pre-supposed}. + +Here's what to do with the stuff in each directory, once unpacked. +% (If your binary distribution, doesn't look like this---don't despair! +% It may be a ``dumped-from-a-build'' distribution; please see +% \sectionref{dumped-from-build}.) + +\begin{description} +%--------------------------------------------------------------------- +\item[\tr{bin/<platform>} (sometimes just \tr{bin/}):] +Copy these executables so that they will be in users' PATHs. + +%--------------------------------------------------------------------- +\item[\tr{lib}:] +Move this directory, in toto, to wherever you want it to live. +It should still be called \tr{lib}. + +%--------------------------------------------------------------------- +\item[\tr{docs}:] +This is the full \tr{docs} tree. Just follow the normal instructions, +in \sectionref{make-docs}. +\end{description} + +Things you need to fiddle so the tools will spring to life: +\begin{enumerate} +\item +\tr{rehash} (csh users), so your shell will see the new stuff in your +bin directory. + +\item +CHOICE \#1 (BETTER): +Edit your \tr{ghc}, \tr{mkdependHS}, and \tr{hstags} scripts: +(a)~Create a correct \tr{#!...perl} first line in each one. (Ask a +Unix-friendly person to help you, if you don't know what a +\tr{#!}-line is.) (b) Find the line that looks something like: +\begin{verbatim} +# $ENV{'GLASGOW_HASKELL_ROOT'} = '/some/absolute/path/name'; +\end{verbatim} +Remote the comment symbol (\tr{#}) on the front, and change the +path name to be the right thing. + +So, if your ``lib'' files are now in \tr{/home/myself/lib/ghc/...}, +then you should set \tr{GLASGOW_HASKELL_ROOT} to \tr{/home/myself}. + +\item +CHOICE \#2: +Set your \tr{GLASGOW_HASKELL_ROOT} environment variable, and +don't edit the \tr{ghc}, \tr{mkdependHS}, and \tr{hstags} scripts +at all. + +It's better to edit the scripts; that way, it's once for all. + +\item +You {\em may} need to re-\tr{ranlib} your libraries (on Sun4s). +\begin{verbatim} +% cd <wherever-the-lib-files-are-now>/ghc/0.26/sparc-sun-sunos4 +% foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv... +? ranlib $i +? # or, on some machines: ar s $i +? end +\end{verbatim} + +\item +Once done, test your ``installation'' as suggested in +\sectionref{GHC_test}. Be sure to use a \tr{-v} option, so you +can see exactly what pathnames it's using. + +If things don't work, double-check your hand-edited path +names. Things will go catastrophically wrong as long as they are +incorrect. +\end{enumerate} + +%************************************************************************ +%* * +\subsection[non-GHC-bin-distrib]{Other tools from binary distributions} +%* * +%************************************************************************ + +NOT DONE YET. + +All of the above is for GHC bundles. For other tools, the same +principles apply: get the binary bundles you want, then unpack them +all together in the same place. + +%************************************************************************ +%* * +%\subsection[dumped-from-build]{Installing a ``dumped-from-build'' binary distribution (some platforms)} +%* * +%************************************************************************ +%#% +%#% Sometimes, a binary distribution is taken directly from a GHC +%#% ``build.'' An example is the Solaris distribution. You can tell from +%#% the layout of the files. +%#% +%#% The setup required is nearly the same as a ``regular'' binary +%#% distribution; only some names are different. +%#% \begin{enumerate} +%#% \item +%#% Get the user-executable scripts into your PATH, either by copying it +%#% or by linking to it. These are in: +%#% \begin{verbatim} +%#% <topdir>/ghc/driver/ghc +%#% <topdir>/ghc/utils/mkdependHS/mkdependHS +%#% <topdir>/ghc/utils/hstags/hstags +%#% \end{verbatim} +%#% +%#% \item +%#% Set the \tr{GLASGOW_HASKELL_ROOT} environment variable for the three +%#% scripts above, in the manner outlined in the previous section. +%#% +%#% \item +%#% Possibly re-\tr{ranlib}'ing your \tr{*.a} files: +%#% \begin{verbatim} +%#% % cd <topdir> +%#% % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv... +%#% % ranlib $i +%#% % # or, on some machines: ar s $i +%#% % end +%#% \end{verbatim} +%#% +%#% \item +%#% Don't forget to test it! +%#% \end{enumerate} + +%************************************************************************ +%* * +\section[checklist]{Building Glasgow tools from source: a checklist} +%* * +%************************************************************************ + +\begin{enumerate} +\item +Install any pre-supposed utility programs that you do not have at your +site. You have to do this ``by hand.'' It's not hard, and these are +things you want to have anyway. Please see \sectionref{Pre-supposed}. + +\item +Be sure you have a suitable Haskell compiler, or else the intermediate +C (\tr{.hc}) files. In some cases, you might want an alternative set +of interface (\tr{.hi}) files (quicker than generating a fresh set). +\Sectionref{install-strategy} lists the various strategies you might +adopt. + +If you don't have a Haskell compiler, the most painless option is to +use a binary-distributed GHC to compile Glasgow tools (including GHC +itself) from source. Installing a binary distribution (the first +step) is described in \sectionref{installing-bin-distrib}. + +\item +You might want to write-protect your source files at this point: +\begin{verbatim} +cd <the-very-top-dir> +find . -type f \! -name \*.hi \! -name \*.hc \! -name \*.jm -print \ + | xargs chmod a-w +\end{verbatim} + +\item +Run the \tr{configure} script. It is a shell script that looks around +to find out things about your system. You can see the \tr{configure} +options by passing it a \tr{--help} flag, or by reading +\sectionref{Configuring}. + +\item +Once configured, build the basic support utilities and make your +Makefiles, including the automagically-created dependencies between +files. The near-universal incantation is: +\begin{verbatim} +% cd <the-very-top-dir> +% sh < STARTUP >& startup.log # and chk the log afterwards! +\end{verbatim} + +\item +Build the Glasgow tools you are interested in, as \tr{STARTUP} suggests: +\begin{verbatim} +% cd <the-very-top-dir>/<tool> +% make all >& make.log # time to go to lunch! +\end{verbatim} +Consult the list of known pitfalls (\sectionref{build-pitfalls}) if +something goes wrong. + +\item +Test what you've built, enough to know that it's working. + +\item +Actually install the tools, if you wish: +\begin{verbatim} +% cd <the-very-top-dir>/<tool> +% make install +\end{verbatim} + +\item +Make and/or install the documentation. + +\item +Save a copy of your \tr{config.status} file, for the next +even-more-wonderful release! + +\item +If you're finished, tidy up after yourself [\tr{make clean}], if you +want to. + +Alternatively, \tr{/bin/rm -rf <tool>} :-) +\end{enumerate} + +%************************************************************************ +%* * +\section[building-GHC]{Building the Glasgow Haskell Compiler (GHC)} +\index{GHC installation, from sources} +%* * +%************************************************************************ + +%************************************************************************ +%* * +\downsection +\section{Building GHC from source, compiling it with itself} +\index{building GHC with itself} +\index{booting GHC with itself} +%* * +%************************************************************************ + +This section describes how to build GHC from source. You would do +this if (a)~there is no ``canned'' binary distribution for your +machine, (b)~the binary distribution omits features that you want, +(c)~you want to make changes to GHC and them build them in, or +(d)~you like torturing yourself. + +This blow-by-blow description follows the general checklist in +\sectionref{checklist}. + +%************************************************************************ +%* * +\subsection[Right-compiler-and-files]{Do you have a suitable compiler and/or \tr{.hc} files and/or \tr{.hi} files?} +\index{booting GHC, files needed} +%* * +%************************************************************************ + +We now proceed through each installation step, carefully. + +Because the compiler heart of Glorious Glasgow Haskell is written in +Haskell, you have to use some ``bootstrapping'' mechanism. + +Your best choice, if available, is to use a binary distribution for +your platform; i.e., compile GHC~0.26 with a GHC~0.26 that we have +provided. Please see \sectionref{installing-bin-distrib} for how to +install a binary distribution. + +Your remaining choice is to use the intermediate C (\tr{.hc}) files that we +supply. This is the {\em only} choice for anyone trying to port to +a new or weakly-supported system. + +The main drawback of the supplied-\tr{.hc} approach is that you will +have a lot of very bulky intermediate files on your disk for a while. + +One obscure note: if you're going to build GHC to have a native-code +generator, you're well advised to get a suitable set of interface +files (to save making them yourself). Please see \sectionref{Compiler_reconfig} +if you plan to end up with a native-code generator. + +% If you have to boot from C (\tr{.hc}) files, you should follow the +% directions in \sectionref{booting-from-C}. + +% We also supply parts of the system pre-compiled to C (in \tr{.hc} +% files). This is partly to save you work (you don't have to wait for +% them to compile yourself) and partly because this is how we will +% eventually supply the self-compiling compiler (when that's ready). +% In any case, if you slurped the \tr{.tar.gz} file, you should, {\em in +% the same directory as before}, do... +% \begin{verbatim} +% % gunzip -c ghc-<version>-hc-files.tar.gz | tar xfv - +% \end{verbatim} + +%************************************************************************ +%* * +\subsection{Write-protecting your source files} +\index{write-protecting source files} +%* * +%************************************************************************ + +At this point, some people like to write-protect their source files against +inadvertent change: +\begin{verbatim} +cd <very-top-dir> +find . -type f \! -name '*.hi' \! -name \*.hc \! -name '*.jm' -print \ + | xargs chmod a-w +\end{verbatim} + +%************************************************************************ +%* * +\subsection{Running \tr{configure} and \tr{STARTUP} for GHC} +\index{configure, for GHC} +\index{STARTUP, for GHC} +%* * +%************************************************************************ + +The \tr{configure} script finds out things about your machine. It +also allows you to specify features to include/exclude from your GHC +installation. + +Please see \sectionref{Configuring} for all about \tr{configure}, and +\sectionref{Configuring-GHC} for details of GHC configuring (including +examples). + +Once \tr{configure} runs successfully, do as it says and do +\tr{sh < STARTUP}. + +%************************************************************************ +%* * +\subsection{Build the compiler!} +\index{make all, for GHC} +%* * +%************************************************************************ + +Do the main GHC build, just as \tr{STARTUP} suggests: +\begin{verbatim} +% cd ghc +% make all >& make.log +\end{verbatim} +If this fails or something seems suspicious, check the ``known +pitfalls'' (\sectionref{build-pitfalls}). If you can't figure out how +to proceed, please get in touch with us. + +If you have to restart the build, for whatever reason, you are just as +well to make the whole thing; i.e., re-do as described above. (Well, +the \tr{compiler} and \tr{lib} subdirectories are the last two; if the +build ``dies'' in one of them, it is usually safe to finish the job by +hand.) + +%************************************************************************ +%* * +\subsection[GHC_test]{Test that GHC seems to be working} +\index{testing a new GHC} +%* * +%************************************************************************ + +The way to do this is, of course, to compile and run {\em this} program +(in a file \tr{Main.hs}): +\begin{verbatim} +main = putStr "Hello, world!\n" +\end{verbatim} + +First, give yourself a convenient way to execute the driver script +\tr{ghc/driver/ghc}, perhaps something like... +\begin{verbatim} +% ln -s /local/src/ghc-0.26/ghc/driver/ghc ~/bin/sun4/ghc +% rehash +\end{verbatim} + +Compile the program, using the \tr{-v} (verbose) flag to verify that +libraries, etc., are being found properly: +\begin{verbatim} +% ghc -v -o hello -fhaskell-1.3 Main.hs +\end{verbatim} + +Now run it: +\begin{verbatim} +% ./hello +Hello, world! +\end{verbatim} + +Some simple-but-profitable tests are to compile and run the +notorious \tr{nfib} program, using different numeric types. Start +with \tr{nfib :: Int -> Int}, and then try \tr{Integer}, \tr{Float}, +\tr{Double}, \tr{Rational} and maybe \tr{Complex Float}. Code +for this is distributed in \tr{ghc/misc/examples/nfib/}. + +For more information on how to ``drive'' GHC, +either do \tr{ghc -help} or consult the User's Guide (distributed in +\tr{ghc/docs/users_guide}). + +%************************************************************************ +%* * +\subsection[GHC_install]{Actually installing GHC} +\index{make install, GHC} +\index{installing, GHC} +%* * +%************************************************************************ + +``Installing GHC'' means copying the files required to run it to their +``permanent home.'' You can then delete, or at least tidy up, your +source directory. + +If you have no reason to install GHC, you can execute directly out of +the source tree, as sketched in the section above +(\sectionref{GHC_test}). + +Assuming that everything's OK so far, all you need to do is: +\begin{verbatim} +% cd <very-top>/ghc +% make install +\end{verbatim} + +If you're a little dubious (as I usually am), you can always do a +``trial run'' first: +\begin{verbatim} +% cd <very-top>/ghc +% make -n install >& temp-log-file-to-look-at +\end{verbatim} + +In both cases, if something breaks, it's a {\em bug}. + + +%************************************************************************ +%* * +\subsection[make-docs]{Installing the GHC documentation (optional)} +\index{documentation, making} +\index{make docs, GHC} +\index{installing documentation} +%* * +%************************************************************************ + +Because our documentation is in DVI/Info formats, and because there is +no standard practice about how such documents are ``installed,'' we +haven't tried to automate this (at least not enough that we promise it +works). + +You can find all the documentation in the distribution with: +\begin{verbatim} +% cd ghc/docs +% find . \( -name '*.dvi' -o -name '*.info' -o -name '*.html' \) -print +\end{verbatim} + +If you have a standard place to put such files, just copy +them there. (Better ideas welcome.) + +The following ``man'' pages are hidden around in the distribution: +\begin{verbatim} +ghc/utils/hp2ps/hp2ps.1 +literate/info-utils/info.1 +glafp-utils/scripts/mkdirhier.man +glafp-utils/scripts/lndir.man +\end{verbatim} +Please install them by hand if you need to. + +%There are various pieces of GHC whose code can be formatted +%``literately.'' The usual procedure is... +%\begin{verbatim} +%% cd ghc/<wherever> +%% make depend # VERY IMPORTANT for literate docs! +%% make docs # or more directly.... +%% make whatever.dvi # or, for Info freaks,... +%% make whatever.info +%\end{verbatim} + +%For ``chunks'' of the compiler proper, in \tr{ghc/compiler}, you will +%need to make a \tr{Makefile} for them first: +%\begin{verbatim} +%cd ghc/compiler +%make Makefile SUBDIRS=prelude # for example... +%cd prelude +%make depend # i.e., as before +%make prelude.dvi +%\end{verbatim} +%Directories for which this {\em might} (I emphasize: `MIGHT') work are ... +%\begin{verbatim} +%codeGen/Jmakefile +%coreSyn/Jmakefile +%deSugar/Jmakefile +%podizeCore/Jmakefile +%prelude/Jmakefile +%typecheck/Jmakefile +%\end{verbatim} +% +%Remember: an unpatched perl 4.035 will {\em crash} on making many of +%our ``literate'' Info files. (The current version, 4.036, will not.) + +%$$ Note: Because we make our Info files by going through Texinfo format, +%$$ you can use \tr{texi2html} to produce HTML files. A +%$$ minisculely-hacked version is in the distribution in +%$$ \tr{literate/texi2html/texi2html}. + +%************************************************************************ +%* * +\subsection[clean-up]{Cleaning up after yourself} +\index{make clean, GHC} +\index{cleaning up afterwards} +%* * +%************************************************************************ + +\tr{make clean} is the basic command to tidy things up. However: if +you do this, {\em you will not be able to execute directly out of the +source tree thereafter!} (as sketched in \sectionref{GHC_test}). Nor will +you be able to make documents, etc.---you would have to re-build parts +of GHC first. + +If you want to execute out of the source tree but would like to clear +off lots and lots of stuff, you can do: +\begin{verbatim} +% cd ghc/lib # scrub library C and object files +% rm */*.hc +% find . -name '*.o' -print | xargs /bin/rm + +% cd ghc/compiler # scrub compiler object files +% rm */*.o +% rm */*.hc # if you have been keeping them around +\end{verbatim} +(You can scrub the object files in \tr{ghc/runtime} similarly---except +\tr{main/TopClosure*.o}.) + +%\tr{make veryclean} is the command to clear off everything that can be +%safely cleared off. Not recommended (inadequately tested). + +%************************************************************************ +%* * +\section[booting-from-C]{Booting/porting from C (\tr{.hc}) files} +\index{building GHC from .hc files} +\index{booting GHC from .hc files} +%* * +%************************************************************************ + +This section is for people trying to get GHC going by using the +supplied intermediate C (\tr{.hc}) files. This would probably be +because no binaries have been provided, or because the machine +is not ``fully supported.'' + +To boot from C (\tr{.hc}) files, you need the regular source distribution +(\tr{ghc-0.26-src.tar.gz}) and also some extra files in +\tr{ghc-0.26-hc-files.tar.gz}. DON'T FORGET any extra \tr{.hc} +files for profiling, concurrent, parallel, ... + +Whatever you want to build, just unpack all the files ``together'': +\begin{verbatim} +% cd <wherever> +% gunzip -c ghc-0.26-src.tar.gz | tar xf - +% gunzip -c ghc-0.26-hc-files.tar.gz | tar xf - # basic... +% gunzip -c ghc-0.26-prof-hc-files.tar.gz | tar xf - # profiling... +% gunzip -c ghc-0.26-conc-hc-files.tar.gz | tar xf - # concurrent... +... etc ... +\end{verbatim} + +For the ``it's been tried before'' machines, the normal +configure/build procedure will probably work; just keep your eyes +peeled for mischief. + +WORD OF WISDOM: Be sure you have a suitable GCC (GNU C compiler); please +see \sectionref{port-info} for any specific requirements for your machine. + +You'll need plenty of disk space to do this whole procedure! + +%$$ %************************************************************************ +%$$ %* * +%$$ \subsection[boot-file-fiddling]{Unpack; then fiddle files before booting} +%$$ %* * +%$$ %************************************************************************ +%$$ +%$$ Unpack the relevant files for booting as described above. +%$$ +%$$ If you are on a never-seen-before platform, then there is a little +%$$ machine-specific code/stuff scattered around the GHC files, which will +%$$ need to be updated before you get started. +%$$ +%$$ \begin{description} +%$$ %--------------------------------------------------------------------- +%$$ \item[Change \tr{configure}, so it recognizes your machine:] +%$$ Add the obvious stuff if it says ``Unrecognised platform for GHC.'' +%$$ +%$$ If you are teaching GHC how to ``registerise'' on a new platform, you +%$$ will also need to make sure the variable @GhcWithRegisterised@ is set +%$$ correctly. +%$$ +%$$ %--------------------------------------------------------------------- +%$$ \item[Change {\em two} copies of \tr{platform.h.in}:] +%$$ In the obvious way. They are in \tr{ghc/includes/} and \tr{mkworld/}. +%$$ +%$$ %--------------------------------------------------------------------- +%$$ \item[Floating-pointness:] +%$$ Grep for \tr{_TARGET} in \tr{ghc/includes/*.*h} and make suitable +%$$ adjustments. +%$$ +%$$ One change you will certainly make is in \tr{StgMacros.lh}, to decide +%$$ the inclusion of \tr{ieee-flpt.h} and \tr{BIGENDIAN}. +%$$ +%$$ Please use the CPP symbols defined in \tr{platform.h.in}! +%$$ +%$$ %--------------------------------------------------------------------- +%$$ \item[64-bitness:] +%$$ Again, grepping for \tr{_TARGET} in \tr{ghc/includes/*.lh} will find +%$$ the places that need adjusting. \tr{GhcConstants.lh} and +%$$ \tr{StgTypes.lh} are two places that will need tweaking, for example. +%$$ +%$$ %--------------------------------------------------------------------- +%$$ \item[``Registerizing'' magic:] +%$$ This is the platform-specific stuff in \tr{COptJumps.lh}, +%$$ \tr{COptWraps.lh}, and \tr{MachRegs.lh} in \tr{ghc/includes}. +%$$ +%$$ If you are doing an initial unregisterised boot for your platform, you +%$$ don't need to mess with these files at all. +%$$ +%$$ \Sectionref{real-version-from-init-boot} discusses how to get a +%$$ ``registerised'' version of GHC going. (Much trickier, but much +%$$ faster. [0.26: and the documentation is OUT-OF-DATE]) +%$$ +%$$ %--------------------------------------------------------------------- +%$$ \item[Host/target platforms in the driver:] +%$$ Grep for all occurrences of \tr{$HostPlatform} and \tr{$TargetPlatform} +%$$ in \tr{ghc/driver/*.lprl}. +%$$ +%$$ Don't worry about the \tr{process_asm_block} stuff in +%$$ \tr{ghc-split.lprl}. Not used in a straight ``unregisterised'' +%$$ version. +%$$ +%$$ %--------------------------------------------------------------------- +%$$ \item[Target-specific GCC flags in the driver:] +%$$ +%$$ The main thing to worry about in \tr{ghc.lprl} is the section on how +%$$ to ``Add on machine-specific C-compiler flags.'' +%$$ You may want to add something {\em vaguely} like: +%$$ \begin{verbatim} +%$$ ... +%$$ } elsif ($TargetPlatform =~ /^mips-dec-ultrix/) { +%$$ unshift(@CcBoth_flags, ('-G0', '-static')) if $GccAvailable; +%$$ \end{verbatim} +%$$ +%$$ Explanations: (1)~Static linking {\em tends} to give less problems, so +%$$ it is a reasonable choice for an initial attempt. +%$$ +%$$ (2)~In processing +%$$ the intermediate C (\tr{.hc}) files, you are compiling some {\em huge} +%$$ wads of C. Sadly, quite a few systems don't cope well with this, and +%$$ more than a few silently produce object files that won't link. GCC +%$$ usually provides some platform-specific flag that says ``generate code +%$$ that will work no matter how big the files are''. The \tr{-G0} for +%$$ DEC MIPS boxes is an example. If your system has such restrictions, +%$$ insert some magic {\em here}! +%$$ \end{description} + +%************************************************************************ +%* * +\subsection{Do \tr{configure}; \tr{sh < STARTUP}; \tr{cd ghc; make all}; test it!} +\index{configure, GHC with .hc files} +\index{make all, GHC with .hc files} +%* * +%************************************************************************ + +Go ahead and try \tr{configure}, as described \Sectionref{Configuring} +(GHC specifics in \Sectionref{Configuring-GHC}). + +The key \tr{configure} option is \tr{--with-hc=c}. A typical +going-via-C invocation might be: + +\begin{verbatim} +% ./configure --prefix=/local/fp --with-hc=c # basic + profiling +\end{verbatim} + +Other common possibilities might be: + +\begin{verbatim} +% ./configure --with-hc=c --disable-profiling # basic only + +% ./configure --with-hc=c --enable-concurrent --enable-parallel + # basic + profiling + concurrent + parallel +\end{verbatim} + +%$$ One likely reason it won't work is it will say it never heard of your +%$$ machine. Just edit the script and carry on! (As always, please send +%$$ us the changes.) + +Next, run \tr{STARTUP} in the usual way, as described in +\Sectionref{STARTUP}. + +It's now time to type \tr{cd ghc; make all}! This ``should'' work, +especially, on a known machine. Also, it can take a VERY long time +(esp. on oldish machines), so it's good to run overnight, on a quiet +machine, nice'd, etc., etc. + +When it's all built, test your alleged GHC system, as suggested in +\sectionref{GHC_test}. + +%$$ What you should end up with, built in this order: (1)~a runtime system +%$$ [\tr{ghc/runtime/libHSrts_ap.a}]; (2)~Prelude libraries +%$$ [\tr{ghc/lib/libHS_ap.a} and \tr{ghc/lib/libHShbc_ap.a}]; and (3)~a +%$$ compiler [\tr{ghc/compiler/hsc}] (which needs the first two). +%$$ +%$$ (Umm... if you are on a supported platform, but compiling via C, then +%$$ the \tr{*.a} suffixes will be \tr{_ap_o.a} (regular) and \tr{_p.a} +%$$ (profiling).) + +%$$ %************************************************************************ +%$$ %* * +%$$ \subsubsection{A pre-emptive \tr{hello, world} test} +%$$ %* * +%$$ %************************************************************************ +%$$ +%$$ On an unsupported platform, +%$$ You very well may want to {\em kill the compilation} once +%$$ \tr{libHSrts_ap.a} and \tr{libHS_ap.a} are built, to do a little +%$$ pre-emptive testing: time to run \tr{Hello, world!}. Using +%$$ \tr{ghc/CONTRIB/hello.hc}... +%$$ \begin{verbatim} +%$$ % .../ghc/driver/ghc -c -g hello.hc +%$$ % .../ghc/driver/ghc -v -o hello -g hello.o +%$$ % ./hello +%$$ \end{verbatim} +%$$ +%$$ If you have any trouble to do with ``consistency checking,'' just +%$$ avoid it, with the \tr{-no-link-chk} flag. +%$$ +%$$ If \tr{hello} crashes/breaks, it's time for Ye Olde Debugger, or +%$$ perhaps Ye Older Cry for Help... +%$$ +%$$ If things are OK and if you {\em did} kill the compilation, just re-do +%$$ \tr{make} to finish the job (build any other libraries, then the +%$$ compiler binary \tr{ghc/hsc}). +%$$ +%$$ %************************************************************************ +%$$ %* * +%$$ \subsubsection[init-boot-hsc]{Finishing the initial boot} +%$$ %* * +%$$ %************************************************************************ +%$$ +%$$ If you manage to get a \tr{ghc/hsc} binary (usually huge), then... +%$$ YOU HAVE A HASKELL COMPILER, albeit big and slow! So test it, +%$$ ``from the sources,'' before installing it: +%$$ \begin{verbatim} +%$$ % cat > test.hs +%$$ main = print ((10001 - 30002)::Integer) +%$$ -- or any other program(s) you want... +%$$ ^D +%$$ % .../ghc/driver/ghc -v -g -c test.hs +%$$ % .../ghc/driver/ghc -v -g -o test test.o +%$$ % ./test +%$$ \end{verbatim} +%$$ (Note how I fiendishly included a \tr{-g}, in case I had to throw a +%$$ debugger at it...) +%$$ +%$$ Of course, you {\em may not} have a \tr{ghc/hsc} binary---something +%$$ went wrong. The most likely cause is a compiler/assembler/linker +%$$ failure due to the HUGE size of this program. Please revisit the +%$$ discussion about this towards the end of +%$$ \sectionref{boot-file-fiddling}. Sadly, if you have to tweak +%$$ C-compiler/whatever flags, you may have to rebuild all the +%$$ libraries/compiler again; the following is sufficient to clear +%$$ off everything for a fresh start (NB: don't do \tr{make clean}): +%$$ \begin{verbatim} +%$$ % cd ghc/runtime # clear off RTS +%$$ % make clean SUBDIRS=foo # but avoid clearing GMP lib +%$$ % cd ../lib +%$$ % rm */*.o +%$$ % cd ../compiler +%$$ % rm */*.o +%$$ \end{verbatim} +%$$ +%$$ %************************************************************************ +%$$ %* * +%$$ \subsubsection[installing-init-boot]{`Installing' the initial boot} +%$$ %* * +%$$ %************************************************************************ +%$$ +%$$ If you are satisfied that things are working, {\em possibly install} the +%$$ initial booted version. The main point is: save the precious files +%$$ you've just created. +%$$ +%$$ Should you choose {\em not to install}, be sure to secure these files +%$$ somewhere/somehow: +%$$ \begin{verbatim} +%$$ ghc/compiler/hsc # compiler +%$$ ghc/runtime/libHSrts_ap.a # RTS things +%$$ ghc/lib/libHS_ap.a # prelude library +%$$ \end{verbatim} +%$$ +%$$ Should you install, the comments about `normal' installing, in +%$$ \Sectionref{GHC_install}, do apply. It should come down to +%$$ something like... +%$$ \begin{verbatim} +%$$ % cd ghc +%$$ % make -n install >& temp-log-file-to-look-at # trial run: chk it out! +%$$ % make install # the real thing... +%$$ \end{verbatim} +%$$ +%$$ (I'd probably do the install by hand, if at all; let me know if you're +%$$ worried about the exact incantations.) +%$$ +%$$ %************************************************************************ +%$$ %* * +%$$ \subsubsection[testing-init-boot]{Testing the initial boot} +%$$ %* * +%$$ %************************************************************************ +%$$ +%$$ It wouldn't be a bad idea, especially on an unusual machine; I usually +%$$ just skip this part, though :-) +%$$ +%$$ %************************************************************************ +%$$ %* * +%$$ \subsection[split-libs]{Getting ``splitting'' going on your Prelude libraries} +%$$ %* * +%$$ %************************************************************************ +%$$ +%$$ ghc-split.lprl +%$$ +%$$ %************************************************************************ +%$$ %* * +%$$ \subsection[real-version-from-init-boot]{Getting a ``registerised'' version going} +%$$ %* * +%$$ %************************************************************************ +%$$ +%$$ Version 0.26: THIS DOCUMENTATION IS OUT-OF-DATE. (Sigh) +%$$ +%$$ %************************************************************************ +%$$ %* * +%$$ \subsubsection[registerised-magic-files]{Setting up files for `registerizing'} +%$$ %* * +%$$ %************************************************************************ +%$$ +%$$ It's time to jiggle some files related to GCC-magic-optimisation. +%$$ {\em This is real work, folks.} What follows is a {\em rough} guide to +%$$ what needs looking at. +%$$ +%$$ \begin{description} +%$$ %--------------------------------------------------------------------- +%$$ \item[\tr{ghc/includes/MachRegs.lh}:] +%$$ This maps ``STG registers'' (Hp, SpA, TagReg, etc.) to machine +%$$ registers on a platform-by-platform basis. +%$$ If you can't figure it out, you'd probably better ask. +%$$ +%$$ We are using a GCC extension to put C global variables in specific +%$$ registers; see the \tr{Global Reg Vars} node in the GCC documentation. +%$$ +%$$ You should get the idea from the settings for our ``fully supported'' +%$$ platforms, but you will need to know/learn something about your +%$$ hardware and your GCC (e.g., what registers it snaffles for itself). +%$$ +%$$ One way I went about learning these register secrets was to try the +%$$ following test file (a Sun3 version here, \tr{regs3.hc}): +%$$ \begin{verbatim} +%$$ #define StgPtr long int * +%$$ +%$$ register StgPtr FooL0 __asm__("a0"); +%$$ register StgPtr FooL1 __asm__("a1"); +%$$ register StgPtr FooL2 __asm__("a2"); +%$$ register StgPtr FooL3 __asm__("a3"); +%$$ register StgPtr FooL4 __asm__("a4"); +%$$ register StgPtr FooL5 __asm__("a5"); +%$$ register StgPtr FooL6 __asm__("a6"); +%$$ register StgPtr FooL7 __asm__("a7"); +%$$ +%$$ register StgPtr FooG0 __asm__("d0"); +%$$ register StgPtr FooG1 __asm__("d1"); +%$$ register StgPtr FooG2 __asm__("d2"); +%$$ register StgPtr FooG3 __asm__("d3"); +%$$ register StgPtr FooG4 __asm__("d4"); +%$$ register StgPtr FooG5 __asm__("d5"); +%$$ register StgPtr FooG6 __asm__("d6"); +%$$ register StgPtr FooG7 __asm__("d7"); +%$$ +%$$ wurble(x) +%$$ int x; +%$$ { +%$$ return (x + 42); +%$$ } +%$$ \end{verbatim} +%$$ Then compile it repeatedly with your new driver, e.g., +%$$ \tr{ghc-boot-me -v -S regs3.hc}, removing register declarations that +%$$ offend it. Note: GCC's error messages about these register things +%$$ can be less than totally enlightening. +%$$ +%$$ Note: don't worry about warnings that you're stealing a +%$$ ``call-clobbered'' (caller-saves) register. These are stealable, +%$$ though some extra work may be required. +%$$ +%$$ %--------------------------------------------------------------------- +%$$ \item[\tr{ghc/includes/COptJumps.lh}:] +%$$ The name of the game, essentially, is for the @JMP_@ macro to turn +%$$ into a simple jump instruction. Also, through fiendish collaboration +%$$ with the assembly-language post-processor in the driver (coming up +%$$ soon...), we're going to rip out all the pushing/popping to do with +%$$ the C stack. +%$$ +%$$ You {\em may} need to do something as on 680x0s, where we inject +%$$ beginning-of- and end-of-real-code markers, which gives the post-processor +%$$ something to look out for and tidy up around. +%$$ +%$$ You also need to define some mini-interpreter-related macros. These +%$$ are discussed under \tr{StgMiniInt.lc} (below). +%$$ +%$$ %--------------------------------------------------------------------- +%$$ \item[\tr{ghc/includes/COptWraps.lh}:] +%$$ +%$$ The macro @STGCALL1(f,a)@ is defined here; it almost certainly should +%$$ just be \tr{callWrapper(f,a)} (where the magical routine @callWrapper@ +%$$ is yet to come). +%$$ +%$$ %--------------------------------------------------------------------- +%$$ \item[\tr{ghc/driver/ghc-asm-<arch>.lprl}:] +%$$ This is the notorious ``optimised assembler post-processor.'' You +%$$ need to create a suitable \tr{require}-able file (if you haven't +%$$ already), add a mention in the \tr{Jmakefile}, and add suitable code +%$$ in the driver, \tr{ghc.lprl} to invoke it. +%$$ +%$$ This is really quite horrible for a SPARC; we have to shut down the +%$$ register-window mechanism {\em entirely}, by ripping out all the +%$$ \tr{save} and \tr{restore} instructions. +%$$ +%$$ We also go to lots of trouble to move info tables next to entry code, +%$$ elide slow and fast entry-point routines, and probably some things +%$$ I've forgotten about. +%$$ +%$$ Ask if you are desperately confused... +%$$ +%$$ Perhaps it will be less gruesome for your machine! +%$$ +%$$ Don't forget to test it with \tr{-g} turned on (lots of \tr{\.stab?} +%$$ lines suddenly appear)... +%$$ +%$$ %--------------------------------------------------------------------- +%$$ \item[\tr{CallWrap_C.lc} or \tr{CallWrapper.ls}, in ghc/runtime/c-as-asm/:] +%$$ +%$$ These files have register saving/restoring code. For a SPARC, quite a +%$$ bit has to be written in assembly language (\tr{CallWrapper.ls}), to +%$$ avoid register windowing; but, for other machines, the C versions +%$$ (\tr{CallWrap_C.lc}) should work fine. +%$$ +%$$ Look at the generated assembly-language very carefully! +%$$ +%$$ %--------------------------------------------------------------------- +%$$ \item[ghc/runtime/c-as-asm/StgMiniInt.lc:] +%$$ +%$$ You need to manage to create entry points named @miniInterpret@ and +%$$ @miniInterpretEnd@, the former to jump off into threaded code; the +%$$ latter to come back to. +%$$ +%$$ You may be able to do something quite simple---it's not bad either for +%$$ mc680x0s or SPARCs---but you will want to inspect the assembler output +%$$ before declaring victory. +%$$ +%$$ In the SPARC case, it uses a macro (@MINI_INTERPRETER_END_IS_HERE@) +%$$ defined in \tr{imports/COptJumps.lh}. +%$$ \end{description} +%$$ +%$$ %************************************************************************ +%$$ %* * +%$$ \subsubsection[testing-registerisation]{Initial testing of a `registerisation'} +%$$ %* * +%$$ %************************************************************************ +%$$ +%$$ {\em How to begin testing this registerised stuff:} +%$$ +%$$ Make sure your imports files are up-to-date: +%$$ \begin{verbatim} +%$$ % cd ghc/includes +%$$ % make +%$$ \end{verbatim} +%$$ +%$$ Park yourself in your driver subdirectory and ... +%$$ \begin{verbatim} +%$$ % cd ghc/driver # park +%$$ % make Makefile # if you changed "only4-ghc.ljm"... +%$$ % make # just to be sure +%$$ +%$$ % cp ../compiler/utils/Util.hc temp.hc # grab a test file; +%$$ # you may want to chop it down +%$$ % ghc-boot-me -v -S -ddump-raw-asm temp.hc # see what happens! +%$$ \end{verbatim} +%$$ +%$$ (The \tr{-ddump-raw-asm} option shows you, on stderr, what comes +%$$ directly out of GCC. That's what your post-processing mangler has to +%$$ chomp on.) +%$$ +%$$ {\em Going further on testing this stuff:} +%$$ +%$$ Another good place to practice is \tr{ghc/runtime}; so, for example: +%$$ \begin{verbatim} +%$$ % cd ghc/runtime +%$$ % make Makefile +%$$ % make clean +%$$ % make libHSrts_ap_o.a +%$$ \end{verbatim} +%$$ +%$$ The .s output from \tr{main/StgUpdate.lhc} can be particularly +%$$ enlightening, in that, if you are going to have register spills (e.g., +%$$ because your registerisation choices left GCC with too few with which +%$$ to generate good code), you will see it on this file. +%$$ +%$$ Don't forget: you need a working \tr{CallWrapper.ls} and +%$$ \tr{StgMiniInt.lc} (both in \tr{c-as-asm}) before this registerised +%$$ stuff will actually run. +%$$ +%$$ %************************************************************************ +%$$ %* * +%$$ \subsubsection[building-registerized]{Building the basics of a registerised GHC} +%$$ %* * +%$$ %************************************************************************ +%$$ +%$$ \begin{description} +%$$ %--------------------------------------------------------------------- +%$$ \item[What you need to run a registerised program:] +%$$ +%$$ Once you make a \tr{libHSrts_ap_o.a} in runtime, all you need is a +%$$ prelude library. You need to do it by hand still. +%$$ \begin{verbatim} +%$$ % cd ghc/lib +%$$ % ghc-boot-me -c -g -O -osuf _ap_o.o */*.hc # takes a while +%$$ % +%$$ % rm libHS_ap_o.a +%$$ % ar clq libHS_ap_o.a */*_ap_o.o +%$$ % ranlib libHS_ap_o.a +%$$ \end{verbatim} +%$$ +%$$ %--------------------------------------------------------------------- +%$$ \item[Testing the registerised GHC:] +%$$ +%$$ As before, starting with the \tr{.hc} you made in the first round: +%$$ \begin{verbatim} +%$$ % ghc-boot-me -v -g -c test.hc +%$$ % ghc-boot-me -v -g -o test test.o +%$$ % ./test +%$$ \end{verbatim} +%$$ +%$$ If things are broken, the likely outcome is a core dump, and you'll +%$$ need to throw GDB (or equiv) at it. Useful breakpoints are +%$$ \tr{main}, \tr{miniInterpret}, \tr{Main_main_entry}, and +%$$ \tr{startStgWorld} (when you're just getting going), and +%$$ \tr{stopStgWorld} and \tr{miniInterpretEnd} (which can show that you +%$$ ``almost made it''). +%$$ +%$$ %--------------------------------------------------------------------- +%$$ \item[If you get a consistency-checking error:] +%$$ +%$$ [From the driver] (These are not as terrible as they seem...) +%$$ +%$$ The driver, notably \tr{driver/ghc-consist.lprl}, runs the SCCS +%$$ program \tr{what} over your executable, and tries to make sense of the +%$$ output. +%$$ +%$$ If you need to make changes to \tr{ghc-consist.lprl}, just do so, then +%$$ re-\tr{make} in the driver directory. +%$$ +%$$ %--------------------------------------------------------------------- +%$$ \item[Compiling the compiler registerisedly:] +%$$ +%$$ If you can successfully compile and run {\em some} registerised +%$$ programs, you are probably ready to compile the compiler in that way. +%$$ \begin{verbatim} +%$$ % cd ghc/compiler +%$$ % ghc-boot-me -c -g -O */*.hc # takes *much more* than a while +%$$ % ghc-boot-me -g -O -o hsc */*.o # LINK! +%$$ \end{verbatim} +%$$ +%$$ (Sun3 note: on the particular system I used, I had link troubles. It +%$$ was apparently a Sun bug, because I got a successful link with the GNU +%$$ linker.) +%$$ +%$$ %--------------------------------------------------------------------- +%$$ \item[Testing the {\em whole} registerised GHC:] +%$$ +%$$ As before, but now you can try compiling from \tr{.hs} to \tr{.hc} +%$$ files with the newly-registerised \tr{hsc}. +%$$ \end{description} +%$$ +%$$ %************************************************************************ +%$$ %* * +%$$ \subsubsection[real-version-fine-tuning]{Fine-tuning of a ``registerised'' version of GHC} +%$$ %* * +%$$ %************************************************************************ +%$$ +%$$ NOT FINISHED YET. Let me know if you get this far :-) +%$$ +%$$ installing +%$$ +%************************************************************************ +%* * +\subsection[Compiler_reconfig]{Building GHC again after you've bootstrapped} +\index{GHC reconfiguration, after booting} +\index{booting, then GHC reconfigure} +\index{native-code generator, after booting} +%* * +%************************************************************************ + +Two reasons why you might want to re-configure and re-build GHC after +an initial boot are: (a)~to get a native-code generator, or (b)~if you +are going to hack on GHC. + +The reason you must rebuild to get a native-code generator: The +\tr{.hc} files will {\em not} turn into a native-code generator, and +the distributed \tr{.hi} files ``match'' those \tr{.hc} files. + +From here on, I presume you've installed your booted GHC as +\tr{ghc-0.26}. + +If you are going for a native-code generator, you can save yourself +some re-compiling by getting a suitable set of interface (\tr{.hi}) +files, for GHC for your machine. You should end up doing, for example: +\begin{verbatim} +cd ghc-0.26/ghc/compiler # note where you are! + +rm */*.o # scrub the old compiler files + +gunzip -c ghc-0.26-hi-files-alpha.tar.gz | tar xfv - +\end{verbatim} + +Now you can configure as before, but using \tr{--with-hc=ghc-0.26} +(\tr{config.status} records what you did before). + +Running \tr{sh < STARTUP} isn't strictly necessary; you only need to +rebuild in \tr{ghc/compiler}: +\begin{verbatim} +cd ghc-0.26/ghc/compiler +make Makefile # if you didn't STARTUP... + +make all EXTRA_HC_OPTS=-fvia-C # -fvia-C important! +make all EXTRA_HC_OPTS=-fvia-C # again, until .hi files settle... +\end{verbatim} + +You might want to to again test GHC ``out of the build'' before you +type \tr{make install} in \tr{ghc/compiler} to finish the job. + +%************************************************************************ +%* * +\section[building-with-HBC]{Building GHC with HBC or other funny Haskell compilers} +\index{GHC, building with HBC} +\index{GHC, building with old GHCs} +\index{GHC, building with other compilers} +%* * +%************************************************************************ + +GHC~0.26 doesn't build with HBC. (It could, but we haven't put in +the effort to maintain it.) + +GHC~0.26 is best built with itself, GHC~0.26. We heartily recommend +it. GHC~0.26 can certainly be built with GHC~0.23 or 0.24, and with +some earlier versions, with some effort. + +GHC has never been built with compilers other than GHC and HBC. + +%$$ If you are going to build the compiler with HBC, +%$$ please get the appropriate set of \tr{.hi} interface +%$$ files. If you going to build with an old GHC, +%$$ visit your psychiatrist first. +%$$ +%$$ If you choose this route, +%$$ you are well advised to get and install a set of \tr{.hi} interface +%$$ files that were created by the same compiler you intend to use. If +%$$ you intend to use HBC, we may provide a suitable ``spare'' set of \tr{.hi} files, +%$$ in \tr{ghc-0.26-hi-files-hbc.tar.gz}, from an FTP site near you. +%$$ +%$$ Unpack the \tr{.hi} files in this {\em somewhat unobvious} way: +%$$ \begin{verbatim} +%$$ % cd ghc-0.26/ghc/compiler # **** this is where you want to be!!! **** +%$$ +%$$ % gunzip -c ghc-0.26-hi-files-hbc.tar.gz | tar xfv - +%$$ \end{verbatim} + +%************************************************************************ +%* * +\section[Pre-supposed]{Installing pre-supposed utilities} +\index{pre-supposed utilities} +\index{utilities, pre-supposed} +%* * +%************************************************************************ + +Here are the gory details about some utility programs you may need; +\tr{perl} and \tr{gcc} are the only important ones. (PVM is important if you're going for Parallel Haskell.) The +\tr{configure} script will tell you if you are missing something. + +\begin{description} +\item[Perl:] +\index{pre-supposed: Perl} +\index{Perl, pre-supposed} +{\em You have to have Perl to proceed!} Perl is a language quite good +for doing shell-scripty tasks that involve lots of text processing. +It is pretty easy to install. + +(We still assume Perl version 4; experience suggests that Perl~5 +is fine, too.) + +Perl should be put somewhere so that it can be invoked by the \tr{#!} +script-invoking mechanism. (I believe \tr{/usr/bin/perl} is preferred; +we use \tr{/usr/local/bin/perl} at Glasgow.) The full pathname should +be less than 32 characters long. + +Perl version 4.035 has a bug to do with recursion that will bite if +you run the \tr{lit2texi} script, when making Info files from +``literate'' files of various sorts. Either use a more recent version +(4.036, or 5.00n) or an older version +(e.g., perl 4.019). + +\item[GNU C (\tr{gcc}):] +\index{pre-supposed: GCC (GNU C compiler)} +\index{GCC (GNU C compiler), pre-supposed} +The current version is 2.7.0, and has no problems that we know of. + +If your GCC dies with ``internal error'' on some GHC source file, +please let us know, so we can report it and get things improved. +(Exception: on \tr{iX86} boxes---you may need to fiddle with GHC's +\tr{-monly-N-regs} option; ask if confused...) + +\item[PVM version 3:] +\index{pre-supposed: PVM3 (Parallel Virtual Machine)} +\index{PVM3 (Parallel Virtual Machine), pre-supposed} +PVM is the Parallel Virtual Machine on which Parallel Haskell programs +run. Underneath PVM, you can have (for example) a network of +workstations (slow) or a multiprocessor box (faster). + +The current version of PVM is 3.3.7. It is readily available on +the net; I think I got it from \tr{research.att.com}, in \tr{netlib}. + +A PVM installation is slightly quirky, but easy to do. Just follow +the \tr{Readme} instructions. + +\item[\tr{xargs} on Solaris2:] +\index{xargs, presupposed (Solaris only)} +\index{Solaris: alternative xargs} +The GHC libraries are put together with something like: +\begin{verbatim} +find bunch-of-dirs -name '*.o' -print | xargs ar q ... +\end{verbatim} +Unfortunately the Solaris \tr{xargs} (the shell-script equivalent +of \tr{map}) only ``bites off'' the \tr{.o} files a few at a +time---with near-infinite rebuilding of the symbol table in +the \tr{.a} file. + +The best solution is to install a sane \tr{xargs} from the GNU +findutils distribution. You can unpack, build, and install the GNU +version in the time the Solaris \tr{xargs} mangles just one GHC +library. + +\item[\tr{bash} (Parallel Haskell only):] +\index{bash, presupposed (Parallel Haskell only)} +Sadly, the \tr{gr2ps} script, used to convert ``parallelism profiles'' +to PostScript, is written in Bash (GNU's Bourne Again shell). +This bug will be fixed. + +\item[Makeindex:] +\index{pre-supposed: makeindex} +\index{makeindex, pre-supposed} +You won't need this unless you are re-making our documents. Makeindex +normally comes with a \TeX{} distribution, but if not, we can provide +the latest and greatest. + +\item[Tgrind:] +\index{pre-supposed: tgrind} +\index{tgrind, pre-supposed} +This is required only if you remake lots of our documents {\em and} +you use the \tr{-t tgrind} option with \tr{lit2latex} (also literate +programming), to do ``fancy'' typesetting of your code. {\em +Unlikely.} + +\item[Flex:] +\index{pre-supposed: flex} +\index{flex, pre-supposed} +This is a quite-a-bit-better-than-Lex lexer. Used in the +literate-programming stuff. You won't need it unless you're hacking +on some of our more obscure stuff. + +\item[Something other than Sun's \tr{/usr/bin/yacc}:] +\index{pre-supposed: non-worthless Yacc} +\index{Yacc, pre-supposed} +If you mess with the Haskell parser, you'll need a Yacc that can cope. +The unbundled \tr{/usr/lang/yacc} is OK; the GNU \tr{bison} is OK; +Berkeley yacc, \tr{byacc}, is not OK. +\end{description} + +%************************************************************************ +%* * +\section[build-pitfalls]{Known pitfalls in building Glasgow Haskell} +\index{problems, building} +\index{pitfalls, in building} +\index{building pitfalls} +%* * +%************************************************************************ + +WARNINGS about pitfalls and known ``problems'': + +\begin{enumerate} +%------------------------------------------------------------------------ +\item +One difficulty that comes up from time to time is running out of space +in \tr{/tmp}. (It is impossible for the configuration stuff to +compensate for the vagaries of different sysadmin approaches re temp +space.) + +The quickest way around it is \tr{setenv TMPDIR /usr/tmp} or +even \tr{setenv TMPDIR .} (or the equivalent incantation with the +shell of your choice). + +The best way around it is to use the \tr{--with-tmpdir=<dir>} option +to \tr{configure}. Then GHC will use the appropriate directory +in all cases. + +%------------------------------------------------------------------------ +\item +When configuring the support code (mkworld, glafp-utils, etc.), you +will see mention of \tr{NO_SPECIFIC_PROJECT} and +\tr{NO_SPECIFIC_VERSION}. This is cool. + +%------------------------------------------------------------------------ +\item +In compiling some support-code bits, e.g., in \tr{ghc/runtime/gmp} and +even in \tr{ghc/lib}, you may get a few C-compiler warnings. We think +these are OK. + +%------------------------------------------------------------------------ +\item +In 0.26, when compiling via C, you'll sometimes get ``warning: +assignment from incompatible pointer type'' out of GCC. Harmless. + +%------------------------------------------------------------------------ +%\item +%If you build an ``unregisterised'' build, you will get bazillions of +%warnings about `ANSI C forbids braced-groups within expressions'. +%Especially in \tr{ghc/lib}. These are OK. + +%------------------------------------------------------------------------ +\item +Similarly, \tr{ar}chiving warning messages like the following are not +a problem: +\begin{verbatim} +ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_ +ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_ +... +\end{verbatim} + +%------------------------------------------------------------------------ +\item +Also harmless are some specialisation messages that you may see when +compiling GHC; e.g.: +\begin{verbatim} +SPECIALISATION MESSAGES (Desirable): +*** INSTANCES +{-# SPECIALIZE instance Eq [Class] #-} +{-# SPECIALIZE instance Eq (Class, [Class]) #-} +{-# SPECIALIZE instance Outputable [ClassOp] #-} +{-# SPECIALIZE instance Outputable [Id] #-} +\end{verbatim} + +%------------------------------------------------------------------------ +\item +In compiling the compiler proper (in \tr{compiler/}), you {\em may} get an +``Out of heap space'' error message. These +can vary with the vagaries of different systems, it seems. The +solution is simple: (1)~add a suitable \tr{-H} flag to the \tr{compile} +macro for the offending module, +in \tr{ghc/compiler/Jmakefile} (towards the end); +(2)~re-\tr{make Makefile} in that directory; (3)~try again: \tr{make}. + +Alternatively, just cut to the chase scene: +\begin{verbatim} +% cd ghc/compiler +% make EXTRA_HC_OPTS=-H32m # or some nice big number +\end{verbatim} + +%------------------------------------------------------------------------ +\item +Not too long into the build process, you may get a huge complaint +of the form: +\begin{verbatim} +Giant error 'do'ing getopts.pl: at ./lit2pgm.BOOT line 27. +\end{verbatim} +This indicates that your \tr{perl} was mis-installed; the binary is +unable to find the files for its ``built-in'' library. Speak to your +perl installer, then re-try. + +%------------------------------------------------------------------------ +\item +If you try to compile some Haskell, and you get errors from GCC +about lots of things from \tr{/usr/include/math.h}, then your GCC +was mis-installed. \tr{fixincludes} wasn't run when it should've +been. + +As \tr{fixincludes} is now automagically run as part of GCC +installation, this bug also suggests that you have an old GCC. + +%------------------------------------------------------------------------ +%\item +%Sooner or later in your ``make-worlding'' life you will do and see +%something like: +%\begin{verbatim} +%% make Makefile +% rm -f Makefile.bak; mv Makefile Makefile.bak +%../.././mkworld/jmake -P ghc -S std -I../.././mkworld -DTopDir=../../. -DTopDir=... +%../.././mkworld/jrestoredeps +%==== The new Makefile is for: ==== +%make: Fatal error in reader: Makefile, line 850: Unexpected end of line seen +%Current working directory /export/users/fp/grasp/ghc-0.26/ghc/runtimes/standard +%*** Error code 1 +%make: Fatal error: Command failed for target `Makefile' +%\end{verbatim} +% +%Don't panic! It should restore your previous \tr{Makefile}, and +%leave the junk one in \tr{Makefile.bad}. Snoop around at your leisure. + +%------------------------------------------------------------------------ +%\item +%If you do corrupt a \tr{Makefile} totally, or you need to glue a new +%directory into the directory structure (in \tr{newdir}---which must +%have a \tr{Jmakefile}, even if empty), here's a neat trick: +%\begin{verbatim} +%# +%# move to the directory just above the one where you want a Makefile... +%cd .. +%# +%# make Makefiles, but lie about the directories below... +%make Makefiles SUBDIRS=newdir +%\end{verbatim} +% +%This will create a \tr{Makefile} {\em ex nihilo} in \tr{newdir}, and +%it will be properly wired into the general make-world structure. + +%------------------------------------------------------------------------ +%\item +%Don't configure/build/install using a variety of machines. A +%mistake we've made is to do \tr{make Makefiles} on a Sun4, then try to +%build GHC (\tr{make all}) on a Sun3. + +%------------------------------------------------------------------------ +\item +If you end up making documents that involve (La)TeX and/or \tr{tib} +(Simon's favourite), the odds are that something about your/our setup +will reach out and bite you. Yes, please complain; meanwhile, +you can do \tr{make -n whatever.dvi} to see the intended commands, +then try to muddle through, doing them by hand. + +%------------------------------------------------------------------------ +%\item +\end{enumerate} + +%************************************************************************ +%* * +\section[weird-configs]{Making weird GHC configurations} +\index{GHC unusual configurations} +%* * +%************************************************************************ + +The usual way to build a ``weird'' GHC configuration is to turn +various \tr{configure} knobs, e.g., \tr{--enable-concurrent}. +Please see \sectionref{Configuring-GHC} about GHC configuring. + +If you want to build some Very Customised GHC libraries, it's +probably best to send email to us, asking how. + +%$$ Usually, you will build whatever libraries your chosen ``setup'' +%$$ specifies. However, perhaps you are a hacker, and you want an extra +%$$ ``ticky-ticky profiling'' version of the libraries. (Or, you want a +%$$ version compiled with your Very Own Optimisation...) +%$$ +%$$ To create a ``user way'' or setup, put +%$$ something like this somewhere (more on ``somewhere'', below): +%$$ \begin{verbatim} +%$$ #ifndef GhcBuild_UserWay_a +%$$ #define GhcBuild_UserWay_a YES +%$$ GHC_USER_WAY_FLAG_a = -ticky +%$$ GHC_USER_WAY_OPTS_a = -fstg-reduction-counts -O +%$$ #endif /* ! GhcBuild_UserWay_a */ +%$$ \end{verbatim} +%$$ You'll be able to invoke the driver with a \tr{-ticky} option, which +%$$ will be as if you typed in all that other stuff. It will also arrange +%$$ that there is a version of the prelude (\tr{libHS_a.a} library, +%$$ \tr{Prelude_a.hi} to match) and runtime system (\tr{libHSrts_a.a}) to +%$$ match. (Neat, huh?) +%$$ +%$$ On the ``somewhere'' to specify what to build: If you don't plan +%$$ to re-\tr{configure}, just change \tr{site-ghc.jm}. If you do plan to +%$$ re-\tr{configure}, change \tr{site-ghc.jm.in} and re-\tr{configure} +%$$ immediately. +%$$ +%$$ One note about {\em adding} ``user setups'' to an existing build: +%$$ Besides remaking your \tr{Makefiles} straight away, {\em don't forget} +%$$ to remake the driver (in \tr{ghc/driver}) before making any libraries! +%$$ The short cut is: +%$$ \begin{verbatim} +%$$ cd ..../ghc/driver +%$$ make Makefile; make all +%$$ cd ../runtime +%$$ make Makefile; make all +%$$ cd ../lib +%$$ make Makefile; make all +%$$ \end{verbatim} + +\upsection + +%************************************************************************ +%* * +\section[building-Haggis]{Building Haggis (Haskell GUI toolkit)} +\index{Haggis, building} +\index{building Haggis} +%* * +%************************************************************************ + +NOT DONE YET. + +%************************************************************************ +%* * +\section[building-Happy]{Building Happy (Haskell parser generator)} +\index{Happy, building} +\index{building Happy} +%* * +%************************************************************************ + +NOT DONE YET. + +%************************************************************************ +%* * +\section[building-NoFib]{Building NoFib (Haskell benchmark suite)} +\index{NoFib suite, building} +\index{building the NoFib suite} +%* * +%************************************************************************ + +NOT DONE YET. + +%************************************************************************ +%* * +\section[Configuring]{Running \tr{configure}} +\index{configure script} +%* * +%************************************************************************ + +The GNU-style \tr{configure} script figures out things which we need +to know to build one or more Glasgow tools for your machine. Also, +\tr{configure} lets you specify what you want built. + +Most people will configure/build one tool at a time. The +``short-cut'' instructions +for GHC are in \sectionref{Configuring-GHC}, +for Haggis in \sectionref{Configuring-Haggis}, +for Happy in \sectionref{Configuring-Happy}, +and for NoFib in \sectionref{Configuring-NoFib}. + +However, \tr{configure} lets you pick and choose, so you can build +several things ``in a one-er''. Just fling in all the options +at once, and be amazed. + +%************************************************************************ +%* * +\subsection[Configuring-general]{\tr{configure} options for all tools} +\index{Configuring (general)} +%* * +%************************************************************************ + +Many \tr{configure} options apply no matter what tools you are building. + +\begin{description} +\item[\tr{--help}:] (a standard GNU option) +\index{--help configure option} +Prints out a long usage message. The first part is GNU boilerplate; +after that is the Glasgow info. + +\item[\tr{--prefix=}{\em directory}:] (a standard GNU option) +\index{--prefix configure option} +Sets the ``root'' directory for where a system should be installed; +defaults to \tr{/usr/local}. + +With Happy, for example, the main \tr{happy} binary will end up in +\tr{/usr/local/bin/happy}. + +%-------------------------------------------------------------- +\item[\tr{--exec-prefix=}{\em directory}:] (a standard GNU option) +\index{--exec-prefix configure option} +Sets the ``root'' directory +for where executables +(e.g., the GHC driver) should be installed; defaults to whatever +\tr{--prefix} is, +meaning that things will be installed in \tr{/usr/local/bin}. + +%$$ At Glasgow, we want such executables to go in (e.g.) +%$$ \tr{/local/fp/bin.sun4}, so \tr{--exec-prefix} is no use to us. +%$$ Happily, there's more than one way to do it!---just change +%$$ \tr{InstBinDir_GHC} in \tr{ghc/mkworld/site-ghc.jm.in}... (We hope +%$$ this doesn't bring back too many bad memories for our +%$$ pre-\tr{configure} users.) + +%-------------------------------------------------------------- +\item[\tr{--with-hc=}{\em hask}:] +\index{--with-hc configure option} +Use {\em hask} as my ``installed Haskell compiler.'' + +The name {\em hask} has to be one of \tr{ghc*} (for Glasgow Haskell), +\tr{hbc*} (for Chalmers HBC), or \tr{nhc*} (for Rojemo's NHC). +We hope to add more! + +As a special case, \tr{--with-hc=c} means ``I don't have a Haskell +compiler, please compile from intermediate C files (produced by GHC +somewhere else).'' + +%-------------------------------------------------------------- +\item[\tr{--with-tmpdir=}{\em directory}:] +Set the directory where temporary files should be created. This is +\tr{/tmp} by default, which is Sometimes Uncool (because, e.g., +\tr{/tmp} is too small). There's just no telling. + +On our Alphas, for example, we use \tr{--with-tmpdir=/usr/tmp}. + +%-------------------------------------------------------------- +\item[\tr{--with-max-heap=}{\em size}:] +When whatever Haskell compiler is run while building the Glasgow +tools, it will try to use some sane-but-not-too-big heap size. If you +have a machine with plenty of memory, you might want to say ``Go ahead +and use a great big heap.'' This option allows this. So, for +example, on our Alphas we might say \tr{--with-max-heap=48m}. +\end{description} + +%************************************************************************ +%* * +\subsection[Configuring-GHC]{GHC-specific things in \tr{configure}} +\index{Configuring for GHC} +%* * +%************************************************************************ + +The easiest way to see all the \tr{configure} options for GHC is to +type \tr{./configure --help}. (I don't feel like typing the whole +thing again, into this document...) + +Some common combinations would be: + +\begin{verbatim} +./configure --prefix=/users/fp/partain --with-hc=c --disable-profiling + # use .hc files; don't bother with profiling + +./configure --with-hc=ghc-0.26 --with-readline-library --with-sockets-library + # simple build with itself; for Sun4s & Alphas, you + # should grab & use ghc-0.26-hi-files-<blah>.tar.gz + # (because those machines have a native-code generator). + # For the extra libraries, you've got to have the right + # stuff to link to. + +./configure --with-hc=ghc-0.26 --disable-hsc-optimised --enable-hsc-debug + # Don't use -O on GHC itself; turn on -DDEBUG. + # Slows things way down, but it's the right thing if + # you're hacking on GHC and doing lots of recompilations. + +./configure --with-hc=c --enable-concurrent --enable-parallel --with-tmpdir=/usr/tmp + # Do everything from .hc files; besides the normal ones, + # you'll need the "prof", "conc" and "par" .hc files. + # Use /usr/tmp as TMPDIR... +\end{verbatim} + +Remember, if you build \tr{--with-hc=c} on a Sun4 or Alpha, you +do {\em not} have a native-code generator. + +%************************************************************************ +%* * +\subsection[Configuring-Haggis]{Haggis-specific things in \tr{configure}} +\index{Configuring for Haggis} +%* * +%************************************************************************ + +Use \tr{--enable-haggis}. If you have Haggis and GHC in the same +build tree but only want to build Haggis, use \tr{--disable-ghc}. + +MORE TO COME. + +%************************************************************************ +%* * +\subsection[Configuring-Happy]{Happy-specific things in \tr{configure}} +\index{Configuring for Happy} +%* * +%************************************************************************ + +Use \tr{--enable-happy}. If you have Happy and GHC in the same +build tree but only want to build Happy, use \tr{--disable-ghc}. + +MORE TO COME. + +%************************************************************************ +%* * +\subsection[Configuring-NoFib]{NoFib-specific things in \tr{configure}} +\index{Configuring for NoFib} +%* * +%************************************************************************ + +Use \tr{--enable-nofib}. If you have NoFib and GHC in the same build +tree but only want to build the NoFib suite, use \tr{--disable-ghc}. + +You may want to enable or disable various sets of tests, as +suggested by \tr{./configure --help}. If you use \tr{--enable-all-tests}, +be aware that many of them are GHC-specific. Also, we may not have +given you all of the source :-) + +%************************************************************************ +%* * +\section[STARTUP]{Running \tr{STARTUP}} +\index{STARTUP script} +%* * +%************************************************************************ + +Once you've \tr{configure}d, utter the magic incantation: +\begin{verbatim} +% sh < STARTUP >& startup.log +\end{verbatim} +The reason you might want to pipe the chatter into a file is so you +can check it afterwards. It should be pretty obvious if it is happy. +Note: it takes a little while. + +\tr{STARTUP} is a simple shell script that builds \tr{mkworld} +(Makefile-generating system), \tr{literate} (literate-programming +system), and \tr{glafp-utils} (a few utility programs); then makes the +Makefiles and dependencies for everything. + +If you have any problems before getting through \tr{STARTUP}, you +are probably best off re-running \tr{configure} and \tr{STARTUP} +(after fixing what was broken). + +%************************************************************************ +%* * +\section[utils_install]{Installing the support software (optional)} +\index{utilities, installing} +%* * +%************************************************************************ + +By default, the support software that comes with the Glasgow +tools---\tr{mkworld}, \tr{literate}, and \tr{glafp-utils}---is not +installed. However, they're generally-useful tools, so... + +If you did want to install the ``make world'' system, for example: +\begin{verbatim} +% cd <very-top>/mkworld +% make install +\end{verbatim} + +If it isn't installing things where you want it to, you can either +fiddle things on the fly... +\begin{verbatim} +% make install prefix=/home/sweet/home +\end{verbatim} + +If you want to install just one utility, for example \tr{lndir}: +\begin{verbatim} +% cd <very-top>/glafp-utils/scripts +% make install_lndir +\end{verbatim} + +``Make world''---It slices, it dices... it's great! + +%************************************************************************ +%* * +\section[arrangement-of-sources]{Arrangement of the sources} +%* * +%************************************************************************ + +Once you un\tr{tar} the Glorious Haskell Compilation (GHC) system sources +and \tr{cd} into the top directory, here's a bird's-eye view of what +you should see: + +\begin{tabular}{ll} +mkworld/ & ``Make world'' sub-system for configuring the system.\\ + & \\ +glafp-utils/ & Utility programs and scripts used in building the distribution;\\ + & often acquired from elsewhere. \\ +literate/ & Glasgow literate programming sub-system. \\ + & \\ +ghc/driver/ & The driver program for GHC; \\ + & currently a perl script, \tr{ghc}. \\ + & \\ +ghc/compiler/ & The Haskell compiler proper, called \tr{hsc}; \\ + & source files are in \tr{compiler/*/[A-Z]*.lhs}. \\ + & \\ +ghc/runtime/ & The runtime system, including the garbage-collector(s).\\ + & \\ +ghc/lib/prelude/& Source for the linked-in code for the ``standard prelude''. \\ +ghc/lib/glaExts/ & Source for the linked-in code for our Glasgow extensions. \\ +ghc/lib/haskell-1.3/ & Source for the linked-in code for Haskell 1.3 I/O. \\ +ghc/lib/hbc/ & Source for the HBC `system library'. \\ +ghc/lib/ghc/ & Source for the GHC `system library'.\\ + & \\ +ghc/includes/ & The ``public'' .hi files slurped by the parser, \\ + & and .h files \tr{#include}d in generated .hc files come from.\\ + & \\ +ghc/docs/ & documents; see the README file there. \\ + & \\ +ghc/CONTRIB/ & reserved for contributed things \\ +haggis/ & Haggis Haskell X11 GUI toolkit \\ +happy/ & Happy Haskell parser generator \\ +nofib/ & NoFib Haskell benchmark and test suite \\ +\end{tabular} + +\begin{onlystandalone} +\printindex +\end{document} +\end{onlystandalone} diff --git a/ghc/docs/release_notes/0-02-notes.lit b/ghc/docs/release_notes/0-02-notes.lit new file mode 100644 index 0000000000..3d4e69cab7 --- /dev/null +++ b/ghc/docs/release_notes/0-02-notes.lit @@ -0,0 +1,230 @@ +\section[0-02-limitations]{Limitations of Glasgow \Haskell{}, release~0.02} + +[Scribe for the 0.02 notes: Cordy Hall.] + +These are the current major limitations of release~0.02, +and a way to get around each if there is one. + +\begin{enumerate} +\item +{\em Doesn't yet track version~1.1 of the \Haskell{} Report.} +If you are lucky, sections might work anyway... +\item +{\em No automatic importation of Prelude.} You can add an import of +module @MiniPrel@, which is in \tr{lib/prelude/MiniPrel.hi}, and +extend your own version of this file as you wish as long as you do not +add anything currently built into the compiler. The following are +already built in (see \tr{compiler/typecheck/PrelCoreEnv.lhs}): +\begin{itemize} +\item +the boolean data type +\item +the string data type +\item +the primitive Haskell types, @Int@, @Char@, @Integer@, @Float@, @Double@ +\item +function type +\item +list type +\item +tuple type (up to and including 5 tuples) +\item +random unboxed types (@IntPrim@, @StringPrim@, etc.) +\item +class @Eq@ with all operations, and the following instances: +@Integer@, @Int@, @Rational@, @List@, @Char@, 2 tuple +\item +class @Ord@ with all operations, and the following instances: +@Integer@, @Int@ +\item +class @Num@ with all operations, and the following instances: +@Integer@, @Int@, @Rational@ +\item +class @Fractional@ with all operations, and the following instances: +@Integer@, @Rational@ +\item +cons @(:)@ and @[]@ +\end{itemize} +\item +{\em No renaming} +\item +{\em No selective export} +\item +{\em No re-export of imported entities} +\item +{\em No contexts in data declarations} +\item +{\em No ambiguity resolution for numeric types} +\item +{\em No overloaded numeric patterns or @n+k@ patterns} +\item +{\em No deriving clause on data type declarations.} You can get around this +by creating explicit instances for the data type. For example, if you wanted +to derive @Eq@ for the data type + +\begin{verbatim} +data T a = D (B a) | C +data B b = X | Y b +\end{verbatim} + +then you would write + +\begin{verbatim} +import MiniPrel + +data T a = D (B a) | C +data B b = X | Y b + +instance (Eq a) => Eq (T a) where + (D x) == (D y) = x == y + C == C = True + a == b = False + + a /= b = not (a == b) + +instance (Eq b) => Eq (B b) where + X == X = True + (Y a) == (Y b) = a == b + a == b = False + + a /= b = not (a == b) +\end{verbatim} + +The reason that @MiniPrel@ is imported is that it provides a type for @not@. +\item +{\em No default methods in class declarations} +\end{enumerate} + +So far, operations on @Int@s will have code generated for them +but more work needs to be done to handle other types +in the code generator. However, all of the above should be handled by the +typechecker. + +Other limitations: +\begin{itemize} +\item +Error messages need lots of improvement. +\item +The generated code is inefficient, and it takes a long time to generate it. +\item +Documentation is minimal. +\item +The only programs that compile and run are those for which @main@ has +type @Int@!!! Examples in \tr{compiler/tests/codeGen}... +\end{itemize} + +\section[0-02-new-tools]{New Tools} + +Programs with type errors can be difficult to correct +without some help. Unfortunately, providing this help is a difficult research +problem. Wand's recent POPL paper suggests an interesting approach, but it +costs overhead even when the code typechecks. Instead, we've taken the +following approach: + +\begin{enumerate} +\item +People who program in functional languages like interpreters because they + can find out how a small function behaves, and then deduce how it will + behave in a larger context. + +\item + Type checking is rather like debugging, so it would be nice to give the user + something that would allow probing of function and expression types + within the context of the rest of the program. + +\item + To do this, we allow the user to attach a special type variable as a + signature to any function definition or expression of interest. The + typechecker can then textually substitute the type of that expression for + the signature, and print out the original program. +\end{enumerate} + +For example, in the following program + +\begin{verbatim} +f x = ((g :: tyreq1) 'a',(g :: tyreq2) True) + where + g x = x +\end{verbatim} + +the type variables @tyreq1@ and @tyreq2@ are seen as special by the compiler. +The program printed out is: + +\begin{verbatim} +f x = ((g :: Char -> Char) 'a',(g :: Bool -> Bool) True) + where + g x = x +\end{verbatim} + +If the program was instead + +\begin{verbatim} +f x = (g 'a', True) + where + g :: tyreq1 + g x = x +\end{verbatim} + +then the program printed out would be + +\begin{verbatim} +f x = (g 'a', g True) + where + g :: a -> a + g x = x +\end{verbatim} + +A note about these `special type variables'---the user must guarantee +(at present) that each is unique, and that each +begins with the string @tyreq@. + +At present, the typechecker fails whenever there is a type error. Once +it can be made to succeed on errors, handing control to something +which can deal with this situation, then it will be easy to get some +idea of what the typechecker thought about interesting expressions in +the code, even though these types may not yet be fully defined. {\em For +now, this tool is really only useful if you have a program that does +typecheck (avoiding failure) but you wish to examine some of the types +of the program's expressions.} + +To use this feature, the compiler must be built using the +\tr{-DTYPE_ERROR_HELP} +flag (change \tr{compiler/Jmakefile} in the appropriate place). When +invoking the driver \tr{driver/ghc}, use the \tr{-ddump-type-error} +flag. + +If you do use this and/or have any comments to make, please email to +cvh\@dcs.glasgow.ac.uk. + +\section[0-02-instabilities]{Known instabilities in the compiler internals} + +Here are some things we know we are going to change in the internals +of the compiler. Fellow developers may want to query these if they +think that they may be adversely affected. + +\begin{enumerate} +\item +A modest revision to the basic data types for variables, constructors, +and type variables (currently in \tr{compiler/names/{Local,Global}.lhs} +and in \tr{compiler/absSyntax/UniType.lhs}). See +\tr{compiler/names/Id.lhs} for our notes on what to do. + +\item +A major overhaul of the pretty-printing and error-reporting machinery. + +\item +A major overhaul of the ``make world'' machinery. Ideas welcome. + +\item +A fairly significant module-renaming exercise. A proposal, not yet +agreed, is in \tr{docs/FILE-RENAMING}. +\end{enumerate} + +\section[0-02-other-problems]{Other known problems in the distribution} + +The GNU Info-file reader (\tr{literate/info-utils/info.c}) is an +unusually buggy version, for some reason. + +The tests files have been stripped out of this release, merely to +reduce the sheer volume of the distribution. Let us know if you want +the test files. diff --git a/ghc/docs/release_notes/0-03-README b/ghc/docs/release_notes/0-03-README new file mode 100644 index 0000000000..516e449a3a --- /dev/null +++ b/ghc/docs/release_notes/0-03-README @@ -0,0 +1,47 @@ +Version 0.03 of the new Glasgow Haskell compiler was an unannounced +(exceedingly unpolished) release for our friends at York. + +------------------------------------- + +A quick list of things to note: + +* Significantly different parser (parsers/hsp/) and reader + (compiler/reader/), to do Haskell 1.1 syntax. The abstract syntax + (compiler/abstractSyn/) now covers the entire Haskell language. + +* Compiler files have been majorly shuffled, renamed, in part to + ensure filenames are <= 14 chars. Another such catastrophic + re-shuffle is unlikely for the foreseeable future. + + The file docs/FILE-RENAMING is a fairly complete list of + what-changed-to-what. + +* Pretty-printing machinery (compiler/utils/{Pretty,Outputable}.lhs) + is completely changed. + +* Identifiers are now "Ids" (compiler/basicTypes/Id.lhs), not "Locals" + or "Globals". + +* What-the-compiler-must-know-about-the-prelude (compiler/prelude) is + believed to be complete; this includes Chars, Ints, Floats, and + Doubles as primitives. + + (Stuff for Integers and Rationals is NOT all there.) + + All other prelude stuff should be specifiable w/ an ordinary + interface file (notably lib/prelude/MiniPrel.hi). + +* The compiler does full-blown overloading of expressions and + patterns. Yell if this really won't do -- perhaps a build-time + option to override? + +* All flavours of patterns and expressions (e.g., n+k patterns, + arithmetic sequences) are in; testing in some cases near zero. + +* BUGS INEVITABLE, MAJOR BUGS ENTIRELY POSSIBLE, PATCHES WILL PROBABLY + BE REQUIRED. Don't panic, report promptly! + +* "main"'s (main/Main.lhs) handling of command-line options [and the + feeding of same by the driver, driver/ghc.lprl] has been revised. + +* Documentation has _not_ been updated. diff --git a/ghc/docs/release_notes/0-04-README b/ghc/docs/release_notes/0-04-README new file mode 100644 index 0000000000..14be2b0efd --- /dev/null +++ b/ghc/docs/release_notes/0-04-README @@ -0,0 +1,15 @@ +Version 0.04 of the new Glasgow Haskell compiler was yet another +unannounced release for our friends at York (and elswhere). + +---------------------------------------------------------------- +91/11/01: + +2 notes: [1] "main" should no longer have the non-std type "Int"; instead, +it should have the non-std type "IOPrim"! (We're creeping towards +real Haskell I/O.) compiler/tests/codeGen/cg001/Main.hs is a New +Improved "main", I believe. docs/io-design may also be useful. +[2] The old "import MiniPrel" trick has changed (and will change +again). Because we're in the middle of trying to get full/original +names going, you have to use one or more MODULE-SPECIFIC +"MiniPrel*.hi" files; they're in lib/prelude. + diff --git a/ghc/docs/release_notes/0-05-notes.lit b/ghc/docs/release_notes/0-05-notes.lit new file mode 100644 index 0000000000..3f42108127 --- /dev/null +++ b/ghc/docs/release_notes/0-05-notes.lit @@ -0,0 +1,86 @@ +\begin{description} +%------------------------------------------------------------------- +\item[1.1 syntax:] +Does \Haskell{} version~1.1 syntax. The code for the parser +(\tr{parsers/hsp/}) has been tidied up quite a bit [nice job, Kevin]. + +%------------------------------------------------------------------- +\item[Expressions and patterns:] +All forms of expressions and patterns work, including overloaded +patterns and @n+k@ patterns. + +%------------------------------------------------------------------- +\item[A big part of the standard prelude is operational:] +These parts (in \tr{lib/prelude}) have been compiled with the new +compiler, and programs compiled with the new compiler can be linked to +it. + +With the exceptions of (a)~hooking in the standard Haskell I/O system +(see next item) and (b)~special pleading for constant-time-access +arrays (or other magical features), all Prelude stuff is either done +or easily do-able. + +%------------------------------------------------------------------- +\item[Simple resolution of ambiguous overloading of numeric types:] +(As per Haskell report, section~4.3.4). @default@ declarations do +{\em NOT} work; however, the ``default default'' +(@default (Int, Double)@) is wired in. This should clear up nearly +all annoying ``ambiguous dictionary'' errors. + +%------------------------------------------------------------------- +\item[Better non-standard I/O:] +We have implemented the bare bones of the I/O described in +\tr{docs/io-design/}. It's not standard \Haskell{} I/O +(we haven't yet implemented the impedance-matcher discussed in the +doc), and it's not the same as what was there in 0.02. However, you +can now write a simple reads-stdin/writes-stdout program: + +\begin{verbatim} +#include "GhcPrelude.h" + +main = readString `thenIO` ( \ s -> + writeString (my_String_to_String_manglification s) ) +\end{verbatim} + +The implementation of @error@ (via @sysError@) is also as described in +the I/O document. + +%------------------------------------------------------------------- +\item[Faster compiler:] +The compiler is faster than version~0.02---we promise---but the +significant tuning work is not yet done. We will do it after The +Mangler (renamer) is in. + +%------------------------------------------------------------------- +\item[Run compiled code on a Sun4:] +If you compile your program to C (\tr{.hc} files), with, e.g.: + +\begin{verbatim} +% glhc -C Foo.hs +\end{verbatim} + +then you compile the output on a Sun4 with: + +\begin{verbatim} +% glhc -c Foo.hc +\end{verbatim} + +and, if you have the right things to link to, you can link with: + +\begin{verbatim} +% glhc -o foo Foo.o +\end{verbatim} + +The ``right things to link to'' include: the runtime system ( +\tr{cd runtimes/standard; make} on a sun4), and the standard libraries +(\tr{cd lib; make all} on a sun4). + +We have not yet tried to make this work for Every Known Unix Box In +The Universe. (But we plan to, with your help :-) + +%------------------------------------------------------------------- +\item[Upheaval during FPCA:] +As advertised with 0.02: Files moved around, modules and data types +were renamed, and a generally Much Cleaner World now exists. We have +no plans to do more of the same (at least for the compiler proper). +\end{description} diff --git a/ghc/docs/release_notes/0-06-notes.lit b/ghc/docs/release_notes/0-06-notes.lit new file mode 100644 index 0000000000..e91ceac99b --- /dev/null +++ b/ghc/docs/release_notes/0-06-notes.lit @@ -0,0 +1,266 @@ +The really new thing about release 0.06 is this: if you can get +your program through the compiler, then it should actually work when you +run it! + +Another thing we have worked hard on recently is {\em documentation} (see +next section). + +%************************************************************************ +%* * +\subsection[0-06-new-docs]{New documentation, especially for hackers!} +%* * +%************************************************************************ + +See the file \tr{docs/README} for a full ``roadmap'' to all known +documentation. + +\begin{description} +%------------------------------------------------------------------- +\item[STG-machine paper.] +A monster (70+-page) paper which gives a detailed description of the +Spineless Tagless G-machine, on which the back end of the compiler is based. +Simon is Jolly Proud of this paper. + +This paper isn't in the distribution, but is available by asking +Simon, or by FTP from \tr{ftp.dcs.glasgow.ac.uk:pub/glasgow-fp/stg.dvi}. +%------------------------------------------------------------------- +\item[\tr{imports/SMinterface.lh}.] +The storage manager is carefully isolated from the rest of the runtime +system behind a carefully identified interface. This paper documents +the interface, and says a little about the implementation. NB: +``literate'' \tr{.h} file! +%------------------------------------------------------------------- +\item[\tr{docs/C_optimisation}.] +Lots of details about how we use C as a target language, and +the tricks we use to make it go fast. Still drafty. +%------------------------------------------------------------------- +\item[\tr{docs/runtime}.] +The {\em beginnings} of a description of details of the runtime system +which aren't covered by the STG paper above. +%------------------------------------------------------------------- +\item[\tr{docs/typecheck}.] +The {\em beginnings} of a description of tricky corners of the type checker. +%------------------------------------------------------------------- +\item[\tr{docs/arrays}.] +A work-in-progress on how to handle arrays properly. +%------------------------------------------------------------------- +\item[\tr{docs/core-overview}:] +The beginnings of a description of the Core data type, plus the other +data types you need to know about to write programs which manipulate +the Core data type. + +The ``how to add to the compiler'' document +(\tr{docs/add_to_compiler}) has some of this stuff in it, too. +%------------------------------------------------------------------- +\item[Type classes paper:] +This is a short (20-page) form of the massive ``Static Semantics of +Haskell'' paper. We submitted it to Lisp and FP 1992, but they +(unaccountably) rejected it. + +This paper isn't in the distribution; please ask for it. +\end{description} + +%************************************************************************ +%* * +\subsection[0-06-new-in-compiler]{To do with the compiler proper} +%* * +%************************************************************************ + +\begin{description} +%------------------------------------------------------------------- +%------------------------------------------------------------------- +\item[1.2 syntax:] +The parser handles the Haskell syntax given in the Haskell report, +version~1.2. See \tr{parsers/hsp}. + +%------------------------------------------------------------------- +\item[Graph reduction:] +Updates are in and we're doing graph reduction! (All the bells and +whistles for doing a good job of [avoiding] updates are not +in yet.) + +See \tr{compiler/codeGen/{CodeGen,CgClosure}.lhs} and +\tr{runtime/main/Update.lhc} for the main bits. + +%------------------------------------------------------------------- +\item[Closure layout less deeply wired into compiler:] +Rather than knowing word-for-word how each closure is layed out in +memory, the compiler emits C macro calls to access/fill-in the ``fixed +header'' and ``variable header'' parts of each closure (all described +in the storage-manager document). + +This means, for example, that the very same C code used on sequential +machines can be used on GRIP as well, even though closures in GRIP +have some extra fields---all that is required is suitable \tr{.h} +files to define the header macros accordingly! + +Anyone whose efforts involve munging around in or pinning things onto +closures should like this ``feature.'' + +%------------------------------------------------------------------- +\item[Statistics about program execution:] +The compiler emits macro calls into the C output which, if expanded +(use @-DDO_RUNTIME_PROFILING@, default: on), will accumulate +statistics about program behaviour. To have those statistics printed +out (to @stderr@), give your program the @-p@ RTS flag, thusly: + +\begin{verbatim} +% a.out +RTS -p +\end{verbatim} + +We welcome any interesting profiles that you may churn up! + +See \tr{imports/StgProfile.h} and \tr{runtime/main/StgProfile.lc}, +plus insertions of those macro calls in +\tr{compiler/codeGen}. + +%------------------------------------------------------------------- +\item[New simplifier/transformation stuff:] +Contributed by research students Andr\'e Santos and Andy Gill. In +\tr{compiler/simplify} and \tr{compiler/stranal-triv}; it's still +thoroughly experimental. + +The old-but-reliable brain-damaged simplifier is now in +\tr{compiler/simplify0} and is still the default. + +%------------------------------------------------------------------- +%\item[Faster compiler:] +% (NOT QUITE YET) The compiler is again faster than the previous release +% (version~0.05). The C output is also smaller. + +%------------------------------------------------------------------- +\item[Compiler is compilable with Chalmers's HBC or Glasgow prototype compiler:] +The default set of \tr{compiler/*/*.hi} interface files in the +distribution are for compiling with HBC (this seems to be the people's +preference); version 0.997.3 or greater, please. + +A separate set of \tr{.hi} files are provided for those who use the +Glasgow prototype compiler. These are in the file +\tr{ghc-0.06-proto-hi-files.tar.Z}, available wherever you got the +basic distribution. The installation document says how to deal with +these various blobs of files. + +The possibility of using HBC means you can compile the Glasgow Haskell +compiler on any machine supported for HBC (Sun3s, Sun4s, DEC 3100s +[and one or two more flavours?]). +\end{description} + +%************************************************************************ +%* * +\subsection[0-06-new-in-compiler-contrib]{In contributed bits of the compiler} +%* * +%************************************************************************ + +\begin{description} +%------------------------------------------------------------------- +\item[Semantique strictness analyser:] +The one in the distribution now builds; in \tr{compiler/stranal-sem}. +This would only be of interest to those who might want to play with +it. The rest of the compiler can't use its results. + +If you want to build this strictness analyser, you need to configure +appropriately (see \tr{mkworld/Project-ghc-full.*}, when you get to +that part of the installation instructions). +\end{description} + +Please send us {\em your} bits for next time! + +%************************************************************************ +%* * +\subsection[0-06-new-in-libraries]{In @Prelude@ and runtime support} +%* * +%************************************************************************ + +\begin{description} +%------------------------------------------------------------------- +\item[``Binary bloat'' from the prelude, ameliorated:] +The C files produced from compiling the prelude are chopped into +some 400 separate C files, which are individually compiled and +banged into an archive. Result is that you only get the bits you +``need,'' and binary sizes have about halved. +(There is more work to do in this department.) + +%------------------------------------------------------------------- +\item[Naive implementation of Haskell I/O:] +At least \tr{ReadChan stdin} and \tr{AppendChan stdout} requests work. +It shouldn't be too hard to add support for other requests in +\tr{lib/io/DialogueToIO.lhs}. (Only [extended] Haskell hacking needed!) + +%------------------------------------------------------------------- +\item[Storage management moved behind a safe wall:] + +It's now in \tr{runtime/storage/.} All four flavours of garbage +collector (two-space copying, one-space compacting, dual-mode, and +Appel-like generational) seem to work. + +Patrick Sansom, research student and hacker extraordinaire, did all +of this. + +%------------------------------------------------------------------- +\item[Flags-to-RTS machinery in place:] + +When your @ghc@-compiled Haskell program starts up, any command-line +arguments bracketted by @+RTS@ and @-RTS@ (or the end of the arguments) +are assumed to be flags for the runtime system. These flags are used +to alter the heap size, ask for garbage-collection stats, etc. + +To see what flags are available, try: \tr{myprog +RTS -f}. + +Patrick did this, too. + +%------------------------------------------------------------------- +\item[C-optimisation sleaziness also better hidden:] + +It is in \tr{runtime/c-as-asm/}. (It needs to be tidier, but...) + +We are still actively working on getting this right. Please get in +touch if you are interested. +\end{description} + +%************************************************************************ +%* * +\subsection[0-06-new-in-mkworld]{In distribution/build/installation machinery} +%* * +%************************************************************************ + +\begin{description} +%------------------------------------------------------------------- +\item[Better line numbers, and Emacs-able TAGS files:] +(Yes, they're related!) Error messages should come out with better +line numbers than before. + +The distribution now includes tags-making things: souped-up \tr{etags} +program [for C], \tr{perltags} [for perl], and \tr{hstags} [for +Haskell] (mostly in \tr{utils/scripts}). The Haskell tags program +uses the parser, so it Does It Right. + +\tr{make tags fulltags} at the top of the distribution tree will make a +huge TAGS file for the whole compilation system. + +%------------------------------------------------------------------- +\item[\tr{make install} might do something sensible:] +Yes, it does. But you'd be well advised to do a \tr{make -n install} +just to check first! +\end{description} + +%************************************************************************ +%* * +\subsection[0-06-new-misc]{Miscellaneous new things} +%* * +%************************************************************************ + +\begin{description} +%------------------------------------------------------------------- +\item[Consistency-checking for executables:] +Given that our system can generate \tr{.o} object files which are +seriously {\em incompatible} with each other, depending on choice of +garbage collector, degree of optimisation, whether or not compiling +for GRIP, etc., we have implemented a scheme (in the driver \tr{ghc}) +that checks that all the linked bits in an executable ``belong'' +together. + +%------------------------------------------------------------------- +\item[Scripts from Denis Howe:] +We have included his \tr{fptags} and \tr{mira2hs} scripts that he +posted to \tr{comp.lang.functional}. +\end{description} diff --git a/ghc/docs/release_notes/0-07-README b/ghc/docs/release_notes/0-07-README new file mode 100644 index 0000000000..4048f17747 --- /dev/null +++ b/ghc/docs/release_notes/0-07-README @@ -0,0 +1,4 @@ +Version 0.07 was an unannounced not-really-a-release to a few diehard +friends. Much of what is described in the 0.08 release notes was +actually done in 0.07. Please see the 0.08 release ntoes for further +details. diff --git a/ghc/docs/release_notes/0-07-notes.lit b/ghc/docs/release_notes/0-07-notes.lit new file mode 100644 index 0000000000..7b729d6046 --- /dev/null +++ b/ghc/docs/release_notes/0-07-notes.lit @@ -0,0 +1,51 @@ +%************************************************************************ +%* * +\section[0-07-new]{New things in Glasgow \Haskell{}, release~0.07} +%* * +%************************************************************************ + +%************************************************************************ +%* * +\subsection[0-07-new-docs]{New documentation, especially for hackers!} +%* * +%************************************************************************ + +%************************************************************************ +%* * +\subsection[0-07-new-in-compiler]{To do with the compiler proper} +%* * +%************************************************************************ + +\begin{description} +%------------------------------------------------------------------- +\item[eval does right thing:] + +%------------------------------------------------------------------- +\item[CAFs fully supported (notably updatable ones):] +\end{description} + +%************************************************************************ +%* * +\subsection[0-07-new-in-compiler-contrib]{In contributed bits of the compiler} +%* * +%************************************************************************ + +Please send us {\em your} bits for next time! + +%************************************************************************ +%* * +\subsection[0-07-new-in-libraries]{In @Prelude@ and runtime support} +%* * +%************************************************************************ + +%************************************************************************ +%* * +\subsection[0-07-new-in-mkworld]{In distribution/build/installation machinery} +%* * +%************************************************************************ + +%************************************************************************ +%* * +\subsection[0-07-new-misc]{Miscellaneous new things} +%* * +%************************************************************************ diff --git a/ghc/docs/release_notes/0-08-notes.lit b/ghc/docs/release_notes/0-08-notes.lit new file mode 100644 index 0000000000..eaefa740fa --- /dev/null +++ b/ghc/docs/release_notes/0-08-notes.lit @@ -0,0 +1,149 @@ +0.08 was not an announced release, so these notes are of historical +interest, at best. + +%************************************************************************ +%* * +\subsection[0-08-new-docs]{New documentation, especially for hackers!} +%* * +%************************************************************************ + +%************************************************************************ +%* * +\subsection[0-08-new-in-usage]{Main user-visible changes} +%* * +%************************************************************************ + +\begin{description} +%------------------------------------------------------------------- +\item[@ghc@ driver flag fiddling:] +These things change... A good thing to try is \tr{ghc -help}, unless +of course you think the documentation might be right (in which case +look there :-). + +%------------------------------------------------------------------- +\item[@ghc@ driver more ``policy-free'':] + +The driver no longer has great wads of built-in options for its +constituent phases (parser, Haskell compiler, C compiler, etc.). It +is much easier to configure these (if required) at build time. A +better idea, which we use, is to wired in very few options, but to use +the ``make world'' machinery to ensure that the desired (wads of +options) are always passed explicitly. + +%------------------------------------------------------------------- +\item[-OC:] We got rid of the \tr{-OC} flag. +\end{description} + +%************************************************************************ +%* * +\subsection[0-08-new-in-compiler]{To do with the compiler proper} +%* * +%************************************************************************ + +\begin{description} +%------------------------------------------------------------------- +\item[``Renamer'' is in:] +Essentially, this implements module-system stuff. Checks for +naming/scoping errors have been moved out of the typechecker into the +renamer, which should be faster. + +%------------------------------------------------------------------- +\item[Interface-file (\tr{.hi} file) generation:] +It works. + +%------------------------------------------------------------------- +\item[Ambiguous-type resolution:] +It's basically right now, except that we still don't grok @default@ +declarations (which we have yet to see in a real Haskell program :-). + +%------------------------------------------------------------------- +\item[Smaller C output:] + +%------------------------------------------------------------------- +\item[Code generator:] +Improvements related to the information carried around about closures +(@ClosureInfo@ and @LambdaFormInfo@ types); matches the STG-machine paper. + +CAFs fully supported (notably updatable ones). + +Black-holing (at garbage-collection time) fully supported. + +%------------------------------------------------------------------- +\item[Simplifiers:] +Further work on the @Core@-to-@Core@ local-transformation passes (in +\tr{compiler/simplCore/}). Also, we have added +some @STG@-to-@STG@ transformations; for example, floating @lets@ +outward is most conveniently done at the STG level... + +%------------------------------------------------------------------- +\item[Cost-centre-style profiling:] + +%------------------------------------------------------------------- +\item[Improvements to basic datatypes:] +Notably to @Ids@ (\tr{basicTypes/Id.lhs}) and names +(\tr{basicTypes/NameTypes.lhs}). There is a new compiler-wide class, +@NamedThing@ (\tr{utils/Outputable.lhs}). Essentially it is easier to +ask of an entity: where did you come from? (e.g., PreludeCore?, +imported?) what are you? (a data-constructor? a dictionary selector?) +what is your original name? where are you going? (exported or not...) +\end{description} + +%************************************************************************ +%* * +\subsection[0-08-new-in-compiler-contrib]{In contributed bits of the compiler} +%* * +%************************************************************************ + +\begin{description} +\item[Evaluation-transformer bits:] +Denis Howe has sent us an initial version (\tr{compiler/evalTran}). +It isn't used by default, but is presumably play-withable... + +This @Core@-to-@Core@ transformation makes all lets of the form +\begin{verbatim} +let VAR = eval EXPR in ... +\end{verbatim} +strict. @eval@ is a dummy name which is thrown away (i.e., @eval x = x@). +\end{description} + +Please send us {\em your} bits for next time! + +%************************************************************************ +%* * +\subsection[0-08-new-in-libraries]{In @Prelude@ and runtime support} +%* * +%************************************************************************ + +Prelude is 1.2. + +The compiler has basically all of @PreludeCore@ wired into it (see +\tr{compiler/prelude/}); the rest is brought in with a straightforward +\tr{import Prelude} (which brings in \tr{imports/Prelude.hi}). [The +old \tr{MiniPrel*} files are dead and unmissed.] + +%************************************************************************ +%* * +\subsection[0-08-new-in-mkworld]{In distribution/build/installation machinery} +%* * +%************************************************************************ + +The ``make world'' machinery has many small improvements. + +It works notably better in a shared-symlink-tree world (which we use +at Glasgow). + +We have abandoned efforts to use one build tree for making object +files for multiple platforms. We can make simpler Makefiles as a +result. + +There's a new standard setup, called \tr{fast}. The name is +inappropriate at present, but it is intended to be for people who +value compiled-code-speed above all else (within reason, of course). + +%************************************************************************ +%* * +\subsection[0-08-new-misc]{Miscellaneous new things} +%* * +%************************************************************************ + +New version of Denis Howe's \tr{mira2hs} script. diff --git a/ghc/docs/release_notes/0-10-notes.lit b/ghc/docs/release_notes/0-10-notes.lit new file mode 100644 index 0000000000..9048e8a1bc --- /dev/null +++ b/ghc/docs/release_notes/0-10-notes.lit @@ -0,0 +1,72 @@ +Release~0.10 was the first major, public release of this compilation +system. + +The announcement (now distributed in \tr{ghc/docs/ANNOUNCE-0.10}) +describes the most notable features of this release. These notes, +therefore, just cover some of the fine points... + +%************************************************************************ +%* * +\subsection[0-10-new-docs]{New documentation} +%* * +%************************************************************************ + +We're providing a few more papers, in \tr{ghc/docs/papers}. See +\tr{ghc/docs/README} for a full list of documentation. + +%************************************************************************ +%* * +\subsection[0-10-new-in-usage]{User-visible changes} +%* * +%************************************************************************ + +An ``Appel-style'' generational garbage collector is now the default. +(It used to be a two-space copying collector.) + +The flag to use the unboxery and other Glasgow extensions was +\tr{-funboxed}. We've changed it to \tr{-fglasgow-exts}. We may +elaborate this further, eventually... + +(If 0.06 is the last version you looked at, flags/options have changed +a fair bit since then.) + +%************************************************************************ +%* * +\subsection[0-10-new-in-compiler]{New in the compiler proper} +%* * +%************************************************************************ + +Derived instances are in, well partly. We'll put in the rest when +there's a demand (or we have nothing better to do). + +@Integers@ (arbitrary-precision integers) are now in properly. +Just as HBC does, we use the GNU multi-precision arithmetic package. +Source is in \tr{ghc/runtime/gmp}. + +We did a bunch of stuff in the typechecker region to support +overloading better; we called it ``dictionary stomping.'' One +side-effect of this work is that error messages related to overloading +have a slight chance of being sensible (which they weren't before). + +``Primitive arrays,'' on top of which efficient, regular Haskell +arrays can be (are) built, went in. There's a {\em little} about +using them, in the ``Glasgow extensions'' section of the User's Guide. + +Similarly, the mechanisms for calling C directly (@ccall@ and @casm@) +are more likely to be useful. Again, a little documentation in the +same place... + +%************************************************************************ +%* * +\subsection[0-10-new-in-libraries]{In the prelude and runtime support} +%* * +%************************************************************************ + +Our standard prelude conforms to the Haskell~1.2 report. + +We support a non-standard @fromInt@ method for the @Num@ class, just as +HBC does. + +We support a non-standard @cmp3@ method for the @Ord@ class. Snoop +around in the \tr{ghc/lib/prelude/*.hs} code, if you care. (We use it +in code generated for derived instances.) diff --git a/ghc/docs/release_notes/0-16-notes.lit b/ghc/docs/release_notes/0-16-notes.lit new file mode 100644 index 0000000000..ba2d504062 --- /dev/null +++ b/ghc/docs/release_notes/0-16-notes.lit @@ -0,0 +1,106 @@ +Release~0.16 was the second public release of this compilation system. +It was primarily a bug-fixing and ``solidifying'' release. + +The announcement for this release is distributed as \tr{ANNOUNCE-0.16} +in the top-level directory. + +%************************************************************************ +%* * +\subsection[0-16-new-docs]{New documentation} +%* * +%************************************************************************ + +We're providing a few more papers, in \tr{ghc/docs/papers}. See +\tr{ghc/docs/README} for a full list of documentation. + +%************************************************************************ +%* * +\subsection[0-16-new-in-compiler]{New in the compiler proper} +%* * +%************************************************************************ + +New strictness analyser and update analyser; their use will be +reflected in the pragmas in your interface files. The format of these +interface pragmas {\em will probably change}. + +Errors related to misuse of Prelude identifiers are more likely to be +caught. + +For some unknown reason, our ``wired-in'' default declaration in 0.10 was +\tr{default (Integer,Double)}. We changed it to +\tr{default (Int,Double)}, as the Report suggests (which is less safe). + +We've switched from basing our derived instances on a non-standard +@cmp3@ method (class @Ord@), to basing them on another non-standard +method @tagCmp@. The relevant types and things are... +\begin{verbatim} +cmp3 :: b -> b -> b -> a -> a -> b + +tagCmp :: a -> a -> CMP_TAG +data CMP_TAG = LT_TAG | EQ_TAG | GT_TAG +\end{verbatim} +If you peer into the \tr{ghc/lib/prelude/*.hs} code, it will be +obvious what's going on here. We hope to make further improvements +on comparison code in the foreseeable future. + +%************************************************************************ +%* * +\subsection[0-16-new-in-libraries]{In the prelude and runtime support} +%* * +%************************************************************************ + +The libraries underpinning Glasgow monadic I/O, sequencing, primitive +arrays, and variables have been reworked, with some consequent +changes. If you encounter difficulties, you should consult the +@PreludeGlaIO.hi@ and @PreludeGlaArray.hi@ interfaces in your +\tr{imports} directory. + +Andy Gill's proposal for access to standard Haskell I/O functions from +the monadic I/O world has been implemented. So you have functions +such as @getArgsIO@, @appendChanIO@, etc., etc. + +The stuff you used to get from @Stdio.hi@ now comes directly from +@PreludeGlaIO.hi@. + +The @packString#@ function has been moved into a module of its own, +@PackedString@, and {\em its type has changed}. The functions now in +that module are (to be elaborated...): +\begin{verbatim} +packString :: String -> PackedString +packString# :: String -> Arr# Char# +\end{verbatim} +The latter is very useful to preparing @String@ arguments to pass to C. + +The HBC library modules that compile readily with GHC are available, +you'll need to give a \tr{-lHShbc} option to the driver. These +modules are: +\begin{verbatim} +Either, Hash, ListUtil, Maybe, Miranda, Number, Parse, Pretty, QSort, +Random, Time, Word +\end{verbatim} + +The GNU multi-precision (GMP) package which underpins our @Integer@ +support has been upgraded to version 1.3.2. + +%************************************************************************ +%* * +\subsection[0-16-new-elsewhere]{New elsewhere} +%* * +%************************************************************************ + +0.16 has a new and much uglier ``assembler mangler'' +(\tr{ghc/driver/ghc-asm-*.lprl}), which is what converts GCC-produced +assembly-language output into the stuff you actually run. Besides +throwing away function prologues/epilogues, it parks ``info tables'' +next to entry code, and fast-entry code right next to slow-entry code. + +The net effect of this assembler-mangler is that there is {\em very +little runtime penalty} for compiling via GCC. + +The way we go about mapping ``STG registers'' to real machine +registers (\tr{ghc/imports/StgRegs.lh}) is different. It should be +particularly better for machines with few registers (though we still +don't have a good solution for x86 machines). + +We can now ``steal'' caller-save registers; in the past, we could only +steal callee-save registers. diff --git a/ghc/docs/release_notes/0-17-notes.lit b/ghc/docs/release_notes/0-17-notes.lit new file mode 100644 index 0000000000..5528f2a7b5 --- /dev/null +++ b/ghc/docs/release_notes/0-17-notes.lit @@ -0,0 +1 @@ +Added @getProgNameIO@ and @getProgNameIOE@ (inadvertently omitted). diff --git a/ghc/docs/release_notes/0-18-README b/ghc/docs/release_notes/0-18-README new file mode 100644 index 0000000000..dc6ec5f953 --- /dev/null +++ b/ghc/docs/release_notes/0-18-README @@ -0,0 +1,63 @@ +This is version 0.18 of the Glasgow Haskell compiler. + +0.18 is an "internal" release intended *ONLY* for those actually +hacking on the compiler source -- that is, those who *REALLY* know +what they are doing. Anyone else is crazy to use it; anyone who uses +it without keeping a "real" GHC release (0.16 or 0.17) around is +obviously demented. + +The chances of a "clean" build are near zero, no matter what Haskell +compiler you build with. Be prepared to utter magic incantations. +(For example, `make reader/ReadPragmas.o +EXTRA_HC_OPTS="-fno-strictness -fno-specialise -fno-case-of-case"'.) + +An incomplete "what's new" list: + +* Unfoldings across module boundaries. Still v limited. + +* Specialisation of overloaded functions. Instances -- not yet. + +* Strictness analyser that handles "nested" strictness and does + "absence analysis" as well. Makes Prelude.hi fun to read. Hints: + _N_ = nothing, _A_ = arity, _U_ = update analysis info, _S_ = + strictness (U = unpack, A = absent, L = lazy, S = strict, E = strict + & enumeration type, P = primitive). + +* Prelude info no longer horribly built into the compiler (as much). + Manipulating the prelude is not nearly so delicate as it once was. + +* Some names have changed: MkChar => C#, MkInt => I#, MkFloat => F#, + MkDouble => D#, MkInteger => J#. (They won't change again...) + +* Includes Patrick Sansom's array-based substitution code (much faster + typechecking). (You probably won't see the speedup, though, because + we've spent all the savings on fancier intermodule stuff.) + +* We've added a Core "lint" pass, which can be used to check + types/out-of-scope-errors/etc after every Core-to-Core pass. It's + great! -dcore-lint. + +* Initial "Native" class support; use "-syslib hbc". + +* Lots of compiler code hacked on, for better or worse. + +* Lots of gratuitous "trace" messages when running the compiler :-) + +Documentation is unchanged since 0.1[67]. There is not one word about +any new features. + +We *hope* for a new public release before Christmas (1993). + +Will Partain +Keeper of the Bits, AQUA Project + +Dated: 93/11/04 + +E-mail contacts: + glasgow-haskell-bugs@dcs.glasgow.ac.uk (bug reports) + glasgow-haskell-request@dcs.glasgow.ac.uk (general queries) + +Anonymous FTP site: ftp.dcs.glasgow.ac.uk:pub/haskell/glasgow. Mostly +mirrored by ftp.cs.chalmers.se and nebula.cs.yale.edu (same +directory). Also: src.doc.ic.ac.uk, in +computing/programming/languages/haskell/glasgow/. diff --git a/ghc/docs/release_notes/0-19-notes.lit b/ghc/docs/release_notes/0-19-notes.lit new file mode 100644 index 0000000000..66c102453c --- /dev/null +++ b/ghc/docs/release_notes/0-19-notes.lit @@ -0,0 +1,187 @@ +Release~0.19 was the third public release of this compilation system. +It incorporates our new work for the last half of 1993. + +The announcement for this release is distributed as \tr{ANNOUNCE-0.19} +in the top-level directory. + +%************************************************************************ +%* * +\subsection[0-19-user-visible]{User-visible changes in 0.19, including incompatibilities} +%* * +%************************************************************************ + +You'll need to recompile everything if you're switching from a +previous version of GHC. (If you don't, you'll get ``consistency +errors''.) + +Default declarations: in. + +Derived instances of \tr{Ix} and \tr{readsPrec} (\tr{Text} class): in. +(Random Prelude instances of weird things: in.) You can avoid the +\tr{readsPrec} methods by using the \tr{-fomit-derived-read} option. + +Should be {\em faster}, for two reasons: (1)~A native-code generator +for the SPARC architecture (avoids C compilation time); (2)~an +array-based [vs naive list-based...] substitution mechanism in the +typechecker. Using \tr{-O2} or \tr{-fvia-C} avoids the native-code +generator. + +(Shouldn't be too much faster, because we spent a lot of the winnings +:-() + +\tr{MkInt} and friends {\em renamed}: \tr{MkInt}, \tr{MkChar}, +\tr{MkFloat}, \tr{MkDouble}, and \tr{MkInteger} are now \tr{I#}, +\tr{C#}, \tr{F#}, \tr{D#}, and \tr{J#}, respectively. +We won't change them again, we promise. + +\tr{-i}/\tr{-I} flags changed: You used to specify directories to +search for interface files with \tr{-I <dir>}; now you do it with +\tr{-i<dir>} [{\em no space after the \tr{-i}}] (same as HBC). +\tr{-I} is reserved for when doing \tr{-cpp} and for the C compiler, +when it is run. + +Renaming, feature horribilis that it is, is more-or-less fully +implemented. The User's Guide lists one or two exceptions. + +Specialised versions of overloaded functions: these are created +automagically with \tr{-O}, and also when you ask for them with +\tr{SPECIALIZE} pragmas. See the User's Guide for how to do this +(same as HBC). (We don't have specialised instance declarations yet.) + +GHC tries hard to do inlining (or ``unfolding'') across module +boundaries; just look at \tr{-O}-produced interface files. You can +enliven this process with \tr{INLINE} pragmas. + +The \tr{__GLASGOW_HASKELL__} CPP directive is only set when +pre-processing Haskell source (and not when pre-processing generated +C). + +Revised scheme for using system-provided libraries (e.g., the HBC +library). Just use a \tr{-syslib <name>} option when compiling and +linking. See the User's Guide for details. + +%************************************************************************ +%* * +\subsection[0-19-new-docs]{New documentation} +%* * +%************************************************************************ + +See \tr{ghc/docs/README} for a full list of documentation. + +The updated User's Guide has new sections including: (a)~advice for +creating smaller and faster programs more quickly, and (b)~about the +HBC library [stolen documentation]. + +We've dropped papers from the distribution (they're big, and you can +get them easily anyway); instead, we provide abstracts of all +documents about all relevant work at Glasgow; see +\tr{ghc/docs/abstracts}. + +New: ``A Simple Country Boy's Guide to Monadic-Style Programming'' (Will +Partain). In \tr{ghc/docs/simple-monad.lhs}. + +%************************************************************************ +%* * +\subsection[0-19-new-in-compiler]{New in the compiler proper} +%* * +%************************************************************************ + +Strictness analyser: produces/handles ``nested'' strictness -- e.g., +\tr{U(SLL)} means ``this single-constructor argument is strict, and it +is also strict in its first component.'' There's also ``absence +analysis'' in there: \tr{U(ASA)} means ``strict in the second +component, and the first/third are not used at all.'' + +New simplifier: the program-transformation engine in the middle of the +compiler. The ``old simplifier,'' primarily the work of Andr\'e +Santos, has retired to an Old Simplifier's Home on the coast of +Brazil, where it is collecting a well-deserved monadic pension. + +%************************************************************************ +%* * +\subsection[0-19-new-in-libraries]{In the prelude and runtime support} +%* * +%************************************************************************ + +A couple of new functions in the @PackedString@ module that comes with +the system. Mentioned in the User's Guide. + +The HBC library has been upgraded to match the latest HBC release +(0.999.5). We now support the \tr{Native} and \tr{NameSupply} +modules, which we didn't before. + +Alastair Reid's implementation of ``stable pointers,'' which he uses +to do callbacks with the X Window System (yow!), is in. I (WDP) don't +know about documentation.... send mail if you need to know. + +%************************************************************************ +%* * +\subsection[0-19-new-ports]{In the porting department} +%* * +%************************************************************************ + +We use Sun4s running SunOS~4.1.3, so those are the best-supported +machines. For these, we have a native-code generator (the best); next +best is a ``registerised'' port; the bare minimum is an +``unregisterised'' port. + +The 0.19 infrastructure for ``stealing'' registers for a registerised port +(using a GCC extension) is much more robust---take note, brave porters. + +Here's everying that's known about the porting world: +\begin{description} +%------------------------------------------------------------------- +\item[Sun3 running SunOS~4.1.3:] +A registerised port is done; could be made available. + +%------------------------------------------------------------------- +\item[GRIP multiprocessor:] +68020-based multiprocessor for running parallel Haskell programs. +A registerised port is done; too bad we have the only machine! +If you have something parallel you {\em really} wanted to run on it, +please get in touch with us. + +%------------------------------------------------------------------- +\item[HP-PA box running HP/UX:] +An unregisterised port of 0.17 (0.16+portability fixes) seems to +work, except that floating-point is definitely busted. 0.19~should be +no worse. + +%------------------------------------------------------------------- +\item[DECstation (MIPS-based):] +An unregisterised port of 0.17 works; 0.19~should be the same. + +%------------------------------------------------------------------- +\item[DEC Alpha running OSF/1:] +We've done an unregisterised port (unreleased), and a registerised +port is not far off. + +%------------------------------------------------------------------- +\item[Sun running Solaris 2.x:] +We've started on this ourselves and foresee no obstacle to a +``registerised'' port. Not sure about native-code... + +%------------------------------------------------------------------- +\item[x86 PCs running Linux:] +This really needs a native-code generator to be viable. We hope the +elves will give us one for Christmas! + +%------------------------------------------------------------------- +\item[Macintosh, using MPW:] +As mind-blowing at it may seem, David Wright in Tasmania has actually +gotten GHC to run on a Macintosh. I believe it's still in the ``you +can do it, but you don't want to'' stage. +\end{description} + +%************************************************************************ +%* * +\subsection[0-19-new-elsewhere]{New elsewhere} +%* * +%************************************************************************ + +In the ``literate programming'' stuff that happens to come with GHC: a +few bug fixes, plus a significant contribution from Chris Toshok +(\tr{toshok@cs.uidaho.edu}) of ``lit2html'' stuff; i.e., to convert +your literate programs into HTML, the Hypertext Markup Language used +on the World-Wide Web. I (WDP) am not sure it's completely finished, +or exactly what you invoke to do what, but it seems Way Cool. diff --git a/ghc/docs/release_notes/0-22-notes.lit b/ghc/docs/release_notes/0-22-notes.lit new file mode 100644 index 0000000000..aa9e72205b --- /dev/null +++ b/ghc/docs/release_notes/0-22-notes.lit @@ -0,0 +1,205 @@ +Release~0.22 is the fourth public release of Glasgow Haskell. +It incorporates our new work for the first half of 1994. + +The announcement for this release is distributed as \tr{ANNOUNCE-0.22} +in the top-level directory. + +%************************************************************************ +%* * +\subsection[0-22-ports]{What machines GHC~0.22 runs on} +%* * +%************************************************************************ + +We use Sun4s running SunOS~4.1.3 and DEC~Alphas running OSF/1~V2.0, so +those are the ``fully-supported'' platforms, unsurprisingly. For +Sun4s, we have a native-code generator, which makes for somewhat +quicker compilations. (We actually produce better code by compiling +intermediate C with GCC.) + +The GHC hierarchy of Porting Goodness: (a)~Best is a native-code +generator [only for Sun4s, now]; (b)~next best is a ``registerised'' +port; (c)~the bare minimum is an ``unregisterised'' port. +``Unregisterised'' Haskell programs are much bigger and slower, +but the port is much easier to get going. + +Here's everything that's known about GHC ports, as of 0.22: +\begin{description} +%------------------------------------------------------------------- +\item[Sun4 running SunOS~4.1.3:] +Fully supported, including native-code generator. + +%------------------------------------------------------------------- +\item[DEC Alpha running OSF/1 V2.0:] +Fully supported, but no native-code generator (none planned). + +%------------------------------------------------------------------- +\item[Sun3 running SunOS~4.1.3:] +GHC~0.22 should work, registerised. (0.21 did work.) + +%------------------------------------------------------------------- +\item[Sun4 running Solaris 2.x:] +We expect to finish a ``registerised'' port ourselves, in the +foreseeable future. Feel free to ask about it, if interested. Not +sure about native-code... + +%------------------------------------------------------------------- +\item[HP-PA box running HP/UX 9.x:] +An unregisterised port of 0.21 (last ``internal'' release before 0.22) +seems to work, except that floating-point is definitely busted. +0.22~should be the same. + +%------------------------------------------------------------------- +\item[Silicon Graphics box running IRIX 5.x:] +An unregisterised port of 0.21 +seemed to work. 0.22~should be the same. + +%------------------------------------------------------------------- +\item[DECstation (MIPS-based):] +An unregisterised port back around the time of 0.17 seemed to work; +0.22~should be the same, modulo a little bit-rot. + +%------------------------------------------------------------------- +\item[x86 PCs running Linux/NetBSD/FreeBSD:] +This really needs a native-code generator to be viable. No +recent progress. + +%------------------------------------------------------------------- +\item[GRIP multiprocessor:] +GRIP is a 68020-based multiprocessor for running parallel Haskell +programs; too bad we have the only machine! We run GHC~0.16 on it, +with no plans to upgrade. + +We are working on other parallel stuff. Stay tuned. + +%------------------------------------------------------------------- +\item[NeXT box running whatever NeXTs run:] +Carsten Schultz succeeded with a ``registerised'' port of GHC~0.19. +There's probably a little bit-rot since then, but otherwise it should +still be fine. + +%------------------------------------------------------------------- +\item[Macintosh, using MPW:] +As mind-blowing at it may seem, David Wright in Tasmania has actually +gotten GHC to run on a Macintosh. Ditto James Thomson here at Glasgow. +You may be able to get Thomson's from here. (Not sure that it will +excite you to death, but...) +\end{description} + +%************************************************************************ +%* * +\subsection[0-22-user-visible]{User-visible changes in 0.22, including incompatibilities} +%* * +%************************************************************************ + +You'll need to recompile everything if you're switching from a +previous version of GHC. (If you don't, you'll get ``consistency +errors''.) + +Lazy pattern-matching (e.g., \tr{let (x,y) = ... in ...}) no longer +carries with it the threat of a space leak. (It used to be that, as +long as {\em either} of \tr{x} or \tr{y} was ``live,'' the storage +manager would hang onto {\em both} chunks of graph.) No longer. + +We've done a complete overhaul of the state-transformer stuff which +underlies our array, I/O, and C-calling support. The ``state +interface document,'' distributed in \tr{ghc/docs/state-interface.dvi} +defines what we have done. You may wish to check our abstracts +(\tr{ghc/docs/abstracts/}) to find papers about this stuff. If you've +written code that grovels around in GHC innards (e.g., uses +``primitive operations'' directly), it will probably need updating. + +We do {\em not} support Haskell~1.3 monadic I/O (any draft version), +but we will once the dust settles. We still support the +\tr{PreludeGlaIO} interface that we have had for some time. + +You can now build GHC to support ``threaded'' execution. (Configure +\tr{--with-threads=yes}, then use GHC with a \tr{-threads} option.) +Using the \tr{_seq_} and \tr{_par_} constructs, + +GHC does a better job of not stealing from the user's name space (for +its own extensions, etc.). For example, the ``set cost-centre'' +keyword is now \tr{_scc_}, rather than \tr{scc} (though the latter +will continue to be accepted for a while). With the +\tr{-fglasgow-exts} flag on, names may begin with an underscore +(\tr{_}). + +We have friendly interaction between ``Haskell land'' and ``C land'' +via (a)~{\em stable pointers} (pass Haskell pointers to C and have the +garbage-collector not forget about them); and (b)~{\em malloc +pointers} (return C pointers to Haskell and tell Haskell ``throw this +away when you're finished with it''). See the User's Guide for more +info. + +%************************************************************************ +%* * +\subsection[0-22-support]{New in support tools (e.g., profiling)} +%* * +%************************************************************************ + +The profiling system of GHC has been improved in version~0.22 in the +following ways: +\begin{description} +\item[Now uses the ``hybrid scheme'':] (Rather than pure ``lexical +scoping'') What this means for you: ``CAF'' cost-centres will no +longer be blamed for gigantic chunks of the time in your program. + +\item[Uses the generational garbage-collector:] (At least when doing +time profiling) It used to use a two-space copying GC; it still does +when space profiling. You should be able to profile larger programs. +\end{description} + +%************************************************************************ +%* * +\subsection[0-22-new-in-compiler]{New in the compiler proper} +%* * +%************************************************************************ + +The ``simplifier''---the program-transformation engine in the middle +of the compiler---has settled down (at least until Simon has another +Brain Wave). We've made ``per-simplification'' flags, so that each +run of the simplifier can be controlled separately---this allows very +precise control. (But makes it pretty hard to exercise any control +from the command-line.) More in the docs. + +Related to simplifier stuff was a revision of the ``unfoldery'' +machinery. We try very hard to find and exploit unfolding (or +inlining), including across module boundaries. + +%************************************************************************ +%* * +\subsection[0-22-new-in-libraries]{In the prelude and runtime support} +%* * +%************************************************************************ + +We've introduced a ``GHC system library,'' similar to the ``HBC system +library'' which we have supported for some time. Just say +\tr{-syslib ghc} and the GHC library stuff is at your fingertips. +See the User's Guide for exactly what's on offer (not a lot right now, +but more will show up). + +The @PackedString@ module that comes with the system is even beefier +than before; see the User's Guide. (This module really should be +in the GHC library.) + +%************************************************************************ +%* * +\subsection[0-22-new-elsewhere]{Other new stuff} +%* * +%************************************************************************ + +We have two new mailing lists about Glasgow Haskell. +\begin{description} +\item[glasgow-haskell-users:] +This list is for GHC users to chat among themselves. Subscribe by +sending mail to \tr{glasgow-haskell-users-request@dcs.glasgow.ac.uk}. +Messages for the list go to \tr{glasgow-haskell-users}. + +\item[glasgow-haskell-bugs:] +This used to be an address for some lonely person who received bug +reports. It is now a mailing list for the sort of people who discuss, +well, bug reports when they go to a party. + +Subscribe via \tr{glasgow-haskell-bugs-request@dcs.glasgow.ac.uk}; +send bug reports and rumination thereupon go to +\tr{glasgow-haskell-bugs}. +\end{description} diff --git a/ghc/docs/release_notes/0-23-notes.lit b/ghc/docs/release_notes/0-23-notes.lit new file mode 100644 index 0000000000..196592c84b --- /dev/null +++ b/ghc/docs/release_notes/0-23-notes.lit @@ -0,0 +1,253 @@ +Release~0.23 is the fifth public release of Glasgow Haskell. +It incorporates our new work for the second half of 1994. + +The announcement for this release is distributed as \tr{ANNOUNCE-0.23} +in the top-level directory. + +%************************************************************************ +%* * +\subsection[0-23-ports]{What machines GHC~0.23 runs on} +%* * +%************************************************************************ + +NOTE: the porting situation is essentially unchanged between 0.22 and +0.23, except for adding the native-code generator for DEC Alphas. + +We use Sun4s running SunOS~4.1.3 and DEC~Alphas running OSF/1~V2.0, so +those are the ``fully-supported'' platforms, unsurprisingly. Both +have native-code generators, for quicker compilations. + +The GHC hierarchy of Porting Goodness: (a)~Best is a native-code +generator; (b)~next best is a ``registerised'' +port; (c)~the bare minimum is an ``unregisterised'' port. +``Unregisterised'' Haskell programs are much bigger and slower, +but the port is much easier to get going. + +Here's everything that's known about GHC ports, as of 0.23: +\begin{description} +%------------------------------------------------------------------- +\item[Sun4 running SunOS~4.1.3 (\tr{sparc-sun-sunos4}):] +Fully supported, including native-code generator. + +%------------------------------------------------------------------- +\item[Sun4 running Solaris 2.x (\tr{sparc-sun-solaris2}):] +Fully supported, including native-code generator. +(NB: not tested before release.) + +%------------------------------------------------------------------- +\item[DEC Alpha running OSF/1 V2.0 (\tr{alpha-dec-osf1}):] +Fully supported, including native-code generator. + +%------------------------------------------------------------------- +\item[Sun3 running SunOS~4.1.3 (\tr{m68k-sun-sunos4}):] +GHC~0.23 works registerised. No native-code generator. + +%------------------------------------------------------------------- +\item[HP-PA box running HP/UX 9.x:] +An unregisterised port of 0.21 (last ``internal'' release before 0.23) +seems to work, except that floating-point is definitely busted. +0.23~should be the same. + +%------------------------------------------------------------------- +\item[Silicon Graphics box running IRIX 5.x:] +An unregisterised port of 0.21 +seemed to work. 0.23~should be the same. + +%------------------------------------------------------------------- +\item[DECstation (MIPS-based):] +An unregisterised port back around the time of 0.17 seemed to work; +0.23~should be the same, modulo a little bit-rot. + +%------------------------------------------------------------------- +\item[x86 PCs running Linux/NetBSD/FreeBSD:] +This really needs a native-code generator to be viable. No +recent progress. + +%------------------------------------------------------------------- +\item[GRIP multiprocessor:] +GRIP is a 68020-based multiprocessor for running parallel Haskell +programs; too bad we have the only machine! We run GHC~0.16 on it, +with no plans to upgrade. + +We are working on other parallel stuff. Stay tuned. + +%------------------------------------------------------------------- +\item[NeXT box running whatever NeXTs run:] +Carsten Schultz succeeded with a ``registerised'' port of GHC~0.19. +There's probably a little bit-rot since then, but otherwise it should +still be fine. Had a report that things were basically OK at 0.22. + +%------------------------------------------------------------------- +\item[Macintosh, using MPW:] +As mind-blowing at it may seem, David Wright in Tasmania has actually +gotten GHC to run on a Macintosh. Ditto James Thomson here at Glasgow. +You may be able to get Thomson's from here. (Not sure that it will +excite you to death, but...) +\end{description} + +%************************************************************************ +%* * +\subsection[0-23-config]{New configuration things in 0.23} +%* * +%************************************************************************ + +Essentially, upgraded to Autoconf~2. Probably the easiest way to see +what all the options are now is to type \tr{./configure --help} and +look at the stuff near the end. + +%************************************************************************ +%* * +\subsection[0-23-user-visible]{User-visible changes in 0.23, including incompatibilities} +%* * +%************************************************************************ + +You'll need to recompile everything if you're switching from a +previous version of GHC. (If you don't, you'll get ``consistency +errors''.) Some day, we will stop doing this to you :-) + +Monadic I/O has taken yet another shake-up; that is outlined in the +next section. + +To use the 1.3-DRAFT I/O features, you use a \tr{-fhaskell-1.3} flag. +This also nets you, from your Prelude, the \tr{Maybe} and \tr{Either} +types, and the functions \tr{thenMaybe}, \tr{curry}, and \tr{uncurry}. + +The driver supports a heap-and-stack-sizes scaling flag. For example, +\tr{-Rscale-sizes2} would cause the driver to use twice as much +heap/stack space as it would otherwise. This is a convenient way to +move between machines with differing memory setups (e.g., 32-bit vs +64-bit) without changing millions of -H flags in a Makefile. Note: +something like \tr{-Rscale-sizes1.5} is OK, too. + +``Lit-lit'' literals are now overloaded. They can be any +\tr{_CCallable} type, not just \tr{_Addrs}. The price of this extra +convenience is that you sometimes have to insert a type signature. + +The shift-right primitive-operation, \tr{shiftR#}, has been renamed +and clarified to \tr{shiftRA#} (arithmetic). A new prim-op +\tr{shiftRL#} (logical) has been added. + +Comparable shift primitive-ops on \tr{Int#s} (rather than \tr{Word#s}) +have been added: \tr{iShiftL#}, \tr{iShiftRA#}, and \tr{iShiftRL#}. +Long live high-level languages! + +%************************************************************************ +%* * +\subsection[0-23-io]{New in I/O, esp. ``monadic,'' esp. ``1.3''} +%* * +%************************************************************************ + +GHC~0.23 is still a Haskell~1.2 compiler. Do nothing weird, and it +should work exactly as before. + +If you give GHC a \tr{-fhaskell-1.3} flag (both compile and link time, +please!), it will use a VERY EARLY, LARGELY UNTESTED implementation of +the DRAFT 1.3 I/O PROPOSAL. + +The \tr{PreludeGlaIO} interface, which was based on a long-ago 1.3 I/O +proposal, is DEAD. It was in a pretty bad state, anyway. +Putting \tr{PreludeGlaIO} code through as 1.3 code, I got pretty +far with just these few impedance-matching definitions: +\begin{verbatim} +> type Void = () +> returnIO = return +> thenIO = (>>=) +> mapIO :: (a -> IO b) -> [a] -> IO [b] +> mapIO f = accumulate {-was:listIO-} . map f +\end{verbatim} + +We supply the DRAFT 1.3 I/O PROPOSAL in \tr{ghc/docs/io-1.3/}. +It is in HTML format. + +We still give access to our underlying \tr{PrimIO} monad, via the +\tr{PreludePrimIO} interface. This is the level at which \tr{_ccall_s} +operate. It should still be quite solid, and counts as a good fall-back +position when the 1.3-DRAFT stuff dies on you. See the User's Guide. + +%************************************************************************ +%* * +\subsection[0-23-support]{New in support tools (e.g., profiling)} +%* * +%************************************************************************ + +The reports from profiling should be a bit tidier. The ``automagic'' +cost-centres for, e.g., ``all the CAFs in module X'', will now be +reported against \tr{CAFs_in_... X}. Which seems fair enough. + +GHCI---an INTERPRETER for Glasgow Haskell! The brainchild and work of +Alastair Reid, before he defected to the Enemy at Yale. Accepts full +Glasgow Haskell, including many extensions. Can mix interpreted and +compiled code, the Prelude being a notably case of the latter. +MASSIVE HACK VALUE! The problem is it doesn't quite compile under +0.23 (I ran out of time), and some of its dodgy bits (used to mix +interpreted and compiled code) need upgrading to work with the new +info tables. It lives in \tr{ghc/compiler} and below, notably the +\tr{interpreter} subdirectory. Don't be shy now---roll up your +sleeves and strut your hacking stuff! + +%************************************************************************ +%* * +\subsection[0-23-new-in-compiler]{New in the compiler proper} +%* * +%************************************************************************ + +The compiler is quite a bit faster at compiling, {\em without} +\tr{-O}. We are in the HBC league now. I don't remember all the +HACKs that we threw in to make this happen :-) + +New-format ``info tables'' (work by Bryan O'Sullivan and friends). +Essentially, static info used by the garbage-collector has been moved +one indirection further away, into a ``rep table,'' of which there are +a fixed number. So the same GC info isn't replicated over and over +again. This is our main space-savings gain in 0.23. + +A native-code generator for the DEC Alpha. Jim Mattson did it in one +weekend. What a great system! + +Rather than have a separate Yacc-parser process that spews a long +``prefix form'' string into the compiler, the compiler now just does a +\tr{_ccall_ yyparse} and then walks the resulting parse tree directly. +(Not quite {\em that} simple, but... still pretty cool.) + +A {\em selective} lambda-lifter. (Simon is very excited about its +selectiveness.) That means it only does lambda-lifting if there is a +benefit in doing so. It's done on the STG syntax (quite late in the +compilation). + +%************************************************************************ +%* * +\subsection[0-23-new-in-libraries]{In the prelude and runtime support} +%* * +%************************************************************************ + +PackedStrings (now called \tr{_PackedString}s) are now a built-in +type, just like \tr{Int}s, say. Their interface is described with the +Glasgow extensions in the User's Guide. There is also a +``extensions-free'' interface (no underscores on the front of names) +which you can get at as a system library (\tr{-syslib ghc}). + +The pretty-printing code that we use in GHC is now available in the +GHC system library (\tr{-syslib ghc} and \tr{import Pretty}). We +would claim it is more ``industrial strength'' than the one in the HBC +system library... + +Because of name-grabbing by the DRAFT-1.3-I/O, two functions in the +HBC library's \tr{Parse} module have been renamed: \tr{(>>)} is now +\tr{act}, and \tr{fail} is now \tr{failP}. (We will change these +again if Lennart does something differently.) + +%************************************************************************ +%* * +\subsection[0-23-new-elsewhere]{Other new stuff} +%* * +%************************************************************************ + +We've added a new utility, \tr{pphs}, for pretty-printing Haskell code +in LaTeX documents. It was written by Andrew Preece, a student at +Glasgow. The code is in \tr{ghc/CONTRIB/pphs}. + +Over in literate-land, we've hidden a copy of a slightly-tweaked +\tr{texi2html} script (in \tr{literate/texi2html/texi2html}). This is +probably the most painless way to turn ``literate'' things into +Webbable HTML documents. (Use our literate stuff to make Texinfo +files, then convert with \tr{texi2html}.) NB: not really tested. diff --git a/ghc/docs/release_notes/0-26-notes.lit b/ghc/docs/release_notes/0-26-notes.lit new file mode 100644 index 0000000000..b10c7e1c40 --- /dev/null +++ b/ghc/docs/release_notes/0-26-notes.lit @@ -0,0 +1,244 @@ +Release~0.26 is a major public release of Glasgow Haskell. +It incorporates our new work for the first half of 1995. + +The announcement for this release is distributed as \tr{ANNOUNCE-0.26} +in the top-level directory. + +You'll need to recompile everything if you're switching from a +previous version of GHC. (If you don't, you'll get ``consistency +errors''.) Some day, we will stop doing this to you :-) + +Information about ``what's ported to which machine'' is now given in +the Installation Guide. +The new ports since 0.23 are: \tr{hppa1.1-hp-hpux}, +\tr{i386-*-linuxaout}, and \tr{mips-sgi-irix5}. + +%************************************************************************ +%* * +\subsection[0-26-config]{New configuration things in 0.26} +%* * +%************************************************************************ + +We are moving towards one \tr{configure} script for all Glasgow +functional-programming tools. Consequently, the configure options +have been tweaked. Doing \tr{./configure --help} will show you the +current state of play. + +%************************************************************************ +%* * +\subsection[0-26-user-visible]{User-visible changes in 0.26, including incompatibilities} +%* * +%************************************************************************ + +The names \tr{scc}, \tr{ccall}, and \tr{casm} are no longer stolen +from the user's name space. (The magical constructs they once were +have been known as \tr{_scc_}, \tr{_ccall_}, and \tr{_casm_} for some +time now...) + +Similarly, \tr{trace} is no longer built-in (so you can use the name +if you want to). You can get \tr{trace} either as \tr{_trace} +(Glasgow extension), or as itself via \tr{import Trace} with +\tr{-syslib hbc} (i.e., exactly like HBC). + +Lazy, or irrefutable, patterns with unboxed-type components are +no longer allowed. You'll need to rewrite \tr{let (I# x) = exp ...} +as \tr{let x = case exp of { I# i -> i } in ... }. + +GHC now supports hexadecimal and octal numeric syntax for integer constants. +(But \tr{read} doesn't grok it yet...) + +GHC now supports specialised instances (as in HBC); you can write: +\begin{verbatim} +instance Eq a => Eq (Foo a) where { ... } +{-# SPECIALIZE instance Eq (Foo Bool) #-} +\end{verbatim} + +GHC's pragmas for specialised values now have a magical \tr{= blah} +form, in which you specify the code to be used for the specialised value. +For example: +\begin{verbatim} +f :: Ord a => a -> Int -> a +{-# SPECIALIZE f :: Double -> Int -> Double = f_Double #-} + +f_Double :: Double -> Int -> Double +f_Double ... +\end{verbatim} +In some cases, the \tr{= blah} form can be a {\em big} win. + +What we used to call ``threaded'' Haskell, we now call ``Concurrent +Haskell.'' And there's a paper about it. Please see the User's Guide. + +``Parallel Haskell,'' running under PVM, is here. Again, see the +User's Guide. + +%************************************************************************ +%* * +\subsection[0-26-options]{New or changed GHC command-line options} +%* * +%************************************************************************ + +The \tr{-g}, \tr{-p}, \tr{-pg}, \tr{-fpic}, and \tr{-fPIC} are no +longer passed straight through to GCC. They probably buy you nothing, +while potentially causing substantial mischief. If you know what you're doing, +you can still use them, via \tr{-optcO-...}. + +The main option for Concurrent Haskell is \tr{-concurrent}; for +Parallel Haskell, it's \tr{-parallel}. + +The \tr{-dict-all} option, used with \tr{-prof}, has died. It never +did anything anyway. + +Besides the \tr{-fshow-specialisations} option to see what specialisations +have occurred, you may also use the \tr{-fshow-import-specs} option +to see what specialisations GHC would like to have had available. +By then adding these ``desirable'' pragmas to your code, you can +squash most of the overloading from your program. + +There are some new sanity-checking options. Use +\tr{-fsignatures-required} if you want to force all top-level +definitions to have type signatures. Use \tr{-fshadowing-not-ok} +if you want to disallow name shadowing. You can't use the latter on +modules that include circular definitions. + +The \tr{-Rghc-timing} option gives a convenient one-line summary to +GHC's runtime and heap allocation. + +The \tr{-odump} option may be used to save GHC's standard-error output +to a file. (It normally shows up on your screen.) + +You can now use \tr{-H0} and \tr{-K0} to reset the heap and stack +sizes. As these sizes are normally ``maxxed up'' (\tr{-H32m -H16m} +gets you a 32MB heap), you can use this form to decrease the size: +\tr{-H6m -H0 -H250k} gives you a heap of 250KB. + +%************************************************************************ +%* * +\subsection[0-26-io]{New in monadic I/O} +%* * +%************************************************************************ + +GHC~0.26 is still a Haskell~1.2 compiler (and will remain so until +there is a non-DRAFT 1.3 standard). + +We killed the \tr{PreludePrimIO} interface. You can get all the same +functions from \tr{PreludeGlaST}. + +All the \tr{_IVar} and \tr{_MVar} operations are now in the 1.3 +\tr{IO} monad, not the non-standard \tr{PrimIO} monad. You now +get them from \tr{Concurrent}, not from \tr{PreludeGlaST}. + +%************************************************************************ +%* * +\subsection[0-26-new-in-compiler]{New in the compiler proper} +%* * +%************************************************************************ + +The main new things are ``foldr-build'' deforestation (by Andy Gill) +and ever-more-glorious specialisation (by Patrick Sansom). + +And the usual few megabytes of gratuitous changes. + +%************************************************************************ +%* * +\subsection[0-26-new-in-libraries]{In the prelude and libraries} +%* * +%************************************************************************ + +All of the basic state-transformer stuff now comes from +\tr{PreludeGlaST}. The \tr{PreludePrimIO} interface no longer exists. + +The function \tr{foldrPrimIO} went away. The function \tr{forkPrimIO} +sprang to life. + +The what-you-need-for-Concurrent-Haskell interface is \tr{Concurrent}. +The GHC option is \tr{-concurrent}. Please see the User's Guide. +Note that the operations @threadDelay@ and @threadWait@ now come +from \tr{Concurrent}, not \tr{PreludeGlaMisc}. + +I-Vars and M-Vars (synchronising variables) are now +specifically I/O operations, not general state-transformer operations. +They also come from the \tr{Concurrent} interface. + +Renamings: what used to be the \tr{newMVar} operation is now called +\tr{newEmptyMVar}; what was \tr{initMVar} is now \tr{newMVar}. + +The what-you-need-for-Parallel-Haskell interface is \tr{Parallel}. +The GHC option is \tr{-parallel}. At the moment, the \tr{Parallel} +interface just provides \tr{par} and \tr{seq}. But that will change. + +\tr{LibPosix} now provides \tr{runProcess}, our candidate for the +high-level OS-independent operation. + +NEW: The \tr{Regex} (\tr{-syslib ghc}) interface provides direct +access to the GNU regexp (regular expressions on strings) package. +The \tr{MatchPS} interface is higher-level, providing string-matching +functions on \tr{_PackedStrings}. (All by Sigbjorn Finne) + +NEW: The \tr{Readline} interface (also \tr{-syslib ghc}) provides +access to the GNU readline package. Instant command-line editing +for your Haskell programs. (By Darren Moffat) + +NEW: A ``network interface toolkit'' by Darren Moffat. BSD sockets +for Haskell---way cool. + +The \tr{FiniteMap} module has two new functions, \tr{isEmptyFM} and +\tr{elemFM}. + +The \tr{Maybes} module now uses the Haskell~1.3 built-in \tr{Maybe} +type; you should use \tr{-fhaskell-1.3} with this module now. + +The HBC library modules \tr{Maybe}, \tr{Either}, and \tr{Option} are +{\em gone}. Just use \tr{-fhaskell-1.3} and get the types directly +from the Prelude. + +All system-library modules that use the \tr{Maybe} type now require +\tr{-fhaskell-1.3}. For the GHC library, that means \tr{FiniteMap}, +\tr{Maybes}, \tr{Util}, \tr{Set}, \tr{Regex}, and \tr{MatchPS}. For +the HBC library, that means \tr{ListUtil}, \tr{Native}, and +\tr{Parse}. (In some cases, you could avoid the \tr{-fhaskell-1.3} +requirement by doing selective imports.) + +GHC now supports \tr{trace} exactly like HBC: \tr{import Trace} and +do \tr{-syslib hbc}. The built-in no-import-required version +is now called \tr{_trace}. + +Instances for \tr{Shorts} and \tr{Bytes} have been added to the +HBC library module \tr{Word}. + +As part of the GHC system library, we now provide an interface to the +GNU regexp (regular-expression) library; the \tr{Regexp} interface. +A higher-level interface, to do matches on \tr{_PackedString}s comes +from the \tr{MatchPS} interface. + +We no longer provide specialisations of Prelude functions to the +\tr{Float} type; only to \tr{Double}. It saves space, and we want to +discourage the use of single-precision floating-point. + +%************************************************************************ +%* * +\subsection[0-26-new-in-rts]{In the runtime system} +%* * +%************************************************************************ + +GHC now supplies some very simple ``hooks'' to let you change the +failure messages for stack and heap overflow, \tr{error}, and +pattern-matching failure. Please see the User's Guide. + +You can now force garbage collection after every N bytes of allocation +(presumably for stats collection, or something). Use the \tr{-j} RTS +option. + +``Squeezing out'' update frames at garbage-collection time is now {\em +on} by default. (You can turn it off with the \tr{-Z} RTS option, but +I can't think why you would want to.) + +%************************************************************************ +%* * +\subsection[0-26-new-elsewhere]{Other new stuff} +%* * +%************************************************************************ + +The GHC distribution now includes an ``examples'' directory, including +a simple shell (\tr{hsh} and quite a few to do with 1.3 I/O +(\tr{ioNNN}) and \tr{LibPosix} (\tr{poNNN}). All in +\tr{ghc/misc/examples}... diff --git a/ghc/docs/release_notes/Jmakefile b/ghc/docs/release_notes/Jmakefile new file mode 100644 index 0000000000..88109ac206 --- /dev/null +++ b/ghc/docs/release_notes/Jmakefile @@ -0,0 +1,13 @@ +/* there are rules to make this piece of "the book" + * as a standalone document, + * but nothing to "install" it + */ + +LitStuffNeededHere(docs depend) +InfoStuffNeededHere(docs) + +LiterateSuffixRules() +DocProcessingSuffixRules() + +/* no space between the two args! */ +LitDocRootTarget(release,lit) diff --git a/ghc/docs/release_notes/real-soon-now.lit b/ghc/docs/release_notes/real-soon-now.lit new file mode 100644 index 0000000000..7fd5b85b67 --- /dev/null +++ b/ghc/docs/release_notes/real-soon-now.lit @@ -0,0 +1,49 @@ +%************************************************************************ +%* * +%* Stuff for : Real Soon Now * +%* * +%************************************************************************ + +Below is a short list of things we hope to tackle soon. We welcome +prodding, cajoling, large sums of money, offers of holidays in warm +climates... Umm, excuse me, I got carried away.... + +\begin{description} +%------------------------------------------------------------------- +\item[Compilation speed:] +This is still our \#1 priority. (Actually, we {\em have} saved a lot +on compilation time since~0.16; however, we've spent a goodly chunk of +our winnings.) + +%------------------------------------------------------------------- +\item[Revised I/O scheme:] We've {\em finally} figured out the right +way to do this ``state'' stuff; see the Launchbury/Peyton Jones ``Lazy +Functional State Threads'' paper (draft; check +\tr{ghc/docs/abstracts/abstracts93.tex}). + +Simultaneously, the Haskell~1.3 I/O proposal is coming along. We hope +to use the former to do the latter, if you know what I mean. + +%------------------------------------------------------------------- +\item[More with unfoldings:] +And our new simplifier. Both of these new pieces of machinery are +still a bit ``raw.'' (The reason we don't quote performance numbers +is because we haven't collected any yet.) + +%------------------------------------------------------------------- +\item[Specialised instances:] Tedious and boring. + +%------------------------------------------------------------------- +\item[More with ``semi-tagging'':] +(which we haven't done much with yet...) and other code-generator-ish +hacks. [It depends how close we let Simon get to the code.] + +%------------------------------------------------------------------- +\item[More tuning:] +We're {\em generally} happy with the time/space behaviour of Haskell +programs compiled with this system. But there's always work to do. + +We still welcome a copy of any Haskell program for which a competing +compiler generates better code. We want to stamp out these +unfortunate anomalies! +\end{description} diff --git a/ghc/docs/release_notes/release.lit b/ghc/docs/release_notes/release.lit new file mode 100644 index 0000000000..16e4d24062 --- /dev/null +++ b/ghc/docs/release_notes/release.lit @@ -0,0 +1,93 @@ +\begin{onlystandalone} +\documentstyle[11pt,literate]{article} +\begin{document} +\title{Release notes for Glasgow Haskell} +\author{Will Partain (for the AQUA Team)\\ +Department of Computing Science\\ +University of Glasgow\\ +Glasgow, Scotland\\ +G12 8QQ\\ +\\ +Email: glasgow-haskell-\{bugs,request\}\@dcs.glasgow.ac.uk} +\maketitle +\begin{rawlatex} +\tableofcontents +\end{rawlatex} +\clearpage +\end{onlystandalone} + +% NOTE TO MAINTAINERS: the way these notes are organized: +% (1) What's new in the current release +% (2) What's next ("real soon now") +% (3) What was new in previous releases (reverse chronological order) +% (4) anything else +% +% Remember: this isn't the compiler documentation! -- it's just +% pointers to it. Mentioning something in the release notes is not +% the same as documenting it. + +\section[release-0-26]{Release notes for version~0.26---7/95} +\input{0-26-notes.lit} + +%\section[release-RSN]{What we hope to do Real Soon Now} +%\downsection +%\input{real-soon-now.lit} +%\upsection + +\section{Non-release notes for versions~0.24 and 0.25} +Version~0.24 (March 1995) was a tidy-up release; it mostly +fixed some ``threads'' problems (now ``Concurrent Haskell''), +some I/O problems, and some porting problems. + +Version~0.25 was a binary-only dump of a \tr{i386-*-linuxaout} +build, just so people could try it. + +\section[release-0-23]{Release notes for version~0.23---12/94} +\input{0-23-notes.lit} + +\section[release-0-22]{Release notes for version~0.22---7/94} +\input{0-22-notes.lit} + +\section[release-0-19]{Release notes for version~0.19---12/93} +\input{0-19-notes.lit} + +\section[release-0-16]{Release notes for version~0.16---07/93} +\input{0-16-notes.lit} + +\section[release-0-10]{Release notes for version~0.10---12/92} +\input{0-10-notes.lit} + +\section[release-0-09]{Release~0.09---9/92} + +This was an unannounced pseudo-release to a few people. + +\section[release-0-08]{Release notes for version~0.08---7/92} +\input{0-08-notes.lit} + +\section[release-0-07]{Release~0.07} + +This was an unannounced pseudo-release to a few people. + +\section[release-0-06]{Release notes for version~0.06---3/92} +\input{0-06-notes.lit} + +\section[release-0-05]{Release notes for version~0.05---12/91} +\input{0-05-notes.lit} + +\section[releases-0-03-04]{Releases between 0.02 and 0.05} + +There were a couple of private releases to highly zealous people, +mainly our friends at York. There are README files in the +\tr{release_notes/} dir about those, if you are really interested. + +\section[release-0-02]{Release notes for version~0.02---8/91} +\downsection +Nothing about version 0.02, our very first release, is still +interesting :-) +%\input{0-02-notes.lit} +\upsection + +\begin{onlystandalone} +% \printindex +\end{document} +\end{onlystandalone} diff --git a/ghc/docs/simple-monad.lhs b/ghc/docs/simple-monad.lhs new file mode 100644 index 0000000000..82157b34b5 --- /dev/null +++ b/ghc/docs/simple-monad.lhs @@ -0,0 +1,264 @@ +A Simple Country Boy's Guide to Monadic-Style Programming +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Forget the category theory, forget all the fancy talk, forget "monadic +I/O", forget Phil Wadler's papers! Let's just do a little *plumbing* +in the monadic style, in plain-vanilla Haskell. + +You can compile this guide as a Haskell module; I haven't put in +enough code to make it run or do anytning interesting. Excuse me for +a moment, while I get some preliminaries out of the way... +\begin{code} +module Foo where + +infixr 9 `thenFoo`, `thenFoo_` -- ignore me + +data Foo = NullFoo | ConsFoo Int Foo -- assorted types, of little interest +type SwitchChecker = String -> Bool +type EnvA = [(String, Float)] +type NameSupply = Int +\end{code} + +*** MOTIVATION ********* + +If you find that your Haskell functions are starting to carry around a +lot of baggage ..., e.g., +\begin{code} +f :: EnvA -> SwitchChecker -> NameSupply -> Foo -> (Int, NameSupply) + +f env sw_chkr names NullFoo = (0, names) + +f env sw_chkr names (ConsFoo x xs) + = let + (x', names') = f env sw_chkr names xs + in + (x + x', names') +{- + `env' is some kind of environment; + what most people call "lookup tables". + `sw_chkr' is a function which, when presented with a + String, will tell you if that string was present + on the command line. + `names' is some kind of "name supply"; `f' + `f' returns a depleted name supply (2nd component of result). +-} +\end{code} + +...then it may be time to use monadic code to hide some of the mess!! + +GRATUITOUS PLUMBING OF STATE MUST DIE. + + +*** SETTING UP THE MONAD MACHINERY ******* + +First, divide the things to be plumbed into: + + * things that are only passed "downwards" through the function; + in the example above, the `env' and `sw_chkr' are such things; + + * things that are "threaded" through the function; you want the + changed whatsit back from "down below"; `names' is such a thing. + +Now, implement your monad; let's call it `FooM'; think of a `FooM +Wibble' as an *action* that, when performed, produces a `Wibble'. + +\begin{code} +type FooM a = EnvA -- type of lookup-tbl being plumbed + -> SwitchChecker -- type of switch looker-upper... + -> NameSupply -- NameSupply going down... + -> (a, -- result of the `FooM a' action + NameSupply) -- NameSupply that comes back... +\end{code} + +(Note: in reality, it would be good practice to hide all this stuff +behind a clean interface, in another module.) + +Let's write the basic operations on these `FooM a' guys: + +\begin{code} +returnFoo :: a -> FooM a + -- make a `FooM thing' action from a `thing' value + -- [Phil W would call this `unitFoo'] + +thenFoo :: FooM a -> (a -> FooM b) -> FooM b + -- sequence two actions; the second uses the + -- result of the first + -- [Phil W would call this `bindFoo', or semi-colon :-] + +thenFoo_ :: FooM a -> FooM b -> FooM b + -- sequence two actions; don't care about the + -- result of the first + -- [the name is a mnemonic for "... thenFoo \ _ -> ...] +\end{code} + +They're implemented in the obvious way: +\begin{code} +returnFoo thing env sw_chkr ns = (thing, ns) + +thenFoo action1 action2 env sw_chkr ns + = case (action1 env sw_chkr ns) of + (result1, ns1) -> action2 result1 env sw_chkr ns1 + +thenFoo_ action1 action2 env sw_chkr ns + = case (action1 env sw_chkr ns) of + (_{-boring result-}, ns1) -> action2 env sw_chkr ns1 +\end{code} + +All those are "pure plumbing". We need a few "monadic functions" that +do something useful. + +For example, you need to be able to "do a `FooM' action" and get the +answer back (along with the depleted NameSupply); for that, use... +\begin{code} +initFoo :: FooM a -> SwitchChecker -> NameSupply -> (NameSupply, a) + +initFoo action sw_chkr ns + = case (action [] sw_chkr ns) of + (result, new_ns) -> (new_ns, result) + -- gratuitous order-swapping +\end{code} + +You would then have a this-monad-specific set of functions to ``reach +down'' in the plumbing and use the env, switch-checker, etc., that are +being carried around. Some examples might be: +\begin{code} +getNewName :: FooM Int + +getNewName env sw_chkr ns = (ns, ns+1) + +------------ + +ifSwitchSet :: String -> FooM a -> FooM a -> FooM a + +ifSwitchSet sw_to_chk then_ else_ env sw_chkr ns + = (if (sw_chkr sw_to_chk) then then_ else else_) env sw_chkr ns + +------------ + +lookupInEnv :: String -> FooM Float + +lookupInEnv key env sw_chkr ns + = case [ v | (k, v) <- env, k == key ] of + [] -> error "lookupInEnv: no match" + (val:_) -> (val, ns) +\end{code} + +*** USING THE MONAD MACHINERY ******* + +We now have everything needed to write beautiful (!) monadic code. To +remind you of the basic "monadic" functions at our disposal: + +\begin{verbatim} +returnFoo :: a -> FooM a +thenFoo :: FooM a -> (a -> FooM b) -> FooM b +thenFoo_ :: FooM a -> FooM b -> FooM b +initFoo :: FooM a -> SwitchChecker -> NameSupply -> (NameSupply, a) + +getNewName :: FooM Int +ifSwitchSet :: String -> FooM a -> FooM a -> FooM a +lookupInEnv :: String -> FooM Float +\end{verbatim} + +Before going on: there are a few plumbing things that aren't +essential, but tend to be useful. They needn't be written at the +"bare-bones" level; they show the use of `returnFoo' and `thenFoo'. +\begin{code} +mapFoo :: (a -> FooM b) -> [a] -> FooM [b] + +mapFoo f [] = returnFoo [] +mapFoo f (x:xs) + = f x `thenFoo` \ r -> + mapFoo f xs `thenFoo` \ rs -> + returnFoo (r:rs) + +mapAndUnzipFoo :: (a -> FooM (b,c)) -> [a] -> FooM ([b],[c]) + +mapAndUnzipFoo f [] = returnFoo ([],[]) +mapAndUnzipFoo f (x:xs) + = f x `thenFoo` \ (r1, r2) -> + mapAndUnzipFoo f xs `thenFoo` \ (rs1, rs2) -> + returnFoo (r1:rs1, r2:rs2) +\end{code} + +You should read + + f x `thenFoo` \ r -> ... + +as + + "do `f' with argument `x', giving result `r'". + +If you wanted, you could do really horrible things with the C +pre-processor (GHC and HBC let you do this...): +\begin{verbatim} +#define RETN returnFoo +#define BIND {--} +#define _TO_ `thenFoo` \ {--} + +mapFoo f [] = RETN [] +mapFoo f (x:xs) + = BIND (f x) _TO_ r -> + BIND (mapFoo f xs) _TO_ rs -> + RETN (r:rs) +\end{verbatim} + +*** USING THE MONAD MACHINERY, FOR REAL ******* + +We can finally re-write our `f' function in a "monadic style" (except +I'll call it `g'), using the functions above. +\begin{code} +g :: Foo -> FooM Int + -- `g' has the same arguments as `f' (really), but in a different + -- order: just unravel the type synonyms + +g NullFoo = returnFoo 0 + +g (ConsFoo x xs) + = g xs `thenFoo` \ x' -> + returnFoo (x + x') +\end{code} + +LOOK, MOM, NO GRATUITOUS PLUMBING OF STATE! + +OK, `g' shows how much the monadic style tidies up the plumbing, but +it is really boring---it doesn't use any of the functions we defined +earlier. Here's a function that does: +\begin{code} +h :: Int -> FooM Integer + +h x + = getNewName `thenFoo_` -- ignore that one... + getNewName `thenFoo` \ int_name -> + + mapAndUnzipFoo zwonk [int_name ..] + `thenFoo` \ (some_nums, more_nums) -> + + ifSwitchSet "-beat-hbc" ( + returnFoo (toInteger (some_nums !! 6) + 42) + + ) {-else-} ( + lookupInEnv "-ghc-is-cool" `thenFoo` \ ghc_float -> + returnFoo (toInteger (truncate ghc_float)) + ) + where + zwonk :: Int -> FooM (Int, Int) + zwonk i = returnFoo (i, x*i) +\end{code} + +*** CONCLUSION ******* + +Ordinary Haskell programming, but in a "monadic style", is a good way +to control the plumbing of state through your code. + +I have left out lots and lots of Neat Things you can do with monads -- +see the papers for more interesting stuff. But 99% of the monadic +code you're likely to write or see will look like the stuff in here. + +Comments, suggestions, etc., to me, please. + +Will Partain +partain@dcs.glasgow.ac.uk + +% compile with: +% ghc -cpp <other-flags> Foo.lhs +% hbc -M <other-flags> Foo.lhs diff --git a/ghc/docs/users_guide/Jmakefile b/ghc/docs/users_guide/Jmakefile new file mode 100644 index 0000000000..018e0e1b2d --- /dev/null +++ b/ghc/docs/users_guide/Jmakefile @@ -0,0 +1,9 @@ +LitStuffNeededHere(docs depend) +InfoStuffNeededHere(docs) + +LiterateSuffixRules() +DocProcessingSuffixRules() + +/* no space between the args! */ +/*LitDocRootTarget(profiling,lit)*/ +LitDocRootTarget(user,lit) diff --git a/ghc/docs/users_guide/glasgow_exts.lit b/ghc/docs/users_guide/glasgow_exts.lit new file mode 100644 index 0000000000..e480f8c005 --- /dev/null +++ b/ghc/docs/users_guide/glasgow_exts.lit @@ -0,0 +1,722 @@ +%************************************************************************ +%* * +\section[glasgow-exts]{Glasgow extensions to Haskell} +\index{Haskell, Glasgow extensions} +\index{extensions, Glasgow Haskell} +%* * +%************************************************************************ + +As with all known Haskell systems, GHC implements some extensions to +the language. +To use them, you'll need to give +a \tr{-fglasgow-exts}% +\index{-fglasgow-exts option} option. + +Virtually all of the Glasgow extensions serve to give you access to the +underlying facilities with which we implement Haskell. Thus, you can +get at the Raw Iron, if you are willing to write some non-standard +code at a more primitive level. You need not be ``stuck'' on +performance because of the implementation costs of Haskell's +``high-level'' features---you can always code ``under'' them. In an +extreme case, you can write all your time-critical code in C, and then +just glue it together with Haskell! + +Executive summary of our extensions: +\begin{description} +\item[Unboxed types and primitive operations:] You can get right down +to the raw machine types and operations; included in this are +``primitive arrays'' (direct access to Big Wads of Bytes). +Please see \Sectionref{glasgow-unboxed} and following. + +%\item[Synchronising variables---\tr{_IVar}s, \tr{_MVar}s:] +%These are used when reads and writes need to be coordinated, +%e.g., if the readers and writers are different concurrent threads. +%Please see \Sectionref{ivars-mvars}. + +\item[Calling out to C:] Just what it sounds like. We provide {\em +lots} of rope that you can dangle around your neck. +Please see \Sectionref{glasgow-ccalls}. + +\item[``Monadic I/O:''] This stuff will be coming to you For Real +with Haskell~1.3, whenever that is. +Please see \Sectionref{io-1-3} (the ``1.3 I/O'' section). + +\item[``HBC-ish'' extensions:] Extensions implemented because people said, +``HBC does Y. Could you teach GHC to do the same?'' Please see +\Sectionref{glasgow-hbc-exts} for a quick list. +\end{description} + +Before you get too carried away working at the lowest level (e.g., +sloshing \tr{MutableByteArray#}s around your program), you may wish to +check if there are system libraries that provide a ``Haskellised +veneer'' over the features you want. See \Sectionref{syslibs}. + +The definitive guide for many of the low-level facilities in GHC is +the ``state interface document'' (distributed in +\tr{ghc/docs/state-interface.dvi}). We do not repeat its details here. + +%Pieter Hartel led an interesting comparison-of-many-compilers (and +%many languages) in which GHC got to show off its extensions. We did +%very well! For the full details, check out +%\tr{pub/computer-systems/functional/packages/pseudoknot.tar.Z} on \tr{ftp.fwi.uva.nl}. +%Good clean fun! + +%************************************************************************ +%* * +\subsection[glasgow-unboxed]{Unboxed types} +\index{Unboxed types (Glasgow extension)} +%* * +%************************************************************************ + +These types correspond to the ``raw machine'' types you would use in +C: \tr{Int#} (long int), \tr{Double#} (double), +\tr{Addr#} (void *), etc. The {\em primitive +operations} (PrimOps) on these types are what you might expect; e.g., +\tr{(+#)} is addition on \tr{Int#}s, and is the machine-addition that +we all know and love---usually one instruction. + +A numerically-intensive program using unboxed types can go a {\em lot} +faster than its ``standard'' counterpart---we saw a threefold speedup +on one example. + +Please see the very first part of the ``state interface document'' +(distributed in \tr{ghc/docs/state-interface.dvi}) for the details of +unboxed types and the operations on them. + +%************************************************************************ +%* * +\subsection[glasgow-ST-monad]{Primitive state-transformer monad} +\index{state transformers (Glasgow extensions)} +%* * +%************************************************************************ + +This monad underlies our implementation of arrays, mutable and immutable, +and our implementation of I/O, including ``C calls''. + +You probably won't use the monad directly, but you might use all those +other things! + +The ``state interface document'' defines the state-related types in +sections~1.4 and~1.5, and the monad itself in section~2.1. + +%************************************************************************ +%* * +\subsection[glasgow-prim-arrays]{Primitive arrays, mutable and otherwise} +\index{primitive arrays (Glasgow extension)} +\index{arrays, primitive (Glasgow extension)} +%* * +%************************************************************************ + +GHC knows about quite a few flavours of Large Swathes of Bytes. + +First, GHC distinguishes between primitive arrays of (boxed) Haskell +objects (type \tr{Array# obj}) and primitive arrays of bytes (type +\tr{ByteArray#}). + +Second, it distinguishes between... +\begin{description} +\item[Immutable:] +Arrays that do not change (as with ``standard'' Haskell arrays); you +can only read from them. Obviously, they do not need the care and +attention of the state-transformer monad. + +\item[Mutable:] +Arrays that may be changed or ``mutated.'' All the operations on them +live within the state-transformer monad and the updates happen {\em +in-place}. + +\item[``Static'' (in C land):] +A C~routine may pass an \tr{Addr#} pointer back into Haskell land. +There are then primitive operations with which you may merrily grab +values over in C land, by indexing off the ``static'' pointer. + +\item[``Stable'' pointers:] +If, for some reason, you wish to hand a Haskell pointer (i.e., {\em +not} an unboxed value) to a C~routine, you first make the pointer +``stable,'' so that the garbage collector won't forget that it exists. +That is, GHC provides a safe way to pass Haskell pointers to C. + +Please see \Sectionref{glasgow-stablePtrs} for more details. + +\item[``Malloc'' pointers:] +A ``malloc'' pointer is a safe way to pass a C~pointer to Haskell and +have Haskell do the Right Thing when it no longer references the +object. So, for example, C could pass a large bitmap over to Haskell +and say ``please free this memory when you're done with it.'' + +Please see \Sectionref{glasgow-mallocPtrs} for more details. +\end{description} + +See sections~1.4 and~1.6 of the ``state interface document'' for the +details of all these ``primitive array'' types and the operations on +them. + + +%************************************************************************ +%* * +\subsection[glasgow-ccalls]{Calling~C directly from Haskell} +\index{C calls (Glasgow extension)} +\index{_ccall_ (Glasgow extension)} +\index{_casm_ (Glasgow extension)} +%* * +%************************************************************************ + +%Besides using a \tr{-fglasgow-exts} flag, your modules need to include... +%\begin{verbatim} +%import PreludePrimIO +%\end{verbatim} + +SINCE VERSION 0.22: ``Literal-literals'', e.g., \tr{``NULL''}, can now +be any `boxed-primitive' type---they are not automatically taken to be +\tr{_Addr}s. This is cool, except you may sometimes have to put in +a type signature to force the desired type. + +SINCE VERSION 0.19: \tr{ccall} and \tr{casm} have been renamed to +\tr{_ccall_} and \tr{_casm_} and \tr{veryDangerousCcall} and +\tr{veryDangerousCasm} have been removed. It is no longer necessary +(nor legal!) to unbox/rebox the arguments and results to @_ccall_@. +GHC does the unboxing/reboxing for you. + +GOOD ADVICE: Because this stuff is not Entirely Stable as far as names +and things go, you would be well-advised to keep your C-callery +corraled in a few modules, rather than sprinkled all over your code. +It will then be quite easy to update later on. + +WARNING AS OF 0.26: Yes, the \tr{_ccall_} stuff probably {\em will +change}, to something better, of course! We are only at the +musing-about-it stage, however. + +%************************************************************************ +%* * +\subsubsection[ccall-intro]{\tr{_ccall_} and \tr{_casm_}: an introduction} +%* * +%************************************************************************ + +The simplest way to use a simple C function +\begin{verbatim} +double fooC( FILE *in, char c, int i, double d, unsigned int u ) +\end{verbatim} +is to provide a Haskell wrapper +\begin{verbatim} +fooH :: Char -> Int -> Double -> _Word -> PrimIO Double +fooH c i d w = _ccall_ fooC ``stdin'' c i d w +\end{verbatim} +The function @fooH@ will unbox all of its arguments, call the C +function \tr{fooC} and box the corresponding arguments. + +So, if you want to do C-calling, you have to confront the underlying +Glasgow I/O system. It's just your typical monad whatnot. + +%The code in \tr{ghc/lib/glaExts/*.lhs} is not too obtuse. +%That code, plus \tr{lib/prelude/Builtin.hs}, give examples +%of its use. The latter includes the implementations of \tr{error} and +%\tr{trace}. + +One of the annoyances about \tr{_ccall_}s is when the C types don't quite +match the Haskell compiler's ideas. For this, the \tr{_casm_} variant +may be just the ticket (NB: {\em no chance} of such code going through +a native-code generator): +\begin{verbatim} +oldGetEnv name + = _casm_ ``%r = getenv((char *) %0);'' name `thenPrimIO` \ litstring@(A# str#) -> + returnPrimIO ( + if (litstring == ``NULL'') then + Failure (SearchError ("GetEnv:"++name)) + else + Str (unpackCString# str#) + ) +\end{verbatim} + +The first literal-literal argument to a \tr{_casm_} is like a +\tr{printf} format: \tr{%r} is replaced with the ``result,'' +\tr{%0}--\tr{%n-1} are replaced with the 1st--nth arguments. As you +can see above, it is an easy way to do simple C~casting. Everything +said about \tr{_ccall_} goes for \tr{_casm_} as well. + +%************************************************************************ +%* * +\subsubsection[glasgow-foreign-headers]{Using function headers} +\index{C calls---function headers} +%* * +%************************************************************************ + +When generating C (using the \tr{-fvia-C} directive), one can assist +the C compiler in detecting type errors by using the \tr{-#include} +directive to provide \tr{.h} files containing function headers. + +For example, +\begin{verbatim} +typedef unsigned long *StgMallocPtr; +typedef long StgInt; + +extern void initialiseEFS PROTO( (StgInt size) ); +extern StgInt terminateEFS (); +extern StgMallocPtr emptyEFS(); +extern StgMallocPtr updateEFS PROTO( (StgMallocPtr a, StgInt i, StgInt x) ); +extern StgInt lookupEFS PROTO( (StgMallocPtr a, StgInt i) ); +\end{verbatim} + +You can find appropriate definitions for \tr{StgInt}, +\tr{StgMallocPtr}, etc using \tr{gcc} on your architecture by +consulting \tr{ghc/includes/StgTypes.lh}. The following table +summarises the relationship between Haskell types and C types. + +\begin{tabular}{ll} +C type name & Haskell Type \\ \hline +%----- & --------------- +\tr{StgChar} & \tr{Char#}\\ +\tr{StgInt} & \tr{Int#}\\ +\tr{StgWord} & \tr{Word#}\\ +\tr{StgAddr} & \tr{Addr#}\\ +\tr{StgFloat} & \tr{Float#}\\ +\tr{StgDouble} & \tr{Double#}\\ + +\tr{StgArray} & \tr{Array#}\\ +\tr{StgByteArray} & \tr{ByteArray#}\\ +\tr{StgArray} & \tr{MutableArray#}\\ +\tr{StgByteArray} & \tr{MutableByteArray#}\\ + +\tr{StgStablePtr} & \tr{StablePtr#}\\ +\tr{StgMallocPtr} & \tr{MallocPtr#} +\end{tabular} + +Note that this approach is only {\em essential\/} for returning +\tr{float}s (or if \tr{sizeof(int) != sizeof(int *)} on your +architecture) but is a Good Thing for anyone who cares about writing +solid code. You're crazy not to do it. + +%************************************************************************ +%* * +\subsubsection[glasgow-stablePtrs]{Subverting automatic unboxing with ``stable pointers''} +\index{stable pointers (Glasgow extension)} +%* * +%************************************************************************ + +The arguments of a \tr{_ccall_} are automatically unboxed before the +call. There are two reasons why this is usually the Right Thing to do: +\begin{itemize} +\item +C is a strict language: it would be excessively tedious to pass +unevaluated arguments and require the C programmer to force their +evaluation before using them. + +\item Boxed values are stored on the Haskell heap and may be moved +within the heap if a garbage collection occurs --- that is, pointers +to boxed objects are not {\em stable\/}. +\end{itemize} + +It is possible to subvert the unboxing process by creating a ``stable +pointer'' to a value and passing the stable pointer instead. (To use +stable pointers, you must \tr{import PreludeGlaMisc}.) For example, to +pass/return an integer lazily to C functions \tr{storeC} and +\tr{fetchC}, one might write: +\begin{verbatim} +storeH :: Int -> PrimIO () +storeH x = makeStablePtr x `thenPrimIO` \ stable_x -> + _ccall_ storeC stable_x + +fetchH :: PrimIO Int +fetchH x = _ccall_ fetchC `thenPrimIO` \ stable_x -> + deRefStablePtr stable_x `thenPrimIO` \ x -> + freeStablePtr stable_x `seqPrimIO` + returnPrimIO x +\end{verbatim} + +The garbage collector will refrain from throwing a stable pointer away +until you explicitly call one of the following from C or Haskell. +\begin{verbatim} +void freeStablePointer( StgStablePtr stablePtrToToss ) +freeStablePtr :: _StablePtr a -> PrimIO () +\end{verbatim} + +As with the use of \tr{free} in C programs, GREAT CARE SHOULD BE +EXERCISED to ensure these functions are called at the right time: too +early and you get dangling references (and, if you're lucky, an error +message from the runtime system); too late and you get space leaks. + +%Doesn't work in ghc-0.23 - best to just keep quiet about them. +% +%And to force evaluation of the argument within \tr{fooC}, one would +%call one of the following C functions (according to type of argument). +% +%\begin{verbatim} +%void performIO ( StgStablePtr stableIndex /* _StablePtr s (PrimIO ()) */ ); +%StgInt enterInt ( StgStablePtr stableIndex /* _StablePtr s Int */ ); +%StgFloat enterFloat ( StgStablePtr stableIndex /* _StablePtr s Float */ ); +%\end{verbatim} +% +%ToDo ADR: test these functions! +% +%Note Bene: \tr{_ccall_GC_} must be used if any of these functions are used. + + +%************************************************************************ +%* * +\subsubsection[glasgow-mallocPtrs]{Pointing outside the Haskell heap} +\index{malloc pointers (Glasgow extension)} +%* * +%************************************************************************ + +There are two types that \tr{ghc} programs can use to reference +(heap-allocated) objects outside the Haskell world: \tr{_Addr} and +\tr{_MallocPtr}. (You must import \tr{PreludeGlaMisc} to use +\tr{_MallocPtr}.) + +If you use \tr{_Addr}, it is up to you to the programmer to arrange +allocation and deallocation of the objects. + +If you use \tr{_MallocPtr}, \tr{ghc}'s garbage collector will +call the user-supplied C function +\begin{verbatim} +void FreeMallocPtr( StgMallocPtr garbageMallocPtr ) +\end{verbatim} +when the Haskell world can no longer access the object. Since +\tr{_MallocPtr}s only get released when a garbage collection occurs, +we provide ways of triggering a garbage collection from within C and +from within Haskell. +\begin{verbatim} +void StgPerformGarbageCollection() +performGC :: PrimIO () +\end{verbatim} + +%************************************************************************ +%* * +\subsubsection[glasgow-avoiding-monads]{Avoiding monads} +\index{C calls to `pure C'} +\index{unsafePerformPrimIO (PreludeGlaST)} +%* * +%************************************************************************ + +The \tr{_ccall_} construct is part of the \tr{PrimIO} monad because 9 +out of 10 uses will be to call imperative functions with side effects +such as \tr{printf}. Use of the monad ensures that these operations +happen in a predictable order in spite of laziness and compiler +optimisations. + +There are three situations where one might like to use +@unsafePerformPrimIO@ to avoid the monad: +\begin{itemize} +\item +Calling a function with no side-effects: +\begin{verbatim} +atan2d :: Double -> Double -> Double +atan2d y x = unsafePerformPrimIO (_ccall_ atan2d y x) + +sincosd :: Double -> (Double, Double) +sincosd x = unsafePerformPrimIO ( + newDoubleArray (0, 1) `thenPrimIO` \ da -> + _casm_ ``sincosd( %0, &((double *)%1[0]), &((double *)%1[1]) );'' x da + `seqPrimIO` + readDoubleArray da 0 `thenPrimIO` \ s -> + readDoubleArray da 1 `thenPrimIO` \ c -> + returnPrimIO (s, c) + ) +\end{verbatim} + +\item Calling a set of functions which have side-effects but which can +be used in a purely functional manner. + +For example, an imperative implementation of a purely functional +lookup-table might be accessed using the following functions. + +\begin{verbatim} +empty :: EFS x +update :: EFS x -> Int -> x -> EFS x +lookup :: EFS a -> Int -> a + +empty = unsafePerformPrimIO (_ccall_ emptyEFS) + +update a i x = unsafePerformPrimIO ( + makeStablePtr x `thenPrimIO` \ stable_x -> + _ccall_ updateEFS a i stable_x + ) + +lookup a i = unsafePerformPrimIO ( + _ccall_ lookupEFS a i `thenPrimIO` \ stable_x -> + deRefStablePtr stable_x + ) +\end{verbatim} + +You will almost always want to use \tr{_MallocPtr}s with this. + +\item Calling a side-effecting function even though the results will +be unpredictable. For example the \tr{trace} function is defined by: + +\begin{verbatim} +trace :: String -> a -> a +trace string expr = unsafePerformPrimIO ( + appendChan# ``stderr'' "Trace On:\n" `seqPrimIO` + appendChan# ``stderr'' string `seqPrimIO` + appendChan# ``stderr'' "\nTrace Off.\n" `seqPrimIO` + returnPrimIO expr ) +\end{verbatim} + +(This kind of use is not highly recommended --- it is only really +useful in debugging code.) + +\end{itemize} + +%************************************************************************ +%* * +\subsubsection[ccall-gotchas]{C-calling ``gotchas'' checklist} +\index{C call dangers} +%* * +%************************************************************************ + +And some advice, too. + +\begin{itemize} +\item +\tr{_ccall_} is part of the \tr{PrimIO} monad --- not the 1.3 \tr{IO} Monad. +Use the function +\begin{verbatim} +primIOToIO :: PrimIO a -> IO a +\end{verbatim} +to promote a \tr{_ccall_} to the \tr{IO} monad. + +\item +For modules that use \tr{_ccall_}s, etc., compile with \tr{-fvia-C}.\index{-fvia-C option} +You don't have to, but you should. + +Also, use the \tr{-#include "prototypes.h"} flag (hack) to inform the +C compiler of the fully-prototyped types of all the C functions you +call. (\Sectionref{glasgow-foreign-headers} says more about this...) + +This scheme is the {\em only} way that you will get {\em any} +typechecking of your \tr{_ccall_}s. (It shouldn't be that way, +but...) + +\item +Try to avoid \tr{_ccall_}s to C~functions that take \tr{float} +arguments or return \tr{float} results. Reason: if you do, you will +become entangled in (ANSI?) C's rules for when arguments/results are +promoted to \tr{doubles}. It's a nightmare and just not worth it. +Use \tr{doubles} if possible. + +If you do use \tr{floats}, check and re-check that the right thing is +happening. Perhaps compile with \tr{-keep-hc-file-too} and look at +the intermediate C (\tr{.hc} file). + +\item +The compiler uses two non-standard type-classes when +type-checking the arguments and results of \tr{_ccall_}: the arguments +(respectively result) of \tr{_ccall_} must be instances of the class +\tr{_CCallable} (respectively \tr{_CReturnable}. (Neither class +defines any methods --- their only function is to keep the +type-checker happy.) + +The type checker must be able to figure out just which of the +C-callable/returnable types is being used. If it can't, you have to +add type signatures. For example, +\begin{verbatim} +f x = _ccall_ foo x +\end{verbatim} +is not good enough, because the compiler can't work out what type @x@ is, nor +what type the @_ccall_@ returns. You have to write, say: +\begin{verbatim} +f :: Int -> PrimIO Double +f x = _ccall_ foo x +\end{verbatim} + +This table summarises the standard instances of these classes. + +% ToDo: check this table against implementation! + +\begin{tabular}{llll} +Type &CCallable&CReturnable & Which is probably... \\ \hline +%------ ---------- ------------ ------------- +\tr{Char} & Yes & Yes & \tr{unsigned char} \\ +\tr{Int} & Yes & Yes & \tr{long int} \\ +\tr{_Word} & Yes & Yes & \tr{unsigned long int} \\ +\tr{_Addr} & Yes & Yes & \tr{char *} \\ +\tr{Float} & Yes & Yes & \tr{float} \\ +\tr{Double} & Yes & Yes & \tr{double} \\ +\tr{()} & No & Yes & \tr{void} \\ +\tr{[Char]} & Yes & No & \tr{char *} (null-terminated) \\ + +\tr{Array} & Yes & No & \tr{unsigned long *}\\ +\tr{_ByteArray} & Yes & No & \tr{unsigned long *}\\ +\tr{_MutableArray} & Yes & No & \tr{unsigned long *}\\ +\tr{_MutableByteArray} & Yes & No & \tr{unsigned long *}\\ + +\tr{_State} & Yes & Yes & nothing!\\ + +\tr{_StablePtr} & Yes & Yes & \tr{unsigned long *}\\ +\tr{_MallocPtr} & Yes & Yes & see later\\ +\end{tabular} + +The brave and careful programmer can add their own instances of these +classes for the following types: +\begin{itemize} +\item +A {\em boxed-primitive} type may be made an instance of both +\tr{_CCallable} and \tr{_CReturnable}. + +A boxed primitive type is any data type with a +single unary constructor with a single primitive argument. For +example, the following are all boxed primitive types: + +\begin{verbatim} +Int +Double +data XDisplay = XDisplay Addr# +data EFS a = EFS# MallocPtr# +\end{verbatim} + +\begin{verbatim} +instance _CCallable (EFS a) +instance _CReturnable (EFS a) +\end{verbatim} + +\item Any datatype with a single nullary constructor may be made an +instance of \tr{_CReturnable}. For example: + +\begin{verbatim} +data MyVoid = MyVoid +instance _CReturnable MyVoid +\end{verbatim} + +\item As at version 0.26, \tr{String} (i.e., \tr{[Char]}) is still +not a \tr{_CReturnable} type. + +Also, the now-builtin type \tr{_PackedString} is neither +\tr{_CCallable} nor \tr{_CReturnable}. (But there are functions in +the PackedString interface to let you get at the necessary bits...) +\end{itemize} + +\item +The code-generator will complain if you attempt to use \tr{%r} +in a \tr{_casm_} whose result type is \tr{PrimIO ()}; or if you don't +use \tr{%r} {\em precisely\/} once for any other result type. These +messages are supposed to be helpful and catch bugs---please tell us +if they wreck your life. + +\item +If you call out to C code which may trigger the Haskell garbage +collector (examples of this later...), then you must use the +\tr{_ccall_GC_} or \tr{_casm_GC_} variant of C-calls. (This does not +work with the native code generator - use \tr{\fvia-C}.) This stuff is +hairy with a capital H! +\end{itemize} + +%************************************************************************ +%* * +%\subsubsection[ccall-good-practice]{C-calling ``good practice'' checklist} +%* * +%************************************************************************ + +%************************************************************************ +%* * +\subsection[glasgow-hbc-exts]{``HBC-ish'' extensions implemented by GHC} +\index{HBC-like Glasgow extensions} +\index{extensions, HBC-like} +%* * +%************************************************************************ + +\begin{description} +%------------------------------------------------------------------- +\item[@fromInt@ method in class @Num@:] +It's there. Converts from an \tr{Int} to the type. + +%------------------------------------------------------------------- +\item[@toInt@ method in class @Integral@:] +Converts from type type to an \tr{Int}. + +%------------------------------------------------------------------- +\item[Overlapping instance declarations:] +\index{overlapping instances} +\index{instances, overlapping} + +In \tr{instance <context> => Class (T x1 ... xn)}, the \tr{xi}s can be +{\em types}, rather than just {\em type variables}. + +Thus, you can have an instance \tr{instance Foo [Char]}, as well as +the more general \tr{instance Foo [a]}; the former will be used in +preference to the latter, where applicable. + +As Lennart says, ``This is a dubious feature and should not be used +carelessly.'' + +See also: \tr{SPECIALIZE instance} pragmas, in \Sectionref{faster}. + +%------------------------------------------------------------------- +\item[Signal-handling I/O request:] +\index{signal handling (extension)} +\index{SigAction I/O request} +The Haskell-1.2 I/O request \tr{SigAction n act} installs a signal handler for signal +\tr{n :: Int}. The number is the usual UNIX signal number. The action +is of this type: +\begin{verbatim} +data SigAct + = SAIgnore + | SADefault + | SACatch Dialogue +\end{verbatim} + +The corresponding continuation-style I/O function is the unsurprising: +\begin{verbatim} +sigAction :: Int -> SigAct -> FailCont -> SuccCont -> Dialogue +\end{verbatim} + +When a signal handler is installed with \tr{SACatch}, receipt of the +signal causes the current top-level computation to be abandoned, and +the specified dialogue to be executed instead. The abandoned +computation may leave some partially evaluated expressions in a +non-resumable state. If you believe that your top-level computation +and your signal handling dialogue may share subexpressions, you should +execute your program with the \tr{-N} RTS option, to prevent +black-holing. + +The \tr{-N} option is not available with concurrent/parallel programs, +so great care should be taken to avoid shared subexpressions between +the top-level computation and any signal handlers when using threads. + +%------------------------------------------------------------------- +%\item[Simple time-out mechanism, in ``monadic I/O'':] +%\index{time-outs (extension)} +% +%This function is available: +%\begin{verbatim} +%timeoutIO :: Int -> IO Void -> IO (IO Void) +%\end{verbatim} +% +%Wait that many seconds, then abandon the current computation and +%perform the given I/O operation (second argument). Uses the +%signal-handling, so it returns the previous signal-handler (in case +%you want to re-install it). As above, you may need to execute your +%program with the RTS flag \tr{-N}, to prevent black-holing. +% +\end{description} + +%************************************************************************ +%* * +%\subsection[glasgow-compiler-namespace]{Fiddlings the compiler's built-in namespaces} +%* * +%************************************************************************ + +%This is really only used for compiling the prelude. It's turgid and +%will probably change. + +% \begin{description} +% \item[\tr{-no-implicit-prelude}:] +% \index{-no-implicit-prelude option} +% +% ???? (Tells the parser not to read \tr{Prelude.hi}). +% +% \item[\tr{-fhide-builtin-names}:] +% \index{-fhide-builtin-names option} +% This hides {\em all} Prelude names built-in to the compiler. +% +% \item[\tr{-fmin-builtin-names}:] +% \index{-fmin-builtin-names option} +% This hides all but a few of the Prelude names that are built-in to the +% compiler. @:@ (cons) is an example of one that would remain visible. +% +% \item[\tr{-fhide-builtin-instances}:] +% \index{-fhide-builtin-instances option} +% This suppresses the compiler's own ideas about what instances already +% exist (e.g., \tr{instance Eq Int}). +% +% This flag is used when actually compiling the various instance +% declarations in the Prelude. +% \end{description} diff --git a/ghc/docs/users_guide/gone_wrong.lit b/ghc/docs/users_guide/gone_wrong.lit new file mode 100644 index 0000000000..4403d203f9 --- /dev/null +++ b/ghc/docs/users_guide/gone_wrong.lit @@ -0,0 +1,332 @@ +%************************************************************************ +%* * +\section[wrong]{What to do when something goes wrong} +\index{problems} +%* * +%************************************************************************ + +If you still have a problem after consulting this section, then you +may have found a {\em bug}---please report it! See +\Sectionref{bug-reports} for a list of things we'd like to know about +your bug. If in doubt, send a report---we love mail from irate users :-! + +(\Sectionref{vs-Haskell-defn}, which describes Glasgow Haskell's +shortcomings vs.~the Haskell language definition, may also be of +interest.) + +%************************************************************************ +%* * +\subsection[wrong-compiler]{When the compiler ``does the wrong thing''} +\index{compiler problems} +\index{problems with the compiler} +%* * +%************************************************************************ + +\begin{description} +%------------------------------------------------------------------- +\item[``Help! The compiler crashed (or `panic'd)!''] +These events are {\em always} bugs in the GHC system---please report +them. + +%Known compiler ``panics'': +%\begin{description} +%\item[From SPARC native-code generator:] These tend to say something +%like ``unknown PrimOp;'' you can avoid it by compiling that module +%with \tr{-fvia-C}.\index{-fvia-C option} +%\end{description} + +%------------------------------------------------------------------- +\item[``The compiler ran out of heap (or stack) when compiling itself!''] +It happens. We try to supply reasonable \tr{-H<n>} flags for +\tr{ghc/compiler/} and \tr{ghc/lib/}, but GHC's memory consumption +can vary by platform (e.g., on a 64-bit machine). + +Just say \tr{make all EXTRA_HC_OPTS=-H<a reasonable number>} and see +how you get along. + +%------------------------------------------------------------------- +\item[``The compiler died with a pattern-matching error.''] +This is a bug just as surely as a ``panic.'' Please report it. + +%------------------------------------------------------------------- +\item[``Some confusion about a value specialised to a type...'' Huh???] +(A deeply obscure and unfriendly error message.) + +This message crops up when the typechecker is sees a reference in an +interface pragma to a specialisation of an overloaded value +(function); for example, \tr{elem} specialised for type \tr{[Char]} +(\tr{String}). The problem is: it doesn't {\em know} that such a +specialisation exists! + +The cause of this problem is (please report any other cases...): The +compiler has imported pragmatic info for the value in question from +more than one interface, and the multiple interfaces did not agree +{\em exactly} about the value's pragmatic info. Since the compiler +doesn't know whom to believe, it believes none of them. + +The cure is to re-compile the modules that {\em re-export} the +offending value (after possibly re-compiling its defining module). +Now the pragmatic info should be exactly the same in every case, and +things should be fine. + +%------------------------------------------------------------------- +\item[``Can't see the data constructors for a ccall/casm'' Huh?] +GHC ``unboxes'' C-call arguments and ``reboxes'' C-call results for you. +To do this, it {\\em has} to be able to see the types fully; +abstract types won't do! + +Thus, if you say \tr{data Foo = Foo Int#} +(a cool ``boxed primitive'' type), but then make it abstract +(only \tr{data Foo} appears in the interface), then GHC can't figure +out what to do with \tr{Foo} arguments/results to C-calls. + +Solutions: either make the type unabstract, or compile with \tr{-O}. +With the latter, the constructor info will be passed along in +the interface pragmas. + +%------------------------------------------------------------------- +\item[``This is a terrible error message.''] +If you think that GHC could have produced a better error message, +please report it as a bug. + +%------------------------------------------------------------------- +\item[``What about these `trace' messages from GHC?''] +Almost surely not a problem. About some specific cases... +\begin{description} +\item[Simplifier still going after N iterations:] +Sad, but harmless. You can change the number with a +\tr{-fmax-simplifier-iterations<N>}\index{-fmax-simplifier-iterations<N> option} option (no space); +and you can see what actions took place in each iteration by +turning on the \tr{-fshow-simplifier-progress} +\index{-fshow-simplifier-progress option} option. + +If the simplifier definitely seems to be ``looping,'' please report +it. +\end{description} + +%------------------------------------------------------------------- +\item[``What about this warning from the C compiler?''] + +For example: ``...warning: `Foo' declared `static' but never defined.'' +Unsightly, but not a problem. + +%------------------------------------------------------------------- +\item[Sensitivity to \tr{.hi} interface files:] + +GHC is very sensitive about interface files. For example, if it picks +up a non-standard \tr{Prelude.hi} file, pretty terrible things will +happen. If you turn on +\tr{-fno-implicit-prelude}\index{-fno-implicit-prelude option}, the +compiler will almost surely die, unless you know what you are doing. + +Furthermore, as sketched below, you may have big problems +running programs compiled using unstable interfaces. + +%------------------------------------------------------------------- +\item[``I think GHC is producing incorrect code'':] + +Unlikely :-) A useful be-more-paranoid option to give to GHC is +\tr{-dcore-lint}\index{-dcore-lint option}; this causes a ``lint'' pass to +check for errors (notably type errors) after each Core-to-Core +transformation pass. We run with \tr{-dcore-lint} on all the time; it +costs about 5\% in compile time. (Or maybe 25\%; who knows?) + +%------------------------------------------------------------------- +%\item[``Can I use HBC-produced \tr{.hi} interface files?''] +%Yes, though you should keep compiling until you have a stable set of +%GHC-produced ones. + +%------------------------------------------------------------------- +\item[``Why did I get a link error?''] + +If the linker complains about not finding \tr{_<something>_fast}, then +your interface files haven't settled---keep on compiling! (In +particular, this error means that arity information, which you can see +in any \tr{.hi} file, has changed.) + +%If the linker complains about not finding \tr{SpA}, \tr{SuA}, and +%other such things, then you've tried to link ``unregisterised'' object +%code (produced with \tr{-O0}) with the normal registerised stuff. + +%If you get undefined symbols that look anything like (for example) +%\tr{J3C_Interact$__writeln}, \tr{C_Prelude$__$2B$2B}, +%\tr{VC_Prelude$__map}, etc., then you are trying to link HBC-produced +%object files with GHC. + +%------------------------------------------------------------------- +\item[``What's a `consistency error'?''] +(These are reported just after linking your program.) + +You tried to link incompatible object files, e.g., normal ones +(registerised, Appel garbage-collector) with profiling ones (two-space +collector). Or those compiled by a previous version of GHC +with an incompatible newer version. + +If you run \tr{nm -o *.o | egrep 't (cc|hsc)\.'} (or, on +unregisterised files: \tr{what *.o}), you'll see all the consistency +tags/strings in your object files. They must all be the same! +(ToDo: tell you what they mean...) + +%------------------------------------------------------------------- +\item[``Is this line number right?''] +On this score, GHC usually does pretty well, especially +if you ``allow'' it to be off by one or two. In the case of an +instance or class declaration, the line number +may only point you to the declaration, not to a specific method. + +Please report line-number errors that you find particularly unhelpful. +\end{description} + +%************************************************************************ +%* * +\subsection[wrong-compilee]{When your program ``does the wrong thing''} +\index{problems running your program} +%* * +%************************************************************************ + +(For advice about overly slow or memory-hungry Haskell programs, +please see \sectionref{sooner-faster-quicker}). + +\begin{description} +%----------------------------------------------------------------------- +\item[``Help! My program crashed!''] +(e.g., a `segmentation fault' or `core dumped') + +If your program has no @_ccall_@s/@_casm_@s in it, then a crash is always +a BUG in the GHC system, except in one case: If your program is made +of several modules, each module must have been compiled with a stable +group of interface (\tr{.hi}) files. + +For example, if an interface is lying about the type of an imported +value then GHC may well generate duff code for the importing module. +{\em This applies to pragmas inside interfaces too!} If the pragma is +lying (e.g., about the ``arity'' of a value), then duff code may result. +Furthermore, arities may change even if types do not. + +In short, if you compile a module and its interface changes, then all +the modules that import that interface {\em must} be re-compiled. + +A useful option to alert you when interfaces change is +\tr{-hi-diffs}\index{-hi-diffs option}. It will run \tr{diff} on the +changed interface file, before and after, when applicable. + +If you are using \tr{make}, a useful tool to make sure that every +module {\em is} up-to-date with respect to its imported interfaces is +\tr{mkdependHS} (which comes with GHC). Please see +\sectionref{mkdependHS}. + +If you are down to your last-compile-before-a-bug-report, we +would recommend that you add a \tr{-dcore-lint} option (for +extra checking) to your compilation options. + +So, before you report a bug because of a core dump, you should probably: +\begin{verbatim} +% rm *.o # scrub your object files +% make my_prog # re-make your program; use -hi-diffs to highlight changes +% ./my_prog ... # retry... +\end{verbatim} + +Of course, if you have @_ccall_@s/@_casm_@s in your program then all bets +are off, because you can trash the heap, the stack, or whatever. + +If you are interested in hard-core debugging of a crashing +GHC-compiled program, please see \sectionref{hard-core-debug}. + +% (If you have an ``unregisterised'' arity-checking +% (\tr{-O0 -darity-checks}) around [as we sometimes do at Glasgow], then you +% might recompile with \tr{-darity-checks}\index{-darity-checks option}, +% which will definitely detect arity-compatibility errors.) + +%------------------------------------------------------------------- +\item[``My program entered an `absent' argument.''] +This is definitely caused by a bug in GHC. Please report it. + +%----------------------------------------------------------------------- +\item[``What's with this `arithmetic (or `floating') exception' ''?] + +@Int@, @Float@, and @Double@ arithmetic is {\em unchecked}. Overflows +and underflows are {\em silent}. Divide-by-zero {\em may} cause an +untrapped exception (please report it if it does). I suppose other +arithmetic uncheckiness might cause an exception, too... +\end{description} + +%************************************************************************ +%* * +\subsection[bug-reports]{How to report a bug in the GHC system} +\index{bug reports} +%* * +%************************************************************************ + +Glasgow Haskell is a changing system so there are sure to be bugs in +it. Please report them to +\tr{glasgow-haskell-bugs@dcs.glasgow.ac.uk}! (However, please check +the earlier part of this section to be sure it's not a known +not-really-a problem.) + +The name of the bug-reporting game is: facts, facts, facts. +Don't omit them because ``Oh, they won't be interested...'' +\begin{enumerate} +\item +What kind of machine are you running on, and exactly what version of the +operating system are you using? (\tr{cat /etc/motd} often shows the desired +information.) + +\item +What version of GCC are you using? \tr{gcc -v} will tell you. + +\item +Run the sequence of compiles/runs that caused the offending behaviour, +capturing all the input/output in a ``script'' (a UNIX command) or in +an Emacs shell window. We'd prefer to see the whole thing. + +\item +Be sure any Haskell compilations are run with a \tr{-v} (verbose) +flag, so we can see exactly what was run, what versions of things you +have, etc. + +\item +What is the program behaviour that is wrong, in your opinion? + +\item +If practical, please send enough source files/interface files for us +to duplicate the problem. + +\item +If you are a Hero and track down the problem in the compilation-system +sources, please send us {\em whole files} (by e-mail or FTP) that we +can compare against some base release. +\end{enumerate} + +%************************************************************************ +%* * +\subsection[hard-core-debug]{Hard-core debugging of GHC-compiled programs} +\index{debugging, hard-core} +%* * +%************************************************************************ + +If your program is crashing, you should almost surely file a bug +report, as outlined in previous sections. + +This section suggests ways to Make Further Progress Anyway. + +The first thing to establish is: Is it a garbage-collection (GC) bug? +Try your program with a very large heap and a \tr{-Sstderr} RTS +flag. +\begin{itemize} +\item +If it crashes {\em without} garbage-collecting, then it is +definitely {\em not} a GC bug. +\item +If you can make it crash with one heap size but not with another, then +it {\em probably is} a GC bug. +\item +If it crashes with the normal +collector, but not when you force two-space collection (\tr{-F2s} +runtime flag), then it {\em probably is} a GC bug. +\end{itemize} + +If it {\em is} a GC bug, you may be able to avoid it by using a +particular heap size or by using a \tr{-F2s} runtime flag. (But don't +forget to report the bug!!!) + +ToDo: more here? diff --git a/ghc/docs/users_guide/how_to_run.lit b/ghc/docs/users_guide/how_to_run.lit new file mode 100644 index 0000000000..79c7ab9fff --- /dev/null +++ b/ghc/docs/users_guide/how_to_run.lit @@ -0,0 +1,1139 @@ +\section[invoking-GHC]{Invoking GHC: Command-line options} +\index{command-line options} +\index{options, GHC command-line} + +Command-line arguments are either options or file names. + +Command-line options begin with \tr{-}. They may {\em not} be +grouped: \tr{-vO} is different from \tr{-v -O}. +Options need not precede filenames: e.g., \tr{ghc *.o -o foo}. +All options are processed +and then apply to all files; you cannot, for example, +invoke \tr{ghc -c -O1 Foo.hs -O2 Bar.hs} to apply different +optimisation levels to the files \tr{Foo.hs} and \tr{Bar.hs}. For +conflicting options, e.g., \tr{-c -S}, we reserve the right to do +anything we want. (Usually, the last one applies.) + +Options related to profiling, Glasgow extensions to Haskell (e.g., +unboxed values), Concurrent and Parallel Haskell are +described in \sectionref{profiling}, \sectionref{glasgow-exts}, and +\sectionref{concurrent-and-parallel}, respectively. + +%************************************************************************ +%* * +\subsection[file-suffixes]{Meaningful file suffixes} +\index{suffixes, file} +\index{file suffixes for GHC} +%* * +%************************************************************************ + +File names with ``meaningful'' suffixes (e.g., \tr{.lhs} or \tr{.o}) +cause the ``right thing'' to happen to those files. + +\begin{description} +\item[\tr{.lhs}:] +\index{lhs suffix@.lhs suffix} +A ``literate Haskell'' module. + +\item[\tr{.hs}:] +A not-so-literate Haskell module. + +\item[\tr{.hi}:] +A Haskell interface file, probably compiler-generated. + +\item[\tr{.hc}:] +Intermediate C file produced by the Haskell compiler. + +\item[\tr{.c}:] +A C~file not produced by the Haskell compiler. + +% \item[\tr{.i}:] +% C code after it has be preprocessed by the C compiler (using the +% \tr{-E} flag). + +\item[\tr{.s}:] +An assembly-language source file, usually +produced by the compiler. + +\item[\tr{.o}:] +An object file, produced by an assembler. +\end{description} + +Files with other suffixes (or without suffixes) are passed straight +to the linker. + +%************************************************************************ +%* * +\subsection[options-help]{Help and verbosity options} +\index{help options (GHC)} +\index{verbose option (GHC)} +%* * +%************************************************************************ + +A good option to start with is the \tr{-help} (or \tr{-?}) option. +\index{-help option} +\index{-? option} +GHC spews a long message to standard output and then exits. + +The \tr{-v}\index{-v option} option makes GHC {\em verbose}: it +reports its version number and shows (on stderr) exactly how it invokes each +phase of the compilation system. Moreover, it passes +the \tr{-v} flag to most phases; each reports +its version number (and possibly some other information). + +Please, oh please, use the \tr{-v} option when reporting bugs! +Knowing that you ran the right bits in the right order is always the +first thing we want to verify. + +%************************************************************************ +%* * +\subsection[options-order]{Running the right phases in the right order} +\index{order of passes in GHC} +\index{pass ordering in GHC} +%* * +%************************************************************************ + +The basic task of the \tr{ghc} driver is to run each input file +through the right phases (parsing, linking, etc.). + +The first phase to run is determined by the input-file suffix, and the +last phase is determined by a flag. If no relevant flag is present, +then go all the way through linking. This table summarises: + +\begin{tabular}{llll} +phase of the & suffix saying & flag saying & (suffix of) \\ +compilation system & ``start here''& ``stop after''& output file \\ \hline + +literate pre-processor & .lhs & - & - \\ +C pre-processor (opt.) & - & - & - \\ +Haskell parser & .hs & - & - \\ +Haskell compiler & - & -C, -S & .hc, .s \\ +C compiler (opt.) & .hc or .c & -S & .s \\ +assembler & .s & -c & .o \\ +linker & other & - & a.out \\ +\end{tabular} +\index{-C option} +\index{-S option} +\index{-c option} + +Thus, a common invocation would be: \tr{ghc -c Foo.hs} + +Note: What the Haskell compiler proper produces depends on whether a +native-code generator is used (producing assembly language) or not +(producing C). + +%The suffix information may be overridden with a \tr{-lang <suf>} +%\index{-lang <suf> option} option. This says: process all inputs +%files as if they had suffix \pl{<suf>}. [NOT IMPLEMENTED YET] + +The option \tr{-cpp}\index{-cpp option} must be given for the C +pre-processor phase to be run. + +The option \tr{-E}\index{-E option} runs just the C-preprocessor part +of the C-compiling phase, sending the result to stdout [I think]. (For +debugging, usually.) + +%************************************************************************ +%* * +\subsection[options-optimise]{Optimisation (code improvement)} +\index{optimisation (GHC)} +\index{improvement, code (GHC)} +%* * +%************************************************************************ + +The \tr{-O*} options specify convenient ``packages'' of optimisation +flags; the \tr{-f*} options described later on specify {\em individual} +optimisations to be turned on/off; the \tr{-m*} options specify {\em +machine-specific} optimisations to be turned on/off. + +%---------------------------------------------------------------------- +\subsubsection[optimise-pkgs]{\tr{-O*}: convenient ``packages'' of optimisation flags.} +\index{-O options (GHC)} + +There are {\em many} options that affect the quality of code produced by +GHC. Most people only have a general goal, something like ``Compile +quickly'' or ``Make my program run like greased lightning.'' The +following ``packages'' of optimisations (or lack thereof) should suffice. + +Once you choose a \tr{-O*} ``package,'' stick with it---don't chop and +change. Modules' interfaces {\em will} change with a shift to a new +\tr{-O*} option, and you will have to recompile all importing modules +before your program can again be run safely. + +\begin{description} +\item[No \tr{-O*}-type option specified:] +\index{-O* not specified} +This is taken to mean: ``Please compile quickly; I'm not over-bothered +about compiled-code quality.'' So, for example: \tr{ghc -c Foo.hs} + +\item[\tr{-O} or \tr{-O1}:] +\index{-O option} +\index{-O1 option} +\index{optimise normally} +Means: ``Generate good-quality code without taking too long about it.'' +Thus, for example: \tr{ghc -c -O Main.lhs} + +\item[\tr{-O2}:] +\index{-O2 option} +\index{optimise aggressively} +Means: ``Apply every non-dangerous optimisation, even if it means +significantly longer compile times.'' + +The avoided ``dangerous'' optimisations are those that can make +runtime or space {\em worse} if you're unlucky. They are +normally turned on or off individually. + +As of version~0.26, \tr{-O2} is {\em unlikely} to produce +better code than \tr{-O}. + +% \item[\tr{-O0}:] +% \index{-O0 option} +% \index{optimise minimally} +% [``Oh zero''] Means: ``Turn {\em off} as many optimisations (e.g., +% simplifications) as possible.'' This is the only optimisation level +% at which the GCC-register-trickery is turned off. {\em You can't use +% it unless you have a suitably-built Prelude to match.} Intended for +% hard-core debugging. + +\item[\tr{-fvia-C}:] +\index{-fvia-C option} +Compile via C, and don't use the native-code generator. +(There are many cases when GHC does this on its own.) You might +pick up a little bit of speed by compiling via C. If you use +\tr{_ccall_}s or \tr{_casm_}s, you probably {\em have to} use +\tr{-fvia-C}. + +\item[\tr{-O2-for-C}:] +\index{-O2-for-C option} +Says to run GCC with \tr{-O2}, which may be worth a few percent in +execution speed. Don't forget \tr{-fvia-C}, lest you use the +native-code generator and bypass GCC altogether! + +\item[\tr{-Onot}:] +\index{-Onot option} +\index{optimising, reset} +This option will make GHC ``forget'' any -Oish options it has seen +so far. Sometimes useful; for example: \tr{make all EXTRA_HC_OPTS=-Onot}. + +\item[\tr{-Ofile <file>}:] +\index{-Ofile <file> option} +\index{optimising, customised} +For those who need {\em absolute} control over {\em exactly} what +options are used (e.g., compiler writers, sometimes :-), a list of +options can be put in a file and then slurped in with \tr{-Ofile}. + +In that file, comments are of the \tr{#}-to-end-of-line variety; blank +lines and most whitespace is ignored. + +Please ask if you are baffled and would like an example of \tr{-Ofile}! +\end{description} + +At Glasgow, we don't use a \tr{-O*} flag for day-to-day work. We use +\tr{-O} to get respectable speed; e.g., when we want to measure +something. When we want to go for broke, we tend to use +\tr{-O -fvia-C -O2-for-C} (and we go for lots of coffee breaks). + +%Here is a table to summarise whether pragmatic interface information +%is used or not, whether the native-code generator is used (if +%available), and whether we use GCC register tricks (for speed!) on the +%generated C code: +% +%\begin{tabular}{lccl} +%\tr{-O*} & Interface & Native code & `Registerised' C \\ +% & pragmas? & (if avail.) & (if avail.) \\ \hline +%% +%\pl{<none>} & no & yes & yes, only if \tr{-fvia-C} \\ +%\tr{-O,-O1} & yes & yes & yes, only if \tr{-fvia-C} \\ +%\tr{-O2} & yes & no & yes \\ +%\tr{-Ofile} & yes & yes & yes, only if \tr{-fvia-C} \\ +%\end{tabular} + +The easiest way to see what \tr{-O} (etc) ``really mean'' is to run +with \tr{-v}, then stand back in amazement. +Alternatively, just look at the +\tr{@HsC_minus<blah>} lists in the \tr{ghc} driver script. + +%---------------------------------------------------------------------- +\subsubsection{\tr{-f*}: platform-independent flags} +\index{-f* options (GHC)} +\index{-fno-* options (GHC)} + +Flags can be turned {\em off} individually. (NB: I hope +you have a good reason for doing this....) To turn off the \tr{-ffoo} +flag, just use the \tr{-fno-foo} flag.\index{-fno-<opt> anti-option} +So, for example, you can say +\tr{-O2 -fno-strictness}, which will then drop out any running of the +strictness analyser. + +The options you are most likely to want to turn off are: +\tr{-fno-update-analysis}\index{-fno-update-analysis option} [because +it is sometimes slow], +\tr{-fno-strictness}\index{-fno-strictness option} (strictness +analyser [because it is sometimes slow]), +\tr{-fno-specialise}\index{-fno-specialise option} (automatic +specialisation of overloaded functions [because it makes your code +bigger]) [US spelling also accepted], +and +\tr{-fno-foldr-build}\index{-fno-foldr-build option} [because no-one +knows what Andy Gill made it do]. + +Should you wish to turn individual flags {\em on}, you are advised to +use the \tr{-Ofile} option, described above. Because the order in +which optimisation passes are run is sometimes crucial, it's quite +hard to do with command-line options. + +Here are some ``dangerous'' optimisations you {\em might} want to try: +\begin{description} +%------------------------------------------------------------------ +\item[\tr{-funfolding-creation-threshold<n>}:] +(Default: 30) By raising or lowering this number, you can raise or lower the +amount of pragmatic junk that gets spewed into interface files. +(An unfolding has a ``size'' that reflects the cost in terms of ``code +bloat'' of expanding that unfolding in another module. A bigger +Core expression would be assigned a bigger cost.) + +\item[\tr{-funfolding-use-threshold<n>}:] +(Default: 3) By raising or lowering this number, you can make the +compiler more or less keen to expand unfoldings. + +OK, folks, these magic numbers `30' and `3' are mildly arbitrary; they +are of the ``seem to be OK'' variety. The `3' is the more critical +one; it's what determines how eager GHC is about expanding unfoldings. + +\item[\tr{-funfolding-override-threshold<n>}:] +(Default: 8) [Pretty obscure] +When deciding what unfoldings from a module should be made available +to the rest of the world (via this module's interface), the compiler +normally likes ``small'' expressions. + +For example, if it sees \tr{foo = bar}, it will decide that the very +small expression \tr{bar} is a great unfolding for \tr{foo}. But if +\tr{bar} turns out to be \tr{(True,False,True)}, we would probably +prefer {\em that} for the unfolding for \tr{foo}. + +Should we ``override'' the initial small unfolding from \tr{foo=bar} +with the bigger-but-better one? Yes, if the bigger one's ``size'' is +still under the ``override threshold.'' You can use this flag to +adjust this threshold (why, I'm not sure). + +\item[\tr{-fliberated-case-threshold<n>}:] +(Default: 12) [Vastly obscure: NOT IMPLEMENTED YET] +``Case liberation'' lifts evaluation out of recursive functions; it +does this by duplicating code. Done without constraint, you can get +serious code bloat; so we only do it if the ``size'' of the duplicated +code is smaller than some ``threshold.'' This flag can fiddle that +threshold. + +\item[\tr{-fsemi-tagging}:] +This option (which {\em does not work} with the native-code generator) +tells the compiler to add extra code to test for already-evaluated +values. You win if you have lots of such values during a run of your +program, you lose otherwise. (And you pay in extra code space.) + +We have not played with \tr{-fsemi-tagging} enough to recommend it. +(For all we know, it doesn't even work in 0.26. Sigh.) +\end{description} + +%---------------------------------------------------------------------- +% \subsubsection[optimise-simplifier]{Controlling ``simplification'' in the Haskell compiler.} +% +%Almost everyone turns program transformation +% (a.k.a. ``simplification'') on/off via one of the ``packages'' above, +%but you can exert absolute control if you want to. Do a \tr{ghc -v -O ...}, +%and you'll see there are plenty of knobs to turn! +% +%The Core-to-Core and STG-to-STG passes can be run multiple times, and +%in varying orders (though you may live to regret it). The on-or-off +%global flags, however, are simply, well, on or off. +% +%The best way to give an exact list of options is the \tr{-Ofile} +%option, described elsewhere. +% +% [Check out \tr{ghc/compiler/simplCore/SimplCore.lhs} and +%\tr{simplStg/SimplStg.lhs} if you {\em really} want to see every +%possible Core-to-Core and STG-to-STG pass, respectively. The +%on-or-off global flags that effect what happens {\em within} one of +%these passes are defined by the \tr{GlobalSwitch} datatype in +%\tr{compiler/main/CmdLineOpts.lhs}.] + +%---------------------------------------------------------------------- +\subsubsection{\tr{-m*}: platform-specific flags} +\index{-m* options (GHC)} +\index{platform-specific options} +\index{machine-specific options} + +Some flags only make sense for particular target platforms. + +\begin{description} +\item[\tr{-mlong-calls}:] +(HPPA machines)\index{-mlong-calls option (HPPA only)} +Means to pass the like-named option to GCC. Required for Very Big +modules, maybe. (Probably means you're in trouble...) + +\item[\tr{-monly-[432]-regs}:] +(iX86 machines)\index{-monly-N-regs option (iX86 only)} +GHC tries to ``steal'' five registers from GCC, for performance +reasons; it almost always works. However, when GCC is compiling some +modules with five stolen registers, it will crash, probably saying: +\begin{verbatim} +Foo.hc:533: fixed or forbidden register was spilled. +This may be due to a compiler bug or to impossible asm +statements or clauses. +\end{verbatim} +Just give some registers back with \tr{-monly-N-regs}. Try `4' first, +then `3', then `2'. If `2' doesn't work, please report the bug to us. +\end{description} + +%---------------------------------------------------------------------- +\subsubsection[optimise-C-compiler]{Code improvement by the C compiler.} +\index{optimisation by GCC} +\index{GCC optimisation} + +The C~compiler, normally GCC, is run with \tr{-O} turned on. (It has +to be, actually.) + +If you want to run GCC with \tr{-O2}---which may be worth a few +percent in execution speed---you can give a +\tr{-O2-for-C}\index{-O2-for-C option} option. + +%If you are brave or foolish, you might want to omit some checking code +% (e.g., for stack-overflow checks), as sketched in +%\sectionref{omit-checking}. + +%************************************************************************ +%* * +\subsection[options-sanity]{Sanity-checking options} +\index{sanity-checking options} +%* * +%************************************************************************ + +If you would like GHC to check that every top-level value has a type +signature, use the \tr{-fsignatures-required} +option.\index{-fsignatures-required option} + +If you would like to disallow ``name shadowing,'' i.e., an inner-scope +value has the same name as an outer-scope value, then use the +\tr{-fname-shadowing-not-ok} +option.\index{-fname-shadowing-not-ok option} +This option catches typographical errors that turn into hard-to-find +bugs, e.g., in the inadvertent cyclic definition \tr{let x = ... x ... in}. + +Consequently, this option does {\em not} allow cyclic recursive +definitions. + +If you're feeling really paranoid, the \tr{-dcore-lint} +option\index{-dcore-lint option} is a good choice. It turns on +heavyweight intra-pass sanity-checking within GHC. (It checks GHC's +sanity, not yours.) + +%************************************************************************ +%* * +\subsection[options-output]{Re-directing the compilation output(s)} +\index{output-directing options} +%* * +%************************************************************************ + +When compiling a Haskell module, GHC may produce several files of +output (usually two). + +One file is usually an {\em interface file}. If compiling +\tr{bar/Foo.hs}, the interface file would normally be \tr{bar/Foo.hi}. +The interface output may be directed to another file +\tr{bar2/Wurble.iface} with the option +\tr{-ohi bar2/Wurble.iface}\index{-ohi <file> option}. + +To avoid generating an interface file at all, use a \tr{-nohi} +option.\index{-nohi option} + +The compiler does not overwrite an existing \tr{.hi} interface file if +the new one is byte-for-byte the same as the old one; this is friendly to +\tr{make}. When an interface does change, it is often enlightening to +be informed. The \tr{-hi-diffs}\index{-hi-diffs option} option will +make \tr{ghc} run \tr{diff} on the old and new \tr{.hi} files. + +GHC's non-interface output normally goes into a \tr{.hc}, \tr{.o}, +etc., file, depending on the last-run compilation phase. The option +\tr{-o foo}\index{-o option} re-directs the output of that last-run +phase to file \tr{foo}. + +Note: this ``feature'' can be counterintuitive: +\tr{ghc -C -o foo.o foo.hs} will put the intermediate C code in the +file \tr{foo.o}, name notwithstanding! + +EXOTICA: But the \tr{-o} option isn't much use if you have {\em +several} input files... Non-interface output files are normally put +in the same directory as their corresponding input file came from. +You may specify that they be put in another directory using the +\tr{-odir <dir>}\index{-odir <dir> option} (the ``Oh, dear'' option). +For example: + +\begin{verbatim} +% ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` +\end{verbatim} + +The output files, \tr{Foo.o}, \tr{Bar.o}, and \tr{Bumble.o} would be +put into a subdirectory named after the architecture of the executing +machine (\tr{sun4}, \tr{mips}, etc). The directory must already +exist; it won't be created. + +Note that the \tr{-odir} option does {\em not} affect where the +interface files are put. In the above example, they would still be +put in \tr{parse/Foo.hi}, \tr{parse/Bar.hi}, and +\tr{gurgle/Bumble.hi}. + +MORE EXOTICA: The \tr{-osuf <suffix>}\index{-osuf <suffix> option} +will change the \tr{.o} file suffix for object files to whatever +you specify. (We use this in compiling the prelude.) + +Similarly, the \tr{-hisuf <suffix>}\index{-hisuf <suffix> option} will +change the \tr{.hi} file suffix for non-system interface files. This +can be useful when you are trying to compile a program several ways, +all in the same directory. The suffix given is used for {\em all} +interfaces files written, {\em and} for all non-system interface files +that your read. + +The \tr{-hisuf}/\tr{-osuf} game is useful if you want to compile a +program with both GHC and HBC (say) in the same directory. Let HBC +use the standard \tr{.hi}/\tr{.o} suffixes; add +\tr{-hisuf _g.hi -osuf _g.o} to your \tr{make} rule for GHC compiling... + +% THIS SHOULD HAPPEN AUTOMAGICALLY: +% If you want to change the suffix looked for on system-supplied +% interface files (notably the \tr{Prelude.hi} file), use the +% \tr{-hisuf-prelude <suffix>}\index{-hisuf-prelude <suffix> option} +% option. (This may be useful if you've built GHC in various funny +% ways, and you are running tests in even more funny ways. It happens.) + +FURTHER EXOTICA: If you are doing a normal \tr{.hs}-to-\tr{.o} compilation +but would like to hang onto the intermediate \tr{.hc} C file, just +throw in a \tr{-keep-hc-file-too} option\index{-keep-hc-file-too option}. +If you would like to look at the assembler output, toss in a +\tr{-keep-s-file-too},\index{-keep-hc-file-too option} too. + +SAVING GHC STDERR OUTPUT: Sometimes, you may cause GHC to be rather +chatty on standard error; with \tr{-fshow-import-specs}, for example. +You can instruct GHC to {\em append} this output to a particular log +file with a \tr{-odump <blah>}\index{-odump <blah> option} option. + +TEMPORARY FILES: If you have trouble because of running out of space +in \tr{/tmp/} (or wherever your installation thinks temporary files +should go), you may use the \tr{-tmpdir <dir>}\index{-tmpdir <dir> option} +option to specify an alternate directory. For example, \tr{-tmpdir .} +says to put temporary files in the current working directory. + +BETTER IDEA FOR TEMPORARY FILES: Use your \tr{TMPDIR} environment +variable.\index{TMPDIR environment variable} Set it to the name of +the directory where temporary files should be put. GCC and other +programs will honour the \tr{TMPDIR} variable as well. + +EVEN BETTER IDEA: Configure GHC with \tr{--with-tmpdir=<mumble>} when +you build it, and never worry about \tr{TMPDIR} again. + +%************************************************************************ +%* * +\subsection[options-finding-imports-etc]{For finding interface files, etc.} +\index{interface files, finding them} +\index{finding interface files} +%* * +%************************************************************************ + +In your program, you import a module \tr{Foo} by saying +\tr{import Foo}. GHC goes looking for an interface file, \tr{Foo.hi}. +It has a builtin list of directories (notably including \tr{.}) where +it looks. + +The \tr{-i<dirs>} option\index{-i<dirs> option} prepends a +colon-separated list of \tr{dirs} to the ``import directories'' list. + +A plain \tr{-i} resets the ``import directories'' list back to nothing. + +GHC normally imports \tr{PreludeCore.hi} and \tr{Prelude.hi} files for +you. If you'd rather it didn't, then give it a +\tr{-fno-implicit-prelude} option\index{-fno-implicit-prelude option}. +(Sadly, it still has to {\em find} a \tr{PreludeNull_.hi} file; it +just won't feed it into the compiler proper.) You are unlikely to get +very far without a Prelude, but, hey, it's a free country. + +If you are using a system-supplied non-Prelude library (e.g., the HBC +library), just use a \tr{-syslib hbc}\index{-syslib <lib> option} +option (for example). The right interface files should then be +available. + +Once a Haskell module has been compiled to C (\tr{.hc} file), you may +wish to specify where GHC tells the C compiler to look for \tr{.h} +files. (Or, if you are using the \tr{-cpp} option\index{-cpp option}, +where it tells the C pre-processor to look...) For this purpose, use +a \tr{-I<dir>}\index{-I<dir> option} in the usual C-ish way. + +Pragmas: Interface files are normally jammed full of +compiler-produced {\em pragmas}, which record arities, strictness +info, etc. If you think these pragmas are messing you up (or you are +doing some kind of weird experiment), you can tell GHC to ignore them +with the \tr{-fignore-interface-pragmas}\index{-fignore-interface-pragmas option} +option. + +See also \sectionref{options-linker}, which describes how the linker +finds standard Haskell libraries. + +%************************************************************************ +%* * +%\subsection[options-names]{Fiddling with namespaces} +%* * +%************************************************************************ + +%-split-objs and -fglobalise-toplev-names. You don't need them and you +%don't want to know; used for the prelude (ToDo). + +%************************************************************************ +%* * +\subsection[options-CPP]{Related to the C pre-processor} +\index{C pre-processor options} +\index{pre-processor (cpp) options} +%* * +%************************************************************************ + +The C pre-processor \tr{cpp} is run over your Haskell code only if the +\tr{-cpp} option \index{-cpp option} is given. Unless you are +building a large system with significant doses of conditional +compilation, you really shouldn't need it. +\begin{description} +\item[\tr{-D<foo>}:] +\index{-D<name> option} +Define macro \tr{<foo>} in the usual way. NB: does {\em not} affect +\tr{-D} macros passed to the C~compiler when compiling via C! For +those, use the \tr{-optc-Dfoo} hack... + +\item[\tr{-U<foo>}:] +\index{-U<name> option} +Undefine macro \tr{<foo>} in the usual way. + +\item[\tr{-I<dir>}:] +\index{-I<dir> option} +Specify a directory in which to look for \tr{#include} files, in +the usual UNIX/C way. +\end{description} + +The \tr{ghc} driver pre-defines several macros: +\begin{description} +\item[\tr{__HASKELL1__}:] +\index{__HASKELL1__ macro} +If defined to $n$, that means GHC supports the +Haskell language defined in the Haskell report version $1.n$. +Currently 2. + +NB: This macro is set both when pre-processing Haskell source and +when pre-processing generated C (\tr{.hc}) files. + +If you give the \tr{-fhaskell-1.3} flag\index{-fhaskell-1.3 option}, +then \tr{__HASKELL1__} is set to 3. Obviously. + +\item[\tr{__GLASGOW_HASKELL__}:] +\index{__GLASGOW_HASKELL__ macro} +For version $n$ of the GHC system, this will be \tr{#define}d to +$100 \times n$. So, for version~0.26, it is 26. + +This macro is {\em only} set when pre-processing Haskell source. +({\em Not} when pre-processing generated C.) + +With any luck, \tr{__GLASGOW_HASKELL__} will be undefined in all other +implementations that support C-style pre-processing. + +(For reference: the comparable symbols for other systems are: +\tr{__YALE_HASKELL__} for Yale Haskell, \tr{__HBC__} for Chalmers +HBC, and \tr{__GOFER__} for Gofer [I think].) + +\item[\tr{__CONCURRENT_HASKELL__}:] +\index{__CONCURRENT_HASKELL__ macro} +Only defined when \tr{-concurrent} is in use! +This symbol is +defined when pre-processing Haskell (input) and pre-processing C (GHC +output). + +\item[\tr{__PARALLEL_HASKELL__}:] +\index{__PARALLEL_HASKELL__ macro} +Only defined when \tr{-parallel} is in use! This symbol is defined when +pre-processing Haskell (input) and pre-processing C (GHC output). +\end{description} + +Options other than the above can be forced through to the C +pre-processor with the \tr{-opt} flags (see +\sectionref{forcing-options-through}). + +A small word of warning: \tr{-cpp} is not friendly to +``string gaps''.\index{-cpp vs string gaps}\index{string gaps vs -cpp} + + +%************************************************************************ +%* * +\subsection[options-C-compiler]{Options affecting the C compiler (if applicable)} +\index{C compiler options} +\index{GCC options} +%* * +%************************************************************************ + +At the moment, quite a few common C-compiler options are passed on +quietly to the C compilation of Haskell-compiler-generated C files. +THIS MAY CHANGE. Meanwhile, options so sent are: + +\begin{tabular}{ll} +\tr{-Wall} & get all warnings from GCC \\ +\tr{-ansi} & do ANSI C (not K\&R) \\ +\tr{-pedantic} & be so\\ +\tr{-dgcc-lint} & (hack) short for ``make GCC very paranoid''\\ +\end{tabular} +\index{-Wall option (for GCC)} +\index{-ansi option (for GCC)} +\index{-pedantic option (for GCC)} +\index{-dgcc-lint option (GCC paranoia)} + +If you are compiling with lots of \tr{ccalls}, etc., you may need to +tell the C~compiler about some \tr{#include} files. There is no +pretty way to do this, but you can use this hack from the +command-line: +\begin{verbatim} +% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs +\end{verbatim} +\index{-#include <file> option} + +%************************************************************************ +%* * +%\subsection[options-native-code]{Options affecting the native-code generator(s)} +%* * +%************************************************************************ + +%The only option is to select the target architecture. Right now, +%you have only at most one choice: \tr{-fasm-sparc}.\index{-fasm-<target> option} +% +%EXPECT this native-code stuff to change in the future. + +%************************************************************************ +%* * +\subsection[options-linker]{Linking and consistency-checking} +\index{linker options} +\index{ld options} +%* * +%************************************************************************ + +GHC has to link your code with various libraries, possibly including: +user-supplied, GHC-supplied, and system-supplied (\tr{-lm} math +library, for example). + +\begin{description} +\item[\tr{-l<FOO>}:] +\index{-l<lib> option} +Link in a library named \tr{lib<FOO>.a} which resides somewhere on the +library directories path. + +Because of the sad state of most UNIX linkers, the order of such +options does matter. Thus: \tr{ghc -lbar *.o} is almost certainly +wrong, because it will search \tr{libbar.a} {\em before} it has +collected unresolved symbols from the \tr{*.o} files. +\tr{ghc *.o -lbar} is probably better. + +The linker will of course be informed about some GHC-supplied +libraries automatically; these are: + +\begin{tabular}{ll} +-l equivalent & description \\ \hline + +-lHSrts,-lHSclib & basic runtime libraries \\ +-lHS & standard Prelude library \\ +-lgmp & GNU multi-precision library (for Integers)\\ +\end{tabular} +\index{-lHS library} +\index{-lHSrts library} +\index{-lgmp library} + +\item[\tr{-syslib <name>}:] +\index{-syslib <name> option} + +If you are using an optional GHC-supplied library (e.g., the HBC +library), just use the \tr{-syslib hbc} option, and the correct code +should be linked in. + +Please see \sectionref{syslibs} for information about optional +GHC-supplied libraries. + +\item[\tr{-L<dir>}:] +\index{-L<dir> option} +Where to find user-supplied libraries... Prepend the directory +\tr{<dir>} to the library directories path. + +\item[\tr{-static}:] +\index{-static option} +Tell the linker to avoid shared libraries. + +\item[\tr{-no-link-chk} and \tr{-link-chk}:] +\index{-no-link-chk option} +\index{-link-chk option} +\index{consistency checking of executables} +By default, immediately after linking an executable, GHC verifies that +the pieces that went into it were compiled with compatible flags; a +``consistency check''. +(This is to avoid mysterious failures caused by non-meshing of +incompatibly-compiled programs; e.g., if one \tr{.o} file was compiled +for a parallel machine and the others weren't.) You may turn off this +check with \tr{-no-link-chk}. You can turn it (back) on with +\tr{-link-chk} (the default). +\end{description} + +%************************************************************************ +%* * +\subsection[options-compiler-RTS]{For the compiler's RTS: heap, stack sizes, etc.} +\index{heap-size options (for GHC)} +\index{stack-size options (for GHC)} +%* * +%************************************************************************ + +The compiler is itself a Haskell program, so it has a tweakable +runtime-system (RTS), just like any other Haskell program. + +\begin{description} +\item[\tr{-H<size>} or \tr{-Rmax-heapsize <size>}:] +\index{-H<size> option} +\index{-Rmax-heapsize <size> option} +Don't use more than \tr{<size>} {\em bytes} for heap space. If more +than one of these arguments is given, the largest will be taken. + +A size of zero can be used to reset the heap size downwards. For +example, to run GHC with a heap of 250KB (the default is 6MB), do +\tr{-H0 -H250k}. + +\item[\tr{-K<size>} or \tr{-Rmax-stksize <size>}:] +\index{-K<size> option} +\index{-Rmax-stksize <size> option} +Set the stack space to \tr{<size>} bytes. If you have to set it very +high [a megabyte or two, say], the compiler is probably looping, which +is a BUG (please report). + +A size of zero can be used to rest the stack size downwards, as above. + +\item[\tr{-Rscale-sizes<factor>}:] +\index{-Rscale-sizes<factor> option} +Multiply the given (or default) heap and stack sizes by \tr{<factor>}. +For example, on a DEC Alpha (a 64-bit machine), you might want to +double those space sizes; just use \tr{-Rscale-sizes2}. + +A non-integral factor is OK, too: \tr{-Rscale-sizes1.2}. + +\item[\tr{-Rghc-timing}:] +\index{-Rghc-timing option} +Reports a one-line useful collection of time- and space- statistics +for a module's compilation. + +\item[\tr{-Rgc-stats}:] +\index{-Rgc-stats option} +Report garbage-collection statistics. It will create a +\tr{<foo>.stat} file, in some obvious place (I hope). + +Alternatively, if you'd rather the GC stats went straight to standard +error, you can ``cheat'' by using, instead: \tr{-optCrts-Sstderr}. + +\item[\tr{-Rhbc}:] +\index{-Rhbc option} +Tell the compiler it has an HBC-style RTS; i.e., it was compiled with +HBC. Not used in Real Life. + +\item[\tr{-Rghc}:] +\index{-Rghc option} +Tell the compiler it has a GHC-style RTS; i.e., it was compiled with +GHC. Not used in Real Life. +\end{description} + +For all \tr{<size>}s: If the last character of \tr{size} is a K, +multiply by 1000; if an M, by 1,000,000; if a G, by 1,000,000,000. +Sizes are always in {\em bytes}, not words. Good luck on the G's (I +think the counter is still only 32-bits [WDP])! + +%************************************************************************ +%* * +%\subsection[options-cross-compiling]{For cross-compiling to another architecture} +%* * +%************************************************************************ +% +% (We do this for GRIP at Glasgow; it's hacked in---not proper +%cross-compiling support. But you could do the same, if required...) +% +%The \tr{-target <arch>} option\index{-target <arch> option} says to +%generate code for the \tr{<arch>} architecture. + +%************************************************************************ +%* * +\subsection[options-parallel]{For Concurrent and Parallel Haskell} +%* * +%************************************************************************ + +For the full story on using GHC for concurrent \& parallel Haskell +programming, please see \Sectionref{concurrent-and-parallel}. + +%The \tr{-fparallel} option\index{-fparallel option} tells the compiler +%to generate code for parallel execution. The \tr{-mgrip} +%option\index{-mgrip option} says that the code should be explicitly +%suitable for the GRIP multiprocessor (the one in our Glasgow basement). + +%************************************************************************ +%* * +\subsection[options-experimental]{For experimental purposes} +\index{experimental options} +%* * +%************************************************************************ + +From time to time, we provide GHC options for ``experimenting.'' Easy +come, easy go. In version~0.26, the ``experimental'' options are: +\begin{description} +\item[\tr{-firrefutable-tuples} option:] +\index{-firrefutable-tuples option (experimental)} +Pretend that every tuple pattern is irrefutable; i.e., has a +``twiddle'' (\tr{~}) in front of it. + +Some parts of the GHC system {\em depend} on strictness properties which +\tr{-firrefutable-tuples} may undo, notably the low-level state-transformer +stuff, which includes I/O (!). You're on your own... + +\item[\tr{-fall-strict} option:] +\index{-fall-strict option (experimental)} +(DOESN'T REALLY WORK, I THINK) Changes the strictness analyser so +that, when it asks the question ``Is this function argument certain to +be evaluated?'', the answer is always ``yes''. + +Compilation is changed in no other way. +\end{description} +% -firrefutable-everything +% -fall-demanded + +%************************************************************************ +%* * +\subsection[options-debugging]{For debugging the compiler} +\index{debugging options (for GHC)} +%* * +%************************************************************************ + +HACKER TERRITORY. HACKER TERRITORY. +(You were warned.) + +%---------------------------------------------------------------------- +\subsubsection[replacing-phases]{Replacing the program for one or more phases.} +\index{GHC phases, changing} +\index{phases, changing GHC} + +You may specify that a different program +be used for one of the phases of the compilation system, in place of +whatever the driver \tr{ghc} has wired into it. For example, you +might want to test a replacement parser. The +\tr{-pgm<phase-code><program-name>}\index{-pgm<phase><stuff> option} option to +\tr{ghc} will cause it to use \pl{<program-name>} for phase +\pl{<phase-code>}, where the codes to indicate the phases are: + +\begin{tabular}{ll} +code & phase \\ \hline +L & literate pre-processor \\ +P & C pre-processor (if -cpp only) \\ +p & parser \\ +C & Haskell compiler \\ +cO & C compiler for `optimised' (normal) compiling \\ +c & C compiler for `unregisterised' compiling \\ +a & assembler \\ +l & linker \\ +\end{tabular} + +If you use the ambiguous \tr{-pgmcOle}, it will take it to mean +``use program \tr{le} for optimised C compiling.'' + +%---------------------------------------------------------------------- +\subsubsection[forcing-options-through]{Forcing options to a particular phase.} +\index{forcing GHC-phase options} + +The preceding sections describe driver options that are mostly +applicable to one particular phase. You may also {\em force} a +specific option \tr{<option>} to be passed to a particular phase +\tr{<phase-code>} by feeding the driver the option +\tr{-opt<phase-code><option>}.\index{-opt<phase><stuff> option} The +codes to indicate the phases are the same as in the previous section. + +So, for example, to force an \tr{-Ewurble} option to the assembler, you +would tell the driver \tr{-opta-Ewurble} (the dash before the E is +required). + +Besides getting options to the Haskell compiler with \tr{-optC<blah>}, +you can get options through to its runtime system with +\tr{-optCrts<blah>}\index{-optCrts<blah> option}. + +So, for example: when I want to use my normal driver but with my +profiled compiler binary, I use this script: +\begin{verbatim} +#! /bin/sh +exec /local/grasp_tmp3/partain/ghc-BUILDS/working-alpha/ghc/driver/ghc \ + -pgmC/local/grasp_tmp3/partain/ghc-BUILDS/working-hsc-prof/hsc \ + -optCrts-i0.5 \ + -optCrts-PT \ + "$@" +\end{verbatim} + +%---------------------------------------------------------------------- +\subsubsection[dumping-output]{Dumping out compiler intermediate structures} +\index{dumping GHC intermediates} +\index{intermediate passes, output} + +\begin{description} +\item[\tr{-noC}:] +\index{-noC option} +Don't bother generating C output {\em or} an interface file. Usually +used in conjunction with one or more of the \tr{-ddump-*} options; for +example: \tr{ghc -noC -ddump-simpl Foo.hs} + +\item[\tr{-hi}:] +\index{-hi option} +{\em Do} generate an interface file. This would normally be used in +conjunction with \tr{-noC}, which turns off interface generation; +thus: \tr{-noC -hi}. + +\item[\tr{-ddump-parser}:] +\index{-ddump-parser option} +This debugging option shows the exact prefix-form Haskell that is fed +into the Haskell compiler proper. + +\item[\tr{-ddump-<pass>}:] +\index{-ddump-<pass> options} +Make a debugging dump after pass \tr{<pass>} (may be common enough to +need a short form...). Some of the most useful ones are: + +\begin{tabular}{ll} +\tr{-ddump-rif2hs} & reader output (earliest stuff in the compiler) \\ +\tr{-ddump-rn4} & renamer output \\ +\tr{-ddump-tc} & typechecker output \\ +\tr{-ddump-deriv} & derived instances \\ +\tr{-ddump-ds} & desugarer output \\ +\tr{-ddump-simpl} & simplifer output (Core-to-Core passes) \\ + & (and don't forget \tr{-O}, too!) \\ +\tr{-ddump-stranal} & strictness analyser output \\ + & (only works in conjunction with -ddump-simpl)\\ +\tr{-ddump-occur-anal} & `occurrence analysis' output \\ + & (only works in conjunction with -ddump-simpl)\\ +\tr{-ddump-spec} & dump specialisation info \\ +\tr{-ddump-stg} & output of STG-to-STG passes \\ +\tr{-ddump-absC} & {\em un}flattened Abstract~C \\ +\tr{-ddump-flatC} & {\em flattened} Abstract~C \\ +\tr{-ddump-realC} & same as what goes to the C compiler \\ +\tr{-ddump-asm} & assembly language from the native-code generator \\ +\end{tabular} +\index{-ddump-rif2hs option}% +\index{-ddump-rn4 option}% +\index{-ddump-tc option}% +\index{-ddump-deriv option}% +\index{-ddump-ds option}% +\index{-ddump-simpl option}% +\index{-ddump-stranal option}% +\index{-ddump-occur-anal option}% +\index{-ddump-spec option}% +\index{-ddump-stg option}% +\index{-ddump-absC option}% +\index{-ddump-flatC option}% +\index{-ddump-realC option}% +\index{-ddump-asm option} + +%For any other \tr{-ddump-*} options: consult the source, notably +%\tr{ghc/compiler/main/CmdLineOpts.lhs}. + +\item[\tr{-dverbose-simpl} and \tr{-dverbose-stg}:] +\index{-dverbose-simpl option} +\index{-dverbose-stg option} +Show the output of the intermediate Core-to-Core and STG-to-STG +passes, respectively. ({\em Lots} of output!) So: when we're +really desperate: +\begin{verbatim} +% ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs +\end{verbatim} + +\item[\tr{-dppr-{user,debug,all}}:] +\index{-dppr-user option} +\index{-dppr-debug option} +\index{-dppr-all option} +Debugging output is in one of several ``styles.'' Take the printing +of types, for example. In the ``user'' style, the compiler's internal +ideas about types are presented in Haskell source-level syntax, +insofar as possible. In the ``debug'' style (which is the default for +debugging output), the types are printed in the most-often-desired +form, with explicit foralls, etc. In the ``show all'' style, very +verbose information about the types (e.g., the Uniques on the +individual type variables) is displayed. + +\item[\tr{-ddump-raw-asm}:] +\index{-ddump-raw-asm option} +Dump out the assembly-language stuff, before the ``mangler'' gets it. + +\item[\tr{-dgc-debug}:] +\index{-dgc-debug option} +Enables some debugging code related to the garbage-collector. +\end{description} + +%ToDo: -ddump-asm-insn-counts +%-ddump-asm-globals-info + +%---------------------------------------------------------------------- +\subsubsection[arity-checking]{Options to insert arity-checking code} +\index{arity checking} + +The \tr{-darity-checks}\index{-darity-checks option} option inserts +code to check for arity violations. Unfortunately, it's not that +simple: you have to link with a prelude that was also built with arity +checks. If you have one, then great; otherwise... + +The \tr{-darity-checks-C-only}\index{-darity-checks-C-only option} +option inserts the self-same arity checking code into \tr{.hc} files, +but doesn't compile it into the \tr{.o} files. We use this flag with +the \tr{-keep-hc-file-too}\index{-keep-hc-file-too option}, where we +are keeping \tr{.hc} files around for debugging purposes. + +%---------------------------------------------------------------------- +\subsubsection[omit-checking]{Options to omit checking code} +\index{omitting runtime checks} + +By default, the GHC system emits all possible not-too-expensive +runtime checking code. If you are brave or experimenting, you might +want to turn off some of this (not recommended): + +\begin{tabular}{ll} +-dno-black-holing & won't buy you much (even if it works) \\ +-dno-updates & you're crazy if you do this \\ +-dno-stk-stubbing & omit stack stubbing (NOT DONE YET) \\ +\end{tabular} +\index{-dno-black-holing option}% +\index{-dno-updates option}% +\index{-dno-stk-stubbing option} + +Warning: all very lightly tested, if at all... + +%% %************************************************************************ +%% %* * +%% \subsection[options-GC]{Choosing a garbage collector} +%% %* * +%% %************************************************************************ +%% +%% (Note: you need a Good Reason before launching into this territory.) +%% +%% There are up to four garbage collectors to choose from (it depends how +%% your local system was built); the Appel-style generational collector +%% is the default. +%% +%% If you choose a non-default collector, you must specify it both when +%% compiling the modules and when linking them together into an +%% executable. Also, the native-code generator only works with the +%% default collector (a small point to bear in mind). +%% +%% \begin{description} +%% \item[\tr{-gc-ap} option:] +%% \index{-gc-ap option} +%% Appel-like generational collector (the default). +%% +%% \item[\tr{-gc-2s} option:] +%% \index{-gc-2s option} +%% Two-space copying collector. +%% +%% \item[\tr{-gc-1s} option:] +%% \index{-gc-1s option} +%% One-space compacting collector. +%% +%% \item[\tr{-gc-du} option:] +%% \index{-gc-du option} +%% Dual-mode collector (swaps between copying and compacting). +%% \end{description} diff --git a/ghc/docs/users_guide/intro.lit b/ghc/docs/users_guide/intro.lit new file mode 100644 index 0000000000..4a85d28a9a --- /dev/null +++ b/ghc/docs/users_guide/intro.lit @@ -0,0 +1,69 @@ +% +% $Header: /srv/cvs/cvs.haskell.org/fptools/ghc/docs/users_guide/Attic/intro.lit,v 1.1 1996/01/08 20:25:10 partain Exp $ +% +\section[introduction-GHC]{Introduction to GHC} + +This is a guide to using the Glasgow Haskell compilation (GHC) system. +It is a batch compiler for the Haskell~1.2 language, with support for +various extensions, including the DRAFT 1.3 I/O proposal. + +Many people will use GHC very simply: compile some +modules---\tr{ghc -c -O Foo.hs Bar.hs}; and link them--- +\tr{ghc -o wiggle -O Foo.o Bar.o}. + +But if you need to do something more complicated, GHC can do that, +too: +\begin{verbatim} +ghc -c -O -fno-foldr-build -dcore-lint -fvia-C -ddump-simpl Foo.lhs +\end{verbatim} +Stay tuned---all will be revealed! + +In this document, we assume that GHC has been installed at your +site as \tr{ghc}. +If you are unfamiliar with the conventions of UNIX compilers, the +material in \sectionref{compiler-tutorial} may help. + +%-------------------------------------------------------------------- +\section[mailing-lists-GHC]{Knowing us, knowing you: Web sites, mailing lists, etc.} +\index{mailing lists, Glasgow Haskell} +\index{Glasgow Haskell mailing lists} + +On the World-Wide Web, there are several URLs of likely interest: +\begin{display} +GHC home page -- http://www.dcs.glasgow.ac.uk/fp/software/ghc.html +Glasgow FP group page -- http://www.dcs.glasgow.ac.uk/fp/ +comp.lang.functional FAQ -- http://www.cs.nott.ac.uk/Department/Staff/mpj/faq.html +programming language research page -- + http://www.cs.cmu.edu/afs/cs.cmu.edu/user/mleone/web/language-research.html +\end{display} +We run two mailing lists about Glasgow Haskell. We encourage you to +join, as you feel is appropriate. +\begin{description} +\item[glasgow-haskell-users:] +This list is for GHC users to chat among themselves. Subscribe by +sending mail to \tr{glasgow-haskell-users-request@dcs.glasgow.ac.uk}. +Messages for the list go to \tr{glasgow-haskell-users}. + +\item[glasgow-haskell-bugs:] +Send bug reports for GHC to this address! The sad and lonely people +who subscribe to this list will muse upon what's wrong and what you +might do about it. + +Subscribe via \tr{glasgow-haskell-bugs-request@dcs.glasgow.ac.uk}. +\end{description} + +There is also the general Haskell mailing list. Subscribe by sending +email to \tr{haskell-request@dcs.glasgow.ac.uk} or +\tr{haskell-request@cs.yale.edu}, whichever is geographically closer +to you. + +Some Haskell-related discussion takes place in the Usenet newsgroup +\tr{comp.lang.functional}. (But note: news propagation to Glasgow can +be terrible. That's one reason Glaswegians aren't too active in +c.f.l.) + +The main anonymous-FTP site for Glasgow Haskell is +\tr{ftp.dcs.glasgow.ac.uk}, in \tr{pub/haskell/glasgow/}. +``Important'' bits are mirrored at other Haskell archive sites (and we +have their stuff, too). + diff --git a/ghc/docs/users_guide/libraries.lit b/ghc/docs/users_guide/libraries.lit new file mode 100644 index 0000000000..dbe7b00a1b --- /dev/null +++ b/ghc/docs/users_guide/libraries.lit @@ -0,0 +1,1047 @@ +%************************************************************************ +%* * +\section[syslibs]{System libraries} +\index{system libraries} +\index{libraries, system} +%* * +%************************************************************************ + +We intend to provide more and more ready-to-use Haskell code, so that +every program doesn't have to invent everything from scratch. + +At the moment, we supply a part of the HBC library, as well as the +beginnings of one of our own (``GHC library''). + +If you provide a \tr{-syslib <name>}\index{-syslib <name> option} option, +then the interfaces for that library will come into scope (and may be +\tr{import}ed), and the code will be added in at link time. + +%************************************************************************ +%* * +\subsection[GHC-library]{The GHC system library} +\index{library, GHC} +\index{GHC library} +%* * +%************************************************************************ + +We have started to put together a ``GHC system library.'' + +At the moment, the library is made of generally-useful bits of the +compiler itself. + +To use this library, just give a \tr{-syslib ghc}\index{-syslib ghc option} +option to GHC, both for compiling and linking. + +%************************************************************************ +%* * +\subsubsection[Bag]{The @Bag@ type} +\index{Bag module (GHC syslib)} +%* * +%************************************************************************ + +A {\em bag} is an unordered collection of elements which may contain +duplicates. To use, \tr{import Bag}. + +\begin{verbatim} +emptyBag :: Bag elt +unitBag :: elt -> Bag elt + +unionBags :: Bag elt -> Bag elt -> Bag elt +unionManyBags :: [Bag elt] -> Bag elt +snocBag :: Bag elt -> elt -> Bag elt + +elemBag :: Eq elt => elt -> Bag elt -> Bool +isEmptyBag :: Bag elt -> Bool +filterBag :: (elt -> Bool) -> Bag elt -> Bag elt +partitionBag :: (elt -> Bool) -> Bag elt-> (Bag elt, Bag elt) + -- returns the elements that do/don't satisfy the predicate + +listToBag :: [elt] -> Bag elt +bagToList :: Bag elt -> [elt] +\end{verbatim} + +%************************************************************************ +%* * +\subsubsection[BitSet]{The @BitSet@ type} +\index{BitSet module (GHC syslib)} +%* * +%************************************************************************ + +Bit sets are a fast implementation of sets of integers ranging from 0 +to one less than the number of bits in a machine word (typically 31). +If any element exceeds the maximum value for a particular machine +architecture, the results of these operations are undefined. You have +been warned. [``If you put any safety checks in this code, I will have +to kill you.'' --JSM] + +\begin{verbatim} +mkBS :: [Int] -> BitSet +listBS :: BitSet -> [Int] +emptyBS :: BitSet +singletonBS :: Int -> BitSet + +unionBS :: BitSet -> BitSet -> BitSet +minusBS :: BitSet -> BitSet -> BitSet +elementBS :: Int -> BitSet -> Bool +intersectBS :: BitSet -> BitSet -> BitSet + +isEmptyBS :: BitSet -> Bool +\end{verbatim} + +%************************************************************************ +%* * +\subsubsection[FiniteMap]{The @FiniteMap@ type} +\index{FiniteMap module (GHC syslib)} +%* * +%************************************************************************ + +What functional programmers call a {\em finite map}, everyone else +calls a {\em lookup table}. + +Out code is derived from that in this paper: +\begin{display} +S Adams +"Efficient sets: a balancing act" +Journal of functional programming 3(4) Oct 1993, pages 553-562 +\end{display} +Guess what? The implementation uses balanced trees. + +\begin{verbatim} +-- BUILDING +emptyFM :: FiniteMap key elt +singletonFM :: key -> elt -> FiniteMap key elt +listToFM :: Ord key => [(key,elt)] -> FiniteMap key elt + -- In the case of duplicates, the last is taken + +-- ADDING AND DELETING + -- Throws away any previous binding + -- In the list case, the items are added starting with the + -- first one in the list +addToFM :: Ord key => FiniteMap key elt -> key -> elt -> FiniteMap key elt +addListToFM :: Ord key => FiniteMap key elt -> [(key,elt)] -> FiniteMap key elt + + -- Combines with previous binding +addToFM_C :: Ord key => (elt -> elt -> elt) + -> FiniteMap key elt -> key -> elt + -> FiniteMap key elt +addListToFM_C :: Ord key => (elt -> elt -> elt) + -> FiniteMap key elt -> [(key,elt)] + -> FiniteMap key elt + + -- Deletion doesn't complain if you try to delete something + -- which isn't there +delFromFM :: Ord key => FiniteMap key elt -> key -> FiniteMap key elt +delListFromFM :: Ord key => FiniteMap key elt -> [key] -> FiniteMap key elt + +-- COMBINING + -- Bindings in right argument shadow those in the left +plusFM :: Ord key => FiniteMap key elt -> FiniteMap key elt + -> FiniteMap key elt + + -- Combines bindings for the same thing with the given function +plusFM_C :: Ord key => (elt -> elt -> elt) + -> FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt + +minusFM :: Ord key => FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt + -- (minusFM a1 a2) deletes from a1 any bindings which are bound in a2 + +intersectFM :: Ord key => FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt +intersectFM_C :: Ord key => (elt -> elt -> elt) + -> FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt + +-- MAPPING, FOLDING, FILTERING +foldFM :: (key -> elt -> a -> a) -> a -> FiniteMap key elt -> a +mapFM :: (key -> elt1 -> elt2) -> FiniteMap key elt1 -> FiniteMap key elt2 +filterFM :: Ord key => (key -> elt -> Bool) + -> FiniteMap key elt -> FiniteMap key elt + +-- INTERROGATING +sizeFM :: FiniteMap key elt -> Int +isEmptyFM :: FiniteMap key elt -> Bool + +elemFM :: Ord key => key -> FiniteMap key elt -> Bool +lookupFM :: Ord key => FiniteMap key elt -> key -> Maybe elt +lookupWithDefaultFM + :: Ord key => FiniteMap key elt -> elt -> key -> elt + -- lookupWithDefaultFM supplies a "default" elt + -- to return for an unmapped key + +-- LISTIFYING +fmToList :: FiniteMap key elt -> [(key,elt)] +keysFM :: FiniteMap key elt -> [key] +eltsFM :: FiniteMap key elt -> [elt] +\end{verbatim} + +%************************************************************************ +%* * +\subsubsection[ListSetOps]{The @ListSetOps@ type} +\index{ListSetOps module (GHC syslib)} +%* * +%************************************************************************ + +Just a few set-sounding operations on lists. If you want sets, use +the \tr{Set} module. + +\begin{verbatim} +unionLists :: Eq a => [a] -> [a] -> [a] +intersectLists :: Eq a => [a] -> [a] -> [a] +minusList :: Eq a => [a] -> [a] -> [a] +disjointLists :: Eq a => [a] -> [a] -> Bool +intersectingLists :: Eq a => [a] -> [a] -> Bool +\end{verbatim} + +%************************************************************************ +%* * +\subsubsection[Maybes]{The @Maybes@ type} +\index{Maybes module (GHC syslib)} +%* * +%************************************************************************ + +Note: a \tr{Maybe} type is nearly inevitable in Haskell~1.3. +You should use this module with \tr{-fhaskell-1.3}. + +Two non-abstract types: +\begin{verbatim} +data Maybe a = Nothing | Just a -- Prelude; re-exported +data MaybeErr val err = Succeeded val | Failed err +\end{verbatim} + +Some operations to do with \tr{Maybe} (some commentary follows): +\begin{verbatim} +maybeToBool :: Maybe a -> Bool -- Nothing => False; Just => True +catMaybes :: [Maybe a] -> [a] +allMaybes :: [Maybe a] -> Maybe [a] +firstJust :: [Maybe a] -> Maybe a +findJust :: (a -> Maybe b) -> [a] -> Maybe b + +assocMaybe :: Eq a => [(a,b)] -> a -> Maybe b +mkLookupFun :: (key -> key -> Bool) -- Equality predicate + -> [(key,val)] -- The assoc list + -> (key -> Maybe val) -- A lookup fun to use + + -- a monad thing +thenMaybe :: Maybe a -> (a -> Maybe b) -> Maybe b +returnMaybe :: a -> Maybe a +failMaybe :: Maybe a +mapMaybe :: (a -> Maybe b) -> [a] -> Maybe [b] +\end{verbatim} + +@catMaybes@ takes a list of @Maybe@s and returns a list of the +contents of all the @Just@s in it. + +@allMaybes@ collects a list of @Justs@ into a single @Just@, returning +@Nothing@ if there are any @Nothings@. + +@firstJust@ takes a list of @Maybes@ and returns the +first @Just@ if there is one, or @Nothing@ otherwise. + +@assocMaybe@ looks up in an association list, returning +@Nothing@ if it fails. + +Now, some operations to do with \tr{MaybeErr} (comments follow): +\begin{verbatim} + -- a monad thing (surprise, surprise) +thenMaB :: MaybeErr a err -> (a -> MaybeErr b err) -> MaybeErr b err +returnMaB :: val -> MaybeErr val err +failMaB :: err -> MaybeErr val err + +listMaybeErrs :: [MaybeErr val err] -> MaybeErr [val] [err] +foldlMaybeErrs :: (acc -> input -> MaybeErr acc err) + -> acc + -> [input] + -> MaybeErr acc [err] +\end{verbatim} + +@listMaybeErrs@ takes a list of @MaybeErrs@ and, if they all succeed, +returns a @Succeeded@ of a list of their values. If any fail, it +returns a @Failed@ of the list of all the errors in the list. + +@foldlMaybeErrs@ works along a list, carrying an accumulator; it +applies the given function to the accumulator and the next list item, +accumulating any errors that occur. + +%************************************************************************ +%* * +\subsubsection[PackedString]{The @_PackedString@ type} +\index{PackedString module (GHC syslib)} +%* * +%************************************************************************ + +The type \tr{_PackedString} is built-in, i.e., no +special action (other than a \tr{-fglasgow-exts} flag) is required to +use it. + +The documentation here describes the {\em built-in} functions. + +You may also access this code as a system library and {\em not} use +the \tr{-fglasgow-exts} flag. Just do \tr{import PackedString}, +heave in your \tr{-syslib ghc}, and drop off the leading underscores +which you see here. + +We still may change this interface (again). + +The basic type and functions which are available are: +\begin{verbatim} +data _PackedString + +_packString :: [Char] -> _PackedString +_packStringST :: [Char] -> _ST s _PackedString +_packCString :: _Addr -> _PackedString +_packCBytes :: Int -> _Addr -> _PackedString +_packCBytesST :: Int -> _Addr -> _ST s _PackedString +_packBytesForC :: [Char] -> _ByteArray Int +_packBytesForCST :: [Char] -> _ST s (_ByteArray Int) +_byteArrayToPS :: _ByteArray Int -> _PackedString +_psToByteArray :: _PackedString -> _ByteArray Int + +_unpackPS :: _PackedString -> [Char] +\end{verbatim} + +We also provide a wad of list-manipulation-like functions: +\begin{verbatim} +_nilPS :: _PackedString +_consPS :: Char -> _PackedString -> _PackedString + +_headPS :: _PackedString -> Char +_tailPS :: _PackedString -> _PackedString +_nullPS :: _PackedString -> Bool +_appendPS :: _PackedString -> _PackedString -> _PackedString +_lengthPS :: _PackedString -> Int +_indexPS :: _PackedString -> Int -> Char + -- 0-origin indexing into the string +_mapPS :: (Char -> Char) -> _PackedString -> _PackedString {-or String?-} +_filterPS :: (Char -> Bool) -> _PackedString -> _PackedString {-or String?-} +_foldlPS :: (a -> Char -> a) -> a -> _PackedString -> a +_foldrPS :: (Char -> a -> a) -> a -> _PackedString -> a +_takePS :: Int -> _PackedString -> _PackedString +_dropPS :: Int -> _PackedString -> _PackedString +_splitAtPS :: Int -> _PackedString -> (_PackedString, _PackedString) +_takeWhilePS:: (Char -> Bool) -> _PackedString -> _PackedString +_dropWhilePS:: (Char -> Bool) -> _PackedString -> _PackedString +_spanPS :: (Char -> Bool) -> _PackedString -> (_PackedString, _PackedString) +_breakPS :: (Char -> Bool) -> _PackedString -> (_PackedString, _PackedString) +_linesPS :: _PackedString -> [_PackedString] +_wordsPS :: _PackedString -> [_PackedString] +_reversePS :: _PackedString -> _PackedString +_concatPS :: [_PackedString] -> _PackedString + +_substrPS :: _PackedString -> Int -> Int -> _PackedString + -- pluck out a piece of a _PS + -- start and end chars you want; both 0-origin-specified +\end{verbatim} + +%************************************************************************ +%* * +\subsubsection[Pretty]{The @Pretty@ type} +\index{Pretty module (GHC syslib)} +%* * +%************************************************************************ + +This is the pretty-printer that we use in GHC. + +\begin{verbatim} +type Pretty + +ppShow :: Int{-width-} -> Pretty -> [Char] + +pp'SP :: Pretty -- "comma space" +ppComma :: Pretty -- , +ppEquals :: Pretty -- = +ppLbrack :: Pretty -- [ +ppLparen :: Pretty -- ( +ppNil :: Pretty -- nothing +ppRparen :: Pretty -- ) +ppRbrack :: Pretty -- ] +ppSP :: Pretty -- space +ppSemi :: Pretty -- ; + +ppChar :: Char -> Pretty +ppDouble :: Double -> Pretty +ppFloat :: Float -> Pretty +ppInt :: Int -> Pretty +ppInteger :: Integer -> Pretty +ppRational :: Rational -> Pretty +ppStr :: [Char] -> Pretty + +ppAbove :: Pretty -> Pretty -> Pretty +ppAboves :: [Pretty] -> Pretty +ppBeside :: Pretty -> Pretty -> Pretty +ppBesides :: [Pretty] -> Pretty +ppCat :: [Pretty] -> Pretty +ppHang :: Pretty -> Int -> Pretty -> Pretty +ppInterleave :: Pretty -> [Pretty] -> Pretty -- spacing between +ppIntersperse :: Pretty -> [Pretty] -> Pretty -- no spacing between +ppNest :: Int -> Pretty -> Pretty +ppSep :: [Pretty] -> Pretty +\end{verbatim} + +%************************************************************************ +%* * +\subsubsection[Set]{The @Set@ type} +\index{Set module (GHC syslib)} +%* * +%************************************************************************ + +Our implementation of {\em sets} (key property: no duplicates) is just +a variant of the \tr{FiniteMap} module. + +\begin{verbatim} +mkSet :: Ord a => [a] -> Set a +setToList :: Set a -> [a] +emptySet :: Set a +singletonSet :: a -> Set a + +union :: Ord a => Set a -> Set a -> Set a +unionManySets :: Ord a => [Set a] -> Set a +intersect :: Ord a => Set a -> Set a -> Set a +minusSet :: Ord a => Set a -> Set a -> Set a +mapSet :: Ord a => (b -> a) -> Set b -> Set a + +elementOf :: Ord a => a -> Set a -> Bool +isEmptySet :: Set a -> Bool +\end{verbatim} + +%************************************************************************ +%* * +\subsubsection[Util]{The @Util@ type} +\index{Util module (GHC syslib)} +%* * +%************************************************************************ + +Stuff that has been useful to use in writing the compiler. Don't be +too surprised if this stuff moves/gets-renamed/etc. + +\begin{verbatim} +-- general list processing +forall :: (a -> Bool) -> [a] -> Bool +exists :: (a -> Bool) -> [a] -> Bool +zipEqual :: [a] -> [b] -> [(a,b)] +nOfThem :: Int -> a -> [a] +lengthExceeds :: [a] -> Int -> Bool +isSingleton :: [a] -> Bool + +-- association lists +assoc :: Eq a => String -> [(a, b)] -> a -> b + +-- duplicate handling +hasNoDups :: Eq a => [a] -> Bool +equivClasses :: (a -> a -> _CMP_TAG) -> [a] -> [[a]] +runs :: (a -> a -> Bool) -> [a] -> [[a]] +removeDups :: (a -> a -> _CMP_TAG) -> [a] -> ([a], [[a]]) + +-- sorting (don't complain of no choice...) +quicksort :: (a -> a -> Bool) -> [a] -> [a] +sortLt :: (a -> a -> Bool) -> [a] -> [a] +stableSortLt :: (a -> a -> Bool) -> [a] -> [a] +mergesort :: (a -> a -> _CMP_TAG) -> [a] -> [a] +mergeSort :: Ord a => [a] -> [a] +naturalMergeSort :: Ord a => [a] -> [a] +mergeSortLe :: Ord a => [a] -> [a] +naturalMergeSortLe :: Ord a => [a] -> [a] + +-- transitive closures +transitiveClosure :: (a -> [a]) -- Successor function + -> (a -> a -> Bool) -- Equality predicate + -> [a] + -> [a] -- The transitive closure + +-- accumulating (Left, Right, Bi-directional) +mapAccumL :: (acc -> x -> (acc, y)) + -- Function of elt of input list and + -- accumulator, returning new accumulator and + -- elt of result list + -> acc -- Initial accumulator + -> [x] -- Input list + -> (acc, [y]) -- Final accumulator and result list + +mapAccumR :: (acc -> x -> (acc, y)) -> acc -> [x] -> (acc, [y]) + +mapAccumB :: (accl -> accr -> x -> (accl, accr,y)) + -> accl -> accr -> [x] + -> (accl, accr, [y]) + +-- comparisons +cmpString :: String -> String -> _CMP_TAG + +-- this type is built-in +data _CMP_TAG = _LT | _EQ | _GT + +-- pairs +applyToPair :: ((a -> c), (b -> d)) -> (a, b) -> (c, d) +applyToFst :: (a -> c) -> (a, b) -> (c, b) +applyToSnd :: (b -> d) -> (a, b) -> (a, d) +foldPair :: (a->a->a, b->b->b) -> (a, b) -> [(a, b)] -> (a, b) +unzipWith :: (a -> b -> c) -> [(a, b)] -> [c] +\end{verbatim} + +%************************************************************************ +%* * +\subsection[C-interfaces]{Interfaces to C libraries} +\index{C library interfaces} +\index{interfaces, C library} +%* * +%************************************************************************ + +The GHC system library (\tr{-syslib ghc}) also provides interfaces to +several useful C libraries, mostly from the GNU project. + +%************************************************************************ +%* * +\subsubsection[Readline]{The @Readline@ interface} +\index{Readline library (GHC syslib)} +\index{command-line editing library} +%* * +%************************************************************************ + +(Darren Moffat supplied the \tr{Readline} interface.) + +The \tr{Readline} module is a straightforward interface to the GNU +Readline library. As such, you will need to look at the GNU +documentation (and have a \tr{libreadline.a} file around somewhere...) + +You'll need to link any Readlining program with \tr{-lreadline -ltermcap}, +besides the usual \tr{-syslib ghc} (and \tr{-fhaskell-1.3}). + +The main function you'll use is: +\begin{verbatim} +readline :: String{-the prompt-} -> IO String +\end{verbatim} + +If you want to mess around with Full Readline G(l)ory, we also +provide: +\begin{verbatim} +rlInitialize, addHistory, + +rlBindKey, rlAddDefun, RlCallbackFunction(..), + +rlGetLineBuffer, rlSetLineBuffer, rlGetPoint, rlSetPoint, rlGetEnd, +rlSetEnd, rlGetMark, rlSetMark, rlSetDone, rlPendingInput, + +rlPrompt, rlTerminalName, rlSetReadlineName, rlGetReadlineName +\end{verbatim} +(All those names are just Haskellised versions of what you +will see in the GNU readline documentation.) + +%************************************************************************ +%* * +\subsubsection[Regexp]{The @Regexp@ and @MatchPS@ interfaces} +\index{Regex library (GHC syslib)} +\index{MatchPS library (GHC syslib)} +\index{regular-expressions library} +%* * +%************************************************************************ + +(Sigbjorn Finne supplied the regular-expressions interface.) + +The \tr{Regex} library provides quite direct interface to the GNU +regular-expression library, for doing manipulation on +\tr{_PackedString}s. You probably need to see the GNU documentation +if you are operating at this level. + +The datatypes and functions that \tr{Regex} provides are: +\begin{verbatim} +data PatBuffer # just a bunch of bytes (mutable) + +data REmatch + = REmatch (Array Int GroupBounds) -- for $1, ... $n + GroupBounds -- for $` (everything before match) + GroupBounds -- for $& (entire matched string) + GroupBounds -- for $' (everything after) + GroupBounds -- for $+ (matched by last bracket) + +-- GroupBounds hold the interval where a group +-- matched inside a string, e.g. +-- +-- matching "reg(exp)" "a regexp" returns the pair (5,7) for the +-- (exp) group. (_PackedString indices start from 0) + +type GroupBounds = (Int, Int) + +re_compile_pattern + :: _PackedString -- pattern to compile + -> Bool -- True <=> assume single-line mode + -> Bool -- True <=> case-insensitive + -> PrimIO PatBuffer + +re_match :: PatBuffer -- compiled regexp + -> _PackedString -- string to match + -> Int -- start position + -> Bool -- True <=> record results in registers + -> PrimIO (Maybe REmatch) + +-- Matching on 2 strings is useful when you're dealing with multiple +-- buffers, which is something that could prove useful for +-- PackedStrings, as we don't want to stuff the contents of a file +-- into one massive heap chunk, but load (smaller chunks) on demand. + +re_match2 :: PatBuffer -- 2-string version + -> _PackedString + -> _PackedString + -> Int + -> Int + -> Bool + -> PrimIO (Maybe REmatch) + +re_search :: PatBuffer -- compiled regexp + -> _PackedString -- string to search + -> Int -- start index + -> Int -- stop index + -> Bool -- True <=> record results in registers + -> PrimIO (Maybe REmatch) + +re_search2 :: PatBuffer -- Double buffer search + -> _PackedString + -> _PackedString + -> Int -- start index + -> Int -- range (?) + -> Int -- stop index + -> Bool -- True <=> results in registers + -> PrimIO (Maybe REmatch) +\end{verbatim} + +The \tr{MatchPS} module provides Perl-like ``higher-level'' facilities +to operate on \tr{_PackedStrings}. The regular expressions in +question are in Perl syntax. The ``flags'' on various functions can +include: \tr{i} for case-insensitive, \tr{s} for single-line mode, and +\tr{g} for global. (It's probably worth your time to peruse the +source code...) + +\begin{verbatim} +matchPS :: _PackedString -- regexp + -> _PackedString -- string to match + -> [Char] -- flags + -> Maybe REmatch -- info about what matched and where + +searchPS :: _PackedString -- regexp + -> _PackedString -- string to match + -> [Char] -- flags + -> Maybe REmatch + +-- Perl-like match-and-substitute: +substPS :: _PackedString -- regexp + -> _PackedString -- replacement + -> [Char] -- flags + -> _PackedString -- string + -> _PackedString + +-- same as substPS, but no prefix and suffix: +replacePS :: _PackedString -- regexp + -> _PackedString -- replacement + -> [Char] -- flags + -> _PackedString -- string + -> _PackedString + +match2PS :: _PackedString -- regexp + -> _PackedString -- string1 to match + -> _PackedString -- string2 to match + -> [Char] -- flags + -> Maybe REmatch + +search2PS :: _PackedString -- regexp + -> _PackedString -- string to match + -> _PackedString -- string to match + -> [Char] -- flags + -> Maybe REmatch + +-- functions to pull the matched pieces out of an REmatch: + +getMatchesNo :: REmatch -> Int +getMatchedGroup :: REmatch -> Int -> _PackedString -> _PackedString +getWholeMatch :: REmatch -> _PackedString -> _PackedString +getLastMatch :: REmatch -> _PackedString -> _PackedString +getAfterMatch :: REmatch -> _PackedString -> _PackedString + +-- (reverse) brute-force string matching; +-- Perl equivalent is index/rindex: +findPS, rfindPS :: _PackedString -> _PackedString -> Maybe Int + +-- Equivalent to Perl "chop" (off the last character, if any): +chopPS :: _PackedString -> _PackedString + +-- matchPrefixPS: tries to match as much as possible of strA starting +-- from the beginning of strB (handy when matching fancy literals in +-- parsers): +matchPrefixPS :: _PackedString -> _PackedString -> Int +\end{verbatim} + +%************************************************************************ +%* * +\subsubsection[Socket]{Network-interface toolkit---@Socket@ and @SocketPrim@} +\index{SocketPrim interface (GHC syslib)} +\index{Socket interface (GHC syslib)} +\index{network-interface library} +\index{sockets library} +\index{BSD sockets library} +%* * +%************************************************************************ + +(Darren Moffat supplied the network-interface toolkit.) + +Your best bet for documentation is to look at the code---really!--- +normally in \tr{ghc/lib/ghc/{BSD,Socket,SocketPrim}.lhs}. + +The \tr{BSD} module provides functions to get at system-database info; +pretty straightforward if you're into this sort of thing: +\begin{verbatim} +getHostName :: IO String + +getServiceByName :: ServiceName -> IO ServiceEntry +getServicePortNumber:: ServiceName -> IO PortNumber +getServiceEntry :: IO ServiceEntry +setServiceEntry :: Bool -> IO () +endServiceEntry :: IO () + +getProtocolByName :: ProtocolName -> IO ProtocolEntry +getProtocolByNumber :: ProtocolNumber -> IO ProtcolEntry +getProtocolNumber :: ProtocolName -> ProtocolNumber +getProtocolEntry :: IO ProtocolEntry +setProtocolEntry :: Bool -> IO () +endProtocolEntry :: IO () + +getHostByName :: HostName -> IO HostEntry +getHostByAddr :: Family -> HostAddress -> IO HostEntry +getHostEntry :: IO HostEntry +setHostEntry :: Bool -> IO () +endHostEntry :: IO () +\end{verbatim} + +The \tr{SocketPrim} interface provides quite direct access to the +socket facilities in a BSD Unix system, including all the +complications. We hope you don't need to use it! See the source if +needed... + +The \tr{Socket} interface is a ``higher-level'' interface to sockets, +and it is what we recommend. Please tell us if the facilities it +offers are inadequate to your task! + +The interface is relatively modest: +\begin{verbatim} +connectTo :: Hostname -> PortID -> IO Handle +listenOn :: PortID -> IO Socket + +accept :: Socket -> IO (Handle, HostName) +sendTo :: Hostname -> PortID -> String -> IO () + +recvFrom :: Hostname -> PortID -> IO String +socketPort :: Socket -> IO PortID + +data PortID -- PortID is a non-abstract type + = Service String -- Service Name eg "ftp" + | PortNumber Int -- User defined Port Number + | UnixSocket String -- Unix family socket in file system + +type Hostname = String +\end{verbatim} + +Various examples of networking Haskell code are provided in +\tr{ghc/misc/examples/}, notably the \tr{net???/Main.hs} programs. + +%************************************************************************ +%* * +\subsection[HBC-library]{The HBC system library} +\index{HBC system library} +\index{system library, HBC} +%* * +%************************************************************************ + +This documentation is stolen directly from the HBC distribution. The +modules that GHC does not support (because they require HBC-specific +extensions) are omitted. + +\begin{description} +\item[\tr{Either}:] +\index{Either module (HBC library)}% +A binary sum data type: +\begin{verbatim} +data Either a b = Left a | Right b +\end{verbatim} +The constructor \tr{Left} is typically used for errors; it can be +renamed to \tr{Wrong} on import. + +\item[\tr{Maybe}:] +\index{Maybe module (HBC library)}% +A type for failure or success: +\begin{verbatim} +data Maybe a = Nothing | Just a +thenM :: Maybe a -> (a -> Maybe b) -> Maybe b + -- apply a function that may fail +\end{verbatim} + +\item[\tr{Option}:] +\index{Option module (HBC library)}% +An alias for \tr{Maybe}: +\begin{verbatim} +data Option a = None | Some a +thenO :: Option a -> (a -> Option b) -> Option b +\end{verbatim} + +\item[\tr{ListUtil}:] +\index{ListUtil module (HBC library)}% +Various useful functions involving lists that are missing from the +\tr{Prelude}: +\begin{verbatim} +assoc :: (Eq c) => (a -> b) -> b -> [(c, a)] -> c -> b + -- assoc f d l k looks for k in the association list l, if it + -- is found f is applied to the value, otherwise d is returned. +concatMap :: (a -> [b]) -> [a] -> [b] + -- flattening map (LML's concmap) +unfoldr :: (a -> (b, a)) -> (a -> Bool) -> a -> [b] + -- unfoldr f p x repeatedly applies f to x until (p x) holds. + -- (f x) should give a list element and a new x. +mapAccuml :: (a -> b -> (a, c)) -> a -> [b] -> (a, [c]) + -- mapAccuml f s l maps f over l, but also threads the state s + -- through (LML's mapstate). +union :: (Eq a) => [a] -> [a] -> [a] + -- union of two lists +intersection :: (Eq a) => [a] -> [a] -> [a] + -- intersection of two lists +chopList :: ([a] -> (b, [a])) -> [a] -> [b] + -- LMLs choplist +assocDef :: (Eq a) => [(a, b)] -> b -> a -> b + -- LMLs assocdef +lookup :: (Eq a) => [(a, b)] -> a -> Option b + -- lookup l k looks for the key k in the association list l + -- and returns an optional value +tails :: [a] -> [[a]] + -- return all the tails of a list +rept :: (Integral a) => a -> b -> [b] + -- repeat a value a number of times +groupEq :: (a->a->Bool) -> [a] -> [[a]] + -- group list elements according to an equality predicate +group :: (Eq a) => [a] -> [[a]] + -- group according to} == +readListLazily :: (Text a) => String -> [a] + -- read a list in a lazy fashion +\end{verbatim} + +\item[\tr{Pretty}:] +\index{Pretty module (HBC library)}% +John Hughes's pretty printing library. +\begin{verbatim} +type Context = (Bool, Int, Int, Int) +type IText = Context -> [String] +text :: String -> IText -- just text +(~.) :: IText -> IText -> IText -- horizontal composition +(^.) :: IText -> IText -> IText -- vertical composition +separate :: [IText] -> IText -- separate by spaces +nest :: Int -> IText -> IText -- indent +pretty :: Int -> Int -> IText -> String -- format it +\end{verbatim} + +\item[\tr{QSort}:] +\index{QSort module (HBC library)}% +A sort function using quicksort. +\begin{verbatim} +sortLe :: (a -> a -> Bool) -> [a] -> [a] + -- sort le l sorts l with le as less than predicate +sort :: (Ord a) => [a] -> [a] + -- sort l sorts l using the Ord class +\end{verbatim} + +\item[\tr{Random}:] +\index{Random module (HBC library)}% +Random numbers. +\begin{verbatim} +randomInts :: Int -> Int -> [Int] + -- given two seeds gives a list of random Int +randomDoubles :: Int -> Int -> [Double] + -- random Double with uniform distribution in (0,1) +normalRandomDoubles :: Int -> Int -> [Double] + -- random Double with normal distribution, mean 0, variance 1 +\end{verbatim} + +\item[\tr{Trace}:] +Simple tracing. (Note: This comes with GHC anyway.) +\begin{verbatim} +trace :: String -> a -> a -- trace x y prints x and returns y +\end{verbatim} + +\item[\tr{Miranda}:] +\index{Miranda module (HBC library)}% +Functions found in the Miranda library. +(Note: Miranda is a registered trade mark of Research Software Ltd.) + +\item[\tr{Word}:] +\index{Word module (HBC library)} +Bit manipulation. (GHC doesn't implement absolutely all of this. +And don't count on @Word@ being 32 bits on a Alpha...) +\begin{verbatim} +class Bits a where + bitAnd :: a -> a -> a -- bitwise and + bitOr :: a -> a -> a -- bitwise or + bitXor :: a -> a -> a -- bitwise xor + bitCompl :: a -> a -- bitwise negation + bitRsh :: a -> Int -> a -- bitwise right shift + bitLsh :: a -> Int -> a -- bitwise left shift + bitSwap :: a -> a -- swap word halves + bit0 :: a -- word with least significant bit set + bitSize :: a -> Int -- number of bits in a word + +data Byte -- 8 bit quantity +data Short -- 16 bit quantity +data Word -- 32 bit quantity + +instance Bits Byte, Bits Short, Bits Word +instance Eq Byte, Eq Short, Eq Word +instance Ord Byte, Ord Short, Ord Word +instance Text Byte, Text Short, Text Word +instance Num Byte, Num Short, Num Word +wordToShorts :: Word -> [Short] -- convert a Word to two Short +wordToBytes :: Word -> [Byte] -- convert a Word to four Byte +bytesToString :: [Byte] -> String -- convert a list of Byte to a String (bit by bit) +wordToInt :: Word -> Int -- convert a Word to Int +shortToInt :: Short -> Int -- convert a Short to Int +byteToInt :: Byte -> Int -- convert a Byte to Int +\end{verbatim} + +\item[\tr{Time}:] +\index{Time module (HBC library)}% +Manipulate time values (a Double with seconds since 1970). +\begin{verbatim} +-- year mon day hour min sec dec-sec weekday +data Time = Time Int Int Int Int Int Int Double Int +dblToTime :: Double -> Time -- convert a Double to a Time +timeToDbl :: Time -> Double -- convert a Time to a Double +timeToString :: Time -> String -- convert a Time to a readable String +\end{verbatim} + +\item[\tr{Hash}:] +\index{Hash module (HBC library)}% +Hashing functions. +\begin{verbatim} +class Hashable a where + hash :: a -> Int -- hash a value, return an Int +-- instances for all Prelude types +hashToMax :: (Hashable a) => Int -> a -> Int -- hash into interval [0..x-1] +\end{verbatim} + +\item[\tr{NameSupply}:] +\index{NameSupply module (HBC library)}% +Functions to generate unique names (Int). +\begin{verbatim} +type Name = Int +initialNameSupply :: NameSupply + -- The initial name supply (may be different every + -- time the program is run. +splitNameSupply :: NameSupply -> (NameSupply,NameSupply) + -- split the namesupply into two +getName :: NameSupply -> Name + -- get the name associated with a name supply +\end{verbatim} + +\item[\tr{Parse}:] +\index{Parse module (HBC library)}% +Higher order functions to build parsers. With a little care these +combinators can be used to build efficient parsers with good error +messages. +\begin{verbatim} +infixr 8 +.+ , ..+ , +.. +infix 6 `act` , >>> , `into` , .> +infixr 4 ||| , ||! , |!! +data ParseResult a b +type Parser a b = a -> Int -> ParseResult a b +(|||) :: Parser a b -> Parser a b -> Parser a b + -- Alternative +(||!) :: Parser a b -> Parser a b -> Parser a b + -- Alternative, but with committed choice +(|!!) :: Parser a b -> Parser a b -> Parser a b + -- Alternative, but with committed choice +(+.+) :: Parser a b -> Parser a c -> Parser a (b,c) + -- Sequence +(..+) :: Parser a b -> Parser a c -> Parser a c + -- Sequence, throw away first part +(+..) :: Parser a b -> Parser a c -> Parser a b + -- Sequence, throw away second part +act :: Parser a b -> (b->c) -> Parser a c + -- Action +(>>>) :: Parser a (b,c) -> (b->c->d) -> Parser a d + -- Action on two items +(.>) :: Parser a b -> c -> Parse a c + -- Action ignoring value +into :: Parser a b -> (b -> Parser a c) -> Parser a c + -- Use a produced value in a parser. +succeed b :: Parser a b + -- Always succeeds without consuming a token +failP :: Parser a b + -- Always fails. +many :: Parser a b -> Parser a [b] + -- Kleene star +many1 :: Parser a b -> Parser a [b] + -- Kleene plus +count :: Parser a b -> Int -> Parser a [b] + -- Parse an exact number of items +sepBy1 :: Parser a b -> Parser a c -> Parser a [b] + -- Non-empty sequence of items separated by something +sepBy :: Parser a b -> Parser a c -> Parser a [b] + -- Sequence of items separated by something +lit :: (Eq a, Text a) => a -> Parser [a] a + -- Recognise a literal token from a list of tokens +litp :: String -> (a->Bool) -> Parser [a] a + -- Recognise a token with a predicate. + -- The string is a description for error messages. +testp :: String -> (a -> Bool) -> (Parser b a) -> Parser b a + -- Test a semantic value. +token :: (a -> Either String (b, a)) -> Parser a b + -- General token recogniser. +parse :: Parser a b -> a -> Either ([String], a) [(b, a)] + -- Do a parse. Return either error (possible tokens and rest + -- of tokens) or all possible parses. +sParse :: (Text a) => (Parser [a] b) -> [a] -> Either String b + -- Simple parse. Return error message or result. +\end{verbatim} + +%%%simpleLex :: String -> [String] -- A simple (but useful) lexical analyzer + +\item[\tr{Native}:] +\index{Native module (HBC library)}% +Functions to convert the primitive types \tr{Int}, \tr{Float}, and \tr{Double} to +their native representation as a list of bytes (\tr{Char}). If such a list +is read/written to a file it will have the same format as when, e.g., +C read/writes the same kind of data. +\begin{verbatim} +type Bytes = [Char] -- A byte stream is just a list of characters + +class Native a where + showBytes :: a -> Bytes -> Bytes + -- prepend the representation of an item the a byte stream + listShowBytes :: [a] -> Bytes -> Bytes + -- prepend the representation of a list of items to a stream + -- (may be more efficient than repeating showBytes). + readBytes :: Bytes -> Maybe (a, Bytes) + -- get an item from the stream and return the rest, + -- or fail if the stream is to short. + listReadBytes :: Int -> Bytes -> Maybe ([a], Bytes) + -- read n items from a stream. + +instance Native Int +instance Native Float +instance Native Double +instance (Native a, Native b) => Native (a,b) + -- juxtaposition of the two items +instance (Native a, Native b, Native c) => Native (a, b, c) + -- juxtaposition of the three items +instance (Native a) => Native [a] + -- an item count in an Int followed by the items + +shortIntToBytes :: Int -> Bytes -> Bytes + -- Convert an Int to what corresponds to a short in C. +bytesToShortInt :: Bytes -> Maybe (Int, Bytes) + -- Get a short from a byte stream and convert to an Int. + +showB :: (Native a) => a -> Bytes -- Simple interface to showBytes. +readB :: (Native a) => Bytes -> a -- Simple interface to readBytes. +\end{verbatim} + +\item[\tr{Number}:] +\index{Number module (HBC library)}% +Simple numbers that belong to all numeric classes and behave like +a naive user would expect (except that printing is still ugly). +(NB: GHC does not provide a magic way to use \tr{Numbers} everywhere, +but you should be able to do it with normal \tr{import}ing and +\tr{default}ing.) +\begin{verbatim} +data Number -- The type itself. +instance ... -- All reasonable instances. +isInteger :: Number -> Bool -- Test if a Number is an integer. +\end{verbatim} +\end{description} diff --git a/ghc/docs/users_guide/parallel.lit b/ghc/docs/users_guide/parallel.lit new file mode 100644 index 0000000000..335e8febcf --- /dev/null +++ b/ghc/docs/users_guide/parallel.lit @@ -0,0 +1,662 @@ +% both concurrent and parallel +%************************************************************************ +%* * +\section[concurrent-and-parallel]{Concurrent and Parallel Haskell} +\index{Concurrent Haskell} +\index{Parallel Haskell} +%* * +%************************************************************************ + +Concurrent and Parallel Haskell are Glasgow extensions to Haskell +which let you structure your program as a group of independent +`threads'. + +Concurrent and Parallel Haskell have very different purposes. + +Concurrent Haskell is for applications which have an inherent +structure of interacting, concurrent tasks (i.e. `threads'). Threads +in such programs may be {\em required}. For example, if a concurrent +thread has been spawned to handle a mouse click, it isn't +optional---the user wants something done! + +A Concurrent Haskell program implies multiple `threads' running within +a single Unix process on a single processor. + +Simon Peyton Jones and Sigbjorn Finne have a paper available, +``Concurrent Haskell: preliminary version.'' +(draft available via \tr{ftp} +from \tr{ftp.dcs.gla.ac.uk/pub/glasgow-fp/drafts}). + +Parallel Haskell is about {\em speed}---spawning threads onto multiple +processors so that your program will run faster. The `threads' +are always {\em advisory}---if the runtime system thinks it can +get the job done more quickly by sequential execution, then fine. + +A Parallel Haskell program implies multiple processes running on +multiple processors, under a PVM (Parallel Virtual Machine) framework. + +Parallel Haskell is new with GHC 0.26; it is more about ``research +fun'' than about ``speed.'' That will change. There is no paper about +Parallel Haskell. That will change, too. + +Some details about Concurrent and Parallel Haskell follow. + +%************************************************************************ +%* * +\subsection{Concurrent and Parallel Haskell---language features} +\index{Concurrent Haskell---features} +\index{Parallel Haskell---features} +%* * +%************************************************************************ + +%************************************************************************ +%* * +\subsubsection{Features specific to Concurrent Haskell} +%* * +%************************************************************************ + +%************************************************************************ +%* * +\subsubsubsection{The \tr{Concurrent} interface (recommended)} +\index{Concurrent interface} +%* * +%************************************************************************ + +GHC provides a \tr{Concurrent} module, a common interface to a +collection of useful concurrency abstractions, including those +mentioned in the ``concurrent paper''. + +Just put \tr{import Concurrent} into your modules, and away you go. +NB: intended for use with the \tr{-fhaskell-1.3} flag. + +To create a ``required thread'': + +\begin{verbatim} +forkIO :: IO a -> IO a +\end{verbatim} + +The \tr{Concurrent} interface also provides access to ``I-Vars'' +and ``M-Vars'', which are two flavours of {\em synchronising variables}. +\index{synchronising variables (Glasgow extension)} +\index{concurrency -- synchronising variables} + +\tr{_IVars}\index{_IVars (Glasgow extension)} are write-once +variables. They start out empty, and any threads that attempt to read +them will block until they are filled. Once they are written, any +blocked threads are freed, and additional reads are permitted. +Attempting to write a value to a full \tr{_IVar} results in a runtime +error. Interface: +\begin{verbatim} +type IVar a = _IVar a -- more convenient name + +newIVar :: IO (_IVar a) +readIVar :: _IVar a -> IO a +writeIVar :: _IVar a -> a -> IO () +\end{verbatim} + +\tr{_MVars}\index{_MVars (Glasgow extension)} are rendezvous points, +mostly for concurrent threads. They begin empty, and any attempt to +read an empty \tr{_MVar} blocks. When an \tr{_MVar} is written, a +single blocked thread may be freed. Reading an \tr{_MVar} toggles its +state from full back to empty. Therefore, any value written to an +\tr{_MVar} may only be read once. Multiple reads and writes are +allowed, but there must be at least one read between any two +writes. Interface: +\begin{verbatim} +type MVar a = _MVar a -- more convenient name + +newEmptyMVar :: IO (_MVar a) +newMVar :: a -> IO (_MVar a) +takeMVar :: _MVar a -> IO a +putMVar :: _MVar a -> a -> IO () +readMVar :: _MVar a -> IO a +swapMVar :: _MVar a -> a -> IO a +\end{verbatim} + +A {\em channel variable} (@CVar@) is a one-element channel, as +described in the paper: + +\begin{verbatim} +data CVar a +newCVar :: IO (CVar a) +putCVar :: CVar a -> a -> IO () +getCVar :: CVar a -> IO a +\end{verbatim} + +A @Channel@ is an unbounded channel: + +\begin{verbatim} +data Chan a +newChan :: IO (Chan a) +putChan :: Chan a -> a -> IO () +getChan :: Chan a -> IO a +dupChan :: Chan a -> IO (Chan a) +unGetChan :: Chan a -> a -> IO () +getChanContents :: Chan a -> IO [a] +\end{verbatim} + +General and quantity semaphores: + +\begin{verbatim} +data QSem +newQSem :: Int -> IO QSem +waitQSem :: QSem -> IO () +signalQSem :: QSem -> IO () + +data QSemN +newQSemN :: Int -> IO QSemN +signalQSemN :: QSemN -> Int -> IO () +waitQSemN :: QSemN -> Int -> IO () +\end{verbatim} + +Merging streams---binary and n-ary: + +\begin{verbatim} +mergeIO :: [a] -> [a] -> IO [a] +nmergeIO :: [[a]] -> IO [a] +\end{verbatim} + +A {\em Sample variable} (@SampleVar@) is slightly different from a +normal @_MVar@: +\begin{itemize} +\item Reading an empty @SampleVar@ causes the reader to block + (same as @takeMVar@ on empty @_MVar@). +\item Reading a filled @SampleVar@ empties it and returns value. + (same as @takeMVar@) +\item Writing to an empty @SampleVar@ fills it with a value, and +potentially, wakes up a blocked reader (same as for @putMVar@ on empty @_MVar@). +\item Writing to a filled @SampleVar@ overwrites the current value. + (different from @putMVar@ on full @_MVar@.) +\end{itemize} + +\begin{verbatim} +type SampleVar a = _MVar (Int, _MVar a) + +emptySampleVar :: SampleVar a -> IO () +newSampleVar :: IO (SampleVar a) +readSample :: SampleVar a -> IO a +writeSample :: SampleVar a -> a -> IO () +\end{verbatim} + +Finally, there are operations to delay a concurrent thread, and to +make one wait:\index{delay a concurrent thread} +\index{wait for a file descriptor} +\begin{verbatim} +threadDelay :: Int -> IO () -- delay rescheduling for N microseconds +threadWait :: Int -> IO () -- wait for input on specified file descriptor +\end{verbatim} + +%************************************************************************ +%* * +\subsubsection{Features specific to Parallel Haskell} +%* * +%************************************************************************ + +%************************************************************************ +%* * +\subsubsubsection{The \tr{Parallel} interface (recommended)} +\index{Parallel interface} +%* * +%************************************************************************ + +GHC provides two functions for controlling parallel execution, through +the \tr{Parallel} interface: +\begin{verbatim} +interface Parallel where +infixr 0 `par` +infixr 1 `seq` + +par :: a -> b -> b +seq :: a -> b -> b +\end{verbatim} + +The expression \tr{(x `par` y)} {\em sparks} the evaluation of \tr{x} +(to weak head normal form) and returns \tr{y}. Sparks are queued for +execution in FIFO order, but are not executed immediately. At the +next heap allocation, the currently executing thread will yield +control to the scheduler, and the scheduler will start a new thread +(until reaching the active thread limit) for each spark which has not +already been evaluated to WHNF. + +The expression \tr{(x `seq` y)} evaluates \tr{x} to weak head normal +form and then returns \tr{y}. The \tr{seq} primitive can be used to +force evaluation of an expression beyond WHNF, or to impose a desired +execution sequence for the evaluation of an expression. + +For example, consider the following parallel version of our old +nemesis, \tr{nfib}: + +\begin{verbatim} +import Parallel + +nfib :: Int -> Int +nfib n | n <= 1 = 1 + | otherwise = par n1 (seq n2 (n1 + n2 + 1)) + where n1 = nfib (n-1) + n2 = nfib (n-2) +\end{verbatim} + +For values of \tr{n} greater than 1, we use \tr{par} to spark a thread +to evaluate \tr{nfib (n-1)}, and then we use \tr{seq} to force the +parent thread to evaluate \tr{nfib (n-2)} before going on to add +together these two subexpressions. In this divide-and-conquer +approach, we only spark a new thread for one branch of the computation +(leaving the parent to evaluate the other branch). Also, we must use +\tr{seq} to ensure that the parent will evaluate \tr{n2} {\em before} +\tr{n1} in the expression \tr{(n1 + n2 + 1)}. It is not sufficient to +reorder the expression as \tr{(n2 + n1 + 1)}, because the compiler may +not generate code to evaluate the addends from left to right. + +%************************************************************************ +%* * +\subsubsubsection{Underlying functions and primitives} +\index{parallelism primitives} +\index{primitives for parallelism} +%* * +%************************************************************************ + +The functions \tr{par} and \tr{seq} are really just renamings: +\begin{verbatim} +par a b = _par_ a b +seq a b = _seq_ a b +\end{verbatim} + +The functions \tr{_par_} and \tr{_seq_} are built into GHC, and unfold +into uses of the \tr{par#} and \tr{seq#} primitives, respectively. If +you'd like to see this with your very own eyes, just run GHC with the +\tr{-ddump-simpl} option. (Anything for a good time...) + +You can use \tr{_par_} and \tr{_seq_} in Concurrent Haskell, though +I'm not sure why you would want to. + +%************************************************************************ +%* * +\subsubsection{Features common to Concurrent and Parallel Haskell} +%* * +%************************************************************************ + +Actually, you can use the \tr{`par`} and \tr{`seq`} combinators +(really for Parallel Haskell) in Concurrent Haskell as well. +But doing things like ``\tr{par} to \tr{forkIO} many required threads'' +counts as ``jumping out the 9th-floor window, just to see what happens.'' + +%************************************************************************ +%* * +\subsubsubsection{Scheduling policy for concurrent/parallel threads} +\index{Scheduling---concurrent/parallel} +\index{Concurrent/parallel scheduling} +%* * +%************************************************************************ + +Runnable threads are scheduled in round-robin fashion. Context +switches are signalled by the generation of new sparks or by the +expiry of a virtual timer (the timer interval is configurable with the +\tr{-C[<num>]}\index{-C<num> RTS option (concurrent, parallel)} RTS option). +However, a context switch doesn't really happen until the next heap +allocation. If you want extremely short time slices, the \tr{-C} RTS +option can be used to force a context switch at each and every heap +allocation. + +When a context switch occurs, pending sparks which have not already +been reduced to weak head normal form are turned into new threads. +However, there is a limit to the number of active threads (runnable or +blocked) which are allowed at any given time. This limit can be +adjusted with the \tr{-t<num>}\index{-t <num> RTS option (concurrent, parallel)} +RTS option (the default is 32). Once the +thread limit is reached, any remaining sparks are deferred until some +of the currently active threads are completed. + +%************************************************************************ +%* * +\subsection{How to use Concurrent and Parallel Haskell} +%* * +%************************************************************************ + +[You won't get far unless your GHC system was configured/built with +concurrency and/or parallelism enabled. (They require separate +library modules.) The relevant section of the installation guide says +how to do this.] + +%************************************************************************ +%* * +\subsubsection{Using Concurrent Haskell} +\index{Concurrent Haskell---use} +%* * +%************************************************************************ + +To compile a program as Concurrent Haskell, use the \tr{-concurrent} +option,\index{-concurrent option} both when compiling {\em and +linking}. You will probably need the \tr{-fglasgow-exts} option, too. + +Three RTS options are provided for modifying the behaviour of the +threaded runtime system. See the descriptions of \tr{-C[<us>]}, \tr{-q}, +and \tr{-t<num>} in \Sectionref{parallel-rts-opts}. + +%************************************************************************ +%* * +\subsubsubsection[concurrent-problems]{Potential problems with Concurrent Haskell} +\index{Concurrent Haskell problems} +\index{problems, Concurrent Haskell} +%* * +%************************************************************************ + +The main thread in a Concurrent Haskell program is given its own +private stack space, but all other threads are given stack space from +the heap. Stack space for the main thread can be +adjusted as usual with the \tr{-K} RTS +option,\index{-K RTS option (concurrent, parallel)} but if this +private stack space is exhausted, the main thread will switch to stack +segments in the heap, just like any other thread. Thus, problems +which would normally result in stack overflow in ``sequential Haskell'' +can be expected to result in heap overflow when using threads. + +The concurrent runtime system uses black holes as synchronisation +points for subexpressions which are shared among multiple threads. In +``sequential Haskell'', a black hole indicates a cyclic data +dependency, which is a fatal error. However, in concurrent execution, a +black hole may simply indicate that the desired expression is being +evaluated by another thread. Therefore, when a thread encounters a +black hole, it simply blocks and waits for the black hole to be +updated. Cyclic data dependencies will result in deadlock, and the +program will fail to terminate. + +Because the concurrent runtime system uses black holes as +synchronisation points, it is not possible to disable black-holing +with the \tr{-N} RTS option.\index{-N RTS option} Therefore, the use +of signal handlers (including timeouts) with the concurrent runtime +system can lead to problems if a thread attempts to enter a black hole +that was created by an abandoned computation. The use of signal +handlers in conjunction with threads is strongly discouraged. + + +%************************************************************************ +%* * +\subsubsection{Using Parallel Haskell} +\index{Parallel Haskell---use} +%* * +%************************************************************************ + +[You won't be able to execute parallel Haskell programs unless PVM3 +(Parallel Virtual Machine, version 3) is installed at your site.] + +To compile a Haskell program for parallel execution under PVM, use the +\tr{-parallel} option,\index{-parallel option} both when compiling +{\em and linking}. You will probably want to \tr{import Parallel} +into your Haskell modules. + +To run your parallel program, once PVM is going, just invoke it ``as +normal''. The main extra RTS option is \tr{-N<n>}, to say how many +PVM ``processors'' your program to run on. (For more details of +all relevant RTS options, please see \sectionref{parallel-rts-opts}.) + +In truth, running Parallel Haskell programs and getting information +out of them (e.g., activity profiles) is a battle with the vagaries of +PVM, detailed in the following sections. + +For example: the stdout and stderr from your parallel program run will +appear in a log file, called something like \tr{/tmp/pvml.NNN}. + +%************************************************************************ +%* * +\subsubsubsection{Dummy's guide to using PVM} +\index{PVM, how to use} +\index{Parallel Haskell---PVM use} +%* * +%************************************************************************ + +Before you can run a parallel program under PVM, you must set the +required environment variables (PVM's idea, not ours); something like, +probably in your \tr{.cshrc} or equivalent: +\begin{verbatim} +setenv PVM_ROOT /wherever/you/put/it +setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch` +setenv PVM_DPATH $PVM_ROOT/lib/pvmd +\end{verbatim} + +Creating and/or controlling your ``parallel machine'' is a purely-PVM +business; nothing specific to Parallel Haskell. + +You use the \tr{pvm}\index{pvm command} command to start PVM on your +machine. You can then do various things to control/monitor your +``parallel machine;'' the most useful being: + +\begin{tabular}{ll} +\tr{Control-D} & exit \tr{pvm}, leaving it running \\ +\tr{halt} & kill off this ``parallel machine'' \& exit \\ +\tr{add <host>} & add \tr{<host>} as a processor \\ +\tr{delete <host>} & delete \tr{<host>} \\ +\tr{reset} & kill what's going, but leave PVM up \\ +\tr{conf} & list the current configuration \\ +\tr{ps} & report processes' status \\ +\tr{pstat <pid>} & status of a particular process \\ +\end{tabular} + +The PVM documentation can tell you much, much more about \tr{pvm}! + +%************************************************************************ +%* * +\subsubsection{Parallelism profiles} +\index{parallelism profiles} +\index{profiles, parallelism} +\index{visualisation tools} +%* * +%************************************************************************ + +With Parallel Haskell programs, we usually don't care about the +results---only with ``how parallel'' it was! We want pretty pictures. + +Parallelism profiles (\`a la \tr{hbcpp}) can be generated with the +\tr{-q}\index{-q RTS option (concurrent, parallel)} RTS option. The +per-processor profiling info is dumped into files {\em in your home +directory} named \tr{<program>.gr}. These are then munged into a +PostScript picture, which you can then display. For example, +to run your program \tr{a.out} on 8 processors, then view the +parallelism profile, do: + +\begin{verbatim} +% ./a.out +RTS -N8 -q +% cd # to home directory +% grs2gr *.???.gr # combine the 8 .gr files into one +% gr2ps -O temp.gr # cvt to .ps; output in temp.ps +% ghostview -seascape temp.ps # look at it! +\end{verbatim} + +The scripts for processing the parallelism profiles are distributed +in \tr{ghc/utils/parallel/}. + +%************************************************************************ +%* * +\subsubsection{Activity profiles} +\index{activity profiles} +\index{profiles, activity} +\index{visualisation tools} +%* * +%************************************************************************ + +You can also use the standard GHC ``cost-centre'' profiling to see how +much time each PVM ``processor'' spends + +No special compilation flags beyond \tr{-parallel} are required to get +this basic four-activity profile. Just use the \tr{-P} RTS option, +thusly: +\begin{verbatim} +./a.out +RTS -N7 -P # 7 processors +\end{verbatim} + +The above will create files named \tr{<something>.prof} and/or +\tr{<something>.time} {\em in your home directory}. You can +process the \tr{.time} files into PostScript using \tr{hp2ps}, +\index{hp2ps} +as described elsewhere in this guide. The only thing is: +because of the weird file names, you probably need to use +\tr{hp2ps} as a filter; so: +\begin{verbatim} +% hp2ps < fooo.001.time > temp.ps +\end{verbatim} + +%$$ The first line of the +%$$ \tr{.qp} file contains the name of the program executed, along with +%$$ any program arguments and thread-specific RTS options. The second +%$$ line contains the date and time of program execution. The third +%$$ and subsequent lines contain information about thread state transitions. +%$$ +%$$ The thread state transition lines have the following format: +%$$ \begin{verbatim} +%$$ time transition thread-id thread-name [thread-id thread-name] +%$$ \end{verbatim} +%$$ +%$$ The \tr{time} is the virtual time elapsed since the program started +%$$ execution, in milliseconds. The \tr{transition} is a two-letter code +%$$ indicating the ``from'' queue and the ``to'' queue, where each queue +%$$ is one of: +%$$ \begin{itemize} +%$$ \item[\tr{*}] Void: Thread creation or termination. +%$$ \item[\tr{G}] Green: Runnable (or actively running, with \tr{-qv}) threads. +%$$ \item[\tr{A}] Amber: Runnable threads (\tr{-qv} only). +%$$ \item[\tr{R}] Red: Blocked threads. +%$$ \end{itemize} +%$$ The \tr{thread-id} is a unique integer assigned to each thread. The +%$$ \tr{thread-name} is currently the address of the thread's root closure +%$$ (in hexadecimal). In the future, it will be the name of the function +%$$ associated with the root of the thread. +%$$ +%$$ The first \tr{(thread-id, thread-name)} pair identifies the thread +%$$ involved in the indicated transition. For \tr{RG} and \tr{RA} transitions +%$$ only, there is a second \tr{(thread-id, thread-name)} pair which identifies +%$$ the thread that released the blocked thread. +%$$ +%$$ Provided with the GHC distribution is a perl script, \tr{qp2pp}, which +%$$ will convert \tr{.qp} files to \tr{hbcpp}'s \tr{.pp} format, so that +%$$ you can use the \tr{hbcpp} profiling tools, such as \tr{pp2ps92}. The +%$$ \tr{.pp} format has undergone many changes, so the conversion script +%$$ is not compatible with earlier releases of \tr{hbcpp}. Note that GHC +%$$ and \tr{hbcpp} use different thread scheduling policies (in +%$$ particular, \tr{hbcpp} threads never move from the green queue to the +%$$ amber queue). For compatibility, the \tr{qp2pp} script eliminates the +%$$ GHC amber queue, so there is no point in using the verbose (\tr{-qv}) +%$$ option if you are only interested in using the \tr{hbcpp} profiling +%$$ tools. + +%************************************************************************ +%* * +\subsubsection[parallel-rts-opts]{RTS options for Concurrent/Parallel Haskell} +\index{RTS options, concurrent} +\index{RTS options, parallel} +\index{Concurrent Haskell---RTS options} +\index{Parallel Haskell---RTS options} +%* * +%************************************************************************ + +Besides the usual runtime system (RTS) options +(\sectionref{runtime-control}), there are a few options particularly +for concurrent/parallel execution. + +\begin{description} +\item[\tr{-N<N>}:] +\index{-N<N> RTS option (parallel)} +(PARALLEL ONLY) Use \tr{<N>} PVM processors to run this program; +the default is 2. + +\item[\tr{-C[<us>]}:] +\index{-C<us> RTS option} +Sets the context switch interval to \pl{<us>} microseconds. A context +switch will occur at the next heap allocation after the timer expires. +With \tr{-C0} or \tr{-C}, context switches will occur as often as +possible (at every heap allocation). By default, context switches +occur every 10 milliseconds. Note that many interval timers are only +capable of 10 millisecond granularity, so the default setting may be +the finest granularity possible, short of a context switch at every +heap allocation. + +\item[\tr{-q[v]}:] +\index{-q RTS option} +Produce a quasi-parallel profile of thread activity, in the file +\tr{<program>.qp}. In the style of \tr{hbcpp}, this profile records +the movement of threads between the green (runnable) and red (blocked) +queues. If you specify the verbose suboption (\tr{-qv}), the green +queue is split into green (for the currently running thread only) and +amber (for other runnable threads). We do not recommend that you use +the verbose suboption if you are planning to use the \tr{hbcpp} +profiling tools or if you are context switching at every heap check +(with \tr{-C}). + +\item[\tr{-t<num>}:] +\index{-t<num> RTS option} +Limit the number of concurrent threads per processor to \pl{<num>}. +The default is 32. Each thread requires slightly over 1K {\em words} +in the heap for thread state and stack objects. (For 32-bit machines, +this translates to 4K bytes, and for 64-bit machines, 8K bytes.) + +\item[\tr{-d}:] +\index{-d RTS option (parallel)} +(PARALLEL ONLY) Turn on debugging. It pops up one xterm (or GDB, or +something...) per PVM processor. We use the standard \tr{debugger} +script that comes with PVM3, but we sometimes meddle with the +\tr{debugger2} script. We include ours in the GHC distribution, +in \tr{ghc/utils/pvm/}. +\end{description} + +%************************************************************************ +%* * +\subsubsubsection[parallel-problems]{Potential problems with Parallel Haskell} +\index{Parallel Haskell---problems} +\index{problems, Parallel Haskell} +%* * +%************************************************************************ + +The ``Potential problems'' for Concurrent Haskell also apply for +Parallel Haskell. Please see \Sectionref{concurrent-problems}. + +%$$ \subsubsubsection[par-notes]{notes for 0.26} +%$$ +%$$ \begin{verbatim} +%$$ Install PVM somewhere, as it says. We use 3.3 +%$$ +%$$ pvm.h : can do w/ a link from ghc/includes to its true home (???) +%$$ +%$$ +%$$ ghc -gum ... => a.out +%$$ +%$$ a.out goes to $PVM_ROOT/bin/$PVM_ARCH/$PE +%$$ +%$$ (profiling outputs go to ~/$PE.<process-num>.<suffix>) +%$$ +%$$ trinder scripts in: ~trinder/bin/any/instPHIL +%$$ +%$$ To run: +%$$ +%$$ Then: +%$$ SysMan [-] N (PEs) args-to-program... +%$$ +%$$ - ==> debug mode +%$$ mattson setup: GDB window per task +%$$ /local/grasp_tmp5/mattson/pvm3/lib/debugger{,2} +%$$ +%$$ to set breakpoint, etc, before "run", just modify debugger2 +%$$ +%$$ stderr and stdout are directed to /tmp/pvml.NNN +%$$ +%$$ Visualisation stuff (normal _mp build): +%$$ +%$$ +RTS -q gransim-like profiling +%$$ (should use exactly-gransim RTS options) +%$$ -qb binary dumps : not tried, not recommended: hosed! +%$$ +%$$ ascii dump : same info as gransim, one extra line at top w/ +%$$ start time; all times are ms since then +%$$ +%$$ dumps appear in $HOME/<program>.nnn.gr +%$$ +%$$ ~mattson/grs2gr.pl == combine lots into one (fixing times) +%$$ +%$$ /local/grasp/hwloidl/GrAn/bin/ is where scripts are. +%$$ +%$$ gr2ps == activity profile (bash script) +%$$ +%$$ ~mattson/bin/`arch`/gr2qp must be picked up prior to hwloidl's for +%$$ things to work... +%$$ +%$$ +RTS -[Pp] (parallel) 4-cost-centre "profiling" (gc,MAIN,msg,idle) +%$$ +%$$ ToDos: time-profiles from hp2ps: something about zeroth sample; +%$$ \end{verbatim} diff --git a/ghc/docs/users_guide/prof-compiler-options.lit b/ghc/docs/users_guide/prof-compiler-options.lit new file mode 100644 index 0000000000..21d8ca6965 --- /dev/null +++ b/ghc/docs/users_guide/prof-compiler-options.lit @@ -0,0 +1,84 @@ +% +% Included by prof-options.lit and how_to_run.lit +% + +To make use of the cost centre profiling system {\em all} modules must +be compiled and linked with the \tr{-prof} option.\index{-prof option} +Any \tr{_scc_} constructs you've put in your source will spring to life. + +Without a \tr{-prof} option, your \tr{_scc_}s are ignored; so you can +compiled \tr{_scc_}-laden code without changing it. + +There are a few other profiling-related compilation options. Use them +{\em in addition to} \tr{-prof}. These do not have to be used +consistently for all modules in a program. + +\begin{description} +\item[\tr{-auto}:] +\index{-auto option} +GHC will automatically add \tr{_scc_} constructs for +all top-level, exported functions. + +\item[\tr{-auto-all}:] +\index{-auto-all option} +{\em All} top-level functions, exported or not, will be automatically +\tr{_scc_}'d. + +% secret! +%\item[\tr{-caf-all}:] +%\index{-caf-all option} +%The costs of all CAFs in a module are usually attributed to one +%``big'' CAF cost-centre. With this option, all CAFs get their own cost-centre. + +%\item[\tr{-dict-all}:] +%\index{-dict-all option} +%Similarly, this option means that all ``dictionaries'' (internal +%constructs to support Haskell overloading) should get their own +%cost-centre. (Again, the costs are usually attributed to one ``big'' +%DICT cost-centre.) +% +%Incidentally, something is probably Bad Wrong (i.e., a GHC bug) if you +%see big costs attributed to dictionaries. + +\item[\tr{-ignore-scc}:] +\index{-ignore-scc option} +Ignore any \tr{_scc_} constructs, +so a module which already has \tr{_scc_}s can be +compiled for profiling with the annotations ignored. + +\item[\tr{-G<group>}:] +\index{-G<group> option} +Specifies the \pl{<group>} to be attached to all the cost-centres +declared in the module. If no group is specified it defaults to the +module name. +\end{description} + +%Alternative profiling semantics have also been implemented. To use +%these the runtime system and prelude libraries must have been built +%for the alternative profiling setup. This is done using a particular +%UserWay setup. If your system has this been built for this profiling +%system the alternative profiling system will normally be invoked using +%the options: +%\begin{description} +%\item[\tr{-lex}:] +%\index{-eval option} +%for lexical profiling. +%\item[\tr{-eval}:] +%\index{-eval option} +%for evaluation profiling. +%\end{description} +%All modules must be consistently compiled with the \tr{-lex} or +%\tr{-eval} option instead of the \tr{-prof} option. The other +%profiling options are still applicable. +% +%Finally we note that the options which dump the program source during +%compilation may be useful to determine exactly what code is being +%profiled. Useful options are: +%\begin{description} +%\item[\tr{-ddump-ds}:] dump after desugaring. Any automatic \tr{_scc_} +%annotations will have been added. +%\item[\tr{-ddump-simpl}:] dump after simplification. +%\item[\tr{-ddump-stg}:] dump the STG-code immediately before code +%generation. +%\end{description} + diff --git a/ghc/docs/users_guide/prof-options.lit b/ghc/docs/users_guide/prof-options.lit new file mode 100644 index 0000000000..afee1b901c --- /dev/null +++ b/ghc/docs/users_guide/prof-options.lit @@ -0,0 +1,30 @@ +%************************************************************************ +%* * +\subsection[prof-compiler-options]{Compiling programs for profiling} +\index{profiling options} +\index{options, for profiling} +%* * +%************************************************************************ + +\input{prof-compiler-options.lit} + +%************************************************************************ +%* * +\subsection[prof-rts-options]{Controlling the profiler at runtime} +\index{profiling RTS options} +\index{RTS options, for profiling} +%* * +%************************************************************************ + +\input{prof-rts-options.lit} + +%************************************************************************ +%* * +\subsection[prof-graphs]{Producing graphical heap profiles} +\index{heap profiles, producing} +%* * +%************************************************************************ + +\input{prof-post-processors.lit} + + diff --git a/ghc/docs/users_guide/prof-post-processors.lit b/ghc/docs/users_guide/prof-post-processors.lit new file mode 100644 index 0000000000..c704d2909b --- /dev/null +++ b/ghc/docs/users_guide/prof-post-processors.lit @@ -0,0 +1,130 @@ +% +% Included by prof-options.lit +% + +Utility programs which produce graphical profiles. + +\subsubsection[hp2ps]{\tr{hp2ps}--heap profile to PostScript} +\index{hp2ps (utility)} +\index{heap profiles} +\index{PostScript, from heap profiles} + +%\vspace{2ex} +%\begin{quote} +USAGE: \tr{hp2ps} [flags] [\pl{<file>}[\tr{.stat}]] +%\end{quote} + +The program \tr{hp2ps}\index{hp2ps} converts a heap profile as +produced by the \tr{-h<break-down>}\index{-h<break-down> RTS option} +runtime option into a PostScript graph of the heap profile. By +convention, the file to be processed by \tr{hp2ps} has a \tr{.hp} +extension. The PostScript output is written to \pl{<file>}\tr{.ps}. If +\pl{<file>} is omitted entirely, then the program behaves as a filter. + +\tr{hp2ps} is distributed in \tr{ghc/utils/hp2ps}. It was originally +developed by Dave Wakeling as part of the HBC/LML heap +profiler. + + +The flags are: +\begin{description} +\item[\tr{-d}] +In order to make graphs more readable, \tr{hp2ps} sorts the shaded +bands for each identifier. The default sort ordering is for the bands +with the largest area to be stacked on top of the smaller ones. The +\tr{-d} option causes rougher bands (those representing series of +values with the largest standard deviations) to be stacked on top of +smoother ones. + +\item[\tr{-b}] +Normally, \tr{hp2ps} puts the title of the graph in a small box at the +top of the page. However, if the JOB string is too long to fit in a +small box (more than 35 characters), then +\tr{hp2ps} will choose to use a big box instead. The \tr{-b} +option forces \tr{hp2ps} to use a big box. + +\item[\tr{-e<float>[in|mm|pt]}] +Generate encapsulated PostScript suitable for inclusion in LaTeX +documents. Usually, the PostScript graph is drawn in landscape mode +in an area 9 inches wide by 6 inches high, and \tr{hp2ps} arranges +for this area to be approximately centred on a sheet of a4 paper. +This format is convenient of studying the graph in detail, but it is +unsuitable for inclusion in LaTeX documents. The \tr{-e} option +causes the graph to be drawn in portrait mode, with float specifying +the width in inches, millimetres or points (the default). The +resulting PostScript file conforms to the Encapsulated PostScript +(EPS) convention, and it can be included in a LaTeX document using +Rokicki's dvi-to-PostScript converter \tr{dvips}. + +\item[\tr{-g}] +Create output suitable for the \tr{gs} PostScript previewer (or +similar). In this case the graph is printed in portrait mode without +scaling. The output is unsuitable for a laser printer. + +\item[\tr{-l}] +Normally a profile is limited to 20 bands with additional identifiers +being grouped into an \tr{OTHER} band. The \tr{-l} flag removes this +20 band and limit, producing as many bands as necessary. No key is +produced as it won't fit!. It is useful for creation time profiles +with many bands. + +\item[\tr{-m<int>}] +Normally a profile is limited to 20 bands with additional identifiers +being grouped into an \tr{OTHER} band. The \tr{-m} flag specifies an +alternative band limit (the maximum is 20). + +\tr{-m0} requests the band limit to be removed. As many bands as +necessary are produced. However no key is produced as it won't fit! It +is useful for displaying creation time profiles with many bands. + +\item[\tr{-p}] +Use previous parameters. By default, the PostScript graph is +automatically scaled both horizontally and vertically so that it fills +the page. However, when preparing a series of graphs for use in a +presentation, it is often useful to draw a new graph using the same +scale, shading and ordering as a previous one. The \tr{-p} flag causes +the graph to be drawn using the parameters determined by a previous +run of \tr{hp2ps} on \pl{file}. These are extracted from +\pl{file}\tr{.aux}. + +\item[\tr{-s}] Use a small box for the title. + +\item[\tr{-t<float>}] +Normally trace elements which sum to a total of less than 1\% of the +profile are removed from the profile. The \tr{-t} option allows this +percentage to be modified (maximum 5\%). + +\tr{-t0} requests no trace elements to be removed from the profile, +ensuring that all the data will be displayed. + +\item[\tr{-?}] Print out usage information. +\end{description} + +\subsubsection[stat2resid]{\tr{stat2resid}---residency info from GC stats} +\index{stat2resid (utility)} +\index{GC stats---residency info} +\index{residency, from GC stats} + +%\vspace{2ex} +%\begin{quote} +USAGE: \tr{stat2resid} [\pl{<file>}[\tr{.stat}] [\pl{<outfile>}]] +%\end{quote} + +The program \tr{stat2resid}\index{stat2resid} converts a detailed +garbage collection statistics file produced by the +\tr{-S}\index{-S RTS option} runtime option into a PostScript heap +residency graph. The garbage collection statistics file can be +produced without compiling your program for profiling. + +By convention, the file to be processed by \tr{stat2resid} has a +\tr{.stat} extension. If the \pl{<outfile>} is not specified the +PostScript will be written to \pl{<file>}\tr{.resid.ps}. If +\pl{<file>} is omitted entirely, then the program behaves as a filter. + +The plot can not be produced from the statistics file for a +generational collector, though a suitable stats file can be produced +using the \tr{-F2s}\index{-F2s RTS option} runtime option when the +program has been compiled for generational garbage collection (the +default). + +\tr{stat2resid} is distributed in \tr{ghc/utils/stat2resid}. diff --git a/ghc/docs/users_guide/prof-reports.lit b/ghc/docs/users_guide/prof-reports.lit new file mode 100644 index 0000000000..fd0abfb104 --- /dev/null +++ b/ghc/docs/users_guide/prof-reports.lit @@ -0,0 +1 @@ +What the bits of a profiling report mean. diff --git a/ghc/docs/users_guide/prof-rts-options.lit b/ghc/docs/users_guide/prof-rts-options.lit new file mode 100644 index 0000000000..022d4e3172 --- /dev/null +++ b/ghc/docs/users_guide/prof-rts-options.lit @@ -0,0 +1,120 @@ +% +% Included by prof-options.lit and runtime_control.lit +% + +It isn't enough to compile your program for profiling with \tr{-prof}! + +When you {\em run} your profiled program, you must tell the runtime system (RTS) +what you want to profile (e.g., time and/or space), and how you wish +the collected data to be reported. You also may wish to set the +sampling interval used in time profiling. + +Executive summary: \tr{./a.out +RTS -p} produces a time profile in +\tr{a.out.prof}; \tr{./a.out +RTS -hC} produces space-profiling +info which can be mangled by \tr{hp2ps} and viewed with \tr{ghostview} +(or equivalent). + +Profiling runtime flags are passed to your program between the usual +\tr{+RTS} and \tr{-RTS} options. + +\begin{description} +\item[\tr{-p<sort>} or \tr{-P<sort>}:] +\index{-p<sort> RTS option (profiling)} +\index{-P<sort> RTS option (profiling)} +\index{time profile} +\index{serial time profile} +The \tr{-p} option produces a standard {\em time profile} report. +It is written into the file \pl{<program>}\tr{.prof}. + +The \tr{-P} option produces a more detailed report containing the +actual time and allocation data as well. (Not used much.) + +The \tr{-P} option also produces {\em serial time-profiling} +information, in the file \pl{<program>}\tr{.time}. This can be +converted into a (somewhat unsatisfactory) PostScript graph using +\tr{hp2ps} (see \Sectionref{hp2ps}). + +???? -F2s needed for serial time profile??? ToDo + +The \pl{<sort>} indicates how the cost centres are to be sorted in the +report. Valid \pl{<sort>} options are: +\begin{description} +\item[\tr{T}:] by time, largest first (the default); +\item[\tr{A}:] by bytes allocated, largest first; +\item[\tr{C}:] alphabetically by group, module and cost centre. +\end{description} + +\item[\tr{-i<secs>}:] +\index{-i<secs> RTS option (profiling)} +Set the profiling (sampling) interval to \tr{<secs>} seconds (the +default is 1~second). + +\item[\tr{-h<break-down>}:] +\index{-h<break-down> RTS option (profiling)} +\index{heap profile} +Produce a detailed {\em space profile} of the heap occupied by live +closures. The profile is written to the file \pl{<program>}\tr{.hp} +from which a PostScript graph can be produced using \tr{hp2ps} (see +\Sectionref{hp2ps}). + +The heap space profile may be broken down by different criteria: +\begin{description} +\item[\tr{-hC}:] cost centre which produced the closure (the default). +\item[\tr{-hM}:] cost centre module which produced the closure. +\item[\tr{-hG}:] cost centre group which produced the closure. +\item[\tr{-hD}:] closure description --- a string describing the closure. +\item[\tr{-hY}:] closure type --- a string describing the closure's type. +\item[\tr{-hT<ints>,<start>}:] the time interval the closure was +created. \tr{<ints>} specifies the no. of interval bands plotted +(default 18) and \tr{<start>} the number of seconds after which the +reported intervals start (default 0.0). +\end{description} +By default all live closures in the heap are profiled, but particular +closures of interest can be selected (see below). +\end{description} + + +Heap (space) profiling uses hash tables. If these tables +should fill the run will abort. The +\tr{-z<tbl><size>}\index{-z<tbl><size> RTS option (profiling)} option is used to +increase the size of the relevant hash table (\tr{C}, \tr{M}, +\tr{G}, \tr{D} or \tr{Y}, defined as for \pl{<break-down>} above). The +actual size used is the next largest power of 2. + +The heap profile can be restricted to particular closures of interest. +The closures of interest can selected by the attached cost centre +(module:label, module and group), closure category (description, type, +and kind) and closure age using the following options: +\begin{description} +\item[\tr{-c{<mod>:<lab>,<mod>:<lab>...}}:] +\index{-c{<lab>} RTS option (profiling)} +Selects individual cost centre(s). +\item[\tr{-m{<mod>,<mod>...}}:] +\index{-m{<mod>} RTS option (profiling)} +Selects all cost centres from the module(s) specified. +\item[\tr{-g{<grp>,<grp>...}}:] +\index{-g{<grp>} RTS option (profiling)} +Selects all cost centres from the groups(s) specified. +\item[\tr{-d{<des>,<des>...}}:] +\index{-d{<des>} RTS option (profiling)} +Selects closures which have one of the specified descriptions. +\item[\tr{-y{<typ>,<typ>...}}:] +\index{-y{<typ>} RTS option (profiling)} +Selects closures which have one of the specified type descriptions. +\item[\tr{-k{<knd>,<knd>...}}:] +\index{-k{<knd>} RTS option (profiling)} +Selects closures which are of one of the specified closure kinds. +Valid closure kinds are \tr{CON} (constructor), \tr{FN} (manifest +function), \tr{PAP} (partial application), \tr{BH} (black hole) and +\tr{THK} (thunk). +\item[\tr{-a<age>}:] +\index{-a<age> RTS option (profiling)} +Selects closures which have survived \pl{<age>} complete intervals. +\end{description} +The space occupied by a closure will be reported in the heap profile +if the closure satisfies the following logical expression: +\begin{display} +([-c] or [-m] or [-g]) and ([-d] or [-y] or [-k]) and [-a] +\end{display} +where a particular option is true if the closure (or its attached cost +centre) is selected by the option (or the option is not specified). diff --git a/ghc/docs/users_guide/profiling.lit b/ghc/docs/users_guide/profiling.lit new file mode 100644 index 0000000000..e98cdb5093 --- /dev/null +++ b/ghc/docs/users_guide/profiling.lit @@ -0,0 +1,239 @@ +\begin{onlystandalone} +\documentstyle[11pt,literate]{article} +\begin{document} +\title{The Glorious Haskell Compilation System\\ Profiling Guide} +\author{The AQUA Team (Patrick M. Sansom)\\ +Department of Computing Science\\ +University of Glasgow\\ +Glasgow, Scotland\\ +G12 8QQ\\ +\\ +Email: glasgow-haskell-\{bugs,request\}\@dcs.glasgow.ac.uk} +\maketitle +\begin{rawlatex} +\tableofcontents +\end{rawlatex} +\end{onlystandalone} + +\section[profiling]{Profiling Haskell programs} +\index{profiling, with cost-centres} +\index{cost-centre profiling} + +Glasgow Haskell comes with a time and space profiling system. Its +purpose is to help you improve your understanding of your program's +execution behaviour, so you can improve it. + +%This profiling system is still under development. +%Please e-mail reports of any bugs you discover to +%\tr{glasgow-haskell-bugs@dcs.glasgow.ac.uk}. + +Any comments, suggestions and/or improvements you have to are welcome. +Recommended ``profiling tricks'' would be especially cool! + +\subsection[profiling-intro]{How to profile a Haskell program} + +The GHC approach to profiling is very simple: annotate the expressions +you consider ``interesting'' with {\em cost centre} labels (strings); +so, for example, you might have: + +\begin{verbatim} +f x y + = let + output1 = _scc_ "Pass1" ( pass1 x ) + output2 = _scc_ "Pass2" ( pass2 output1 y ) + output3 = _scc_ "Pass3" ( pass3 (output2 `zip` [1 .. ]) ) + in concat output3 +\end{verbatim} + +The costs of the evaluating the expressions bound to \tr{output1}, +\tr{output2} and \tr{output3} will be attributed to the ``cost +centres'' \tr{Pass1}, \tr{Pass2} and \tr{Pass3}, respectively. + +The costs of evaluating other expressions, e.g., \tr{concat output4}, +will be inherited by the scope which referenced the function \tr{f}. + +You can put in cost-centres via \tr{_scc_} constructs by hand, as in +the example above. Perfectly cool. That's probably what you {\em +would} do if your program divided into obvious ``passes'' or +``phases'', or whatever. + +If your program is large or you have no clue what might be gobbling +all the time, you can get GHC to mark all functions with \tr{_scc_} +constructs, automagically. Add an \tr{-auto} compilation flag to the +usual \tr{-prof} option. + +Once you start homing in on the Guilty Suspects, you may well switch +from automagically-inserted cost-centres to a few well-chosen ones of +your own. + +To use profiling, you must {\em compile} and {\em run} with special +options. (We usually forget the ``run'' magic!---Do as we say, not as +we do...) Details follow. + +If you're serious about this profiling game, you should probably read +one or more of the Sansom/Peyton Jones papers about the GHC profiling +system. Just visit the Glasgow FP Web page... + +%************************************************************************ +%* * +\subsection[prof-compiler-options]{Compiling programs for profiling} +\index{profiling options} +\index{options, for profiling} +%* * +%************************************************************************ + +\input{prof-compiler-options.lit} + +%************************************************************************ +%* * +\subsection[prof-rts-options]{How to control your profiled program at runtime} +\index{profiling RTS options} +\index{RTS options, for profiling} +%* * +%************************************************************************ + +\input{prof-rts-options.lit} + +%************************************************************************ +%* * +\subsection[prof-graphs]{Producing graphical heap profiles} +\index{heap profiles, producing} +%* * +%************************************************************************ + +\input{prof-post-processors.lit} + +% \subsection[cost-centres]{Profiling by Cost Centres} +% +% Problems with lazy evaluation +% +% The central idea is to identify particular source code expressions of +% interest. These expressions are annotated with a {\em cost +% centre}\index{cost centre} label. Execution and allocation costs are +% attributed to the cost centre label which encloses the expression +% incurring the costs. +% +% Simple example +% +% (Note: the paper in \tr{ghc/docs/papers/profiling.ps} may have some +% decent examples...) +% +% Costs are attribution to one cost centre. +% Inheritance of un-profiled costs. +% +% Degree of evaluation +% Unevaluated arguments +% Optimisation and transformation +% Evaluation of instances +% escaping functions: evaluation vs lexical +% +% \subsection[prof-annotations]{Annotating your Haskell source} +% +% Explicit annotations +% Automatic annotation +% +% \subsection[prof-information]{Profiling information} +% +% Cost Centre Label,Module,Group +% Example time/alloc profile +% +% Description of heap profile +% Closure Description, Type and Kind +% \subsection[limitations]{Limitations of the current profiling system} +% +% There are a number of limitations and shortcomings of the current +% profiling system. Any comments on the impact of these and any +% suggested improvements would be greatly appreciated. +% +% \begin{onlylatex} +% \subsubsection*{Explicit \tr{_scc_} annotations} +% \end{onlylatex} +% \begin{onlyinfo} +% Explicit \tr{_scc_} annotations: +% \end{onlyinfo} +% +% The explicit \tr{_scc_} source annotations cannot annotate entire +% function declarations as the clauses, pattern matching are not part of +% the expression syntax --- they are syntactic sugar. It is possible to +% remove the syntactic sugar by hand, translating to a simple +% declaration with case expressions on the rhs, but this is very +% tiresome. +% +% We propose to introduce an additional annotation to enable a \tr{_scc_} +% annotation to be placed around an entire declaration. +% +% To further ease the explicit annotation process we also propose to +% provide annotations which instruct the compiler to annotate all the +% declarations in a particular \tr{let} or \tr{where} clause with the +% name of the declaration. +% +% Other annotation schemes are feasible. Any suggestions / requests? +% +% +% \begin{onlylatex} +% \subsubsection*{Closure descriptions} +% \end{onlylatex} +% \begin{onlyinfo} +% Closure descriptions: +% \end{onlyinfo} +% +% The closure descriptions are by no means perfect ... +% +% The descriptions for expressions are somewhat tedious as they reflect +% some of the structure of the transformed STG code. This is largely to +% provide additional information so use of the STG code can be made if +% required (use the compiler option \tr{-ddump-stg}). This may be +% removed if the name of the \pl{corner} is considered sufficient. +% +% Local bindings introduced by the compiler have a name \tr{?<tag>}. +% Most of these are not related to the source in any meaningful way. For +% example, the \tr{?stg} names are introduced during the CoreToStg pass. +% Some other arbitrary compiler introduced names are: \tr{?ds}, +% \tr{?tpl}, \tr{?si}, \tr{?cs}, \tr{?ll}, and \tr{?sat}. Please let us +% know if any of these turn out to be a problem. We could introduce a +% more meaningful naming scheme into the compiler which assigns names +% that reflect the nearest enclosing source binding. Another possibility +% is to add the unique identifier so they aren't all clumped together as +% one indistinguishable description. +% +% There is only one closure description and type for all black holes, +% ``BH''. It might be useful to record the closure that is currently +% being evaluated as part of the black hole description. +% +% Similarly there is only one partial application description, ``PAP''. +% It might be useful to record the function being applied in the partial +% application as part of the partial application description. +% +% +% \begin{onlylatex} +% \subsubsection*{Garbage collection and paging} +% \end{onlylatex} +% \begin{onlyinfo} +% Garbage collection and paging: +% \end{onlyinfo} +% +% Currently the profiling implementation requires the two-space +% (\tr{-gc-2s}) garbage collector to be used. When using the \tr{-prof} +% options a particular garbage collector should not be specified. This +% imposes particular paging characteristics which may be different from +% the garbage collector your program normally uses. These paging +% characteristics may distort the user time profiling results, though we +% do not believe this is a significant problem. +% +% +% \subsection[references]{Papers describing this work} +% +% A discussion of our initial ideas are described in the paper +% ``Profiling Lazy Functional Languages'' by Patrick Sansom and Simon +% Peyton Jones. +% +% It is in the GHC distribution in \tr{ghc/docs/papers/profiling.ps}, +% or it can be retrieved using ftp from +% \tr{ftp.dcs.glasgow.ac.uk} (\tr{[130.209.240.50]}) +% in the file +% \tr{pub/glasgow-fp/papers/lazy-profiling.ps}. + +\begin{onlystandalone} +\printindex +\end{document} +\end{onlystandalone} diff --git a/ghc/docs/users_guide/runtime_control.lit b/ghc/docs/users_guide/runtime_control.lit new file mode 100644 index 0000000000..db7c4fdc17 --- /dev/null +++ b/ghc/docs/users_guide/runtime_control.lit @@ -0,0 +1,332 @@ +%************************************************************************ +%* * +\section[runtime-control]{Controlling the run-time behaviour of your programs} +\index{runtime control of Haskell programs} +\index{RTS options} +%* * +%************************************************************************ + +To make an executable program, the GHC system compiles your code and +then links it with a non-trivial runtime system (RTS), which handles +storage management, profiling, etc. + +You have some control over the behaviour of the RTS, by giving special +command-line arguments to your program. + +%You have some control over the behavior of the runtime system, either +%by giving special command-line arguments to your program (the usual) or by +%building in your own defaults at compile time (the exotic). + +When your Haskell program starts up, its RTS extracts +command-line arguments bracketed between \tr{+RTS}\index{+RTS option} +and \tr{-RTS}\index{-RTS option} as its own. For example: +\begin{verbatim} +% ./a.out -f +RTS -p -S -RTS -h foo bar +\end{verbatim} +The RTS will snaffle \tr{-p -S} for itself, +and the remaining arguments \tr{-f -h foo bar} will be handed +to your program when it does a @GetArgs@ I/O request. + +No \tr{-RTS} option is required if the runtime-system options extend +to the end of the command line, as in this example: +\begin{verbatim} +% hls -ltr /usr/etc +RTS -H5m +\end{verbatim} +If you absolutely positively want all the rest of the options in a +command line to go to the program (and not the RTS), use a +\tr{--RTS}\index{--RTS option}. + +As always, for RTS options that take \tr{<size>}s: If the last +character of \tr{size} is a K or k, multiply by 1000; if an M or m, by +1,000,000; if a G or G, by 1,000,000,000. (And any wraparound in the +counters is {\em your} fault!) + +Giving a \tr{+RTS -f}\index{-f RTS option} option will print out the +RTS options actually available in your program (which vary, depending +on how you compiled). + +%************************************************************************ +%* * +\subsection{Generally-available RTS options} +\index{RTS options, general} +%* * +%************************************************************************ + +The most important RTS options are: +\begin{description} +\item[\tr{-H<size>}:] +\index{-H<size> RTS option} +Set the heap size to \pl{<size>} bytes +[default: 4M]. + +\item[\tr{-K<size>}:] +\index{-K<size> RTS option} +Set the stack size to \pl{<size>} bytes [default: 64K]. +For concurrent/parallel programs, it is the stack size of the main +thread; generally speaking, c/p stacks are in heap. + +Note: if your program seems to be consuming infinite stack space, it +is probably in a loop :-) Of course, if stacks are in the heap, make +that infinite {\em heap} space... + +\item[\tr{-s<file>} or \tr{-S<file>}:] +\index{-S<file> RTS option} +\index{-s<file> RTS option} +Write modest (\tr{-s}) or verbose (\tr{-S}) garbage-collector +statistics into file \pl{<file>}. The default \pl{<file>} is +\pl{<program>}\tr{.stat}. The \pl{<file>} \tr{stderr} is treated +specially, with the output really being sent to \tr{stderr}. + +%Note that \tr{stdout} is flushed before each garbage collection so the +%interleaving of \tr{stdout} and the garbage collection statistics will +%be accurate. + +%Note that the same program will typically allocate more space with a +%generational collector than with a non-generational collector. +The amount of heap allocation will typically increase as the total heap +size is reduced. The reason for this odd behaviour is that updates of +promoted-to-old-generation objects may require the extra allocation of a new-generation +object to ensure that there are never any pointers from the old +generation to the new generation. + +For some garbage collectors (not including the default one, sadly), +you can convert the \tr{-S} output into a residency graph (in +PostScript), using the \tr{stat2resid}\index{stat2resid} utility in +the GHC distribution (\tr{ghc/utils/stat2resid}). + +\item[\tr{-N}:] +\index{-N RTS option} +Normally, the garbage collector black-holes closures which are being +evaluated, as a space-saving measure. That's exactly what you want +for ordinary Haskell programs. + +When signal handlers are present, however, a computation may be +abandoned prematurely, leaving black holes behind. If the signal +handler shares one of these black-holed closures, disaster can result. +Use the \tr{-N} option to prevent black-holing by the garbage +collector if you suspect that your signal handlers may share {\em any} +subexpressions with the top-level computation. Expect your heap usage +to increase, since the lifetimes of some closures may be extended. +\end{description} + +%************************************************************************ +%* * +\subsection{RTS options to control the garbage-collector} +\index{RTS options, garbage-collection} +%* * +%************************************************************************ + +Besides the \tr{-H} (set heap size) and \tr{-S}/\tr{-s} (GC stats) RTS +options, there are several options to give you precise control over +garbage collection. + +\begin{description} +\item[\tr{-M<n>}:] +\index{-M<n> RTS option} +Minimum \% \pl{<n>} of heap which must be available for allocation. +The default is 3\%. + +\item[\tr{-A<size>}:] +\index{-A<size> RTS option} +Sets a limit on the size of the allocation area for generational +garbage collection to \pl{<size>} bytes (\tr{-A} gives default of 64k). If +a negative size is given the size of the allocation is fixed to +-\pl{<size>}. For non-generational collectors, it fixes the minimum +heap which must be available after a collection, overriding the +\tr{-M<n>} RTS option. + +\item[\tr{-G<size>}:] +\index{-G<size> RTS option} +Sets the percentage of free space to be promoted before a major +collection is invoked to \pl{<size>}\%. The default is 66\%. If a +negative size is given it fixes the size of major generation threshold +to -\pl{<size>} bytes. + +\item[\tr{-F2s}:] +\index{-F2s RTS option} +Forces a program compiled for generational GC to use two-space copying +collection. The two-space collector may outperform the generational +collector for programs which have a very low heap residency. It can +also be used to generate a statistics file from which a basic heap +residency profile can be produced (see Section \ref{stat2resid}). + +There will still be a small execution overhead imposed by the +generational compilation as the test for old generation updates will +still be executed (of course none will actually happen). This +overhead is typically less than 1\%. + +\item[\tr{-j<size>}:] +\index{-j<size> RTS option} +Force a major garbage collection every \pl{<size>} bytes. (Normally +used because you're keen on getting major-GC stats, notably heap residency +info.) +\end{description} + +%************************************************************************ +%* * +\subsection{RTS options for profiling and Concurrent/Parallel Haskell} +%* * +%************************************************************************ + +The RTS options related to profiling are described in +\Sectionref{prof-rts-options}; +and those for concurrent/parallel stuff, in \Sectionref{parallel-rts-opts}. + +%************************************************************************ +%* * +\subsection{RTS options for hackers, debuggers, and over-interested souls} +\index{RTS options, hacking/debugging} +%* * +%************************************************************************ + +These RTS options might be used (a)~to avoid a GHC bug, (b)~to see +``what's really happening'', or (c)~because you feel like it. Not +recommended for everyday use! + +\begin{description} +\item[\tr{-B}:] +\index{-B RTS option} +Sound the bell at the start of each (major) garbage collection. +[Why anyone would do this, I cannot imagine.] + +\item[\tr{-I}:] +Use the ``debugging mini-interpreter'' with sanity-checking; you have +to have an appropriately-compiled version of the prelude, etc. +Goes together nicely with GDB (GNU debugger)... +(OLD, REALLY) + +\item[\tr{-r<file>}:] +\index{-r <file> RTS option} +Produce ``ticky-ticky'' statistics at the end of the program run. +The \tr{<file>} business works just like on the \tr{-S} RTS option (above). + +``Ticky-ticky'' statistics are counts of various program actions +(updates, enters, etc.) +The program must have been compiled using +\tr{-fstg-reduction-counts}\index{-fstg-reduction-counts option} +(a.k.a. ``ticky-ticky profiling''), and, for it to be really useful, +linked with suitable system libraries. Not a trivial undertaking: +consult the installation guide on how to set things up for +easy ``ticky-ticky'' profiling. + +\item[\tr{-T<num>}:] +\index{-T RTS option} +An RTS debugging flag; varying quantities of output depending on which bits +are set in \pl{<num>}. + +\item[\tr{-Z}:] +\index{-Z RTS option} +Turn {\em off} ``update-frame squeezing'' at garbage-collection time. +(There's no particularly good reason to turn it off.) +\end{description} + +%************************************************************************ +%* * +\subsection[rts-hooks]{``Hooks'' to change RTS failure messages} +\index{hooks, RTS} +\index{RTS hooks} +%* * +%************************************************************************ + +GHC lets you exercise rudimentary control over the messages printed +when the runtime system ``blows up,'' e.g., on stack overflow. + +Simply write some of the following procedures in C and then make sure +they get linked in, in preference to those in the RTS library: +\begin{description} +\item[\tr{void ErrorHdrHook (FILE *)}:] +\index{ErrorHdrHook} +What's printed out before the message from \tr{error}. + +\item[\tr{void OutOfHeapHook (unsigned long, unsigned long)}:] +\index{OutOfHeapHook} +The heap-overflow message. + +\item[\tr{void StackOverflowHook (long int)}:] +\index{StackOverflowHook} +The stack-overflow message. + +\item[\tr{void MallocFailHook (long int)}:] +\index{MallocFailHook} +The message printed if \tr{malloc} fails. + +\item[\tr{void PatErrorHdrHook (FILE *)}:] +\index{PatErrorHdrHook} +The message printed if a pattern-match fails (the failures +that were not handled by the Haskell programmer). + +\item[\tr{void PreTraceHook (FILE *)}:] +\index{PreTraceHook} +What's printed out before a \tr{trace} message. + +\item[\tr{void PostTraceHook (FILE *)}:] +\index{PostTraceHook} +What's printed out after a \tr{trace} message. +\end{description} + +For example, here is the ``hooks'' code used by GHC itself: +\begin{verbatim} +#include <stdio.h> +#define W_ unsigned long int +#define I_ long int + +void +ErrorHdrHook (where) + FILE *where; +{ + fprintf(where, "\n"); /* no "Fail: " */ +} + +void +OutOfHeapHook (request_size, heap_size) + W_ request_size; /* in bytes */ + W_ heap_size; /* in bytes */ +{ + fprintf(stderr, "GHC's heap exhausted;\nwhile trying to + allocate %lu bytes in a %lu-byte heap;\nuse the `-H<size>' + option to increase the total heap size.\n", + request_size, + heap_size); +} + +void +StackOverflowHook (stack_size) + I_ stack_size; /* in bytes */ +{ + fprintf(stderr, "GHC stack-space overflow: current size + %ld bytes.\nUse the `-K<size>' option to increase it.\n", + stack_size); +} + +void +PatErrorHdrHook (where) + FILE *where; +{ + fprintf(where, "\n*** Pattern-matching error within GHC!\n\n + This is a compiler bug; please report it to + glasgow-haskell-bugs@dcs.glasgow.ac.uk.\n\nFail: "); +} + +void +PreTraceHook (where) + FILE *where; +{ + fprintf(where, "\n"); /* not "Trace On" */ +} + +void +PostTraceHook (where) + FILE *where; +{ + fprintf(where, "\n"); /* not "Trace Off" */ +} +\end{verbatim} + +%************************************************************************ +%* * +%\subsection[rts-control-shell-scripts]{Hiding the runtime-control mess with a shell script} +%* * +%************************************************************************ + +%NOT DONE YET. + diff --git a/ghc/docs/users_guide/sooner.lit b/ghc/docs/users_guide/sooner.lit new file mode 100644 index 0000000000..a7f535c594 --- /dev/null +++ b/ghc/docs/users_guide/sooner.lit @@ -0,0 +1,530 @@ +%************************************************************************ +%* * +\section[sooner-faster-quicker]{Advice on: sooner, faster, smaller, stingier} +%* * +%************************************************************************ + +Please advise us of other ``helpful hints'' that should go here! + +%************************************************************************ +%* * +\subsection[sooner]{Sooner: producing a program more quickly} +\index{compiling faster} +\index{faster compiling} +%* * +%************************************************************************ + +\begin{description} +%---------------------------------------------------------------- +\item[Don't use \tr{-O} or (especially) \tr{-O2}:] +By using them, you are telling GHC that you are willing to suffer +longer compilation times for better-quality code. + +GHC is surprisingly zippy for normal compilations without \tr{-O}! + +%---------------------------------------------------------------- +\item[Use more memory:] +Within reason, more memory for heap space means less garbage +collection for GHC, which means less compilation time. If you use +the \tr{-Rgc-stats} option, you'll get a garbage-collector report. +(Again, you can use the cheap-and-nasty \tr{-optCrts-Sstderr} option to +send the GC stats straight to standard error.) + +If it says you're using more than 20\% of total time in garbage +collecting, then more memory would help. + +You ask for more heap with the \tr{-H<size>}\index{-H<size> option} +option; e.g.: \tr{ghc -c -O -H16m Foo.hs}. + +If GHC persists in being a bad memory citizen, please report it as a +bug. + +%---------------------------------------------------------------- +\item[Don't use too much memory!] +As soon as GHC plus its ``fellow citizens'' (other processes on your machine) start +using more than the {\em real memory} on your machine, and the machine +starts ``thrashing,'' {\em the party is over}. Compile times will be +worse than terrible! Use something like the csh-builtin \tr{time} +command to get a report on how many page faults you're getting. + +If you don't know what virtual memory, thrashing, and page faults are, +or you don't know the memory configuration of your machine, {\em +don't} try to be clever about memory use: you'll just make your life a +misery (and for other people, too, probably). + +%---------------------------------------------------------------- +\item[Try to use local disks when linking:] +Because Haskell objects and libraries tend to be large, it can take +many real seconds to slurp the bits to/from an NFS filesystem (say). + +It would be quite sensible to {\em compile} on a fast machine using +remotely-mounted disks; then {\em link} on a slow machine that had +your disks directly mounted. + +%---------------------------------------------------------------- +\item[Don't derive \tr{read} for \tr{Text} unnecessarily:] +When doing \tr{deriving Text}, +use \tr{-fomit-derived-read}\index{-fomit-derived-read option} +to derive only the \tr{showsPrec} method. Quicker, smaller code. + +%---------------------------------------------------------------- +\item[Don't re-export instance declarations:] + +(Note: This recommendation totally violates the Haskell language +standard.) + +The Haskell module system dictates that instance declarations are +exported and re-exported into interface files with considerable gusto. +In a large system, especially one with mutually-recursive modules, +this tendency makes your interface files bigger (bad) and decreases +the chances that changes will be propagated incorrectly (bad). + +If you wish, you may use a language-violating option, +\tr{-fomit-reexported-instances}, +\index{-fomit-reexported-instances option} +to get just the effect you might expect. It can't help but +speed things up. + +%---------------------------------------------------------------- +\item[GHC compiles some program constructs slowly:] +Deeply-nested list comprehensions seem to be one such; in the past, +very large constant tables were bad, too. + +We'd rather you reported such behaviour as a bug, so that we can try +to correct it. + +The parts of the compiler that seem most prone to wandering off for a +long time are the abstract interpreters (strictness and update +analysers). You can turn these off individually with +\tr{-fno-strictness}\index{-fno-strictness anti-option} and +\tr{-fno-update-analysis}.\index{-fno-update-analysis anti-option} + +If \tr{-ddump-simpl} produces output after a reasonable time, but +\tr{-ddump-stg} doesn't, then it's probably the update analyser +slowing you down. + +If your module has big wads of constant data, GHC may produce a huge +basic block that will cause the native-code generator's register +allocator to founder. + +If \tr{-ddump-absC} produces output after a reasonable time, but +nothing after that---it's probably the native-code generator. Bring +on \tr{-fvia-C}\index{-fvia-C option} (not that GCC will be that quick about it, either). + +%---------------------------------------------------------------- +\item[Avoid the consistency-check on linking:] +Use \tr{-no-link-chk}\index{-no-link-chk}; saves effort. This is probably +safe in a I-only-compile-things-one-way setup. + +%---------------------------------------------------------------- +\item[Explicit \tr{import} declarations:] +Instead of saying \tr{import Foo}, say +\tr{import Foo (...stuff I want...)}. + +Truthfully, the reduction on compilation time will be very small. +However, judicious use of \tr{import} declarations can make a +program easier to understand, so it may be a good idea anyway. +\end{description} + +%************************************************************************ +%* * +\subsection[faster]{Faster: producing a program that runs quicker} +\index{faster programs, how to produce} +%* * +%************************************************************************ + +The key tool to use in making your Haskell program run faster are +GHC's profiling facilities, described separately in +\sectionref{profiling}. There is {\em no substitute} for finding +where your program's time/space is {\em really} going, as opposed +to where you imagine it is going. + +Another point to bear in mind: By far the best way to improve a +program's performance {\em dramatically} is to use better algorithms. +Once profiling has thrown the spotlight on the guilty +time-consumer(s), it may be better to re-think your program than to +try all the tweaks listed below. + +Another extremely efficient way to make your program snappy is to use +library code that has been Seriously Tuned By Someone Else. You {\em might} be able +to write a better quicksort than the one in the HBC library, but it +will take you much longer than typing \tr{import QSort}. +(Incidentally, it doesn't hurt if the Someone Else is Lennart +Augustsson.) + +Please report any overly-slow GHC-compiled programs. The current +definition of ``overly-slow'' is ``the HBC-compiled version ran +faster''... + +\begin{description} +%---------------------------------------------------------------- +\item[Optimise, using \tr{-O} or \tr{-O2}:] This is the most basic way +to make your program go faster. Compilation time will be slower, +especially with \tr{-O2}. + +At version~0.26, \tr{-O2} is nearly indistinguishable from \tr{-O}. + +%---------------------------------------------------------------- +\item[Compile via C and crank up GCC:] Even with \tr{-O}, GHC tries to +use a native-code generator, if available. But the native +code-generator is designed to be quick, not mind-bogglingly clever. +Better to let GCC have a go, as it tries much harder on register +allocation, etc. + +So, when we want very fast code, we use: \tr{-O -fvia-C -O2-for-C}. + +%---------------------------------------------------------------- +\item[Overloaded functions are not your friend:] +Haskell's overloading (using type classes) is elegant, neat, etc., +etc., but it is death to performance if left to linger in an inner +loop. How can you squash it? + +\begin{description} +\item[Give explicit type signatures:] +Signatures are the basic trick; putting them on exported, top-level +functions is good software-engineering practice, anyway. + +The automatic specialisation of overloaded functions should take care +of overloaded local and/or unexported functions. + +\item[Use \tr{SPECIALIZE} pragmas:] +\index{SPECIALIZE pragma} +\index{overloading, death to} +(UK spelling also accepted.) For key overloaded functions, you can +create extra versions (NB: more code space) specialised to particular +types. Thus, if you have an overloaded function: +\begin{verbatim} +hammeredLookup :: Ord key => [(key, value)] -> key -> value +\end{verbatim} +If it is heavily used on lists with \tr{Widget} keys, you could +specialise it as follows: +\begin{verbatim} +{-# SPECIALIZE hammeredLookup :: [(Widget, value)] -> Widget -> value #-} +\end{verbatim} + +To get very fancy, you can also specify a named function to use for +the specialised value, by adding \tr{= blah}, as in: +\begin{verbatim} +{-# SPECIALIZE hammeredLookup :: ...as before... = blah #-} +\end{verbatim} +It's {\em Your Responsibility} to make sure that \tr{blah} really +behaves as a specialised version of \tr{hammeredLookup}!!! + +An example in which the \tr{= blah} form will Win Big: +\begin{verbatim} +toDouble :: Real a => a -> Double +toDouble = fromRational . toRational + +{-# SPECIALIZE toDouble :: Int -> Double = i2d #-} +i2d (I# i) = D# (int2Double# i) -- uses Glasgow prim-op directly +\end{verbatim} +The \tr{i2d} function is virtually one machine instruction; the +default conversion---via an intermediate \tr{Rational}---is obscenely +expensive by comparison. + +By using the US spelling, your \tr{SPECIALIZE} pragma will work with +HBC, too. Note that HBC doesn't support the \tr{= blah} form. + +A \tr{SPECIALIZE} pragma for a function can be put anywhere its type +signature could be put. + +\item[Use \tr{SPECIALIZE instance} pragmas:] +Same idea, except for instance declarations. For example: +\begin{verbatim} +instance (Eq a) => Eq (Foo a) where { ... usual stuff ... } + +{-# SPECIALIZE instance Eq (Foo [(Int, Bar)] #-} +\end{verbatim} +Compatible with HBC, by the way. + +See also: overlapping instances, in \Sectionref{glasgow-hbc-exts}. +They are to \tr{SPECIALIZE instance} pragmas what \tr{= blah} +hacks are to \tr{SPECIALIZE} (value) pragmas... + +\item[``How do I know what's happening with specialisations?'':] + +The \tr{-fshow-specialisations}\index{-fshow-specialisations option} +will show the specialisations that actually take place. + +The \tr{-fshow-import-specs}\index{-fshow-import-specs option} will +show the specialisations that GHC {\em wished} were available, but +were not. You can add the relevant pragmas to your code if you wish. + +You're a bit stuck if the desired specialisation is of a Prelude +function. If it's Really Important, you can just snap a copy of the +Prelude code, rename it, and then SPECIALIZE that to your heart's +content. + +\item[``But how do I know where overloading is creeping in?'':] + +A low-tech way: grep (search) your interface files for overloaded +type signatures; e.g.,: +\begin{verbatim} +% egrep '^[a-z].*::.*=>' *.hi +\end{verbatim} + +Note: explicit export lists sometimes ``mask'' overloaded top-level +functions; i.e., you won't see anything about them in the interface +file. I sometimes remove my export list temporarily, just to see what +pops out. +\end{description} + +%---------------------------------------------------------------- +\item[Strict functions are your dear friends:] +and, among other things, lazy pattern-matching is your enemy. + +(If you don't know what a ``strict function'' is, please consult a +functional-programming textbook. A sentence or two of +explanation here probably would not do much good.) + +Consider these two code fragments: +\begin{verbatim} +f (Wibble x y) = ... # strict + +f arg = let { (Wibble x y) = arg } in ... # lazy +\end{verbatim} +The former will result in far better code. + +A less contrived example shows the use of \tr{cases} instead +of \tr{lets} to get stricter code (a good thing): +\begin{verbatim} +f (Wibble x y) # beautiful but slow + = let + (a1, b1, c1) = unpackFoo x + (a2, b2, c2) = unpackFoo y + in ... + +f (Wibble x y) # ugly, and proud of it + = case (unpackFoo x) of { (a1, b1, c1) -> + case (unpackFoo y) of { (a2, b2, c2) -> + ... + }} +\end{verbatim} + +%---------------------------------------------------------------- +\item[GHC loves single-constructor data-types:] + +It's all the better if a function is strict in a single-constructor +type (a type with only one data-constructor; for example, tuples are +single-constructor types). + +%---------------------------------------------------------------- +\item[``How do I find out a function's strictness?''] + +Don't guess---look it up. + +Look for your function in the interface file, then for the third field +in the pragma; it should say \tr{_S_ <string>}. The \tr{<string>} +gives the strictness of the function's arguments. \tr{L} is lazy +(bad), \tr{S} and \tr{E} are strict (good), \tr{P} is ``primitive'' (good), +\tr{U(...)} is strict and +``unpackable'' (very good), and \tr{A} is absent (very good). + +If the function isn't exported, just compile with the extra flag \tr{-ddump-simpl}; +next to the signature for any binder, it will print the self-same +pragmatic information as would be put in an interface file. +(Besides, Core syntax is fun to look at!) + +%---------------------------------------------------------------- +\item[Force key functions to be \tr{INLINE}d (esp. monads):] + +GHC (with \tr{-O}, as always) tries to inline (or ``unfold'') +functions/values that are ``small enough,'' thus avoiding the call +overhead and possibly exposing other more-wonderful optimisations. + +You will probably see these unfoldings (in Core syntax) in your +interface files. + +Normally, if GHC decides a function is ``too expensive'' to inline, it +will not do so, nor will it export that unfolding for other modules to +use. + +The sledgehammer you can bring to bear is the +\tr{INLINE}\index{INLINE pragma} pragma, used thusly: +\begin{verbatim} +key_function :: Int -> String -> (Bool, Double) + +#ifdef __GLASGOW_HASKELL__ +{-# INLINE key_function #-} +#endif +\end{verbatim} +(You don't need to do the C pre-processor carry-on unless you're going +to stick the code through HBC---it doesn't like \tr{INLINE} pragmas.) + +The major effect of an \tr{INLINE} pragma is to declare a function's +``cost'' to be very low. The normal unfolding machinery will then be +very keen to inline it. + +An \tr{INLINE} pragma for a function can be put anywhere its type +signature could be put. + +\tr{INLINE} pragmas are a particularly good idea for the +\tr{then}/\tr{return} (or \tr{bind}/\tr{unit}) functions in a monad. +For example, in GHC's own @UniqueSupply@ monad code, we have: +\begin{verbatim} +#ifdef __GLASGOW_HASKELL__ +{-# INLINE thenUs #-} +{-# INLINE returnUs #-} +#endif +\end{verbatim} + +GHC reserves the right to {\em disallow} any unfolding, even if you +explicitly asked for one. That's because a function's body may +become {\em unexportable}, because it mentions a non-exported value, +to which any importing module would have no access. + +If you want to see why candidate unfoldings are rejected, use the +\tr{-freport-disallowed-unfoldings} +\index{-freport-disallowed-unfoldings} +option. + +%---------------------------------------------------------------- +\item[Don't let GHC ignore pragmatic information:] + +Sort-of by definition, GHC is allowed to ignore pragmas in interfaces. +Your program should still work, if not as well. + +Normally, GHC {\em will} ignore an unfolding pragma in an interface if +it cannot figure out all the names mentioned in the unfolding. (A +very much hairier implementation could make sure This Never Happens, +but life is too short to wage constant battle with Haskell's module +system.) + +If you want to prevent such ignorings, give GHC a +\tr{-fshow-pragma-name-errs} +option.\index{-fshow-pragma-name-errs option} +It will then treat any unresolved names in pragmas as {\em +errors}, rather than inconveniences. + +%---------------------------------------------------------------- +\item[Explicit \tr{export} list:] +If you do not have an explicit export list in a module, GHC must +assume that everything in that module will be exported. This has +various pessimising effect. For example, if a bit of code is actually +{\em unused} (perhaps because of unfolding effects), GHC will not be +able to throw it away, because it is exported and some other module +may be relying on its existence. + +GHC can be quite a bit more aggressive with pieces of code if it knows +they are not exported. + +%---------------------------------------------------------------- +\item[Look at the Core syntax!] +(The form in which GHC manipulates your code.) Just run your +compilation with \tr{-ddump-simpl} (don't forget the \tr{-O}). + +If profiling has pointed the finger at particular functions, look at +their Core code. \tr{lets} are bad, \tr{cases} are good, dictionaries +(\tr{d.<Class>.<Unique>}) [or anything overloading-ish] are bad, +nested lambdas are bad, explicit data constructors are good, primitive +operations (e.g., \tr{eqInt#}) are good, ... + +%---------------------------------------------------------------- +\item[Use unboxed types (a GHC extension):] +When you are {\em really} desperate for speed, and you want to +get right down to the ``raw bits.'' +Please see \sectionref{glasgow-unboxed} for some information about +using unboxed types. + +%---------------------------------------------------------------- +\item[Use \tr{_ccall_s} (a GHC extension) to plug into fast libraries:] +This may take real work, but... There exist piles of +massively-tuned library code, and the best thing is not +to compete with it, but link with it. + +\Sectionref{glasgow-ccalls} says a little about how to use C calls. + +%---------------------------------------------------------------- +\item[Don't use \tr{Float}s:] +We don't provide specialisations of Prelude functions for \tr{Float} +(but we do for \tr{Double}). If you end up executing overloaded +code, you will lose on performance, perhaps badly. + +\tr{Floats} (probably 32-bits) are almost always a bad idea, anyway, +unless you Really Know What You Are Doing. Use Doubles. There's +rarely a speed disadvantage---modern machines will use the same +floating-point unit for both. With \tr{Doubles}, you are much less +likely to hang yourself with numerical errors. + +%---------------------------------------------------------------- +\item[Use a bigger heap!] +If your program's GC stats (\tr{-S}\index{-S RTS option} RTS option) +indicate that it's doing lots of garbage-collection (say, more than +20\% of execution time), more memory might help---with the +\tr{-H<size>}\index{-H<size> RTS option} RTS option. + +%---------------------------------------------------------------- +\item[Use a smaller heap!] +Some programs with a very small heap residency (toy programs, usually) +actually benefit from running the heap size way down. The +\tr{-H<size>} RTS option, as above. + +%---------------------------------------------------------------- +\item[Use a smaller ``allocation area'':] +If you can get the garbage-collector's youngest generation to fit +entirely in your machine's cache, it may make quite a difference. +The effect is {\em very machine dependent}. But, for example, +a \tr{+RTS -A128k}\index{-A<size> RTS option} option on one of our +DEC Alphas was worth an immediate 5\% performance boost. +\end{description} + +%************************************************************************ +%* * +\subsection[smaller]{Smaller: producing a program that is smaller} +\index{smaller programs, how to produce} +%* * +%************************************************************************ + +Decrease the ``go-for-it'' threshold for unfolding smallish expressions. +Give a \tr{-funfolding-use-threshold0}\index{-funfolding-use-threshold0 option} +option for the extreme case. (``Only unfoldings with zero cost should proceed.'') + +(Note: I have not been too successful at producing code smaller +than that which comes out with \tr{-O}. WDP 94/12) + +Use \tr{-fomit-derived-read} if you are using a lot of derived +instances of \tr{Text} (and don't need the read methods). + +Use \tr{strip} on your executables. + +%************************************************************************ +%* * +\subsection[stingier]{Stingier: producing a program that gobbles less heap space} +\index{memory, using less heap} +\index{space-leaks, avoiding} +\index{heap space, using less} +%* * +%************************************************************************ + +``I think I have a space leak...'' Re-run your program with +\tr{+RTS -Sstderr},\index{-Sstderr RTS option} and remove all doubt! +(You'll see the heap usage get bigger and bigger...) [Hmmm... this +might be even easier with the \tr{-F2s}\index{-F2s RTS option} RTS +option; so... \tr{./a.out +RTS -Sstderr -F2s}...] + +Once again, the profiling facilities (\sectionref{profiling}) are the +basic tool for demystifying the space behaviour of your program. + +Strict functions are good to space usage, as they are for time, as +discussed in the previous section. Strict functions get right down to +business, rather than filling up the heap with closures (the system's +notes to itself about how to evaluate something, should it eventually +be required). + +If you have a true blue ``space leak'' (your program keeps gobbling up +memory and never ``lets go''), then 7 times out of 10 the problem is +related to a {\em CAF} (constant applicative form). Real people call +them ``top-level values that aren't functions.'' Thus, for example: +\begin{verbatim} +x = (1 :: Int) +f y = x +ones = [ 1, (1 :: Float), .. ] +\end{verbatim} +\tr{x} and \tr{ones} are CAFs; \tr{f} is not. + +The GHC garbage collectors are not clever about CAFs. The part of the +heap reachable from a CAF is never collected. In the case of +\tr{ones} in the example above, it's {\em disastrous}. For this +reason, the GHC ``simplifier'' tries hard to avoid creating CAFs, but +it cannot subvert the will of a determined CAF-writing programmer (as +in the case above). diff --git a/ghc/docs/users_guide/ticky.lit b/ghc/docs/users_guide/ticky.lit new file mode 100644 index 0000000000..478677af51 --- /dev/null +++ b/ghc/docs/users_guide/ticky.lit @@ -0,0 +1,26 @@ +%************************************************************************ +%* * +\section[ticky-ticky]{Using ``ticky-ticky'' profiling (for implementors)} +\index{ticky-ticky profiling (implementors)} +%* * +%************************************************************************ + +(ToDo: document properly.) + +It is possible to compile Glasgow Haskell programs so that they will +count lots and lots of interesting things, e.g., number of updates, +number of data constructors entered, etc., etc. We call this +``ticky-ticky'' profiling,\index{ticky-ticky profiling}% +\index{profiling, ticky-ticky} because that's the sound a Sun4 makes +when it is running up all those counters ({\em slowly}). + +Ticky-ticky profiling is mainly intended for implementors; it is quite +separate from the main ``cost-centre'' profiling system, intended for +all users everywhere. + +To be able to use ticky-ticky profiling, you will need to have built +appropriate libraries and things when you made the system. See +``Customising what libraries to build,'' in the installation guide. + +To get your compiled program to spit out the ticky-ticky numbers, use +a \tr{-r} RTS option\index{-r RTS option}. diff --git a/ghc/docs/users_guide/tutorial.lit b/ghc/docs/users_guide/tutorial.lit new file mode 100644 index 0000000000..89233e6799 --- /dev/null +++ b/ghc/docs/users_guide/tutorial.lit @@ -0,0 +1,129 @@ +% +% $Header: /srv/cvs/cvs.haskell.org/fptools/ghc/docs/users_guide/Attic/tutorial.lit,v 1.1 1996/01/08 20:25:11 partain Exp $ +% +\section[compiler-tutorial]{Tutorial material about this compilation system} + +This guide assumes quite a bit of knowledge about UNIX compilers and +their conventional use. This section has a little extra information +for those who are new at this racket. + +%************************************************************************ +%* * +\subsection[batch-system-parts]{The (batch) compilation system components} +%* * +%************************************************************************ + +The Glorious Haskell Compilation System, as with most UNIX (batch) +compilation systems, has several interacting parts: +\begin{enumerate} +\item +A {\em driver}\index{driver program} \tr{ghc}\index{ghc}---which you +usually think of as ``the compiler''---is a program that merely +invokes/glues-together the other pieces of the system (listed below), +passing the right options to each, slurping in the right libraries, +etc. + +\item +A {\em literate pre-processor} +\index{literate pre-processor} +\index{pre-processor, literate} +\tr{unlit}\index{unlit} that extracts Haskell +code from a literate script; used if you believe in that sort of +thing. + +\item +The {\em Haskellised C pre-processor} +\index{Haskellised C pre-processor} +\index{C pre-processor, Haskellised} +\index{pre-processor, Haskellised C} +\tr{hscpp},\index{hscpp} only needed by people requiring conditional +compilation, probably for large systems. The ``Haskellised'' part +just means that \tr{#line} directives in the output have been +converted into proper Haskell \tr{{-# LINE ... -}} pragmas. + +You must give an explicit \tr{-cpp} option +\index{-cpp option} for the C pre-processor to be invoked. + +\item +The {\em Haskell compiler} +\index{Haskell compiler} +\index{compiler, Haskell} +\tr{hsc},\index{hsc} +which---in normal use---takes its input from the C pre-processor +and produces assembly-language output (sometimes: ANSI C output). + +\item +The {\em ANSI~C Haskell high-level assembler :-)} +\index{ANSI C compiler} +\index{high-level assembler} +\index{assembler, high-level} +compiles \tr{hsc}'s C output into assembly language for a particular +target architecture. (It doesn't have to be an ANSI C compiler, but +that's preferred; to go fastest, you need GNU C, version 2.x.) + +\item +The {\em assembler}\index{assembler}---a standard UNIX one, probably +\tr{as}\index{as}. + +\item +The {\em linker}\index{linker}---a standard UNIX one, probably +\tr{ld}.\index{ld} + +\item +A {\em runtime system},\index{runtime system} including (most notably) +a storage manager; the linker links in the code for this. + +\item +The {\em Haskell standard prelude}\index{standard prelude}, a +large library of standard functions, is linked in as well. + +\item +Parts of other {\em installed libraries} that you have at your site +may be linked in also. +\end{enumerate} + +%************************************************************************ +%* * +\subsection[compile-what-really-happens]{What really happens when I ``compile'' a Haskell program?} +%* * +%************************************************************************ + +You invoke the Glasgow Haskell compilation system through the +driver program \tr{ghc}.\index{ghc} For example, if you had typed a +literate ``Hello, world!'' program into \tr{hello.lhs}, and you then +invoked: +\begin{verbatim} +ghc hello.lhs +\end{verbatim} + +the following would happen: +\begin{enumerate} +\item +The file \tr{hello.lhs} is run through the literate-program +code extractor \tr{unlit}\index{unlit}, feeding its output to + +\item +The Haskell compiler proper \tr{hsc}\index{hsc}, which produces +input for + +\item +The assembler (or that ubiquitous ``high-level assembler,'' a C +compiler), which produces an object file and passes it to + +\item +The linker, which links your code with the appropriate libraries +(including the standard prelude), producing an executable program in +the default output file named \tr{a.out}. +\end{enumerate} + +You have considerable control over the compilation process. You feed +command-line arguments (call them ``options,'' for short) to the +driver, \tr{ghc}; the ``types'' of the input files (as encoded in +their names' suffixes) also matter. + +Here's hoping this is enough background so that you can read the rest +of this guide! + +% The ``style'' of the driver program \tr{ghc} follows that of the GNU C +% compiler driver \tr{gcc}. The use of environment variables to provide +% defaults is more extensive in this compilation system. diff --git a/ghc/docs/users_guide/user.lit b/ghc/docs/users_guide/user.lit new file mode 100644 index 0000000000..51f63e20a5 --- /dev/null +++ b/ghc/docs/users_guide/user.lit @@ -0,0 +1,36 @@ +\begin{onlystandalone} +\documentstyle[11pt,literate]{article} +\begin{document} +\title{The Glorious Glasgow Haskell Compilation System\\ Version~0.26\\ User's Guide} +\author{The AQUA Team\\ +Department of Computing Science\\ +University of Glasgow\\ +Glasgow, Scotland\\ +G12 8QQ\\ +\\ +Email: glasgow-haskell-\{bugs,request\}\@dcs.glasgow.ac.uk} +\maketitle +\begin{rawlatex} +\tableofcontents +\pagebreak +\end{rawlatex} +\end{onlystandalone} + +\input{intro.lit} +\input{how_to_run.lit} +\input{runtime_control.lit} +\input{sooner.lit} +\input{profiling.lit} +\input{glasgow_exts.lit} +\input{libraries.lit} +\input{parallel.lit} +\input{gone_wrong.lit} +\input{vs_haskell.lit} +\input{utils.lit} +\input{ticky.lit} +\input{tutorial.lit} + +\begin{onlystandalone} +\printindex +\end{document} +\end{onlystandalone} diff --git a/ghc/docs/users_guide/utils.lit b/ghc/docs/users_guide/utils.lit new file mode 100644 index 0000000000..d007621521 --- /dev/null +++ b/ghc/docs/users_guide/utils.lit @@ -0,0 +1,143 @@ +%************************************************************************ +%* * +\section[utils]{Other Haskell utility programs} +\index{utilities, Haskell} +%* * +%************************************************************************ + +This section describes other program(s) which we distribute, that help +with the Great Haskell Programming Task. + +%************************************************************************ +%* * +\subsection[mkdependHS]{Makefile dependencies in Haskell: using \tr{mkdependHS}} +\index{mkdependHS} +\index{Makefile dependencies} +\index{dependencies in Makefiles} +%* * +%************************************************************************ + +It is reasonably straightforward to set up a \tr{Makefile} to use with +GHC, assuming you name your source files the same as your modules. +Thus: +\begin{verbatim} +HC = ghc +HCFLAGS = -fhaskell-1.3 -cpp -hi-diffs $(EXTRA_HC_OPTS) + +SRCS = Main.lhs Foo.lhs Bar.lhs +OBJS = Main.o Foo.o Bar.o + +.SUFFIXES : .o .lhs +.lhs.o: + $(RM) $@ + $(HC) -c $< $(HCFLAGS) + +cool_pgm : $(OBJS) + $(RM) $@ + $(HC) -o $@ $(HCFLAGS) $(OBJS) +\end{verbatim} + +The only thing lacking in the above \tr{Makefile} is interface-file +dependencies. If \tr{Foo.lhs} imports module \tr{Bar} and the +\tr{Bar} interface changes, then \tr{Foo.lhs} needs to be recompiled. + +Putting dependencies of the form \tr{Foo.o : Bar.hi} into your +\tr{Makefile} by hand is rather error-prone. Don't worry---never +fear, \tr{mkdependHS} is here! (and is distributed as part of GHC) +Add the following to your \tr{Makefile}: +\begin{verbatim} +depend : + mkdependHS -- $(HCFLAGS) -- $(SRCS) +\end{verbatim} + +Now, before you start compiling, and any time you change the +\tr{imports} in your program, do \tr{make depend} before you do +\tr{make cool_pgm}. \tr{mkdependHS} will append the needed +dependencies to your \tr{Makefile}. + +A few caveats about this simple scheme: (a)~You may need to compile +some modules explicitly to create their interfaces in the first place +(e.g., \tr{make Bar.o} to create \tr{Bar.hi}). (b)~You may have to +type \tr{make} more than once for the dependencies to have full +effect. However, a \tr{make} run that does nothing {\em does} mean +``everything's up-to-date.'' (c) This scheme will work with +mutually-recursive modules but, again, it may take multiple +iterations to ``settle.'' + +%************************************************************************ +%* * +\subsection[hstags]{Emacs `TAGS' for Haskell: \tr{hstags}} +\index{hstags} +\index{TAGS for Haskell} +%* * +%************************************************************************ + +`Tags' is a facility for indexing the definitions of +programming-language things in a multi-file program, and then using +that index to jump around among these definitions. + +Rather than scratch your head, saying ``Now where did we define +`foo'?'', you just do (in Emacs) \tr{M-. foo RET}, and You're There! +Some people go wild over this stuff... + +GHC comes with a program \tr{hstags}, which build Emacs-able TAGS +files. The invocation syntax is: +\begin{verbatim} +hstags [GHC-options] file [files...] +\end{verbatim} + +The best thing is just to feed it your GHC command-line flags. +A good Makefile entry might be: +\begin{verbatim} +tags: + $(RM) TAGS + hstags $(GHC_FLAGS) *.lhs +\end{verbatim} + +The only flags of its own are: \tr{-v} to be verbose; \tr{-a} to +**APPEND** to the TAGS file, rather than write to it. + +Shortcomings: (1)~Instance declarations don't get into the TAGS file +(but the definitions inside them do); as instances aren't named, this +is probably just as well. (2)~Data-constructor definitions don't get +in. Go for the corresponding type constructor instead. + +(Actually, GHC also comes with \tr{etags} [for C], and \tr{perltags} +[for You Know What]. And---I cannot tell a lie---there is Denis +Howe's \tr{fptags} [for Haskell, etc.] in the \tr{ghc/CONTRIB} +section...) + +%************************************************************************ +%* * +\subsection[happy]{``Yacc for Haskell'': \tr{happy}} +\index{happy} +\index{Yacc for Haskell} +\index{parser generator for Haskell} +%* * +%************************************************************************ + +Andy Gill and Simon Marlow have written a parser-generator for +Haskell, called \tr{happy}.\index{happy parser generator} \tr{Happy} +is to Haskell what \tr{Yacc} is to C. + +You can get \tr{happy} by FTP from \tr{ftp.dcs.glasgow.ac.uk} in +\tr{pub/haskell/happy}, the file \tr{happy-0.8.tar.gz}. + +\tr{Happy} is at its shining best when compiled by GHC. + +%************************************************************************ +%* * +\subsection[pphs]{Pretty-printing Haskell: \tr{pphs}} +\index{pphs} +\index{pretty-printing Haskell code} +%* * +%************************************************************************ + +Andrew Preece has written +\tr{pphs},\index{pphs}\index{pretty-printing Haskell} +a utility to pretty-print Haskell code in LaTeX documents. +Keywords in bolds, variables in italics---that sort of thing. It is +good at lining up program clauses and equals signs, things that are +very tiresome to do by hand. + +The code is distributed with GHC in \tr{ghc/CONTRIB/pphs}. diff --git a/ghc/docs/users_guide/vs_haskell.lit b/ghc/docs/users_guide/vs_haskell.lit new file mode 100644 index 0000000000..c4fc5e5b7b --- /dev/null +++ b/ghc/docs/users_guide/vs_haskell.lit @@ -0,0 +1,575 @@ +%************************************************************************ +%* * +\section[vs-Haskell-defn]{Haskell~1.2 vs.~Glasgow Haskell~0.26: language non-compliance} +\index{GHC vs the Haskell 1.2 language} +\index{Haskell 1.2 language vs GHC} +%* * +%************************************************************************ + +This section lists Glasgow Haskell infelicities in its implementation +of Haskell~1.2. See also the ``when things go wrong'' section +(\sectionref{wrong}) for information about crashes, space leaks, and +other undesirable phenomena. + +The limitations here are listed in Haskell-Report order (roughly). +%Limitations related to Glasgow extensions (unboxed numbers, etc.) are +%given thereafter (\sectionref{infelicities-Glasgow-exts}). + +%************************************************************************ +%* * +\subsection[infelicities-exprs-pats]{Expressions and patterns} +%* * +%************************************************************************ + +\begin{description} +%------------------------------------------------------------------- +\item[Some valid irrefutable patterns are rejected:] +As syntax errors; just put parentheses around them. + +%------------------------------------------------------------------- +\item[Very long @String@ constants:] +May not go through. If you add a ``string gap'' every +few thousand characters, then the strings can be as long +as you like. + +Bear in mind that string gaps and the \tr{-cpp}\index{-cpp option} +option don't mix. The C-preprocessor may munch the backslashes. + +%------------------------------------------------------------------- +\item[Very long literal lists:] +These may tickle a ``yacc stack overflow'' error in the parser. +(It depends on the Yacc used to build your parser.) +\end{description} + +%************************************************************************ +%* * +\subsection[infelicities-decls]{Declarations and bindings} +%* * +%************************************************************************ + +\begin{description} +%------------------------------------------------------------------- +\item[Contexts on @data@ declarations are ignored:] +Not that they do much, anyway... This won't wreck your life. +(We still [vaguely] plan to add them, however.) + +%------------------------------------------------------------------- +\item[Location of instance declarations is unchecked:] +We don't check that instance declarations occur either in the module +where the class is declared or the module where the data type is +declared. This shouldn't hurt you. + +For better or worse, we {\em do} check if you try to declare a Prelude +instance (Prelude class, Prelude type; e.g., \tr{instance Num Bool}) +in one of your own modules. For some reason, people like to do this! +(But it is not legal Haskell.) + +%------------------------------------------------------------------- +\item[Derived instances of @Text@ for infix constructors:] +All the carry-on about derived @readsPrec@ and @showsPrec@ for infix +constructors---we don't do it (yet). We treat them the same way as +all other constructors. + +%------------------------------------------------------------------- +\item[Derived instances of @Binary@:] +We don't. (We don't do anything @Binary@ish.) +\end{description} + +%************************************************************************ +%* * +\subsection[infelicities-Modules]{Module system and interface files} +%* * +%************************************************************************ + +\begin{description} +%------------------------------------------------------------------- +\item[Duplicates in a `renaming' list:] +Are not reported. + +%------------------------------------------------------------------- +\item[Duplicates in an `import' declaration:] +These are reported as errors, which some might argue they shouldn't +be. We reckon it's a feature, not a bug. + +%------------------------------------------------------------------- +\item[Export of `renamed' class methods:] +Willnae work. That is: you import a class, renaming one or more +methods; then export that class---the renaming of the methods {\em +will not} propagate. + +(Otherwise, `renaming'---disgusting though it may be---should work.) + +%------------------------------------------------------------------- +\item[Fixities/precedences following `renamed' entities that are exported:] +No chance. + +%------------------------------------------------------------------- +\item[\tr{import Foo ()} vs \tr{import Foo}:] +GHC cannot tell the difference (!). + +Given that the only module on which you might want to do the former is +\tr{import Prelude ()}, there are probably much bigger gremlins that +would jump out and bite you if the import {\em did} work. Besides +which, you can achieve the same result with +\tr{-fno-implicit-prelude}.\index{-fno-implicit-prelude option} + +%------------------------------------------------------------------- +\item[Some selective import/export checking not done:] +On selective import and export of type-constructors/classes in +which the data-constructors/methods are named explicitly: +it'll work; it's just that every conceivable paranoia +check won't be done. + +%------------------------------------------------------------------- +\item[Some Prelude entities cannot be hidden:] +For example, this doesn't work: +\begin{verbatim} +import Prelude hiding (readParen) +\end{verbatim} +That's because there are a few should-be-hideable Prelude entities +which need to appear by magic for derived instances. They are +\tr{(&&)}, \tr{(.)}, \tr{lex}, \tr{map}, \tr{not}, \tr{readParen}, +\tr{showParen}, and \tr{showString}. SIGH. + +%------------------------------------------------------------------- +\item[\tr{M..} exports vs multiply-imported entities:] +If an entity \tr{foo} is imported from several interfaces, as in... +\begin{verbatim} +import A1 (foo); import A2 (foo); import A3 (foo) +\end{verbatim} +... and you then do a ``dot dot'' export of \tr{A1} (for example), it +will be {\em pure luck} if \tr{foo} gets exported. This is very sad. + +Workaround: export \tr{foo} explicitly. + +%------------------------------------------------------------------- +\item[\tr{M..} with Prelude interfaces:] +Doing \tr{Prelude<something>..} in an export list; don't even think +it. + +%------------------------------------------------------------------- +\item[Export of Prelude types/classes must be explicit:] + +If you want to export a data type, type synonym or class from a +Prelude module (its name starts with `Prelude'), then it must be +listed explicitly in the export list. If you say: + +\begin{verbatim} +module PreludeMeGently ( PreludeMeGently.. , other_stuff ) where .. +\end{verbatim} + +then the classes/types in \tr{PreludeMeGently} will {\em not} be +exported; just add them to the export list. (This shortcoming is only +likely to affect people writing their own Prelude modules.) + +%------------------------------------------------------------------- +\item[Can't export primitives types (e.g., \tr{Int#}):] + +Don't even try... + +%------------------------------------------------------------------- +\item[Naming errors with \tr{-O} but not without:] + +Documentation by example---Consider a module with these imports: + +\begin{verbatim} +... various imports ... +import Prettyterm -- desired import + +import Pretty -- sadly-needed import +\end{verbatim} + +The \tr{import Pretty} is required because it defines a type +\tr{Pretty.Doc} which is mentioned in \tr{import Prettyterm}. +(Extremely sad, but them's the rules.) + +But without \tr{-O}, GHC uses its \tr{-fuse-get-mentioned-vars} hack +(for speed), trying to avoid looking at parts of interfaces that have +no relevance to this module. As it happens, the thing in +\tr{Prettyterm} that mentions \tr{Pretty.Doc} is not used here, so +this module will go through without \tr{import Pretty}. Nice, but +wrong. +\end{description} + +%************************************************************************ +%* * +\subsection[infelicities-numbers]{Numbers, basic types, and built-in classes} +%* * +%************************************************************************ + +\begin{description} +%------------------------------------------------------------------- +% now in glasgow_exts +%\item[@fromInt@ method in class @Num@:] +% (Non-standard.) We support it, as does HBC. + +%------------------------------------------------------------------- +\item[Very large/small fractional constants:] +(i.e., with a decimal point somewhere) GHC does not check that these +are out of range (e.g., for a @Float@), and bad things will inevitably +follow. To be corrected. + +This problem does {\em not} exist for integral constants. + +For very large/small fractional constants near the limits of your +floating-point precision, things may go wrong. (It's better than it +used to be.) Please report any such bugs. + +%------------------------------------------------------------------- +\item[Unchecked arithmetic:] +Arguably {\em not} an infelicity, but... Bear in mind that operations +on \tr{Int}, \tr{Float}, and \tr{Double} numbers are {\em unchecked} +for overflow, underflow, and other sad occurrences. + +Use \tr{Integer}, \tr{Rational}, etc., numeric types if this stuff keeps you +awake at night. + +%------------------------------------------------------------------- +\item[Multiply-defined array elements---not checked:] +This code fragment {\em should} elicit a fatal error, but it does not: +\begin{verbatim} +main = print (array (1,1) [ 1:=2, 1:=3 ]) +\end{verbatim} + +%------------------------------------------------------------------- +\item[Support for @Binary@ whatnot:] +We don't. +\end{description} + +%************************************************************************ +%* * +\subsection[infelicities-IO]{Dialogue I/O} +%* * +%************************************************************************ + +Dialogue-style I/O---still the default for GHC---is on its way out +(see the stuff about ``monadic I/O for Haskell~1.3''), so we probably +won't fix these shortcomings. + +\begin{description} +%------------------------------------------------------------------- +\item[Support for @Dialogue@ I/O:] +We do not yet support all @Requests@, notably: +@ReadBinFile@, +@WriteBinFile@, +@AppendBinFile@, +@StatusFile@, +@ReadBinChan@, +@AppendBinChan@, +@StatusChan@, +@SetEnv@. Also, we do not support the optional I/O @Requests@. + +\item[@AppendChan@ and @ReadChan@ requests:] +The former only works for \tr{stdout} and \tr{stderr}; the +latter only for \tr{stdin}. + +\item[@Echo@ request:] +We don't do anything at all. +\end{description} + +%************************************************************************ +%* * +\subsection[infelicities-Prelude]{In Prelude support} +%* * +%************************************************************************ + +\begin{description} +%------------------------------------------------------------------- +\item[Arbitrary-sized tuples:] +Plain old tuples of arbitrary size {\em do} work. +Note that lots +of overloading can give rise to large tuples ``under the hood'' of +your program. + +HOWEVER: standard instances for tuples (@Eq@, @Ord@, @Ix@, and +@Binary@) are available {\em only} up to 5-tuples; except @Binary@, +which we don't do at all. + +These limitations are easily subvertible, so please ask if you get +stuck on them. +\end{description} + +%************************************************************************ +%* * +%\subsection[infelicities-Glasgow-exts]{In Glasgow extensions} +%* * +%************************************************************************ + +%\begin{description} +%------------------------------------------------------------------- +%\item[Glasgow extensions not well ``packaged'':] +%We would rather give you tidy interfaces to the primitive extensions +%that GHC provides. For example, instead of your having to muck around +%with... +%\begin{verbatim} +% ... _ccall_ fflush ``stderr'' `thenIO_Int_#` ... +%\end{verbatim} +%... (all very grimy); you should be able to import a \tr{LibC.hi}, and +%pretend that @fflush@ is really a Haskell function! + +%This problem will be fixed when Haskell~1.3 comes into existence, and +%we implement it. + +%------------------------------------------------------------------- +%\item[@ArrRef@s of @Int#@s, @Float#@s, @Double#@s:] +%Are not in yet, but will be. (Easy to add if you're desperate.) +%\end{description} + +%************************************************************************ +%* * +\section[vs-Haskell-1.3]{Haskell~1.3 DRAFT vs.~Glasgow Haskell~0.26} +\index{GHC vs the DRAFT Haskell 1.3 language} +\index{Haskell 1.3 language DRAFT vs GHC} +%* * +%************************************************************************ + +There is work afoot on ``Haskell~1.3,'' a substantial revision of +the Haskell~1.2 language. + +Haskell 1.3 is NOT a standard; it is NOT even a DRAFT standard. As of +June 1995, there exists a 1.3 PROPOSAL, which will CERTAINLY change. +Therefore, the ``1.3 things'' we ``support'' may change ARBITRARILY +much, and we won't even be mildly apologetic about breaking programs +that use ``1.3'' facilities. + +That said, there are two categories of ``1.3'' things that we commend +to you. +\begin{itemize} +\item +Things virtually certain to end up in any 1.3~standard. An example is +the \tr{Maybe} type. +\item +Wobblier things which are so much better than their 1.2 equivalents +that you will want to use them. We mean: monadic I/O. + +The basic I/O functions are ``unlikely'' to change and so are +reasonably safe to adopt. (But see WARNING above...) +\end{itemize} + +To use our 1.3 code, you should compile {\em and link} using a +\tr{-fhaskell-1.3}\index{-fhaskell-1.3 option} flag. + +%************************************************************************ +%* * +\subsection[duffer-1-3]{Duffer's guide for converting 1.2 I/O to 1.3 I/O} +\index{I/O---converting 1.2 to 1.3} +\index{Dialogue I/O--converting to 1.3} +\index{1.2 I/O---converting to 1.3} +%* * +%************************************************************************ + +Here is our ``crib sheet'' for converting 1.2 I/O to 1.3. In most cases, +it's really easy. +\begin{enumerate} +\item +Change \tr{readChan stdin} to \tr{hGetContents stdin}. +\item +Change \tr{appendChan stdout} to \tr{putStr}, which is equivalent to +\tr{hPutStr stdout}. +Change \tr{appendChan stderr} to \tr{hPutStr stderr}. +\item +You need to \tr{import LibSystem} if you used @getArgs@, @getEnv@, +or @getProgName@. +\item +Assuming continuation-style @Dialogue@ code, change \tr{... exit done $} +to \tr{... >>}. Change \tr{... exit $ \ foo ->} to \tr{... >>= \ foo ->}. +\item +If you had any functions named \tr{(>>)}, \tr{(>>=)}, or \tr{return}, +change them to something else. +\end{enumerate} + +%************************************************************************ +%* * +\subsection[nonio-1-3]{Non-I/O things from the 1.3-DRAFT proposal} +%* * +%************************************************************************ + +Besides the I/O stuff, you also get these things when you use the +\tr{-fhaskell-1.3}\index{-fhaskell-1.3 option} flag. + +Once again: ANY of thing might CHANGE COMPLETELY before we have ``1.3 +for real.'' + +\begin{verbatim} +data Either a b = Left a | Right b deriving (Text, Eq, Ord) + +data Maybe a = Nothing | Just a deriving (Eq, Ord, Text) + +thenMaybe :: Maybe a -> (a -> Maybe b) -> Maybe b +thenMaybe Nothing _ = Nothing +thenMaybe (Just x) f = f x + +curry :: ((a,b) -> c) -> a -> b -> c +curry f x y = f (x,y) + +uncurry :: (a -> b -> c) -> (a,b) -> c +uncurry f (x,y) = f x y +\end{verbatim} +\index{Maybe type (Haskell 1.3)} +\index{Either type (Haskell 1.3)} +\index{curry function (Haskell 1.3)} +\index{uncurry function (Haskell 1.3)} + +%************************************************************************ +%* * +\subsection[io-1-3]{Vs~1.3 monadic I/O} +\index{GHC vs the DRAFT 1.3 I/O proposal} +\index{DRAFT 1.3 I/O proposal vs GHC} +%* * +%************************************************************************ + +The most notable improvement in Haskell~1.3 is its I/O, with a shift to +``monadic-style'' I/O. + +We still offer direct access to the so-called \tr{PrimIO} monad, via +the \tr{PreludeGlaST} interface. This is NON-STANDARD, an extension. +This interface is described in \Sectionref{io-1-3-prim-interface}. + +The old \tr{PreludePrimIO} interface is DEAD. + +The even-older \tr{PreludeGlaIO} interface is DEADER. + +%************************************************************************ +%* * +\subsubsection[io-1-3-shortcomings]{Known shortcomings in monadic I/O} +%* * +%************************************************************************ + +Before you begin with ``1.3-style'' monadic I/O, you might as well +know the known shortcomings of our implementation, as at 0.26. + +The error type is called \tr{IOError13}, rather than \tr{IOError} +\index{IOError13 vs IOError} +(which is still the 1.2 type). (Prelude types cannot be renamed, +so...) You probably shouldn't be messing with \tr{IOError} much, +anyway. + +Some of the 1.3 I/O code, notably the Extremely Cool \tr{LibPosix} +stuff, is relatively untested. Go for it, but be wary... +\index{LibPosix bugs} +\index{bugs, LibPosix} + +%************************************************************************ +%* * +\subsubsection[io-1-3-main-interface]{1.3-style monadic I/O} +%* * +%************************************************************************ + +To use our 1.3 I/O, you should compile {\em and link} using a +\tr{-fhaskell-1.3}\index{-fhaskell-1.3 option} flag. + +You should consult the PROPOSED 1.3-I/O standard. GHC~0.26 implements +the ``December 1994'' draft, which we distribute in +\tr{ghc/docs/io-1.3/}. + +Alternatively, you could grab the ``June 1995'' draft, from +\tr{pub/haskell/report/}, on \tr{ftp.dcs.glasgow.ac.uk}. The main +December--June change that you need to know about is: many of the I/O +functions have been removed from \tr{Prelude*} interfaces (no import +required) and put into \tr{Lib*} interfaces (import required). + +GHC~0.26 still provides the I/O functions via \tr{Prelude.hi} (no +import required). Ignore the ``June draft'' pleadings for +\tr{import LibIO}, and you'll be fine. + +{\em There is no guarantee that the final 1.3 proposal will look +anything like the current DRAFT.} It ain't a standard until the fat +committee sings. + +For interaction with our non-standard \tr{PrimIO}, including +\tr{_ccall_}s. we also provide: +\begin{verbatim} +-- impedance matching stuff +ioToPrimIO :: IO a -> PrimIO a +\end{verbatim} + +%************************************************************************ +%* * +\subsubsection[io-1-3-prim-interface]{Access to the \tr{PrimIO} monad} +\index{PrimIO monad (Glasgow extension)} +\index{I/O, primitive (Glasgow extension)} +%* * +%************************************************************************ + +In what we have implemented, \tr{PrimIO} is the +handle-the-errors-yourself monad (NB: used for C-calls and such); +whereas \tr{IO} is the 1.3-ish we-handle-errors-for-you monad. + +Should you may need to play with the \tr{PrimIO} monad directly, you +can import \tr{PreludeGlaST}. + +NB: You used to get this stuff from the \tr{PreludePrimIO} interface, +which is now deceased. As of 0.26, you get all things +state-transforming from the \tr{PreludeGlaST} interface. + +The usual monadic stuff for \tr{PrimIO}: +\begin{verbatim} +returnPrimIO :: a -> PrimIO a +thenPrimIO :: PrimIO a -> (a -> PrimIO b) -> PrimIO b +seqPrimIO :: PrimIO a -> PrimIO b -> PrimIO b +fixPrimIO :: (a -> PrimIO a) -> PrimIO a +foldrPrimIO :: (a -> b -> PrimIO b) -> PrimIO b -> [a] -> PrimIO b +listPrimIO :: [PrimIO a] -> PrimIO [a] +mapPrimIO :: (a -> PrimIO b) -> [a] -> PrimIO [b] +mapAndUnzipPrimIO :: (a -> PrimIO (b,c)) -> [a] -> PrimIO ([b],[c]) +forkPrimIO :: PrimIO a -> PrimIO a + +unsafePerformPrimIO :: PrimIO a -> a +unsafeInterleavePrimIO :: PrimIO a -> PrimIO a + -- and they are not called "unsafe" for nothing! +\end{verbatim} + +And some other stuff: +\begin{verbatim} +data _FILE -- corresponds to a "FILE *" in C + -- in classes Eq, _CCallable, and _CReturnable + +fclose :: _FILE -> PrimIO Int +fdopen :: Int -> String -> PrimIO _FILE +fflush :: _FILE -> PrimIO Int +fopen :: String -> String -> PrimIO _FILE +fread :: Int -> Int -> _FILE -> PrimIO (Int, _ByteArray Int) +freopen :: String -> String -> _FILE -> PrimIO _FILE +fwrite :: _ByteArray Int -> Int -> Int -> _FILE -> PrimIO Int + +-- please AVOID using these (They will probably die) +appendChanPrimIO :: String -> String -> PrimIO () +appendFilePrimIO :: String -> String -> PrimIO () +getArgsPrimIO :: PrimIO [String] +readChanPrimIO :: String -> PrimIO String +\end{verbatim} + +%************************************************************************ +%* * +\subsubsection[own-mainPrimIO]{Using your own @mainPrimIO@} +\index{mainPrimIO, rolling your own} +%* * +%************************************************************************ + +Normally, the GHC runtime system begins things by called an internal +function @mainPrimIO :: PrimIO ()@ which, in turn, fires up +@dialogueToIO :: Dialogue -> IO ()@, linking in {\em your} @Main.main@ +to provide the @Dialogue@. + +(If you give a \tr{-fhaskell-1.3} flag, then a {\em different} +@mainPrimIO@ will be linked in---that's why it is important to link +with \tr{-fhaskell-1.3}...) + +To subvert the above process, you need only provide +a @mainPrimIO :: PrimIO ()@ of your own +(in a module named \tr{Main}). Do {\em not} use a \tr{-fhaskell-1.3} flag! + +Here's a little example, stolen from Alastair Reid: +\begin{verbatim} +module Main ( mainPrimIO ) where + +import PreludeGlaST + +mainPrimIO :: PrimIO () +mainPrimIO = + sleep 5 `seqPrimIO` + _ccall_ printf "%d\n" (14::Int) + +sleep :: Int -> PrimIO () +sleep t = _ccall_ sleep t +\end{verbatim} |