Merge branch 'main' of github.com:zmkfirmware/zmk into main

docs/docs/dev-setup.md

@@ -4,6 +4,21 @@ title: 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
 
 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`
 - 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:
 
-#### 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:
 
-```bash
+```sh
 sudo apt update
 ```
 
-#### Install Dependencies
-
 With the latest package information, you can now install the base dependencies:
 
-```bash
+```sh
 sudo apt install -y \
 	git \
 	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
 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
+```
+
+</TabItem>
+<TabItem value="fedora">
+
+On Fedora, we'll use `dnf` to install our base dependencies:
 
-### WSL
+#### DNF Update
 
-Windows Subsystem for Linux can use various Linux distributions. Find a WSL installation on the [Windows Store](https://aka.ms/wslstore).
+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
+```
 
-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
-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
 
 ### 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:
 
@@ -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.
 
+</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
 
 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
 
-```bash
+```sh
 cd zmk
 ```
 
 #### Initialize West
 
-```bash
+```sh
 west init -l app/
 ```
 
@@ -141,19 +314,19 @@ section again for links to how to do this
 
 #### Update To Fetch Modules
 
-```bash
+```sh
 west update
 ```
 
 #### Export Zephyr™ Core
 
-```bash
+```sh
 west zephyr-export
 ```
 
 #### Install Zephyr Python Dependencies
 
-```bash
+```sh
 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:
 
+<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,
 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
 ```
 
-##### ZSH
+</TabItem>
+
+<TabItem value="zsh">
 
 ```
 cat ~/.zephyrrc >> ~/.zshrc
 ```
 
+</TabItem>
+
+<TabItem value="cmd">
+
+`cmd.exe` instructions coming soon!
+
+</TabItem>
+
+</Tabs>
+
 ## Build
 
 From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout:
 
-```bash
+```sh
 cd app
 ```
 
@@ -210,7 +443,7 @@ Given the following:
 
 You can build ZMK with the following:
 
-```bash
+```sh
 west build -b proton_c -- -DSHIELD=kyria -DKEYMAP=default
 ```
 
@@ -225,7 +458,7 @@ Given the following:
 
 you can build ZMK with the following:
 
-```bash
+```sh
 west build -b planck -- -DKEYMAP=default
 ```