xenua
/
zmk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

Merge pull request #240 from chenkevinh/windows_setup 

docs: Fixed Windows setup instructions
xmkb
Pete Johanson 4 years ago committed by GitHub
parent
222515f091 6427e64df3
commit
9249d2f4b7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 58 additions and 54 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 112
      docs/docs/dev-setup.md

112
docs/docs/dev-setup.md
Unescape View File

@ -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
#### For GNU ARM Embedded on Windows <Tabs
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'Other OS', value: 'other'},
]}>
<TabItem value = 'win'>
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
<details> On Windows, only two environment variables need to be set for ZMK to build properly: `ZEPHYR_TOOLCHAIN_VARIANT` and `GNUARMEMB_TOOLCHAIN_PATH`.
<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
```
</TabItem>
<TabItem value="raspberryos">
```
source zephyr/zephyr-env.sh
```
</TabItem>
<TabItem value="fedora">
``` ```
source zephyr/zephyr-env.sh 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>

Write Preview
Loading…
Cancel
Save