VSCode Setup

Setup of VS Code

NOTE: This is a draft, for an unsupported branch that’s not fully tested and released yet.

Aside: Why VSCode

Microsoft’s Visual Studio Code (VSCode for short), not to be confused with Microsoft’s older (and still maintained) Visual Studio, is a complete language-agnostic Integrated Development Environment (IDE) that is cross-platform (Mac, Windows, and Linux), free, open-source, and extensible.

Compared to other IDEs, VSCode had the best mix of capabilities for our unique set of requirements for the g2core project. We needed it first and foremost to support bare-metal embedded code-editing, compiling, and debugging. We also had a strong desire for it to be cross-platform to support development without needing a Windows VM on Macs or on Linux-based computers. VSCode gets extra points for having great support for Windows Subsystem for Linux (WSL) to ease development on Windows without having to maintain a separate set of configurations for Windows.

References

• VSCode Download Page
• VSCode C++ Extension Documentation
• VSCode C++ FAQ

TODO

• Document Window differences
• Document Linux differences

Precursor Steps

These instructions assume you have already cloned the g2 repo locally using another means. The g2 repo should contain the g2core subdirectory, and a Motate subdirectory, among other things.

Github has advanced token management that may be helpful.

Installation

1. Install VSCode
   • See their setup documentation
   • If you’re new to VSCode, then their introductory videos may be of interest.
2. Follow the setup instructions for your platform: Mac, Linux, Windows
   • Note, for Windows we recommend using the Windows Subsystem for Linux (WSL) to get the development tools
3. Open VSCode, and then open the g2core repo
4. Install the recommended extensions (left hand nav bar "blocky" symbol - see documentation)
   • VSCode Extension usage documentation
   • Note that you can optionally open the Extensions sidebar and browse the extensions that are currently active. You can safely disable any unused extensions for this workspace to speed up VSCode when working in g2core. Any extensions not related to C++, “Cortex-Debug,” Git, Github, WSL (on Windows), or IntelliCode can safely be disabled for this workspace.

Usage Note: Unlike other IDEs which use most of the screen real-estate for buttons, each for a single task, VSCode (much like Atom) uses the type-to-find-commands approach, and they call it the Command Palette (<COMMAND><SHIFT>p).

Some functionality can only be found via the Command Palette, so it’s important to learn how to use it. Note that all of the functions found there either already have keyboard shortcuts (shown in the list when you search) or can be assigned keyboard shortcuts (note you can assign individual tasks their own shortcuts as well).

Also note: As a general rule we try not to add keyboard shortcut configuration to the committed configuration files in the repo, as it may conflict with personal preferences or setup for other projects.

Also needed

You will need the following command line tools to be installed for compiling:

• git . Install GitHub Desktop: https://desktop.github.com or https://git-scm.com/download
• node . Install the LTS version: https://nodejs.org/en/
• Others? TBD
• J-Link Software and Documentation Pack for flashing and debugging

Hardware needed

• A J-Link hardware debugger
  • Adafruit sells two options which are much more reasonably priced for hobbiest uses:
    • J-Link EDU, you’ll also need an adapter and a cable
    • J-Link EDU Mini, you may also want to grab an extra cable, but the Mini comes with one
• A compatible g2core device, of course 😉

Building

TODO

Notes:

• The workspace already has Tasks configured for building and cleaning the repo for various targets.

Here are some step-by-step instructions to use this (which will probably require edits)

• Open a terminal window using Terminal / Open Terminal
• Ensure Motate is up to date: git submodule update
• Type tasks in Command Palette

Briefly: Under the Terminal menu (or using the Command Palette) choose Run Build Task. (Note: The keyboard shortcut for your OS will be shown next to Run Build Task, note it for faster access in the future.)

Debugging

TODO

We have already configured Debugging for several targets, all using the J-Link tools. Follow the VSCode documentation (additional notes for C++ here), using one of those profiles.

Notes (To be incorporated above and then deleted)

Windows:

• Install gitHub Desktop
• Install git
  • See screenshots for specific configuration, use defaults for the rest
• Install VSCode
  • Install Recommended Extensions
    • May be warnings about things already installed and not being updated - safe to ignore
• Install WSL (https://docs.microsoft.com/en-us/windows/wsl/install-win10) and The in the Windows Store install Ubuntu

FAIL - WSL can build, but cannot debug, no access to USB.

• Note the command to enable WSL needs to run in a PowerShell running as Administrator. Search for PowerShell and click on “Run as Administrator” and then wave away all the various warnings about the dangers.
• In VScode, Connect to Ubuntu (Screen with network-like icon in the toolbar, it’ll open a new window most likely), or re-open a previous Ubuntu connection
• Open Cloned Repo from inside the Ubuntu-connected window (may be easier if it’s cloned inside Ubuntu)
  • The window will have “>< WSL: Ubuntu” in the bottom left corner
• In the shell, run sudo apt-get update -y && sudo apt-get install build-essential nodejs -y
• Install JLink
  • Download the latest .deb
  • sudo dpkg -i <path_to_deb> && sudo apt-get install libsm6 libxrandr-dev libxrender-dev libxfixes-dev libxcurson-dev -y

ENDFAIL