From 88c84260dac7aa07cde3a5dfb2ee06918766762f Mon Sep 17 00:00:00 2001 From: Justin Wood Date: Wed, 1 Apr 2020 15:20:03 +0000 Subject: [PATCH 1/5] Initial Stab --- README.md | 2 +- BUILDING.md => docs/BUILDING.md | 0 docs/README.md | 15 +++++++++++++++ docs/VSCODE_DEVELOPMENT.md | 33 +++++++++++++++++++++++++++++++++ docs/style/README.md | 6 ++++++ 5 files changed, 55 insertions(+), 1 deletion(-) rename BUILDING.md => docs/BUILDING.md (100%) create mode 100644 docs/VSCODE_DEVELOPMENT.md create mode 100644 docs/style/README.md diff --git a/README.md b/README.md index 03edc5fc9a9160..e267d8dedafcd0 100644 --- a/README.md +++ b/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? diff --git a/BUILDING.md b/docs/BUILDING.md similarity index 100% rename from BUILDING.md rename to docs/BUILDING.md diff --git a/docs/README.md b/docs/README.md index 25f8d456418b55..0d7a1263c2345e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1 +1,16 @@ # 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/) + diff --git a/docs/VSCODE_DEVELOPMENT.md b/docs/VSCODE_DEVELOPMENT.md new file mode 100644 index 00000000000000..cda75a158dd834 --- /dev/null +++ b/docs/VSCODE_DEVELOPMENT.md @@ -0,0 +1,33 @@ +# 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 that Visual Studio Code, and has an container environment setup automatically. You can read more about this workflow [here](https://code.visualstudio.com/docs/remote/containers). + +Tested on: +* MacOS + +## Setup Steps + +1. Install [Docker](https://www.docker.com/) for your operating system of choice from here: +1. Install [Visual Studio Code](https://code.visualstudio.com/) for your operating system of choice here: +1. Install [Git](https://git-scm.com/) if you haven't already +1. Git clone the main CHIP repository here: +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. 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" + diff --git a/docs/style/README.md b/docs/style/README.md new file mode 100644 index 00000000000000..890578a55f2f60 --- /dev/null +++ b/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) From e19107ebadb29dfce133c82e255b0f1cb2673758 Mon Sep 17 00:00:00 2001 From: Justin Wood Date: Wed, 1 Apr 2020 17:59:52 +0000 Subject: [PATCH 2/5] Aligning tasks & Docks --- .vscode/tasks.json | 22 +++++++++++++++++----- README.md | 6 ------ docs/README.md | 6 ++++++ docs/VSCODE_DEVELOPMENT.md | 19 +++++++++++++++++++ 4 files changed, 42 insertions(+), 11 deletions(-) diff --git a/.vscode/tasks.json b/.vscode/tasks.json index c7d4ebd9078f56..a4f8ce28fa5298 100644 --- a/.vscode/tasks.json +++ b/.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" diff --git a/README.md b/README.md index e267d8dedafcd0..3386517d961b6e 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/README.md b/docs/README.md index 0d7a1263c2345e..f96378db329f38 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,3 +14,9 @@ * 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. + diff --git a/docs/VSCODE_DEVELOPMENT.md b/docs/VSCODE_DEVELOPMENT.md index cda75a158dd834..dca5995030d026 100644 --- a/docs/VSCODE_DEVELOPMENT.md +++ b/docs/VSCODE_DEVELOPMENT.md @@ -31,3 +31,22 @@ Tested on: 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. + From 5d51a1d9953b6d0c5eaa8e11a59b803d9db94eb1 Mon Sep 17 00:00:00 2001 From: Justin Wood Date: Wed, 1 Apr 2020 18:06:55 +0000 Subject: [PATCH 3/5] Fixing typo --- docs/VSCODE_DEVELOPMENT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/VSCODE_DEVELOPMENT.md b/docs/VSCODE_DEVELOPMENT.md index dca5995030d026..81a9473ecebf75 100644 --- a/docs/VSCODE_DEVELOPMENT.md +++ b/docs/VSCODE_DEVELOPMENT.md @@ -2,7 +2,7 @@ [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 that Visual Studio Code, and has an container environment setup automatically. You can read more about this workflow [here](https://code.visualstudio.com/docs/remote/containers). +CHIP supports the docker / remote container workflow in Visual Studio Code, and has an container environment setup automatically. You can read more about this workflow [here](https://code.visualstudio.com/docs/remote/containers). Tested on: * MacOS From dc437250348f3ea632650c03d62216c7c1e642e8 Mon Sep 17 00:00:00 2001 From: Justin Wood Date: Wed, 1 Apr 2020 18:09:24 +0000 Subject: [PATCH 4/5] More typos --- docs/VSCODE_DEVELOPMENT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/VSCODE_DEVELOPMENT.md b/docs/VSCODE_DEVELOPMENT.md index 81a9473ecebf75..f63beb9ea78cb8 100644 --- a/docs/VSCODE_DEVELOPMENT.md +++ b/docs/VSCODE_DEVELOPMENT.md @@ -2,7 +2,7 @@ [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 an container environment setup automatically. You can read more about this workflow [here](https://code.visualstudio.com/docs/remote/containers). +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 From 8335909585586f6f04fca68be955d2335c67d858 Mon Sep 17 00:00:00 2001 From: Justin Wood Date: Wed, 1 Apr 2020 20:23:02 +0000 Subject: [PATCH 5/5] Tested on Windows, and updating instructions --- docs/VSCODE_DEVELOPMENT.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/VSCODE_DEVELOPMENT.md b/docs/VSCODE_DEVELOPMENT.md index f63beb9ea78cb8..fca1967dd2111f 100644 --- a/docs/VSCODE_DEVELOPMENT.md +++ b/docs/VSCODE_DEVELOPMENT.md @@ -5,10 +5,13 @@ 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 +* 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: +1. *Windows Only* Install Ubuntu from the Windows App Store here: 1. Install [Docker](https://www.docker.com/) for your operating system of choice from here: 1. Install [Visual Studio Code](https://code.visualstudio.com/) for your operating system of choice here: 1. Install [Git](https://git-scm.com/) if you haven't already @@ -17,6 +20,8 @@ Tested on: 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)