From 31e481954f1e22e42bde4b71753e279cdd4c77ed Mon Sep 17 00:00:00 2001 From: Kevin Date: Sun, 4 Oct 2020 17:03:56 -0700 Subject: [PATCH] fix(docs): Fixed Python environment variables and commands for Windows setup --- docs/docs/dev-setup.md | 111 +++++++++++++++++++++-------------------- 1 file changed, 57 insertions(+), 54 deletions(-) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 1d7d703b..2e232f89 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -12,16 +12,16 @@ groupId="operating-systems" defaultValue="debian" values={[ {label: 'Debian/Ubuntu', value: 'debian'}, -{label: 'Raspberry OS', value: 'raspberryos'}, -{label: 'Fedora', value: 'fedora'}, {label: 'Windows', value: 'win'}, {label: 'macOS', value: 'mac'}, +{label: 'Raspberry OS', value: 'raspberryos'}, +{label: 'Fedora', value: 'fedora'}, ] }>{props.children}); ## Prerequisites -A unix-like environment with the following base packages installed: +ZMK requires the following base packages to first be installed: - Git - Python 3 @@ -34,6 +34,7 @@ A unix-like environment with the following base packages installed: + On Debian and Ubuntu, we'll use `apt` to install our base dependencies: First, if you haven't updated recently, or if this is a new install, @@ -74,7 +75,8 @@ or download and install CMake version 3.13.1 or newer manually. ::: -On Raspberry OS, we'll use apt to install our base dependencies: + +On Raspberry OS, we'll use `apt` to install our base dependencies: First, if you haven't updated recently, or if this is a new install, you should update to get the latest package information: @@ -185,14 +187,39 @@ brew install cmake ninja python3 ccache dtc git wget `west` is the [Zephyr™ meta-tool](https://docs.zephyrproject.org/2.3.0/guides/west/index.html) used to configure and build Zephyr™ applications. -West can be installed by using the `pip` python package manager. +West can be installed by using the `pip` python package manager. The [Zephyr™ instructions](https://docs.zephyrproject.org/latest/guides/west/install.html#installing-west) are summarized here: + + + ```sh pip3 install --user -U west ``` -:::danger pip user packages -If you haven't done so yet, you may need to add the Python Pip user package directory to your `PATH` otherwise your computer will not be able to find the `west` command. + + + +In `cmd.exe` as **Administrator**: + +```sh +pip3 install -U west +``` + +Once `west` is installed, close Command Prompt and open a new session as a **user** for the remainder of the instructions. +:::note +**For Windows, do not use the `--user` argument** that Linux uses otherwise `west` will be installed in a different location and the below instructions for adding Python `pip` will no longer apply. +::: + + + + +:::danger `pip` user packages +If you haven't done so yet, you may need to add the Python `pip` package directory to your `PATH` otherwise your computer will not be able to find the `west` command. ::: 1. See the [Environment Variables](#environment-variables) section on how to get to the Environment Variables page. -3. Click "Edit..." and then "New" to add the directory where your west.exe is located. By default this should be something like `C:\Python38\Scripts`. +2. Under "System variables" select the "Path" variable. Click "Edit..." and then "New" to add the directory where your `west.exe` is located. By default this should be `C:\Python##\Scripts` where ## is your Python version number. +3. Close Command Prompt and open a new session for the changes to take effect, or run `refreshenv`. @@ -279,7 +307,7 @@ The installation will prompt with several questions about installation location, #### GNU ARM Embedded -Since the Zephyr™ SDK is not available for Windows, we recommending following the steps to install the [GNU ARM Embedded](https://docs.zephyrproject.org/2.3.0/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded). +Since the Zephyr™ SDK is not available for Windows, we recommending following the [Zephyr documentation](https://docs.zephyrproject.org/2.3.0/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded) to install a GNU ARM Embedded build. Note the warnings regarding installing the toolchain into a path with spaces, and make sure to follow the steps to add the environment variables which are also summarized with screenshots in the [Environment Variables](#environment-variables) section below. @@ -308,7 +336,7 @@ 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: +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 @@ -358,12 +386,17 @@ pip3 install --user -r zephyr/scripts/requirements-base.txt ### Environment Variables -#### For GNU ARM Embedded on Windows + + -On Windows, you will have to set two environment variables for ZMK to build properly: `ZEPHYR_TOOLCHAIN_VARIANT` and `GNUARMEMB_TOOLCHAIN_PATH`. +#### For GNU ARM Embedded on Windows -
- Steps to Update Environment Variables +On Windows, only two environment variables need to be set for ZMK to build properly: `ZEPHYR_TOOLCHAIN_VARIANT` and `GNUARMEMB_TOOLCHAIN_PATH`. 1. Open Start Menu and type 'env' to find the 'Edit the system environment variables' option. Open it. @@ -381,11 +414,15 @@ On Windows, you will have to set two environment variables for ZMK to build prop ![Adding Zephyr toolchain variable](assets/env-var/zephyr_toolchain.png) -5. Create another variable with variable name 'GNUARMEMB_TOOLCHAIN_PATH' and value set to wherever you installed your toolchain. Click OK to save. +5. Create another variable with variable name 'GNUARMEMB_TOOLCHAIN_PATH' and value set to wherever you installed your toolchain. **Make sure this path does not contain any spaces.** If it does, rename the folder and update here. Click OK to save. ![Adding GNUARMEMB variable](assets/env-var/gnuarmemb.png) -
+6. Close Command Prompt and reopen, or run `refreshenv` to apply the changes. + + + + #### For Zephyr @@ -396,48 +433,10 @@ We suggest two main [options](https://docs.zephyrproject.org/2.3.0/guides/env_va To load the Zephyr environment properly for just one transient shell, run the following from your ZMK checkout directory: - - - -``` -source zephyr/zephyr-env.sh -``` - - - - - -``` -source zephyr/zephyr-env.sh -``` - - - - - ``` source zephyr/zephyr-env.sh ``` - - - - -``` -source zephyr/zephyr-env.sh -``` - - - - - -``` -source zephyr/zephyr-env.cmd -``` - - - - ##### All Shells To load the environment variables for your shell every time, @@ -469,3 +468,7 @@ cat ~/.zephyrrc >> ~/.zshrc + + + +