git.iko.soy/streamly
on ea2d85b help sign in
streamly/docs/Compiling.md
136 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 have some performance issues, please see [this
12issue](https://github.com/composewell/streamly/issues/1061) for details.
13However, upcoming releases may fix some of these issues.
15### Distributions
17Tested with stackage `lts-18.18` and `nix 21.05`.
19### Memory requirements
21Building streamly itself may require upto 4GB memory. Depending on the
22size of the application you may require 1-16GB memory to build. For most
23applications up to 8GB of memory should be sufficient.
25To reduce the memory footprint you may want to break big modules into
26smaller ones and reduce unnecessary inlining on large functions. You can
27also use the `-Rghc-timing` GHC option to report the memory usage during
28compilation.
30See the "Build times and space considerations" section below for more
31details.
33### Compilation Options
35#### Recommended Options
37Add `fusion-plugin` to the `build-depends` section of your program in
38the cabal file and use the following GHC options:
40```
41 -O2
42 -fdicts-strict
43 -fmax-worker-args=16
44 -fspec-constr-recursive=16
45 -fplugin Fusion.Plugin
46```
48Important Notes:
501. [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.
562. 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.
593. 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.
64See [Explanation](#explanation) for details about these flags.
66#### Explanation
68* `-fdicts-strict` is needed to avoid [a GHC
69issue](https://gitlab.haskell.org/ghc/ghc/issues/17745) leading to
70memory leak in some cases.
72* `-fspec-constr-recursive` is needed for better stream fusion by enabling
73the `SpecConstr` optimization in more cases. Large values used with this flag
74may lead to huge compilation times and code bloat, if that happens please avoid
75it or use a lower value (e.g. 3 or 4).
77* `-fmax-worker-args` is needed for better stream fusion by enabling the
78`SpecConstr` optimization in some important cases.
80* `-fplugin=Fusion.Plugin` enables predictable stream fusion
81optimization in certain cases by helping the compiler inline internal
82bindings and therefore enabling case-of-case optimization. In some
83cases, especially in some file IO benchmarks, it can make a difference of
845-10x better performance.
86### Multi-core Parallelism
88Concurrency without a threaded runtime may be a bit more efficient. Do not use
89threaded runtime unless you really need multi-core parallelism. To get
90multi-core parallelism use the following GHC options:
92 `-threaded -with-rtsopts "-N"`
94## Platform Specific Features
96Streamly supports Linux, macOS and Windows operating systems. Some
97modules and functionality may depend on specific OS kernel features.
98Features/modules may get disabled if the kernel/OS does not support it.
100### Linux
102File system events notification module is supported only for kernel versions
1032.6.36 onwards.
105### macOS
107File system events notification module supports macOS 10.7+ . You must
108have the ``Cocoa`` framework installed which is supplied by the macOS
109SDK. If ``Cocoa`` is not installed, you may see an error like this:
111```
112error: ld: framework not found Cocoa
113```
115### Native build
117Usually, if you have a working GHC you would already have the SDK
118installed. See the documentation of `Xcode` or `xcode-select` tool for
119more details.
121### Nix build
123Please note that cabal2nix may not always be able to generate a complete nix
124expression on `macOS`. See [this
125issue](https://github.com/NixOS/cabal2nix/issues/470).
127You may need to add ``nixpkgs.darwin.apple_sdk.frameworks.Cocoa`` to
128your ``buildInputs`` or ``executableFrameworkDepends``. Something like
129this:
131```
132executableFrameworkDepends =
133 if builtins.currentSystem == "x86_64-darwin"
134 then [nixpkgs.darwin.apple_sdk.frameworks.Cocoa]
135 else [];
136```