@@ -1,14 +1,26 @@
11# Using `streamly` package
22
3+If you are new to Haskell please take a look at [Haskell Getting Started
4+Guide](https://github.com/composewell/haskell-dev/blob/master/getting-started.rst).
5+
6+The following instructions assume that you are using a shell on a POSIX
7+system. On Windows you need a shell under `msys`, some of the commands
8+may have slight differences.
9+
10+## Which version to use?
11+
312* [Latest stable release](https://hackage.haskell.org/package/streamly) is available on
413 Hackage.
514* [Latest development version](https://github.com/composewell/streamly) is
615 available on github.
7−* See [recommended compilation options here](docs/Build.md).
816
917If you are using `stack` or `nix` please make sure to add the latest version
1018from Hackage to your tool configuration.
1119
20+## Recommended build options
21+
22+See [recommended compilation options here](docs/Build.md).
23+
1224## Using with `cabal`
1325
1426Make sure you have `cabal` version 3.0 or later installed and you have `ghc`
@@ -18,20 +30,47 @@ available in your PATH. Refresh your package list:
1830$ cabal update
1931```
2032
33+Create a directory for isolated builds:
34+
35+```
36+$ mkdir streamly-play
37+```
38+
39+Create a `.cabal` file:
40+
41+```
42+$ cd streamly-play
43+$ cabal init --minimal --dependency base --dependency streamly
44+```
45+
46+You can add any other dependencies as well later on by editing the
47+`build-depends` section of the cabal file.
48+
2149### Using hackage version in repl
2250
51+Run repl with the latest version from Hackage:
52+
2353```
24−# Run repl with the latest version from Hackage
2554$ cabal repl --build-depends streamly
55+GHCi, version 8.8.3: https://www.haskell.org/ghc/ :? for help
56+[1 of 1] Compiling Main ( Main.hs, interpreted )
57+Ok, one module loaded.
58+*Main> S.drain $ S.mapM print $ S.fromList [1..3]
59+1
60+2
61+3
62+*Main>
63+```
2664
27−# Run repl with a specific version from Hackage
28−$ cabal repl --build-depends streamly==0.7.1
65+Run repl with a specific version from Hackage:
66+
67+```
68+$ cabal repl --build-depends streamly==0.7.2
2969```
3070
3171### Using github version in repl
3272
33−Create a directory for your playground (e.g. `test`) and create a
34−`cabal.project` file in it as follows:
73+Create a `cabal.project` file with the following contents:
3574
3675```
3776packages: .
@@ -41,48 +80,27 @@ source-repository-package
4180 tag: master
4281```
4382
44−Create a cabal file (e.g. `test.cabal`) as follows
45−
46−```
47−cabal-version: 2.4
48−name: test
49−version: 0
50−
51−library
52− build-depends: base, streamly
53−```
54−
5583Run repl:
5684
5785```
5886$ cabal repl
5987```
6088
61−### Using with ghc or ghci
89+### Hello World!
6290
63−Before you can use a package with `ghc` or `ghci` directly you need to install
64−the package:
91+Edit `Main.hs` as follows:
6592
6693```
67−$ cabal install streamly-0.7.1 --lib
68−```
94+module Main where
6995
70−```
71−$ cat hello.hs
7296import qualified Streamly.Prelude as S
7397
74−main = S.runStream $ S.fromListM [putStrLn "hello", putStrLn "world"]
98+main :: IO ()
99+main = S.drain $ S.mapM print $ S.fromList [1..3]
75100```
76101
102+Build and run:
103+
77104```
78−$ ghc hello.hs
105+$ cabal run
79106```
80−
81−### Using in a Project
82−
83−Add `streamly` to the `build-depends` section of your library/executable in
84−your `<package>.cabal` file. Appropriate version from Hackage will be picked
85−depending on the version bounds that you specify. See the `github version in
86−repl` section above for a sample `<package>.cabal` file and optionally use the
87−`cabal.project` file if you want to use the development version from github in
88−your project.