From fa39132c2a452c2305994398d9f30e435b79ecec Mon Sep 17 00:00:00 2001 From: KemoNine Date: Fri, 27 Nov 2020 23:48:09 +0000 Subject: [PATCH] Slice up the development environment setup some included changes: - Give a brief overview of docker+vscode vs native os - Dedicated page for docker+vscode setup - Dedicated page for native os setup - Dedicated page for setting up zmk sources for development --- docs/docs/development/setup/docker-vscode.md | 17 +++ .../development/{setup.md => setup/native.md} | 142 ++---------------- docs/docs/development/setup/setup.md | 19 +++ docs/docs/development/setup/zmk.md | 128 ++++++++++++++++ docs/sidebars.js | 12 +- 5 files changed, 186 insertions(+), 132 deletions(-) create mode 100644 docs/docs/development/setup/docker-vscode.md rename docs/docs/development/{setup.md => setup/native.md} (75%) create mode 100644 docs/docs/development/setup/setup.md create mode 100644 docs/docs/development/setup/zmk.md diff --git a/docs/docs/development/setup/docker-vscode.md b/docs/docs/development/setup/docker-vscode.md new file mode 100644 index 00000000..eb5050b9 --- /dev/null +++ b/docs/docs/development/setup/docker-vscode.md @@ -0,0 +1,17 @@ +--- +title: Docker+VSCode Setup +sidebar_label: Docker+VSCode +--- + +:::danger The Docker+VSCode environment will **NOT** run on arm CPUs. You must use the Native environment if using an arm CPU. +::: + +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 +Once the above is setup you're ready to setup the ZMK sources as defined [here](/docs/development/setup/zmk) +::: diff --git a/docs/docs/development/setup.md b/docs/docs/development/setup/native.md similarity index 75% rename from docs/docs/development/setup.md rename to docs/docs/development/setup/native.md index 6ad4e2bf..41b6f2f6 100644 --- a/docs/docs/development/setup.md +++ b/docs/docs/development/setup/native.md @@ -1,6 +1,6 @@ --- -title: Basic Setup -sidebar_label: Basic Setup +title: Native OS Setup +sidebar_label: Native OS --- import Tabs from '@theme/Tabs'; @@ -15,7 +15,6 @@ values={[ {label: 'macOS', value: 'mac'}, {label: 'Raspberry OS', value: 'raspberryos'}, {label: 'Fedora', value: 'fedora'}, -{label: 'VS Code & Docker', value: 'docker'}, ] }>{props.children}); @@ -185,19 +184,6 @@ Homebrew is required to install the system dependencies. If you haven't done so, brew install cmake ninja python3 ccache dtc git wget dfu-util ``` - - - -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). -::: - @@ -355,116 +341,6 @@ The transient instructions can be used to setup the current shell, and the autom The transient instructions must be run to build firmware using the current shell. ::: -### Source Code - -Next, you'll need to clone the ZMK source repository if you haven't already. Navigate to the folder you would like to place your `zmk` directory in and run the following command: - -``` -git clone https://github.com/zmkfirmware/zmk.git -``` - -### Initialize & Update Zephyr Workspace - -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 - - - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - - - -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. -::: - - - - -#### Initialize West - -```sh -west init -l app/ -``` - -:::caution Command Not Found? -If you encounter errors like `command not found: west` then your `PATH` environment variable is likely -missing the Python 3 user packages directory. See the [West Build Command](#west-build-command) -section again for links to how to do this -::: - -#### Update To Fetch Modules - -```sh -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](./development/build-flash.md). -::: - -#### Export Zephyr™ Core - -```sh -west zephyr-export -``` - -#### Install Zephyr Python Dependencies - -```sh -pip3 install --user -r zephyr/scripts/requirements-base.txt -``` - ### Environment Variables > ~/.zshrc + +:::info +Once the above is setup you're ready to setup the ZMK sources as defined [here](/docs/development/setup/zmk) +::: diff --git a/docs/docs/development/setup/setup.md b/docs/docs/development/setup/setup.md new file mode 100644 index 00000000..49619e9f --- /dev/null +++ b/docs/docs/development/setup/setup.md @@ -0,0 +1,19 @@ +--- +title: General Info +sidebar_label: General Information +--- + +## Environment Setup + +There are 2 ways to setup the zmk development environment: Docker+VSCode and Native OS. The Docker+VSCode approach is a self-contained development environment while Native OS approach will setup your local operating system for development. + +The Docker+VSCode approach is very straight forward to setup. The Native approach requires more up-front work but doesn't require installing Docker/VSCode and can be faster for development depending on your computer's hardware. + +The links in the navigation bar will outline the necessary steps for setting up both of these approaches. + +:::danger The Docker+VSCode environment will **NOT** run on arm CPUs. You must use the Native OS environment if using an arm CPU. +::: + +## ZMK Sources Setup + +Once you've setup either the Docker+VSCode environment or Native OS environment you will need to setup the ZMK sources. Please see the [ZMK Sources](/docs/development/setup/zmk) section once you've setup your chosen environment. diff --git a/docs/docs/development/setup/zmk.md b/docs/docs/development/setup/zmk.md new file mode 100644 index 00000000..28aeae68 --- /dev/null +++ b/docs/docs/development/setup/zmk.md @@ -0,0 +1,128 @@ +--- +title: ZMK Sources +sidebar_label: ZMK Sources +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const OsTabs = (props) => ({props.children}); + +### Source Code + +Next, you'll need to clone the ZMK source repository if you haven't already. Navigate to the folder you would like to place your `zmk` directory in and run the following command: + +``` +git clone https://github.com/zmkfirmware/zmk.git +``` + +:::caution +If you're using the Docker+VSCode environment on Windows, you _must_ checkout the sources to a folder within `C:\Users\[your_user_here]` to avoid a potential permissions issue. +::: + +### Initialize & Update Zephyr Workspace + +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 + + + + +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. +::: + + + + + +```sh +cd zmk +``` + + + + +```sh +cd zmk +``` + + + + +```sh +cd zmk +``` + + + + +```sh +cd zmk +``` + + + + +```sh +cd zmk +``` + + + + +#### Initialize West + +```sh +west init -l app/ +``` + +:::caution Command Not Found? (Native OS) +If you encounter errors like `command not found: west` then your `PATH` environment variable is likely +missing the Python 3 user packages directory. See the [West Build Command](#west-build-command) +section again for links to how to do this +::: + +#### Update To Fetch Modules + +```sh +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! +::: + +#### Export Zephyr™ Core + +```sh +west zephyr-export +``` + +#### Install Zephyr Python Dependencies + +```sh +pip3 install --user -r zephyr/scripts/requirements-base.txt +``` diff --git a/docs/sidebars.js b/docs/sidebars.js index e98b3f81..0df9f1ca 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -43,7 +43,17 @@ module.exports = { Development: [ "development/clean-room", "development/documentation", - "development/setup", + { + type: "category", + label: "Setup", + collapsed: false, + items: [ + "development/setup/setup", + "development/setup/docker-vscode", + "development/setup/native", + "development/setup/zmk", + ], + }, "development/build-flash", "development/boards-shields-keymaps", "development/posix-board",