Skip to content

Latest commit

 

History

History
129 lines (99 loc) · 5.53 KB

VSCODE_DEVELOPMENT.md

File metadata and controls

129 lines (99 loc) · 5.53 KB
Raw

Visual Studio Code Development

Visual Studio Code is a great and simple IDE that can be used to build & develop with.

This repo supports the docker / remote container workflow in Visual Studio Code, and has a container environment setup automatically. You can read more about this workflow here.

Tested on:

  • macOS 13.2
  • Windows 10 Pro + WSL + Ubuntu 18 LTS
  • Linux - Fedora Core 35 distribution

Setup Steps

  1. Windows Only Enable the Windows Subsystem for Linux (WSL) following instructions here: https://docs.microsoft.com/en-us/windows/wsl/install-win10
  2. Windows Only Install Ubuntu from the Windows App Store here: https://www.microsoft.com/en-us/p/ubuntu-1804-lts/9n9tngvndl3q
  3. Install Docker for your operating system of choice from here: https://docs.docker.com/engine/install
  4. Install Visual Studio Code for your operating system of choice here: https://code.visualstudio.com/Download
  5. Install Git if you haven't already
  6. Windows Only Enable git to use LF instead of CLRF by default: git config --global core.autocrlf false
  7. Git clone the main repository here: https://github.com/O-H-M2/qmk_port_ch582
  8. Launch Visual Studio Code, and open the cloned folder from
  9. Install the Dev Containers extension for Visual Studio Code, this extension allows you to use docker containers as a development backend.
  10. Once this is installed, you'll be prompted to reload Visual Studio Code, do so
  11. At the bottom right of your Visual Studio Code window you should have a new box prompting you to re-open the window as a container. Hit yes.
  12. Windows Only Update your Visual Studio Code settings as documented here: https://code.visualstudio.com/docs/editor/integrated-terminal#_configuration to use Bash on Ubuntu (on Windows) eg: "terminal.integrated.shell.windows": "C:\\Windows\\System32\\bash.exe"
  13. Now your local machine is building a docker image that has all the tools necessary to build. This can take some time, but will eventually complete and open up the source tree

Tasks

Located in the tasks json file you'll find a list of tasks that can be run from the "Run Task..." command. Example task is "Fullclean".

Current base tasks are listed here

  • Fullclean - Remove build artifacts

Build

Wait for the Dev Container extension done setting your virtual environment, then check CMake configurations on status bar which you can find at the bottom of you GUI:

  • Check build type to Release
  • Check active kit to No active kit if you are using the WCH toolchain, or to the corresponding toolchain you have downloaded.
  • Press the Build button.

Firmwares will be generated to the root directory in the name of your keyboard. Choose xxx_upgrade.uf2 if you are the end user, xxx_factory.hex is for developers only.

Common Issues

Docker FAQ

DNS problem: can't resolve archive.ubuntu.com

A common problem encountered is that a container can't resolve archive.ubuntu.com and can't install anything via apt-get, during the creation of the container image, resulting in an error like:

E: Package 'locales' has no installation candidate
The command '/bin/sh -c apt-get install -y locales && localedef -i en_US -c -f UTF-8 -A /usr/share/locale/locale.alias en_US.UTF-8' returned a non-zero code: 100

Most common reason for this is that the DNS for docker daemon has not been set up correctly and is simply using a default: 8.8.8.8, which in many corporate or more secure environments is not accessible. A typical solution for this is to put a following key/value into your system-wide docker daemon.json (Typically located under /etc/docker/daemon.json on a Linux system):

"dns": ["<<IP ADDRESS OF YOUR NAMESERVER>>", "8.8.8.8"]

You can obtain the address you should put into that line of your nameserver by running:

nmcli dev show | grep 'IP4.DNS'

After you update the dns, you should restart docker, specific to your system. On a typical Linux workstation, you do this via:

sudo service docker restart

Alternatively, you can also pass the --dns argument to your docker daemon, but creating a daemon.json and following the above method will solve the problem system-wide.

Visual Studio Code FAQ

Visual Studio Code Recommended Settings

  • Configure the editor to format on save, in your Visual Studio Code Settings: "editor.formatOnSave": true
  • Configure the clang-format extension @ext:xaver.clang-format, it is installed in the docker container. Make sure all languages are enabled