blob: 5e7eeab92ee08c197936590133350195cbc4a053 [file] [log] [blame] [view]
Justin Wood88c84262020-04-01 15:20:03 +00001# Visual Studio Code Development
2
Justin Wood0a9545e2020-04-20 18:15:21 -07003[Visual Studio Code](https://code.visualstudio.com/) is a great and simple IDE
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +02004that can be used to build & develop with for Matter.
Justin Wood88c84262020-04-01 15:20:03 +00005
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +02006Matter supports the docker / remote container workflow in Visual Studio Code,
7and has a container environment setup automatically. You can read more about
8this workflow [here](https://code.visualstudio.com/docs/remote/containers).
Justin Wood88c84262020-04-01 15:20:03 +00009
10Tested on:
Justin Wood0a9545e2020-04-20 18:15:21 -070011
Rob Walker00c01602020-10-14 18:55:02 -070012- macOS 10.5
Justin Wood0a9545e2020-04-20 18:15:21 -070013- Windows 10 Pro + WSL + Ubuntu 18 LTS
Timotej Ecimovicd7f312a2022-03-07 19:28:22 -050014- Linux - Fedora Core 35 distribution
Justin Wood88c84262020-04-01 15:20:03 +000015
16## Setup Steps
17
Justin Wood0a9545e2020-04-20 18:15:21 -0700181. _Windows Only_ Enable the Windows Subsystem for Linux (WSL) following
19 instructions here:
20 <https://docs.microsoft.com/en-us/windows/wsl/install-win10>
211. _Windows Only_ Install Ubuntu from the Windows App Store here:
22 <https://www.microsoft.com/en-us/p/ubuntu-1804-lts/9n9tngvndl3q>
231. Install [Docker](https://www.docker.com/) for your operating system of choice
Anna Bridge18cd3382022-11-02 03:35:37 +000024 from here: <https://docs.docker.com/engine/install>
Justin Wood0a9545e2020-04-20 18:15:21 -0700251. Install [Visual Studio Code](https://code.visualstudio.com/) for your
26 operating system of choice here: <https://code.visualstudio.com/Download>
Justin Wood88c84262020-04-01 15:20:03 +0000271. Install [Git](https://git-scm.com/) if you haven't already
Justin Wood0a9545e2020-04-20 18:15:21 -0700281. _Windows Only_ Enable git to use LF instead of CLRF by default:
29 `git config --global core.autocrlf false`
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +0200301. Git clone the main Matter repository here:
Justin Wood0a9545e2020-04-20 18:15:21 -070031 <https://github.com/project-chip/connectedhomeip>
Alex Pyginb1e6aa22023-02-03 13:30:25 -0600321. Launch Visual Studio Code, and open the cloned folder from above
Justin Wood0a9545e2020-04-20 18:15:21 -0700331. Install the
Frederico Hakamine1da05c92023-01-18 06:06:14 -060034 [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
Justin Wood0a9545e2020-04-20 18:15:21 -070035 extension for Visual Studio Code, this extension allows you to use docker
36 containers as a development backend.
371. Once this is installed, you'll be prompted to reload Visual Studio Code, do
38 so
391. 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.
411. _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"`
451. Now your local machine is building a docker image that has all the tools
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +020046 necessary to build and test Matter. This can take some time, but will
Justin Wood0a9545e2020-04-20 18:15:21 -070047 eventually complete and open up the source tree
Justin Wood88c84262020-04-01 15:20:03 +000048
49## Bootstrapping your source tree (one time)
Justin Wood0a9545e2020-04-20 18:15:21 -070050
511. Under the "Terminal" menu (or using another shortcut to the same tool),
52 select "Run Task..."
Justin Wood88c84262020-04-01 15:20:03 +0000531. Select the "Bootstrap" task
54
55## Building the Source Tree
Justin Wood0a9545e2020-04-20 18:15:21 -070056
Justin Wood88c84262020-04-01 15:20:03 +0000571. Under the "Terminal" menu select "Run Build Task..."
58
59## Tasks
60
Justin Wood0a9545e2020-04-20 18:15:21 -070061Located in the [tasks json](../.vscode/tasks.json) file you'll find a list of
62tasks that can be run from the "Run Task..." command. Example tasks are "Clean",
63"Run Pretty Check"
Justin Wood88c84262020-04-01 15:20:03 +000064
Justin Wood0a9545e2020-04-20 18:15:21 -070065Developers are encouraged to add tasks to the
66[tasks json](../.vscode/tasks.json) over time to make sure everyone is using the
67same base configuration and build.
Justin Woode19107e2020-04-01 17:59:52 +000068
69### Current base tasks are listed here
Justin Wood0a9545e2020-04-20 18:15:21 -070070
Michael Spang31574232020-09-10 23:40:35 -040071- 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 Spange931c962020-11-03 14:00:15 -050074 Android, EFR32)
Michael Spang31574232020-09-10 23:40:35 -040075- 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 Wood0a9545e2020-04-20 18:15:21 -070079- Clean Tree - Full (and destructive) git clean of the tree
Justin Woode19107e2020-04-01 17:59:52 +000080
81## Launch Tasks
82
Justin Wood0a9545e2020-04-20 18:15:21 -070083Located in the [launch json](../.vscode/launch.json) file you'll find a list of
84build & run jobs that can be run from the "Run" tab and start a run or debug
85session.
Justin Woode19107e2020-04-01 17:59:52 +000086
Justin Wood0a9545e2020-04-20 18:15:21 -070087Developers are encouraged to add tasks to the
88[launch json](../.vscode/launch.json) over time to make sure everyone is using
Victor Morales9e8d2682021-09-14 09:34:55 -070089the same base debugging setup.
Justin Woode19107e2020-04-01 17:59:52 +000090
Justin Wood92003e82020-04-01 21:37:52 +000091## Submitting a Pull Request - Practical Advice
92
93### Before submitting a PR, make sure these commands run and succeed
Justin Wood0a9545e2020-04-20 18:15:21 -070094
Michael Spang31574232020-09-10 23:40:35 -040095- Run task: "Build & Test (all)"
Justin Wood9b4c0c52020-04-02 00:38:16 +000096
Pankaj Garg73af2622020-04-01 21:32:24 +000097## Common Issues
Justin Wood0a9545e2020-04-20 18:15:21 -070098
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 Woodff607d22020-04-03 21:53:36 +0000102
Timotej Ecimovicd7f312a2022-03-07 19:28:22 -0500103## Docker FAQ
104
105### DNS problem: can't resolve archive.ubuntu.com
106
107A common problem encountered is that a container can't resolve
108`archive.ubuntu.com` and can't install anything via `apt-get`, during the
109creation of the container image, resulting in an error like:
110
111```
112E: Package 'locales' has no installation candidate
113The 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
116Most common reason for this is that the DNS for docker daemon has not been set
117up correctly and is simply using a default: 8.8.8.8, which in many corporate or
118more secure environments is not accessible. A typical solution for this is to
119put a following key/value into your system-wide docker `daemon.json` (Typically
120located under `/etc/docker/daemon.json` on a Linux system):
121
122```
123"dns": ["<<IP ADDRESS OF YOUR NAMESERVER>>", "8.8.8.8"]
124```
125
126You can obtain the address you should put into that line of your nameserver by
127running:
128
129```
130nmcli dev show | grep 'IP4.DNS'
131```
132
133After you update the dns, you should restart docker, specific to your system. On
134a typical Linux workstation, you do this via:
135
136```
137sudo service docker restart
138```
139
140Alternatively, you can also pass the `--dns` argument to your docker daemon, but
141creating a `daemon.json` and following the above method will solve the problem
142system-wide.
143
Justin Woodff607d22020-04-03 21:53:36 +0000144## Visual Studio Code FAQ
145
Justin Wood0a9545e2020-04-20 18:15:21 -0700146- _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 Woodff607d22020-04-03 21:53:36 +0000153
154## Visual Studio Code Recommended Settings
155
Justin Wood0a9545e2020-04-20 18:15:21 -0700156- 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