docs/other_vscode.md

   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 the [Newbs Getting Started Guide](newbs_getting_started.md) 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 ### Configuring VS Code
  50
  51 First, we need to set up IntelliSense. This isn't strictly required, but it will make your life a LOT easier. To do this, we need to create the `.vscode/c_cpp_properies.json` file in the QMK Firmware folder, You can do this all manually, but I've done most of the work already.
  52
  53 Grab [this file](https://gist.github.com/drashna/48e2c49ce877be592a1650f91f8473e8) and save it.  You may need to edit this file, if you didn't install MSYS2 to the default location, or are using WSL/LxSS.
  54
  55 Once you have saved this file, you will need to reload VS Code, if it was already running.
  56
  57 ?> You should see an `extensions.json` and `settings.json` file in the `.vscode` folder, as well.
  58
  59
  60 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.
  61
  62 1. Click <kbd><kbd>File</kbd> > <kbd>Preferences ></kbd> > <kbd>Settings</kbd> </kbd>
  63 2. Click on the <kbd>{}</kbd> button, in the top right to open the `settings.json` file.
  64 3. Set the file's content to:
  65
  66    ```json
  67    {
  68         "terminal.integrated.shell.windows": "C:\\msys64\\usr\\bin\\bash.exe",
  69         "terminal.integrated.env.windows": {
  70             "MSYSTEM": "MINGW64",
  71             "CHERE_INVOKING": "1"
  72         },
  73         "terminal.integrated.shellArgs.windows": [
  74             "--login"
  75         ],
  76         "terminal.integrated.cursorStyle": "line"
  77     }
  78     ```
  79
  80    If there are settings here already, then just add everything between the first and last curly brackets.
  81
  82 ?> 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.
  83
  84 4. Hit Ctrl-` (grave) to bring up the terminal.
  85
  86    This should start the terminal in the workspace's folder (so the `qmk_firmware` folder), and then you can compile your keyboard.
  87
  88
  89 ## Every other Operating System
  90
  91 1. Head to [VS Code](https://code.visualstudio.com/) and download the installer
  92 2. Run the installer
  93 3. That's it
  94
  95 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.
  96
  97 ## Plugins
  98
  99 There are a number of extensions that you may want to install:
 100
 101 * [Git Extension Pack](https://marketplace.visualstudio.com/items?itemName=donjayamanne.git-extension-pack) -
 102 This installs a bunch of Git related tools that may make using Git with QMK Firmware easier.
 103 * [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) - _[Optional]_ -  Helps to keep the code to the QMK Coding Conventions.
 104 * [Bracket Pair Colorizer 2](https://marketplace.visualstudio.com/items?itemName=CoenraadS.bracket-pair-colorizer-2) - _[Optional]_ - This color codes the brackets in your code, to make it easier to reference nested code.
 105 * [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.
 106 * [VS Live Share Extension Pack](https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare-pack) - _[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.
 107 * [VIM Keymap](https://marketplace.visualstudio.com/items?itemName=GiuseppeCesarano.vim-keymap) - _[Optional]_ - For those that prefer VIM style keybindings. There are other options for this, too.
 108 * [Travis CI Status](https://marketplace.visualstudio.com/items?itemName=felixrieseberg.vsc-travis-ci-status) - _[Optional]_ - This shows the current Travis CI status, if you have it set up.
 109
 110 Restart once you've installed any extensions
 111
 112 # Configure VS Code for QMK
 113 1. Click <kbd><kbd>File</kbd> > <kbd>Open Folder</kbd></kbd>
 114 2. Open the QMK Firmware folder that you cloned from GitHub.
 115 3. Click <kbd><kbd>File</kbd> > <kbd>Save Workspace As...</kbd></kbd>
 116
 117 And now you're ready to code QMK Firmware in VS Code