| 1 | # Sapling VS Code extension |
| 2 | |
| 3 | This folder contains the VS Code extension, |
| 4 | including the Sapling SCM provider and embedded ISL. |
| 5 | |
| 6 | > NOTE: This file acts as the technical `README` for the `vscode/` folder, |
| 7 | > while `README.md` is the user-facing description of the extension visible in the extension marketplace. |
| 8 | |
| 9 | The VS Code extension consists of two forms of JavaScript: |
| 10 | |
| 11 | - Extension code, running in the VS Code extension host process. |
| 12 | This code uses the VS Code API and acts like a node process. |
| 13 | - Webview code (of ISL), running in a VS Code webview. |
| 14 | This code cannot use the VS Code API, and acts like it's running in a browser. |
| 15 | |
| 16 | The two are built separately, and communicate via message passing. |
| 17 | Unlike web `sl` in `isl-server/proxy`, this does not use WebSockets |
| 18 | but rather VS Code's own message passing system (which still works across remote connections). |
| 19 | |
| 20 | ## Building & Running |
| 21 | |
| 22 | Build artifacts live in `./dist`. |
| 23 | |
| 24 | **Development** |
| 25 | |
| 26 | - `yarn watch-extension` to compile extension code |
| 27 | - `yarn watch-webview` to compile webview code |
| 28 | |
| 29 | **Production** |
| 30 | |
| 31 | - `yarn build-extension` to build production extension code |
| 32 | - `yarn build-webview` to build production webview code |
| 33 | |
| 34 | **Dogfooding** |
| 35 | |
| 36 | You can use a development build of the VS Code extension by symlinking into this folder, |
| 37 | since `package.json` points to `dist/`: |
| 38 | |
| 39 | ```sh |
| 40 | ln -s ./vscode ~/.vscode/extensions/meta.sapling-scm-100.0.0-dev |
| 41 | ``` |
| 42 | |
| 43 | **Debugging** |
| 44 | |
| 45 | VS Code webview source maps don't load automatically, since we produce separate `.js.map` files |
| 46 | instead of inline source maps. The VS Code webview resource system doesn't seem to load these correctly. |
| 47 | |
| 48 | To get source maps in the webview, you need to load them manually: |
| 49 | |
| 50 | 1. Open ISL in VS Code |
| 51 | 2. Open the developer tools from the Help menu |
| 52 | 3. Go to the "console" tab |
| 53 | 4. Change "top" to the "pending-frame" that corresponds to ISL |
| 54 | 5. Open `webview.js` in the "sources" tab (e.g. from a stack trace) |
| 55 | 6. Right-click on the file, choose "Add source map..." |
| 56 | 7. Enter the full URL to the `.map` file: `file:///path/to/addons/vscode/dist/webview/webview.js.map` |
| 57 | |
| 58 | Enjoy your proper stack traces, files, and breakpoints! :D |
| 59 | |