@@ -1,5 +1,8 @@
1−# GHC Haskell
2−## Compiler (GHC) Versions
1+# Build and Optimization Guide
2+
3+## Building
4+
5+### Compiler (GHC) Versions
36
47For best performance use GHC 8.10 or 8.8 along with `fusion-plugin`
58(see below). Benchmarks show that GHC 8.8 has significantly better
@@ -19,7 +22,7 @@ GHC 8.2.2 may hog memory and hang when building certain applications using
1922streamly (particularly the benchmark programs in the streamly package).
2023Therefore, we recommend avoiding using the GHC version 8.2.x.
2124
22−## Memory requirements
25+### Memory requirements
2326
2427Building streamly itself may require upto 4GB memory. Depending on the
2528size of the application you may require 1-16GB memory to build. For most
@@ -33,9 +36,9 @@ compilation.
3336See the "Build times and space considerations" section below for more
3437details.
3538
36−## Compilation Options
39+### Compilation Options
3740
38−### Recommended Options
41+#### Recommended Options
3942
4043Add `fusion-plugin` to the `build-depends` section of your program in
4144the cabal file and use the following GHC options:
@@ -66,7 +69,7 @@ Important Notes:
6669
6770See [Explanation](#explanation) for details about these flags.
6871
69−### Explanation
72+#### Explanation
7073
7174* `-fdicts-strict` is needed to avoid [a GHC
7275issue](https://gitlab.haskell.org/ghc/ghc/issues/17745) leading to
@@ -86,7 +89,7 @@ bindings and therefore enabling case-of-case optimization. In some
8689cases, especially in some file IO benchmarks, it can make a difference of
87905-10x better performance.
8891
89−## Multi-core Parallelism
92+### Multi-core Parallelism
9093
9194Concurrency without a threaded runtime may be a bit more efficient. Do not use
9295threaded runtime unless you really need multi-core parallelism. To get
@@ -94,24 +97,24 @@ multi-core parallelism use the following GHC options:
9497
9598 `-threaded -with-rtsopts "-N"`
9699
97−# Platform Specific
100+## Platform Specific Features
98101
99102Streamly supports Linux, macOS and Windows operating systems. Some
100103modules and functionality may depend on specific OS kernel features.
101104Features/modules may get disabled if the kernel/OS does not support it.
102105
103−## Linux
106+### Linux
104107
105108* File system events notification module is supported only for kernel versions
106109 2.6.36 onwards.
107110
108−## Mac OSX
111+### Mac OSX
109112
110113* File system events notification module requires macOS 10.7+ with
111114 Xcode/macOS SDK installed (depends on `Cocoa` framework). However, we only
112115 test on latest three versions of the OS.
113116
114−# Performance Optimizations
117+## Performance Optimizations
115118
116119A "closed loop" is any streamly code that generates a stream using
117120unfold (or conceptually any stream generation combinator) and ends
@@ -138,7 +141,7 @@ cases where programmer annotation may help in stream fusion.
138141Remember, you need to worry about performance only where it matters, try
139142to optimize the fast path and not everything blindly.
140143
141−## INLINE annotations
144+### INLINE annotations
142145
143146It may help to add INLINE annotations on any intermediate functions
144147involved in a closed loop. In some cases you may have to add an inline
@@ -147,7 +150,7 @@ phase as well as described below.
147150Usually GHC has three inline phases - the first phase is pahse-2, the
148151second phase is phase-1 and the last one is phase-0.
149152
150−### Early INLINE
153+#### Early INLINE
151154
152155Generally, you only have to inline the combinators or functions
153156participating in a loop and not the whole loop itself. But sometimes
@@ -164,7 +167,7 @@ annotation GHC may decide to delay the inlining in some cases. This is
164167not very common but may be needed sometimes. Perhaps GHC can be fixed or
165168we can resolve this using fusion-plugin in future.
166169
167−### Delayed INLINE
170+#### Delayed INLINE
168171
169172When a function is passed to a higher order function e.g. a function
170173passed to `concatMap` or `unfoldMany` then we want the function to be
@@ -172,7 +175,7 @@ inlined after the higher order is inlined so that proper fusion of the
172175higher order function can occur. For such cases we usually add INLINE[1]
173176on the function being passed to instruct GHC not to inline it too early.
174177
175−## Strictness annotations
178+### Strictness annotations
176179
177180* Strictness annotations on data, specially the data used as accumulator in
178181 folds and scans, can help in improving performance.
@@ -182,14 +185,14 @@ on the function being passed to instruct GHC not to inline it too early.
182185 may be missing some strictness annotations. `-XStrict` can be used as an aid
183186 to detect missing annotations, using it blindly may regress performance.
184187
185−## Use tail recursion
188+### Use tail recursion
186189
187190Do not use a strict `foldr` or lazy `foldl` unless you know what you are
188191doing. Use lazy `foldr` for lazily transforming the stream and strict
189192`foldl` for reducing the stream. If you are manually writing recursive
190193code, try to use tail recursion where possible.
191194
192−# Build times and space considerations
195+## Build times and space considerations
193196
194197Haskell, being a pure functional language, confers special powers on
195198GHC. It allows GHC to do whole program optimization. In a closed loop