X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fintro.sgml;h=6e877b45cda6d19ae59bc3e3b84c31a0918235a3;hb=49c120b93b0688863d46582eee6b20bfbed6c077;hp=828eb0ef31ab3c3bf2deff464bf1d02775429c8d;hpb=36a21908ebf86c6d7596abbf588588f3e487c8ae;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/intro.sgml b/ghc/docs/users_guide/intro.sgml index 828eb0e..6e877b4 100644 --- a/ghc/docs/users_guide/intro.sgml +++ b/ghc/docs/users_guide/intro.sgml @@ -1,219 +1,48 @@ - -Introduction to GHC - - - -This is a guide to using the Glasgow Haskell compilation (GHC) system. It is -a batch compiler for the Haskell 98 language, with support for various -Glasgow-only extensions. In this document, we assume that GHC has been -installed at your site as ghc. A separate document, -“Building and Installing the Glasgow Functional Programming Tools Suite”, -describes how to install ghc. - - - -Many people will use GHC very simply: compile some -modules—ghc -c -O Foo.hs Bar.hs; and link them— -ghc -o wiggle -O Foo.o Bar.o. - - - -But if you need to do something more complicated, GHC can do that, -too: - - -ghc -c -O -fno-foldr-build -dcore-lint -fvia-C -ddump-simpl Foo.lhs - - -Stay tuned—all will be revealed! - - - -The rest of this section provide some tutorial information -on batch-style compilation; if you're familiar with these concepts -already, then feel free to skip to the next section. - - - -The (batch) compilation system components - - -The Glorious Haskell Compilation System, as with most UNIX (batch) -compilation systems, has several interacting parts: - - - - -A driverdriver -program -ghcghc—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. - - - - - -A literate pre-processor -literate pre-processor -pre-processor, literate -unlitunlit that extracts Haskell -code from a literate script; used if you believe in that sort of -thing. - - - - - -The Haskellised C pre-processor -Haskellised C pre-processor -C pre-processor, Haskellised -pre-processor, Haskellised C -hscpp,hscpp only needed by people requiring conditional -compilation, probably for large systems. The “Haskellised” part -just means that #line directives in the output have been -converted into proper Haskell {-# LINE ... -} pragmas. You must give an explicit -cpp option --cpp option for the C pre-processor to be invoked. - - - - - -The Haskell compiler -Haskell compiler -compiler, Haskell -hsc,hsc -which—in normal use—takes its input from the C pre-processor -and produces assembly-language output (sometimes: ANSI C output). - - - - - -The ANSI C Haskell high-level assembler :-) -ANSI C compiler -high-level assembler -assembler, high-level -compiles hsc's C output into assembly language for a particular -target architecture. In fact, the only C compiler we currently -support is gcc, because we make use of certain extensions to the -C language only supported by gcc. Version 2.x is a must; we recommend -version 2.7.2.1 for stability (we've heard both good and bad reports -of later versions). - - - - - -The assemblerassembler—a standard UNIX one, probably -asas. - - - - - -The linkerlinker—a standard UNIX one, probably -ld.ld - - - - - -A runtime system,runtime system including (most notably) -a storage manager; the linker links in the code for this. - - - - - -The Haskell standard preludestandard prelude, a -large library of standard functions, is linked in as well. - - - - - -Parts of other installed libraries that you have at your site may be linked in also. - - - - - - - - - -What really happens when I “compile” a Haskell program? - - - -You invoke the Glasgow Haskell compilation system through the -driver program ghc.ghc For example, if you had typed a -literate “Hello, world!” program into hello.lhs, and you then -invoked: - - -ghc hello.lhs - - - - - -the following would happen: - - - - - -The file hello.lhs is run through the literate-program -code extractor unlitunlit, feeding its output to - - - - - - -The Haskell compiler proper hschsc, which produces -input for - - - - - - -The assembler (or that ubiquitous “high-level assembler,” a C -compiler), which produces an object file and passes it to - - - - - - -The linker, which links your code with the appropriate libraries -(including the standard prelude), producing an executable program in -the default output file named a.out. - - - - - - - - -You have considerable control over the compilation process. You feed -command-line arguments (call them “options,” for short) to the -driver, 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! - - - + + Introduction to GHC + + This is a guide to using the Glasgow Haskell Compiler (GHC): + an interactive and batch compilation system for the Haskell 98 + language. + + GHC has two main components: an interactive Haskell + interpreter (also known as GHCi), described in , and a batch compiler, described throughout . In fact, GHC consists of a single program + which is just run with different options to provide either the + interactive or the batch system. + + The batch compiler can be used alongside GHCi: compiled + modules can be loaded into an interactive session and used in the + same way as interpreted code, and in fact when using GHCi most of + the library code will be pre-compiled. This means you get the best + of both worlds: fast pre-compiled library code, and fast compile + turnaround for the parts of your program being actively + developed. + + GHC supports numerous language extensions, including + concurrency, a foreign function interface, exceptions, type system + extensions such as multi-parameter type classes, local universal and + existential quantification, functional dependencies, scoped type + variables and explicit unboxed types. These are all described in + . + + GHC has a comprehensive optimiser, so when you want to Really + Go For It (and you've got time to spare) GHC can produce pretty fast + code. Alternatively, the default option is to compile as fast as + possible while not making too much effort to optimise the generated + code (although GHC probably isn't what you'd describe as a fast + compiler :-). + + GHC's profiling system supports “cost centre + stacks”: a way of seeing the profile of a Haskell program in a + call-graph like structure. See for more + details. + + GHC comes with a large collection of libraries, with + everything from parser combinators to networking. The libraries are + described in separate documentation. Meta-information: Web sites, mailing lists, etc. @@ -221,138 +50,268 @@ of this guide! mailing lists, Glasgow Haskell Glasgow Haskell mailing lists -On the World-Wide Web, there are several URLs of likely -interest: - - - - - - - - Haskell home page - - - - - - GHC home page - - - - - - comp.lang.functional FAQ - - - - - - - - -We run two mailing lists about Glasgow Haskell. We encourage you to -join, as you feel is appropriate. - - - - - - -glasgow-haskell-users: - - -This list is for GHC users to chat among themselves. Subscribe by -sending mail to majordomo@haskell.org, with a message -body (not header) like this: - - - - - -subscribe glasgow-haskell-users MyName <m.y.self@bigbucks.com> - - - - - -(The last bit is your all-important e-mail address, of course.) - - - -To communicate with your fellow users, send mail to glasgow-haskell-users@haskell.org. - - - -To contact the list administrator, send mail to -owner-glasgow-haskell-users@haskell.org. An archive -of the list is available on the Web at the glasgow-haskell-users -mailing list archive. - - - - -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 majordomo@haskell.org with: - - - - - -subscribe glasgow-haskell-bugs My Name <m.y.self@hackers.r.us> - - - - - -Again, you may contact the list administrator at owner-glasgow-haskell-bugs@haskell.org. -And, yes, an archive of the list is available on the Web at the -glasgow-haskell-bugs mailing list archive - - - - - - - -There is also the general Haskell mailing list. Subscribe by sending -email to majordomo@haskell.org, with the usual message body: - - - - - -subscribe haskell My Name <m.y.self@fp.rules.ok.org> - - - - - -Some Haskell-related discussion takes place in the Usenet newsgroup -comp.lang.functional. - - - + On the World-Wide Web, there are several URLs of likely + interest: + + + + Haskell home + page + + + + GHC home + page + + + + comp.lang.functional + FAQ + + + + + We run the following mailing lists about Glasgow Haskell. + We encourage you to join, as you feel is appropriate. + + + + glasgow-haskell-users: + + This list is for GHC users to chat among themselves. + If you have a specific question about GHC, please check the + FAQ first (). + + + + list email address: + + glasgow-haskell-users@haskell.org + + + + + subscribe at: + + http://www.haskell.org/mailman/listinfo/glasgow-haskell-users. + + + + + admin email address: + + glasgow-haskell-users-admin@haskell.org + + + + + list archives: + + http://www.haskell.org/pipermail/glasgow-haskell-users/ + + + + + + + + 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. + + + + list email address: + + glasgow-haskell-bugs@haskell.org + + + + + subscribe at: + + http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs. + + + + + admin email address: + + glasgow-haskell-bugs-admin@haskell.org + + + + + list archives: + + http://www.haskell.org/pipermail/glasgow-haskell-bugs/ + + + + + + + + cvs-ghc: + + The hardcore GHC developers hang out here. This list + also gets commit message from the CVS repository. There are + several other similar lists for other parts of the CVS + repository (eg. cvs-hslibs, + cvs-happy, cvs-hdirect + etc.) + + + + list email address: + + cvs-ghc@haskell.org + + + + + subscribe at: + + http://www.haskell.org/mailman/listinfo/cvs-ghc. + + + + + admin email address: + + cvs-ghc-admin@haskell.org + + + + + list archives: + + http://www.haskell.org/pipermail/cvs-ghc/ + + + + + + + + There are several other haskell and GHC-related mailing + lists served by www.haskell.org. Go to http://www.haskell.org/mailman/listinfo/ + for the full list. + + Some Haskell-related discussion also takes place in the + Usenet newsgroup comp.lang.functional. + + + + + Reporting bugs in GHC + bugsreporting + + reporting bugs + + + Glasgow Haskell is a changing system so there are sure to be + bugs in it. + + To report a bug, either: + + + + Go to the SoureForge GHC + page, go to the bugs section, click on + submit, and enter your bug report. You can also + check the outstanding bugs here and search the archives to make + sure it hasn't already been reported. Or: + + + Email your bug report to + glasgow-haskell-bugs@haskell.org. + + + + + How do I tell if I should report my bug? + + Take a look at the FAQ () and , which will give you some guidance as to + whether the behaviour you're seeing is really a bug or + not. + + If it is a bug, then it might have been reported before: + try searching the mailing list archives. The archives don't + have a built-in search facility, but we find that Google's site search works + pretty well: enter + site:www.haskell.org followed + by your search term into Google. + + If in doubt, just report it. + + + + What to put in a bug report + bug reportscontents + + The name of the bug-reporting game is: facts, facts, + facts. Don't omit them because “Oh, they won't be + interested…” + + + + What kind of machine are you running on, and exactly + what version of the operating system are you using? + (on a Unix system, uname -a or cat + /etc/motd will show the desired information.) + + + + What version of GCC are you using? gcc + -v will tell you. + + + + 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. + + + + Be sure any Haskell compilations are run with a + (verbose) flag, so we can see exactly + what was run, what versions of things you have, etc. + + + + What is the program behaviour that is wrong, in your + opinion? + + + + If practical, please send enough source files for us + to duplicate the problem. + + + + If you are a Hero and track down the problem in the + compilation-system sources, please send us patches relative + to a known released version of GHC, or whole files if you + prefer. + + + + GHC version numbering policy @@ -372,7 +331,7 @@ Some Haskell-related discussion takes place in the Usenet newsgroup is zero). Patchlevels are bug-fix releases only, and never change the programmer interface to any system-supplied code. However, if you install a new patchlevel over an old one you - may need to recompile any code that was compiled against the + will need to recompile any code that was compiled against the old libraries. The value of __GLASGOW_HASKELL__ @@ -394,8 +353,8 @@ Some Haskell-related discussion takes place in the Usenet newsgroup GHC web site for details). Snapshot releases are named - x.yy.DDMMYYYY where yy - is odd, and DDMMYYYY + x.yy.YYYYMMDD where yy + is odd, and YYYYMMDD is the date of the sources from which the snapshot was built. In theory, you can check out the exact same sources from the CVS repository using this date. @@ -419,11 +378,12 @@ Some Haskell-related discussion takes place in the Usenet newsgroup The version number of your copy of GHC can be found by invoking ghc with the - --version flag. + ––version flag (see ). -&relnotes +&relnotes;