Welcome! So glad you've decided to help make Cursorless better. Once you've learned how to set up and run / test a local copy of the extension, you may want to check out the Cursorless API docs to learn more about how Cursorless works. You may also find the VSCode API docs helpful to learn about VSCode extension development.
Open the newly created
cursorlessdirectory in VSCode. If you're on Windows, don't use WSL (see #919 for discussion / workaround).
Run the following in the terminal:
yarn init-launch-sandboxcommand creates a local sandbox containing a specific set of VSCode extensions that will be run alongside Cursorless when you launch Cursorless in debug or test mode. Please file an issue if you'd like to use additional extensions when debugging locally.
Running / testing extension locally
In order to test out your local version of the extension or to run unit tests
locally, you need to run the extension in debug mode. To do so you need to run
workbench.action.debug.selectandstart command in VSCode and then select either "Run
Extension" or "Extension Tests".
Running a subset of tests
The entire test suite takes a little while to run (1-2 mins), so if you'd like to run just a subset of the tests, you can edit the constant in
runTestSubset to a string supported by mocha grep and use the "Run Test Subset" launch config instead of the usual "Extension Tests".
pre-commit to automate autoformatting.
Autoformatters will automatically run on PRs in CI, but you can also run them
locally or install pre-commit hooks as described in the
Running docs site locally
workbench.action.debug.selectandstart command and then select
"Docusaurus Start (Debug)".
Parse tree support
Adding a new programming language
Adding syntactic scope types to an existing language
Testing Cursorless with a local version of the VSCode parse tree extension
First bundle the parse tree extension into a
.vsix, using something like the following:
vsce package -o bundle.vsix
Once you have your package then you can install it into the sandbox using the following command:
code --extensions-dir .vscode-sandbox/extensions --install-extension ../vscode-parse-tree/bundle.vsix
SVG preprocessing script
You'll probably want to run the following to make sure the SVGs have everything they need:
yarn run compile && node ./out/scripts/preprocessSvgHats.js
This script will add dummy width, height and fill attributes as necessary to appease the regex in
Adding hat adjustments at finish
While tweaking, the easiest approach is probably to use the
cursorless.individualHatAdjustments setting in your settings.json to change
size / alignment so you don't need to refresh every time. Once you're done, you
can paste the settings into
scripts/hatAdjustments/add.ts and run the following to get
yarn run compile && node ./out/scripts/hatAdjustments/add.js
If instead, you want to average your adjustments with those in main and see the differences to get to yours and main, you can paste the settings into
scripts/hatAdjustments/average.ts and run:
yarn run compile && node ./out/scripts/hatAdjustments/average.js