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 03edc5fc9a9160..3386517d961b6e 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? @@ -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/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..f96378db329f38 100644 --- a/docs/README.md +++ b/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. + diff --git a/docs/VSCODE_DEVELOPMENT.md b/docs/VSCODE_DEVELOPMENT.md new file mode 100644 index 00000000000000..fca1967dd2111f --- /dev/null +++ b/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: +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 +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. *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. + 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)