@@ -1,296 +1,224 @@
11<!--
2+(c) 2019, Composewell Technologies.
23Portions (c) 2020, Google LLC.
34SPDX-License-Identifer: BSD-3-Clause
45-->
56
6−# Getting started with the `streamly` package
7+# Getting started with `Haskell Streamly`
78
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.
9+This guide shows you how to write a simple program that uses
10+[Streamly][].
11+
12+## Pre-requisites
1113
1214<!-- TODO: Add instructions for `stack` and `nix`.
1315
1416If you are using `stack` or `nix` please make sure to add the latest
1517version from Hackage to your tool configuration. -->
1618
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.
19+No prior knowledge of Haskell is needed. We do however assume that you
20+are using a command-line shell on a POSIX operating system. If you are
21+running Windows™ then you may need to run a command-line shell
22+under `msys` and some of the commands below may also need to be changed
23+in small ways to make them work.
2224
23−**Note**: If you are new to Haskell you may find the [Haskell Getting
24−Started Guide][haskell-getting-started] to be useful.
25+### Installing Haskell
2526
26−If you know your way around Haskell, and have an up to date toolchain
27−already installed, then you can jump straight to the section titled
28−"[_Prepare Your Build Directory_](#prepare-your-build-directory)".
27+To get started, you will need a fairly recent version (last three major
28+versions will work) of the Haskell compiler `ghc` and the build tool
29+`cabal` installed on your system. Please see the install instructions
30+at https://www.haskell.org/downloads/ .
2931
30−## Getting started with `streamly` using `cabal`
32+### Complete Development Environment
3133
32−To get started, you will need a recent `cabal` binary to be installed
33−on your system.
34+If you use the nix package manager, a nix shell for complete
35+development environment - including a consistent set of latest streamly
36+ecosystem packages, hoogle documentation, vim and vscode editors,
37+Haskell language server (HLS) and other tools - is available at
38+[streamly-packages][streamly-packages].
3439
35−### Installing `cabal`
40+## Using `streamly` Interactively in REPL
3641
37−A pre-packaged `cabal` binary may already be available for your
38−operating system.
42+You can try out `streamly` using `GHCi`, the interactive Haskell
43+read-eval-print-loop (REPL).
3944
40−For example, on Debian GNU/Linux, you could install `cabal` using::
45+Streamly consists of two packages, namely `streamly-core` and
46+`streamly`. The former package provides basic functionality and the
47+latter provides higher level functionality. To start up the GHCi REPL
48+using the latest released `streamly-core` package from Hackage, please
49+use:
4150
4251```
43−$ sudo apt install cabal-install
52+$ cabal repl --build-depends streamly-core
53+... plenty of build messages, the first time around ...
54+GHCi, version 9.2.2: https://www.haskell.org/ghc/ :? for help
55+ghci>
4456```
4557
46−### Installing `ghc`
47−
48−You would also need to install the Glasgow Haskell Compiler `ghc`. In
49−most operating systems, using the system's package manager to install
50−`cabal` would also bring in a version of `ghc` as a dependency.
51−
52−Please verify that `ghc` is present:
53−
54−```
55−$ ghc --version
56−The Glorious Glasgow Haskell Compilation System, version 8.0.2
57−```
58+This command may take a while to build the package first time around,
59+please be patient.
5860
59−If `ghc` isn't present, please install it using your operating
60−system's package manager. For example, on Debian GNU/Linux, use:
61+Once at the `ghci>` prompt, you can import Haskell modules from the
62+`streamly-core` package and use the available functions in the REPL:
6163
6264```
63−$ sudo apt install ghc
64−```
65−
66−### Update `cabal` if necessary
67−
68−Many operating systems ship an old version of `cabal`; in order to use
69−`streamly` you should use `cabal` version 3.0 (or later).
70−
71−You can check the installed version of `cabal` by using its
72−`--version` flag:
65+ghci> import qualified Streamly.Data.Stream as Stream
66+ghci> import qualified Streamly.Data.Fold as Fold
7367
68+ghci> Stream.fold Fold.drain $ Stream.mapM print $ Stream.fromList [1..3]
69+1
70+2
71+3
72+ghci>
7473```
75−$ which cabal
76−/usr/bin/cabal
77−$ /usr/bin/cabal --version
78−cabal-install version 1.24.0.2
79−compiled using version 1.24.2.0 of the Cabal library
80−```
81−
82−In this example, the installed `cabal` binary is too old for our
83−needs. It would need to be upgraded.
8474
85−You can ask `cabal` to upgrade itself (please see
86−<https://www.haskell.org/cabal/>):
75+For the curious, here is a high level overview of what these lines
76+do:
8777
88−```
89−$ cabal install Cabal cabal-install
90−Resolving dependencies...
91−Downloading base16-bytestring-0.1.1.7...
92−... lots of build output ...
93−Building cabal-install-3.0.0.0...
94−Installed cabal-install-3.0.0.0
95−```
78+1. `import qualified Streamly.Data.Stream as Stream` imports the Streamly
79+ Stream module into GHCi, and makes it available under the name `Stream`.
80+2. `[1..3]` generates the Haskell list `[1, 2, 3]`.
81+3. `Stream.fromList` transforms that list into a stream of integers.
82+4. `Stream.mapM print` transforms the stream of integers into a stream of
83+ actions that would print those integers when executed.
84+5. `Stream.fold Fold.drain` folds that stream using the `drain` fold,
85+ transforming it into an IO action that evaluates the stream.
9686
97−`cabal` will usually place its compiled binaries inside the directory
98−`$HOME/.cabal/bin`.
87+### Using a specific version of `streamly` in the REPL
9988
100−You can verify the version of your newly installed binary by using the
101−`--version` flag again:
89+You can also ask `cabal` to use a specific version of `streamly-core` by
90+adding a version number constraint to the `--build-depends` flag:
10291
10392```
104−$ $HOME/.cabal/bin/cabal --version
105−cabal-install version 3.0.0.0
106−compiled using version 3.0.2.0 of the Cabal library
93+$ cabal repl --build-depends streamly-core==0.8.3
94+...
95+ghci>
10796```
10897
109−If you have upgraded `cabal`, do be sure to specify `$HOME/.cabal/bin`
110−early in your `PATH` shell variable, so that the new binary gets used
111−instead of the older version on your system.
98+## Using `streamly` in a Project
11299
113−```
114−$ PATH=$HOME/.cabal/bin:$PATH
115−```
116−
117−Once you have `cabal` version 3.0 (or later) successfully installed,
118−please refresh its package list by using `cabal update`.
100+Create a project directory for our example project.
119101
120102```
121−$ cabal update
122−Downloading the latest package list from hackage.haskell.org
103+$ mkdir streamly-project
123104```
124105
125−### Prepare Your Build Directory
126−
127−Next, create a build directory, so that you can use `cabal`'s isolated
128−builds feature.
106+Run `cabal init` in the project directory to create an initial set of
107+project files:
129108
130109```
131−$ mkdir streamly-play
132−$ cd streamly-play
133−```
134−
135−Run `cabal init` to create an initial set of project files:
110+$ cd streamly-project
111+$ cabal init --minimal --dependency base --dependency streamly-core
136112
113+...
114+Generating app/Main.hs...
115+Generating streamly-project.cabal...
116+...
137117```
138−$ cabal init --minimal --dependency base --dependency streamly
139118
140−Generating LICENSE...
141−... other messages ...
142−Generating Main.hs...
143−Generating streamly-play.cabal...
119+This invocation sets up a Haskell package named `streamly-project`
120+with two build dependencies, namely `base` (the Haskell standard
121+library) and `streamly-core`. You can add additional dependencies
122+later, by editing the `build-depends` section of the generated
123+cabal file `streamly-project.cabal`. Please see the [Cabal User
124+Guide](https://www.haskell.org/cabal/users-guide/) for more information
125+on `.cabal` files.
144126
145−Warning: no synopsis given. You should edit the .cabal file and add one.
146−You may want to edit the .cabal file and add a Description field.
147−```
127+This invocation also creates a skeletal `app/Main.hs` file which we
128+will now use to write our streamly based program.
148129
149−This invocation will set up a build with two build dependencies,
150−namely `base` and `streamly`. You can add additional dependencies
151−later, by editing the `build-depends` section of the generated cabal
152−file `streamly-play.cabal`. Please see the [Cabal User
153−Guide](https://www.haskell.org/cabal/users-guide/) for more
154−information on how to configure `cabal`.
130+### Use `streamly` in the Project Code
155131
156−This invocation also creates a skeletal `Main.hs` program which we
157−will use later.
132+Let us now turn the single-line stanza we used in the REPL into a
133+standalone program.
158134
159−### Try `streamly` in the GHCi REPL
135+Edit `app/Main.hs` to contain the following:
160136
161−You can now try out `streamly` using the `GHCi` interpreter's
162−read-eval-print-loop (REPL) facility.
137+```haskell
138+module Main where
163139
164−To start up the GHCi REPL using the released `streamly` version on
165−Hackage, please use:
140+import qualified Streamly.Data.Stream as Stream
141+import qualified Streamly.Data.Fold as Fold
166142
167−```
168−$ cabal repl --build-depends streamly
169−... plenty of build messaages, the first time around ...
170−GHCi, version 8.8.3: https://www.haskell.org/ghc/ :? for help
171−[1 of 1] Compiling Main ( Main.hs, interpreted )
172−Ok, one module loaded.
173−*Main>
143+main :: IO ()
144+main = Stream.fold Fold.drain $ Stream.mapM print $ Stream.fromList [1..3]
174145```
175146
176−Once at the `*Main>` prompt, you can import `streamly` and use it
177−directly:
147+Build and run this program using `cabal run`:
178148
179149```
180−*Main> import qualified Streamly.Prelude as Stream
181−
182−*Main Stream> Stream.drain $ Stream.mapM print $ Stream.fromList [1..3]
150+$ cabal run
151+... build messages ...
1831521
1841532
1851543
186−*Main Stream>
187155```
188156
189−For the curious, here is a high level overview of what these lines
190−do:
191−
192−1. `import qualified Streamly.Prelude as Stream` imports the Streamly
193− prelude into GHCi, and makes it available as module `Stream`.
194−2. `[1..3]` generates the Haskell list `[1, 2, 3]`.
195−3. `Stream.fromList` transforms that list into a stream of integers.
196−4. `Stream.mapM print` transforms the stream of integers into a stream of
197− actions that would print those integers when executed.
198−5. `Stream.drain` transforms that stream of actions into an IO action that
199− `main` or GHCi's REPL can execute.
200−
201−#### Using a specific version of `streamly` in the REPL
157+### Running the project in GHCi REPL
202158
203−You can also ask `cabal` to use a specific version of `streamly` by
204−adding a version number constraint to the `--build-depends` flag:
159+To start up the GHCi REPL for your project, please use:
205160
206161```
207−$ cabal repl --build-depends streamly==0.8.2
208−[1 of 1] Compiling Main ( Main.hs, interpreted )
209−Ok, modules loaded: Main.
210−*Main>
162+$ cabal repl
163+...
164+ghci>
211165```
212166
213−#### (Advanced) Using the development version of `streamly` in the REPL
167+The repl will load all the dependencies and modules of the project. You can now
168+run your project code or any other code snippets as you desire.
169+
170+### (Advanced) Using the development version of `streamly`
214171
215172To use the development version of `streamly`, we need to configure
216173`cabal` to fetch it from Github.
217174
218−Create a `cabal.project` file in the current directory with the
175+Create a `cabal.project` file in the project directory with the
219176following content:
220177
221178```
222179packages: .
180+-- fetch streamly-core dependency package from github
223181source-repository-package
224182 type: git
225183 location: https://github.com/composewell/streamly
184+ subdir: core
226185 tag: master
227186```
228187
229188With this file present, `cabal` will fetch and build the current
230−version of `streamly` from Github every time it is run. For example:
189+version of `streamly-core` from Github. For example:
231190
232191```
233192$ cabal repl
234−... fetches the 'master' branch of streamly from Github ...
235−... build messages ...
236−[1 of 1] Compiling Main v ( Main.hs, interpreted )
237−Ok, modules loaded: Main.
238−*Main>
239−```
240−
241−### Using `streamly` in a standalone program
242−
243−Let us now turn the single-line stanza above into a standalone program
244−that uses `streamly`.
245−
246−Edit `Main.hs` to contain the following:
247−
248−```haskell
249−module Main where
250−
251−import qualified Streamly.Prelude as Stream
252−
253−main :: IO ()
254−main = Stream.drain $ Stream.mapM print $ Stream.fromList [1..3]
255−```
256−
257−Build and run this program using `cabal run`:
258−
259−```
260−$ cabal run
261−... build messages ...
262−1
263−2
264−3
193+Cloning into '/home/harendra/streamly-project/...
194+...
195+In order, the following will be built (use -v for more details):
196+ - streamly-core-0.1.0 (lib:streamly-core) (requires build)
197+ - streamly-project-0.1.0.0 (exe:streamly-project) (configuration changed)
198+ ...
199+ghci>
265200```
266201
267202## Which version of `streamly` should you use?
268203
269−If you are new to Streamly, we recommend using latest [stable release
204+If you are new to Streamly, we recommend using the latest [stable release
270205of streamly][streamly-hackage] on Hackage.
271206
272207If you need access to cutting edge features (and do not mind the
273208occasional breakage), please use the [development version of
274−streamly][streamly-github] on Github.
275−
209+streamly][streamly-github] from Github.
276210
277211## Next Steps
278212
279−If you got this far successfully, congratulations!
280−
281−* For an overview of the `streamly` package, please read the
282− [Streamly Quick Overview](/docs/User/Tutorials/Introduction.md).
283−* Please browse the code examples in the
284− [`Streamly examples repository`][streamly-examples].
285−* If you would like to start on a real world project, please take a
286− look at the [Streamly Build Guide](/docs/User/HowTo/Compiling.md).
287−* For comprehensive documentation please visit the
288− [Streamly Homepage][Streamly].
213+If you got this far successfully, congratulations! For an overview
214+of the `streamly` package, please read the [Streamly Quick
215+Overview](/docs/User/Tutorials/Introduction.md).
289216
290217<!-- Markdown Links -->
291218
292219 [Streamly]: https://streamly.composewell.com/
293220 [streamly-hackage]: https://hackage.haskell.org/package/streamly
294221 [streamly-github]: https://github.com/composewell/streamly
222+ [streamly-packages]: https://github.com/composewell/streamly-packages
295223 [streamly-examples]: https://github.com/composewell/streamly-examples
296224 [haskell-getting-started]: https://github.com/composewell/haskell-dev/blob/master/getting-started.rst