diff --git a/PROJECT_HEURISTICS.md b/PROJECT_HEURISTICS.md new file mode 100644 index 000000000..c6215bf70 --- /dev/null +++ b/PROJECT_HEURISTICS.md @@ -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")` + +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` + + +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 + +``` + /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`.