Merge pull request #197 from woody-apple/build-documentation

Add documentation for downloading and using VS Code

.vscode/tasks.json

@@ -11,31 +11,43 @@
             }
         },
         {
-            "label": "Pretty",
+            "label": "Auto-enforce coding style",
+            "type": "shell",
+            "command": "make -f Makefile-Standalone pretty-check",
+            "group": "none"
+        },
+        {
+            "label": "Verify coding style conformance",
             "type": "shell",
             "command": "make -f Makefile-Standalone pretty",
             "group": "none"
         },
         {
-            "label": "Test & Check",
+            "label": "Run Unit and Functional Tests",
             "type": "shell",
             "command": "make -f Makefile-Standalone check",
             "group": "none"
         },
         {
-            "label": "Dist Check",
+            "label": "Run Distribution Generation",
             "type": "shell",
             "command": "make -f Makefile-Standalone distcheck",
             "group": "none"
         },
         {
-            "label": "Clean",
+            "label": "Run Code Coverage",
+            "type": "shell",
+            "command": "make -f Makefile-Standalone coverage",
+            "group": "none"
+        },
+        {
+            "label": "Clean build",
             "type": "shell",
             "command": "make -f Makefile-Standalone clean",
             "group": "none"
         },
         {
-            "label": "Bootstrap",
+            "label": "Bootstrap the source tree",
             "type": "shell",
             "command": "./bootstrap",
             "group": "none"

README.md

@@ -7,7 +7,7 @@
 
 All documentation is inside of the [docs section](./docs/README.md)
 
-Additional build information can also be found in [BUILDING.md](./BUILDING.md).
+Instructions about how to build and develop CHIP can be found [here](./docs/README.md#BuildingandDeveloping).
 
 # Need help?
 
@@ -45,12 +45,6 @@ The CHIP repository is structured as follows:
 | `third_party/` | Third-party code used by CHIP.|
 | `tools/` | Tools needed to work with the CHIP repo, as well as develop in the repository |
 
-# Third Party Tools
-
-Some tools and utilities are dependent on third party tools, such as Docker.
-
-[Docker](https://www.docker.com) is an excellent way to have stable build environments that don't pollute the host OS. It is also much easier to maintain stability across multiple host environments. Install stable version of [Docker Desktop](https://www.docker.com/products/docker-desktop) relevant to your native OS (MacOS or Windows). Once installed, you can run docker commands from the shell/terminal.
-
 # Contributing
 
 We would love for you to contribute to CHIP and help make it even

docs/README.md

@@ -1 +1,22 @@
 # Documentation
+
+## Building and Developing
+
+* Documentation about building from the command line can be found in [the build guide](./BUILDING.md)
+* Documentation about standard build & development flows using [Visual Studio Code](https://code.visualstudio.com/) can be found in [the development guide](./VSCODE_DEVELOPMENT.md)
+
+## Project Flow
+
+* Documentation about general CHIP usage of GitHub, and project tools is documented in [the project flow](./PROJECT_FLOW.md)
+
+## Style Guide
+
+* Documentation about style is documented in [the style guide](./STYLE_GUIDE.md)
+* Additional documentation about more specific files are in the [style folder](./style/)
+
+## Third Party Tools
+
+Some tools and utilities are dependent on third party tools, such as Docker.
+
+[Docker](https://www.docker.com) is an excellent way to have stable build environments that don't pollute the host OS. It is also much easier to maintain stability across multiple host environments. Install stable version of [Docker Desktop](https://www.docker.com/products/docker-desktop) relevant to your native OS (MacOS or Windows). Once installed, you can run docker commands from the shell/terminal.
+

docs/VSCODE_DEVELOPMENT.md

@@ -0,0 +1,57 @@
+# Visual Studio Code Development
+
+[Visual Studio Code](https://code.visualstudio.com/) is a great and simple IDE that can be used to build & develop with for CHIP. 
+
+CHIP 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](https://code.visualstudio.com/docs/remote/containers).
+
+Tested on:
+* MacOS 10.5
+* Windows 10 Pro + WSL + Ubuntu 18 LTS
+
+## 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>
+1. *Windows Only* Install Ubuntu from the Windows App Store here: <https://www.microsoft.com/en-us/p/ubuntu-1804-lts/9n9tngvndl3q>
+1. Install [Docker](https://www.docker.com/) for your operating system of choice from here: <https://docs.docker.com/install>
+1. Install [Visual Studio Code](https://code.visualstudio.com/) for your operating system of choice here: <https://code.visualstudio.com/Download>
+1. Install [Git](https://git-scm.com/) if you haven't already
+1. Git clone the main CHIP repository here: <https://github.com/project-chip/connectedhomeip>
+1. Launch Visual Studio Code, and open the cloned folder from
+1. Install the [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension for Visual Studio Code, this extension allows you to use docker containers as a development backend.
+1. Once this is installed, you'll be prompted to reload Visual Studio Code, do so
+1. 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.
+1. *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`
+1. Now your local machine is building a docker image that has all the tools necessary to build and test CHIP. This can take some time, but will eventually complete and open up the source tree
+
+## Bootstrapping your source tree (one time)
+1. Under the "Terminal" menu (or using another shortcut to the same tool), select "Run Task..."
+1. Select the "Bootstrap" task
+
+## Building the Source Tree
+1. Under the "Terminal" menu select "Run Build Task..."
+
+## Tasks
+
+Located in the [tasks json](../.vscode/tasks.json) file you'll find a list of tasks that can be run from the "Run Task..." command.
+Example tasks are "Clean", "Run Pretty Check"
+
+Developers are encouraged to add tasks to the [tasks json](../.vscode/tasks.json) over time to make sure everyone is using the same base configuration and build. 
+
+### Current base tasks are listed here
+* Main Build - Full build and test of the tree
+* Auto-enforce coding style
+* Verify coding style conformance
+* Run Unit and Functional Tests
+* Run Distribution Generation - Build and check distribution, running all functional and unit tests
+* Run Code Coverage (via 'make coverage')
+* Clean build - Full clean build and test of the tree
+* Bootstrap the source tree - On a clean tree, pull in the third party dependencies required
+* Clean Tree - Full (and destructive) git clean of the tree
+
+## Launch Tasks
+
+Located in the [launch json](../.vscode/launch.json) file you'll find a list of build & run jobs that can be run from the "Run" tab and start a run or debug session.
+
+Developers are encouraged to add tasks to the [launch json](../.vscode/launch.json) over time to make sure everyone is using the same base debuging setup. 
+

docs/style/README.md

@@ -0,0 +1,6 @@
+# Style
+
+When necessary to drive into more detail about styles about specific types of files this is where CHIP collects them
+
+## Specific Types
+* [Makefiles](./STYLE_MAKEFILES.md)