@@ -1,5 +1,8 @@
1−# GHC Haskell
1+# Build and Optimization Guide
2−## Compiler (GHC) Versions
5+### Compiler (GHC) Versions
4For best performance use GHC 8.10 or 8.8 along with `fusion-plugin`
7For 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
8(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
19streamly (particularly the benchmark programs in the streamly package).
22streamly (particularly the benchmark programs in the streamly package).
20Therefore, we recommend avoiding using the GHC version 8.2.x.
23Therefore, we recommend avoiding using the GHC version 8.2.x.
22−## Memory requirements
25+### Memory requirements
24Building streamly itself may require upto 4GB memory. Depending on the
27Building streamly itself may require upto 4GB memory. Depending on the
25size of the application you may require 1-16GB memory to build. For most
28size of the application you may require 1-16GB memory to build. For most
@@ -33,9 +36,9 @@ compilation.
33See the "Build times and space considerations" section below for more
36See the "Build times and space considerations" section below for more
36−## Compilation Options
39+### Compilation Options
38−### Recommended Options
41+#### Recommended Options
40Add `fusion-plugin` to the `build-depends` section of your program in
43Add `fusion-plugin` to the `build-depends` section of your program in
41the cabal file and use the following GHC options:
44the cabal file and use the following GHC options:
@@ -66,7 +69,7 @@ Important Notes:
67See [Explanation](#explanation) for details about these flags.
70See [Explanation](#explanation) for details about these flags.
69−### Explanation
72+#### Explanation
71* `-fdicts-strict` is needed to avoid [a GHC
74* `-fdicts-strict` is needed to avoid [a GHC
72issue](https://gitlab.haskell.org/ghc/ghc/issues/17745) leading to
75issue](https://gitlab.haskell.org/ghc/ghc/issues/17745) leading to
@@ -86,7 +89,7 @@ bindings and therefore enabling case-of-case optimization. In some
86cases, especially in some file IO benchmarks, it can make a difference of
89cases, especially in some file IO benchmarks, it can make a difference of
875-10x better performance.
905-10x better performance.
89−## Multi-core Parallelism
92+### Multi-core Parallelism
91Concurrency without a threaded runtime may be a bit more efficient. Do not use
94Concurrency without a threaded runtime may be a bit more efficient. Do not use
92threaded runtime unless you really need multi-core parallelism. To get
95threaded runtime unless you really need multi-core parallelism. To get
@@ -94,24 +97,24 @@ multi-core parallelism use the following GHC options:
95 `-threaded -with-rtsopts "-N"`
98 `-threaded -with-rtsopts "-N"`
97−# Platform Specific
100+## Platform Specific Features
99Streamly supports Linux, macOS and Windows operating systems. Some
102Streamly supports Linux, macOS and Windows operating systems. Some
100modules and functionality may depend on specific OS kernel features.
103modules and functionality may depend on specific OS kernel features.
101Features/modules may get disabled if the kernel/OS does not support it.
104Features/modules may get disabled if the kernel/OS does not support it.
103−## Linux
106+### Linux
105* File system events notification module is supported only for kernel versions
108* File system events notification module is supported only for kernel versions
106 2.6.36 onwards.
109 2.6.36 onwards.
108−## Mac OSX
111+### Mac OSX
110* File system events notification module requires macOS 10.7+ with
113* File system events notification module requires macOS 10.7+ with
111 Xcode/macOS SDK installed (depends on `Cocoa` framework). However, we only
114 Xcode/macOS SDK installed (depends on `Cocoa` framework). However, we only
112 test on latest three versions of the OS.
115 test on latest three versions of the OS.
114−# Performance Optimizations
117+## Performance Optimizations
116A "closed loop" is any streamly code that generates a stream using
119A "closed loop" is any streamly code that generates a stream using
117unfold (or conceptually any stream generation combinator) and ends
120unfold (or conceptually any stream generation combinator) and ends
@@ -138,7 +141,7 @@ cases where programmer annotation may help in stream fusion.
138Remember, you need to worry about performance only where it matters, try
141Remember, you need to worry about performance only where it matters, try
139to optimize the fast path and not everything blindly.
142to optimize the fast path and not everything blindly.
141−## INLINE annotations
144+### INLINE annotations
143It may help to add INLINE annotations on any intermediate functions
146It may help to add INLINE annotations on any intermediate functions
144involved in a closed loop. In some cases you may have to add an inline
147involved in a closed loop. In some cases you may have to add an inline
@@ -147,7 +150,7 @@ phase as well as described below.
147Usually GHC has three inline phases - the first phase is pahse-2, the
150Usually GHC has three inline phases - the first phase is pahse-2, the
148second phase is phase-1 and the last one is phase-0.
151second phase is phase-1 and the last one is phase-0.
150−### Early INLINE
153+#### Early INLINE
152Generally, you only have to inline the combinators or functions
155Generally, you only have to inline the combinators or functions
153participating in a loop and not the whole loop itself. But sometimes
156participating 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
164not very common but may be needed sometimes. Perhaps GHC can be fixed or
167not very common but may be needed sometimes. Perhaps GHC can be fixed or
165we can resolve this using fusion-plugin in future.
168we can resolve this using fusion-plugin in future.
167−### Delayed INLINE
170+#### Delayed INLINE
169When a function is passed to a higher order function e.g. a function
172When a function is passed to a higher order function e.g. a function
170passed to `concatMap` or `unfoldMany` then we want the function to be
173passed 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
172higher order function can occur. For such cases we usually add INLINE[1]
175higher order function can occur. For such cases we usually add INLINE[1]
173on the function being passed to instruct GHC not to inline it too early.
176on the function being passed to instruct GHC not to inline it too early.
175−## Strictness annotations
178+### Strictness annotations
177* Strictness annotations on data, specially the data used as accumulator in
180* Strictness annotations on data, specially the data used as accumulator in
178 folds and scans, can help in improving performance.
181 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.
182 may be missing some strictness annotations. `-XStrict` can be used as an aid
185 may be missing some strictness annotations. `-XStrict` can be used as an aid
183 to detect missing annotations, using it blindly may regress performance.
186 to detect missing annotations, using it blindly may regress performance.
185−## Use tail recursion
188+### Use tail recursion
187Do not use a strict `foldr` or lazy `foldl` unless you know what you are
190Do not use a strict `foldr` or lazy `foldl` unless you know what you are
188doing. Use lazy `foldr` for lazily transforming the stream and strict
191doing. Use lazy `foldr` for lazily transforming the stream and strict
189`foldl` for reducing the stream. If you are manually writing recursive
192`foldl` for reducing the stream. If you are manually writing recursive
190code, try to use tail recursion where possible.
193code, try to use tail recursion where possible.
192−# Build times and space considerations
195+## Build times and space considerations
194Haskell, being a pure functional language, confers special powers on
197Haskell, being a pure functional language, confers special powers on
195GHC. It allows GHC to do whole program optimization. In a closed loop
198GHC. It allows GHC to do whole program optimization. In a closed loop