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