git.iko.soy/streamly
on master help sign in
Add build/test/bench instructions
f3c31f0Harendra Kumar
CONTRIBUTING.md+43−36
compare with master
unifiedsplit
@@ -15,6 +15,43 @@ Beginners are encouraged to pick up issues that are marked `help wanted`. It is
15a good idea to update the issue expressing your intent so that others do not
15a good idea to update the issue expressing your intent so that others do not
16duplicate the effort and people with a background on the issue can help.
16duplicate the effort and people with a background on the issue can help.
17
17
18+## Build and test
19+
20+Some common commands:
21+
22+```
23+$ cabal repl
24+$ cabal build
25+$ cabal build --disable-optimization --flags -opt
26+$ bin/test.sh --quick
27+$ bin/bench.sh --quick # For nix use "--use-nix"
28+$ bin/run-ci --targets help # Only supported with nix
29+$ cabal haddock
30+$ cabal-docspec --timeout 60 --check-properties --property-variables xs
31+```
32+
33+The `bin/test.sh` and `bin/bench.sh` are custom scripts to perform test
34+and benchmarking tasks conveniently. They support running a group of
35+tests or benchmarks, coverage, using correct optimization flags for
36+benchmarking, benchmark comparison reports etc. Use the `--help` option
37+to see how to use these. See [benchmark/README.md](benchmark/README.md)
38+and [test/README.md](test/README.md) for more details.
39+
40+You can also run tests or benchmarks directly for example:
41+
42+```
43+$ cabal test --disable-optimization --flags -opt --test-show-details=streaming --test-option=--color streamly-tests
44+```
45+
46+To view haddock docs open the link printed at the end of the haddock
47+command, in your browser.
48+
49+Nix users: There is a `default.nix` available which can be used to start
50+a nix-shell and then use the above commands as usual. nix-shell started
51+by `default.nix` creates a `.cabal.nix` for cabal configuration and sets
52+`CABAL_DIR` environment variable to point to that. Therefore, `~/.cabal`
53+would not be used.
54+
18## Contributing A Change
55## Contributing A Change
19
56
20If the feature makes significant changes to design, we encourage you to open an
57If the feature makes significant changes to design, we encourage you to open an
@@ -107,8 +144,9 @@ BRANCH.
107
144
108### Testing
145### Testing
109
146
110−It is a good idea to include tests for the changes where applicable. See the
147+It is a good idea to include tests for the changes where applicable. See
111−existing tests [here](test).
148+the existing tests in the [test](test) directory. Also see the
149+[test/README](test/README) for more details on how to run the tests.
112
150
113### Documentation
151### Documentation
114
152
@@ -182,16 +220,9 @@ copying does not have an associated license please do not use it.
182
220
183## Developer documentation
221## Developer documentation
184
222
185−To build haddock documentation:
223+* Use https://streamly.composewell.com/ for searching in reference docs
186−
224+* Build haddock docs for latest reference docs
187−```
225+* See [the dev directory](dev) for design guidelines and dev documents.
188−$ cabal haddock
189−```
190−
191−Open the link printed at the end of the output of this command, in
192−your browser.
193−
194−For general library developer documentation see the `dev` directory.
195
226
196## Coding Guidelines
227## Coding Guidelines
197
228
@@ -239,27 +270,3 @@ mapM f (Stream step1 state1) = Stream step state
239In general, the rule is - the shorter the scope of a variable the shorter its
270In general, the rule is - the shorter the scope of a variable the shorter its
240name can be. For example, `s` has the shortest scope in the above code, `st`
271name can be. For example, `s` has the shortest scope in the above code, `st`
241has a bigger scope and `state` has the biggest scope.
272has a bigger scope and `state` has the biggest scope.
242−
243−## Design guides
244−
245−See [the design directory](design) for design guidelines and documents.
246−
247−### Tricky Parts
248−
249−The state-passing through each API is currently fragile. Every time we run a
250−stream we need to be careful about the state we are passing to it. In case of
251−folds where there is no incoming state, we start with the initial state
252−`defState`. When we have an incoming state passed to us there are two cases:
253−
254−1. When we are building a concurrent stream that needs to share the same `SVar`
255− we pass the incoming state as is.
256−2. In all other cases we must not share the SVar and every time we pass on the
257− state to run a stream we must use `adaptState` to reset the `SVar` in the
258− state.
259−
260−When in doubt just use `adaptState` on the state before passing it on, we will at
261−most lose concurrency but the behavior will be correct.
262−
263−There is no type level enforcement about this as of now, and therefore we need
264−to be careful when coding. There are specific tests to detect and report any
265−problems due to this, all transform operations must be added to those tests.
dev/overview.mdnew file+24
@@ -0,0 +1,24 @@
1+# Streamly
2+
3+This document is yet to be written. It is supposed to provide an overall
4+design overview for developers.
5+
6+## Tricky Parts
7+
8+The state-passing through each API is currently fragile. Every time we run a
9+stream we need to be careful about the state we are passing to it. In case of
10+folds where there is no incoming state, we start with the initial state
11+`defState`. When we have an incoming state passed to us there are two cases:
12+
13+1. When we are building a concurrent stream that needs to share the same `SVar`
14+ we pass the incoming state as is.
15+2. In all other cases we must not share the SVar and every time we pass on the
16+ state to run a stream we must use `adaptState` to reset the `SVar` in the
17+ state.
18+
19+When in doubt just use `adaptState` on the state before passing it on, we will at
20+most lose concurrency but the behavior will be correct.
21+
22+There is no type level enforcement about this as of now, and therefore we need
23+to be careful when coding. There are specific tests to detect and report any
24+problems due to this, all transform operations must be added to those tests.