Prepare dph for a vectInfoVar type change
[packages/dph.git] / README
1
2 Directories in libraries/dph
3
4    dph-base/
5         Common config and debugging functions for Data Parallel Haskell.
6
7    dph-buildbot/
8         Performance regression buildbot.
9
10    dph-examples/
11         Examples using Data Parallel Haskell.
12
13    dph-prim-interface/
14         Empty implementation of flat parallel arrays. 
15         This package exists only so that dph-prim-par and dph-prim-seq
16         can provide the same interface.
17
18    dph-prim-seq/
19         Sequential implementation of the flat parallel array API defined
20         in dph-prim-interface.
21         This is only used during debugging.
22         You probably want dph-prim-par instead.
23
24    dph-prim-par/
25         Production implementation of the flat parallel array API defined
26         in dph-prim-interface.
27
28    dph-lifted-base/
29         Common definitions used by the other dph-lifted packages.
30
31
32    The following packages provide:
33      Nested arrays and the primitive operators that work on them (PA functions).
34      The lifted array combinators that the vectoriser introduces (PP functions).
35      The user facing library functions that work on [::] style arrays (P functions).
36
37      dph-lifted-boxed/
38         Incomplete implementation using boxed array elements.
39         This is very slow, but sometimes useful for debugging.
40         
41      dph-lifted-copy/
42         Deprecated implementation that performs deep copying replicate.
43         Using this package can cause the vectorised program to have worse
44         asymptotic complexity than the original.
45         Use dph-lifted-vseg instead.
46
47      dph-lifted-vseg/
48         This implementation directly encodes sharing between array segments,
49         and avoids the copying that dph-lifted-copy would otherwise do.
50         Use this version for production code.
51
52
53    Odds and ends:
54    make/
55         Makefiles used for development and debugging
56
57    dph-test/
58         Quickcheck tests for the array operators.
59
60    dtrace/
61         Old code to add dtrace support to DPH.
62
63    examples/
64         Rotted example code that doesn't build anymore and should 
65         probably just be deleted.
66     
67
68 To compile programs use:
69      ghc -rtsopts -threaded 
70          -fllvm -optlo-O3 
71          -Odph -fcpr-off -fno-liberate-case 
72          -package dph-lifted-vseg
73
74 Why:
75      -rtsopts -threaded         -- You'll want to pass +RTS -Nwhatever when running
76                                 --  the compiled program to enable threads.
77
78      -fllvm                     -- LLVM produces much better numerical code than GHC's
79                                 --  default native code generator.
80
81      -optlo-O3                  -- Turn on more LLVM optimisations. 
82                                 --  This can produce better numerical code, 
83                                 --  but sometimes tickles bugs in LLVM.
84
85      -fcpr-off                  -- The Constructed Product Result transform sometimes
86                                 --  interferes with fusion in the Data.Vector Library.
87
88      -fno-liberate-case         -- The LiberateCase transform can duplicate lots of 
89                                 --  intermediate code, result in slow compile times,
90                                 --  large binaries, and minimal performance improvement.
91                                 --  The implementation of the DPH backend library should
92                                 --  manually handle most cases where LiberateCase
93                                 --  would fire.
94