ReScript Project spec #51
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,261 @@ | ||
| # Project heuristics | ||
|
|
||
| Vscode and vim need to be able to detect the correct location of the `.compiler.log`, `bsc.exe` and `bsb` for diagnostics and formatting. | ||
| Different project layouts result into different locations. The aim of this document is to formalize the different cases and specify where the editor tooling should search for `.compiler.log`, `bsc.exe` and `bsb` | ||
|
|
||
| ## Heuristics | ||
|
|
||
| 1. `.compiler.log` (diagnostics) | ||
| - Starting from the current open file, walk the filesystem upwards, until `bsconfig.json` is located | ||
| - `.compiler.log` is located at `path.join(foundDirectory, "lib", "bs", ".compiler.log")` | ||
|
|
||
| 2. platform specific `bsc.exe` (formatter) | ||
| - Starting from the current open file, walk the filesystem upwards, until `./node_modules/bs-platform` is located | ||
| - `bsc.exe` is located at `path.join(foundDirectory, "./node_modules/bs-platform", platform, "bsc.exe")` | ||
|
|
||
|
There was a problem hiding this comment. This is not exact since if you are not in the root project but in a dependency, this might be wrong There was a problem hiding this comment. I have a vague memory that there is something called |
||
| 3. `bsb` (start a build/get freshest data) | ||
| - Starting from the current open file, walk the filesystem upwards, until `./node_modules/.bin/bsb` is located | ||
| - `bsb` is located at `path.join(foundDirectory, "./node_modules/.bin", "bsb")` | ||
|
|
||
| ## Cases | ||
| ### Simple project | ||
|
|
||
| ``` | ||
| /folder1 | ||
| /src | ||
| App.res | ||
| /lib | ||
| /bs | ||
| .compiler.log | ||
| /node_modules | ||
| /bs-platform | ||
| /darwin|linux|win32 | ||
| bsc.exe | ||
| /.bin | ||
| bsb | ||
| package.json | ||
| bsconfig.json | ||
| ``` | ||
|
|
||
| Typical workflow: | ||
| 1. run `yarn` or `npm install` in `/folder1` | ||
| 2. build: `npx/yarn bsb` in `/folder1` | ||
|
|
||
| When `/folder1/src/App.res` is openend in the editor: | ||
| 1. `bsc.exe` can be found in `folder1/node_modules/bs-platform/{platform}/bsc.exe` | ||
| 2. `.compiler.log` can be found in `folder1/lib/bs/.compiler.log` | ||
| 3. `bsb` to get a build for this project and get the freshest data: `folder1/node_modules/.bin/bsb` | ||
|
|
||
|
|
||
| ### Monorepo with yarn workspace with one ReScript project in subfolder | ||
| ``` | ||
| /root | ||
| /folder1 | ||
| /src | ||
| App.res | ||
| /lib | ||
| /bs | ||
| .compiler.log | ||
| /node_modules | ||
| /.bin | ||
| bsb | ||
| package.json | ||
| bsconfig.json | ||
| /node_modules | ||
| /bs-platform | ||
| /darwin|linux|win32 | ||
| bsc.exe | ||
| /.bin | ||
| bsb | ||
| package.json | ||
| yarn.lock | ||
| ``` | ||
|
|
||
| Typical workflow: | ||
| 1. run `yarn` in the root | ||
| 2. build folder1: `cd folder1 && yarn bsb` | ||
|
|
||
| When `/folder1/src/App.res` is openend in the editor: | ||
| 1. `bsc.exe` can be found in `/root/node_modules/bs-platform/{platform}/bsc.exe` | ||
| 2. `.compiler.log` can be found in `/root/folder1/lib/bs/.compiler.log` | ||
| 3. `bsb` to get a build for this project and get the freshest data: `/root/folder1/node_modules/.bin/bsb`. Note that there's also a one in `/root/node_modules/.bin/bsb`. The bsb in the subfolder is a symlink to the one in the root's node_modules. Bsb needs a `bsconfig.json` in the current working directory, so the cwd for bsb needs to be `/root/folder1` | ||
|
|
||
|
|
||
| ### Yarn workspace with multiple ReScript projects in subfolders | ||
|
|
||
| Monorepo with two subfolders `folder1` and `folder2` on the same bs-platform version. | ||
|
|
||
| ``` | ||
| /root | ||
| /folder1 | ||
| /src | ||
| Folder1App.res | ||
| /lib | ||
| /bs | ||
| .compiler.log | ||
| /node_modules | ||
| /.bin | ||
| bsb | ||
| package.json | ||
| bsconfig.json | ||
| /folder2 | ||
| /src | ||
| Folder2App.res | ||
| /lib | ||
| /bs | ||
| .compiler.log | ||
| /node_modules | ||
| /.bin | ||
| bsb | ||
| package.json | ||
| bsconfig.json | ||
| /node_modules | ||
| /bs-platform | ||
| /darwin|linux|win32 | ||
| bsc.exe | ||
| /.bin | ||
| bsb | ||
| package.json | ||
| yarn.lock | ||
| ``` | ||
|
|
||
| Typical workflow: | ||
| 1. run `yarn` in the root | ||
| 2. build folder1: `cd folder1 && yarn bsb` | ||
| 3. build folder2: `cd folder2 && yarn bsb` | ||
|
|
||
|
There was a problem hiding this comment. this is incorrect. user should only run bsb in the main repo. |
||
|
|
||
| When `/root/folder1/src/Folder1App.res` is openend in the editor: | ||
| 1. `bsc.exe` can be found in `/root/node_modules/bs-platform/{platform}/bsc.exe` | ||
| 2. `.compiler.log` can be found in `/root/folder1/lib/bs/.compiler.log` | ||
| 3. `bsb` to get a build for this project and get the freshest data: `/root/folder1/node_modules/.bin/bsb`. Note that there's also a one in `/root/node_modules/.bin/bsb`. The bsb in the subfolder is a symlink to the one in the root's node_modules. Bsb needs a `bsconfig.json` in the current working directory, so the cwd needs for bsb to be `/root/folder1` | ||
|
|
||
| When `/root/folder2/src/Folder2App.res` is openend in the editor: | ||
| 1. `bsc.exe` can be found in `/root/node_modules/bs-platform/{platform}/bsc.exe` | ||
| 2. `.compiler.log` can be found in `/root/folder2/lib/bs/.compiler.log` | ||
| 3. `bsb` to get a build for this project and get the freshest data: `/root/folder2/node_modules/.bin/bsb`. Note that there's also a one in `/root/node_modules/.bin/bsb`. The bsb in the subfolder is a symlink to the one in the root's node_modules. Bsb needs a `bsconfig.json` in the current working directory, so the cwd for bsb needs to be `/root/folder2` | ||
|
|
||
| ### Yarn workspace with multiple ReScript projects in subfolders where one is on a different bs-platform version | ||
|
|
||
| Monorepo where `folder1` and `folder2` are on `bs-platform` 8.4.2 and `folder3` on 8.3.3 | ||
|
|
||
|
There was a problem hiding this comment. This should not happen, since the main entry point decides the compiler version |
||
| ``` | ||
| /folder1 | ||
| /src | ||
| Folder1App.res | ||
| /lib | ||
| /bs | ||
| .compiler.log | ||
| /node_modules | ||
| /.bin | ||
| bsb --> symlink to /root/node_modules/.bin/bsb | ||
| package.json | ||
| bsconfig.json | ||
| /folder2 | ||
| /src | ||
| Folder2App.res | ||
| /lib | ||
| /bs | ||
| .compiler.log | ||
| /node_modules | ||
| /.bin | ||
| bsb --> symlink to /root/node_modules/.bin/bsb | ||
| package.json | ||
| bsconfig.json | ||
| /folder3 | ||
| /src | ||
| Folder3App.res | ||
| /lib | ||
| /bs | ||
| .compiler.log | ||
| /node_modules --> contains bs-platform with 8.3.3 | ||
| /.bin | ||
| bsb --> 8.3.3 | ||
| /bs-platform | ||
| /darwin|linux|win32 | ||
| bsc.exe --> 8.3.3 | ||
| package.json | ||
| bsconfig.json | ||
| /node_modules | ||
| /bs-platform | ||
| /darwin|linux|win32 | ||
| bsc.exe | ||
| /.bin | ||
| bsb | ||
| package.json | ||
| yarn.lock | ||
| ``` | ||
|
|
||
| Typical workflow: | ||
| 1. run `yarn` in the root | ||
| 2. build folder1: `cd folder1 && yarn bsb` | ||
| 3. build folder2: `cd folder2 && yarn bsb` | ||
| 4. build folder3: `cd folder3 && ./node_modules/.bin/bsb` (if you want to run bsb 8.3.3) | ||
|
|
||
| When `/root/folder1/src/Folder1App.res` is openend in the editor: | ||
| 1. `bsc.exe` can be found in `/root/node_modules/bs-platform/{platform}/bsc.exe` | ||
| 2. `.compiler.log` can be found in `/root/folder1/lib/bs/.compiler.log` | ||
| 3. `bsb` to get a build for this project and get the freshest data: `/root/folder1/node_modules/.bin/bsb`. Note that there's also a one in `/root/node_modules/.bin/bsb`. The bsb in the subfolder is a symlink to the one in the root's node_modules. Bsb needs a `bsconfig.json` in the current working directory, so the cwd needs to be `/root/folder1` | ||
|
|
||
| When `/root/folder2/src/Folder2App.res` is openend in the editor: | ||
| 1. `bsc.exe` can be found in `/root/node_modules/bs-platform/{platform}/bsc.exe` | ||
| 2. `.compiler.log` can be found in `/root/folder2/lib/bs/.compiler.log` | ||
| 3. `bsb` to get a build for this project and get the freshest data: `/root/folder2/node_modules/.bin/bsb`. Note that there's also a one in `/root/node_modules/.bin/bsb`. The bsb in the subfolder is a symlink to the one in the root's node_modules. Bsb needs a `bsconfig.json` in the current working directory, so the cwd for bsb needs to be `/root/folder2` | ||
|
|
||
| When `/root/folder3/src/Folder3App.res` is openend in the editor: | ||
| 1. `bsc.exe` can be found in `/root/folder3/node_modules/bs-platform/{platform}/bsc.exe` | ||
| 2. `.compiler.log` can be found in `/root/folder3/lib/bs/.compiler.log` | ||
| 3. `bsb` to get a build for this project and get the freshest data: `/root/folder3/node_modules/.bin/bsb`. Here we need to use the `bsb` from `/root/folder3/node_modules/.bin/bsb` to get the correct 8.3.3 bsb! | ||
|
|
||
| ### Yarn workspace with the "pinned dependencies" ReScript feature. | ||
|
|
||
| Monorepo with two folders: `folder1` and `folder2` on the same bs-platform version. The `bsconfig.json` of `folder1` contains: `"pinned-dependencies": ["folder2"]`. | ||
|
|
||
| ``` | ||
| /root | ||
| /folder1 | ||
| /src | ||
| Folder1App.res | ||
| /lib | ||
| /bs | ||
| .compiler.log | ||
| /node_modules | ||
| /.bin | ||
| bsb | ||
| package.json | ||
| bsconfig.json | ||
| /folder2 | ||
| /src | ||
| Folder2App.res | ||
| /lib | ||
| /bs | ||
| .compiler.log | ||
| /node_modules | ||
| /.bin | ||
| bsb | ||
| package.json | ||
| bsconfig.json | ||
| /node_modules | ||
| /bs-platform | ||
| /darwin|linux|win32 | ||
| bsc.exe | ||
| /.bin | ||
| bsb | ||
| package.json | ||
| yarn.lock | ||
| ``` | ||
|
|
||
| Typical workflow: | ||
| - install node_modules: `yarn` from `/root` | ||
| - build: run `yarn bsb -make-world` from `/folder1` to build `/folder1` and `/folder2` | ||
|
|
||
| When `/root/folder1/src/Folder1App.res` is openend in the editor: | ||
| 1. `bsc.exe` can be found in `/root/node_modules/bs-platform/{platform}/bsc.exe` | ||
| 2. `.compiler.log` can be found in `/root/folder1/lib/bs/.compiler.log` | ||
| 3. `bsb` to get a build for this project and get the freshest data: `/root/folder1/node_modules/.bin/bsb`. Note that there's also a one in `/root/node_modules/.bin/bsb`. The bsb in the subfolder is a symlink to the one in the root's node_modules. Bsb needs a `bsconfig.json` in the current working directory, so the cwd for bsb needs to be `/root/folder1` | ||
|
|
||
| When `/root/folder2/src/Folder2App.res` is openend in the editor: | ||
| 1. `bsc.exe` can be found in `/root/node_modules/bs-platform/{platform}/bsc.exe` | ||
| 2. `.compiler.log` can be found in `/root/folder2/lib/bs/.compiler.log` | ||
| 3. `bsb` to get a build for this project and get the freshest data: `/root/folder2/node_modules/.bin/bsb`. Note that there's also a one in `/root/node_modules/.bin/bsb`. The bsb in the subfolder is a symlink to the one in the root's node_modules. Bsb needs a `bsconfig.json` in the current working directory, so the cwd for bsb needs to be `/root/folder2` | ||
|
|
||
| **Note**: Running `yarn bsb -make-world` from `folder1` will build `folder2` due to pinned dependencies. When changes are maded to `folder2`, either `bsb -make-world` needs to be run from `folder1` or a `bsb` from `folder2` to get up to date diagnostics and type information in `folder2`. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this is correct