From: panne Date: Mon, 16 Aug 2004 07:24:29 +0000 (+0000) Subject: [project @ 2004-08-16 07:24:25 by panne] X-Git-Tag: Initial_conversion_from_CVS_complete~1735 X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=092d79172d9e27e329481aae18b4a931619ab81c;p=ghc-hetmet.git [project @ 2004-08-16 07:24:25 by panne] Correct DocBook XML now --- diff --git a/ghc/docs/users_guide/debugging.xml b/ghc/docs/users_guide/debugging.xml index c5758cc..ff8d4f8 100644 --- a/ghc/docs/users_guide/debugging.xml +++ b/ghc/docs/users_guide/debugging.xml @@ -14,8 +14,10 @@ - pass - options + + pass + options + Make a debugging dump after pass <pass> (may be common enough to need @@ -27,28 +29,40 @@ - : + + : + + parser output - : + + : + + renamer output - : + + : + + typechecker output - : + + : + + Dump a type signature for each value defined at the top level of the module. The list is sorted @@ -60,28 +74,40 @@ - : + + : + + derived instances - : + + : + + desugarer output - : + + : + + output of specialisation pass - : + + : + + dumps all rewrite rules (including those generated by the specialisation pass) @@ -89,159 +115,187 @@ - : + + : + + simplifer output (Core-to-Core passes) - : + + : + + inlining info from the simplifier - : + + : + + UsageSP inference pre-inf and output - : + + : + + CPR analyser output - : + + : + + strictness analyser output - : + + : + + CSE pass output - : + + : + + worker/wrapper split output - : + + : + + `occurrence analysis' output - : + + : + + output of “saturate” pass - : + + : + + output of STG-to-STG passes - : + + : + + unflattened Abstract C - : + + : + + flattened Abstract C - : + + : + + same as what goes to the C compiler - : + + : + + native-code generator intermediate form - : + + : + + assembly language from the native-code generator - : + + : + + byte code compiler output - : + + : + + dump foreign export stubs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + Show the output of the intermediate Core-to-Core and STG-to-STG passes, respectively. (Lots @@ -255,8 +309,10 @@ - : - + + : + + Show the output of each iteration of the simplifier (each run of the simplifier has a maximum @@ -266,8 +322,10 @@ - - + + + + Debugging output is in one of several “styles.” Take the printing of types, for @@ -284,8 +342,10 @@ - - + + + + In error messages, expressions are printed to a certain “depth”, with subexpressions beyond the @@ -295,8 +355,10 @@ - - + + + + Dump statistics about how many of each kind of transformation too place. If you add @@ -306,8 +368,10 @@ - - + + + + Make the renamer be *real* chatty about what it is upto. @@ -315,8 +379,10 @@ - - + + + + Print out summary of what kind of information the renamer had to bring in. @@ -324,8 +390,10 @@ - - + + + + Have the renamer report what imports does not contribute. @@ -343,8 +411,10 @@ - - + + + + Turn on heavyweight intra-pass sanity-checking within GHC, at Core level. (It checks GHC's sanity, not yours.) @@ -352,16 +422,20 @@ - : - + + : + + Ditto for STG level. (NOTE: currently doesn't work). - : - + + : + + Turn on checks around UsageSP inference (). This verifies various simple @@ -500,8 +574,10 @@ Main.skip2{-r1L6-} = - : - + + : + + Compile via vanilla ANSI C only, turning off platform-specific optimisations. NOTE: in order to use diff --git a/ghc/docs/users_guide/glasgow_exts.xml b/ghc/docs/users_guide/glasgow_exts.xml index beec0c8..c82e369 100644 --- a/ghc/docs/users_guide/glasgow_exts.xml +++ b/ghc/docs/users_guide/glasgow_exts.xml @@ -73,8 +73,10 @@ documentation describes all the libraries that come with GHC. - : - + + : + + This simultaneously enables all of the extensions to Haskell 98 described in describes all the libraries that come with GHC. - and : - - + + and : + + + This option enables the language extension defined in the Haskell 98 Foreign Function Interface Addendum plus deprecated @@ -111,8 +115,10 @@ documentation describes all the libraries that come with GHC. - : - + + : + + Switch off the Haskell 98 monomorphism restriction. Independent of the @@ -121,13 +127,22 @@ documentation describes all the libraries that come with GHC. - - - - - - - + + + + + + + + + + + + + + + + See . Only relevant if you also use . @@ -135,8 +150,10 @@ documentation describes all the libraries that come with GHC. - - + + + + See . Only relevant if you also use . @@ -144,8 +161,10 @@ documentation describes all the libraries that come with GHC. - - + + + + See . Independent of . @@ -161,8 +180,10 @@ documentation describes all the libraries that come with GHC. - - + + + + See . Independent of . diff --git a/ghc/docs/users_guide/packages.xml b/ghc/docs/users_guide/packages.xml index b50e58e..dcda13b 100644 --- a/ghc/docs/users_guide/packages.xml +++ b/ghc/docs/users_guide/packages.xml @@ -301,10 +301,13 @@ the auto packages required for linking without further assistance. - - - - + + + + + + + Use file as an additional package configuration file. This is used to modify @@ -322,9 +325,13 @@ the auto packages required for linking without further assistance. - - - + + + + + + + This option displays the list of currently installed packages, including those in extra configuration files @@ -352,9 +359,13 @@ the auto packages required for linking without further assistance. - - - + + + + + + + Displays the list of packages installed in the topmost configuration file only: that will be the @@ -369,19 +380,26 @@ the auto packages required for linking without further assistance. - - - - + + + + + + + Removes the specified package from the installed configuration. - - - + + + + + + + Reads package specification from the input, and adds it to the database of installed packages. If a package @@ -392,8 +410,10 @@ the auto packages required for linking without further assistance. - - + + + + Causes ghc-pkg to ignore missing directories and libraries when adding a package, and just @@ -435,9 +455,10 @@ the auto packages required for linking without further assistance. - name - name - package specification + + name + namepackage specification + The package's name, for use with the -package flag and as listed in the @@ -447,10 +468,10 @@ the auto packages required for linking without further assistance. - auto - auto - package specification - + + auto + autopackage specification + Set to True if the package should be automatically available (see - import_dirs - import_dirs - package specification + + import_dirs + import_dirspackage specification + A list of directories containing interface files (.hi files) for this package. @@ -479,9 +501,10 @@ the auto packages required for linking without further assistance. - source_dirs - source_dirs - package specification + + source_dirs + source_dirspackage specification + A list of directories containing Haskell source files for this package. This field isn't used by GHC, but @@ -491,9 +514,10 @@ the auto packages required for linking without further assistance. - library_dirs - library_dirs - package specification + + library_dirs + library_dirspackage specification + A list of directories containing libraries for this package. @@ -501,9 +525,10 @@ the auto packages required for linking without further assistance. - hs_libraries - hs_libraries - package specification + + hs_libraries + hs_librariespackage specification + A list of libraries containing Haskell code for this package, with the .a or @@ -552,9 +577,10 @@ the auto packages required for linking without further assistance. - extra_libraries - extra_libraries - package specification + + extra_libraries + extra_librariespackage specification + A list of extra libraries for this package. The difference between hs_libraries and @@ -589,9 +615,10 @@ the auto packages required for linking without further assistance. - include_dirs - include_dirs - package specification + + include_dirs + include_dirspackage specification + A list of directories containing C includes for this package (maybe the empty list). @@ -599,9 +626,10 @@ the auto packages required for linking without further assistance. - c_includes - c_includes - package specification + + c_includes + c_includespackage specification + A list of files to include for via-C compilations using this package. Typically this include file will @@ -613,9 +641,10 @@ the auto packages required for linking without further assistance. - package_deps - package_deps - package specification + + package_deps + package_depspackage specification + A list of packages which this package depends on. @@ -623,9 +652,10 @@ the auto packages required for linking without further assistance. - extra_ghc_opts - extra_ghc_opts - package specification + + extra_ghc_opts + extra_ghc_optspackage specification + Extra arguments to be added to the GHC command line when this package is being used. @@ -633,9 +663,10 @@ the auto packages required for linking without further assistance. - extra_cc_opts - extra_cc_opts - package specification + + extra_cc_opts + extra_cc_optspackage specification + Extra arguments to be added to the gcc command line when this package is being used (only for via-C @@ -644,9 +675,10 @@ the auto packages required for linking without further assistance. - extra_ld_opts - extra_ld_opts - package specification + + extra_ld_opts + extra_ld_optspackage specification + Extra arguments to be added to the gcc command line (for linking) when @@ -655,9 +687,10 @@ the auto packages required for linking without further assistance. - framework_dirs - framework_dirs - package specification + + framework_dirs + framework_dirspackage specification + On Darwin/MacOS X, a list of directories containing frameworks for this package. This corresponds to the option. @@ -666,9 +699,10 @@ the auto packages required for linking without further assistance. - extra_frameworks - extra_frameworks - package specification + + extra_frameworks + extra_frameworkspackage specification + On Darwin/MacOS X, a list of frameworks to link to. This corresponds to the option. Take a look at Apple's developer documentation diff --git a/ghc/docs/users_guide/phases.xml b/ghc/docs/users_guide/phases.xml index 567c4f4..ea3730e 100644 --- a/ghc/docs/users_guide/phases.xml +++ b/ghc/docs/users_guide/phases.xml @@ -15,9 +15,10 @@ - cmd - - + + cmd + + Use cmd as the literate pre-processor. @@ -25,9 +26,10 @@ - cmd - - + + cmd + + Use cmd as the C pre-processor (with only). @@ -35,9 +37,10 @@ - cmd - - + + cmd + + Use cmd as the C compiler. @@ -45,9 +48,10 @@ - cmd - - + + cmd + + Use cmd as the assembler. @@ -55,9 +59,10 @@ - cmd - - + + cmd + + Use cmd as the linker. @@ -65,9 +70,10 @@ - cmd - - + + cmd + + Use cmd as the DLL generator. @@ -75,9 +81,10 @@ - cmd - - + + cmd + + Use cmd as the dependency generator. @@ -85,9 +92,10 @@ - cmd - - + + cmd + + Use cmd as the pre-processor (with only). @@ -106,68 +114,76 @@ - option - - + + option + + Pass option to the literate pre-processor - option - - + + option + + Pass option to CPP (makes sense only if is also on). - option - - + + option + + Pass option to the custom pre-processor (see ). - option - - + + option + + Pass option to the C compiler. - option - - + + option + + Pass option to the assembler. - option - - + + option + + Pass option to the linker. - option - - + + option + + Pass option to the DLL generator. - option - - + + option + + Pass option to the dependency generator. @@ -197,8 +213,10 @@ - - + + + + The C pre-processor cpp is run over your Haskell code only if the @@ -211,8 +229,10 @@ - symbol=value - + + symbol=value + + Define macro symbol in the usual way. NB: does not affect @@ -224,8 +244,10 @@ - symbol - + + symbol + + Undefine macro symbol in the usual way. @@ -233,8 +255,10 @@ - dir - + + dir + + Specify a directory in which to look for #include files, in the usual C @@ -250,8 +274,10 @@ - __HASKELL98__ - __HASKELL98__ + + __HASKELL98__ + __HASKELL98__ + If defined, this means that GHC supports the language defined by the Haskell 98 report. @@ -259,8 +285,10 @@ - __HASKELL__=98 - __HASKELL__=98 + + __HASKELL__=98 + __HASKELL__=98 + In GHC 4.04 and later, the __HASKELL__ @@ -270,9 +298,10 @@ - __HASKELL1__ - __HASKELL1__ - + + __HASKELL1__ + __HASKELL1__ + If defined to n, that means GHC supports the Haskell language defined in the @@ -283,8 +312,10 @@ - __GLASGOW_HASKELL__ - __GLASGOW_HASKELL__ + + __GLASGOW_HASKELL__ + __GLASGOW_HASKELL__ + For version n of the GHC system, this will be #defined to @@ -315,8 +346,10 @@ - __CONCURRENT_HASKELL__ - __CONCURRENT_HASKELL__ + + __CONCURRENT_HASKELL__ + __CONCURRENT_HASKELL__ + This symbol is defined when pre-processing Haskell (input) and pre-processing C (GHC output). Since GHC from @@ -326,8 +359,10 @@ - __PARALLEL_HASKELL__ - __PARALLEL_HASKELL__ + + __PARALLEL_HASKELL__ + __PARALLEL_HASKELL__ + Only defined when is in use! This symbol is defined when pre-processing Haskell @@ -371,8 +406,10 @@ strmod = "\ - - + + + + A custom pre-processor is run over your Haskell source file only if the option @@ -438,8 +475,10 @@ strmod = "\ - - + + + + Use GHC's native code generator rather than compiling via C. This will compile faster (up to twice as @@ -451,9 +490,10 @@ strmod = "\ - - - + + + + Compile via C instead of using the native code generator. This is default for optimised compilations, @@ -463,9 +503,10 @@ strmod = "\ - - - + + + + Omit code generation (and all later phases) altogether. Might be of some use if you just want to see @@ -489,8 +530,10 @@ strmod = "\ - lib - + + lib + + Link in the lib library. On Unix systems, this will be in a file called @@ -527,10 +570,10 @@ strmod = "\ - - - - + + + + Omit the link step. This flag can be useful if you want to avoid linking in mode, @@ -540,8 +583,10 @@ strmod = "\ - name - + + name + + If you are using a Haskell “package” (see ), don't forget to add the @@ -554,8 +599,10 @@ strmod = "\ - name - + + name + + On Darwin/MacOS X only, link in the framework name. This option corresponds to the option for Apple's Linker. @@ -568,8 +615,10 @@ strmod = "\ - dir - + + dir + + Where to find user-supplied libraries… Prepend the directory dir to @@ -578,8 +627,10 @@ strmod = "\ - dir - + + dir + + On Darwin/MacOS X only, prepend the directory dir to the framework directories path. This option corresponds to the @@ -588,8 +639,10 @@ strmod = "\ - - + + + + Tell the linker to split the single object file that would normally be generated into multiple object files, @@ -601,8 +654,10 @@ strmod = "\ - - + + + + Tell the linker to avoid shared Haskell libraries, if possible. This is the default. @@ -610,8 +665,10 @@ strmod = "\ - - + + + + Tell the linker to use shared Haskell libraries, if available (this option is only supported on Windows at the @@ -621,9 +678,11 @@ strmod = "\ - - - specifying your own main function + + + + specifying your own main function + The normal rule in Haskell is that your program must supply a main function in module Main. When testing, it is often convenient @@ -642,9 +701,11 @@ strmod = "\ - - - linking Haskell libraries with foreign code + + + + linking Haskell libraries with foreign code + In the event you want to include ghc-compiled code as part of another (non-Haskell) program, the RTS will not @@ -671,9 +732,10 @@ strmod = "\ - - - + + + + Link the program with a debugging version of the runtime system. The debugging runtime turns on numerous @@ -684,9 +746,10 @@ strmod = "\ - - - + + + + Link the program with the "threaded" runtime system. This version of the runtime is designed to be used in diff --git a/ghc/docs/users_guide/profiling.xml b/ghc/docs/users_guide/profiling.xml index bae780d..52fc8d8 100644 --- a/ghc/docs/users_guide/profiling.xml +++ b/ghc/docs/users_guide/profiling.xml @@ -345,8 +345,10 @@ x = nfib 25 - : - + + : + + To make use of the profiling system all modules must be compiled and linked @@ -369,9 +371,11 @@ x = nfib 25 - : - - cost centresautomatically inserting + + : + + cost centresautomatically inserting + GHC will automatically add _scc_ constructs for all @@ -380,8 +384,10 @@ x = nfib 25 - : - + + : + + All top-level functions, exported or not, will be automatically @@ -390,8 +396,10 @@ x = nfib 25 - : - + + : + + The costs of all CAFs in a module are usually attributed to one “big” CAF cost-centre. With @@ -401,8 +409,10 @@ x = nfib 25 - : - + + : + + Ignore any _scc_ constructs, so a module which already has @@ -425,10 +435,12 @@ x = nfib 25 - or : - - - time profile + + or : + + + time profile + The option produces a standard time profile report. It is written @@ -442,8 +454,10 @@ x = nfib 25 - : - + + : + + The option generates profiling information in the XML format understood by our new @@ -452,9 +466,10 @@ x = nfib 25 - - RTS - option + + + RTS option + This option makes use of the extra information maintained by the cost-centre-stack profiler to provide @@ -516,9 +531,10 @@ x = nfib 25 - - RTS - option + + + RTS option + Breaks down the graph by the cost-centre stack which produced the data. @@ -526,9 +542,10 @@ x = nfib 25 - - RTS - option + + + RTS option + Break down the live heap by the module containing the code which produced the data. @@ -536,9 +553,10 @@ x = nfib 25 - - RTS - option + + + RTS option + Breaks down the graph by closure description. For actual data, the description @@ -548,9 +566,10 @@ x = nfib 25 - - RTS - option + + + RTS option + Breaks down the graph by type. For closures which have @@ -560,9 +579,10 @@ x = nfib 25 - - RTS - option + + + RTS option + Break down the graph by retainer set. Retainer profiling is described in more @@ -571,9 +591,10 @@ x = nfib 25 - - RTS - option + + + RTS option + Break down the graph by biography. Biographical profiling @@ -591,9 +612,10 @@ x = nfib 25 - name,... - RTS - option + + name,... + RTS option + Restrict the profile to closures produced by cost-centre stacks with one of the specified cost centres @@ -602,9 +624,10 @@ x = nfib 25 - name,... - RTS - option + + name,... + RTS option + Restrict the profile to closures produced by cost-centre stacks with one of the specified cost centres @@ -613,9 +636,10 @@ x = nfib 25 - module,... - RTS - option + + module,... + RTS option + Restrict the profile to closures produced by the specified modules. @@ -623,9 +647,10 @@ x = nfib 25 - desc,... - RTS - option + + desc,... + RTS option + Restrict the profile to closures with the specified description strings. @@ -633,9 +658,10 @@ x = nfib 25 - type,... - RTS - option + + type,... + RTS option + Restrict the profile to closures with the specified types. @@ -643,9 +669,10 @@ x = nfib 25 - cc,... - RTS - option + + cc,... + RTS option + Restrict the profile to closures with retainer sets containing cost-centre stacks with one of the specified @@ -654,9 +681,10 @@ x = nfib 25 - bio,... - RTS - option + + bio,... + RTS option + Restrict the profile to closures with one of the specified biographies, where @@ -687,8 +715,10 @@ x = nfib 25 - : - + + : + + Set the profiling (sampling) interval to secs seconds (the default is @@ -700,9 +730,10 @@ x = nfib 25 - - RTS option - + + + RTS option + Include the memory occupied by threads in a heap profile. Each thread takes up a small area for its thread diff --git a/ghc/docs/users_guide/runtime_control.xml b/ghc/docs/users_guide/runtime_control.xml index e05d1a6..ee62855 100644 --- a/ghc/docs/users_guide/runtime_control.xml +++ b/ghc/docs/users_guide/runtime_control.xml @@ -99,9 +99,11 @@ - size - RTS option - allocation area, size + + size + RTS option + allocation area, size + [Default: 256k] Set the allocation area size used by the garbage collector. The allocation area @@ -122,13 +124,12 @@ - - RTS option - - garbage collectioncompacting - - compacting garbage collection - + + + RTS option + garbage collectioncompacting + compacting garbage collection + Use a compacting algorithm for collecting the oldest generation. By default, the oldest generation is collected @@ -164,10 +165,12 @@ - factor + + factor + RTS option + heap size, factor + - RTS option - heap size, factor [Default: 2] This option controls the amount of memory reserved for the older generations (and in the @@ -191,10 +194,11 @@ - generations - RTS option - generations, number - of + + generations + RTS option + generations, number of + [Default: 2] Set the number of generations used by the garbage collector. The default of 2 seems to be @@ -216,9 +220,11 @@ - size - RTS option - heap size, suggested + + size + RTS option + heap size, suggested + [Default: 0] This option provides a “suggested heap size” for the garbage collector. The @@ -238,9 +244,11 @@ - size - RTS option - stack, minimum size + + size + RTS option + stack, minimum size + [Default: 1k] Set the initial stack size for new threads. Thread stacks (including the main thread's @@ -256,9 +264,11 @@ - size - RTS option - stack, maximum size + + size + RTS option + stack, maximum size + [Default: 8M] Set the maximum stack size for an individual thread to size @@ -269,9 +279,11 @@ - n - RTS option - heap, minimum free + + n + RTS option + heap, minimum free + Minimum % n of heap which must be available for allocation. The default is @@ -280,9 +292,11 @@ - size - RTS option - heap size, maximum + + size + RTS option + heap size, maximum + [Default: unlimited] Set the maximum heap size to size bytes. The heap normally @@ -304,10 +318,14 @@ - file - file - RTS option - RTS option + + file + RTS option + + + file + RTS option + Write modest () or verbose () garbage-collector statistics into file @@ -325,8 +343,10 @@ - - RTS option + + + RTS option + Write a one-line GC stats summary after running the program. This output is in the same format as that produced @@ -359,8 +379,10 @@ - - RTS option + + + RTS option + Sound the bell at the start of each (major) garbage collection. @@ -378,8 +400,10 @@ - num - -DRTS option + + num + -DRTS option + An RTS debugging flag; varying quantities of output depending on which bits are set in @@ -389,10 +413,12 @@ - file - RTS option - ticky ticky profiling - profilingticky ticky + + file + RTS option + ticky ticky profiling + profilingticky ticky + Produce “ticky-ticky” statistics at the end of the program run. The file @@ -413,9 +439,10 @@ - - RTS - option + + + RTS option + (Only available when the program is compiled for profiling.) When an exception is raised in the program, @@ -450,9 +477,10 @@ - - RTS - option + + + RTS option + Turn off “update-frame squeezing” at garbage-collection time. (There's no @@ -508,24 +536,30 @@ char *ghc_rts_opts = "-H128m -K1m"; - void OutOfHeapHook (unsigned long, unsigned long) - OutOfHeapHook + + void OutOfHeapHook (unsigned long, unsigned long) + OutOfHeapHook + The heap-overflow message. - void StackOverflowHook (long int) - StackOverflowHook + + void StackOverflowHook (long int) + StackOverflowHook + The stack-overflow message. - void MallocFailHook (long int) - MallocFailHook + + void MallocFailHook (long int) + MallocFailHook + The message printed if malloc fails. diff --git a/ghc/docs/users_guide/using.xml b/ghc/docs/users_guide/using.xml index ec6187b..2ddc60b 100644 --- a/ghc/docs/users_guide/using.xml +++ b/ghc/docs/users_guide/using.xml @@ -1058,8 +1058,10 @@ f "2" = 2 - No -type option specified: - -O* not specified + + No -type option specified: + -O* not specified + This is taken to mean: “Please compile quickly; I'm not over-bothered about compiled-code @@ -1069,8 +1071,10 @@ f "2" = 2 - : - + + : + + Means “turn off all optimisation”, reverting to the same settings as if no @@ -1082,10 +1086,12 @@ f "2" = 2 - or : - -O option - -O1 option - optimisenormally + + or : + -O option + -O1 option + optimisenormally + Means: “Generate good-quality code without taking too long about it.” Thus, for example: @@ -1098,9 +1104,11 @@ f "2" = 2 - : - -O2 option - optimiseaggressively + + : + -O2 option + optimiseaggressively + Means: “Apply every non-dangerous optimisation, even if it means significantly longer @@ -1118,9 +1126,11 @@ f "2" = 2 - : - -Ofile <file> option - optimising, customised + + : + -Ofile <file> option + optimising, customised + (NOTE: not supported since GHC 4.x. Please ask if you're interested in this.) @@ -1195,9 +1205,10 @@ f "2" = 2 - - - + + + + Turns off the strictness analyser; sometimes it eats too many cycles. @@ -1205,9 +1216,10 @@ f "2" = 2 - - - + + + + Turns off the CPR (constructed product result) analysis; it is somewhat experimental. @@ -1215,12 +1227,13 @@ f "2" = 2 - : - + + : strict constructor fields constructor fields, strict - + + This option causes all constructor fields which are marked strict (i.e. “!”) to be unboxed or unpacked if possible. It is equivalent to adding an @@ -1236,8 +1249,10 @@ f "2" = 2 - - + + + + Switches on an experimental "optimisation". Switching it on makes the compiler a little keener to @@ -1252,12 +1267,13 @@ f "2" = 2 - : - + + : inlining, controlling unfolding, controlling - + + (Default: 45) Governs the maximum size that GHC will allow a function unfolding to be. (An unfolding has a “size” that reflects the cost in terms of @@ -1750,10 +1766,10 @@ statements or clauses. - - - - + + + + Generate .hcr files.