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

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

Multiple OS tabs for dev setup instructions
xmkb
Pete Johanson 4 years ago committed by GitHub
parent
4ab6132f70 c23c44a4c4
commit
c5b45039f6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 267 additions and 34 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. 301
      docs/docs/dev-setup.md

301
docs/docs/dev-setup.md
Unescape 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:
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 apt update
```
With the latest package information, you can now install the base dependencies:
### Fedora ```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
```
TODO </TabItem>
<TabItem value="fedora">
### macOS On Fedora, we'll use `dnf` to install our base dependencies:
TODO #### DNF Update
### WSL First, if you haven't updated recently, or if this is a new install,
you should update to get the latest package information:
Windows Subsystem for Linux can use various Linux distributions. Find a WSL installation on the [Windows Store](https://aka.ms/wslstore). ```sh
sudo dnf update
```
After installing your preferred flavor, follow the directions above on [Debian/Ubuntu](#debianubuntu) or [Fedora](#fedora). #### 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.
West can be installed by using the `pip` python package manager.
```bash ```sh
pip3 install --user west 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
```
</TabItem>
<TabItem value="raspberryos">
``` ```
source zephyr/zephyr-env.sh 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
``` ```

Write Preview
Loading…
Cancel
Save