@@ -1,63 +1,68 @@
11# GHC Haskell
2−## Compiler Versions
2+## Compiler (GHC) Versions
33
4−GHC versions 8.0 onwards are supported by streamly per se. However, note
5−that some packages we depend on (e.g. `network`) support only last three
6−versions of GHC.
4+For best performance use GHC 8.10 or 8.8 along with `fusion-plugin`
5+(see below). Benchmarks show that GHC 8.8 has significantly better
6+performance than GHC 8.6 in many cases.
77
8−Use GHC 8.8 for best performance. Benchmarks show that GHC 8.8 has
9−significantly better performance than GHC 8.6 in many cases.
8+GHC versions 8.6 onwards are fully supported along with `fusion-plugin`.
9+`fusion-plugin` is not supported for GHC versions below 8.6.
10+
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.
1014
1115GHC 8.2.2 may hog memory and hang when building certain applications using
1216streamly (particularly the benchmark programs in the streamly package).
1317Therefore, we recommend avoiding using the GHC version 8.2.x.
1418
15−## Compilation Options
19+## Memory requirements
1620
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.
1824
19−At the very least `-O -fdicts-strict` compilation options are
20−required. If these options are not used, the program may exhibit memory
21−hog. For example, the following program, if compiled without an
22−optimization option, is known to hog memory:
25+To reduce the memory footprint you may want to break big modules into
26+smaller ones and reduce unnecessary inlining on large functions. You can
27+also use the `-Rghc-timing` GHC option to report the memory usage during
28+compilation.
2329
24−```
25−main = S.drain $ S.concatMap S.fromList $ S.repeat []
26−```
30+See the "Build times and space considerations" section below for more
31+details.
32+
33+## Compilation Options
2734
2835### Recommended Options
2936
30−Use the following GHC options:
37+Add `fusion-plugin` to the `build-depends` section of your program in
38+the cabal file and use the following GHC options:
3139
3240```
3341 -O2
3442 -fdicts-strict
3543 -fmax-worker-args=16
3644 -fspec-constr-recursive=16
45+ -fplugin Fusion.Plugin
3746```
3847
39−Important Note: In certain cases it is possible that GHC takes too long to
40−compile with `-fspec-constr-recursive=16`, if that happens please reduce the
41−value or remove that option.
48+Important Notes:
49+
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.
56+2. In certain cases it is possible that GHC takes too long to compile
57+ with `-fspec-constr-recursive=16`, if that happens please reduce the
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.
4263
4364See [Explanation](#explanation) for details about these flags.
4465
45−### Using Fusion Plugin
46−
47−In many cases
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.
52−
53−* Add `fusion-plugin` to the `build-depends` section of your program in
54− the cabal file.
55−* Add the following to GHC options:
56−
57−```
58− -fplugin=Fusion.Plugin
59−```
60−
6166### Explanation
6267
6368* `-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.
103108 Xcode/macOS SDK installed (depends on `Cocoa` framework). However, we only
104109 test on latest three versions of the OS.
105110
106−## Windows
107−
108−* File system event notification module is not yet available for Windows.
109−
110111# Performance Optimizations
111112
112113A "closed loop" is any streamly code that generates a stream using
@@ -118,7 +119,7 @@ programming.
118119
119120Closed loops are generated in a modular fashion by stream generation,
120121transformation 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.
122123These data constructors are eliminated by the compiler using `stream
123124fusion` optimizations, generating a very efficient loop.
124125