git.iko.soy/streamly
on bfeee8a help sign in
streamly/docs/User/HowTo/Compiling.md
132 lines 4.4 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### GHC Plugin for Stream Fusion
26Streamly usually performs very well without any compiler plugins.
27However, we have fixed some deficiencies in GHC's optimizer using a
28[compiler plugin](https://github.com/composewell/fusion-plugin). We
29hope to fold these optimizations into GHC in the future; until then we
30recommend that you use this plugin for applications that are performance
31sensitive.
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```
48See [Explanation](#explanation) section below for details about these flags.
50Important Notes:
521. [fusion-plugin](https://hackage.haskell.org/package/fusion-plugin) can
53 improve performance significantly by better stream fusion, in many
54 cases. If the performance regresses due to fusion-plugin please open
55 an issue. You may remove the `-fplugin` option for regular builds
56 but it is recommended for deployment builds and performance
57 benchmarking.
582. In certain cases it is possible that GHC takes too long to compile
59 with `-fspec-constr-recursive=16`, if that happens please reduce the
60 value or remove that option.
62#### Explanation
64* `-fdicts-strict` is needed to avoid [a GHC
65issue](https://gitlab.haskell.org/ghc/ghc/issues/17745) leading to
66memory leak in some cases.
68* `-fspec-constr-recursive` is needed for better stream fusion, it
69allows the `SpecConstr` optimization to occur in more cases. Large
70values used with this flag may lead to huge compilation times and code
71bloat, if that happens please avoid it or use a lower value (e.g. 3 or
724).
74* `-fmax-worker-args` is needed for better stream fusion, it allows the
75`SpecConstr` optimization to occur in some important cases.
77* `-fplugin=Fusion.Plugin` enables predictable stream fusion
78optimization in certain cases by helping the compiler inline internal
79bindings, therefore, enabling case-of-case optimization. In some cases,
80it can make a difference of 5-10x better performance.
82### Multi-core Parallelism
84Concurrency without a threaded runtime may be a bit more efficient. Do not use
85threaded runtime unless you really need multi-core parallelism. To get
86multi-core parallelism use the following GHC options:
88 `-threaded -with-rtsopts "-N"`
90## Platform Specific Features
92Streamly supports Linux, macOS and Windows operating systems. Some
93modules and functionality may depend on specific OS kernel features.
94Features/modules may get disabled if the kernel/OS does not support it.
96### Linux
98File system events notification module is supported only for kernel versions
992.6.36 onwards.
101### macOS
103File system events notification module supports macOS 10.7+ . You must
104have the ``Cocoa`` framework installed which is supplied by the macOS
105SDK. If ``Cocoa`` is not installed, you may see an error like this:
107```
108error: ld: framework not found Cocoa
109```
111### Native build
113Usually, if you have a working GHC you would already have the SDK
114installed. See the documentation of `Xcode` or `xcode-select` tool for
115more details.
117### Nix build
119Please note that `cabal2nix` may not always be able to generate a complete nix
120expression on `macOS`. See [this
121issue](https://github.com/NixOS/cabal2nix/issues/470).
123You may need to add ``nixpkgs.darwin.apple_sdk.frameworks.Cocoa`` to
124your ``buildInputs`` or ``executableFrameworkDepends``. Something like
125this:
127```
128executableFrameworkDepends =
129 if builtins.currentSystem == "x86_64-darwin"
130 then [nixpkgs.darwin.apple_sdk.frameworks.Cocoa]
131 else [];
132```