Merge pull request #240 from chenkevinh/windows_setup
docs: Fixed Windows setup instructions
This commit is contained in:
commit
9249d2f4b7
1 changed files with 58 additions and 54 deletions
|
@ -12,16 +12,16 @@ groupId="operating-systems"
|
||||||
defaultValue="debian"
|
defaultValue="debian"
|
||||||
values={[
|
values={[
|
||||||
{label: 'Debian/Ubuntu', value: 'debian'},
|
{label: 'Debian/Ubuntu', value: 'debian'},
|
||||||
{label: 'Raspberry OS', value: 'raspberryos'},
|
|
||||||
{label: 'Fedora', value: 'fedora'},
|
|
||||||
{label: 'Windows', value: 'win'},
|
{label: 'Windows', value: 'win'},
|
||||||
{label: 'macOS', value: 'mac'},
|
{label: 'macOS', value: 'mac'},
|
||||||
|
{label: 'Raspberry OS', value: 'raspberryos'},
|
||||||
|
{label: 'Fedora', value: 'fedora'},
|
||||||
]
|
]
|
||||||
}>{props.children}</Tabs>);
|
}>{props.children}</Tabs>);
|
||||||
|
|
||||||
## Prerequisites
|
## Prerequisites
|
||||||
|
|
||||||
A unix-like environment with the following base packages installed:
|
ZMK requires the following base packages to first be installed:
|
||||||
|
|
||||||
- Git
|
- Git
|
||||||
- Python 3
|
- Python 3
|
||||||
|
@ -34,6 +34,7 @@ A unix-like environment with the following base packages installed:
|
||||||
|
|
||||||
<OsTabs>
|
<OsTabs>
|
||||||
<TabItem value="debian">
|
<TabItem value="debian">
|
||||||
|
|
||||||
On Debian and Ubuntu, we'll use `apt` to install our base dependencies:
|
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,
|
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.
|
||||||
:::
|
:::
|
||||||
</TabItem>
|
</TabItem>
|
||||||
<TabItem value="raspberryos">
|
<TabItem value="raspberryos">
|
||||||
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,
|
First, if you haven't updated recently, or if this is a new install,
|
||||||
you should update to get the latest package information:
|
you should update to get the latest package information:
|
||||||
|
@ -185,14 +187,40 @@ 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` 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:
|
||||||
|
|
||||||
|
<Tabs
|
||||||
|
defaultValue="linux"
|
||||||
|
values={[
|
||||||
|
{label: 'Linux', value: 'linux'},
|
||||||
|
{label: 'Windows', value: 'win'},
|
||||||
|
]}>
|
||||||
|
<TabItem value = 'linux'>
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
pip3 install --user -U west
|
pip3 install --user -U west
|
||||||
```
|
```
|
||||||
|
|
||||||
:::danger pip user packages
|
</TabItem>
|
||||||
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.
|
<TabItem value = 'win'>
|
||||||
|
|
||||||
|
In `cmd.exe` as **Administrator**:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
pip3 install -U west
|
||||||
|
```
|
||||||
|
|
||||||
|
:::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.
|
||||||
|
:::
|
||||||
|
|
||||||
|
Once `west` is installed, close Command Prompt and open a new session as a **user** for the remainder of the instructions.
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
:::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.
|
||||||
:::
|
:::
|
||||||
|
|
||||||
<Tabs
|
<Tabs
|
||||||
|
@ -213,7 +241,8 @@ source ~/.bashrc
|
||||||
<TabItem value = 'win'>
|
<TabItem value = 'win'>
|
||||||
|
|
||||||
1. See the [Environment Variables](#environment-variables) section on how to get to the Environment Variables page.
|
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`.
|
||||||
|
|
||||||
</TabItem>
|
</TabItem>
|
||||||
</Tabs>
|
</Tabs>
|
||||||
|
@ -279,7 +308,7 @@ The installation will prompt with several questions about installation location,
|
||||||
|
|
||||||
#### GNU ARM Embedded
|
#### 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.
|
||||||
|
|
||||||
</TabItem>
|
</TabItem>
|
||||||
<TabItem value="mac">
|
<TabItem value="mac">
|
||||||
|
@ -308,7 +337,7 @@ The transient instructions must be run to build firmware using the current shell
|
||||||
|
|
||||||
### Source Code
|
### 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
|
git clone https://github.com/zmkfirmware/zmk.git
|
||||||
|
@ -358,12 +387,17 @@ pip3 install --user -r zephyr/scripts/requirements-base.txt
|
||||||
|
|
||||||
### Environment Variables
|
### Environment Variables
|
||||||
|
|
||||||
|
<Tabs
|
||||||
|
defaultValue="win"
|
||||||
|
values={[
|
||||||
|
{label: 'Windows', value: 'win'},
|
||||||
|
{label: 'Other OS', value: 'other'},
|
||||||
|
]}>
|
||||||
|
<TabItem value = 'win'>
|
||||||
|
|
||||||
#### For GNU ARM Embedded on Windows
|
#### 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`.
|
On Windows, only two environment variables need to be set for ZMK to build properly: `ZEPHYR_TOOLCHAIN_VARIANT` and `GNUARMEMB_TOOLCHAIN_PATH`.
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary> Steps to Update Environment Variables </summary>
|
|
||||||
|
|
||||||
1. Open Start Menu and type 'env' to find the 'Edit the system environment variables' option. Open it.
|
1. Open Start Menu and type 'env' to find the 'Edit the system environment variables' option. Open it.
|
||||||
|
|
||||||
|
@ -381,11 +415,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)
|
![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)
|
![Adding GNUARMEMB variable](assets/env-var/gnuarmemb.png)
|
||||||
|
|
||||||
</details>
|
6. Close Command Prompt and reopen, or run `refreshenv` to apply the changes.
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
|
||||||
|
<TabItem value = 'other'>
|
||||||
|
|
||||||
#### For Zephyr
|
#### For Zephyr
|
||||||
|
|
||||||
|
@ -396,48 +434,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:
|
To load the Zephyr environment properly for just one transient shell, run the following from your ZMK checkout directory:
|
||||||
|
|
||||||
<OsTabs>
|
|
||||||
<TabItem value="debian">
|
|
||||||
|
|
||||||
```
|
```
|
||||||
source zephyr/zephyr-env.sh
|
source zephyr/zephyr-env.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
</TabItem>
|
|
||||||
|
|
||||||
<TabItem value="raspberryos">
|
|
||||||
|
|
||||||
```
|
|
||||||
source zephyr/zephyr-env.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
</TabItem>
|
|
||||||
|
|
||||||
<TabItem value="fedora">
|
|
||||||
|
|
||||||
```
|
|
||||||
source zephyr/zephyr-env.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
</TabItem>
|
|
||||||
|
|
||||||
<TabItem value="mac">
|
|
||||||
|
|
||||||
```
|
|
||||||
source zephyr/zephyr-env.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
</TabItem>
|
|
||||||
|
|
||||||
<TabItem value="win">
|
|
||||||
|
|
||||||
```
|
|
||||||
source zephyr/zephyr-env.cmd
|
|
||||||
```
|
|
||||||
|
|
||||||
</TabItem>
|
|
||||||
</OsTabs>
|
|
||||||
|
|
||||||
##### All Shells
|
##### All Shells
|
||||||
|
|
||||||
To load the environment variables for your shell every time,
|
To load the environment variables for your shell every time,
|
||||||
|
@ -469,3 +469,7 @@ cat ~/.zephyrrc >> ~/.zshrc
|
||||||
</TabItem>
|
</TabItem>
|
||||||
|
|
||||||
</Tabs>
|
</Tabs>
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
Loading…
Reference in a new issue