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

Merge pull request #55 from petejohanson/docs/multiple-os-setup-docs

Browse source 
Multiple OS tabs for dev setup instructions
This commit is contained in:
Pete Johanson 2020-07-14 16:46:08 -04:00 committed by GitHub
commit c5b45039f6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 267 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -4,6 +4,21 @@ title: Basic Setup
sidebar_label: Basic Setup sidebar_label: Basic Setup
--- ---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
export const OsTabs = (props) => (<Tabs
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'},
]
}>{props.children}</Tabs>);
## Prerequisites ## Prerequisites
A unix-like environment with the following base packages installed: A unix-like environment with the following base packages installed:
@ -17,24 +32,20 @@ A unix-like environment with the following base packages installed:
- `dfu-util` - `dfu-util`
- Various build essentials, e.g. gcc, automake, autoconf - Various build essentials, e.g. gcc, automake, autoconf
### Debian/Ubuntu <OsTabs>
<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:
#### Apt Update 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 from WSL,
you should update to get the latest package information: you should update to get the latest package information:
```bash ```sh
sudo apt update sudo apt update
``` ```
#### Install Dependencies
With the latest package information, you can now install the base dependencies: With the latest package information, you can now install the base dependencies:
```bash ```sh
sudo apt install -y \ sudo apt install -y \
git \ git \
wget \ wget \
@ -60,41 +71,142 @@ sudo apt install -y \
Ubuntu 18.04 LTS release packages a version of CMake that is too old. Please upgrade to Ubuntu 20.04 LTS Ubuntu 18.04 LTS release packages a version of CMake that is too old. Please upgrade to Ubuntu 20.04 LTS
or download and install CMake version 3.13.1 or newer manually. 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:
### Fedora First, if you haven't updated recently, or if this is a new install,
you should update to get the latest package information:
TODO ```sh
sudo apt update
```
### macOS With the latest package information, you can now install the base dependencies:
TODO ```sh
sudo apt install -y \
git \
wget \
autoconf \
automake \
build-essential \
ccache \
device-tree-compiler \
dfu-util \
g++ \
gcc \
libtool \
make \
ninja-build \
cmake \
python3-dev \
python3-pip \
python3-setuptools \
xz-utils
```
### WSL </TabItem>
<TabItem value="fedora">
Windows Subsystem for Linux can use various Linux distributions. Find a WSL installation on the [Windows Store](https://aka.ms/wslstore). On Fedora, we'll use `dnf` to install our base dependencies:
After installing your preferred flavor, follow the directions above on [Debian/Ubuntu](#debianubuntu) or [Fedora](#fedora). #### DNF Update
First, if you haven't updated recently, or if this is a new install,
you should update to get the latest package information:
```sh
sudo dnf update
```
#### Install Dependencies
With the latest package information, you can now install the base dependencies:
```sh
sudo dnf install -y \
git \
wget \
autoconf \
automake \
ccache \
dtc \
dfu-util \
g++ \
gcc \
libtool \
make \
ninja-build \
cmake \
python3-devel \
python3-pip \
python3-setuptools \
xz
```
</TabItem>
<TabItem value="win">
:::note :::note
On WSL2 don't put the project files into `/mnt/c/` as file I/O speeds are extremely slow. Instead, run everything in the Linux system and use `cp` to move files over to `/mnt/c/` as needed. Use `cmd.exe` with these instructions rather than PowerShell.
::: :::
Chocolatey is recommended and used for the following instructions. You can manually install each of these applications and add them to your `PATH` if you don't want to use Chocolatey.
1. [Install Chocolatey](https://chocolatey.org/install)
2. Open `cmd.exe` as **Administrator**
3. Run the following `choco` commands:
```shell
choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
choco install ninja gperf python git
```
</TabItem>
<TabItem value="mac">
#### Homebrew
Homebrew is required to install the system dependencies. If you haven't done so, visit [Homebrew](https://brew.sh/) for instructions. Once installed, use it to install the base dependencies:
```
brew install cmake ninja python3 ccache dtc git wget
```
</TabItem>
</OsTabs>
## Setup ## Setup
### West Build Command ### West Build Command
`west` is the [Zephyr™ meta-tool](https://docs.zephyrproject.org/latest/guides/west/index.html) used to configure and build Zephyr™ applications. It can be installed by using the `pip` python package manager: `west` is the [Zephyr™ meta-tool](https://docs.zephyrproject.org/latest/guides/west/index.html) used to configure and build Zephyr™ applications.
```bash West can be installed by using the `pip` python package manager.
pip3 install --user west
```sh
pip3 install --user -U west
```
:::tip pip user packages
If you haven't done so yet, you may need to add the Python Pip user package directory to your `PATH`, e.g.:
```
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
``` ```
:::note
If you don't already have it configured, you may need to update your
`PATH` to include the pip install path. See [User Installs](https://pip.pypa.io/en/stable/user_guide/#user-installs) and [Stack Overflow](https://stackoverflow.com/questions/38112756/how-do-i-access-packages-installed-by-pip-user) for more details.
::: :::
### Zephyr™ ARM SDK ### Toolchain Installation
The toolchain provides the compiler, linker, etc necessary to build for the target
platform.
<OsTabs>
<TabItem value="debian">
#### Zephyr™ ARM SDK
To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr™ ARM SDK to your system: To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr™ ARM SDK to your system:
@ -107,6 +219,67 @@ wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_
The installation will prompt with several questions about installation location, and creating a default `~/.zephyrrc` for you with various variables. The defaults shouldn normally work as expected. The installation will prompt with several questions about installation location, and creating a default `~/.zephyrrc` for you with various variables. The defaults shouldn normally work as expected.
</TabItem>
<TabItem value="raspberryos">
Because Raspberry OS (Raspbian) runs on the same architecture (but different ABI) as the keyboard MCUs,
the operating system's installed [cross compilers](https://docs.zephyrproject.org/latest/getting_started/toolchain_other_x_compilers.html) can be used to target the different ABI.
First, the cross compiler should be installed:
```sh
sudo apt install gcc-arm-none-eabi
```
Next, we'll configure Zephyr™ with some extra environment variables needed to find the cross compiler by adding the following to `~/.zephyrrc`:
```sh
export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
export CROSS_COMPILE=/usr/bin/arm-none-eabi-
```
</TabItem>
<TabItem value="fedora">
#### Zephyr™ ARM SDK
To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr™ ARM SDK to your system:
```
export ZSDK_VERSION=0.11.2
wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" && \
sh "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" --quiet -- -d ~/.local/zephyr-sdk-${ZSDK_VERSION} && \
rm "zephyr-toolchain-arm-\${ZSDK_VERSION}-setup.run"
```
The installation will prompt with several questions about installation location, and creating a default `~/.zephyrrc` for you with various variables. The defaults shouldn normally work as expected.
</TabItem>
<TabItem value="win">
#### 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/latest/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded).
</TabItem>
<TabItem value="mac">
#### Zephyr™ ARM SDK
To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr™ ARM SDK to your system:
```
export ZSDK_VERSION=0.11.2
wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" && \
sh "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" --quiet -- -d ~/.local/zephyr-sdk-${ZSDK_VERSION} && \
rm "zephyr-toolchain-arm-\${ZSDK_VERSION}-setup.run"
```
The installation will prompt with several questions about installation location, and creating a default `~/.zephyrrc` for you with various variables. The defaults shouldn normally work as expected.
</TabItem>
</OsTabs>
### 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:
@ -123,13 +296,13 @@ Zephyr™ application is in the `app/` source directory:
#### Step into the repository #### Step into the repository
```bash ```sh
cd zmk cd zmk
``` ```
#### Initialize West #### Initialize West
```bash ```sh
west init -l app/ west init -l app/
``` ```
@ -141,19 +314,19 @@ section again for links to how to do this
#### Update To Fetch Modules #### Update To Fetch Modules
```bash ```sh
west update west update
``` ```
#### Export Zephyr™ Core #### Export Zephyr™ Core
```bash ```sh
west zephyr-export west zephyr-export
``` ```
#### Install Zephyr Python Dependencies #### Install Zephyr Python Dependencies
```bash ```sh
pip3 install --user -r zephyr/scripts/requirements-base.txt pip3 install --user -r zephyr/scripts/requirements-base.txt
``` ```
@ -166,32 +339,92 @@ We suggest two main [options](https://docs.zephyrproject.org/latest/guides/env_v
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,
append the existing `~/.zephyrrc` file to your shell's RC file and then start a new shell. append the existing `~/.zephyrrc` file to your shell's RC file and then start a new shell.
##### Bash <Tabs
groupId="shell"
defaultValue="bash"
values={[
{label: 'bash', value: 'bash'},
{label: 'zsh', value: 'zsh'},
{label: 'cmd.exe', value: 'cmd'},
]
}>
<TabItem value="bash">
``` ```
cat ~/.zephyrrc >> ~/.bashrc cat ~/.zephyrrc >> ~/.bashrc
``` ```
##### ZSH </TabItem>
<TabItem value="zsh">
``` ```
cat ~/.zephyrrc >> ~/.zshrc cat ~/.zephyrrc >> ~/.zshrc
``` ```
</TabItem>
<TabItem value="cmd">
`cmd.exe` instructions coming soon!
</TabItem>
</Tabs>
## Build ## Build
From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout: From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout:
```bash ```sh
cd app cd app
``` ```
@ -210,7 +443,7 @@ Given the following:
You can build ZMK with the following: You can build ZMK with the following:
```bash ```sh
west build -b proton_c -- -DSHIELD=kyria -DKEYMAP=default west build -b proton_c -- -DSHIELD=kyria -DKEYMAP=default
``` ```
@ -225,7 +458,7 @@ Given the following:
you can build ZMK with the following: you can build ZMK with the following:
```bash ```sh
west build -b planck -- -DKEYMAP=default west build -b planck -- -DKEYMAP=default
``` ```