Thanks for your interest. Below is an informal spec of how the plugin's server communicates with the actual compiler. If you're a ReScript editor plugin implementor, you should probably read this to understand the various important nuances.
This repo happens to also contain a language-server usable by other editors. If you'd like to use this language-server with e.g. Atom, for now, you have to clone the repo and run npm run compile
. The language server will be at server/out/server.js
. Wire that into your editor.
.
├── client // Language Client
│ ├── src
│ │ └── extension.ts // Language Client entry point
├── package.json // The extension manifest.
└── server // Language Server
└── src
└── server.ts // Language Server entry point
-
Run
npm install
at the root. This will also install the necessary npm modules in both theclient
andserver
folders. -
Open VS Code to this folder.
-
Switch to the Debug viewlet (command palette -> View: Show Run and Debug).
-
Select
Client + Server
from the drop down, launch it (green arrow):(If you're getting some Promise-related error alert, file an issue here so that we can find a workaround; this seems to be a VSCode bug).
-
In the [Extension Development Host] instance of VSCode that just opened, open a
.res
file. -
Try various features.
-
When you make a change, Go to the same Debug viewlet's Call Stack panel and restart the client and the server:
- Modify
grammars/rescript.tmLanguage.json
.
For more grammar inspirations, check:
They should be synced in from lib/bs/.compiler.log
build. Don't take them from other places.
The build output is streamed into lib/bs/.compiler.log
. Here are its various states, numbered here:
- Doesn't exist: artifacts not built yet, or cleaned away.
- Present, without a final line
#Done
: still building. - Present, with the final line
#Done
: finished building.
Barring FS errors, there should be no other state to .compiler.log
. Among others, this means the file is never present but empty.
Artifacts cleaning through bsb -clean
removes .compiler.log
and turns into state 1. If that's the case, remove the diagnostics in the editor too. One could argue that they should be kept, but that's misleading UX-wise, and harder to implement correctly.
After saving a file and running the build, the results stream into the log file. Unfortunately, UX-wise, in the editor, this might look like the diagnostics are suddenly gone then coming back in file by file. This looks bad. To remediate:
- If it's in state 2, update those particular files' diagnostics but don't wipe the files' diagnostics yet.
- If in state 3, finish by clean up the rest of the old diagnostics. This means there's a bit of bookeeping needed here. Make sure you get it right. It's possible for a build to be interrupted (and therefore state 4 never reached) and restarted.
Even this fix isn't great. Ideally, the editor's diagnostics can be greyed out while we're updating them...
Keep in mind that you might be tracking multiple .compiler.log
s. You should do the above for each.
To check whether the artifacts are stale, do not check .bsb.lock
at the project root. This is unreliable, since it's possible that bsb
wasn't running in watcher mode. We also don't want to encourage overuse of the watcher mode, though it seems increasingly common.
It's possible to open files from different projects into the same editor instance. In that case, also read that file's project's .compiler.log
.
The bad alternatives are:
- Not show that file's project's errors. That's wrong for several reasons (looks like the file has no error, assumes an editor window has a default project, etc.).
- Show only that file's error. That's just weird, the errors are already read from that project's
.compiler.log
. Might as well show all of them (?).
Don't do that unless you've prompted the user.
- Running an implicit
bsb -w
automatically means you've acquired the build watch mode lockfile. The user won't be able to run his/her ownbsb -w
in the terminal. - Running a one-shot
bsb
doesn't conflict, but is a waste. It's also incorrect, as there might be external file system changes you're not detecting. - The build might be a step in a bigger build. The editor running
bsb
implicitly goes against that. - If you have multiple files with different project roots open, running all of the
bsb
s is too intense.
To find the location of bsc
to run:
- Look for the nearest
bsconfig.json
. That's the root of the project. * - Search in that directory's
node_modules/bs-platform/{platform}/bsc.exe
.- Do not directly use
node_modules/.bin/bsc
if you can help it. That's a Nodejs wrapper. Slow startup. We don't want our formatting to be momentarily stalled because some Nodejs cache went cold. platform
can bedarwin
,linux
,win32
orfreebsd
.
- Do not directly use
* Maybe we'll do this differently in the future because asking for a bsconfig.json
just to format some files is rough.
The formatted result should be taken as-is, without any extra string trimming and newline addition/removal by the editor plugin.
The errors returned from bsc.exe -format
should be discarded; in theory, they should have been duplicates of the errors from .compiler.log
.
In the future, we should consier showing the format errors when .compiler.log
isn't found.