You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: bspacks/README.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -54,7 +54,7 @@ to that version first:
54
54
opam switch 4.02.3
55
55
```
56
56
57
-
Build / install the main Reason repo. Follow the instructions in https://github.com/facebook/reason/blob/master/src/README.md#contributor-setup.
57
+
Build / install the main Reason repo. Follow the instructions in https://github.com/facebook/reason/blob/master/docs/GETTING_STARTED_CONTRIBUTING.md#contributor-setup.
**See a list of easy tasks [here](https://github.com/facebook/reason/labels/GOOD%20FIRST%20TASK)**
4
-
5
-
## Code of Conduct
6
-
The code of conduct is described in [`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md)
7
-
8
3
## Contributor Setup
9
4
10
-
Thanks for considering contributing to Reason! Here's the setup you need:
11
5
12
-
### With opam
6
+
### With esy
13
7
14
8
```sh
15
-
# On OSX, install opam via Homebrew:
16
-
brew update
17
-
brew install opam
18
-
# On Linux, see here (you will need opam >= 1.2.2): http://opam.ocaml.org/doc/Install.html
19
-
20
-
opam init
21
-
# Add this to your ~/.bashrc (or ~/.zshrc), then do `source ~/.bashrc`
22
-
# eval $(opam config env)
23
-
24
-
opam update
25
-
opam switch 4.04.2
26
-
eval$(opam config env)
9
+
# Make sure you have the latest esy
10
+
npm install -g esy@next
27
11
git clone https://github.com/facebook/reason.git
28
12
cd reason
29
-
opam pin add -y reason .
30
-
opam pin add -y rtop .
13
+
esy
31
14
```
32
15
33
-
### With esy
34
16
35
-
[`esy`](https://github.com/esy/esy) is an `npm`-like workflow for developing and consuming
36
-
opam packages. It is still experimental, but if you're more familiar with `npm` than `opam`,
37
-
`esy` will likely be an easier way to contribute to Reason.
38
-
**Please file issues regarding `esy` at the [esy project](https://github.com/esy/esy) itself.**
17
+
#### Testing:
18
+
19
+
**Test Suite:**
39
20
40
21
```sh
41
-
# Make sure you have the latest esy
42
-
npm remove -g esy
43
-
npm install -g esy@next
44
-
git clone https://github.com/facebook/reason.git
45
-
cd reason
46
-
esy install
47
-
esy build
22
+
esy test# Run tests
48
23
```
49
24
50
-
##### Editors
51
-
- To use VSCode, just open the Reason project root, and `ocaml-language-server` automatically
52
-
works with `esy` projects, loading all the right dependencies.
53
-
- To use Vim/Emacs, start your editor using `esy vim` or `esy emacs`.
25
+
**One Off Tests:**
54
26
55
-
##### Running tests
27
+
Start up the `rtop` top level with your changes:
56
28
57
-
You can run commands as if you had installed Reason by prefixing commands with `esy x` ("esy execute").
58
-
For example `esy x make test-once-installed`
59
-
29
+
```sh
30
+
esy x rtop
31
+
```
60
32
33
+
Pipe some text to `refmt` with your changes:
61
34
62
-
For more, see the [esy documentation](https://github.com/esy-ocaml/esy).
35
+
```sh
36
+
echo"let a = 1"| esy x refmt
37
+
```
63
38
64
-
### Troubleshooting
65
39
66
-
- Is the previous pinning unsuccessful? We might have updated a dependency; try `opam update` then `opam upgrade`.
67
-
- During the last `opam pin` step, make sure your local repo is clean. In particular, remove artifacts and `node_modules`. Otherwise the pinning might go stale or stall due to the big `node_modules`.
40
+
> **`esy` tips:**
41
+
> -`esy x your command` will run one command `your command` in an environment
42
+
> where the projects are built/installed. `esy x which refmt` will build the
43
+
> packages and install them for the duration of one command - `which refmt`.
44
+
> This will print the location of the built `refmt` binary.
45
+
> - For more, see the [esy documentation](https://github.com/esy-ocaml/esy).
68
46
69
-
### Build
70
47
71
-
`esy x refmt --help`. **If this fails on your machine but master passes**, it means your setup wasn't right. Could you check if you followed the above installation steps? In particular, make sure you did `eval $(opam config env)` and sourced your shell environment (if you don't know how, just open a new shell tab and it'll be sourced usually).
48
+
> All the built binaries are in `esy echo '#{self.target_dir}/install/default/bin'`.
72
49
73
-
The generated artifacts are in `esy echo '#{self.target_dir}/default/`. All the binaries are in `esy echo '#{self.target_dir}/install/default/bin`.
74
50
75
-
### Test
51
+
### With opam
76
52
77
-
To do some one-off tests, try `echo "let a = 1" | esy x refmt`
53
+
```sh
54
+
# On OSX, install opam via Homebrew:
55
+
brew update
56
+
brew install opam
57
+
# On Linux, see here (you will need opam >= 1.2.2): http://opam.ocaml.org/doc/Install.html
78
58
79
-
`esy x make test-once-installed` (make sure to follow the repo pinning instructions above!). The tests will output the difference between the expected syntax formatting and the actual one, if any.
59
+
opam init
60
+
# Add this to your ~/.bashrc (or ~/.zshrc), then do `source ~/.bashrc`
61
+
# eval $(opam config env)
62
+
63
+
opam update
64
+
opam switch 4.04.2
65
+
eval$(opam config env)
66
+
git clone https://github.com/facebook/reason.git
67
+
cd reason
68
+
opam pin add -y reason .
69
+
opam pin add -y rtop .
70
+
```
71
+
> **Opam Troubleshooting:**
72
+
> - Is the previous pinning unsuccessful? We might have updated a dependency;
73
+
> try `opam update` then `opam upgrade`.
74
+
> - During the last `opam pin` step, make sure your local repo is clean. In
75
+
> particular, remove artifacts and `node_modules`. Otherwise the pinning
76
+
> might go stale or stall due to the big `node_modules`.
80
77
81
-
Small exception: testing your changes in `rtop` is a little complicated, but you usually don't need to test it. If you do, you might have seen that your changes of the parser or printer don't affect `rtop` when you run it. Instead, you need to do `opam pin add -y reason .` and _then_ run `rtop` to see the Reason changes reflected.
We're that orange part! The core of the codebase is a parser + a printer, plus other miscellaneous utilities we expose.
84
+
Reason is the orange part. The core of the codebase is a parser + a printer, plus other miscellaneous utilities we expose.
89
85
90
86
Throughout the codebase, you might see mentions of "migrate-parsetree", `Ast_404`, etc. These refer to https://github.com/let-def/ocaml-migrate-parsetree. It's a library that allows you to convert between different versions of the OCaml AST. This way, the Reason repo can be written in OCaml 4.04's AST data structures, while being usable on OCaml 4.02's libraries (BuckleScript's on 4.02 too).
91
87
92
-
Our lexer & parser use [Menhir](http://gallium.inria.fr/~fpottier/menhir/), a library that helps us with parsing (it's a "parser generator"). We **highly recommend** you to read about Menhir [here](https://realworldocaml.org/v1/en/html/parsing-with-ocamllex-and-menhir.html).
88
+
The Reason lexer & parser use [Menhir](http://gallium.inria.fr/~fpottier/menhir/), a library that generates parsers. You can read more about Menhir [here](https://realworldocaml.org/v1/en/html/parsing-with-ocamllex-and-menhir.html).
93
89
94
90
### Core Files
95
91
@@ -100,7 +96,7 @@ Our lexer & parser use [Menhir](http://gallium.inria.fr/~fpottier/menhir/), a li
100
96
-`src/reason-parser/reason_pprint_ast.ml`: the pretty-printer! This is the reverse of parsing: it takes in the AST (abstract syntax tree) and prints out the nicely formatted code text.
101
97
102
98
-`src/reason-parser/reason_parser.messages.checked-in`: this is the huge table of mostly generated, sometimes hand-written, syntax error messages. When the parser ends up at an invalid parsing state (aka ends up with a syntax error), it'd refer to that file's content and see if that case has a specific error message assigned to it. For an example fix, see [this PR](https://github.com/facebook/reason/pull/1018) and the [follow-up](https://github.com/facebook/reason/pull/1033). To add a syntax error message see the "Add a Menhir Error Message" section below.
103
-
- When running `make build`, and a new `reason_parser.messages` file is generated, do a `mv reason_parser.messages reason_parser.messages.checked-in` to persist the updated messages.
99
+
- When running `esy`, and a new `reason_parser.messages` file is generated, do a `mv reason_parser.messages reason_parser.messages.checked-in` to persist the updated messages.
104
100
105
101
-`src/reason-parser/reason_oprint.ml`: the "outcome printer" used by Merlin, rtop and terminal, that prints the errors in Reason syntax. More info in the file itself.
106
102
@@ -112,7 +108,7 @@ Our lexer & parser use [Menhir](http://gallium.inria.fr/~fpottier/menhir/), a li
112
108
113
109
-`*.mllib`: related: see the [OCaml extensions list](https://reasonml.github.io/docs/en/faq.html#i-m-seeing-a-weird-cmi-cmx-cmj-cma-file-referenced-in-a-compiler-error-where-do-these-files-come-from-). These are generated file from `pkg/build.ml`, which describes the package we distribute. No need to worry about them.
114
110
115
-
-`src/reason-parser/reason_config.ml`: global configuration that says whether our parser should run in "recoverable" mode. Merlin has a neat feature which lets it continue diagnosing e.g. type errors even when the file is syntactically invalid (at the expense of the accuracy of those type error reports' quality). Searching `reason_config` in our codebase will show you how this is used.
111
+
-`src/reason-parser/reason_config.ml`: global configuration that says whether the parser should run in "recoverable" mode. Merlin has a neat feature which lets it continue diagnosing e.g. type errors even when the file is syntactically invalid (at the expense of the accuracy of those type error reports' quality). Searching `reason_config` in the codebase will show you how this is used.
116
112
117
113
-`src/refmttype/reason_format_type.ml`, `reason_type_of_ocaml_type.ml`: again, see `pkg/build.ml`. These produce the `refmttype` binary, used by [BetterErrors](refmttype) to output compiler errors in Reason syntax rather than the OCaml one.
118
114
@@ -122,11 +118,11 @@ Our lexer & parser use [Menhir](http://gallium.inria.fr/~fpottier/menhir/), a li
122
118
123
119
-`src/rtop/reason_utop.ml`, `src/rtop/reason_toploop.ml`, `src/rtop/rtop_init.ml`: Reason's [Utop](https://github.com/diml/utop) integration. Utop's the terminal-based REPL you see when executing `utop` (in Reason's case, the wrapper `rtop`).
-`src/reason-parser/reactjs_jsx_ppx_v2.ml`: our ReactJS interop that translates [Reason JSX](https://reasonml.github.io/docs/en/jsx.html) into something that ReactJS understands. See the comments in the file and the description in [ReasonReact](https://reasonml.github.io/reason-react/#reason-react-jsx).
125
+
-`src/reason-parser/reactjs_jsx_ppx_v2.ml`: the ReactJS interop that translates [Reason JSX](https://reasonml.github.io/docs/en/jsx.html) into something that ReactJS understands. See the comments in the file and the description in [ReasonReact](https://reasonml.github.io/reason-react/#reason-react-jsx).
130
126
131
127
-`src/reason-parser-tests/testOprint.ml`: unit tests for the outcome printer mentioned above. See the file for more info on how outcome printing is tested.
132
128
@@ -135,12 +131,11 @@ Our lexer & parser use [Menhir](http://gallium.inria.fr/~fpottier/menhir/), a li
135
131
Here's a recommended workflow:
136
132
137
133
- First put your code in the current master syntax in a file `test.re`
138
-
-`make build`
139
134
-`esy x refmt --print ast test.re`
140
135
- look closely at the ast, spot the thing you need
@@ -178,7 +173,9 @@ Random Stack Overflow answer: https://stackoverflow.com/questions/9897358/ocaml-
178
173
179
174
### Debugging Grammar Conflicts
180
175
181
-
Run the main parser through Menhir with the `--explain` flag to have it print out details about the conflict. `menhir --explain src/reason-parser/reason_parser.mly`. The debug information can be found at `src/reason-parser/reason_parser.conflicts`.
176
+
Run the main parser through Menhir with the `--explain` flag to have it print
177
+
out details about the conflict. `esy menhir --explain src/reason-parser/reason_parser.mly`.
178
+
The debug information can be found at `src/reason-parser/reason_parser.conflicts`.
182
179
183
180
### Debugging the Parser State at Runtime
184
181
@@ -193,7 +190,6 @@ export OCAMLRUNPARAM='p'
193
190
To add a Menhir error message, you first need to know the error code. To find the error code, you can run the following commands from the Reason project root:
194
191
195
192
```
196
-
make
197
193
esy x refmt --parse re foo.re
198
194
```
199
195
@@ -223,7 +219,6 @@ In some situations, Reason might report errors in a different place than where i
223
219
Before digging into Reason parser, make sure this isn't actually caused by some PPX. Otherwise, run:
Basically, turn your old syntax into an AST (which is resilient to syntax changes), then turn it back into the new, textual code. If you're reverting to an old enough version, the old binary's flags and/or the old build instructions might be different. In that case, see `esy x refmt --help` and/or the old README.
267
-
268
-
## Cutting a release
269
-
270
-
### OPAM Releases
271
-
272
-
Reason exists on OCaml's package manager OPAM.
273
-
274
-
- Make sure local changes are properly committed
275
-
- Update remote:
276
-
277
-
```sh
278
-
git fetch;
279
-
git reset --hard origin/master
280
-
```
281
-
282
-
- Prerelease:
283
-
284
-
```sh
285
-
env version=x.y.z make pre_release
286
-
```
287
-
288
-
- Check everything is ok locally
289
-
- Release!
290
-
291
-
```sh
292
-
env version=x.y.z make release
293
-
```
294
-
295
-
- Use [opam-publish](https://github.com/ocaml/opam-publish) to publish the latest version to opam.
296
-
297
-
#### Releasing to OPAM manually
298
-
299
-
Typically Reason will be released to NPM first (through Esy). To manually release
300
-
to OPAM, simply:
301
-
302
-
1. Copy the `.opam` file(s) in this repo
303
-
2. Add a `url` clause ([example](https://github.com/ocaml/opam-repository/blob/a55812366d555a5d2ba45cba01fbdab49e459515/packages/reason/reason.3.2.0/opam#L28-L31)) with the place where to find the release tarball.
304
-
3. Submit a PR to the [OPAM repository](https://github.com/ocaml/opam-repository) under e.g.
305
-
`packages/reason/reason.X.Y.Z/opam`.
306
-
307
-
### Esy Releases
308
-
309
-
Cutting a release of esy versions is a good way to get packages out there for
310
-
testing before submitting to opam. This lets you catch bugs quickly without
311
-
having to go through the whole process of re-releasing to opam.
312
-
313
-
```sh
314
-
esy install
315
-
esy build
316
-
esy make esy-prepublish
317
-
```
318
-
319
-
Then follow the instructions. You should also probably `cd` into each
320
-
`_release/xxxx/package` and try `esy install && esy build` to make sure
321
-
everything builds correctly before publishing esy packages. If each of the
322
-
individual packages builds correctly, then `rm` the `_release` directory
323
-
and re-prepare the release by reruning `esy make esy-prepublish`. There's no
324
-
need to test that each package builds correctly - you already did that.
325
-
326
-
Note `esy` packages are "published to npm" but that is different than the
327
-
following workflow for publishing to npm.
328
-
329
-
### NPM
330
-
331
-
Reason's also on npm, albeit for a different purpose. The `refmt.js` file is distributed there, for use-cases where the native `refmt` doesn't suffice (e.g. using it on the web).
332
-
333
-
To publish to npm, get https://github.com/sindresorhus/np and run `np`.
0 commit comments