git.iko.soy/streamly
on fa9fa09 help sign in
streamly/docs/User/HowTo/Compiling.md
145 lines 5.0 kB history raw
1# Build Guide
3## Building
5### Compiler (GHC) Versions
7Do not use ghc 9.0.x and 9.2.1. GHC 9.6.x may have a small memory
8leak issue in some concurrent stream cases, see below for more details.
9For best performance use `fusion-plugin` (see below) when compiling.
11### Memory requirements
13Building streamly itself may require upto 4GB memory. Depending on the
14size of the application you may require 1-16GB memory to build. For most
15applications up to 8GB of memory should be sufficient.
17To reduce the memory footprint you may want to break big modules
18into smaller ones and reduce unnecessary INLINE pragmas on large
19functions. You can also use the `-Rghc-timing` GHC option to report the
20memory usage during compilation.
22See the "Build times and space considerations" section below for more
23details.
25### GHC Plugin for Stream Fusion
27Streamly usually performs very well without any compiler plugins.
28However, we have fixed some deficiencies in GHC's optimizer using a
29[compiler plugin](https://github.com/composewell/fusion-plugin). We
30hope to fold these optimizations into GHC in the future; until then we
31recommend that you use this plugin for applications that are performance
32sensitive.
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```
49See [Explanation](#explanation) section for details about these flags.
51Important Notes:
531. [fusion-plugin](https://hackage.haskell.org/package/fusion-plugin) can
54 improve performance significantly by better stream fusion, in many
55 cases. If the performance regresses due to fusion-plugin please open
56 an issue. You may remove the `-fplugin` option for regular builds
57 but it is recommended for deployment builds and performance
58 benchmarking.
592. In certain cases it is possible that GHC takes too long to compile
60 with `-fspec-constr-recursive=16`, if that happens please reduce the
61 value or remove that option. This may happen especially when using Parsers.
63#### Explanation
65* `-fdicts-strict` is needed to avoid [a GHC
66issue](https://gitlab.haskell.org/ghc/ghc/issues/17745) leading to
67memory leak in some cases. In GHC 9.6.x this issue cannot be avoided
68even with `-fdicts-strict` option.
70* `-fspec-constr-recursive` is needed for better stream fusion, it
71allows the `SpecConstr` optimization to occur in more cases. Large
72values used with this flag may lead to huge compilation times and code
73bloat, if that happens please avoid it or use a lower value (e.g. 3 or
744).
76* `-fmax-worker-args` is needed for better stream fusion, it allows the
77`SpecConstr` optimization to occur in some important cases.
79* `-fplugin=Fusion.Plugin` enables predictable stream fusion
80optimization in certain cases by helping the compiler inline internal
81bindings, therefore, enabling case-of-case optimization. In some cases,
82it can make a difference of 5-10x better performance.
84### Multi-core Parallelism
86Concurrency without a threaded runtime may be a bit more efficient. Do not use
87threaded runtime unless you really need multi-core parallelism. To get
88multi-core parallelism use the following GHC options:
90 `-threaded -with-rtsopts "-N"`
92## Platform Specific Features
94Streamly supports Linux, macOS and Windows operating systems. Some
95modules and functionality may depend on specific OS kernel features.
96Features/modules may get disabled if the kernel/OS does not support it.
98### Linux
100File system events notification module is supported only for kernel versions
1012.6.36 onwards.
103### macOS
105File system events notification module supports macOS 10.7+ . You must
106have the ``Cocoa`` framework installed which is supplied by the macOS
107SDK. If ``Cocoa`` is not installed, you may see an error like this:
109```
110error: ld: framework not found Cocoa
111```
113#### cabal build
115Usually, if you have a working GHC you would already have the SDK
116installed. See the documentation of `Xcode` or `xcode-select` tool for
117more details.
119#### Nix build
121Please note that `cabal2nix` may not always be able to generate a complete nix
122expression on `macOS`. See [this
123issue](https://github.com/NixOS/cabal2nix/issues/470).
125You may need to add ``nixpkgs.darwin.apple_sdk.frameworks.Cocoa``
126to ``librarySystemDepends``. For example, to create a streamly-0.9.0
127derivation from Hackage:
129```
130 streamly =
131 nixpkgs.haskell.lib.overrideCabal
132 (
133 super.callHackageDirect
134 { pkg = "streamly";
135 ver = "0.9.0";
136 sha256 = "sha256-eOxVb8qQjZDo1+S7CStqYSExOg2QHWkMY+zlOYqwZak=";
137 } {}
138 )
139 (old:
140 { librarySystemDepends =
141 if nixpkgs.lib.strings.hasInfix "darwin" builtins.currentSystem
142 then [nixpkgs.darwin.apple_sdk.frameworks.Cocoa]
143 else [];
144 });
145```