X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fusing.xml;h=be8232244bcab976ae5db065ce986e3d010f73cb;hb=1edc287a8817e76b6895a42c08dc4ab3ca162fac;hp=329c31fffc08945540e3b42b6f7a810b0451b74d;hpb=335b9f366ac440259318777c4c07e4fa42fbbec6;p=ghc-hetmet.git
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 329c31f..be82322 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.
-
-
-
- :
@@ -1308,6 +1398,7 @@ f "2" = 2
e.g., the ‘default default’ for Haskell 1.4 caused the
otherwise unconstrained value 1 to be
given the type Int, whereas Haskell 98
+ and later
defaults it to Integer. This may lead to
differences in performance and behaviour, hence the
usefulness of being non-silent about this.
@@ -1540,31 +1631,6 @@ f "2" = 2
.
-
-
-
- :
- -Ofile <file> option
- optimising, customised
-
-
- (NOTE: not supported since GHC 4.x. Please ask if
- you're interested in this.)
-
- For those who need absolute
- control over exactly what options are
- used (e.g., compiler writers, sometimes :-), a list of
- options can be put in a file and then slurped in with
- .
-
- In that file, comments are of the
- #-to-end-of-line variety; blank
- lines and most whitespace is ignored.
-
- Please ask if you are baffled and would like an
- example of !
-
- We don't use a flag for day-to-day
@@ -1841,7 +1907,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
@@ -2077,7 +2143,7 @@ f "2" = 2
:
- (x86 only, added in GHC 6.14.1) Use the SSE2 registers and
+ (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,
@@ -2125,7 +2191,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
@@ -2163,7 +2229,6 @@ statements or clauses.