pwarren/zmk_mf68
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #240 from chenkevinh/windows_setup

Browse source 
docs: Fixed Windows setup instructions
This commit is contained in:
Pete Johanson 2020-10-04 22:48:48 -04:00 committed by GitHub
commit 9249d2f4b7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 58 additions and 54 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

112
docs/docs/dev-setup.md
View file

@ -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}</Tabs>);
## 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:
<OsTabs>
<TabItem value="debian">
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.
:::
</TabItem>
<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,
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 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
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.
</TabItem>
<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
@ -213,7 +241,8 @@ source ~/.bashrc
<TabItem value = 'win'>
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>
</Tabs>
@ -279,7 +308,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.
</TabItem>
<TabItem value="mac">
@ -308,7 +337,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 +387,17 @@ pip3 install --user -r zephyr/scripts/requirements-base.txt
### Environment Variables
<Tabs
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'Other OS', value: 'other'},
]}>
<TabItem value = 'win'>
#### 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`.
<details>
<summary> Steps to Update Environment Variables </summary>
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 +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)
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)
</details>
6. Close Command Prompt and reopen, or run `refreshenv` to apply the changes.
</TabItem>
<TabItem value = 'other'>
#### 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:
<OsTabs>
<TabItem value="debian">
```
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
To load the environment variables for your shell every time,
@ -469,3 +469,7 @@ cat ~/.zephyrrc >> ~/.zshrc
</TabItem>
</Tabs>
</TabItem>
</Tabs>