X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fusing.xml;h=2fe5959b594998abddee6758b0732e976912dbe6;hb=d62101efb9e263173b69fb89c07f03dcf805e81f;hp=7bf85ef382346138c2d7ed909aab77ca2426b3ee;hpb=93db1991b5cacf8357493a2e17fbbfb485f3205b;p=ghc-hetmet.git
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 7bf85ef..2fe5959 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 argumentsstructure, command-linecommand-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 filessource-file options
@@ -73,15 +73,14 @@ module X where
maintains internally, so you'll be desperately disappointed if
you try to glob etc. inside OPTIONS_GHC.
- NOTE: the contents of OPTIONS_GHC are prepended to the
- command-line options, so you do have the
- ability to override OPTIONS_GHC settings via the command
- line.
+ NOTE: the contents of OPTIONS_GHC are appended to the
+ command-line options, so options given in the source file
+ override those given on 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_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 +103,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 +112,7 @@ module X where
Mode flagsFor 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 .
@@ -138,6 +137,11 @@ module X where
The flag reference tables () lists the status of each flag.
+
+ There are a few flags that are static except that they can
+ also be used with GHCi's :set command; these
+ are listed as “static/:set” in the
+ table.
@@ -225,8 +229,7 @@ module X where
- ghc
- ––interactive
+ ghc --interactiveinteractive modeghci
@@ -240,8 +243,7 @@ module X where
- ghc
- ––make
+ ghc --makemake mode
@@ -258,8 +260,8 @@ module X where
- ghc
- –eexpr
+ ghc -e
+ expreval mode
@@ -275,13 +277,10 @@ module X where
- ghc
-
- -E
- -C
- -S
- -c
-
+ ghc -E
+ ghc -c
+ ghc -S
+ ghc -c
@@ -302,8 +301,7 @@ module X where
- ghc
- –M
+ ghc -Mdependency-generation mode
@@ -311,23 +309,119 @@ 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"/>.
- ghc
- ––mk-dll
+ ghc --mk-dll
- dependency-generation mode
+ DLL-creation modeDLL-creation mode (Windows only). See .
+
+
+
+
+ ghc --helpghc -?
+
+
+
+
+ Cause GHC to spew a long usage message to standard
+ output and then exit.
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ ghc --numeric-version
+
+
+
+
+ Print GHC's numeric version number only.
+
+
+
+
+
+
+ ghc --print-libdir
+
+
+
+
+ Print the path to GHC's library directory. This is
+ the top of the directory tree containing GHC's libraries,
+ 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 ).
+
+
+
+
+
+
+ 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.
+
+
+
@@ -337,7 +431,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
@@ -351,7 +445,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
@@ -446,7 +540,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:
@@ -538,9 +632,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
@@ -574,19 +666,18 @@ ghc -c Foo.hs
help optionsverbosity options
+ See also the , , ,
+ and modes in .
-
-
-
-
-
-
+
+
- Cause GHC to spew a long usage message to standard
- output and then exit.
+ Does a dry-run, i.e. GHC goes through all the motions
+ of compiling as normal, but does not actually run any
+ external commands.
@@ -673,47 +764,6 @@ ghc -c Foo.hs
-
-
-
-
-
-
-
-
-
- Print a one-line string including GHC's version number.
-
-
-
-
-
-
-
-
-
- Print GHC's numeric version number only.
-
-
-
-
-
-
-
-
-
- Print the path to GHC's library directory. This is
- the top of the directory tree containing GHC's libraries,
- 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 ).
-
-
-
-
@@ -748,6 +798,20 @@ ghc -c Foo.hs
+ size
+
+
+
+ Set the minimum size of the heap to
+ size.
+ This option is equivalent to
+ +RTS -Hsize,
+ see .
+
+
+
+
+
@@ -792,26 +856,35 @@ ghc -c Foo.hs
-W optionProvides the standard warnings plus
,
+ ,
,
- ,
- , and
+ , and
.
- :
+ :
-
- 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.
@@ -824,6 +897,16 @@ ghc -c Foo.hs
+
+ :
+
+
+ Warnings are treated only as warnings, not as errors. This is
+ the default, but can be useful to negate a
+ flag.
+
+
+
The full set of warning options is described below. To turn
@@ -842,6 +925,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.
@@ -877,6 +974,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.
+
+
+
+ :
@@ -893,7 +1015,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.
@@ -921,7 +1043,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.
@@ -929,19 +1051,6 @@ f foo = foo { x = 6 }
- :
-
-
-
- Turns on warnings for various harmless but untidy
- things. This currently includes: importing a type with
- (..) when the export is abstract, and
- listing duplicate class assertions in a qualified type.
-
-
-
-
-
:
missing fields, warning
@@ -991,7 +1100,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.
@@ -1006,12 +1116,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 ....
@@ -1045,7 +1151,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
@@ -1070,7 +1176,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:
@@ -1080,10 +1186,18 @@ 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.)
+
+
+
+
+ :
+
+
+ tabs, warning
+ Have the compiler warn if there are tabs in your source
+ file.
+ This warning is off by default.
@@ -1096,7 +1210,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
@@ -1108,6 +1222,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.
+
+
+
+ :
@@ -1199,7 +1327,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.
@@ -1243,10 +1371,6 @@ f "2" = 2
Means: “Generate good-quality code without
taking too long about it.” Thus, for example:
ghc -c -O Main.lhs
-
- currently also implies
- . This may change in the
- future.
@@ -1345,7 +1469,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
.
@@ -1412,6 +1536,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
@@ -1434,7 +1602,7 @@ f "2" = 2
-
+
@@ -1452,7 +1620,7 @@ f "2" = 2
- :
+ :
inlining, controllingunfolding, controlling
@@ -1478,7 +1646,7 @@ f "2" = 2
- :
+ inlining, controlling
@@ -1500,7 +1668,7 @@ f "2" = 2
&phases;
-
+ Using Concurrent HaskellConcurrent Haskellusing
@@ -1530,7 +1698,7 @@ f "2" = 2
-
+ Using SMP parallelismparallelism
@@ -1624,18 +1792,6 @@ f "2" = 2
- :
-
- (SPARC machines)-mv8 option (SPARC
- only) Means to pass the like-named
- option to GCC; it says to use the Version 8 SPARC
- instructions, notably integer multiply and divide. The
- similar GCC options for SPARC also
- work, actually.
-
-
-
- :(iX86 machines)-monly-N-regs