git.iko.soy/streamly
on ec19422 help sign in
streamly/INSTALL.md
298 lines 8.3 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
25Guide](https://github.com/composewell/haskell-dev/blob/master/getting-started.rst)
26to be useful.
28If you know your way around Haskell, and have an up to date toolchain
29already installed, then you can jump straight to the section titled
30"[_Prepare Your Build Directory_](#user-content-prepare-your-build-directory)".
32## Getting started with `streamly` using `cabal`
34To get started, you will need a recent `cabal` binary to be installed
35on your system.
37### Installing `cabal`
39A pre-packaged `cabal` binary may already be available for your
40operating system.
42For example, on Debian GNU/Linux, you could install `cabal` using::
44```
45$ sudo apt install cabal-install
46```
48### Installing `ghc`
50You would also need to install the Glasgow Haskell Compiler `ghc`. In
51most operating systems, using the system's package manager to install
52`cabal` would also bring in a version of `ghc` as a dependency.
54Please verify that `ghc` is present:
56```
57$ ghc --version
58The Glorious Glasgow Haskell Compilation System, version 8.0.2
59```
61If `ghc` isn't present, please install it using your operating
62system's package manager. For example, on Debian GNU/Linux, use:
64```
65$ sudo apt install ghc
66```
68### Update `cabal` if necessary
70Many operating systems ship an old version of `cabal`; in order to use
71`streamly` you should use `cabal` version 3.0 (or later).
73You can check the installed version of `cabal` by using its
74`--version` flag:
76```
77$ which cabal
78/usr/bin/cabal
79$ /usr/bin/cabal --version
80cabal-install version 1.24.0.2
81compiled using version 1.24.2.0 of the Cabal library
82```
84In this example, the installed `cabal` binary is too old for our
85needs. It would need to be upgraded.
87You can ask `cabal` to upgrade itself (please see
88<https://www.haskell.org/cabal/>):
90```
91$ cabal install Cabal cabal-install
92Resolving dependencies...
93Downloading base16-bytestring-0.1.1.7...
94... lots of build output ...
95Building cabal-install-3.0.0.0...
96Installed cabal-install-3.0.0.0
97```
99`cabal` will usually place its compiled binaries inside the directory
100`$HOME/.cabal/bin`.
102You can verify the version of your newly installed binary by using the
103`--version` flag again:
105```
106$ $HOME/.cabal/bin/cabal --version
107cabal-install version 3.0.0.0
108compiled using version 3.0.2.0 of the Cabal library
109```
111If you have upgraded `cabal`, do be sure to specify `$HOME/.cabal/bin`
112early in your `PATH` shell variable, so that the new binary gets used
113instead of the older version on your system.
115```
116$ PATH=$HOME/.cabal/bin:$PATH
117```
119Once you have `cabal` version 3.0 (or later) successfully installed,
120please refresh its package list by using `cabal update`.
122```
123$ cabal update
124Downloading the latest package list from hackage.haskell.org
125```
127### Prepare Your Build Directory
129Next, create a build directory, so that you can use `cabal`'s isolated
130builds feature.
132```
133$ mkdir streamly-play
134$ cd streamly-play
135```
137Run `cabal init` to create an initial set of project files:
139```
140$ cabal init --minimal --dependency base --dependency streamly
142Generating LICENSE...
143... other messages ...
144Generating Main.hs...
145Generating streamly-play.cabal...
147Warning: no synopsis given. You should edit the .cabal file and add one.
148You may want to edit the .cabal file and add a Description field.
149```
151This invocation will set up a build with two build dependencies,
152namely `base` and `streamly`. You can add additional dependencies
153later, by editing the `build-depends` section of the generated cabal
154file `streamly-play.cabal`. Please see the [Cabal User
155Guide](https://www.haskell.org/cabal/users-guide/) for more
156information on how to configure `cabal`.
158This invocation also creates a skeletal `Main.hs` program which we
159will use later.
161### Try `streamly` in the GHCi REPL
163You can now try out `streamly` using the `GHCi` interpreter's
164read-eval-print-loop (REPL) facility.
166To start up the GHCi REPL using the released `streamly` version on
167Hackage, please use:
169```
170$ cabal repl --build-depends streamly
171... plenty of build messaages, the first time around ...
172GHCi, version 8.8.3: https://www.haskell.org/ghc/ :? for help
173[1 of 1] Compiling Main ( Main.hs, interpreted )
174Ok, one module loaded.
175*Main>
176```
178Once at the `*Main>` prompt, you can import `streamly` and use it
179directly:
181```
182*Main> import qualified Streamly.Prelude as S
184*Main S> S.drain $ S.mapM print $ S.fromList [1..3]
188*Main S>
189```
191For the curious, here is a high level overview of what these lines
192do:
1941. `import qualified Streamly.Prelude as S` imports the Streamly
195 prelude into GHCi, and makes it available as module `S`.
1962. `[1..3]` generates the Haskell list `[1, 2, 3]`.
1973. `S.fromList` transforms that list into a stream of integers.
1984. `S.mapM print` transforms the stream of integers into a stream of
199 actions that would print those integers when executed.
2005. `S.drain` transforms that stream of actions into an IO action that
201 `main` or GHCi's REPL can execute.
203These concepts are explained in greater detail in the [Streamly
204Tutorial][tutorial].
206#### Using a specific version of `streamly` in the REPL
208You can also ask `cabal` to use a specific version of `streamly` by
209adding a version number constraint to the `--build-depends` flag:
211```
212$ cabal repl --build-depends streamly==0.7.2
213[1 of 1] Compiling Main ( Main.hs, interpreted )
214Ok, modules loaded: Main.
215*Main>
216```
218#### (Advanced) Using the development version of `streamly` in the REPL
220To use the development version of `streamly`, we need to configure
221`cabal` to fetch it from Github.
223Create a `cabal.project` file in the current directory with the
224following content:
226```
227packages: .
228source-repository-package
229 type: git
230 location: https://github.com/composewell/streamly
231 tag: master
232```
234With this file present, `cabal` will fetch and build the current
235version of `streamly` from Github every time it is run. For example:
237```
238$ cabal repl
239... fetches the 'master' branch of streamly from Github ...
240... build messages ...
241[1 of 1] Compiling Main v ( Main.hs, interpreted )
242Ok, modules loaded: Main.
243*Main>
244```
246### Using `streamly` in a standalone program
248Let us now turn the single-line stanza above into a standalone program
249that uses `streamly`.
251Edit `Main.hs` to contain the following:
253```haskell
254module Main where
256import qualified Streamly.Prelude as S
258main :: IO ()
259main = S.drain $ S.mapM print $ S.fromList [1..3]
260```
262Build and run this program using `cabal run`:
264```
265$ cabal run
266... build messages ...
270```
272## Which version of `streamly` should you use?
274If you are new to Streamly, we recommend using latest [stable release
275of streamly][streamly-hackage] on Hackage.
277If you need access to cutting edge features (and do not mind the
278occasional breakage), please use the [development version of
279streamly][streamly-github] on Github.
282## Next Steps
284If you got this far successfully, congratulations!
286* For an overview of the `streamly` package, please read the
287 [Streamly Tutorial][tutorial].
288* Please browse the code examples in the
289 [`examples`](./examples/README.md) directory.
290* If you would like to start on a real world project, please take a
291 look at the [recommended compilation options](./docs/Build.md).
294<!-- Markdown Links -->
296 [tutorial]: https://hackage.haskell.org/package/streamly/docs/Streamly-Tutorial.html
297 [streamly-hackage]: https://hackage.haskell.org/package/streamly
298 [streamly-github]: https://github.com/composewell/streamly