git.iko.soy/streamly
on master help sign in
streamly/docs/User/Tutorials/getting-started.md
225 lines 6.4 kB history raw
1<!--
2(c) 2019, Composewell Technologies.
3Portions (c) 2020, Google LLC.
4SPDX-License-Identifer: BSD-3-Clause
5-->
7# Getting started with `Haskell Streamly`
9This guide shows you how to use Streamly in `ghci` REPL, a simple
10program or a Haskell project.
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 Haskell is needed. We do however assume that you
18are using a command-line shell on a POSIX operating system. If you are
19running Windows&trade; then you may need to run a command-line shell
20under `msys` and some of the commands below may also need to be changed
21in small ways to make them work.
23## Using `streamly` Interactively in REPL
25You can try out `streamly` using `GHCi`, the interactive Haskell
26read-eval-print-loop (REPL).
28Streamly consists of two packages, namely `streamly-core` and
29`streamly`. The former package provides basic functionality and the
30latter provides higher level functionality. To start up the GHCi REPL
31using the latest released `streamly-core` package from Hackage, please
32use:
34```
35$ cabal repl --build-depends streamly-core
36... plenty of build messages, the first time around ...
37GHCi, version 9.2.2: https://www.haskell.org/ghc/ :? for help
38ghci>
39```
41This command may take a while to build the package first time around,
42please be patient.
44Once at the `ghci>` prompt, you can import Haskell modules from the
45`streamly-core` package and use the available functions in the REPL:
47```
48ghci> import qualified Streamly.Data.Stream as Stream
49ghci> import qualified Streamly.Data.Fold as Fold
51ghci> Stream.fold Fold.drain $ Stream.mapM print $ Stream.fromList [1..3]
55ghci>
56```
58For the curious, here is a high level overview of what these lines
59do:
611. `import qualified Streamly.Data.Stream as Stream` imports the Streamly
62 Stream module into GHCi, and makes it available under the name `Stream`.
632. `[1..3]` generates the Haskell list `[1, 2, 3]`.
643. `Stream.fromList` transforms that list into a stream of integers.
654. `Stream.mapM print` transforms the stream of integers into a stream of
66 actions that would print those integers when executed.
675. `Stream.fold Fold.drain` folds that stream using the `drain` fold,
68 transforming it into an IO action that evaluates the stream.
70### Using a specific version of `streamly` in the REPL
72You can also ask `cabal` to use a specific version of `streamly-core` by
73adding a version number constraint to the `--build-depends` flag:
75```
76$ cabal repl --build-depends streamly-core==0.1.0
77...
78ghci>
79```
81## Using `streamly` in a Project
83Create a project directory for our example project.
85```
86$ mkdir streamly-project
87```
89### Add `streamly` as project dependency
91Run `cabal init` in the project directory to create an initial set of
92project files:
94```
95$ cd streamly-project
96$ cabal init --non-interactive --minimal --dependency base --dependency streamly-core
98...
99Generating app/Main.hs...
100Generating streamly-project.cabal...
101...
102```
104This invocation sets up a Haskell package named `streamly-project`
105with two build dependencies, namely `base` (the Haskell standard
106library) and `streamly-core`. You can add additional dependencies
107later, by editing the `build-depends` section of the generated
108cabal file `streamly-project.cabal`. Please see the [Cabal User
109Guide](https://www.haskell.org/cabal/users-guide/) for more information
110on `.cabal` files.
112IMPORTANT: Because of a bug in cabal 3.8, which is fixed in cabal 3.10,
113this does not generate a dependency on `base`, please edit the generated
114cabal file and add `base` in the `build-depends` section:
116```
117 build-depends: base, streamly-core
118```
120This invocation also creates a skeletal `app/Main.hs`, therefore, we can
121compile and run it right away:
123```
124$ cabal run
125Hello, Haskell!
126```
128### Import `streamly` modules in the project code
130Let us now turn the single-line stanza we used in the REPL into a
131standalone program.
133Edit `app/Main.hs` to contain the following:
135```haskell
136module Main where
138import qualified Streamly.Data.Stream as Stream
139import qualified Streamly.Data.Fold as Fold
141main :: IO ()
142main = Stream.fold Fold.drain $ Stream.mapM print $ Stream.fromList [1..3]
143```
145Build and run this program using `cabal run`:
147```
148$ cabal run
149... build messages ...
153```
155### Running GHCi REPL for the project code
157To start up the GHCi REPL for your project, please use:
159```
160$ cabal repl
161...
162Ok, one module loaded.
163ghci> main
167ghci>
168```
170The repl will load all the dependencies and modules of the project. You can now
171run your project code or any other code snippets as you desire.
173### (Advanced) Using the development version of `streamly`
175To use the development version of `streamly`, we need to configure
176`cabal` to fetch it from Github.
178Create a `cabal.project` file in the project directory with the
179following content:
181```
182packages: .
183-- fetch streamly-core dependency package from github
184source-repository-package
185 type: git
186 location: https://github.com/composewell/streamly
187 subdir: core
188 tag: master
189```
191With this file present, `cabal` will fetch and build the current
192version of `streamly-core` from Github. For example:
194```
195$ cabal repl
196Cloning into '/home/harendra/streamly-project/...
197...
198In order, the following will be built (use -v for more details):
199 - streamly-core-0.1.0 (lib:streamly-core) (requires build)
200 - streamly-project-0.1.0.0 (exe:streamly-project) (configuration changed)
201 ...
202ghci>
203```
205## Which version of `streamly` should you use?
207If you are new to Streamly, we recommend using the latest [stable release
208of streamly][streamly-hackage] on Hackage.
210If you need access to cutting edge features (and do not mind the
211occasional breakage), please use the [development version of
212streamly][streamly-github] from Github.
214## Next Steps
216If you got this far successfully, congratulations! For an overview
217of the `streamly` package, please read the [Streamly Quick
218Overview](/docs/User/Tutorials/quick-overview.md).
220<!-- Markdown Links -->
222 [Streamly]: https://streamly.composewell.com/
223 [streamly-hackage]: https://hackage.haskell.org/package/streamly
224 [streamly-github]: https://github.com/composewell/streamly
225 [streamly-packages]: https://github.com/composewell/streamly-packages