X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fusing.xml;h=32c194a30803fc43a2ad07ae0b16af5f41cbd612;hb=2a2efb720c0fdc06fe749f96f284b00b30f8f3f7;hp=ffe639c507befa110a46da089790ab9c47a15249;hpb=beeecedc85ef566031cc49ae7a370ab44f83bbbd;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/using.xml b/ghc/docs/users_guide/using.xml index ffe639c..32c194a 100644 --- a/ghc/docs/users_guide/using.xml +++ b/ghc/docs/users_guide/using.xml @@ -51,35 +51,38 @@ ghc [argument...] option. Rather than maintaining the list of per-file options in a Makefile, it is possible to do this directly in the source file using the - OPTIONS pragma OPTIONS + OPTIONS_GHC pragma OPTIONS_GHC pragma: -{-# OPTIONS -fglasgow-exts #-} +{-# OPTIONS_GHC -fglasgow-exts #-} module X where ... - OPTIONS pragmas are only looked for at + OPTIONS_GHC 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 + OPTIONS_GHC. Multiple OPTIONS_GHC + pragmas are recognised. Do not put comments before, or on the same line + as, the OPTIONS_GHC pragma. + + 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 + in the array of command-line arguments the compiler maintains internally, so you'll be desperately disappointed if - you try to glob etc. inside OPTIONS. + you try to glob etc. inside OPTIONS_GHC. - NOTE: the contents of OPTIONS are prepended to the + NOTE: the contents of OPTIONS_GHC are prepended to the command-line options, so you do have the - ability to override OPTIONS settings via the command + ability to override OPTIONS_GHC 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 + OPTIONS_GHC pragma is the Right Thing. (If you use and have OPTION flags in - your module, the OPTIONS will get put into the generated .hc + your module, the OPTIONS_GHC will get put into the generated .hc file). @@ -93,21 +96,47 @@ module X where - Static vs. Dynamic options + Static, Dynamic, and Mode options staticoptions dynamicoptions + modeoptions + Each of GHC's command line options is classified as either - static or dynamic. - A static flag may only be specified on the command line, whereas a - dynamic flag may also be given in an OPTIONS - pragma in a source file or set from the GHCi command-line with - :set. - - As a rule of thumb, options which relate to filenames are - static, and the rest are dynamic. The flag reference tables (static or dynamic or + mode: + + + + Mode flags + + For example, or . + There may be only a single mode flag on the command line. The + available modes are listed in . + + + + Dynamic Flags + + Most non-mode flags fall into this category. A dynamic flag + may be used on the command line, in a + GHC_OPTIONS pragma in a source file, or set + using :set in GHCi. + + + + Static Flags + + A few flags are "static", which means they can only be used on + the command-line, and remain in force over the entire GHC/GHCi + run. + + + + + The flag reference tables () lists the status of each flag. @@ -354,7 +383,7 @@ ghc ––make Main.hs , but note that any options you give on the command line will apply to all the source files compiled, so if you want any options to apply to a single source - file only, you'll need to use an OPTIONS + file only, you'll need to use an OPTIONS_GHC pragma (see ). If the program needs to be linked with additional objects @@ -512,6 +541,30 @@ ghc -c Foo.hs of the compiler, dumping the result in a file. Note that this differs from the previous behaviour of dumping the file to standard output. + + + Overriding the default behaviour for a file + + As described above, the way in which a file is processed by GHC + depends on its suffix. This behaviour can be overriden using the + option: + + + + suffix + + + + Causes all files following this option on the command + line to be processed as if they had the suffix + suffix. For example, to compile a + Haskell module in the file M.my-hs, + use ghc -c -x hs M.my-hs. + + + + + @@ -693,6 +746,19 @@ ghc -c Foo.hs it). + + + + + + + Prints a one-line summary of timing statistics for the + GHC run. This option is equivalent to + +RTS -tstderr, see . + + + @@ -835,6 +901,33 @@ g [] = 2 + : + + + incomplete record updates, warning + record updates, incomplete + + The function + f below will fail when applied to + Bar, so the compiler will emit a warning about + this when is + enabled. + + +data Foo = Foo { x :: Int } + | Bar + +f :: Foo -> Foo +f foo = foo { x = 6 } + + + This option isn't enabled be default because it can be + very noisy, and it often doesn't indicate a bug in the + program. + + + + : @@ -923,6 +1016,27 @@ g [] = 2 + : + + + orphan instances, warning + orphan rules, warning + + This option causes a warning to be emitted whenever the + module contains an "orphan" instance declaration or rewrite rule. + An instance declartion is an orphan if it appears in a module in + which neither the class nor the type being instanced are declared + in the same module. A rule is an orphan if it is a rule for a + function declared in another module. A module containing any + orphans is called an orphan module. + The trouble with orphans is that GHC must pro-actively read the interface + files for all orphan modules, just in case their instances or rules + play a role, whether or not the module's interface would otherwise + be of any use. Other things being equal, avoid orphan modules. + + + + : @@ -1239,6 +1353,18 @@ f "2" = 2 + + + + + Turns off the common-sub-expression elimination optimisation. + Can be useful if you have some unsafePerformIO + expressions that you don't want commoned-up. + + + + + @@ -1250,12 +1376,27 @@ f "2" = 2 - - + + - Turns off the CPR (constructed product result) - analysis; it is somewhat experimental. + Turns off the full laziness optimisation (also known as + let-floating). Full laziness increases sharing, which can lead + to increased memory residency. + + + + + + + + + + Turn off the "state hack" whereby any lambda with a + State# token as argument is considered to be + single-entry, hence it is considered OK to inline things inside + it. This can improve performance of IO and ST monad code, but it + runs the risk of reducing sharing. @@ -1350,38 +1491,47 @@ f "2" = 2 &phases; -Using Concurrent Haskell - - Concurrent Haskell—use + Using Concurrent Haskell + Concurrent Haskellusing - -GHC supports Concurrent Haskell by default, without requiring a -special option or libraries compiled in a certain way. To get access -to the support libraries for Concurrent Haskell, just import -Control.Concurrent (details are in the accompanying -library documentation). - - -RTS options are provided for modifying the behaviour of the threaded -runtime system. See . - + GHC supports Concurrent Haskell by default, without requiring a + special option or libraries compiled in a certain way. To get access to + the support libraries for Concurrent Haskell, just import + Control.Concurrent. More information on Concurrent Haskell is provided in the documentation for that module. - -Concurrent Haskell is described in more detail in the documentation -for the Control.Concurrent module. - + The following RTS option(s) affect the behaviour of Concurrent + Haskell programs:RTS options, concurrent - + + + + + RTS option + Sets the context switch interval to s + seconds. A context switch will occur at the next heap block + allocation after the timer expires (a heap block allocation occurs + every 4k of allocation). With or + , context switches will occur as often as + possible (at every heap block allocation). By default, context + switches occur every 20ms. Note that GHC's internal timer ticks + every 20ms, and the context switch timer is always a multiple of + this timer, so 20ms is the maximum granularity available for timed + context switches. + + + + Using parallel Haskell -parallel Haskell—use - - - -[You won't be able to execute parallel Haskell programs unless PVM3 +Parallel Haskellusing +[NOTE: GHC does not support Parallel Haskell by default, you need to + obtain a special version of GHC from the GPH site. Also, +you won't be able to execute parallel Haskell programs unless PVM3 (parallel Virtual Machine, version 3) is installed at your site.] @@ -1390,7 +1540,7 @@ To compile a Haskell program for parallel execution under PVM, use the option,-parallel option both when compiling and linking. You will probably want to import -parallel into your Haskell modules. +Control.Parallel into your Haskell modules. @@ -1522,7 +1672,7 @@ results—only with “how parallel” it was! We want pretty pictu parallelism profiles (à la hbcpp) can be generated with the --qP RTS option (concurrent, parallel) RTS option. The +-qP RTS option 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 @@ -1567,20 +1717,18 @@ what's happening overall is: tail -f /tmp/pvml.nnn. -RTS options for Concurrent/parallel Haskell +<title>RTS options for Parallel Haskell -RTS options, concurrent RTS options, parallel -Concurrent Haskell—RTS options parallel Haskell—RTS options Besides the usual runtime system (RTS) options (), there are a few options particularly -for concurrent/parallel execution. +for parallel execution. @@ -1597,17 +1745,16 @@ the default is 2. -: +: --C<us> RTS option Sets +-C<s> RTS option Sets the context switch interval to <s> seconds. A context switch will occur at the next heap block allocation after the timer expires (a heap block allocation occurs every 4k of allocation). With or , context switches will occur as often as possible (at every heap block -allocation). By default, context switches occur every 20ms -milliseconds. Note that GHC's internal timer ticks every 20ms, and +allocation). By default, context switches occur every 20ms. Note that GHC's internal timer ticks every 20ms, and the context switch timer is always a multiple of this timer, so 20ms is the maximum granularity available for timed context switches. @@ -1636,7 +1783,7 @@ check (with ). -qt<num> RTS option -(paraLLEL ONLY) Limit the thread pool size, i.e. the number of concurrent +(paraLLEL ONLY) Limit the thread pool size, i.e. the number of threads per processor to <num>. The default is 32. Each thread requires slightly over 1K words in the heap for thread state and stack objects. (For 32-bit machines, this @@ -1823,7 +1970,7 @@ ordinary Haskell 98, when translated to External Core, uses things like rank-2 t