From dbf4e05663f90c8d258ad344959d7a2695ca4342 Mon Sep 17 00:00:00 2001 From: KemoNine Date: Mon, 30 Nov 2020 01:13:31 +0000 Subject: [PATCH] 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