Justin Wood | 88c8426 | 2020-04-01 15:20:03 +0000 | [diff] [blame] | 1 | # Visual Studio Code Development |
| 2 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 3 | [Visual Studio Code](https://code.visualstudio.com/) is a great and simple IDE |
Grzegorz Ferenc | bae3e7d | 2021-10-19 15:49:45 +0200 | [diff] [blame] | 4 | that can be used to build & develop with for Matter. |
Justin Wood | 88c8426 | 2020-04-01 15:20:03 +0000 | [diff] [blame] | 5 | |
Grzegorz Ferenc | bae3e7d | 2021-10-19 15:49:45 +0200 | [diff] [blame] | 6 | Matter supports the docker / remote container workflow in Visual Studio Code, |
| 7 | and has a container environment setup automatically. You can read more about |
| 8 | this workflow [here](https://code.visualstudio.com/docs/remote/containers). |
Justin Wood | 88c8426 | 2020-04-01 15:20:03 +0000 | [diff] [blame] | 9 | |
| 10 | Tested on: |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 11 | |
Rob Walker | 00c0160 | 2020-10-14 18:55:02 -0700 | [diff] [blame] | 12 | - macOS 10.5 |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 13 | - Windows 10 Pro + WSL + Ubuntu 18 LTS |
Timotej Ecimovic | d7f312a | 2022-03-07 19:28:22 -0500 | [diff] [blame] | 14 | - Linux - Fedora Core 35 distribution |
Justin Wood | 88c8426 | 2020-04-01 15:20:03 +0000 | [diff] [blame] | 15 | |
| 16 | ## Setup Steps |
| 17 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 18 | 1. _Windows Only_ Enable the Windows Subsystem for Linux (WSL) following |
| 19 | instructions here: |
| 20 | <https://docs.microsoft.com/en-us/windows/wsl/install-win10> |
| 21 | 1. _Windows Only_ Install Ubuntu from the Windows App Store here: |
| 22 | <https://www.microsoft.com/en-us/p/ubuntu-1804-lts/9n9tngvndl3q> |
| 23 | 1. Install [Docker](https://www.docker.com/) for your operating system of choice |
Anna Bridge | 18cd338 | 2022-11-02 03:35:37 +0000 | [diff] [blame] | 24 | from here: <https://docs.docker.com/engine/install> |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 25 | 1. Install [Visual Studio Code](https://code.visualstudio.com/) for your |
| 26 | operating system of choice here: <https://code.visualstudio.com/Download> |
Justin Wood | 88c8426 | 2020-04-01 15:20:03 +0000 | [diff] [blame] | 27 | 1. Install [Git](https://git-scm.com/) if you haven't already |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 28 | 1. _Windows Only_ Enable git to use LF instead of CLRF by default: |
| 29 | `git config --global core.autocrlf false` |
Grzegorz Ferenc | bae3e7d | 2021-10-19 15:49:45 +0200 | [diff] [blame] | 30 | 1. Git clone the main Matter repository here: |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 31 | <https://github.com/project-chip/connectedhomeip> |
Alex Pygin | b1e6aa2 | 2023-02-03 13:30:25 -0600 | [diff] [blame] | 32 | 1. Launch Visual Studio Code, and open the cloned folder from above |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 33 | 1. Install the |
Frederico Hakamine | 1da05c9 | 2023-01-18 06:06:14 -0600 | [diff] [blame] | 34 | [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 35 | extension for Visual Studio Code, this extension allows you to use docker |
| 36 | containers as a development backend. |
| 37 | 1. Once this is installed, you'll be prompted to reload Visual Studio Code, do |
| 38 | so |
| 39 | 1. At the bottom right of your Visual Studio Code window you should have a new |
| 40 | box prompting you to re-open the window as a container. Hit yes. |
| 41 | 1. _Windows Only_ Update your Visual Studio Code settings as documented here: |
| 42 | https://code.visualstudio.com/docs/editor/integrated-terminal#_configuration |
| 43 | to use Bash on Ubuntu (on Windows) eg: |
| 44 | `"terminal.integrated.shell.windows": "C:\\Windows\\System32\\bash.exe"` |
| 45 | 1. Now your local machine is building a docker image that has all the tools |
Grzegorz Ferenc | bae3e7d | 2021-10-19 15:49:45 +0200 | [diff] [blame] | 46 | necessary to build and test Matter. This can take some time, but will |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 47 | eventually complete and open up the source tree |
Justin Wood | 88c8426 | 2020-04-01 15:20:03 +0000 | [diff] [blame] | 48 | |
| 49 | ## Bootstrapping your source tree (one time) |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 50 | |
| 51 | 1. Under the "Terminal" menu (or using another shortcut to the same tool), |
| 52 | select "Run Task..." |
Justin Wood | 88c8426 | 2020-04-01 15:20:03 +0000 | [diff] [blame] | 53 | 1. Select the "Bootstrap" task |
| 54 | |
| 55 | ## Building the Source Tree |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 56 | |
Justin Wood | 88c8426 | 2020-04-01 15:20:03 +0000 | [diff] [blame] | 57 | 1. Under the "Terminal" menu select "Run Build Task..." |
| 58 | |
| 59 | ## Tasks |
| 60 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 61 | Located in the [tasks json](../.vscode/tasks.json) file you'll find a list of |
| 62 | tasks that can be run from the "Run Task..." command. Example tasks are "Clean", |
| 63 | "Run Pretty Check" |
Justin Wood | 88c8426 | 2020-04-01 15:20:03 +0000 | [diff] [blame] | 64 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 65 | Developers are encouraged to add tasks to the |
| 66 | [tasks json](../.vscode/tasks.json) over time to make sure everyone is using the |
| 67 | same base configuration and build. |
Justin Wood | e19107e | 2020-04-01 17:59:52 +0000 | [diff] [blame] | 68 | |
| 69 | ### Current base tasks are listed here |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 70 | |
Michael Spang | 3157423 | 2020-09-10 23:40:35 -0400 | [diff] [blame] | 71 | - Main Build - Build the default configuration (i.e., Linux OpenSSL) |
| 72 | - Run Unit and Functional Tests - Test the default configuration |
| 73 | - Build & Test (all) - Build & Test various configurations (Linux variants, |
Michael Spang | e931c96 | 2020-11-03 14:00:15 -0500 | [diff] [blame] | 74 | Android, EFR32) |
Michael Spang | 3157423 | 2020-09-10 23:40:35 -0400 | [diff] [blame] | 75 | - Update compilation database - Update the database used by IntelliSense |
| 76 | (needed for cross references, completion) |
| 77 | - Bootstrap - On a clean tree, pull in the third party dependencies required |
| 78 | - Clean Output - Remove build artifacts |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 79 | - Clean Tree - Full (and destructive) git clean of the tree |
Justin Wood | e19107e | 2020-04-01 17:59:52 +0000 | [diff] [blame] | 80 | |
| 81 | ## Launch Tasks |
| 82 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 83 | Located in the [launch json](../.vscode/launch.json) file you'll find a list of |
| 84 | build & run jobs that can be run from the "Run" tab and start a run or debug |
| 85 | session. |
Justin Wood | e19107e | 2020-04-01 17:59:52 +0000 | [diff] [blame] | 86 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 87 | Developers are encouraged to add tasks to the |
| 88 | [launch json](../.vscode/launch.json) over time to make sure everyone is using |
Victor Morales | 9e8d268 | 2021-09-14 09:34:55 -0700 | [diff] [blame] | 89 | the same base debugging setup. |
Justin Wood | e19107e | 2020-04-01 17:59:52 +0000 | [diff] [blame] | 90 | |
Justin Wood | 92003e8 | 2020-04-01 21:37:52 +0000 | [diff] [blame] | 91 | ## Submitting a Pull Request - Practical Advice |
| 92 | |
| 93 | ### Before submitting a PR, make sure these commands run and succeed |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 94 | |
Michael Spang | 3157423 | 2020-09-10 23:40:35 -0400 | [diff] [blame] | 95 | - Run task: "Build & Test (all)" |
Justin Wood | 9b4c0c5 | 2020-04-02 00:38:16 +0000 | [diff] [blame] | 96 | |
Pankaj Garg | 73af262 | 2020-04-01 21:32:24 +0000 | [diff] [blame] | 97 | ## Common Issues |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 98 | |
| 99 | - [Missing Git credential](https://code.visualstudio.com/docs/remote/containers#_sharing-git-credentials-with-your-container) |
| 100 | - [Missing Git SSH keys](https://code.visualstudio.com/docs/remote/containers#_sharing-git-credentials-with-your-container) |
| 101 | - [Using GPG signing keys](https://github.com/microsoft/vscode-remote-release/issues/72) |
Justin Wood | ff607d2 | 2020-04-03 21:53:36 +0000 | [diff] [blame] | 102 | |
Timotej Ecimovic | d7f312a | 2022-03-07 19:28:22 -0500 | [diff] [blame] | 103 | ## Docker FAQ |
| 104 | |
| 105 | ### DNS problem: can't resolve archive.ubuntu.com |
| 106 | |
| 107 | A common problem encountered is that a container can't resolve |
| 108 | `archive.ubuntu.com` and can't install anything via `apt-get`, during the |
| 109 | creation of the container image, resulting in an error like: |
| 110 | |
| 111 | ``` |
| 112 | E: Package 'locales' has no installation candidate |
| 113 | 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 |
| 114 | ``` |
| 115 | |
| 116 | Most common reason for this is that the DNS for docker daemon has not been set |
| 117 | up correctly and is simply using a default: 8.8.8.8, which in many corporate or |
| 118 | more secure environments is not accessible. A typical solution for this is to |
| 119 | put a following key/value into your system-wide docker `daemon.json` (Typically |
| 120 | located under `/etc/docker/daemon.json` on a Linux system): |
| 121 | |
| 122 | ``` |
| 123 | "dns": ["<<IP ADDRESS OF YOUR NAMESERVER>>", "8.8.8.8"] |
| 124 | ``` |
| 125 | |
| 126 | You can obtain the address you should put into that line of your nameserver by |
| 127 | running: |
| 128 | |
| 129 | ``` |
| 130 | nmcli dev show | grep 'IP4.DNS' |
| 131 | ``` |
| 132 | |
| 133 | After you update the dns, you should restart docker, specific to your system. On |
| 134 | a typical Linux workstation, you do this via: |
| 135 | |
| 136 | ``` |
| 137 | sudo service docker restart |
| 138 | ``` |
| 139 | |
| 140 | Alternatively, you can also pass the `--dns` argument to your docker daemon, but |
| 141 | creating a `daemon.json` and following the above method will solve the problem |
| 142 | system-wide. |
| 143 | |
Justin Wood | ff607d2 | 2020-04-03 21:53:36 +0000 | [diff] [blame] | 144 | ## Visual Studio Code FAQ |
| 145 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 146 | - _Highly_ recommend you read through |
| 147 | [this page](https://code.visualstudio.com/docs/getstarted/settings) to learn |
| 148 | how to configure Visual Studio Code to suit your style: |
| 149 | <https://code.visualstudio.com/docs/getstarted/settings> |
| 150 | - Great primer set of videos |
| 151 | [here](https://code.visualstudio.com/docs/getstarted/introvideos) |
| 152 | <https://code.visualstudio.com/docs/getstarted/introvideos> |
Justin Wood | ff607d2 | 2020-04-03 21:53:36 +0000 | [diff] [blame] | 153 | |
| 154 | ## Visual Studio Code Recommended Settings |
| 155 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 156 | - Configure the editor to format on save, in your Visual Studio Code Settings: |
| 157 | `"editor.formatOnSave": true` |
| 158 | - Configure the clang-format extension `@ext:xaver.clang-format`, it is |
| 159 | installed in the docker container. Make sure all languages are enabled |