@@ -1,76 +1,227 @@
1−# Using `streamly` package
1+<!--
2+Portions (c) 2020, Google LLC.
3+SPDX-License-Identifer: BSD-3-Clause
4+-->
25
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).
6+# Getting started with the `streamly` package
57
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.
8+This guide will show you how to write a simple program that uses
9+`streamly`, using the [`cabal`](https://www.haskell.org/cabal/) build
10+manager for Haskell.
911
10−## Which version to use?
12+<!-- TODO: Add instructions for `stack` and `nix`.
1113
12−* [Latest stable release](https://hackage.haskell.org/package/streamly) is available on
13− Hackage.
14−* [Latest development version](https://github.com/composewell/streamly) is
15− available on github.
14+If you are using `stack` or `nix` please make sure to add the latest
15+version from Hackage to your tool configuration. -->
1616
17−If you are using `stack` or `nix` please make sure to add the latest version
18−from Hackage to your tool configuration.
17+No prior knowledge of either Haskell or of `cabal` is needed. We do
18+however assume that you are using a command-line shell on a POSIX
19+operating system. If you are running Windows™ then you may need
20+to run a command-line shell under `msys` and some of the commands
21+below may also need to be changed in small ways to make them work.
1922
20−## Recommended build options
23+**Note**: If you are new to Haskell you may find the [Haskell Getting
24+Started
25+Guide](https://github.com/composewell/haskell-dev/blob/master/getting-started.rst)
26+to be useful.
2127
22−See [recommended compilation options here](docs/Build.md).
28+If you know your way around Haskell, and have an up to date toolchain
29+already installed, then you can jump straight to the section titled
30+"[_Prepare Your Build Directory_](#user-content-prepare-your-build-directory)".
2331
24−## Using with `cabal`
32+## Getting started with `streamly` using `cabal`
2533
26−Make sure you have `cabal` version 3.0 or later installed and you have `ghc`
27−available in your PATH. Refresh your package list:
34+To get started, you will need a recent `cabal` binary to be installed
35+on your system.
36+
37+### Installing `cabal`
38+
39+A pre-packaged `cabal` binary may already be available for your
40+operating system.
41+
42+For example, on Debian GNU/Linux, you could install `cabal` using::
43+
44+```
45+$ sudo apt install cabal-install
46+```
47+
48+### Installing `ghc`
49+
50+You would also need to install the Glasgow Haskell Compiler `ghc`. In
51+most operating systems, using the system's package manager to install
52+`cabal` would also bring in a version of `ghc` as a dependency.
53+
54+Please verify that `ghc` is present:
55+
56+```
57+$ ghc --version
58+The Glorious Glasgow Haskell Compilation System, version 8.0.2
59+```
60+
61+If `ghc` isn't present, please install it using your operating
62+system's package manager. For example, on Debian GNU/Linux, use:
63+
64+```
65+$ sudo apt install ghc
66+```
67+
68+### Update `cabal` if necessary
69+
70+Many operating systems ship an old version of `cabal`; in order to use
71+`streamly` you should use `cabal` version 3.0 (or later).
72+
73+You can check the installed version of `cabal` by using its
74+`--version` flag:
75+
76+```
77+$ which cabal
78+/usr/bin/cabal
79+$ /usr/bin/cabal --version
80+cabal-install version 1.24.0.2
81+compiled using version 1.24.2.0 of the Cabal library
82+```
83+
84+In this example, the installed `cabal` binary is too old for our
85+needs. It would need to be upgraded.
86+
87+You can ask `cabal` to upgrade itself (please see
88+<https://www.haskell.org/cabal/>):
89+
90+```
91+$ cabal install Cabal cabal-install
92+Resolving dependencies...
93+Downloading base16-bytestring-0.1.1.7...
94+... lots of build output ...
95+Building cabal-install-3.0.0.0...
96+Installed cabal-install-3.0.0.0
97+```
98+
99+`cabal` will usually place its compiled binaries inside the directory
100+`$HOME/.cabal/bin`.
101+
102+You can verify the version of your newly installed binary by using the
103+`--version` flag again:
104+
105+```
106+$ $HOME/.cabal/bin/cabal --version
107+cabal-install version 3.0.0.0
108+compiled using version 3.0.2.0 of the Cabal library
109+```
110+
111+If you have upgraded `cabal`, do be sure to specify `$HOME/.cabal/bin`
112+early in your `PATH` shell variable, so that the new binary gets used
113+instead of the older version on your system.
114+
115+```
116+$ PATH=$HOME/.cabal/bin:$PATH
117+```
118+
119+Once you have `cabal` version 3.0 (or later) successfully installed,
120+please refresh its package list by using `cabal update`.
28121
29122```
30123$ cabal update
124+Downloading the latest package list from hackage.haskell.org
31125```
32126
33−Create a directory for isolated builds:
127+### Prepare Your Build Directory
128+
129+Next, create a build directory, so that you can use `cabal`'s isolated
130+builds feature.
34131
35132```
36133$ mkdir streamly-play
134+$ cd streamly-play
37135```
38136
39−Create a `.cabal` file:
137+Run `cabal init` to create an initial set of project files:
40138
41139```
42−$ cd streamly-play
43140$ cabal init --minimal --dependency base --dependency streamly
141+
142+Generating LICENSE...
143+... other messages ...
144+Generating Main.hs...
145+Generating streamly-play.cabal...
146+
147+Warning: no synopsis given. You should edit the .cabal file and add one.
148+You may want to edit the .cabal file and add a Description field.
44149```
45150
46−You can add any other dependencies as well later on by editing the
47−`build-depends` section of the cabal file.
151+This invocation will set up a build with two build dependencies,
152+namely `base` and `streamly`. You can add additional dependencies
153+later, by editing the `build-depends` section of the generated cabal
154+file `streamly-play.cabal`. Please see the [Cabal User
155+Guide](https://www.haskell.org/cabal/users-guide/) for more
156+information on how to configure `cabal`.
48157
49−### Using hackage version in repl
158+This invocation also creates a skeletal `Main.hs` program which we
159+will use later.
50160
51−Run repl with the latest version from Hackage:
161+### Try `streamly` in the GHCi REPL
162+
163+You can now try out `streamly` using the `GHCi` interpreter's
164+read-eval-print-loop (REPL) facility.
165+
166+To start up the GHCi REPL using the released `streamly` version on
167+Hackage, please use:
52168
53169```
54170$ cabal repl --build-depends streamly
171+... plenty of build messaages, the first time around ...
55172GHCi, version 8.8.3: https://www.haskell.org/ghc/ :? for help
56173[1 of 1] Compiling Main ( Main.hs, interpreted )
57174Ok, one module loaded.
58−*Main> S.drain $ S.mapM print $ S.fromList [1..3]
175+*Main>
176+```
177+
178+Once at the `*Main>` prompt, you can import `streamly` and use it
179+directly:
180+
181+```
182+*Main> import qualified Streamly.Prelude as S
183+
184+*Main S> S.drain $ S.mapM print $ S.fromList [1..3]
591851
601862
611873
62−*Main>
188+*Main S>
63189```
64190
65−Run repl with a specific version from Hackage:
191+For the curious, here is a high level overview of what these lines
192+do:
193+
194+1. `import qualified Streamly.Prelude as S` imports the Streamly
195+ prelude into GHCi, and makes it available as module `S`.
196+2. `[1..3]` generates the Haskell list `[1, 2, 3]`.
197+3. `S.fromList` transforms that list into a stream of integers.
198+4. `S.mapM print` transforms the stream of integers into a stream of
199+ actions that would print those integers when executed.
200+5. `S.drain` transforms that stream of actions into an IO action that
201+ `main` or GHCi's REPL can execute.
202+
203+These concepts are explained in greater detail in the [Streamly
204+Tutorial][tutorial].
205+
206+#### Using a specific version of `streamly` in the REPL
207+
208+You can also ask `cabal` to use a specific version of `streamly` by
209+adding a version number constraint to the `--build-depends` flag:
66210
67211```
68212$ cabal repl --build-depends streamly==0.7.2
213+[1 of 1] Compiling Main ( Main.hs, interpreted )
214+Ok, modules loaded: Main.
215+*Main>
69216```
70217
71−### Using github version in repl
218+#### (Advanced) Using the development version of `streamly` in the REPL
219+
220+To use the development version of `streamly`, we need to configure
221+`cabal` to fetch it from Github.
72222
73−Create a `cabal.project` file with the following contents:
223+Create a `cabal.project` file in the current directory with the
224+following content:
74225
75226```
76227packages: .
@@ -80,17 +231,26 @@ source-repository-package
80231 tag: master
81232```
82233
83−Run repl:
234+With this file present, `cabal` will fetch and build the current
235+version of `streamly` from Github every time it is run. For example:
84236
85237```
86238$ cabal repl
239+... fetches the 'master' branch of streamly from Github ...
240+... build messages ...
241+[1 of 1] Compiling Main v ( Main.hs, interpreted )
242+Ok, modules loaded: Main.
243+*Main>
87244```
88245
89−### Hello World!
246+### Using `streamly` in a standalone program
90247
91−Edit `Main.hs` as follows:
248+Let us now turn the single-line stanza above into a standalone program
249+that uses `streamly`.
92250
93−```
251+Edit `Main.hs` to contain the following:
252+
253+```haskell
94254module Main where
95255
96256import qualified Streamly.Prelude as S
@@ -99,8 +259,40 @@ main :: IO ()
99259main = S.drain $ S.mapM print $ S.fromList [1..3]
100260```
101261
102−Build and run:
262+Build and run this program using `cabal run`:
103263
104264```
105265$ cabal run
266+... build messages ...
267+1
268+2
269+3
106270```
271+
272+## Which version of `streamly` should you use?
273+
274+If you are new to Streamly, we recommend using latest [stable release
275+of streamly][streamly-hackage] on Hackage.
276+
277+If you need access to cutting edge features (and do not mind the
278+occasional breakage), please use the [development version of
279+streamly][streamly-github] on Github.
280+
281+
282+## Next Steps
283+
284+If you got this far successfully, congratulations!
285+
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).
292+
293+
294+<!-- Markdown Links -->
295+
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