X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fusing.xml;h=9df6eb50b694e60ff27cc97be8210fcdf27ef0f6;hb=e11fa7a5e0025460df3b8562ccbf3ffd1db68d5d;hp=f6afa3c7e65aba6bd372f785f3d6053ea6e6aef2;hpb=4d2b98d0d8e0a349d2448d93d8c0518045489854;p=ghc-hetmet.git diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml index f6afa3c..9df6eb5 100644 --- a/docs/users_guide/using.xml +++ b/docs/users_guide/using.xml @@ -14,7 +14,7 @@ Options can be specified in three ways: - command-line arguments + Command-line arguments structure, command-line command-linearguments @@ -26,9 +26,9 @@ ghc [argument...] - command-line arguments are either options or file names. + Command-line arguments are either options or file names. - command-line options begin with -. + Command-line options begin with -. They may not be grouped: is different from . Options need not precede filenames: e.g., ghc *.o -o @@ -40,7 +40,7 @@ ghc [argument...] - command line options in source files + Command line options in source files source-file options @@ -81,7 +81,7 @@ module X where It is not recommended to move all the contents of your Makefiles into your source files, but in some circumstances, the OPTIONS_GHC pragma is the Right Thing. (If you - use and have OPTION flags in + use and have OPTION flags in your module, the OPTIONS_GHC will get put into the generated .hc file). @@ -104,8 +104,8 @@ module X where modeoptions - Each of GHC's command line options is classified as either - static or dynamic or + Each of GHC's command line options is classified as + static, dynamic or mode: @@ -113,7 +113,7 @@ module X where Mode flags For example, or . - There may be only a single mode flag on the command line. The + There may only be a single mode flag on the command line. The available modes are listed in . @@ -310,7 +310,7 @@ module X where Dependency-generation mode. In this mode, GHC can be used to generate dependency information suitable for use in a Makefile. See . + linkend="makefile-dependencies"/>. @@ -343,10 +343,35 @@ module X where - ghc --version ghc -V + ghc --supported-languages + + + + + Print the supported language extensions. + + + + + + + ghc --info + + + + + Print information about the compiler. + + + + + + + ghc --version + ghc -V + - Print a one-line string including GHC's version number. @@ -356,9 +381,9 @@ module X where - ghc --numeric-version + ghc --numeric-version + - Print GHC's numeric version number only. @@ -368,9 +393,9 @@ module X where - ghc --print-libdir + ghc --print-libdir + - Print the path to GHC's library directory. This is @@ -378,9 +403,23 @@ module X where interfaces, and include files (usually something like /usr/local/lib/ghc-5.04 on Unix). This is the value of - $libdirlibdir - in the package configuration file (see ). + $libdirlibdir + in the package configuration file + (see ). + + + + + + + ghc --print-docdir + + + + + Print the path to GHC's documentation directory. Note that + some distributions do no include the documentation, in which case + this directory may be empty or may not exist. @@ -393,7 +432,7 @@ module X where When given the option, GHC will build a multi-module Haskell program by following - dependencies from a single root module (usually + dependencies from one or more root modules (usually just Main). For example, if your Main module is in a file called Main.hs, you could compile and link the @@ -407,7 +446,7 @@ ghc ––make Main.hs names or module names; GHC will figure out all the modules in the program by following the imports from these initial modules. It will then attempt to compile each module which is out of - date, and finally if there is a Main module, + date, and finally, if there is a Main module, the program will also be linked into an executable. The main advantages to using ghc @@ -502,7 +541,7 @@ olleh The first phase to run is determined by each 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. + relevant flag is present, then go all the way through to linking. This table summarises: @@ -594,9 +633,7 @@ ghc -c Foo.hs Note: The option -E option runs just the pre-processing passes - of the compiler, dumping the result in a file. Note that this - differs from the previous behaviour of dumping the file to - standard output. + of the compiler, dumping the result in a file. Overriding the default behaviour for a file @@ -630,8 +667,8 @@ ghc -c Foo.hs help options verbosity options - See also the , , , - and modes in . + See also the , , , + and modes in . @@ -820,6 +857,7 @@ ghc -c Foo.hs -W option Provides the standard warnings plus , + , , , and . @@ -827,18 +865,27 @@ ghc -c Foo.hs - : + : - - Turns off all warnings, including the standard ones. + + Turns on all warning options that indicate potentially + suspicious code. The warnings that are + not enabled by + are + , + , + , + , and + . - : + : - - Turns on all warning options. + + Turns off all warnings, including the standard ones and + those that -Wall doesn't enable. @@ -869,6 +916,20 @@ ghc -c Foo.hs function or type is used. Entities can be marked as deprecated using a pragma, see . + + This option is on by default. + + + + + : + + + + Causes a warning to be emitted when a a datatype + T is imported + with all constructors, i.e. T(..), but has been + exported abstractly, i.e. T. @@ -904,6 +965,31 @@ ghc -c Foo.hs + : + + + implicit prelude, warning + Have the compiler warn if the Prelude is implicitly + imported. This happens unless either the Prelude module is + explicitly imported with an import ... Prelude ... + line, or this implicit import is disabled (either by + or a + LANGUAGE NoImplicitPrelude pragma). + + Note that no warning is given for syntax that implicitly + refers to the Prelude, even if + would change whether it refers to the Prelude. + For example, no warning is given when + 368 means + Prelude.fromInteger (368::Prelude.Integer) + (where Prelude refers to the actual Prelude module, + regardless of the imports of the module being compiled). + + This warning is off by default. + + + + : @@ -920,7 +1006,7 @@ ghc -c Foo.hs g [] = 2 - This option isn't enabled be default because it can be + This option isn't enabled by 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. @@ -948,7 +1034,7 @@ f :: Foo -> Foo f foo = foo { x = 6 } - This option isn't enabled be default because it can be + This option isn't enabled by default because it can be very noisy, and it often doesn't indicate a bug in the program. @@ -1005,7 +1091,8 @@ f foo = foo { x = 6 } If you would like GHC to check that every top-level function/value has a type signature, use the - option. This + option. As part of + the warning GHC also reports the inferred type. The option is off by default. @@ -1020,12 +1107,8 @@ f foo = foo { x = 6 } 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 - will complain about cyclic recursive - definitions. + in the inadvertent capture of what would be a recursive call in + f = ... let f = id in ... f .... @@ -1059,7 +1142,7 @@ f foo = foo { x = 6 } By default, the compiler will warn you if a set of - patterns are overlapping, i.e., + patterns are overlapping, e.g., f :: String -> Int @@ -1084,7 +1167,7 @@ f "2" = 2 patterns that can fail, eg. \(x:xs)->.... Normally, these aren't treated as incomplete patterns by . - ``Lambda-bound patterns'' includes all places where there is a single pattern, + “Lambda-bound patterns” includes all places where there is a single pattern, including list comprehensions and do-notation. In these cases, a pattern-match failure is quite legitimate, and triggers filtering (list comprehensions) or the monad fail operation (monads). For example: @@ -1094,10 +1177,6 @@ f "2" = 2 Switching on will elicit warnings about these probably-innocent cases, which is why the flag is off by default. - The deriving( Read ) mechanism produces monadic code with - pattern matches, so you will also get misleading warnings about the compiler-generated - code. (This is arguably a Bad Thing, but it's awkward to fix.) - @@ -1122,7 +1201,7 @@ f "2" = 2 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 + e.g., the ‘default default’ for Haskell 1.4 caused the otherwise unconstrained value 1 to be given the type Int, whereas Haskell 98 defaults it to Integer. This may lead to @@ -1134,6 +1213,20 @@ f "2" = 2 + : + + + monomorphism restriction, warning + Have the compiler warn/inform you where in your source + the Haskell Monomorphism Restriction is applied. If applied silently + the MR can give rise to unexpected behaviour, so it can be helpful + to have an explicit warning that it is being applied. + + This warning is off by default. + + + + : @@ -1225,7 +1318,7 @@ f "2" = 2 Note that higher optimisation levels cause more cross-module optimisation to be performed, which can have an impact on how much of your program needs to be recompiled when - you change something. This is one reaosn to stick to + you change something. This is one reason to stick to no-optimisation when developing code. @@ -1367,7 +1460,7 @@ f "2" = 2 Exception.assert in source code (in other words, rewriting Exception.assert p e to e (see ). This flag is turned on by + linkend="assertions"/>). This flag is turned on by . @@ -1434,6 +1527,50 @@ f "2" = 2 + + + + + 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. + + + + + + + + + + Tells GHC to omit all inessential information from the interface file + generated for the module being compiled (say M). This means that a module + importing M will see only the types of the functions that M exports, but not + their unfoldings, strictness info, etc. Hence, for example, + no function exported by M will be inlined + into an importing module. The benefit is that modules that import M will + need to be recompiled less often (only when M's exports change their type, + not when they change their implementation). + + + + + + + + + + + Tells GHC to ignore all inessential information when reading interface files. + That is, even if M.hi contains unfolding or strictness information + for a function, GHC will ignore that information. + + + + + : strict constructor fields @@ -1456,7 +1593,7 @@ f "2" = 2 - + @@ -1474,7 +1611,7 @@ f "2" = 2 - : + : inlining, controlling unfolding, controlling @@ -1500,7 +1637,7 @@ f "2" = 2 - : + inlining, controlling @@ -1522,7 +1659,7 @@ f "2" = 2 &phases; - + Using Concurrent Haskell Concurrent Haskellusing @@ -1552,7 +1689,7 @@ f "2" = 2 - + Using SMP parallelism parallelism