From dca81c6579460e2693d07ecaf08cb5ad766484fe Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Mon, 6 Jul 2020 10:22:43 -0400 Subject: [PATCH 1/4] Tweaks for multiple OS stuff. --- docs/docs/dev-setup.md | 198 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 181 insertions(+), 17 deletions(-) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 5741766b..aef09db5 100644 --- a/docs/docs/dev-setup.md +++ b/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) => ({props.children}); + ## Prerequisites A unix-like environment with the following base packages installed: @@ -17,13 +32,13 @@ A unix-like environment with the following base packages installed: - `dfu-util` - Various build essentials, e.g. gcc, automake, autoconf -### Debian/Ubuntu - + + 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 from WSL, +First, if you haven't updated recently, or if this is a new install, you should update to get the latest package information: ```bash @@ -60,41 +75,146 @@ 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. ::: + + +On Raspberry OS, we'll use apt to install our base dependencies: -### Fedora +#### Apt Update -TODO +First, if you haven't updated recently, or if this is a new install, +you should update to get the latest package information: -### macOS +```bash +sudo apt update +``` -TODO +#### Install Dependencies -### WSL +With the latest package information, you can now install the base dependencies: -Windows Subsystem for Linux can use various Linux distributions. Find a WSL installation on the [Windows Store](https://aka.ms/wslstore). +```bash +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 +``` + + + + +On Fedora, we'll use `dnf` to install our base dependencies: + +#### DNF Update -After installing your preferred flavor, follow the directions above on [Debian/Ubuntu](#debianubuntu) or [Fedora](#fedora). +First, if you haven't updated recently, or if this is a new install, +you should update to get the latest package information: + +```bash +sudo dnf update +``` + +#### Install Dependencies + +With the latest package information, you can now install the base dependencies: + +```bash +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 +``` + + + :::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 + ``` + + + + +#### 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 +``` + + + + ## 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. + +West can be installed by using the `pip` python package manager. ```bash -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. + + + + +#### 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 +227,50 @@ 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. + + + +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: + +```bash +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`: + +```bash +export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile +export CROSS_COMPILE=/usr/bin/arm-none-eabi- +``` + + + + +#### 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. + + +Windows instructions are coming soon! + + +Instructions for macOS coming soon. + + + + ### Source Code Next, you'll need to clone the ZMK source repository if you haven't already: From dd34edace1abe74de13621fd1ce14a5181140422 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Tue, 14 Jul 2020 00:12:54 -0400 Subject: [PATCH 2/4] Remaining fixes. --- docs/docs/dev-setup.md | 85 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 81 insertions(+), 4 deletions(-) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index aef09db5..e4abdc95 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -263,10 +263,27 @@ 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. -Windows instructions are coming soon! + + +#### 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). + + -Instructions for macOS coming soon. +#### 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. @@ -330,27 +347,87 @@ 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: + + + +``` +source zephyr/zephyr-env.sh +``` + + + + + +``` +source zephyr/zephyr-env.sh +``` + + + + + ``` source zephyr/zephyr-env.sh ``` + + + + +``` +source zephyr/zephyr-env.sh +``` + + + + + +``` +source zephyr/zephyr-env.cmd +``` + + + + #### 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 + + + ``` cat ~/.zephyrrc >> ~/.bashrc ``` -##### ZSH + + + ``` cat ~/.zephyrrc >> ~/.zshrc ``` + + + + +`cmd.exe` instructions coming soon! + + + + + ## Build From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout: From 8dcb03faa653246bc1e8f5e912f4c1106e380567 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Tue, 14 Jul 2020 06:40:53 -0400 Subject: [PATCH 3/4] Tweaks for highlighting. --- docs/docs/dev-setup.md | 42 +++++++++++++++++------------------------- 1 file changed, 17 insertions(+), 25 deletions(-) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index e4abdc95..8f3e3ddd 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -36,20 +36,16 @@ A unix-like environment with the following base packages installed: 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, 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 \ @@ -79,20 +75,16 @@ or download and install CMake version 3.13.1 or newer manually. On Raspberry OS, 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, 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 \ @@ -124,7 +116,7 @@ On Fedora, we'll use `dnf` 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: -```bash +```sh sudo dnf update ``` @@ -132,7 +124,7 @@ sudo dnf update With the latest package information, you can now install the base dependencies: -```bash +```sh sudo dnf install -y \ git \ wget \ @@ -192,7 +184,7 @@ brew install cmake ninja python3 ccache dtc git wget West can be installed by using the `pip` python package manager. -```bash +```sh pip3 install --user -U west ``` @@ -235,13 +227,13 @@ the operating system's installed [cross compilers](https://docs.zephyrproject.or First, the cross compiler should be installed: -```bash +```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`: -```bash +```sh export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile export CROSS_COMPILE=/usr/bin/arm-none-eabi- ``` @@ -304,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/ ``` @@ -322,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 ``` @@ -432,7 +424,7 @@ cat ~/.zephyrrc >> ~/.zshrc From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout: -```bash +```sh cd app ``` @@ -451,7 +443,7 @@ Given the following: You can build ZMK with the following: -```bash +```sh west build -b proton_c -- -DSHIELD=kyria -DKEYMAP=default ``` @@ -466,7 +458,7 @@ Given the following: you can build ZMK with the following: -```bash +```sh west build -b planck -- -DKEYMAP=default ``` From c23c44a4c4edf81fdc420c669fb889fdc3efaef1 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Tue, 14 Jul 2020 10:24:51 -0400 Subject: [PATCH 4/4] Fix the default OS tab. --- docs/docs/dev-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 8f3e3ddd..beabca46 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -9,7 +9,7 @@ import TabItem from '@theme/TabItem'; export const OsTabs = (props) => (