diff options
| author | rrt <unknown> | 2000-01-05 11:20:25 +0000 |
|---|---|---|
| committer | rrt <unknown> | 2000-01-05 11:20:25 +0000 |
| commit | a13f31cc8f8da4e71ee252dfcf838993a16e032f (patch) | |
| tree | b3d9ed8434d7dd627360c2eb072d494c312770f6 /ghc/docs/users_guide/using.vsgml | |
| parent | c7f8f1e62b555462f98c3f813440559116033a99 (diff) | |
| download | haskell-a13f31cc8f8da4e71ee252dfcf838993a16e032f.tar.gz | |
[project @ 2000-01-05 11:20:23 by rrt]
VSGML files removed because of conversion from LinuxDoc to DocBook (now
have just SGML files).
Diffstat (limited to 'ghc/docs/users_guide/using.vsgml')
| -rw-r--r-- | ghc/docs/users_guide/using.vsgml | 1664 |
1 files changed, 0 insertions, 1664 deletions
diff --git a/ghc/docs/users_guide/using.vsgml b/ghc/docs/users_guide/using.vsgml deleted file mode 100644 index 88d404ad28..0000000000 --- a/ghc/docs/users_guide/using.vsgml +++ /dev/null @@ -1,1664 +0,0 @@ -<sect> Using GHC -<label id="using-GHC"> -<p> -<nidx>GHC, using</nidx> -<nidx>using GHC</nidx> - -GHC is a command-line compiler: in order to compile a Haskell program, -GHC must be invoked on the source file(s) by typing a command to the -shell. The steps involved in compiling a program can be automated -using the @make@ tool (this is especially useful if the program -consists of multiple source files which depend on each other). This -section describes how to use GHC from the command-line. - -%************************************************************************ -%* * -<sect1> Overall command-line structure -<label id="command-line-structure"> -<p> -<nidx>structure, command-line</nidx> -<nidx>command-line structure</nidx> -%* * -%************************************************************************ - -An invocation of GHC takes the following form: - -<tscreen> <verb> -ghc [argument...] -</verb> </tscreen> - -Command-line arguments are either options or file names. - -Command-line options begin with @-@. They may <em>not</em> be -grouped: @-vO@ is different from @-v -O@. Options need not -precede filenames: e.g., @ghc *.o -o foo@. All options are -processed and then applied to all files; you cannot, for example, invoke -@ghc -c -O1 Foo.hs -O2 Bar.hs@ to apply different optimisation -levels to the files @Foo.hs@ and @Bar.hs@. For conflicting -options, e.g., @-c -S@, we reserve the right to do anything we -want. (Usually, the last one applies.) - -%************************************************************************ -%* * -<sect1>Meaningful file suffixes -<label id="file-suffixes"> -<p> -<nidx>suffixes, file</nidx> -<nidx>file suffixes for GHC</nidx> -%* * -%************************************************************************ - -File names with ``meaningful'' suffixes (e.g., @.lhs@ or @.o@) -cause the ``right thing'' to happen to those files. - -<descrip> -<tag>@.lhs@:</tag> -<nidx>lhs suffix</nidx> -A ``literate Haskell'' module. - -<tag>@.hs@:</tag> -A not-so-literate Haskell module. - -<tag>@.hi@:</tag> -A Haskell interface file, probably compiler-generated. - -<tag>@.hc@:</tag> -Intermediate C file produced by the Haskell compiler. - -<tag>@.c@:</tag> -A C~file not produced by the Haskell compiler. - -% <tag>@.i@:</tag> -% C code after it has be preprocessed by the C compiler (using the -% @-E@ flag). - -<tag>@.s@:</tag> -An assembly-language source file, usually -produced by the compiler. - -<tag>@.o@:</tag> -An object file, produced by an assembler. -</descrip> - -Files with other suffixes (or without suffixes) are passed straight -to the linker. - -%************************************************************************ -%* * -<sect1>Help and verbosity options -<label id="options-help"> -<p> -<nidx>help options (GHC)</nidx> -<nidx>verbose option (GHC)</nidx> -%* * -%************************************************************************ - -A good option to start with is the @-help@ (or @-?@) option. -<nidx>-help option</nidx> -<nidx>-? option</nidx> -GHC spews a long message to standard output and then exits. - -The @-v@<nidx>-v option</nidx> option makes GHC <em>verbose</em>: it -reports its version number and shows (on stderr) exactly how it invokes each -phase of the compilation system. Moreover, it passes -the @-v@ flag to most phases; each reports -its version number (and possibly some other information). - -Please, oh please, use the @-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. - -If you're just interested in the compiler version number, the -@--version@<nidx>--version option</nidx> option prints out a -one-line string containing the requested info. - -%************************************************************************ -%* * -<sect1>Running the right phases in the right order -<label id="options-order"> -<p> -<nidx>order of passes in GHC</nidx> -<nidx>pass ordering in GHC</nidx> -%* * -%************************************************************************ - -The basic task of the @ghc@ driver is to run each input file -through the right phases (compiling, 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: - -<tabular ca="llll"> -Phase of the | Suffix saying | Flag saying | (suffix of) @@ -compilation system | ``start here''| ``stop after''| output file @@ -@@ -literate pre-processor | .lhs | - | - @@ -C pre-processor (opt.) | - | - | - @@ -Haskell compiler | .hs | -C, -S | .hc, .s @@ -C compiler (opt.) | .hc or .c | -S | .s @@ -assembler | .s | -c | .o @@ -linker | other | - | a.out @@ -</tabular> -<nidx>-C option</nidx> -<nidx>-S option</nidx> -<nidx>-c option</nidx> - -Thus, a common invocation would be: @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 option @-cpp@<nidx>-cpp option</nidx> must be given for the C -pre-processor phase to be run, that is, the pre-processor will be run -over your Haskell source file before continuing. - -The option @-E@<nidx>-E option</nidx> runs just the pre-processing -passes of the compiler, outputting the result on stdout before -stopping. If used in conjunction with -cpp, the output is the -code blocks of the original (literal) source after having put it -through the grinder that is the C pre-processor. Sans @-cpp@, the -output is the de-litted version of the original source. - -The option @-optcpp-E@<nidx>-optcpp-E option</nidx> runs just the -pre-processing stage of the C-compiling phase, sending the result to -stdout. (For debugging or obfuscation contests, usually.) - -%************************************************************************ -%* * -<sect1>Re-directing the compilation output(s) -<label id="options-output"> -<p> -<nidx>output-directing options</nidx> -%* * -%************************************************************************ - -GHC's compiled output normally goes into a @.hc@, @.o@, etc., file, -depending on the last-run compilation phase. The option @-o -foo@<nidx>-o option</nidx> re-directs the output of that last-run -phase to file @foo@. - -Note: this ``feature'' can be counterintuitive: -@ghc -C -o foo.o foo.hs@ will put the intermediate C code in the -file @foo.o@, name notwithstanding! - -EXOTICA: But the @-o@ option isn't of much use if you have -<em>several</em> 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 @-odir <dir>@<nidx>-odir <dir> option</nidx> (the -``Oh, dear'' option). For example: - -<tscreen><verb> -% ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` -</verb></tscreen> - -The output files, @Foo.o@, @Bar.o@, and @Bumble.o@ would be -put into a subdirectory named after the architecture of the executing -machine (@sun4@, @mips@, etc). The directory must already -exist; it won't be created. - -Note that the @-odir@ option does <em>not</em> affect where the -interface files are put. In the above example, they would still be -put in @parse/Foo.hi@, @parse/Bar.hi@, and @gurgle/Bumble.hi@. - -MORE EXOTICA: The @-osuf <suffix>@<nidx>-osuf <suffix> -option</nidx> will change the @.o@ file suffix for object files to -whatever you specify. (We use this in compiling the prelude.). -Similarly, the @-hisuf <suffix>@<nidx>-hisuf <suffix> -option</nidx> will change the @.hi@ file suffix for non-system -interface files (see Section <ref name="Other options related to -interface files" id="hi-options">). - -The @-hisuf@/@-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 @.hi@/@.o@ suffixes; add @-hisuf g_hi -osuf g_o@ to your -@make@ rule for GHC compiling... - -FURTHER EXOTICA: If you are doing a normal @.hs@-to-@.o@ compilation -but would like to hang onto the intermediate @.hc@ C file, just -throw in a @-keep-hc-file-too@ option<nidx>-keep-hc-file-too option</nidx>. -If you would like to look at the assembler output, toss in a -@-keep-s-file-too@,<nidx>-keep-s-file-too option</nidx> too. - -<sect2> Saving GHC's standard error output -<label id="saving-ghc-stderr"> -<p> -<nidx>standard error, saving</nidx> - -Sometimes, you may cause GHC to be rather chatty on standard error; -with @-v@, for example. You can instruct GHC to <em>append</em> this -output to a particular log file with a @-odump <blah>@<nidx>-odump -<blah> option</nidx> option. - -<sect2> Redirecting temporary files -<label id="temp-files"> -<p> -<nidx>temporary files, redirecting</nidx> - -If you have trouble because of running out of space in @/tmp@ (or -wherever your installation thinks temporary files should go), you may -use the @-tmpdir <dir>@<nidx>-tmpdir <dir> option</nidx> option -to specify an alternate directory. For example, @-tmpdir .@ says to -put temporary files in the current working directory. - -Alternatively, use your @TMPDIR@ environment variable.<nidx>TMPDIR -environment variable</nidx> Set it to the name of the directory where -temporary files should be put. GCC and other programs will honour the -@TMPDIR@ variable as well. - -Even better idea: Set the @TMPDIR@ variable when building GHC, and -never worry about @TMPDIR@ again. (see the build documentation). - -%************************************************************************ -%* * -<sect1>Warnings and sanity-checking -<label id="options-sanity"> -<p> -<nidx>sanity-checking options</nidx> -<nidx>warnings</nidx> -%* * -%************************************************************************ - -GHC has a number of options that select which types of non-fatal error -messages, otherwise known as warnings, can be generated during -compilation. By default, you get a standard set of warnings which are -generally likely to indicate bugs in your program. These are: -@-fwarn-overlpapping-patterns@, @-fwarn-duplicate-exports@, and -@-fwarn-missing-methods@. The following flags are simple ways to -select standard ``packages'' of warnings: - -<descrip> - -<tag>@-Wnot@:</tag> -<nidx>-Wnot option</nidx> - -Turns off all warnings, including the standard ones. - -<tag>@-w@:</tag> -<nidx>-w option</nidx> - -Synonym for @-Wnot@. - -<tag>@-W@:</tag> -<nidx>-W option</nidx> - -Provides the standard warnings plus @-fwarn-incomplete-patterns@, -@-fwarn-unused-imports@ and @-fwarn-unused-binds@. - -<tag>@-Wall@:</tag> -<nidx>-Wall option</nidx> - -Turns on all warning options. - -</descrip> - -The full set of warning options is described below. To turn off any -warning, simply give the corresponding @-fno-warn-...@ option on -the command line. - -<descrip> - -<tag>@-fwarn-name-shadowing@:</tag> -<nidx>-fwarn-name-shadowing option</nidx> -<nidx>shadowing, warning</nidx> - -This option causes a warning to be emitted whenever an inner-scope -value has the same name as an outer-scope value, i.e. the inner value -shadows the outer one. This can catch typographical errors that turn -into hard-to-find bugs, e.g., in the inadvertent cyclic definition -@let x = ... x ... in@. - -Consequently, this option does <em>not</em> allow cyclic recursive -definitions. - -<tag>@-fwarn-overlapping-patterns@:</tag> -<nidx>-fwarn-overlapping-patterns option</nidx> -<nidx>overlapping patterns, warning</nidx> -<nidx>patterns, overlapping</nidx> - -By default, the compiler will warn you if a set of patterns are -overlapping, i.e., - -<tscreen><verb> -f :: String -> Int -f [] = 0 -f (_:xs) = 1 -f "2" = 2 -</verb></tscreen> - -where the last pattern match in @f@ won't ever be reached, as the -second pattern overlaps it. More often than not, redundant patterns -is a programmer mistake/error, so this option is enabled by default. - -<tag>@-fwarn-incomplete-patterns@:</tag> -<nidx>-fwarn-incomplete-patterns option</nidx> -<nidx>incomplete patterns, warning</nidx> -<nidx>patterns, incomplete</nidx> - -Similarly for incomplete patterns, the function @g@ below will fail -when applied to non-empty lists, so the compiler will emit a warning -about this when @-fwarn-incomplete-patterns@ is enabled. - -<tscreen><verb> -g [] = 2 -</verb></tscreen> - -This option isn't enabled be default because it can be a bit noisy, -and it doesn't always indicate a bug in the program. However, it's -generally considered good practice to cover all the cases in your -functions. - -<tag>@-fwarn-missing-methods@:</tag> -<nidx>-fwarn-missing-methods option</nidx> -<nidx>missing methods, warning</nidx> -<nidx>methods, missing</nidx> - -This option is on by default, and warns you whenever an instance -declaration is missing one or more methods, and the corresponding -class declaration has no default declaration for them. - -<tag>@-fwarn-missing-fields@:</tag> -<nidx>-fwarn-missing-fields option</nidx> -<nidx>missing fields, warning</nidx> -<nidx>fields, missing</nidx> - -This option is on by default, and warns you whenever the construction -of a labelled field constructor isn't complete, missing initializers -for one or more fields. While not an error (the missing fields are -initialised with bottoms), it is often an indication of a programmer -error. - -<tag>@-fwarn-unused-imports@:</tag> -<nidx>-fwarn-unused-imports option</nidx> -<nidx>unused imports, warning</nidx> -<nidx>imports, unused</nidx> - -Report any objects that are explicitly imported but never used. - -<tag>@-fwarn-unused-binds@:</tag> -<nidx>-fwarn-unused-binds option</nidx> -<nidx>unused binds, warning</nidx> -<nidx>binds, unused</nidx> - -Report any function definitions (and local bindings) which are unused. -For top-level functions, the warning is only given if the binding is -not exported. - -<tag>@-fwarn-unused-matches@:</tag> -<nidx>-fwarn-unused-matches option</nidx> -<nidx>unused matches, warning</nidx> -<nidx>matches, unused</nidx> - -Report all unused variables which arise from pattern matches, -including patterns consisting of a single variable. For instance @f x -y = []@ would report @x@ and @y@ as unused. To eliminate the warning, -all unused variables can be replaced with wildcards. - -<tag>@-fwarn-duplicate-exports@:</tag> -<nidx>-fwarn-duplicate-exports option</nidx> -<nidx>duplicate exports, warning</nidx> -<nidx>export lists, duplicates</nidx> - -Have the compiler warn about duplicate entries in export lists. This -is useful information if you maintain large export lists, and want to -avoid the continued export of a definition after you've deleted (one) -mention of it in the export list. - -This option is on by default. - -<tag><tt>-fwarn-type-defaults</tt>:</tag> -<nidx>-fwarn-type-defaults option</nidx> -<nidx>defaulting mechanism, warning</nidx> - -Have the compiler warn/inform you where in your source the Haskell -defaulting mechanism for numeric types kicks in. This is useful -information when converting code from a context that assumed one -default into one with another, e.g., the 'default default' for Haskell -1.4 caused the otherwise unconstrained value <tt>1</tt> to be given -the type <tt>Int</tt>, whereas Haskell 98 defaults it to -<tt>Integer</tt>. This may lead to differences in performance and -behaviour, hence the usefulness of being non-silent about this. - -This warning is off by default. - -<tag>@-fwarn-missing-signatures@:</tag> -<nidx>-fwarn-missing-signatures option</nidx> -<nidx>type signatures, missing</nidx> - -If you would like GHC to check that every top-level function/value has -a type signature, use the @-fwarn-missing-signatures@ option. This -option is off by default. - -</descrip> - -If you're feeling really paranoid, the @-dcore-lint@ -option<nidx>-dcore-lint option</nidx> is a good choice. It turns on -heavyweight intra-pass sanity-checking within GHC. (It checks GHC's -sanity, not yours.) - -%************************************************************************ -%* * -<sect1>Separate compilation -<label id="separate-compilation"> -<p> -<nidx>separate compilation</nidx> -<nidx>recompilation checker</nidx> -<nidx>make and recompilation</nidx> -%* * -%************************************************************************ - -This section describes how GHC supports separate compilation. - -<sect2>Interface files -<label id="hi-files"> -<p> -<nidx>interface files</nidx> -<nidx>.hi files</nidx> - -When GHC compiles a source file @F@ which contains a module @A@, say, -it generates an object @F.o@, <em>and</em> a companion <em>interface -file</em> @A.hi@. The interface file is not intended for human -consumption, as you'll see if you take a look at one. It's merely -there to help the compiler compile other modules in the same program. - -NOTE: <em>The name of the interface file is derived from the name -of the module, not from the name of the file containing the module</em>. -This means that GHC knows what to look for when it sees <tt>import A</tt> -in another module. However, having the name of the interface file follow the module name and -not the file name, means that working with tools such as @make(1)@ -become harder. @make@ implicitly assumes that any output files -produced by processing a translation unit will have file names that -can be derived from the file name of the translation unit. For -instance, pattern rules becomes unusable. For this reason, we -recommend you stick to using the same file name as the module name. - -The interface file for @A@ contains information needed by the compiler -when it compiles any module @B@ that imports @A@, whether directly or -indirectly. When compiling @B@, GHC will read @A.hi@ to find the -details that it needs to know about things defined in @A@. - -Furthermore, when compiling module @C@ which imports @B@, GHC may -decide that it needs to know something about @A@ --- for example, @B@ -might export a function that involves a type defined in @A@. In this -case, GHC will go and read @A.hi@ even though @C@ does not explicitly -import @A@ at all. - -The interface file may contain all sorts of things that aren't -explicitly exported from @A@ by the programmer. For example, even -though a data type is exported abstractly, @A.hi@ will contain the -full data type definition. For small function definitions, @A.hi@ -will contain the complete definition of the function. For bigger -functions, @A.hi@ will contain strictness information about the -function. And so on. GHC puts much more information into @.hi@ files -when optimisation is turned on with the @-O@ flag. Without @-O@ it -puts in just the minimum; with @-O@ it lobs in a whole pile of stuff. -<nidx>optimsation, effect on .hi files</nidx> - -@A.hi@ should really be thought of as a compiler-readable version of -@A.o@. If you use a @.hi@ file that wasn't generated by the same -compilation run that generates the @.o@ file the compiler may assume -all sorts of incorrect things about @A@, resulting in core dumps and -other unpleasant happenings. - -%************************************************************************ -%* * -<sect2>File names and module names -<label id="files-and-modules"> -<p> -%* * -%************************************************************************ - -Typically, a module @Foo@ will be contained in a file called @Foo.hs@ -or @Foo.lhs@. But GHC does not require that to be the case. You can put a module -named @Foo@ in a file named @SomethingElse@. In this case, <em>GHC will still -write an interface file @Foo.hi@</em>, but it will write an object fild -@SomethingElse.o@. Any module that imports @Foo@ will -of course look for @Foo.hi@, and it will find it. - -A useful consequence is that you can have many files, @A.hs@, @B.hs@, etc, containing -the module @Main@. This is useful if you want to build distinct programs -in the same directory. - - -%************************************************************************ -%* * -<sect2>Finding interface files -<label id="options-finding-imports"> -<p> -<nidx>interface files, finding them</nidx> -<nidx>finding interface files</nidx> -%* * -%************************************************************************ - -In your program, you import a module @Foo@ by saying -@import Foo@. GHC goes looking for an interface file, @Foo.hi@. -It has a builtin list of directories (notably including @.@) where -it looks. - -<descrip> - -<tag>@-i<dirs>@</tag><nidx>-i<dirs> option</nidx> This flag -prepends a colon-separated list of @dirs@ to the ``import -directories'' list. -See also Section <ref id="recomp"> for the significance of using -relative and absolute pathnames in the @-i@ list. - -<tag>@-i@</tag> resets the ``import directories'' list back to nothing. - -<tag>@-fno-implicit-prelude@</tag> -<nidx>-fno-implicit-prelude option</nidx> -GHC normally imports @Prelude.hi@ files for you. If you'd rather it -didn't, then give it a @-fno-implicit-prelude@ option. You are -unlikely to get very far without a Prelude, but, hey, it's a free -country. - -<tag>@-syslib <lib>@</tag> -<nidx>-syslib <lib> option</nidx> - -If you are using a system-supplied non-Prelude library (e.g., the -POSIX library), just use a @-syslib posix@ option (for example). The -right interface files should then be available. Section <ref -name="The GHC Prelude and Libraries" id="ghc-prelude"> lists the -libraries available by this mechanism. - -<tag>@-I<dir>@</tag> -<nidx>-I<dir> option</nidx> - -Once a Haskell module has been compiled to C (@.hc@ file), you may -wish to specify where GHC tells the C compiler to look for @.h@ files. -(Or, if you are using the @-cpp@ option<nidx>-cpp option</nidx>, where -it tells the C pre-processor to look...) For this purpose, use a @-I@ -option in the usual C-ish way. - -</descrip> - -%************************************************************************ -%* * -<sect2>Other options related to interface files -<label id="hi-options"> -<p> -<nidx>interface files, options</nidx> -%* * -%************************************************************************ - -GHC supports some other more exotic command-line options related to interface files. -Most programmers should never need to use any of them. - -<descrip> - -<tag>@-ohi@ <filename></tag> -<nidx>-ohi <file> option</nidx> - -The interface output may be directed to another file -@bar2/Wurble.iface@ with the option @-ohi bar2/Wurble.iface@ -(not recommended). - -<tag>@-nohi@</tag> -<nidx>-nohi option</nidx> - -Don't generate an interface file at all. - -<tag>@-hi-diffs@, @-hi-diffs-with-usages@, @-keep-hi-diffs@</tag> -<nidx>-hi-diffs option</nidx> -<nidx>-hi-diffs-with-usages option</nidx> -<nidx>-keep-hi-diffs option</nidx> -The compiler does not overwrite an existing @.hi@ interface file if -the new one is byte-for-byte the same as the old one; this is friendly -to @make@. When an interface does change, it is often enlightening to -be informed. The @-hi-diffs@ option will -make @ghc@ run @diff@ on the old and new @.hi@ files. You can also -record the difference in the interface file itself, the -@-keep-hi-diffs@<nidx>-keep-hi-diffs</nidx> option takes care of that. - -The @.hi@ files from GHC contain ``usage'' information which changes -often and uninterestingly. If you really want to see these changes -reported, you need to use the -@-hi-diffs-with-usages@<nidx>-hi-diffs-with-usages option</nidx> -option. - -<tag>@-fignore-interface-pragmas@</tag> -<nidx>-fignore-interface-pragmas option</nidx> - -Interface files are normally jammed full of compiler-produced -<em>pragmas</em>, 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 -@-fignore-interface-pragmas@ option. - -<tag>@-fno-prune-tydecls@</tag> -<nidx>-fno-prune-tydecls option</nidx> -When compiling without optimisations on, the compiler is extra-careful -about not slurping in data constructors that it will not need. -The @-fno-prune-tydecls@ flag lets you turn this cleverness off; the reason -is to allow us to measure the effect of the cleverness. (In earlier versions -of GHC there was a bug that meant you <em>had</em> to turn it off sometimes, -but that is no longer true.) -</descrip> - -See also Section <ref name="Linking and consistency-checking" -id="options-linker">, which describes how the linker finds standard -Haskell libraries. - -%************************************************************************ -%* * -<sect2>The recompilation checker -<label id="recomp"> -<p> -<nidx>recompilation checker</nidx> -%* * -%************************************************************************ - -In the olden days, GHC compared the newly-generated @.hi@ file with -the previous version; if they were identical, it left the old one -alone and didn't change its modification date. In consequence, -importers of a module with an unchanged output @.hi@ file were not -recompiled. - -This doesn't work any more. In our earlier example, module @C@ does -not import module @A@ directly, yet changes to @A.hi@ should force a -recompilation of @C@. And some changes to @A@ (changing the -definition of a function that appears in an inlining of a function -exported by @B@, say) may conceivably not change @B.hi@ one jot. So -now... - -GHC keeps a version number on each interface file, and on each type -signature within the interface file. It also keeps in every interface -file a list of the version numbers of everything it used when it last -compiled the file. If the source file's modification date is earlier -than the @.o@ file's date (i.e. the source hasn't changed since the -file was last compiled), GHC will be clever. It compares the version -numbers on the things it needs this time with the version numbers on -the things it needed last time (gleaned from the interface file of the -module being compiled); if they are all the same it stops compiling -rather early in the process saying ``Compilation IS NOT required''. -What a beautiful sight! - -GHC <em>only</em> keeps detailed dependency information for ``user'' modules, -not for ``library'' modules. It distinguishes the two by a hack: a module -whose @.hi@ file has an absolute path name is considered a library module, -while a relative path name indicates a user module. So if you have a -multi-directory application, use <em>relative</em> path names in your -@-i@ path, to force GHC to record detailed dependency information. -Use absolute path names only for directories containing slowly-changing -library modules. - -A path is considered ``absolute'' if it starts with ``@/@'', or -``@A:/@'', or ``@A:\@'' (or ``@B:/@'', ``@B:\@'' etc). - -Patrick Sansom had a workshop paper about how all this is done (though -the details have changed quite a bit). Ask -him (email: <htmlurl name="sansom@@dcs.gla.ac.uk" -url="mailto:sansom@@dcs.gla.ac.uk">) if you want a copy. - -%************************************************************************ -%* * -<sect2>Using @make@ -<label id="using-make"> -<p> -<ncdx>make</ncdx> -%* * -%************************************************************************ - -It is reasonably straightforward to set up a @Makefile@ to use with -GHC, assuming you name your source files the same as your modules. -Thus: - -<tscreen><verb> -HC = ghc -HC_OPTS = -cpp $(EXTRA_HC_OPTS) - -SRCS = Main.lhs Foo.lhs Bar.lhs -OBJS = Main.o Foo.o Bar.o - -.SUFFIXES : .o .hi .lhs .hc .s - -cool_pgm : $(OBJS) - rm $@ - $(HC) -o $@ $(HC_OPTS) $(OBJS) - -# Standard suffix rules -.o.hi: - @: - -.lhs.o: - $(HC) -c $< $(HC_OPTS) - -.hs.o: - $(HC) -c $< $(HC_OPTS) - -# Inter-module dependencies -Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz -Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz -</verb></tscreen> - -(Sophisticated @make@ variants may achieve some of the above more -elegantly. Notably, @gmake@'s pattern rules let you write the more -comprehensible: - -<tscreen><verb> -%.o : %.lhs - $(HC) -c $< $(HC_OPTS) -</verb></tscreen> - -What we've shown should work with any @make@.) - -Note the cheesy @.o.hi@ rule: It records the dependency of the -interface (@.hi@) file on the source. The rule says a @.hi@ file can -be made from a @.o@ file by doing... nothing. Which is true. - -Note the inter-module dependencies at the end of the Makefile, which -take the form - -<tscreen><verb> -Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz -</verb></tscreen> - -They tell @make@ that if any of @Foo.o@, @Foo.hc@ or @Foo.s@ have an -earlier modification date than @Baz.hi@, then the out-of-date file -must be brought up to date. To bring it up to date, @make@ looks for -a rule to do so; one of the preceding suffix rules does the job -nicely. - -Putting inter-dependencies of the form @Foo.o : Bar.hi@ into your -@Makefile@ by hand is rather error-prone. Don't worry---never fear, -@mkdependHS@ is here! (and is distributed as part of GHC) Add the -following to your @Makefile@: - -<tscreen><verb> -depend : - mkdependHS -- $(HC_OPTS) -- $(SRCS) -</verb></tscreen> - -Now, before you start compiling, and any time you change the @imports@ -in your program, do @make depend@ before you do @make cool_pgm@. -@mkdependHS@ will append the needed dependencies to your @Makefile@. -@mkdependHS@ is fully describe in Section <ref name="Makefile -dependencies in Haskell: using mkdependHS" id="mkdependHS">. - -A few caveats about this simple scheme: - -<itemize> - -<item> You may need to compile some modules explicitly to create their -interfaces in the first place (e.g., @make Bar.o@ to create @Bar.hi@). - -<item> You may have to type @make@ more than once for the dependencies -to have full effect. However, a @make@ run that does nothing -<em>does</em> mean ``everything's up-to-date.'' - -<item> This scheme will work with mutually-recursive modules but, -again, it may take multiple iterations to ``settle.'' - -</itemize> - -%************************************************************************ -%* * -<sect2>How to compile mutually recursive modules -<label id="mutual-recursion"> -<p> -<nidx>module system, recursion</nidx> -<nidx>recursion, between modules</nidx> -%* * -%************************************************************************ - -Currently, the compiler does not have proper support for dealing with -mutually recursive modules: - -<tscreen><verb> -module A where - -import B - -newtype TA = MkTA Int - -f :: TB -> TA -f (MkTB x) = MkTA x --------- -module B where - -import A - -data TB = MkTB !Int - -g :: TA -> TB -g (MkTA x) = MkTB x -</verb></tscreen> - -When compiling either module A and B, the compiler will try (in vain) -to look for the interface file of the other. So, to get mutually -recursive modules off the ground, you need to hand write an interface -file for A or B, so as to break the loop. These hand-written -interface files are called @hi-boot@ files, and are placed in a file -called @<module>.hi-boot@. To import from an @hi-boot@ file instead -of the standard @.hi@ file, use the following syntax in the importing module: -<nidx>hi-boot files</nidx> -<nidx>importing, hi-boot files</nidx> - -<tscreen> <verb> -import {-# SOURCE #-} A -</verb> </tscreen> - -The hand-written interface need only contain the bare minimum of -information needed to get the bootstrapping process started. For -example, it doesn't need to contain declarations for <em/everything/ -that module @A@ exports, only the things required by the module that -imports @A@ recursively. - -For the example at hand, the boot interface file for A would look like -the following: - -<tscreen><verb> -__interface A 1 404 where -__export A TA{MkTA} ; -1 newtype TA = MkTA PrelBase.Int ; -</verb></tscreen> - -The syntax is essentially the same as a normal @.hi@ file -(unfortunately), but you can usually tailor an existing @.hi@ file to -make a @.hi-boot@ file. - -Notice that we only put the declaration for the newtype @TA@ in the -@hi-boot@ file, not the signature for @f@, since @f@ isn't used by -@B@. - -The number ``1'' after ``__interface A'' gives the version number of module A; -it is incremented whenever anything in A's interface file changes. The ``404'' is -the version number of the interface file <em>syntax</em>; we change it when -we change the syntax of interface files so that you get a better error message when -you try to read an old-format file with a new-format compiler. - -The number ``1'' at the beginning of a declaration is the <em>version -number</em> of that declaration: for the purposes of @.hi-boot@ files -these can all be set to 1. All names must be fully qualified with the -<em/original/ module that an object comes from: for example, the -reference to @Int@ in the interface for @A@ comes from @PrelBase@, -which is a module internal to GHC's prelude. It's a pain, but that's -the way it is. - -If you want an hi-boot file to export a data type, but you don't want to give its constructors -(because the constructors aren't used by the SOURCE-importing module), you can write simply: - -<tscreen><verb> -__interface A 1 404 where -__export A TA; -1 data TA -</verb></tscreen> - -(You must write all the type parameters, but leave out the '=' and everything that follows it.) - -<bf>Note:</bf> This is all a temporary solution, a version of the -compiler that handles mutually recursive properly without the manual -construction of interface files, is (allegedly) in the works. - -%************************************************************************ -%* * -<sect1>Command line options in source files -<label id="source-file-options"> -<p> -<nidx>source-file options</nidx> -%* * -%************************************************************************ - -GHC expects its flags on the command line, but it is also possible -to embed them in the Haskell module itself, using the @OPTIONS@ -pragma <nidx>OPTIONS pragma</nidx>: -<tscreen><verb> - {-# OPTIONS -fglasgow-exts -fno-cpr-analyse #-} - module X where - - ... -</verb></tscreen> -@OPTIONS@ pragmas are only looked for at the top of your source -files, upto the first (non-literate,non-empty) line not containing -@OPTIONS@. Multiple @OPTIONS@ pragmas are recognised. Note -that your command shell does not get to the source file options, they -are just included literally in the array of command-line arguments -the compiler driver maintains internally, so you'll be desperately -disappointed if you try to @glob@ etc. inside @OPTIONS@. - -The contents of @OPTIONS@ are prepended to the command-line -options, so you *do* have the ability to override @OPTIONS@ settings -via the command line. - -It is not recommended to move all the contents of your Makefiles into -your source files, but in some circumstances, the @OPTIONS@ pragma -is the Right Thing. (If you use @-keep-hc-file-too@ and have @OPTIONS@ -flags in your module, the @OPTIONS@ will get put into the generated .hc -file). - - -%************************************************************************ -%* * -<sect1>Optimisation (code improvement) -<label id="options-optimise"> -<p> -<nidx>optimisation (GHC)</nidx> -<nidx>improvement, code (GHC)</nidx> -%* * -%************************************************************************ - -The @-O*@ options specify convenient ``packages'' of optimisation -flags; the @-f*@ options described later on specify -<em>individual</em> optimisations to be turned on/off; the @-m*@ -options specify <em>machine-specific</em> optimisations to be turned -on/off. - -%---------------------------------------------------------------------- -<sect2>@-O*@: convenient ``packages'' of optimisation flags. -<label id="optimise-pkgs"> -<p> -<nidx>-O options</nidx> - -There are <em>many</em> 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 @-O*@ ``package,'' stick with it---don't chop and -change. Modules' interfaces <em>will</em> change with a shift to a new -@-O*@ option, and you may have to recompile a large chunk of all -importing modules before your program can again be run -safely (see Section <ref name="The recompilation checker" id="recomp">). - -<descrip> -<tag>No @-O*@-type option specified:</tag> -<nidx>-O* not specified</nidx> -This is taken to mean: ``Please compile quickly; I'm not over-bothered -about compiled-code quality.'' So, for example: @ghc -c Foo.hs@ - -<tag>@-O@ or @-O1@:</tag> -<nidx>-O option</nidx> -<nidx>-O1 option</nidx> -<nidx>optimise normally</nidx> -Means: ``Generate good-quality code without taking too long about it.'' -Thus, for example: @ghc -c -O Main.lhs@ - -<tag>@-O2@:</tag> -<nidx>-O2 option</nidx> -<nidx>optimise aggressively</nidx> -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</em> if you're unlucky. They are -normally turned on or off individually. - -At the moment, @-O2@ is <em>unlikely</em> to produce -better code than @-O@. - -<tag>@-O2-for-C@:</tag> -<nidx>-O2-for-C option</nidx> -<nidx>gcc, invoking with -O2</nidx> - -Says to run GCC with @-O2@, which may be worth a few percent in -execution speed. Don't forget @-fvia-C@, lest you use the native-code -generator and bypass GCC altogether! - -<tag>@-Onot@:</tag> -<nidx>-Onot option</nidx> -<nidx>optimising, reset</nidx> - -This option will make GHC ``forget'' any @-O@ish options it has seen so -far. Sometimes useful; for example: @make all EXTRA_HC_OPTS=-Onot@. - -<tag>@-Ofile <file>@:</tag> -<nidx>-Ofile <file> option</nidx> -<nidx>optimising, customised</nidx> - -For those who need <em>absolute</em> control over <em>exactly</em> -what options are used (e.g., compiler writers, sometimes :-), a list -of options can be put in a file and then slurped in with @-Ofile@. - -In that file, comments are of the @#@-to-end-of-line variety; blank -lines and most whitespace is ignored. - -Please ask if you are baffled and would like an example of @-Ofile@! -</descrip> - -At Glasgow, we don't use a @-O*@ flag for day-to-day work. We use -@-O@ to get respectable speed; e.g., when we want to measure -something. When we want to go for broke, we tend to use @-O -fvia-C --O2-for-C@ (and we go for lots of coffee breaks). - -The easiest way to see what @-O@ (etc.) ``really mean'' is to run with -@-v@, then stand back in amazement. Alternatively, just look at the -@HsC_minus<blah>@ lists in the @ghc@ driver script. - -%---------------------------------------------------------------------- -<sect2>@-f*@: platform-independent flags -<p> -<nidx>-f* options (GHC)</nidx> -<nidx>-fno-* options (GHC)</nidx> - -Flags can be turned <em>off</em> individually. (NB: I hope you have a -good reason for doing this....) To turn off the @-ffoo@ flag, just use -the @-fno-foo@ flag.<nidx>-fno-<opt> anti-option</nidx> So, for -example, you can say @-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: -<itemize> -<item> -@-fno-strictness@<nidx>-fno-strictness option</nidx> (strictness -analyser, because it is sometimes slow), -<item> -@-fno-specialise@<nidx>-fno-specialise option</nidx> (automatic -specialisation of overloaded functions, because it can make your code -bigger) (US spelling also accepted), and -<item> -@-fno-cpr-analyse@<nidx>-fno-cpr-analyse option</nidx> switches off the CPR (constructed product -result) analyser. -</itemize> - -Should you wish to turn individual flags <em>on</em>, you are advised -to use the @-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</em> want to try: -<descrip> -%------------------------------------------------------------------ -<tag>@-fvia-C@:</tag> -<nidx>-fvia-C option</nidx> -<nidx>native code generator, turning off</nidx> - -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 @_ccall_gc_@s or -@_casm_@s, you probably <em>have to</em> use @-fvia-C@. - -The lower-case incantation, @-fvia-c@, is synonymous. - -Compiling via C will probably be slower (in compilation time) than -using GHC's native code generator. - -<tag>@-funfolding-interface-threshold<n>@:</tag> -<nidx>-funfolding-interface-threshold option</nidx> -<nidx>inlining, controlling</nidx> -<nidx>unfolding, controlling</nidx> -(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 function would be assigned a bigger cost.) - -<tag>@-funfolding-creation-threshold<n>@:</tag> -<nidx>-funfolding-creation-threshold option</nidx> -<nidx>inlining, controlling</nidx> -<nidx>unfolding, controlling</nidx> -(Default: 30) This option is similar to -@-funfolding-interface-threshold@, except that it governs unfoldings -within a single module. Increasing this figure is more likely to -result in longer compile times than faster code. The next option is -more useful: - -<tag>@-funfolding-use-threshold<n>@:</tag> -<nidx>-funfolding-use-threshold option</nidx> -<nidx>inlining, controlling</nidx> -<nidx>unfolding, controlling</nidx> -(Default: 8) This is the magic cut-off figure for unfolding: below -this size, a function definition will be unfolded at the call-site, -any bigger and it won't. The size computed for a function depends on -two things: the actual size of the expression minus any discounts that -apply (see @-funfolding-con-discount@). - -<tag>@-funfolding-con-discount<n>@:</tag> -<nidx>-funfolding-con-discount option</nidx> -<nidx>inlining, controlling</nidx> -<nidx>unfolding, controlling</nidx> -(Default: 2) If the compiler decides that it can eliminate some -computation by performing an unfolding, then this is a discount factor -that it applies to the funciton size before deciding whether to unfold -it or not. - -OK, folks, these magic numbers `30', `8', and '2' are mildly -arbitrary; they are of the ``seem to be OK'' variety. The `8' is the -more critical one; it's what determines how eager GHC is about -expanding unfoldings. - -<tag>@-funbox-strict-fields@:</tag> -<nidx>-funbox-strict-fields option</nidx> -<nidx>strict constructor fields</nidx> -<nidx>constructor fields, strict</nidx> - -This option causes all constructor fields which are marked strict -(i.e. ``!'') to be unboxed or unpacked if possible. For example: - -<tscreen><verb> -data T = T !Float !Float -</verb></tscreen> - -will create a constructor @T@ containing two unboxed floats if the -@-funbox-strict-fields@ flag is given. This may not always be an -optimisation: if the @T@ constructor is scrutinised and the floats -passed to a non-strict function for example, they will have to be -reboxed (this is done automatically by the compiler). - -This option should only be used in conjunction with @-O@, in order to -expose unfoldings to the compiler so the reboxing can be removed as -often as possible. For example: - -<tscreen><verb> -f :: T -> Float -f (T f1 f2) = f1 + f2 -</verb></tscreen> - -The compiler will avoid reboxing @f1@ and @f2@ by inlining @+@ on -floats, but only when @-O@ is on. - -Any single-constructor data is eligible for unpacking; for example - -<tscreen><verb> -data T = T !(Int,Int) -</verb></tscreen> - -will store the two @Int@s directly in the @T@ constructor, by flattening -the pair. Multi-level unpacking is also supported: - -<tscreen><verb> -data T = T !S -data S = S !Int !Int -</verb></tscreen> - -will store two unboxed @Int#@s directly in the @T@ constructor. - -<tag>@-fsemi-tagging@:</tag> -This option (which <em>does not work</em> 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 @-fsemi-tagging@ enough to recommend it. -(For all we know, it doesn't even work anymore... Sigh.) -</descrip> - -%---------------------------------------------------------------------- -<sect2>@-m*@: platform-specific flags -<p> -<nidx>-m* options (GHC)</nidx> -<nidx>platform-specific options</nidx> -<nidx>machine-specific options</nidx> - -Some flags only make sense for particular target platforms. - -<descrip> -<tag>@-mv8@:</tag> -(SPARC machines)<nidx>-mv8 option (SPARC only)</nidx> -Means to pass the like-named option to GCC; it says to use the -Version 8 SPARC instructions, notably integer multiply and divide. -The similiar @-m*@ GCC options for SPARC also work, actually. - -<tag>@-mlong-calls@:</tag> -(HPPA machines)<nidx>-mlong-calls option (HPPA only)</nidx> -Means to pass the like-named option to GCC. Required for Very Big -modules, maybe. (Probably means you're in trouble...) - -<tag>@-monly-[32]-regs@:</tag> -(iX86 machines)<nidx>-monly-N-regs option (iX86 only)</nidx> -GHC tries to ``steal'' four registers from GCC, for performance -reasons; it almost always works. However, when GCC is compiling some -modules with four stolen registers, it will crash, probably saying: -<tscreen><verb> -Foo.hc:533: fixed or forbidden register was spilled. -This may be due to a compiler bug or to impossible asm -statements or clauses. -</verb></tscreen> -Just give some registers back with @-monly-N-regs@. Try `3' first, -then `2'. If `2' doesn't work, please report the bug to us. -</descrip> - -%---------------------------------------------------------------------- -<sect2>Code improvement by the C compiler. -<label id="optimise-C-compiler"> -<p> -<nidx>optimisation by GCC</nidx> -<nidx>GCC optimisation</nidx> - -The C~compiler (GCC) is run with @-O@ turned on. (It has -to be, actually). - -If you want to run GCC with @-O2@---which may be worth a few -percent in execution speed---you can give a -@-O2-for-C@<nidx>-O2-for-C option</nidx> option. - -%************************************************************************ -%* * -<sect1>Options related to a particular phase -<label id="options-phases"> -<p> -%* * -%************************************************************************ - -<sect2> The C pre-processor -<label id="c-pre-processor"> -<p> -<nidx>pre-processing: cpp</nidx> -<nidx>C pre-processor options</nidx> -<nidx>cpp, pre-processing with</nidx> - -The C pre-processor @cpp@ is run over your Haskell code only if the -@-cpp@ option <nidx>-cpp option</nidx> is given. Unless you are -building a large system with significant doses of conditional -compilation, you really shouldn't need it. -<descrip> -<tag>@-D<foo>@:</tag> -<nidx>-D<name> option</nidx> -Define macro @<foo>@ in the usual way. NB: does <em>not</em> affect -@-D@ macros passed to the C~compiler when compiling via C! For those, -use the @-optc-Dfoo@ hack... (see Section <ref name="Forcing options -to a particular phase." id="forcing-options-through">). - -<tag>@-U<foo>@:</tag> -<nidx>-U<name> option</nidx> -Undefine macro @<foo>@ in the usual way. - -<tag>@-I<dir>@:</tag> -<nidx>-I<dir> option</nidx> -Specify a directory in which to look for @#include@ files, in -the usual C way. -</descrip> - -The @ghc@ driver pre-defines several macros when processing Haskell -source code (@.hs@ or @.lhs@ files): - -<descrip> -<tag>@__HASKELL98__@:</tag> -<nidx>__HASKELL98__</nidx> -If defined, this means that GHC supports the language defined by the -Haskell 98 report. - -<tag>@__HASKELL__=98@:</tag> -<nidx>__HASKELL__</nidx> -In GHC 4.04 and later, the @__HASKELL__@ macro is defined as having -the value @98@. - -<tag>@__HASKELL1__@:</tag> -<nidx>__HASKELL1__ macro</nidx> -If defined to <em/n/, that means GHC supports the Haskell language -defined in the Haskell report version <em/1.n/. Currently 5. This -macro is deprecated, and will probably disappear in future versions. - -<tag>@__GLASGOW_HASKELL__@:</tag> -<nidx>__GLASGOW_HASKELL__ macro</nidx> -For version <em/n/ of the GHC system, this will be @#define@d to -<em/100n/. So, for version 4.00, it is 400. - -With any luck, @__GLASGOW_HASKELL__@ will be undefined in all other -implementations that support C-style pre-processing. - -(For reference: the comparable symbols for other systems are: -@__HUGS__@ for Hugs and @__HBC__@ for Chalmers.) - -NB. This macro is set when pre-processing both Haskell source and C -source, including the C source generated from a Haskell module -(ie. @.hs@, @.lhs@, @.c@ and @.hc@ files). - -<tag>@__CONCURRENT_HASKELL__@:</tag> -<nidx>__CONCURRENT_HASKELL__ macro</nidx> -This symbol is defined when pre-processing Haskell (input) and -pre-processing C (GHC output). Since GHC from verion 4.00 now -supports concurrent haskell by default, this symbol is always defined. - -<tag>@__PARALLEL_HASKELL__@:</tag> -<nidx>__PARALLEL_HASKELL__ macro</nidx> -Only defined when @-parallel@ is in use! This symbol is defined when -pre-processing Haskell (input) and pre-processing C (GHC output). -</descrip> - -Options other than the above can be forced through to the C -pre-processor with the @-opt@ flags (see -Section <ref name="Forcing options to a particular phase." id="forcing-options-through">). - -A small word of warning: @-cpp@ is not friendly to ``string -gaps''.<nidx>-cpp vs string gaps</nidx><nidx>string gaps vs --cpp</nidx>. In other words, strings such as the following: - -<tscreen><verb> - strmod = "\ - \ p \ - \ " -</verb></tscreen> - -don't work with @-cpp@; @/usr/bin/cpp@ elides the -backslash-newline pairs. - -However, it appears that if you add a space at the end of the line, -then @cpp@ (at least GNU @cpp@ and possibly other @cpp@s) -leaves the backslash-space pairs alone and the string gap works as -expected. - -%************************************************************************ -%* * -<sect2>Options affecting the C compiler (if applicable) -<label id="options-C-compiler"> -<p> -<nidx>include-file options</nidx> -<nidx>C compiler options</nidx> -<nidx>GCC options</nidx> -%* * -%************************************************************************ - -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: - -<tabular ca="ll"> -@-ansi@ | do ANSI C (not K&R) @@ -@-pedantic@ | be so@@ -@-dgcc-lint@ | (hack) short for ``make GCC very paranoid''@@ -</tabular> -<nidx>-ansi option (for GCC)</nidx> -<nidx>-pedantic option (for GCC)</nidx> -<nidx>-dgcc-lint option (GCC paranoia)</nidx> - -If you are compiling with lots of @ccalls@, etc., you may need to -tell the C~compiler about some @#include@ files. There is no real -pretty way to do this, but you can use this hack from the -command-line: - -<tscreen><verb> -% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs -</verb></tscreen> - - -%************************************************************************ -%* * -<sect2>Linking and consistency-checking -<label id="options-linker"> -<p> -<nidx>linker options</nidx> -<nidx>ld options</nidx> -%* * -%************************************************************************ - -GHC has to link your code with various libraries, possibly including: -user-supplied, GHC-supplied, and system-supplied (@-lm@ math -library, for example). - -<descrip> -<tag>@-l<FOO>@:</tag> -<nidx>-l<lib> option</nidx> -Link in a library named @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: @ghc -lbar *.o@ is almost certainly -wrong, because it will search @libbar.a@ <em>before</em> it has -collected unresolved symbols from the @*.o@ files. -@ghc *.o -lbar@ is probably better. - -The linker will of course be informed about some GHC-supplied -libraries automatically; these are: - -<tabular ca="ll"> -<bf>-l equivalent</bf> | <bf>description</bf> @@ -@@ -@-lHSrts,-lHSclib@ | basic runtime libraries @@ -@-lHS@ | standard Prelude library @@ -@-lHS_cbits@ | C support code for standard Prelude library @@ -@-lgmp@ | GNU multi-precision library (for Integers)@@ -</tabular> - -<nidx>-lHS library</nidx> -<nidx>-lHS_cbits library</nidx> -<nidx>-lHSrts library</nidx> -<nidx>-lgmp library</nidx> - -<tag>@-syslib <name>@:</tag> -<nidx>-syslib <name> option</nidx> - -If you are using a Haskell ``system library'' (e.g., the POSIX -library), just use the @-syslib posix@ option, and the correct code -should be linked in. - -<tag>@-L<dir>@:</tag> -<nidx>-L<dir> option</nidx> -Where to find user-supplied libraries... Prepend the directory -@<dir>@ to the library directories path. - -<tag>@-static@:</tag> -<nidx>-static option</nidx> -Tell the linker to avoid shared libraries. - -<tag>@-no-link-chk@ and @-link-chk@:</tag> -<nidx>-no-link-chk option</nidx> -<nidx>-link-chk option</nidx> -<nidx>consistency checking of executables</nidx> -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 @.o@ file was compiled -for a parallel machine and the others weren't.) You may turn off this -check with @-no-link-chk@. You can turn it (back) on with -@-link-chk@ (the default). - -<tag><tt>-no-hs-main</tt>:</tag> -<nidx>-no-hs-main option</nidx> -<nidx>linking Haskell libraries with foreign code</nidx> - -In the event you want to include ghc-compiled code as part of another -(non-Haskell) program, the RTS will not be supplying its definition of -<tt/main()/ at link-time, you will have to. To signal that to the -driver script when linking, use <tt/-no-hs-main/. - -Notice that since the command-line passed to the linker is rather -involved, you probably want to use the ghc driver script to do the -final link of your `mixed-language' application. This is not a -requirement though, just try linking once with <tt/-v/ on to see what -options the driver passes through to the linker. - -</descrip> - -%************************************************************************ -%* * -<sect1>Using Concurrent Haskell -<p> -<nidx>Concurrent Haskell---use</nidx> -%* * -%************************************************************************ - -GHC (as of version 4.00) supports Concurrent Haskell by default, -without requiring a special option or libraries compiled in a certain -way. To get access to the support libraries for Concurrent Haskell -(ie. @Concurrent@ and friends), use the @-syslib concurrent@ option. - -Three RTS options are provided for modifying the behaviour of the -threaded runtime system. See the descriptions of @-C[<us>]@, @-q@, -and @-t<num>@ in Section <ref name="RTS options for -Concurrent/Parallel Haskell" id="parallel-rts-opts">. - -Concurrent Haskell is described in more detail in Section <ref -name="Concurrent and Parallel Haskell" id="concurrent-and-parallel">. - -%************************************************************************ -%* * -<sect1>Using Parallel Haskell -<p> -<nidx>Parallel Haskell---use</nidx> -%* * -%************************************************************************ - -[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 -@-parallel@ option,<nidx>-parallel option</nidx> both when compiling -<em>and linking</em>. You will probably want to @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 @-N<n>@, to say how many -PVM ``processors'' your program to run on. (For more details of -all relevant RTS options, please see Section <ref name="RTS options for Concurrent/Parallel Haskell" id="parallel-rts-opts">.) - -In truth, running Parallel Haskell programs and getting information -out of them (e.g., parallelism profiles) is a battle with the vagaries of -PVM, detailed in the following sections. - -%************************************************************************ -%* * -<sect2>Dummy's guide to using PVM -<p> -<nidx>PVM, how to use</nidx> -<nidx>Parallel Haskell---PVM use</nidx> -%* * -%************************************************************************ - -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 @.cshrc@ or equivalent: -<tscreen><verb> -setenv PVM_ROOT /wherever/you/put/it -setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch` -setenv PVM_DPATH $PVM_ROOT/lib/pvmd -</verb></tscreen> - -Creating and/or controlling your ``parallel machine'' is a purely-PVM -business; nothing specific to Parallel Haskell. - -You use the @pvm@<nidx>pvm command</nidx> 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} -@Control-D@ & exit @pvm@, leaving it running \\ -@halt@ & kill off this ``parallel machine'' \& exit \\ -@add <host>@ & add @<host>@ as a processor \\ -@delete <host>@ & delete @<host>@ \\ -@reset@ & kill what's going, but leave PVM up \\ -@conf@ & list the current configuration \\ -@ps@ & report processes' status \\ -@pstat <pid>@ & status of a particular process \\ -\end{tabular} - -The PVM documentation can tell you much, much more about @pvm@! - -%************************************************************************ -%* * -<sect2>Parallelism profiles -<p> -<nidx>parallelism profiles</nidx> -<nidx>profiles, parallelism</nidx> -<nidx>visualisation tools</nidx> -%* * -%************************************************************************ - -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 @hbcpp@) can be generated with the -@-q@<nidx>-q RTS option (concurrent, parallel)</nidx> RTS option. The -per-processor profiling info is dumped into files named -@<full-path><program>.gr@. These are then munged into a PostScript picture, -which you can then display. For example, to run your program -@a.out@ on 8 processors, then view the parallelism profile, do: - -<tscreen><verb> -% ./a.out +RTS -N8 -q -% grs2gr *.???.gr > temp.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! -</verb></tscreen> - -The scripts for processing the parallelism profiles are distributed -in @ghc/utils/parallel/@. - -%************************************************************************ -%* * -<sect2>Other useful info about running parallel programs -<p> -%* * -%************************************************************************ - -The ``garbage-collection statistics'' RTS options can be useful for -seeing what parallel programs are doing. If you do either -@+RTS -Sstderr@<nidx>-Sstderr RTS option</nidx> or @+RTS -sstderr@, then -you'll get mutator, garbage-collection, etc., times on standard -error. The standard error of all PE's other than the `main thread' -appears in @/tmp/pvml.nnn@, courtesy of PVM. - -Whether doing @+RTS -Sstderr@ or not, a handy way to watch -what's happening overall is: @tail -f /tmp/pvml.nnn@. - -%************************************************************************ -%* * -<sect2>RTS options for Concurrent/Parallel Haskell -<label id="parallel-rts-opts"> -<p> -<nidx>RTS options, concurrent</nidx> -<nidx>RTS options, parallel</nidx> -<nidx>Concurrent Haskell---RTS options</nidx> -<nidx>Parallel Haskell---RTS options</nidx> -%* * -%************************************************************************ - -Besides the usual runtime system (RTS) options -(Section <ref name="Running a compiled program" id="runtime-control">), there are a few options particularly -for concurrent/parallel execution. - -<descrip> -<tag>@-N<N>@:</tag> -<nidx>-N<N> RTS option (parallel)</nidx> -(PARALLEL ONLY) Use @<N>@ PVM processors to run this program; -the default is 2. - -<tag>@-C[<us>]@:</tag> -<nidx>-C<us> RTS option</nidx> -Sets the context switch interval to @<us>@ microseconds. A context -switch will occur at the next heap allocation after the timer expires. -With @-C0@ or @-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. - -[NOTE: this option currently has no effect (version 4.00). Context -switches happen when the current heap block is full, i.e. every 4k of -allocation]. - -<tag>@-q[v]@:</tag> -<nidx>-q RTS option</nidx> -(PARALLEL ONLY) Produce a quasi-parallel profile of thread activity, -in the file @<program>.qp@. In the style of @hbcpp@, this profile -records the movement of threads between the green (runnable) and red -(blocked) queues. If you specify the verbose suboption (@-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 -@hbcpp@ profiling tools or if you are context switching at every heap -check (with @-C@). - -<tag>@-t<num>@:</tag> -<nidx>-t<num> RTS option</nidx> -(PARALLEL ONLY) Limit the number of concurrent threads per processor -to @<num>@. The default is 32. Each thread requires slightly over 1K -<em>words</em> 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.) - -<tag>@-d@:</tag> -<nidx>-d RTS option (parallel)</nidx> -(PARALLEL ONLY) Turn on debugging. It pops up one xterm (or GDB, or -something...) per PVM processor. We use the standard @debugger@ -script that comes with PVM3, but we sometimes meddle with the -@debugger2@ script. We include ours in the GHC distribution, -in @ghc/utils/pvm/@. - -<tag>@-e<num>@:</tag> -<nidx>-e<num> RTS option (parallel)</nidx> -(PARALLEL ONLY) Limit the number of pending sparks per processor to -@<num>@. The default is 100. A larger number may be appropriate if -your program generates large amounts of parallelism initially. - -<tag>@-Q<num>@:</tag> -<nidx>-Q<num> RTS option (parallel)</nidx> -(PARALLEL ONLY) Set the size of packets transmitted between processors -to @<num>@. The default is 1024 words. A larger number may be -appropriate if your machine has a high communication cost relative to -computation speed. -</descrip> |