git.iko.soy/streamly
on 83bca76 help sign in
streamly/docs/User/HowTo/Compiling.md
137 lines 4.7 kB history raw
1# Build Guide
3## Building
5### Compiler (GHC) Versions
7GHC 8.6 and above are recommended. For best performance use GHC 8.8 or
88.10 along with `fusion-plugin` (see below). Benchmarks show that GHC
98.8 has significantly better performance than GHC 8.6 in many cases.
11GHC 9.0 and GHC 9.2.1 have some performance issues, please see [this
12issue](https://github.com/composewell/streamly/issues/1061) for details.
13GHC 9.2.2 is expected to have the fixes that will bring the performance on par
14with previous versions.
16### Distributions
18Tested with stackage `lts-18.27` and `nix 21.05`.
20### Memory requirements
22Building streamly itself may require upto 4GB memory. Depending on the
23size of the application you may require 1-16GB memory to build. For most
24applications up to 8GB of memory should be sufficient.
26To reduce the memory footprint you may want to break big modules into
27smaller ones and reduce unnecessary inlining on large functions. You can
28also use the `-Rghc-timing` GHC option to report the memory usage during
29compilation.
31See the "Build times and space considerations" section below for more
32details.
34### Compilation Options
36#### Recommended Options
38Add `fusion-plugin` to the `build-depends` section of your program in
39the cabal file and use the following GHC options:
41```
42 -O2
43 -fdicts-strict
44 -fmax-worker-args=16
45 -fspec-constr-recursive=16
46 -fplugin Fusion.Plugin
47```
49Important Notes:
511. [fusion-plugin](https://hackage.haskell.org/package/fusion-plugin) can
52 improve performance significantly by better stream fusion, many
53 cases. If the perform regresses due to fusion-plugin please open
54 an issue. You may remove the `-fplugin` option for regular builds
55 but it is recommended for deployment builds and performance
56 benchmarking. Note, for GHC 8.4 or lower fusion-plugin cannot be used.
572. In certain cases it is possible that GHC takes too long to compile
58 with `-fspec-constr-recursive=16`, if that happens please reduce the
59 value or remove that option.
603. At the very least `-O -fdicts-strict` compilation options are
61 absolutely required to avoid issues in some cases. For example, the
62 program `main = S.drain $ S.concatMap S.fromList $ S.repeat []` may
63 hog memory without these options.
65See [Explanation](#explanation) for details about these flags.
67#### Explanation
69* `-fdicts-strict` is needed to avoid [a GHC
70issue](https://gitlab.haskell.org/ghc/ghc/issues/17745) leading to
71memory leak in some cases.
73* `-fspec-constr-recursive` is needed for better stream fusion by enabling
74the `SpecConstr` optimization in more cases. Large values used with this flag
75may lead to huge compilation times and code bloat, if that happens please avoid
76it or use a lower value (e.g. 3 or 4).
78* `-fmax-worker-args` is needed for better stream fusion by enabling the
79`SpecConstr` optimization in some important cases.
81* `-fplugin=Fusion.Plugin` enables predictable stream fusion
82optimization in certain cases by helping the compiler inline internal
83bindings and therefore enabling case-of-case optimization. In some
84cases, especially in some file IO benchmarks, it can make a difference of
855-10x better performance.
87### Multi-core Parallelism
89Concurrency without a threaded runtime may be a bit more efficient. Do not use
90threaded runtime unless you really need multi-core parallelism. To get
91multi-core parallelism use the following GHC options:
93 `-threaded -with-rtsopts "-N"`
95## Platform Specific Features
97Streamly supports Linux, macOS and Windows operating systems. Some
98modules and functionality may depend on specific OS kernel features.
99Features/modules may get disabled if the kernel/OS does not support it.
101### Linux
103File system events notification module is supported only for kernel versions
1042.6.36 onwards.
106### macOS
108File system events notification module supports macOS 10.7+ . You must
109have the ``Cocoa`` framework installed which is supplied by the macOS
110SDK. If ``Cocoa`` is not installed, you may see an error like this:
112```
113error: ld: framework not found Cocoa
114```
116### Native build
118Usually, if you have a working GHC you would already have the SDK
119installed. See the documentation of `Xcode` or `xcode-select` tool for
120more details.
122### Nix build
124Please note that cabal2nix may not always be able to generate a complete nix
125expression on `macOS`. See [this
126issue](https://github.com/NixOS/cabal2nix/issues/470).
128You may need to add ``nixpkgs.darwin.apple_sdk.frameworks.Cocoa`` to
129your ``buildInputs`` or ``executableFrameworkDepends``. Something like
130this:
132```
133executableFrameworkDepends =
134 if builtins.currentSystem == "x86_64-darwin"
135 then [nixpkgs.darwin.apple_sdk.frameworks.Cocoa]
136 else [];
137```