other_vscode.md (11135B)
1 # Setting up Visual Studio Code for QMK Development 2 3 [Visual Studio Code](https://code.visualstudio.com/) (VS Code) is an open-source code editor that supports many different programming languages. 4 5 Using a full-featured editor such as VS Code provides many advantages over a plain text editor, such as: 6 * intelligent code completion 7 * convenient navigation in the code 8 * refactoring tools 9 * build automation (no need for the command-line) 10 * a graphical front end for GIT 11 * many other tools such as debugging, code formatting, showing call hierarchies etc. 12 13 The purpose of this page is to document how to set up VS Code for developing QMK Firmware. 14 15 This guide covers how to configure everything needed on Windows and Ubuntu 18.04 16 17 # Set up VS Code 18 Before starting, you will want to make sure that you have all of the build tools set up, and QMK Firmware cloned. Head to the [Newbs Getting Started Guide](newbs_getting_started) to get things set up, if you haven't already. 19 20 ## Windows 21 22 ### Prerequisites 23 24 * [Git for Windows](https://git-scm.com/download/win) (This link will prompt to save/run the installer) 25 26 1. Disable all of the options but `Git LFS (Large File Support)` and `Check daily for Git for Windows updates`. 27 2. Set the default editor to `Use Visual Studio Code as Git's default editor` 28 3. Select the `Use Git from Git Bash only` option, since that's the option that you should use here. 29 4. For the `Choosing HTTPS transport backend`, either option should be fine. 30 5. Select the `Checkout as-is, commit Unix-style line endings` option. QMK Firmware uses Unix style commits. 31 6. For the extra options, leave the default options as is. 32 33 This software is needed for Git support in VS Code. It may be possible to not include this, but it is much simpler to just use this. 34 35 * [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases) (Optional) 36 37 This software provides better support for Git by providing secure storage for git credentials, MFA and personal access token generation. 38 39 This isn't strictly needed, but we would recommend it. 40 41 42 ### Installing VS Code 43 44 1. Head to [VS Code](https://code.visualstudio.com/) and download the installer 45 2. Run the installer 46 47 This part is super simple. However, there is some configuration that we need to do to ensure things are configured correctly. 48 49 #### MSYS2 Setup 50 51 Now, we will set up the MSYS2 window to show up in VSCode as the integrated terminal. This has a number of advantages. Mostly, you can control+click on errors and jump to those files. This makes debugging much easier. It's also nice, in that you don't have to jump to another window. 52 53 1. Click <kbd><kbd>File</kbd> > <kbd>Preferences ></kbd> > <kbd>Settings</kbd> </kbd> 54 2. Click on the <kbd>{}</kbd> button, in the top right to open the `settings.json` file. 55 3. Set the file's content to: 56 57 ```json 58 { 59 "terminal.integrated.profiles.windows": { 60 "QMK_MSYS": { 61 "path": "C:/QMK_MSYS/usr/bin/bash.exe", 62 "env": { 63 "MSYSTEM": "MINGW64", 64 "CHERE_INVOKING": "1" 65 }, 66 "args": ["--login"] 67 } 68 }, 69 70 "terminal.integrated.cursorStyle": "line" 71 } 72 ``` 73 74 If there are settings here already, then just add everything between the first and last curly brackets and separate the existing settings with a comma from the newly added ones. 75 76 ::: tip 77 If you installed MSYS2 to a different folder, then you'll need to change the path for `terminal.integrated.shell.windows` to the correct path for your system. 78 ::: 79 80 4. Hit Ctrl-<code>`</code> (Grave) to bring up the terminal or go to <kbd><kbd>View</kbd> > <kbd>Terminal</kbd></kbd> (command `workbench.action.terminal.toggleTerminal`). A new terminal will be opened if there isn‘t one already. 81 82 This should start the terminal in the workspace's folder (so the `qmk_firmware` folder), and then you can compile your keyboard. 83 84 85 ## Every other Operating System 86 87 1. Head to [VS Code](https://code.visualstudio.com/) and download the installer 88 2. Run the installer 89 3. That's it 90 91 No, really, that's it. The paths needed are already included when installing the packages, and it is much better about detecting the current workspace files and parsing them for IntelliSense. 92 93 ## Extensions 94 95 There are a number of extensions that you may want to install: 96 97 * [Git Extension Pack](https://marketplace.visualstudio.com/items?itemName=donjayamanne.git-extension-pack) - This installs a bunch of Git related tools that may make using Git with QMK Firmware easier. 98 * [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) - _[Optional]_ - This is the language server for C/C++ that VS Code uses. It provides IntelliSense and other features. 99 * [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) - _[Optional]_ - Helps to keep the code to the QMK Coding Conventions. 100 * [GitHub Markdown Preview](https://marketplace.visualstudio.com/items?itemName=bierner.github-markdown-preview) - _[Optional]_ - Makes the markdown preview in VS Code more like GitHub's. 101 * [VS Live Share Extension Pack](https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare) - _[Optional]_ - This extension allows somebody else to access your workspace (or you to access somebody else's workspace) and help out. This is great if you're having issues and need some help from somebody. 102 103 Restart once you've installed any extensions. 104 105 # Configure VS Code for QMK 106 107 1. Click <kbd><kbd>File</kbd> > <kbd>Open Folder</kbd></kbd> 108 2. Open the QMK Firmware folder that you cloned from GitHub. 109 3. Click <kbd><kbd>File</kbd> > <kbd>Save Workspace As...</kbd></kbd> 110 111 ## Configuring VS Code 112 113 Using the [standard `compile_commands.json` database](https://clang.llvm.org/docs/JSONCompilationDatabase.html), we can get the VS code _clangd_ extension to use the correct includes and defines used for your keyboard and keymap. 114 115 1. Run `qmk compile -kb <keyboard> -km <keymap> --compiledb` to generate the `compile_commands.json`. 116 1. Inside VS code, press <kbd><kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd></kbd> (macOS: <kbd><kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd></kbd>) to open the command palette. 117 1. Start typing `clangd: Download Language Server` and select it when it appears. Note that this only needs to be done once on clangd extension installation, if it didn't already ask to do so. 118 1. Inside VS code, press <kbd><kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd></kbd> (macOS: <kbd><kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd></kbd>) to open the command palette. 119 1. Start typing `clangd: Restart Language Server` and select it when it appears. 120 121 Now you're ready to code QMK Firmware in VS Code! 122 123 # Debugging ARM MCUs with Visual Studio Code 124 125 **...and a Black Magic Probe.** 126 127 Visual Studio Code has the ability to debug applications, but requires some configuration in order to get it to be able to do so for ARM targets. 128 129 This documentation describes a known-working configuration for setting up the use of a Black Magic Probe to debug using VS Code. 130 131 It is assumed that you've correctly set up the electrical connectivity of the Black Magic Probe with your MCU. Wiring up `NRST`, `SWDIO`, `SWCLK`, and `GND` should be enough. 132 133 Install the following plugin into VS Code: 134 135 * [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) - 136 This adds debugger support for ARM Cortex targets to VS Code. 137 138 A debugging target for the MCU for your board needs to be defined, and can be done so by adding the following to a `.vscode/launch.json` file: 139 140 ```json 141 { 142 // Use IntelliSense to learn about possible attributes. 143 // Hover to view descriptions of existing attributes. 144 // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 145 "version": "0.2.0", 146 "configurations": [ 147 { 148 "name": "Black Magic Probe (OneKey Proton-C)", 149 "type": "cortex-debug", 150 "request": "launch", 151 "cwd": "${workspaceRoot}", 152 "executable": "${workspaceRoot}/.build/handwired_onekey_proton_c_default.elf", 153 "servertype": "bmp", 154 "BMPGDBSerialPort": "COM4", 155 "svdFile": "Q:\\svd\\STM32F303.svd", 156 "device": "STM32F303", 157 "v1": false, 158 "windows": { 159 "armToolchainPath": "C:\\QMK_MSYS\\mingw64\\bin" 160 } 161 } 162 ] 163 } 164 ``` 165 166 You'll need to perform some modifications to the file above in order to target your specific device: 167 168 * `"name"`: Can be anything, but if you're debugging multiple targets you'll want something descriptive here. 169 * `"cwd"`: The path to the QMK Firmware repository root directory -- _if using the `.vscode` directory existing in the `qmk_firmware` git repository, the default above should be correct_ 170 * `"executable"`: The path to the `elf` file generated as part of the build for your keyboard -- _exists in `<qmk_firmware>/.build`_ 171 * `"BMPGDBSerialPort"`: The `COM` port under Windows, or the `/dev/...` path for Linux/macOS. Two serial port devices will be created -- the Black Magic Probe debug port is *usually* the first. If it doesn't work, try the second. 172 * `"svdFile"`: _[Optional]_ The path to the SVD file that defines the register layout for the MCU -- the appropriate file can be downloaded from the [cmsis-svd repository](https://github.com/posborne/cmsis-svd/tree/master/data/STMicro) 173 * `"device"`: The name of the MCU, which matches the `<name>` tag at the top of the downloaded `svd` file. 174 * `"armToolchainPath"`: _[Optional]_ The path to the ARM toolchain installation location on Windows -- under normal circumstances Linux/macOS will auto-detect this correctly and will not need to be specified. 175 176 ::: warning 177 Windows builds of QMK Firmware are generally compiled using QMK MSYS, and the path to gdb's location (`C:\\QMK_MSYS\\mingw64\\bin`) needs to be specified under `armToolchainPath` for it to be detected. You may also need to change the GDB path to point at `C:\\QMK_MSYS\\mingw64\\bin\\gdb-multiarch.exe` in the VSCode Cortex-Debug user settings:  178 ::: 179 180 The following modifications must be made to the keyboard's `rules.mk` file to enable debug information and disable optimisations -- this will ensure breakpoints and variable viewing works correctly: 181 ```makefile 182 # Enable debug information in the final binaries 183 DEBUG_ENABLE = yes 184 # Disable optimisations for debugging purposes 185 LTO_ENABLE = no 186 OPT = g 187 ``` 188 189 At this point, you should build and flash your firmware through normal methods (`qmk compile ...` and `qmk flash ...`). 190 191 Once completed, you can: 192 * Switch to the debug view in VS Code (in the sidebar, the Play button with a bug next to it) 193 * Select the newly-created debug target in the dropdown at the top of the sidebar 194 * Click the green play button next to the dropdown 195 196 VS Code's debugger will then start executing the compiled firmware on the MCU. 197 198 At this stage, you should have full debugging set up, with breakpoints and variable listings working!