Skip to content

Commit 4065bdc

Browse files
vramanajordwalke
vramana
authored and
jordwalke
committed
Revert Install Instructions to use npm
1 parent 5dd7ed6 commit 4065bdc

4 files changed

Lines changed: 166 additions & 66 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@ _build/**
1313
*.run
1414
*.opt
1515

16+
node_modules

‎README-NPM.md‎

Lines changed: 0 additions & 24 deletions
This file was deleted.

‎README-Yarn.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# ExampleProject
2+
3+
[![Build Status](https://travis-ci.org/reasonml/ExampleProject.svg?branch=master)](https://travis-ci.org/reasonml/ExampleProject)
4+
5+
> Note: Usage via Yarn may not work completely yet.
6+
7+
# Reason via `yarn`
8+
9+
Example project using Reason as an `yarn` dependency.
10+
11+
(For instructions with npm, see [Reason via npm](https://github.com/reasonml/ExampleProject/blob/master/README-NPM.md))
12+
13+
## Install yarn:
14+
15+
[yarn](https://yarnpkg.com/) is a fast, reliable, and secure dependency management tool. You can now use yarn to install reason and manage its dependencies.
16+
17+
```
18+
npm install -g yarn
19+
```
20+
21+
## Get started:
22+
```sh
23+
git clone https://github.com/reasonml/ExampleProject.git
24+
cd ExampleProject
25+
yarn cache clean # need to clean every time before installation, see https://github.com/yarnpkg/yarn/issues/480
26+
yarn install
27+
yarn reasonbuild
28+
yarn start
29+
```
30+
31+
## Included Top Level
32+
33+
The top level `rtop` is built in to the sandbox:
34+
35+
```sh
36+
# Opens `rtop` from the sandbox.
37+
yarn top
38+
39+
```
40+
41+
# Editor Support
42+
43+
All of the IDE support, including error highlighting, autocomplete, and
44+
syntax is included inside of the sandbox.
45+
46+
```sh
47+
# Opens your `$EDITOR` with all the right tools in your `$PATH`
48+
yarn editor
49+
```
50+
or
51+
```sh
52+
# Opens your `$EDITOR` with all the right tools in your `$PATH`
53+
npm run editor
54+
```
55+
56+
To make your editor load the IDE support from the sandbox:
57+
58+
- Make sure your `$EDITOR` variable is set if not already.
59+
- `export EDITOR=vim`, or `export EDITOR=atom`
60+
- Configure your `EDITOR` to load the `Reason` plugins. See the instructions
61+
for [Atom](http://facebook.github.io/reason/tools.html#merlin-atom) and
62+
[Vim](https://github.com/facebook/reason/tree/master/editorSupport/VimReason).
63+
64+
> Note: If you use `atom`, and already have `opam` installed, then there's a
65+
known issue where `atom` has problems loading, but you can fix it easily
66+
by commenting out any part in your `bashrc` that sources opam environments.
67+
We will come up with a long term solution at some point.
68+
69+
70+
### What's happening
71+
- `npm install` / `yarn install` will download and install all your dependencies, and run the
72+
`postinstall` steps for all of those dependencies, and then finally the
73+
`postinstall` script step of this project.
74+
- `npm start` / `yarn start` will run the script located in the `start` field of the
75+
`scripts` section of the `package.json` file here. The `start` script simply
76+
runs the binary that was built in the `postinstall` step.
77+
- No, really - all you need is `npm` (> `3.0`) or yarn. All of the compiler infrastructure
78+
has been organized into `npm` packages, and will be compiled on your host
79+
inside of the `./node_modules` directory. No `PATH`s are poluted. No global
80+
environment variables destroyed. No trace is left on your system. If you
81+
delete the `./node_modules` directory, you're back to exactly where you
82+
started.
83+
84+
85+
### How to customize
86+
- `npm` / `yarn` allows `scripts` to be specified in your project's `package.json`.
87+
These `scripts` are a named set of commands.
88+
- A few scripts have special meaning, such as the `postinstall` script. The
89+
`postinstall` script is how your project compiles itself. It is guaranteed
90+
that the `postinstall` script executes any time you run `npm install` / `yarn install` in this
91+
package, or any time another package installs you as a dependency. You're
92+
also guaranteed that your `postinstall` script is executed *after* all of
93+
your dependencies' `postinstall` scripts.
94+
- You can add new named scripts in the `package.json` `scripts` field. Once
95+
added, you can then run them via `npm run scriptName` from within the project
96+
root.
97+
- `. dependencyEnv` is commonly used in these `scripts`. The dot `.` sources
98+
`dependencyEnv` which manages the environment, and ensure that important
99+
binaries (such as `refmt`) are in the `PATH`. `dependencyEnv` ensures that
100+
the environment is augmented only for the duration of that `script` running,
101+
and only in ways that you or your immediate dependencies decide. When
102+
the entire purpose of developer tools is to generate a binary (such as a
103+
compiler) to be included in your `PATH`, or produce a library whose path
104+
should be specified in an special environment variable, it's almost like the
105+
environment variable is the public API of that package. `dependencyEnv`
106+
allows your script to see the environment variables that your immediate
107+
dependencies wanted to publish as their public API. You can learn how
108+
packages can publish environment variables in the [dependency-env
109+
repo](https://github.com/npm-ml/dependency-env).
110+
111+
### Recompiling
112+
- To recompile this package (but not your dependencies), remove the local build
113+
artifacts for this package (usually just the `_build` directory) and then run
114+
`yarn postinstall` or `npm run postinstall`.
115+
116+
### How to turn this project into a library
117+
118+
- To turn this example project into a library that other people can depend on
119+
via `npm`... (coming soon).
120+
121+
### Troubleshooting:
122+
- Check to make sure everything is installed correctly. There's a `script`
123+
already setup that will help you test the location of where `Reason` has been
124+
compiled into.
125+
126+
```
127+
npm run whereisreason
128+
```
129+
130+
131+
- If something goes wrong, try deleting the local `node_modules` directory that
132+
was installed, and then try reinstalling using `npm install -f`.
133+
134+
- For yarn, also delete `~/.yarn` and `./yarn.lock` to remove build cache.
135+
136+
### TODO:
137+
138+
- This also installs sandboxed IDE support for Vim/Atom/Emacs. We need to
139+
upgrade all of the plugins to automatically search for IDE plugins inside of
140+
the `./node_modules` directory.

‎README.md‎

Lines changed: 25 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,41 @@
11
# ExampleProject
22

33
[![Build Status](https://travis-ci.org/reasonml/ExampleProject.svg?branch=master)](https://travis-ci.org/reasonml/ExampleProject)
4-
> Note: This example will be rapidly changing. It is not officially supported
5-
> yet. Always reclone the repo each time you try it out (rebasing is not
6-
> sufficient).
74

8-
# Reason via `yarn`
5+
## Reason via `npm`
96

10-
Example project using Reason as an `yarn` dependency.
7+
Example project using Reason as an `npm` dependency.
118

12-
(For instructions with npm, see [Reason via npm](https://github.com/reasonml/ExampleProject/blob/master/README-NPM.md))
13-
14-
## Install yarn:
15-
16-
[yarn](https://yarnpkg.com/) is a fast, reliable, and secure dependency management tool. You can now use yarn to install reason and manage its dependencies.
9+
> Note: This example will be rapidly changing. It is not officially supported
10+
> yet. Always reclone the repo each time you try it out (rebasing is not
11+
> sufficient).
1712
18-
```
19-
npm install -g yarn
20-
```
13+
## Get Started:
2114

22-
## Get started:
2315
```sh
2416
git clone https://github.com/reasonml/ExampleProject.git
2517
cd ExampleProject
26-
yarn cache clean # need to clean every time before installation, see https://github.com/yarnpkg/yarn/issues/480
27-
yarn install
28-
yarn reasonbuild
29-
yarn start
18+
npm install
19+
npm start
3020
```
3121

22+
If you are running as `root` already (you probably aren't) then invoke `npm
23+
install --unsafe-perm` instead.
24+
3225
## Included Top Level
3326

34-
The top level `rtop` is built in to the sandbox:
27+
The top level `rtop` is built in to the sandbox:
3528

3629
```sh
3730
# Opens `rtop` from the sandbox.
38-
yarn top
39-
31+
npm run top
4032
```
4133

42-
# Editor Support
34+
## Editor Support
4335

4436
All of the IDE support, including error highlighting, autocomplete, and
45-
syntax is included inside of the sandbox.
37+
syntax is included inside of the sandbox.
4638

47-
```sh
48-
# Opens your `$EDITOR` with all the right tools in your `$PATH`
49-
yarn editor
50-
```
51-
or
5239
```sh
5340
# Opens your `$EDITOR` with all the right tools in your `$PATH`
5441
npm run editor
@@ -69,13 +56,13 @@ We will come up with a long term solution at some point.
6956

7057

7158
### What's happening
72-
- `npm install` / `yarn install` will download and install all your dependencies, and run the
59+
- `npm install` will download and install all your dependencies, and run the
7360
`postinstall` steps for all of those dependencies, and then finally the
7461
`postinstall` script step of this project.
75-
- `npm start` / `yarn start` will run the script located in the `start` field of the
62+
- `npm start` will run the script located in the `start` field of the
7663
`scripts` section of the `package.json` file here. The `start` script simply
7764
runs the binary that was built in the `postinstall` step.
78-
- No, really - all you need is `npm` (> `3.0`) or yarn. All of the compiler infrastructure
65+
- No, really - all you need is `npm` (> `3.0`). All of the compiler infrastructure
7966
has been organized into `npm` packages, and will be compiled on your host
8067
inside of the `./node_modules` directory. No `PATH`s are poluted. No global
8168
environment variables destroyed. No trace is left on your system. If you
@@ -84,11 +71,11 @@ We will come up with a long term solution at some point.
8471

8572

8673
### How to customize
87-
- `npm` / `yarn` allows `scripts` to be specified in your project's `package.json`.
74+
- `npm` allows `scripts` to be specified in your project's `package.json`.
8875
These `scripts` are a named set of commands.
8976
- A few scripts have special meaning, such as the `postinstall` script. The
9077
`postinstall` script is how your project compiles itself. It is guaranteed
91-
that the `postinstall` script executes any time you run `npm install` / `yarn install` in this
78+
that the `postinstall` script executes any time you run `npm install` in this
9279
package, or any time another package installs you as a dependency. You're
9380
also guaranteed that your `postinstall` script is executed *after* all of
9481
your dependencies' `postinstall` scripts.
@@ -112,7 +99,7 @@ We will come up with a long term solution at some point.
11299
### Recompiling
113100
- To recompile this package (but not your dependencies), remove the local build
114101
artifacts for this package (usually just the `_build` directory) and then run
115-
`yarn postinstall` or `npm run postinstall`.
102+
`npm run postinstall`.
116103

117104
### How to turn this project into a library
118105

@@ -123,20 +110,16 @@ We will come up with a long term solution at some point.
123110
- Check to make sure everything is installed correctly. There's a `script`
124111
already setup that will help you test the location of where `Reason` has been
125112
compiled into.
126-
113+
114+
- If something goes wrong, try deleting the local `node_modules` directory that
115+
was installed, and then try reinstalling using `npm install -f`.
116+
127117
```
128118
npm run whereisreason
129119
```
130120

131-
132-
- If something goes wrong, try deleting the local `node_modules` directory that
133-
was installed, and then try reinstalling using `npm install -f`.
134-
135-
- For yarn, also delete `~/.yarn` and `./yarn.lock` to remove build cache.
136-
137121
### TODO:
138122

139123
- This also installs sandboxed IDE support for Vim/Atom/Emacs. We need to
140124
upgrade all of the plugins to automatically search for IDE plugins inside of
141125
the `./node_modules` directory.
142-

0 commit comments

Comments
 (0)