X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fusing.xml;h=7ef2f2f99409d11386795e6fd33516696f994e21;hb=0a435635320c2fb075694b52ddbce5bb792110f5;hp=5ad34faf5385acf0dcea828c981bf4889e45826a;hpb=53628e913632cac29d54da914040e39add334784;p=ghc-hetmet.git
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 5ad34fa..7ef2f2f 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -6,6 +6,77 @@
using GHC
+ Getting started: compiling programs
+
+
+ In this chapter you'll find a complete reference to the GHC
+ command-line syntax, including all 400+ flags. It's a large and
+ complex system, and there are lots of details, so it can be
+ quite hard to figure out how to get started. With that in mind,
+ this introductory section provides a quick introduction to the
+ basic usage of GHC for compiling a Haskell program, before the
+ following sections dive into the full syntax.
+
+
+
+ Let's create a Hello World program, and compile and run it.
+ First, create a file hello.hs containing
+ the Haskell code:
+
+
+
+main = putStrLn "Hello, World!"
+
+
+ To compile the program, use GHC like this:
+
+
+$ ghc hello.hs
+
+ (where $ represents the prompt: don't
+ type it). GHC will compile the source
+ file hello.hs, producing
+ an object
+ filehello.o and
+ an interface
+ filehello.hi, and then it
+ will link the object file to the libraries that come with GHC
+ to produce an executable called hello on
+ Unix/Linux/Mac, or hello.exe on
+ Windows.
+
+
+ By default GHC will be very quiet about what it is doing, only
+ printing error messages. If you want to see in more detail
+ what's going on behind the scenes, add to
+ the command line.
+
+
+
+ Then we can run the program like this:
+
+
+
+$ ./hello
+Hello World!
+
+
+ If your program contains multiple modules, then you only need to
+ tell GHC the name of the source file containing
+ the Main module, and GHC will examine
+ the import declarations to find the other
+ modules that make up the program and find their source files.
+ This means that, with the exception of
+ the Main module, every source file should be
+ named after the module name that it contains (with dots replaced
+ by directory separators). For example, the
+ module Data.Person would be in the
+ file Data/Person.hs on Unix/Linux/Mac,
+ or Data\Person.hs on Windows.
+
+
+
+ Options overviewGHC's behaviour is controlled by
@@ -110,7 +181,7 @@ module X where
Mode flags
- For example, or .
+ For example, or .
There may only be a single mode flag on the command line. The
available modes are listed in .
@@ -197,6 +268,22 @@ module X where
+ .ll
+
+ An llvm-intermediate-language source file, usually
+ produced by the compiler.
+
+
+
+
+ .bc
+
+ An llvm-intermediate-language bitcode file, usually
+ produced by the compiler.
+
+
+
+ .sAn assembly-language source file, usually produced by
@@ -220,10 +307,20 @@ module X where
Modes of operation
- GHC's behaviour is firstly controlled by a mode flag. Only
- one of these flags may be given, but it does not necessarily need
- to be the first option on the command-line. The available modes
- are:
+
+ GHC's behaviour is firstly controlled by a mode flag. Only one
+ of these flags may be given, but it does not necessarily need to
+ be the first option on the command-line.
+
+
+
+ If no mode flag is present, then GHC will enter make mode
+ () if there are any Haskell source
+ files given on the command line, or else it will link the
+ objects named on the command line to produce an executable.
+
+
+ The available mode flags are:
@@ -242,7 +339,7 @@ module X where
- ghc --make
+ ghc ––makemake mode
@@ -254,6 +351,12 @@ module X where
likely to be much easier, and faster, than using
make. Make mode is described in .
+
+
+ This mode is the default if there are any Haskell
+ source files mentioned on the command line, and in this case
+ the option can be omitted.
+
@@ -355,9 +458,10 @@ module X where
+ ghc --supported-extensionsghc --supported-languages
-
+ Print the supported language extensions.
@@ -428,8 +532,7 @@ module X where
separate compilation
- When given the option,
- GHC will build a multi-module Haskell program by following
+ In this mode, GHC will build a multi-module Haskell program by following
dependencies from one or more root modules (usually just
Main). For example, if your
Main module is in a file called
@@ -440,12 +543,22 @@ module X where
ghc ––make Main.hs
- The command line may contain any number of source file
- 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,
- the program will also be linked into an executable.
+
+ In fact, GHC enters make mode automatically if there are any
+ Haskell source files on the command line and no other mode is
+ specified, so in this case we could just type
+
+
+
+ghc Main.hs
+
+
+ Any number of source file names or module names may be
+ specified; 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, the
+ program will also be linked into an executable.The main advantages to using ghc
––make over traditional
@@ -876,7 +989,6 @@ ghc -c Foo.hs
suspicious code. The warnings that are
not enabled by
are
- ,
,
,
,
@@ -1026,7 +1138,7 @@ foreign import "&f" f :: FunPtr t
is bound in a way that looks lazy, e.g.
where (I# x) = .... Use
where !(I# x) = ... instead. This will be an
- error, rather than a warning, in GHC 6.14.
+ error, rather than a warning, in GHC 7.2.
@@ -1263,28 +1375,6 @@ f "2" = 2
- :
-
-
-
- Causes the compiler to warn about lambda-bound
- 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,
- 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:
-
- f :: [Maybe a] -> [a]
- f xs = [y | Just y <- xs]
-
- Switching on will elicit warnings about
- these probably-innocent cases, which is why the flag is off by default.
-
-
-
- :
@@ -1667,6 +1757,26 @@ f "2" = 2
+
+
+
+
+ Turns off the float-in transformation.
+
+
+
+
+
+
+
+
+
+ Turns off the automatic specialisation of overloaded functions.
+
+
+
+
+
@@ -1821,7 +1931,7 @@ f "2" = 2
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.
+ url="&libraryBaseLocation;/Control-Concurrent.html">Control.Concurrent. More information on Concurrent Haskell is provided in the documentation for that module.
The following RTS option(s) affect the behaviour of Concurrent
Haskell programs:RTS options, concurrent
@@ -2054,9 +2164,27 @@ f "2" = 2
+ :
+
+
+ (x86 only, added in GHC 7.0.1) Use the SSE2 registers and
+ instruction set to implement floating point operations
+ when using the native code generator. This gives a
+ substantial performance improvement for floating point,
+ but the resulting compiled code will only run on
+ processors that support SSE2 (Intel Pentium 4 and later,
+ or AMD Athlon 64 and later).
+
+
+ SSE2 is unconditionally used on x86-64 platforms.
+
+
+
+
+ :
- (iX86 machines)-monly-N-regs
+ (x86 only)-monly-N-regs
option (iX86 only) GHC tries to
“steal” four registers from GCC, for performance
reasons; it almost always works. However, when GCC is
@@ -2087,7 +2215,7 @@ statements or clauses.
GHC can dump its optimized intermediate code (said to be in “Core” format)
to a file as a side-effect of compilation. Non-GHC back-end tools can read and process Core files; these files have the suffix
- .hcr. The Core format is described in
+ .hcr. The Core format is described in An External Representation for the GHC Core Language,
and sample tools
for manipulating Core files (in Haskell) are in the GHC source distribution
@@ -2125,7 +2253,6 @@ statements or clauses.