From fa39132c2a452c2305994398d9f30e435b79ecec Mon Sep 17 00:00:00 2001 From: KemoNine Date: Fri, 27 Nov 2020 23:48:09 +0000 Subject: [PATCH 1/7] 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", From 23dad0ae11259c89a5543c340028b1228f4e846e Mon Sep 17 00:00:00 2001 From: KemoNine Date: Sat, 28 Nov 2020 00:19:09 +0000 Subject: [PATCH 2/7] Fixup broken URLs based on CI feedback --- docs/docs/troubleshooting.md | 2 +- docs/docusaurus.config.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md index 5eccb7c1..3821a50a 100644 --- a/docs/docs/troubleshooting.md +++ b/docs/docs/troubleshooting.md @@ -26,7 +26,7 @@ Variations of the warnings shown below occur when flashing the `.uf2` ### CMake Error An error along the lines of `CMake Error at (zmk directory)/zephyr/cmake/generic_toolchain.cmake:64 (include): include could not find load file:` during firmware compilation indicates that the Zephyr Environment Variables are not properly defined. -For more information, click [here](../docs/development/setup#environment-variables). +For more information, click [here](../docs/development/setup/native#environment-variables). ### dtlib.DTError diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index f22610a0..c5dec773 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -48,7 +48,7 @@ module.exports = { }, { label: "Development", - to: "docs/development/setup/", + to: "docs/development/setup/setup", }, ], }, From dbf4e05663f90c8d258ad344959d7a2695ca4342 Mon Sep 17 00:00:00 2001 From: KemoNine Date: Mon, 30 Nov 2020 01:13:31 +0000 Subject: [PATCH 3/7] Cleanup documentation to read easier and have more readable conventions. Expand some notes and caution boxes so some pitfalls and ways to improve performance are more clear to users --- docs/docs/development/setup/docker-vscode.md | 15 +++++++++--- docs/docs/development/setup/native.md | 4 ++-- docs/docs/development/setup/setup.md | 25 +++++++++++++------- docs/docs/development/setup/zmk.md | 12 ++++++---- 4 files changed, 38 insertions(+), 18 deletions(-) diff --git a/docs/docs/development/setup/docker-vscode.md b/docs/docs/development/setup/docker-vscode.md index eb5050b9..aa8ed630 100644 --- a/docs/docs/development/setup/docker-vscode.md +++ b/docs/docs/development/setup/docker-vscode.md @@ -1,9 +1,18 @@ --- -title: Docker+VSCode Setup -sidebar_label: Docker+VSCode +title: Docker+VS Code Setup +sidebar_label: Docker --- -:::danger The Docker+VSCode environment will **NOT** run on arm CPUs. You must use the Native environment if using an arm CPU. +:::danger +The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi. You must use the native environment if using an arm CPU. +::: + +:::note Windows Users +Please note the zmk builds can run slower with Docker on Windows if you don't use the WSL2 filesystem to store files. Build times can take 3-5 minutes on slower hardware without using the WSL2 filesystem. If you run into performance problems you can checkout the zmk sources inside a WSL2 environment and use `code .` inside the WSL2 environment to open the sources. This can make builds run as fast as 20s. + +This approach will also need the [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) extension installed in VS Code as well. + +Files stored within WSL2 can be accessed via Windows Explorer by navigating to `\\wsl$`. ::: 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. diff --git a/docs/docs/development/setup/native.md b/docs/docs/development/setup/native.md index 41b6f2f6..18b9880e 100644 --- a/docs/docs/development/setup/native.md +++ b/docs/docs/development/setup/native.md @@ -1,6 +1,6 @@ --- -title: Native OS Setup -sidebar_label: Native OS +title: Native Setup +sidebar_label: Native --- import Tabs from '@theme/Tabs'; diff --git a/docs/docs/development/setup/setup.md b/docs/docs/development/setup/setup.md index 49619e9f..4c23d9a2 100644 --- a/docs/docs/development/setup/setup.md +++ b/docs/docs/development/setup/setup.md @@ -1,19 +1,28 @@ --- -title: General Info -sidebar_label: General Information +title: Getting Started +sidebar_label: Getting Started --- ## 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. +There are 2 ways to setup the zmk development environment: Docker+VS Code (Docker in the rest of the documentation) and using the operating system directly (native in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially. -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. +Please see the [Docker](/docs/development/setup/docker-vscode) instructions or [native](/docs/development/setup/native) instructions to continue setup. -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. +:::danger +The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi. You must use the native 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. +Once you've setup either the Docker environment or native 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. + +## Standard Conventions + +Throughout this documentation you will see commands like + +``` +sudo apt update +``` + +These commands should be run in a terminal such as Bash (Linux/macOS/Docker), PowerShell, or Command Prompt (Windows). diff --git a/docs/docs/development/setup/zmk.md b/docs/docs/development/setup/zmk.md index 28aeae68..aa34248e 100644 --- a/docs/docs/development/setup/zmk.md +++ b/docs/docs/development/setup/zmk.md @@ -19,18 +19,20 @@ values={[ ] }>{props.children}); +:::caution Windows Users +If you're using the Docker environment on Windows, you _must_ checkout the sources to a folder within `C:\Users\[your_user_here]` to avoid a potential permissions issue. + +If you're using the WSL2 native filesystem the sources should go under `~/` to avoid potential permissions issues. +::: + ### 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: +Next, you'll need to clone the ZMK source repository if you haven't already. Open a terminal and navigate to the folder you would like to place your `zmk` directory in, then 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 From 4f6a2a6923279c381a51a4cc864897b767852855 Mon Sep 17 00:00:00 2001 From: KemoNine Date: Wed, 2 Dec 2020 14:17:44 +0000 Subject: [PATCH 4/7] Additional updates and tuning per PR feedback --- docs/docs/development/setup/docker-vscode.md | 8 ++-- .../docs/development/setup/getting-started.md | 24 ++++++++++ docs/docs/development/setup/native.md | 6 +-- docs/docs/development/setup/setup.md | 28 ----------- docs/docs/development/setup/zmk.md | 46 ++++--------------- docs/docusaurus.config.js | 2 +- docs/sidebars.js | 2 +- 7 files changed, 42 insertions(+), 74 deletions(-) create mode 100644 docs/docs/development/setup/getting-started.md delete mode 100644 docs/docs/development/setup/setup.md diff --git a/docs/docs/development/setup/docker-vscode.md b/docs/docs/development/setup/docker-vscode.md index aa8ed630..758522bf 100644 --- a/docs/docs/development/setup/docker-vscode.md +++ b/docs/docs/development/setup/docker-vscode.md @@ -10,7 +10,7 @@ The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi. You m :::note Windows Users Please note the zmk builds can run slower with Docker on Windows if you don't use the WSL2 filesystem to store files. Build times can take 3-5 minutes on slower hardware without using the WSL2 filesystem. If you run into performance problems you can checkout the zmk sources inside a WSL2 environment and use `code .` inside the WSL2 environment to open the sources. This can make builds run as fast as 20s. -This approach will also need the [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) extension installed in VS Code as well. +This approach will also need the [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) extension installed in VS Code. Files stored within WSL2 can be accessed via Windows Explorer by navigating to `\\wsl$`. ::: @@ -21,6 +21,6 @@ This setup leverages the same [image which is used by the GitHub action](https:/ 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) -::: +## ZMK Sources Setup + +Once the above is setup you're ready to [set up the ZMK sources](/docs/development/setup/zmk). diff --git a/docs/docs/development/setup/getting-started.md b/docs/docs/development/setup/getting-started.md new file mode 100644 index 00000000..b432cfbc --- /dev/null +++ b/docs/docs/development/setup/getting-started.md @@ -0,0 +1,24 @@ +--- +title: Getting Started +sidebar_label: Getting Started +--- + +## Environment Setup + +There are two ways to setup the zmk development environment: Docker+VS Code (Docker in the rest of the documentation) and using the operating system directly (native in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially. + +Please see the [Docker](/docs/development/setup/docker-vscode) instructions or [native](/docs/development/setup/native) instructions to continue setup. + +:::danger +The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi. You must use the native environment if using an arm CPU. +::: + +## Standard Conventions + +Throughout this documentation you will see commands like + +``` +sudo apt update +``` + +These commands should be run in a terminal such as Bash (Linux/macOS/Docker), PowerShell, or Command Prompt (Windows). diff --git a/docs/docs/development/setup/native.md b/docs/docs/development/setup/native.md index 18b9880e..42eaeb86 100644 --- a/docs/docs/development/setup/native.md +++ b/docs/docs/development/setup/native.md @@ -430,6 +430,6 @@ cat ~/.zephyrrc >> ~/.zshrc -:::info -Once the above is setup you're ready to setup the ZMK sources as defined [here](/docs/development/setup/zmk) -::: +## ZMK Sources Setup + +Once the above is setup you're ready to [set up the ZMK sources](/docs/development/setup/zmk). diff --git a/docs/docs/development/setup/setup.md b/docs/docs/development/setup/setup.md deleted file mode 100644 index 4c23d9a2..00000000 --- a/docs/docs/development/setup/setup.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Getting Started -sidebar_label: Getting Started ---- - -## Environment Setup - -There are 2 ways to setup the zmk development environment: Docker+VS Code (Docker in the rest of the documentation) and using the operating system directly (native in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially. - -Please see the [Docker](/docs/development/setup/docker-vscode) instructions or [native](/docs/development/setup/native) instructions to continue setup. - -:::danger -The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi. You must use the native environment if using an arm CPU. -::: - -## ZMK Sources Setup - -Once you've setup either the Docker environment or native 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. - -## Standard Conventions - -Throughout this documentation you will see commands like - -``` -sudo apt update -``` - -These commands should be run in a terminal such as Bash (Linux/macOS/Docker), PowerShell, or Command Prompt (Windows). diff --git a/docs/docs/development/setup/zmk.md b/docs/docs/development/setup/zmk.md index aa34248e..3965d534 100644 --- a/docs/docs/development/setup/zmk.md +++ b/docs/docs/development/setup/zmk.md @@ -11,18 +11,14 @@ groupId="operating-systems" defaultValue="docker" values={[ {label: 'VS Code & Docker', value: 'docker'}, -{label: 'Debian/Ubuntu', value: 'debian'}, -{label: 'macOS', value: 'mac'}, -{label: 'Windows', value: 'win'}, -{label: 'Raspberry OS', value: 'raspberryos'}, -{label: 'Fedora', value: 'fedora'}, +{label: 'Native', value: 'native'}, ] }>{props.children}); :::caution Windows Users If you're using the Docker environment on Windows, you _must_ checkout the sources to a folder within `C:\Users\[your_user_here]` to avoid a potential permissions issue. -If you're using the WSL2 native filesystem the sources should go under `~/` to avoid potential permissions issues. +If you're using the WSL2 filesystem the sources should go under `~/` to avoid potential permissions issues. ::: ### Source Code @@ -58,35 +54,7 @@ All subsequent steps must be performed from the VS Code terminal _inside_ the co - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - + ```sh cd zmk @@ -101,9 +69,9 @@ cd zmk west init -l app/ ``` -:::caution Command Not Found? (Native OS) +:::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) +missing the Python 3 user packages directory. See the [Native setup](native/) section again for links to how to do this ::: @@ -125,6 +93,10 @@ west zephyr-export #### Install Zephyr Python Dependencies +:::note +This only need to be run when using the Native setup. +::: + ```sh pip3 install --user -r zephyr/scripts/requirements-base.txt ``` diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index c5dec773..d8ab68b5 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -48,7 +48,7 @@ module.exports = { }, { label: "Development", - to: "docs/development/setup/setup", + to: "docs/development/setup/getting-started", }, ], }, diff --git a/docs/sidebars.js b/docs/sidebars.js index 0df9f1ca..abf009db 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -48,7 +48,7 @@ module.exports = { label: "Setup", collapsed: false, items: [ - "development/setup/setup", + "development/setup/getting-started", "development/setup/docker-vscode", "development/setup/native", "development/setup/zmk", From d32cccd97700ce1612658771735828ef4222c62e Mon Sep 17 00:00:00 2001 From: KemoNine Date: Tue, 2 Mar 2021 19:24:14 +0000 Subject: [PATCH 5/7] docs(setup): misc updates for verbiage from @idan --- docs/docs/development/setup/docker-vscode.md | 14 +++++++------- docs/docs/development/setup/getting-started.md | 6 +++--- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/docs/development/setup/docker-vscode.md b/docs/docs/development/setup/docker-vscode.md index 758522bf..2868b4cc 100644 --- a/docs/docs/development/setup/docker-vscode.md +++ b/docs/docs/development/setup/docker-vscode.md @@ -4,9 +4,15 @@ sidebar_label: Docker --- :::danger -The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi. You must use the native environment if using an arm CPU. +The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi or Apple Silicon. 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) + :::note Windows Users Please note the zmk builds can run slower with Docker on Windows if you don't use the WSL2 filesystem to store files. Build times can take 3-5 minutes on slower hardware without using the WSL2 filesystem. If you run into performance problems you can checkout the zmk sources inside a WSL2 environment and use `code .` inside the WSL2 environment to open the sources. This can make builds run as fast as 20s. @@ -15,12 +21,6 @@ This approach will also need the [Remote - WSL](https://marketplace.visualstudio Files stored within WSL2 can be accessed via Windows Explorer by navigating to `\\wsl$`. ::: -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) - ## ZMK Sources Setup Once the above is setup you're ready to [set up the ZMK sources](/docs/development/setup/zmk). diff --git a/docs/docs/development/setup/getting-started.md b/docs/docs/development/setup/getting-started.md index b432cfbc..1c112d90 100644 --- a/docs/docs/development/setup/getting-started.md +++ b/docs/docs/development/setup/getting-started.md @@ -5,12 +5,12 @@ sidebar_label: Getting Started ## Environment Setup -There are two ways to setup the zmk development environment: Docker+VS Code (Docker in the rest of the documentation) and using the operating system directly (native in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially. +There are two ways to setup the zmk development environment: Docker+VS Code (`Docker` in the rest of the documentation) and using the operating system directly (`native` in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially. Please see the [Docker](/docs/development/setup/docker-vscode) instructions or [native](/docs/development/setup/native) instructions to continue setup. :::danger -The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi. You must use the native environment if using an arm CPU. +The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi or Apple Silicon. You must use the native environment if using an arm CPU. ::: ## Standard Conventions @@ -21,4 +21,4 @@ Throughout this documentation you will see commands like sudo apt update ``` -These commands should be run in a terminal such as Bash (Linux/macOS/Docker), PowerShell, or Command Prompt (Windows). +These commands should be run in a terminal such as Bash (Linux/MacOS/Docker), PowerShell, or Command Prompt (Windows). From 776a6be1b0993db66d593e9499c1204a833c29b0 Mon Sep 17 00:00:00 2001 From: KemoNine Date: Sat, 6 Mar 2021 20:48:12 +0000 Subject: [PATCH 6/7] docs(cleanup): minor tweaks based on @nicell feedback --- docs/docs/development/setup/docker-vscode.md | 4 ++-- docs/docs/development/setup/getting-started.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/development/setup/docker-vscode.md b/docs/docs/development/setup/docker-vscode.md index 2868b4cc..b94b339f 100644 --- a/docs/docs/development/setup/docker-vscode.md +++ b/docs/docs/development/setup/docker-vscode.md @@ -7,14 +7,14 @@ sidebar_label: Docker The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi or Apple Silicon. 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. +This setup leverages the same [Docker image used when building ZMK on GitHub](https://github.com/zmkfirmware/zmk-docker/). 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) :::note Windows Users -Please note the zmk builds can run slower with Docker on Windows if you don't use the WSL2 filesystem to store files. Build times can take 3-5 minutes on slower hardware without using the WSL2 filesystem. If you run into performance problems you can checkout the zmk sources inside a WSL2 environment and use `code .` inside the WSL2 environment to open the sources. This can make builds run as fast as 20s. +Please note the ZMK builds run slower (up to 3-5 minutes on slower hardware) with Docker on Windows if you don't use the WSL2 filesystem to store files. If you run into performance problems you can checkout the ZMK sources inside a WSL2 environment and run `code .` to open the sources. This can make builds run at near-native speed. This approach will also need the [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) extension installed in VS Code. diff --git a/docs/docs/development/setup/getting-started.md b/docs/docs/development/setup/getting-started.md index 1c112d90..00b6be94 100644 --- a/docs/docs/development/setup/getting-started.md +++ b/docs/docs/development/setup/getting-started.md @@ -5,12 +5,12 @@ sidebar_label: Getting Started ## Environment Setup -There are two ways to setup the zmk development environment: Docker+VS Code (`Docker` in the rest of the documentation) and using the operating system directly (`native` in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially. +There are two ways to setup the ZMK development environment: Docker+VS Code (`Docker` in the rest of the documentation) and using the operating system directly (`native` in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially. Please see the [Docker](/docs/development/setup/docker-vscode) instructions or [native](/docs/development/setup/native) instructions to continue setup. -:::danger -The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi or Apple Silicon. You must use the native environment if using an arm CPU. +:::caution +The Docker environment will **NOT** run on ARM CPUs like the Raspberry Pi or Apple Silicon. You must use the native environment if using an ARM CPU. ::: ## Standard Conventions From ff4d628b5969c4b7668c1a601e1037a33a84fd02 Mon Sep 17 00:00:00 2001 From: KemoNine Date: Wed, 10 Mar 2021 23:14:07 +0000 Subject: [PATCH 7/7] docs(misc): add redirects to prevent broken links --- docs/static/_redirects | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/static/_redirects diff --git a/docs/static/_redirects b/docs/static/_redirects new file mode 100644 index 00000000..9f166559 --- /dev/null +++ b/docs/static/_redirects @@ -0,0 +1 @@ +/docs/development/setup /docs/development/setup/getting-started \ No newline at end of file