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 + file hello.o and + an interface + file hello.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 overview GHC'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. + + + + .s An 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 ––make make 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-extensions ghc --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.