git.iko.soy/streamly
on 81bfdec help sign in
streamly/docs/User/HowTo/Compiling.md
123 lines 4.0 kB history raw
1# Build Guide
3## Building
5### Compiler (GHC) Versions
7Do not use ghc 9.0.x and 9.2.1. For best performance use
8`fusion-plugin` (see below) when compiling.
10### Memory requirements
12Building streamly itself may require upto 4GB memory. Depending on the
13size of the application you may require 1-16GB memory to build. For most
14applications up to 8GB of memory should be sufficient.
16To reduce the memory footprint you may want to break big modules
17into smaller ones and reduce unnecessary INLINE pragmas on large
18functions. You can also use the `-Rghc-timing` GHC option to report the
19memory usage during compilation.
21See the "Build times and space considerations" section below for more
22details.
24### Compilation Options
26#### Recommended Options
28Add `fusion-plugin` to the `build-depends` section of your program in
29the cabal file and use the following GHC options:
31```
32 -O2
33 -fdicts-strict
34 -fmax-worker-args=16
35 -fspec-constr-recursive=16
36 -fplugin Fusion.Plugin
37```
39See [Explanation](#explanation) section below for details about these flags.
41Important Notes:
431. [fusion-plugin](https://hackage.haskell.org/package/fusion-plugin) can
44 improve performance significantly by better stream fusion, in many
45 cases. If the performance regresses due to fusion-plugin please open
46 an issue. You may remove the `-fplugin` option for regular builds
47 but it is recommended for deployment builds and performance
48 benchmarking.
492. In certain cases it is possible that GHC takes too long to compile
50 with `-fspec-constr-recursive=16`, if that happens please reduce the
51 value or remove that option.
53#### Explanation
55* `-fdicts-strict` is needed to avoid [a GHC
56issue](https://gitlab.haskell.org/ghc/ghc/issues/17745) leading to
57memory leak in some cases.
59* `-fspec-constr-recursive` is needed for better stream fusion, it
60allows the `SpecConstr` optimization to occur in more cases. Large
61values used with this flag may lead to huge compilation times and code
62bloat, if that happens please avoid it or use a lower value (e.g. 3 or
634).
65* `-fmax-worker-args` is needed for better stream fusion, it allows the
66`SpecConstr` optimization to occur in some important cases.
68* `-fplugin=Fusion.Plugin` enables predictable stream fusion
69optimization in certain cases by helping the compiler inline internal
70bindings, therefore, enabling case-of-case optimization. In some cases,
71it can make a difference of 5-10x better performance.
73### Multi-core Parallelism
75Concurrency without a threaded runtime may be a bit more efficient. Do not use
76threaded runtime unless you really need multi-core parallelism. To get
77multi-core parallelism use the following GHC options:
79 `-threaded -with-rtsopts "-N"`
81## Platform Specific Features
83Streamly supports Linux, macOS and Windows operating systems. Some
84modules and functionality may depend on specific OS kernel features.
85Features/modules may get disabled if the kernel/OS does not support it.
87### Linux
89File system events notification module is supported only for kernel versions
902.6.36 onwards.
92### macOS
94File system events notification module supports macOS 10.7+ . You must
95have the ``Cocoa`` framework installed which is supplied by the macOS
96SDK. If ``Cocoa`` is not installed, you may see an error like this:
98```
99error: ld: framework not found Cocoa
100```
102### Native build
104Usually, if you have a working GHC you would already have the SDK
105installed. See the documentation of `Xcode` or `xcode-select` tool for
106more details.
108### Nix build
110Please note that `cabal2nix` may not always be able to generate a complete nix
111expression on `macOS`. See [this
112issue](https://github.com/NixOS/cabal2nix/issues/470).
114You may need to add ``nixpkgs.darwin.apple_sdk.frameworks.Cocoa`` to
115your ``buildInputs`` or ``executableFrameworkDepends``. Something like
116this:
118```
119executableFrameworkDepends =
120 if builtins.currentSystem == "x86_64-darwin"
121 then [nixpkgs.darwin.apple_sdk.frameworks.Cocoa]
122 else [];
123```