Merge pull request #177 from lf-lang/sdo/contributingAndDebugging

Updated contributing guide to include the debugging workflow.

CONTRIBUTING.md

@@ -14,9 +14,9 @@ from the VSCode marketplace. See
 To check out the repository, build from source, and install the VS Code plugin, make sure you have the following dependencies:
 
 - `rust`. Rust versions preceding 1.76.0 are not guaranteed to work. See [this web page](https://www.rust-lang.org/tools/install) for instructions on installing Rust.
-- `npm`. `npm` versions preceding 10.4.0 are not guaranteed to work.
+- `npm`. `npm` versions preceding 10.4.0 are not guaranteed to work. We are currently using npm v18.17.0.
 
-Then, run the following command:
+Then, run the following command to install the required NPM packages:
 
 ```
 git clone --recurse-submodules [email protected]:lf-lang/vscode-lingua-franca.git \
@@ -32,6 +32,10 @@ git clone --recurse-submodules https://github.com/lf-lang/vscode-lingua-franca.g
 && npm install
 ```
 
+Install the VS Code extension by calling `npm run install-extension`.
+If you want to debug the extension with the language server bundled in a jar see [here](#suggested-debugging-workflow).
+If you want to debug the extension together with the language server see [below](#debugging-interactions-between-the-language-server-and-vs-code).
+
 ### Trouble Shooting
 
 #### VS Code is not detected on Mac OS X
@@ -111,4 +115,8 @@ We suggest the following workflow for debugging the language server (implemented
 
 ## Debugging interactions between the language server and VS Code
 
-To debug interactions between the language server and VS code, start the language server using the VM option `-Dport=7670`. This can be done in IntelliJ by opening `Modify run configuration` > `Add VM options` and typing `-Dport=7670` into the VM options field. Then start the extension using the "Launch VS Code Extension (Socket) LF" launch configuration. This allows to set breakpoints in the language server as it interacts with VS Code.
+1. Run the command `npm run compile` to generate JavaScript together with a source map (in the `out` directory). The source map is necessary for breakpoints to work. You can also use `npm run watch` if you expect to change the VS Code extension code quite often as part of your development.
+2. Start the language server as detailed [here](https://www.lf-lang.org/docs/next/developer/developer-intellij-setup/#starting-and-debugging-the-language-server) with VM option `-Dport=7670` (this is the default behavior).
+3. Go to the `Run and Debug` view and select the `"Launch VS Code Extension (Socket) LF` launch configuration and run it. If you need to update the launch configuration, you can find it in `.vscode/launch.config`. Here the launch configuration also defines the port the extension and the server will connect.
+4. A new VS Code instance will open with the locally build Lingua Franca VS Code extension installed. Once a `.lf` files is opened, the language server will connect and you can debug normally.
+5. All TypeScript files that are not directly started by the `extension.ts` everything in a webview, e.g. the diagram or other webviews cannot be debugged by setting breakpoints in the development VS Code. You have to do that in the development tools of your runtime VS Code.

package.json

@@ -197,7 +197,7 @@
         "package": "move-cli lingua-franca ../temp-lingua-franca89539275 && (vsce package; move-cli ../temp-lingua-franca89539275 lingua-franca)",
         "package-pre-release": "move-cli lingua-franca ../temp-lingua-franca89539275 && (vsce package --pre-release; move-cli ../temp-lingua-franca89539275 lingua-franca)",
         "deploy": "echo \"Y\r\n\" | code --install-extension vscode-lingua-franca-*.vsix --force",
-        "install": "npm run clean && npm run build && npm run package && npm run deploy",
+        "install-extension": "npm run clean && npm run build && npm run package && npm run deploy",
         "test": "npm run compile-tests && node ./out/test/test/test_runner.js --dependencies=present",
         "test-dependencies-outdated": "bash -c \"if [ -z ${LF_VS_CODE_ALLOW_GLOBAL_UNINSTALLS+x} ]; then echo 'If you are sure that you want to run a test which may uninstall binaries from your machine, set the environment variable LF_VS_CODE_ALLOW_GLOBAL_UNINSTALLS' ; else false; fi\" || npm run compile-tests && rustup default 1.26.0 && node ./out/test/test/test_runner.js --dependencies=outdated;",
         "test-dependencies-missing-basic": "bash -c \"if [ -z ${LF_VS_CODE_ALLOW_GLOBAL_UNINSTALLS+x} ]; then echo 'If you are sure that you want to run a test which may uninstall binaries from your machine, set the environment variable LF_VS_CODE_ALLOW_GLOBAL_UNINSTALLS' ; else false; fi\" || npm run compile-tests && (move-cli $INIT_CWD/../../../.cargo $INIT_CWD/../../../.cargo.bak || move-cli C:\\Users\\runneradmin\\.cargo C:\\Users\\runneradmin\\.cargo.bak) && node ./out/test/test/test_runner.js --dependencies=missing0",