git.iko.soy/streamly
on 3feeec2 help sign in
streamly/INSTALL.md
299 lines 8.7 kB history raw
1<!--
2Portions (c) 2020, Google LLC.
3SPDX-License-Identifer: BSD-3-Clause
4-->
6# Getting started with the `streamly` package
8This guide will show you how to write a simple program that uses
9[Streamly][], using the [`cabal`](https://www.haskell.org/cabal/) build
10manager for Haskell.
12<!-- TODO: Add instructions for `stack` and `nix`.
14If you are using `stack` or `nix` please make sure to add the latest
15version from Hackage to your tool configuration. -->
17No prior knowledge of either Haskell or of `cabal` is needed. We do
18however assume that you are using a command-line shell on a POSIX
19operating system. If you are running Windows&trade; then you may need
20to run a command-line shell under `msys` and some of the commands
21below may also need to be changed in small ways to make them work.
23**Note**: If you are new to Haskell you may find the [Haskell Getting
24Started Guide][haskell-getting-started] to be useful.
26If you know your way around Haskell, and have an up to date toolchain
27already installed, then you can jump straight to the section titled
28"[_Prepare Your Build Directory_](#prepare-your-build-directory)".
30## Getting started with `streamly` using `cabal`
32To get started, you will need a recent `cabal` binary to be installed
33on your system.
35### Installing `cabal`
37A pre-packaged `cabal` binary may already be available for your
38operating system.
40For example, on Debian GNU/Linux, you could install `cabal` using::
42```
43$ sudo apt install cabal-install
44```
46### Installing `ghc`
48You would also need to install the Glasgow Haskell Compiler `ghc`. In
49most operating systems, using the system's package manager to install
50`cabal` would also bring in a version of `ghc` as a dependency.
52Please verify that `ghc` is present:
54```
55$ ghc --version
56The Glorious Glasgow Haskell Compilation System, version 8.0.2
57```
59If `ghc` isn't present, please install it using your operating
60system's package manager. For example, on Debian GNU/Linux, use:
62```
63$ sudo apt install ghc
64```
66### Update `cabal` if necessary
68Many operating systems ship an old version of `cabal`; in order to use
69`streamly` you should use `cabal` version 3.0 (or later).
71You can check the installed version of `cabal` by using its
72`--version` flag:
74```
75$ which cabal
76/usr/bin/cabal
77$ /usr/bin/cabal --version
78cabal-install version 1.24.0.2
79compiled using version 1.24.2.0 of the Cabal library
80```
82In this example, the installed `cabal` binary is too old for our
83needs. It would need to be upgraded.
85You can ask `cabal` to upgrade itself (please see
86<https://www.haskell.org/cabal/>):
88```
89$ cabal install Cabal cabal-install
90Resolving dependencies...
91Downloading base16-bytestring-0.1.1.7...
92... lots of build output ...
93Building cabal-install-3.0.0.0...
94Installed cabal-install-3.0.0.0
95```
97`cabal` will usually place its compiled binaries inside the directory
98`$HOME/.cabal/bin`.
100You can verify the version of your newly installed binary by using the
101`--version` flag again:
103```
104$ $HOME/.cabal/bin/cabal --version
105cabal-install version 3.0.0.0
106compiled using version 3.0.2.0 of the Cabal library
107```
109If you have upgraded `cabal`, do be sure to specify `$HOME/.cabal/bin`
110early in your `PATH` shell variable, so that the new binary gets used
111instead of the older version on your system.
113```
114$ PATH=$HOME/.cabal/bin:$PATH
115```
117Once you have `cabal` version 3.0 (or later) successfully installed,
118please refresh its package list by using `cabal update`.
120```
121$ cabal update
122Downloading the latest package list from hackage.haskell.org
123```
125### Prepare Your Build Directory
127Next, create a build directory, so that you can use `cabal`'s isolated
128builds feature.
130```
131$ mkdir streamly-play
132$ cd streamly-play
133```
135Run `cabal init` to create an initial set of project files:
137```
138$ cabal init --minimal --dependency base --dependency streamly
140Generating LICENSE...
141... other messages ...
142Generating Main.hs...
143Generating streamly-play.cabal...
145Warning: no synopsis given. You should edit the .cabal file and add one.
146You may want to edit the .cabal file and add a Description field.
147```
149This invocation will set up a build with two build dependencies,
150namely `base` and `streamly`. You can add additional dependencies
151later, by editing the `build-depends` section of the generated cabal
152file `streamly-play.cabal`. Please see the [Cabal User
153Guide](https://www.haskell.org/cabal/users-guide/) for more
154information on how to configure `cabal`.
156This invocation also creates a skeletal `Main.hs` program which we
157will use later.
159### Try `streamly` in the GHCi REPL
161You can now try out `streamly` using the `GHCi` interpreter's
162read-eval-print-loop (REPL) facility.
164To start up the GHCi REPL using the released `streamly` version on
165Hackage, please use:
167```
168$ cabal repl --build-depends streamly
169... plenty of build messaages, the first time around ...
170GHCi, version 8.8.3: https://www.haskell.org/ghc/ :? for help
171[1 of 1] Compiling Main ( Main.hs, interpreted )
172Ok, one module loaded.
173*Main>
174```
176Once at the `*Main>` prompt, you can import `streamly` and use it
177directly:
179```
180*Main> import qualified Streamly.Prelude as Stream
182*Main Stream> Stream.drain $ Stream.mapM print $ Stream.fromList [1..3]
186*Main Stream>
187```
189For the curious, here is a high level overview of what these lines
190do:
1921. `import qualified Streamly.Prelude as Stream` imports the Streamly
193 prelude into GHCi, and makes it available as module `Stream`.
1942. `[1..3]` generates the Haskell list `[1, 2, 3]`.
1953. `Stream.fromList` transforms that list into a stream of integers.
1964. `Stream.mapM print` transforms the stream of integers into a stream of
197 actions that would print those integers when executed.
1985. `Stream.drain` transforms that stream of actions into an IO action that
199 `main` or GHCi's REPL can execute.
201These concepts are explained in greater detail in the [Streamly
202Tutorial][tutorial].
204#### Using a specific version of `streamly` in the REPL
206You can also ask `cabal` to use a specific version of `streamly` by
207adding a version number constraint to the `--build-depends` flag:
209```
210$ cabal repl --build-depends streamly==0.7.2
211[1 of 1] Compiling Main ( Main.hs, interpreted )
212Ok, modules loaded: Main.
213*Main>
214```
216#### (Advanced) Using the development version of `streamly` in the REPL
218To use the development version of `streamly`, we need to configure
219`cabal` to fetch it from Github.
221Create a `cabal.project` file in the current directory with the
222following content:
224```
225packages: .
226source-repository-package
227 type: git
228 location: https://github.com/composewell/streamly
229 tag: master
230```
232With this file present, `cabal` will fetch and build the current
233version of `streamly` from Github every time it is run. For example:
235```
236$ cabal repl
237... fetches the 'master' branch of streamly from Github ...
238... build messages ...
239[1 of 1] Compiling Main v ( Main.hs, interpreted )
240Ok, modules loaded: Main.
241*Main>
242```
244### Using `streamly` in a standalone program
246Let us now turn the single-line stanza above into a standalone program
247that uses `streamly`.
249Edit `Main.hs` to contain the following:
251```haskell
252module Main where
254import qualified Streamly.Prelude as Stream
256main :: IO ()
257main = Stream.drain $ Stream.mapM print $ Stream.fromList [1..3]
258```
260Build and run this program using `cabal run`:
262```
263$ cabal run
264... build messages ...
268```
270## Which version of `streamly` should you use?
272If you are new to Streamly, we recommend using latest [stable release
273of streamly][streamly-hackage] on Hackage.
275If you need access to cutting edge features (and do not mind the
276occasional breakage), please use the [development version of
277streamly][streamly-github] on Github.
280## Next Steps
282If you got this far successfully, congratulations!
284* For an overview of the `streamly` package, please read the
285 [Streamly Quick Overview](README.md) and [Streamly Tutorial][tutorial].
286* Please browse the code examples in the
287 [`Streamly examples repository`][streamly-examples].
288* If you would like to start on a real world project, please take a
289 look at the [Streamly Build and Optimization Guide](./docs/Build.md).
290* For more information please visit the [Streamly Homepage][Streamly].
292<!-- Markdown Links -->
294 [Streamly]: https://streamly.composewell.com/
295 [tutorial]: https://hackage.haskell.org/package/streamly-0.7.3/docs/Streamly-Tutorial.html
296 [streamly-hackage]: https://hackage.haskell.org/package/streamly
297 [streamly-github]: https://github.com/composewell/streamly
298 [streamly-examples]: https://github.com/composewell/streamly-examples
299 [haskell-getting-started]: https://github.com/composewell/haskell-dev/blob/master/getting-started.rst