git.iko.soy/streamly
on 294aa21 help sign in
streamly/docs/Build.md
99 lines 3.3 kB history raw
1# Compilation Options
3## Recommended Options
5Benchmarks show that GHC 8.8 has significantly better performance than GHC 8.6
6in many cases.
8Use the following GHC options:
10```
11 -O2
12 -fdicts-strict
13 -fmax-worker-args=16
14 -fspec-constr-recursive=16
15```
17Important Note: In certain cases it is possible that GHC takes too long to
18compile with `-fspec-constr-recursive=16`, if that happens please reduce the
19value or remove that option.
21See [Explanation](#explanation) for details about these flags.
23## Using Fusion Plugin
25In many cases `fusion-plugin` can improve performance by better stream
26fusion. However, in some cases performance may also regress. Please note
27that the `fusion-plugin` package works only for GHC >= 8.6.
29* Install the
30[fusion-plugin](https://hackage.haskell.org/package/fusion-plugin)
31package or add it to the `build-depends` section of your program in the
32cabal file.
34* Use the following GHC option in addition to the options listed in the
35 previous section:
37```
38 -fplugin=Fusion.Plugin
39```
41## Minimal
43At the very least `-O -fdicts-strict` compilation options are
44required. If these options are not used, the program may exhibit memory
45hog. For example, the following program, if compiled without an
46optimization option, is known to hog memory:
48```
49main = S.drain $ S.concatMap S.fromList $ S.repeat []
50```
52## Explanation
54* `-fdicts-strict` is needed to avoid [a GHC
55issue](https://gitlab.haskell.org/ghc/ghc/issues/17745) leading to
56memory leak in some cases.
58* `-fspec-constr-recursive` is needed for better stream fusion by enabling
59the `SpecConstr` optimization in more cases. Large values used with this flag
60may lead to huge compilation times and code bloat, if that happens please avoid
61it or use a lower value (e.g. 3 or 4).
63* `-fmax-worker-args` is needed for better stream fusion by enabling the
64`SpecConstr` optimization in some important cases.
66* `-fplugin=Fusion.Plugin` enables predictable stream fusion
67optimization in certain cases by helping the compiler inline internal
68bindings and therefore enabling case-of-case optimization. In some
69cases, especially in some file IO benchmarks, it can make a difference of
705-10x better performance.
72# Multi-core Parallelism
74Concurrency without a threaded runtime may be a bit more efficient. Do not use
75threaded runtime unless you really need multi-core parallelism. To get
76multi-core parallelism use the following GHC options:
78 `-threaded -with-rtsopts "-N"`
80# Compiler Versions
82Use GHC 8.8 for best performance.
84GHC 8.2.2 may hog memory and hang when building certain application using
85streamly (particularly the benchmark programs in the streamly package).
86Therefore we recommend avoiding using the GHC version 8.2.x.
88# Performance Optimizations
90If performance is below expectations:
92* Look for inlining functions in the fast path
93* Strictness annotations on data, specially the data used as accumulator in
94 folds and scans, can help in improving performance.
95* Strictness annotations on function arguments can help the compiler unbox
96 constructors in certain cases, improving performance.
97* Sometimes using `-XStrict` extension can help improve performance, if so you
98 may be missing some strictness annotations.
99* Use tail recursion for streaming data or for large loops