@@ -1,63 +1,68 @@
1# GHC Haskell
1# GHC Haskell
2−## Compiler Versions
2+## Compiler (GHC) Versions
4−GHC versions 8.0 onwards are supported by streamly per se. However, note
4+For best performance use GHC 8.10 or 8.8 along with `fusion-plugin`
5−that some packages we depend on (e.g. `network`) support only last three
5+(see below). Benchmarks show that GHC 8.8 has significantly better
6−versions of GHC.
6+performance than GHC 8.6 in many cases.
8−Use GHC 8.8 for best performance. Benchmarks show that GHC 8.8 has
8+GHC versions 8.6 onwards are fully supported along with `fusion-plugin`.
9−significantly better performance than GHC 8.6 in many cases.
9+`fusion-plugin` is not supported for GHC versions below 8.6.
11+GHC versions 8.0 onwards are supported without `fusion-plugin`. However, note
12+that some packages we depend on (e.g. `network`) may support only last three
13+major versions of GHC.
11GHC 8.2.2 may hog memory and hang when building certain applications using
15GHC 8.2.2 may hog memory and hang when building certain applications using
12streamly (particularly the benchmark programs in the streamly package).
16streamly (particularly the benchmark programs in the streamly package).
13Therefore, we recommend avoiding using the GHC version 8.2.x.
17Therefore, we recommend avoiding using the GHC version 8.2.x.
15−## Compilation Options
19+## Memory requirements
17−### Absolute Minimum
21+Building streamly itself may require upto 4GB memory. Depending on the
22+size of the application you may require 1-16GB memory to build. For most
23+applications up to 8GB of memory should be sufficient.
19−At the very least `-O -fdicts-strict` compilation options are
25+To reduce the memory footprint you may want to break big modules into
20−required. If these options are not used, the program may exhibit memory
26+smaller ones and reduce unnecessary inlining on large functions. You can
21−hog. For example, the following program, if compiled without an
27+also use the `-Rghc-timing` GHC option to report the memory usage during
22−optimization option, is known to hog memory:
28+compilation.
24−```
30+See the "Build times and space considerations" section below for more
25−main = S.drain $ S.concatMap S.fromList $ S.repeat []
31+details.
33+## Compilation Options
28### Recommended Options
35### Recommended Options
37+Add `fusion-plugin` to the `build-depends` section of your program in
30−Use the following GHC options:
38+the cabal file and use the following GHC options:
34 -fdicts-strict
42 -fdicts-strict
35 -fmax-worker-args=16
43 -fmax-worker-args=16
36 -fspec-constr-recursive=16
44 -fspec-constr-recursive=16
45+ -fplugin Fusion.Plugin
50+1. [fusion-plugin](https://hackage.haskell.org/package/fusion-plugin) can
51+ improve performance significantly by better stream fusion, many
52+ cases. If the perform regresses due to fusion-plugin please open
53+ an issue. You may remove the `-fplugin` option for regular builds
54+ but it is recommended for deployment builds and performance
55+ benchmarking. Note, for GHC 8.4 or lower fusion-plugin cannot be used.
39−Important Note: In certain cases it is possible that GHC takes too long to
56+2. In certain cases it is possible that GHC takes too long to compile
40−compile with `-fspec-constr-recursive=16`, if that happens please reduce the
57+ with `-fspec-constr-recursive=16`, if that happens please reduce the
41−value or remove that option.
58+ value or remove that option.
59+3. At the very least `-O -fdicts-strict` compilation options are
60+ absolutely required to avoid issues in some cases. For example, the
61+ program `main = S.drain $ S.concatMap S.fromList $ S.repeat []` may
62+ hog memory without these options.
43See [Explanation](#explanation) for details about these flags.
64See [Explanation](#explanation) for details about these flags.
45−### Using Fusion Plugin
48−[fusion-plugin](https://hackage.haskell.org/package/fusion-plugin) can
49−improve performance by better stream fusion. However, in some cases
50−performance may also regress. Please note that the `fusion-plugin`
51−package works only for GHC >= 8.6.
53−* Add `fusion-plugin` to the `build-depends` section of your program in
55−* Add the following to GHC options:
58− -fplugin=Fusion.Plugin
61### Explanation
66### Explanation
63* `-fdicts-strict` is needed to avoid [a GHC
68* `-fdicts-strict` is needed to avoid [a GHC
@@ -103,10 +108,6 @@ Features/modules may get disabled if the kernel/OS does not support it.
103 Xcode/macOS SDK installed (depends on `Cocoa` framework). However, we only
108 Xcode/macOS SDK installed (depends on `Cocoa` framework). However, we only
104 test on latest three versions of the OS.
109 test on latest three versions of the OS.
108−* File system event notification module is not yet available for Windows.
110# Performance Optimizations
111# Performance Optimizations
112A "closed loop" is any streamly code that generates a stream using
113A "closed loop" is any streamly code that generates a stream using
@@ -118,7 +119,7 @@ programming.
119Closed loops are generated in a modular fashion by stream generation,
120Closed loops are generated in a modular fashion by stream generation,
120transformation and elimination combinators in streamly. Combinators
121transformation and elimination combinators in streamly. Combinators
121−transfer data to the next stage or combinator using data constructors.
122+transfer data to the next stream pipeline stage using data constructors.
122These data constructors are eliminated by the compiler using `stream
123These data constructors are eliminated by the compiler using `stream
123fusion` optimizations, generating a very efficient loop.
124fusion` optimizations, generating a very efficient loop.