From a3783a326f3a19b665883529e12a4609a7e0c327 Mon Sep 17 00:00:00 2001 From: David Terei Date: Tue, 14 Sep 2010 07:21:35 +0000 Subject: [PATCH] Update release notes and docs with LLVM info. --- docs/man/gen_flags.xsl.sh | 3 +- docs/users_guide/7.0.1-notes.xml | 16 +++- docs/users_guide/flags.xml | 45 +++++++++ docs/users_guide/phases.xml | 149 ++++++++++++++++++++--------- docs/users_guide/separate_compilation.xml | 19 ++++ docs/users_guide/sooner.xml | 11 +++ docs/users_guide/using.xml | 16 ++++ 7 files changed, 207 insertions(+), 52 deletions(-) diff --git a/docs/man/gen_flags.xsl.sh b/docs/man/gen_flags.xsl.sh index 28627ea..fed694f 100644 --- a/docs/man/gen_flags.xsl.sh +++ b/docs/man/gen_flags.xsl.sh @@ -71,7 +71,8 @@ As a rule of thumb, all the language options are dynamic, as are the warning options and the debugging options. The rest are static, with the notable exceptions of -.BR \-v ", " \-cpp ", " \-fasm ", " \-fvia\-C ", and " \-#include . +.BR \-v ", " \-cpp ", " \-fasm ", " \-fvia\-C ", " \-fllvm ", and +" \-#include . The OPTIONS sections lists the status of each flag. .PP diff --git a/docs/users_guide/7.0.1-notes.xml b/docs/users_guide/7.0.1-notes.xml index fd63342..085b607 100644 --- a/docs/users_guide/7.0.1-notes.xml +++ b/docs/users_guide/7.0.1-notes.xml @@ -51,6 +51,14 @@ $ ghci -package haskell2010 -hide-package base -hide-package array + GHC now includes an LLVM code generator. For certain code, + particularly arithmetic heavy code, using the LLVM code + generator can bring some nice performance improvements. + + + + + The inliner has been overhauled, which should in general give better performance while reducing unnecessary code-size explosion. @@ -351,14 +359,14 @@ import SpecConstr flags to keep the LLVM intermediate files, -keep-llvm-file and -keep-llvm-files; - flags to set the location and options for the LLVM assembler, - optimiser and compiler, - -pgmla, + flags to set the location and options for the LLVM optimiser + and compiler, -pgmlo, -pgmlc, - -optla, -optlo and -optlc. + The LLVM code generator requires LLVM version 2.7 or later on + your path. diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml index ccf0931..9b26e49 100644 --- a/docs/users_guide/flags.xml +++ b/docs/users_guide/flags.xml @@ -311,6 +311,13 @@ - + or + + retain intermediate LLVM .ll files + dynamic + - + + or retain intermediate .s files @@ -1722,6 +1729,12 @@ phase n -fasm + + Compile via LLVM + dynamic + -fasm + + Omit code generation dynamic @@ -1948,6 +1961,18 @@ phase n Use cmd as the C compiler dynamic - + + cmd + Use cmd as the LLVM optimiser + dynamic + - + + + cmd + Use cmd as the LLVM compiler + dynamic + - + cmd @@ -1999,6 +2024,8 @@ phase n + + @@ -2049,6 +2076,18 @@ phase n - + option + pass option to the LLVM optimiser + dynamic + - + + + option + pass option to the LLVM compiler + dynamic + - + + option pass option to the mangler dynamic @@ -2236,6 +2275,12 @@ phase n - + + Dump LLVM intermediate code + dynamic + - + + Dump occurrence analysis output dynamic diff --git a/docs/users_guide/phases.xml b/docs/users_guide/phases.xml index abe96b3..81be0a5 100644 --- a/docs/users_guide/phases.xml +++ b/docs/users_guide/phases.xml @@ -49,6 +49,28 @@ + cmd + + + + Use cmd as the LLVM + optimiser. + + + + + + cmd + + + + Use cmd as the LLVM + compiler. + + + + + cmd @@ -178,6 +200,24 @@ + option + + + + Pass option to the LLVM optimiser. + + + + + option + + + + Pass option to the LLVM compiler. + + + + option @@ -408,42 +448,42 @@ $ cat foo.hspp - + __PARALLEL_HASKELL__ __PARALLEL_HASKELL__ - - Only defined when is in + + Only defined when is in use! This symbol is defined when pre-processing Haskell (input) and pre-processing C (GHC output). - + - + os_HOST_OS=1 - - This define allows conditional compilation based on + + This define allows conditional compilation based on the Operating System, whereos is the name of the current Operating System (eg. linux, mingw32 for Windows, solaris, etc.). - + - + - + arch_HOST_ARCH=1 - - This define allows conditional compilation based on + + This define allows conditional compilation based on the host architecture, wherearch is the name of the current architecture (eg. i386, x86_64, powerpc, sparc, etc.). - + @@ -574,6 +614,21 @@ $ cat foo.hspp + + + + + Compile via LLVM instead of using the native code + generator. This will generally take slightly longer than the + native code generator to compile but quicker than compiling + via C. Produced code is generally the same speed or faster + than the other two code generators. Compiling via LLVM + requires LLVM version 2.7 or later to be on the path. + + + + + @@ -633,7 +688,7 @@ $ cat foo.hspp different package will reside in a different shared library or binary. Note that using this option when linking causes GHC to link - against shared libraries. + against shared libraries. @@ -699,10 +754,10 @@ $ cat foo.hspp Omits the link step. This option can be used with - to avoid the automatic linking - that takes place if the program contains a Main - module. - + to avoid the automatic linking + that takes place if the program contains a Main + module. + @@ -799,9 +854,9 @@ $ cat foo.hspp This flag tells GHC to link against shared Haskell libraries. - This flag only affects the selection of dependent libraries, not - the form of the current target (see -shared). - See on how to + This flag only affects the selection of dependent libraries, not + the form of the current target (see -shared). + See on how to create them. Note that this option also has an effect on @@ -821,20 +876,20 @@ $ cat foo.hspp DLL, or a Mac OS dylib. GHC hides the operating system details beneath this uniform flag. - The flags / control whether the - resulting shared object links statically or dynamically to - Haskell package libraries given as option. Non-Haskell - libraries are linked as gcc would regularly link it on your - system, e.g. on most ELF system the linker uses the dynamic - libraries when found. + The flags / control whether the + resulting shared object links statically or dynamically to + Haskell package libraries given as option. Non-Haskell + libraries are linked as gcc would regularly link it on your + system, e.g. on most ELF system the linker uses the dynamic + libraries when found. - Object files linked into shared objects must be - compiled with , see + Object files linked into shared objects must be + compiled with , see - When creating shared objects for Haskell packages, the - shared object must be named properly, so that GHC recognizes - the shared object when linked against this package. See - shared object name mangling. + When creating shared objects for Haskell packages, the + shared object must be named properly, so that GHC recognizes + the shared object when linked against this package. See + shared object name mangling. @@ -845,9 +900,9 @@ $ cat foo.hspp - This flag selects one of a number of modes for finding shared - libraries at runtime. See for - a description of each mode. + This flag selects one of a number of modes for finding shared + libraries at runtime. See for + a description of each mode. @@ -864,21 +919,21 @@ $ cat foo.hspp to change which function is the "main" one, and the flag allows you to do so. The thing can be one of: - A lower-case identifier foo. GHC assumes that the main function is Main.foo. - An module name A. GHC assumes that the main function is A.main. - An qualified name A.foo. GHC assumes that the main function is A.foo. - + A lower-case identifier foo. GHC assumes that the main function is Main.foo. + An module name A. GHC assumes that the main function is A.main. + An qualified name A.foo. GHC assumes that the main function is A.foo. + Strictly speaking, is not a link-phase flag at all; it has no effect on the link step. The flag must be specified when compiling the module containing the specified main function (e.g. module A in the latter two items above). It has no effect for other modules, and hence can safely be given to ghc --make. - However, if all the modules are otherwise up to date, you may need to force - recompilation both of the module where the new "main" is, and of the - module where the "main" function used to be; - ghc is not clever - enough to figure out that they both need recompiling. You can - force recompilation by removing the object file, or by using the - flag. + However, if all the modules are otherwise up to date, you may need to force + recompilation both of the module where the new "main" is, and of the + module where the "main" function used to be; + ghc is not clever + enough to figure out that they both need recompiling. You can + force recompilation by removing the object file, or by using the + flag. diff --git a/docs/users_guide/separate_compilation.xml b/docs/users_guide/separate_compilation.xml index 198e5e1..9ce971d 100644 --- a/docs/users_guide/separate_compilation.xml +++ b/docs/users_guide/separate_compilation.xml @@ -440,6 +440,8 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `uname -m` .hc files, saving + .ll files, saving + .s files, saving @@ -467,6 +469,23 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `uname -m` + , + + + + + + Keep intermediate .ll files when + doing .hs-to-.o + compilations via LLVM (NOTE: .ll files + aren't generated when using the native code generator, you + may need to use to force them + to be produced). + + + + + , diff --git a/docs/users_guide/sooner.xml b/docs/users_guide/sooner.xml index 6823ce5..eb85878 100644 --- a/docs/users_guide/sooner.xml +++ b/docs/users_guide/sooner.xml @@ -152,6 +152,17 @@ should go here! + Compile via LLVM: + + The LLVM code generator can sometimes do a far better job + at producing fast code then either the native code generator + or the C code generator. This is not universal and depends + on the code. Numeric heavy code seems to show the best + improvement when compiled via LLVM. + + + + Compile via C and crank up GCC: The native code-generator is designed to be quick, not diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml index 45f6438..593781f 100644 --- a/docs/users_guide/using.xml +++ b/docs/users_guide/using.xml @@ -268,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 -- 1.7.10.4