* [Understanding QMK](understanding_qmk.md)
* Other Topics
- * [Using Eclipse with QMK](eclipse.md)
+ * [Using Eclipse with QMK](other_eclipse.md)
+ * [Using VSCode with QMK](other_vscode.md)
* [Support](support.md)
* QMK Internals (In Progress)
+++ /dev/null
-# Setting up Eclipse for QMK Development
-
-[Eclipse][1] is an open-source [Integrated Development Environment](https://en.wikipedia.org/wiki/Integrated_development_environment) (IDE) widely used for Java development, but with an extensible plugin system that allows to customize it for other languages and usages.
-
-Using an IDE such as Eclipse provides many advantages over a plain text editor, such as:
-* intelligent code completion
-* convenient navigation in the code
-* refactoring tools
-* build automation (no need for the command-line)
-* a GUI for GIT
-* static code analysis
-* many other tools such as debugging, code formatting, showing call hierarchies etc.
-
-The purpose of the is page is to document how to set-up Eclipse for developing AVR software, and working on the QMK code base.
-
-Note that this set-up has been tested on Ubuntu 16.04 only for the moment.
-
-# Prerequisites
-## Build Environment
-Before starting, you must have followed the [Getting Started](README.md#getting-started) section corresponding to your system. In particular, you must have been able to build the firmware with [the `make` command](../#the-make-command).
-
-## Java
-Eclipse is a Java application, so you will need to install Java 8 or more recent to be able to run it. You may choose between the JRE or the JDK, the latter being useful if you intend to do Java development.
-
-# Install Eclipse and Its Plugins
-Eclipse comes in [several flavours](http://www.eclipse.org/downloads/eclipse-packages/) depending on the target usage that you will have. There is no package comprising the AVR stack, so we will need to start from Eclipse CDT (C/C++ Development Tooling) and install the necessary plugins.
-
-## Download and Install Eclipse CDT
-If you already have Eclipse CDT on your system, you can skip this step. However it is advised to keep it up-to-date for better support.
-
-If you have another Eclipse package installed, it is normally possible to [install the CDT plugin over it](https://eclipse.org/cdt/downloads.php). However it is probably better to reinstall it from scratch to keep it light and avoid the clutter of tools that you don't need for the projects you will be working on.
-
-Installation is very simple: follow the [5 Steps to Install Eclipse](https://eclipse.org/downloads/eclipse-packages/?show_instructions=TRUE), and choose **Eclipse IDE for C/C++ Developers** at Step 3.
-
-Alternatively, you can also directly [download Eclipse IDE for C/C++ Developers](http://www.eclipse.org/downloads/eclipse-packages/) ([direct link to current version](http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/neonr)) and extract the package to the location of your choice (this creates an `eclipse` folder).
-
-## First Launch
-When installation is complete, click the <kbd>Launch</kbd> button. (If you extracted the package manually, open the Eclipse installation folder and double-click the `eclipse` executable)
-
-When you are prompted with the Workspace Selector, select a directory that will hold Eclipse metadata and usually your projects. **Do not select the `qmk_firmware` directory**, this will be the project directory. Select the parent folder instead, or another (preferably empty) folder of your choice (the default is fine if you do not use it yet).
-
-Once started, click the <kbd>Workbench</kbd> button at the top right to switch to the workbench view (there is a also checkbox at the bottom to skip the welcome screen at startup).
-
-## Install the Necessary Plugins
-Note: you do not need to restart Eclipse after installing each plugin. Simply restart once all plugins are installed.
-
-### [The AVR Plugin](http://avr-eclipse.sourceforge.net/)
-This is the most important plugin as it will allow Eclipse to _understand_ AVR C code. Follow [the instructions for using the update site](http://avr-eclipse.sourceforge.net/wiki/index.php/Plugin_Download#Update_Site), and agree with the security warning for unsigned content.
-
-### [ANSI Escape in Console](https://marketplace.eclipse.org/content/ansi-escape-console)
-This plugin is necessary to properly display the colored build output generated by the QMK makefile.
-
-1. Open <kbd><kbd>Help</kbd> > <kbd>Eclipse Marketplace…</kbd></kbd>
-2. Search for _ANSI Escape in Console_
-3. Click the <samp>Install</samp> button of the plugin
-4. Follow the instructions and agree again with the security warning for unsigned content.
-
-Once both plugins are installed, restart Eclipse as prompted.
-
-# Configure Eclipse for QMK
-## Importing the Project
-1. Click <kbd><kbd>File</kbd> > <kbd>New</kbd> > <kbd>Makefile Project with Existing Code</kbd></kbd>
-2. On the next screen:
- * Select the directory where you cloned the repository as _Existing Code Location_;
- * (Optional) Give a different name to the project¹, e.g. _QMK_ or _Quantum_;
- * Select the _AVR-GCC Toolchain_;
- * Keep the rest as-is and click <kbd>Finish</kbd>
-
- 
-
-3. The project will now be loaded and indexed. Its files can be browsed easily through the _Project Explorer_ on the left.
-
-¹ There might be issues for importing the project with a custom name. If it does not work properly, try leaving the default project name (i.e. the name of the directory, probably `qmk_firmware`).
-
-## Build Your Keyboard
-We will now configure a make target that cleans the project and builds the keymap of your choice.
-
-1. On the right side of the screen, select the <kbd>Make Target</kbd> tab
-2. Expand the folder structure to the keyboard of your choice, e.g. `qmk_firmware/keyboards/ergodox`
-3. Right-click on the keyboard folder and select <kbd>New…</kbd> (or select the folder and click the <kbd>New Make Target</kbd> icon above the tree)
-4. Choose a name for your build target, e.g. _clean \<your keymap\>_
-5. Make Target: this is the arguments that you give to `make` when building from the command line. If your target name does not match these arguments, uncheck <kbd>Same as target name</kbd> and input the correct arguments, e.g. `clean <your keymap>`
-6. Leave the other options checked and click <kbd>OK</kbd>. Your make target will now appear under the selected keyboard.
-7. (Optional) Toggle the <kbd>Hide Empty Folders</kbd> icon button above the targets tree to only show your build target.
-8. Double-click the build target you created to trigger a build.
-9. Select the <kbd>Console</kbd> view at the bottom to view the running build.
-
- [1]: https://en.wikipedia.org/wiki/Eclipse_(software)
\ No newline at end of file
--- /dev/null
+# Setting up Eclipse for QMK Development
+
+[Eclipse][1] is an open-source [Integrated Development Environment](https://en.wikipedia.org/wiki/Integrated_development_environment) (IDE) widely used for Java development, but with an extensible plugin system that allows to customize it for other languages and usages.
+
+Using an IDE such as Eclipse provides many advantages over a plain text editor, such as:
+* intelligent code completion
+* convenient navigation in the code
+* refactoring tools
+* build automation (no need for the command-line)
+* a GUI for GIT
+* static code analysis
+* many other tools such as debugging, code formatting, showing call hierarchies etc.
+
+The purpose of the is page is to document how to set-up Eclipse for developing AVR software, and working on the QMK code base.
+
+Note that this set-up has been tested on Ubuntu 16.04 only for the moment.
+
+# Prerequisites
+## Build Environment
+Before starting, you must have followed the [Getting Started](README.md#getting-started) section corresponding to your system. In particular, you must have been able to build the firmware with [the `make` command](../#the-make-command).
+
+## Java
+Eclipse is a Java application, so you will need to install Java 8 or more recent to be able to run it. You may choose between the JRE or the JDK, the latter being useful if you intend to do Java development.
+
+# Install Eclipse and Its Plugins
+Eclipse comes in [several flavours](http://www.eclipse.org/downloads/eclipse-packages/) depending on the target usage that you will have. There is no package comprising the AVR stack, so we will need to start from Eclipse CDT (C/C++ Development Tooling) and install the necessary plugins.
+
+## Download and Install Eclipse CDT
+If you already have Eclipse CDT on your system, you can skip this step. However it is advised to keep it up-to-date for better support.
+
+If you have another Eclipse package installed, it is normally possible to [install the CDT plugin over it](https://eclipse.org/cdt/downloads.php). However it is probably better to reinstall it from scratch to keep it light and avoid the clutter of tools that you don't need for the projects you will be working on.
+
+Installation is very simple: follow the [5 Steps to Install Eclipse](https://eclipse.org/downloads/eclipse-packages/?show_instructions=TRUE), and choose **Eclipse IDE for C/C++ Developers** at Step 3.
+
+Alternatively, you can also directly [download Eclipse IDE for C/C++ Developers](http://www.eclipse.org/downloads/eclipse-packages/) ([direct link to current version](http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/neonr)) and extract the package to the location of your choice (this creates an `eclipse` folder).
+
+## First Launch
+When installation is complete, click the <kbd>Launch</kbd> button. (If you extracted the package manually, open the Eclipse installation folder and double-click the `eclipse` executable)
+
+When you are prompted with the Workspace Selector, select a directory that will hold Eclipse metadata and usually your projects. **Do not select the `qmk_firmware` directory**, this will be the project directory. Select the parent folder instead, or another (preferably empty) folder of your choice (the default is fine if you do not use it yet).
+
+Once started, click the <kbd>Workbench</kbd> button at the top right to switch to the workbench view (there is a also checkbox at the bottom to skip the welcome screen at startup).
+
+## Install the Necessary Plugins
+Note: you do not need to restart Eclipse after installing each plugin. Simply restart once all plugins are installed.
+
+### [The AVR Plugin](http://avr-eclipse.sourceforge.net/)
+This is the most important plugin as it will allow Eclipse to _understand_ AVR C code. Follow [the instructions for using the update site](http://avr-eclipse.sourceforge.net/wiki/index.php/Plugin_Download#Update_Site), and agree with the security warning for unsigned content.
+
+### [ANSI Escape in Console](https://marketplace.eclipse.org/content/ansi-escape-console)
+This plugin is necessary to properly display the colored build output generated by the QMK makefile.
+
+1. Open <kbd><kbd>Help</kbd> > <kbd>Eclipse Marketplace…</kbd></kbd>
+2. Search for _ANSI Escape in Console_
+3. Click the <samp>Install</samp> button of the plugin
+4. Follow the instructions and agree again with the security warning for unsigned content.
+
+Once both plugins are installed, restart Eclipse as prompted.
+
+# Configure Eclipse for QMK
+## Importing the Project
+1. Click <kbd><kbd>File</kbd> > <kbd>New</kbd> > <kbd>Makefile Project with Existing Code</kbd></kbd>
+2. On the next screen:
+ * Select the directory where you cloned the repository as _Existing Code Location_;
+ * (Optional) Give a different name to the project¹, e.g. _QMK_ or _Quantum_;
+ * Select the _AVR-GCC Toolchain_;
+ * Keep the rest as-is and click <kbd>Finish</kbd>
+
+ 
+
+3. The project will now be loaded and indexed. Its files can be browsed easily through the _Project Explorer_ on the left.
+
+¹ There might be issues for importing the project with a custom name. If it does not work properly, try leaving the default project name (i.e. the name of the directory, probably `qmk_firmware`).
+
+## Build Your Keyboard
+We will now configure a make target that cleans the project and builds the keymap of your choice.
+
+1. On the right side of the screen, select the <kbd>Make Target</kbd> tab
+2. Expand the folder structure to the keyboard of your choice, e.g. `qmk_firmware/keyboards/ergodox`
+3. Right-click on the keyboard folder and select <kbd>New…</kbd> (or select the folder and click the <kbd>New Make Target</kbd> icon above the tree)
+4. Choose a name for your build target, e.g. _clean \<your keymap\>_
+5. Make Target: this is the arguments that you give to `make` when building from the command line. If your target name does not match these arguments, uncheck <kbd>Same as target name</kbd> and input the correct arguments, e.g. `clean <your keymap>`
+6. Leave the other options checked and click <kbd>OK</kbd>. Your make target will now appear under the selected keyboard.
+7. (Optional) Toggle the <kbd>Hide Empty Folders</kbd> icon button above the targets tree to only show your build target.
+8. Double-click the build target you created to trigger a build.
+9. Select the <kbd>Console</kbd> view at the bottom to view the running build.
+
+ [1]: https://en.wikipedia.org/wiki/Eclipse_(software)
\ No newline at end of file
--- /dev/null
+# Setting up Visual Studio Code for QMK Development
+
+[Visual Studio Code](https://code.visualstudio.com/) (VS Code) is an open-source code editor that supports many different programming languages.
+
+Using a full-featured editor such as VS Code provides many advantages over a plain text editor, such as:
+* intelligent code completion
+* convenient navigation in the code
+* refactoring tools
+* build automation (no need for the command-line)
+* a graphical front end for GIT
+* many other tools such as debugging, code formatting, showing call hierarchies etc.
+
+The purpose of this page is to document how to set up VS Code for developing QMK Firmware.
+
+This guide covers how to configure everything needed on Windows and Ubuntu 18.04
+
+# Set up VS Code
+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.
+
+## Windows
+
+### Prerequisites
+
+* [Git for Windows](https://git-scm.com/download/win) (This link will prompt to save/run the installer)
+
+ 1. Disable all of the options but `Git LFS (Large File Support)` and `Check daily for Git for Windows updates`.
+ 2. Set the default editor to `Use Visual Studio Code as Git's default editor`
+ 3. Select the `Use Git from Git Bash only` option, since that's the option that you should use here.
+ 4. For the `Choosing HTTPS transport backend`, either option should be fine.
+ 5. Select the `Checkout as-is, commit Unix-style line endings` option. QMK Firmware uses Unix style commits.
+ 6. For the extra options, leave the default options as is.
+
+ 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.
+
+* [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases) (Optional)
+
+ This software provides better support for Git by providing secure storage for git credentials, MFA and personal access token generation.
+
+ This isn't strictly needed, but we would recommend it.
+
+
+### Installing VS Code
+
+1. Head to [VS Code](https://code.visualstudio.com/) and download the installer
+2. Run the installer
+
+This part is super simple. However, there is some configuration that we need to do to ensure things are configured correctly.
+
+### Configuring VS Code
+
+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.
+
+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.
+
+Once you have saved this file, you will need to reload VS Code, if it was already running.
+
+?> You should see an `extensions.json` and `settings.json` file in the `.vscode` folder, as well.
+
+
+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.
+
+1. Click <kbd><kbd>File</kbd> > <kbd>Preferences ></kbd> > <kbd>Settings</kbd> </kbd>
+2. Click on the <kbd>{}</kbd> button, in the top right to open the `settings.json` file.
+3. Set the file's content to:
+
+ ```json
+ {
+ "terminal.integrated.shell.windows": "C:\\msys64\\usr\\bin\\bash.exe",
+ "terminal.integrated.env.windows": {
+ "MSYSTEM": "MINGW64",
+ "CHERE_INVOKING": "1"
+ },
+ "terminal.integrated.shellArgs.windows": [
+ "--login"
+ ],
+ "terminal.integrated.cursorStyle": "line"
+ }
+ ```
+
+ If there are settings here already, then just add everything between the first and last curly brackets.
+
+?> 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.
+
+4. Hit Ctrl-` (grave) to bring up the terminal.
+
+ This should start the terminal in the workspace's folder (so the `qmk_firmware` folder), and then you can compile your keyboard.
+
+
+## Every other Operating System
+
+1. Head to [VS Code](https://code.visualstudio.com/) and download the installer
+2. Run the installer
+3. That's it
+
+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.
+
+## Plugins
+
+There are a number of extensions that you may want to install:
+
+* [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.
+* [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) - _[Optional]_ - Helps to keep the code to the QMK Coding Conventions.
+* [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.
+* [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.
+* [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.
+* [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.
+* [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.
+
+Restart once you've installed any extensions
+
+# Configure VS Code for QMK
+1. Click <kbd><kbd>File</kbd> > <kbd>Open Folder</kbd></kbd>
+2. Open the QMK Firmware folder that you cloned from GitHub.
+3. Click <kbd><kbd>File</kbd> > <kbd>Save Workspace As...</kbd></kbd>
+
+And now you're ready to code QMK Firmware in VS Code
projects / qmk_firmware.git / commitdiff