Merge pull request #209 from idan/containerize-development

Add VSCode devcontainer configuration

5 files changed, 102 insertions, 0 deletions

diff --git a/.devcontainer/.bashrc b/.devcontainer/.bashrc
new file mode 100644
index 0000000..855ea75
--- /dev/null
+++ b/.devcontainer/.bashrc
@@ -0,0 +1,6 @@
+export LS_OPTIONS='-F --color=auto'
+eval "`dircolors`"
+alias ls='ls $LS_OPTIONS'
+if [ -f "$WORKSPACE_DIR/zephyr/zephyr-env.sh" ]; then
+  source "$WORKSPACE_DIR/zephyr/zephyr-env.sh"
+fi
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 0000000..184aae9
--- /dev/null
+++ b/.devcontainer/Dockerfile
@@ -0,0 +1,11 @@
+FROM zmkfirmware/zephyr-west-action-arm
+
+RUN apt-get -y update && \
+    apt-get -y upgrade && \
+    apt-get install --no-install-recommends -y \
+    ssh \
+    gpg && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY .bashrc tmp
+RUN mv /tmp/.bashrc ~/.bashrc
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 0000000..940b78b
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,8 @@
+{
+  "name": "ZMK Development",
+  "dockerFile": "Dockerfile",
+  "extensions": ["ms-vscode.cpptools"],
+  "runArgs": ["--security-opt", "label=disable"],
+  "containerEnv": {"WORKSPACE_DIR": "${containerWorkspaceFolder}"}
+}
+
diff --git a/docs/docs/assets/dev-setup/vscode_devcontainer.png b/docs/docs/assets/dev-setup/vscode_devcontainer.png
new file mode 100644
index 0000000..e5c22b0
--- /dev/null
+++ b/docs/docs/assets/dev-setup/vscode_devcontainer.png
diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md
index 4891f5a..114fe0b 100644
--- a/docs/docs/dev-setup.md
+++ b/docs/docs/dev-setup.md
@@ -16,6 +16,7 @@ values={[
 {label: 'macOS', value: 'mac'},
 {label: 'Raspberry OS', value: 'raspberryos'},
 {label: 'Fedora', value: 'fedora'},
+{label: 'VS Code & Docker', value: 'docker'},
 ]
 }>{props.children}</Tabs>);
 
@@ -179,6 +180,20 @@ brew install cmake ninja python3 ccache dtc git wget
 ```
 
 </TabItem>
+<TabItem value="docker">
+
+This setup leverages the same [image which is used by the GitHub action](https://github.com/zmkfirmware/zephyr-west-action) for local development. Beyond the benefits of [dev/prod parity](https://12factor.net/dev-prod-parity), this approach is also the easiest to set up. No toolchain or dependencies are necessary when using Docker; the container image you'll be using already has the toolchain installed and set up to use.
+
+
+1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system.
+2. Install [VS Code](https://code.visualstudio.com/)
+3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+:::info
+The docker container includes `west` and the compilation toolchain. If you're using docker and VS Code, you can skip right to [Source Code](#source-code).
+:::
+
+</TabItem>
 </OsTabs>
 
 ## Setup
@@ -349,12 +364,63 @@ Since ZMK is built as a Zephyr™ application, the next step is
 to use `west` to initialize and update your workspace. The ZMK
 Zephyr™ application is in the `app/` source directory:
 
+
 #### Step into the repository
 
+<OsTabs>
+<TabItem value="debian">
+
 ```sh
 cd zmk
 ```
 
+</TabItem>
+<TabItem value="raspberryos">
+
+```sh
+cd zmk
+```
+
+</TabItem>
+<TabItem value="fedora">
+
+```sh
+cd zmk
+```
+
+</TabItem>
+<TabItem value="mac">
+
+```sh
+cd zmk
+```
+
+</TabItem>
+<TabItem value="win">
+
+```sh
+cd zmk
+```
+
+</TabItem>
+
+<TabItem value="docker">
+
+Open the `zmk` checkout folder in VS Code. The repository includes a configuration for containerized development, so an alert will pop up:
+
+![VS Code Dev Container Configuration Alert](assets/dev-setup/vscode_devcontainer.png)
+
+Click `Reopen in Container` in order to reopen the VS Code with the running container.
+
+The first time you do this on your machine, it will pull the docker image down from the registry and build the container. Subsequent launches are much faster!
+
+:::caution
+All subsequent steps must be performed from the VS Code terminal _inside_ the container. 
+:::
+
+</TabItem>
+</OsTabs>
+
 #### Initialize West
 
 ```sh
@@ -373,6 +439,17 @@ section again for links to how to do this
 west update
 ```
 
+:::tip
+This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection!
+:::
+
+:::info
+If you're using Docker, you're done with setup! You must restart the container at this point. The easiest way to do so is to close the VS Code window, verify that the container has stopped in Docker Dashboard, and reopen the container with VS Code.
+
+Once your container is restarted, proceed to [Building and Flashing](./dev-build.md).
+:::
+
+
 #### Export Zephyr™ Core
 
 ```sh