git.iko.soy/streamly
on 1946eb8 help sign in
streamly/docs/User/Tutorials/setup-and-usage.md
226 lines 6.7 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 install Haskell and the `streamly` package,
10and then use Streamly in a simple program.
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## Installing Haskell
25You can choose one of the following options.
27### Installing the Haskell Toolchain
29To get started, you will need a fairly recent version (last three major
30versions will work) of the Haskell compiler `ghc` and the build tool
31`cabal` installed on your system. Please see the install instructions
32at https://www.haskell.org/downloads/ .
34### Development Environment using Nix
36If you use the nix package manager, a nix shell for complete
37development environment - including a consistent set of latest streamly
38ecosystem packages, hoogle documentation, vim and vscode editors,
39Haskell language server (HLS) and other tools - is available at
40[streamly-packages][streamly-packages].
42## Using `streamly` Interactively in REPL
44You can try out `streamly` using `GHCi`, the interactive Haskell
45read-eval-print-loop (REPL).
47Streamly consists of two packages, namely `streamly-core` and
48`streamly`. The former package provides basic functionality and the
49latter provides higher level functionality. To start up the GHCi REPL
50using the latest released `streamly-core` package from Hackage, please
51use:
53```
54$ cabal repl --build-depends streamly-core
55... plenty of build messages, the first time around ...
56GHCi, version 9.2.2: https://www.haskell.org/ghc/ :? for help
57ghci>
58```
60This command may take a while to build the package first time around,
61please be patient.
63Once at the `ghci>` prompt, you can import Haskell modules from the
64`streamly-core` package and use the available functions in the REPL:
66```
67ghci> import qualified Streamly.Data.Stream as Stream
68ghci> import qualified Streamly.Data.Fold as Fold
70ghci> Stream.fold Fold.drain $ Stream.mapM print $ Stream.fromList [1..3]
74ghci>
75```
77For the curious, here is a high level overview of what these lines
78do:
801. `import qualified Streamly.Data.Stream as Stream` imports the Streamly
81 Stream module into GHCi, and makes it available under the name `Stream`.
822. `[1..3]` generates the Haskell list `[1, 2, 3]`.
833. `Stream.fromList` transforms that list into a stream of integers.
844. `Stream.mapM print` transforms the stream of integers into a stream of
85 actions that would print those integers when executed.
865. `Stream.fold Fold.drain` folds that stream using the `drain` fold,
87 transforming it into an IO action that evaluates the stream.
89### Using a specific version of `streamly` in the REPL
91You can also ask `cabal` to use a specific version of `streamly-core` by
92adding a version number constraint to the `--build-depends` flag:
94```
95$ cabal repl --build-depends streamly-core==0.1.0
96...
97ghci>
98```
100## Using `streamly` in a Project
102Create a project directory for our example project.
104```
105$ mkdir streamly-project
106```
108### Add `streamly` as project dependency
110Run `cabal init` in the project directory to create an initial set of
111project files:
113```
114$ cd streamly-project
115$ cabal init --minimal --dependency base --dependency streamly-core
117...
118Generating app/Main.hs...
119Generating streamly-project.cabal...
120...
121```
123This invocation sets up a Haskell package named `streamly-project`
124with two build dependencies, namely `base` (the Haskell standard
125library) and `streamly-core`. You can add additional dependencies
126later, by editing the `build-depends` section of the generated
127cabal file `streamly-project.cabal`. Please see the [Cabal User
128Guide](https://www.haskell.org/cabal/users-guide/) for more information
129on `.cabal` files.
131This invocation also creates a skeletal `app/Main.hs` file which we
132will now use to write our streamly based program.
134### Import `streamly` modules in the project code
136Let us now turn the single-line stanza we used in the REPL into a
137standalone program.
139Edit `app/Main.hs` to contain the following:
141```haskell
142module Main where
144import qualified Streamly.Data.Stream as Stream
145import qualified Streamly.Data.Fold as Fold
147main :: IO ()
148main = Stream.fold Fold.drain $ Stream.mapM print $ Stream.fromList [1..3]
149```
151Build and run this program using `cabal run`:
153```
154$ cabal run
155... build messages ...
159```
161### Running GHCi REPL for the project code
163To start up the GHCi REPL for your project, please use:
165```
166$ cabal repl
167...
168ghci>
169```
171The repl will load all the dependencies and modules of the project. You can now
172run your project code or any other code snippets as you desire.
174### (Advanced) Using the development version of `streamly`
176To use the development version of `streamly`, we need to configure
177`cabal` to fetch it from Github.
179Create a `cabal.project` file in the project directory with the
180following content:
182```
183packages: .
184-- fetch streamly-core dependency package from github
185source-repository-package
186 type: git
187 location: https://github.com/composewell/streamly
188 subdir: core
189 tag: master
190```
192With this file present, `cabal` will fetch and build the current
193version of `streamly-core` from Github. For example:
195```
196$ cabal repl
197Cloning into '/home/harendra/streamly-project/...
198...
199In order, the following will be built (use -v for more details):
200 - streamly-core-0.1.0 (lib:streamly-core) (requires build)
201 - streamly-project-0.1.0.0 (exe:streamly-project) (configuration changed)
202 ...
203ghci>
204```
206## Which version of `streamly` should you use?
208If you are new to Streamly, we recommend using the latest [stable release
209of streamly][streamly-hackage] on Hackage.
211If you need access to cutting edge features (and do not mind the
212occasional breakage), please use the [development version of
213streamly][streamly-github] from Github.
215## Next Steps
217If you got this far successfully, congratulations! For an overview
218of the `streamly` package, please read the [Streamly Quick
219Overview](/docs/User/Tutorials/quick-overview.md).
221<!-- Markdown Links -->
223 [Streamly]: https://streamly.composewell.com/
224 [streamly-hackage]: https://hackage.haskell.org/package/streamly
225 [streamly-github]: https://github.com/composewell/streamly
226 [streamly-packages]: https://github.com/composewell/streamly-packages