From 308d6bce6eb338f387a454c7366d0bcb07463d7b Mon Sep 17 00:00:00 2001 From: Nicolas Munnich <98408764+Nick-Munnich@users.noreply.github.com> Date: Sun, 2 Jun 2024 06:51:08 +0200 Subject: [PATCH] feat(docs): Improve the toolchain setup page (#2272) Split the toolchain setup into separate docker and native pages and improve instructions to better refer to Zephyr docs in certain steps. Also refactor to improve consistency and add virtualenv instructions. --------- Co-authored-by: KemoNine Co-authored-by: Cem Aksoylar --- docs/blog/2020-08-12-zmk-sotf-1.md | 2 +- docs/blog/2021-07-17-zephyr-2-5.md | 2 +- docs/blog/2022-04-02-zephyr-3-0.md | 2 +- docs/blog/2022-04-10-zmk-sotf-5.md | 2 +- docs/blog/2023-04-06-zephyr-3-2.md | 2 +- docs/blog/2024-02-09-zephyr-3-5.md | 2 +- docs/docs/behaviors/index.mdx | 8 +- docs/docs/customization.md | 2 +- docs/docs/development/new-shield.mdx | 4 +- docs/docs/development/setup.mdx | 322 ---------------------- docs/docs/development/setup/docker.md | 53 ++++ docs/docs/development/setup/index.md | 20 ++ docs/docs/development/setup/native.mdx | 353 +++++++++++++++++++++++++ docs/docs/troubleshooting.md | 2 +- docs/docusaurus.config.js | 3 +- docs/sidebars.js | 11 +- docs/src/css/custom.css | 4 + 17 files changed, 456 insertions(+), 338 deletions(-) delete mode 100644 docs/docs/development/setup.mdx create mode 100644 docs/docs/development/setup/docker.md create mode 100644 docs/docs/development/setup/index.md create mode 100644 docs/docs/development/setup/native.mdx diff --git a/docs/blog/2020-08-12-zmk-sotf-1.md b/docs/blog/2020-08-12-zmk-sotf-1.md index afa03405a70..89cfffabe65 100644 --- a/docs/blog/2020-08-12-zmk-sotf-1.md +++ b/docs/blog/2020-08-12-zmk-sotf-1.md @@ -19,7 +19,7 @@ There's been lots of various activity in ZMK land! - Tons of [documentation](/docs) work. - Refactoring ([#73](https://github.com/zmkfirmware/zmk/pull/73), [#74](https://github.com/zmkfirmware/zmk/pull/74)) of [keymaps](/docs/features/keymaps) to make them simpler for users. - Mod-Tap Behavior (docs coming!) is much improved ([#69](https://github.com/zmkfirmware/zmk/pull/69)) and usable now. -- An initial [`setup.sh`](http://localhost:3000/docs/user-setup#user-config-setup-script) script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you. +- An initial [`setup.sh`](/docs/user-setup#user-config-setup-script) script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you. - Corne shield ([#80](https://github.com/zmkfirmware/zmk/pull/80)) shield definition was added. - Initial [encoder](/docs/features/encoders) support ([#61](https://github.com/zmkfirmware/zmk/pull/61)) was added. diff --git a/docs/blog/2021-07-17-zephyr-2-5.md b/docs/blog/2021-07-17-zephyr-2-5.md index 153027bb4cd..789a644caee 100644 --- a/docs/blog/2021-07-17-zephyr-2-5.md +++ b/docs/blog/2021-07-17-zephyr-2-5.md @@ -61,7 +61,7 @@ Once the container has rebuilt, VS Code will be running the 2.5 Docker image. The following steps will get you building ZMK locally against Zephyr 2.5: -- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work) +- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work) - pull the latest ZMK `main` with `git pull` for your ZMK checkout - run `west update` to pull the updated Zephyr version and its dependencies diff --git a/docs/blog/2022-04-02-zephyr-3-0.md b/docs/blog/2022-04-02-zephyr-3-0.md index 3b16b87ea78..92e8b33bc1c 100644 --- a/docs/blog/2022-04-02-zephyr-3-0.md +++ b/docs/blog/2022-04-02-zephyr-3-0.md @@ -62,7 +62,7 @@ Once the container has rebuilt, VS Code will be running the 3.0 Docker image. The following steps will get you building ZMK locally against Zephyr 3.0: -- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work) +- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work) - pull the latest ZMK `main` with `git pull` for your ZMK checkout - run `west update` to pull the updated Zephyr version and its dependencies diff --git a/docs/blog/2022-04-10-zmk-sotf-5.md b/docs/blog/2022-04-10-zmk-sotf-5.md index 43cb4e67209..1a0ea270c8d 100644 --- a/docs/blog/2022-04-10-zmk-sotf-5.md +++ b/docs/blog/2022-04-10-zmk-sotf-5.md @@ -132,7 +132,7 @@ Another persistent bug that Apple users experienced was related to crashes and p The long awaited locality enhancement was finally merged by [petejohanson] in [#547](https://github.com/zmkfirmware/zmk/pull/547), allowing more fine grained control of where certain behaviors are invoked. Some key improvements thanks to the changes: - [RGB Underglow](/docs/features/underglow) behaviors now run globally, so enabling/disabling RGB, changing the color, animation, etc. applies to both sides of a split properly. -- [Reset](/docs/behaviors/reset#reset)/[Bootloader](/docs/behaviors/reset#bootloader) behaviors now run wherever the key was pressed. For example, adding a `&bootloader` reference to the peripheral side of a split will now put that side of the split into the bootloader when pressed. +- [Reset](/docs/behaviors/reset#reset)/[Bootloader](/docs/behaviors/reset#bootloader-reset) behaviors now run wherever the key was pressed. For example, adding a `&bootloader` reference to the peripheral side of a split will now put that side of the split into the bootloader when pressed. #### Split Connections diff --git a/docs/blog/2023-04-06-zephyr-3-2.md b/docs/blog/2023-04-06-zephyr-3-2.md index 4bb21999422..21058ca9544 100644 --- a/docs/blog/2023-04-06-zephyr-3-2.md +++ b/docs/blog/2023-04-06-zephyr-3-2.md @@ -87,7 +87,7 @@ Once the container has rebuilt, VS Code will be running the 3.2 Docker image. The following steps will get you building ZMK locally against Zephyr 3.2: -- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work) +- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work) - Install the latest version of `west` by running `pip3 install --user --update west`. - pull the latest ZMK `main` with `git pull` for your ZMK checkout - run `west update` to pull the updated Zephyr version and its dependencies diff --git a/docs/blog/2024-02-09-zephyr-3-5.md b/docs/blog/2024-02-09-zephyr-3-5.md index b3fec6cbda2..738f22daa81 100644 --- a/docs/blog/2024-02-09-zephyr-3-5.md +++ b/docs/blog/2024-02-09-zephyr-3-5.md @@ -70,7 +70,7 @@ Once the container has rebuilt, VS Code will be running the 3.5 Docker image. The following steps will get you building ZMK locally against Zephyr 3.5: -- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work) +- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work) - Install the latest version of `west` by running `pip3 install --user --update west`. - Pull the latest ZMK `main` with `git pull` for your ZMK checkout - Run `west update` to pull the updated Zephyr version and its dependencies diff --git a/docs/docs/behaviors/index.mdx b/docs/docs/behaviors/index.mdx index 4a05f5653a0..7cd82d3e4b8 100644 --- a/docs/docs/behaviors/index.mdx +++ b/docs/docs/behaviors/index.mdx @@ -46,10 +46,10 @@ Below is a summary of pre-defined behavior bindings and user-definable behaviors ## Reset behaviors -| Binding | Behavior | Description | -| ------------- | --------------------------------- | ---------------------------------------------------------------------------------------- | -| `&sys_reset` | [Reset](reset.md#reset) | Resets the keyboard and re-runs the firmware flashed to the device | -| `&bootloader` | [Bootloader](reset.md#bootloader) | Resets the keyboard and puts it into bootloader mode, allowing you to flash new firmware | +| Binding | Behavior | Description | +| ------------- | --------------------------------------- | ---------------------------------------------------------------------------------------- | +| `&sys_reset` | [Reset](reset.md#reset) | Resets the keyboard and re-runs the firmware flashed to the device | +| `&bootloader` | [Bootloader](reset.md#bootloader-reset) | Resets the keyboard and puts it into bootloader mode, allowing you to flash new firmware | ## Output selection behaviors diff --git a/docs/docs/customization.md b/docs/docs/customization.md index 46427b9e2f9..96b5e4ea9a0 100644 --- a/docs/docs/customization.md +++ b/docs/docs/customization.md @@ -40,7 +40,7 @@ If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https: ::: :::note -It is also possible to build firmware locally on your computer by following the [toolchain setup](development/setup.mdx) and +It is also possible to build firmware locally on your computer by following the [toolchain setup](development/setup/index.md) and [building instructions](development/build-flash.mdx), which includes pointers to [building using your `zmk-config` folder](development/build-flash.mdx#building-from-zmk-config-folder). ::: diff --git a/docs/docs/development/new-shield.mdx b/docs/docs/development/new-shield.mdx index a542fc84995..d48e0d1de97 100644 --- a/docs/docs/development/new-shield.mdx +++ b/docs/docs/development/new-shield.mdx @@ -554,7 +554,7 @@ Add additional bindings as necessary to match the default number of encoders on ### GitHub Actions -Using GitHub Actions to build your new firmware can save you from doing any local [development setup](./setup.mdx), +Using GitHub Actions to build your new firmware can save you from doing any local [development setup](./setup/index.md), at the expense of a longer feedback loop if there are issues. To push your changes and trigger a build: - Add all your pending changes with `git add .` @@ -566,7 +566,7 @@ Once pushed, click on the "Actions" tab of the repo you created in the first ste ### Local Build :::note -To build locally, be sure you've followed the [development setup](./setup.mdx) guide first. +To build locally, be sure you've followed the [development setup](./setup/index.md) guide first. ::: Once you've fully created the new keyboard shield definition, diff --git a/docs/docs/development/setup.mdx b/docs/docs/development/setup.mdx deleted file mode 100644 index bc275804cf7..00000000000 --- a/docs/docs/development/setup.mdx +++ /dev/null @@ -1,322 +0,0 @@ ---- -title: Toolchain Setup -sidebar_label: Toolchain Setup ---- - -import Tabs from "@theme/Tabs"; -import TabItem from "@theme/TabItem"; - -export const OsTabs = (props) => ( - - {/* eslint-disable-next-line */} - {props.children} - -); - -This guide will show you how to set up a development environment for building ZMK locally. - -## Install Dependencies - -Click the operating system you are using. (The VS Code & Docker option can be used on any OS.) - - - - -This option use the same [Docker image which is used by the GitHub action](https://github.com/zmkfirmware/zmk-docker) for local development. Beyond the benefits of [dev/prod parity](https://12factor.net/dev-prod-parity), this approach is also the easiest to set up. No toolchain or dependencies are necessary when using Docker; the container image you'll be using already has the toolchain installed and set up to use. - -1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system. -2. Install [Visual Studio Code](https://code.visualstudio.com/) -3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) - -:::info -The docker container already includes `west`. Skip past the following section to [Get Source Code](#get-source-code). -::: - - - - -Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections: - -- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os) -- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies) -- [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk) - -Return to this guide once you are finished with each section. - - - - -Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections: - -- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os) -- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies) -- [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk) - -Return to this guide once you are finished with each section. - -`dfu-util` is required to flash devices that use DFU, but there is currently no maintained package for it on Chocolatey. [QMK Toolbox](https://github.com/qmk/qmk_toolbox) contains a working version of it though. - - - - -Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections: - -- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os) -- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies) -- [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk) - -Return to this guide once you are finished with each section. - - - - -#### Install Base Dependencies - -Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions for Ubuntu under these sections: - -- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os) -- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies) - -Return to this guide once you are finished with each section. - -#### Install Cross-Compile Toolchain - -Because Raspberry OS runs on the same architecture (but different ABI) as ARM keyboard MCUs, the operating system's installed [cross compilers](https://docs.zephyrproject.org/3.5.0/develop/toolchains/other_x_compilers.html) can be used to target the different ABI. Building for non-ARM MCUs has not been tested. - -First, the cross compiler should be installed: - -```sh -sudo apt install gcc-arm-none-eabi -``` - -Next, we'll configure Zephyr with some [environment variables](https://docs.zephyrproject.org/3.5.0/develop/env_vars.html#env-vars) needed to find the cross compiler. Create a file named `~/.zephyrrc` if it doesn't exist, and add these lines to it: - -```sh -export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile -export CROSS_COMPILE=/usr/bin/arm-none-eabi- -``` - - - - -Follow Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/installation_linux.html) documentation for Fedora. - - - - -### Install West - -`west` is the [Zephyr® Project's meta-tool](https://docs.zephyrproject.org/3.5.0/develop/west/index.html) used to configure and build Zephyr OS applications. - -West can be installed by using the `pip` python package manager. The [Zephyr™ instructions](https://docs.zephyrproject.org/3.5.0/develop/west/install.html) are summarized here: - - - - -Install west: - -```sh -pip3 install --user -U west -``` - -Verify that west is installed: - -```sh -west --version -``` - -This should print a message like "West version: v0.14.0". If it prints an error instead, make sure `~/.local/bin` is on your `PATH` environment variable. You can add it with these commands: - -```sh -echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc -source ~/.bashrc -``` - - - - -Install west: - -```sh -pip3 install -U west -``` - -Verify that west is installed: - -```sh -west --version -``` - -This should print a message like "West version: v0.14.0". If it prints an error instead, make sure that the Python scripts directory is on your `PATH` environment variable. You can add it by opening a PowerShell window and running the following commands: - -```powershell -$Scripts = python -c "import sysconfig; print(sysconfig.get_path('scripts'))" -$Path = [Environment]::GetEnvironmentVariable('PATH', 'User') -[Environment]::SetEnvironmentVariable('PATH', "$Path;$Scripts", 'User') -$env:PATH += ";$Scripts" -``` - - - - -Install west: - -```sh -pip3 install -U west -``` - - - - -## Get Source Code - -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 -``` - -## Initialize & Update Zephyr Workspace - -Since ZMK is built as a Zephyr™ application, the next step is -to use `west` to initialize and update your workspace. The ZMK -Zephyr™ application is in the `app/` source directory: - -### Step into the repository - - - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - - - -Open the `zmk` checkout folder in VS Code. The repository includes a configuration for containerized development, so an alert will pop up: - -![VS Code Dev Container Configuration Alert](../assets/dev-setup/vscode_devcontainer.png) - -Click `Reopen in Container` in order to reopen the VS Code with the running container. - -The first time you do this on your machine, it will pull the docker image down from the registry and build the container. Subsequent launches are much faster! - -:::warning -All subsequent steps must be performed from the VS Code terminal _inside_ the container. -::: - - - - -### Initialize the Application - -```sh -west init -l app/ -``` - -### Update to Fetch Modules - -```sh -west update -``` - -:::tip -This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection! -::: - -:::info -If you're using Docker, you're done with setup! You must restart the container at this point. The easiest way to do so is to close the VS Code window, verify that the container has stopped in Docker Dashboard, and reopen the container with VS Code. - -Once your container is restarted, proceed to [Building and Flashing](development/build-flash.mdx). -::: - -### Export Zephyr CMake package - -This allows CMake to load the code needed to build ZMK. - -```sh -west zephyr-export -``` - -### Install Zephyr Python Dependencies - -Some additional Python dependencies are listed in Zephyr's `scripts/requirements.txt` file. - - - - -```sh -pip3 install --user -r zephyr/scripts/requirements.txt -``` - - - - -```sh -pip3 install -r zephyr/scripts/requirements.txt -``` - - - - -```sh -pip3 install -r zephyr/scripts/requirements.txt -``` - - - diff --git a/docs/docs/development/setup/docker.md b/docs/docs/development/setup/docker.md new file mode 100644 index 00000000000..767331e409f --- /dev/null +++ b/docs/docs/development/setup/docker.md @@ -0,0 +1,53 @@ +--- +title: Docker +sidebar_label: Docker +--- + +:::note +Currently the Docker approach is only documented for [VS Code](https://github.com/microsoft/vscode) (not [Code OSS](https://github.com/microsoft/vscode/wiki/Differences-between-the-repository-and-Visual-Studio-Code)). While it can be replicated using [devcontainers](https://containers.dev/) this is not documented yet - contributions are welcome! +::: + +### Source Code + +First, you'll need to clone the ZMK source repository if you haven't already. Open a terminal and navigate to the folder you would like to place your `zmk` directory in, then run the following command: + +```sh +git clone https://github.com/zmkfirmware/zmk.git +``` + +### Installing Development Tools + +1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system. +2. Install [VS Code](https://code.visualstudio.com/). +3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). + +### Initialize & Update Zephyr Workspace + +Open the `zmk` checkout folder in VS Code. The repository includes a configuration for containerized development, so an alert will pop up: + +![VS Code Dev Container Configuration Alert](../../assets/dev-setup/vscode_devcontainer.png) + +Click `Reopen in Container` in order to reopen the VS Code with the running container. If the alert fails to pop up or you accidentally close it, you can perform the same action by pressing `ctrl+shift+p` and selecting `Remote: Show Remote Menu`. + +The first time you do this on your machine, it will pull the docker image down from the registry and build the container. Subsequent launches are much faster! + +:::caution +The following step and any future [build commands](../build-flash.mdx) must be executed from the VS Code terminal _inside_ the container. +::: + +Initialize the application and update to fetch modules, including Zephyr: + +```sh +west init -l app/ +west update +``` + +:::tip +This step pulls down quite a bit of tooling, be patient! +::: + +:::info +You must restart the container at this point. The easiest way to do so is to close the VS Code window, verify that the container has stopped in Docker Dashboard, and reopen the container with VS Code. + +Your setup is complete once your container has restarted. +::: diff --git a/docs/docs/development/setup/index.md b/docs/docs/development/setup/index.md new file mode 100644 index 00000000000..5c795fa22c7 --- /dev/null +++ b/docs/docs/development/setup/index.md @@ -0,0 +1,20 @@ +--- +title: Getting Started +sidebar_label: Getting Started +--- + +:::tip +We recommend reading through the setup process before following it step by step, to ensure that you are happy with installing the required dependencies. +::: + +## Environment Setup + +There are two ways to set up the ZMK development environment: + +- [Docker](/docs/development/setup/docker): \ + A self-contained development environment. It uses the same [Docker image which is used by the GitHub action](https://github.com/zmkfirmware/zmk-docker) for local development. Beyond the benefits of [dev/prod parity](https://12factor.net/dev-prod-parity), this approach may be easier to set up for some operating systems. No toolchain or dependencies are necessary when using Docker; the container image has the toolchain installed and set up to use. + +- [Native](/docs/development/setup/native):\ + This uses your operating system directly. Usually runs slightly faster than the Docker approach, and can be preferable for users who already have the dependencies on their system. + +Please see the [Docker](/docs/development/setup/docker) instructions or [native](/docs/development/setup/native) instructions to continue setup. diff --git a/docs/docs/development/setup/native.mdx b/docs/docs/development/setup/native.mdx new file mode 100644 index 00000000000..d077d7d1d7d --- /dev/null +++ b/docs/docs/development/setup/native.mdx @@ -0,0 +1,353 @@ +--- +title: Native Setup +sidebar_label: Native +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +export const OsTabs = (props) => ( + + {/* eslint-disable-next-line */} + {props.children} + + +); + +export const OsNoteTabs = (props) => ( + + {/* eslint-disable-next-line */} + {props.children} + + +); + +export const EnvTabs = (props) => ( + + {/* eslint-disable-next-line */} + {props.children} + + +); + +export const WinTermTabs = (props) => ( + + {/* eslint-disable-next-line */} + {props.children} + + +); + +## 1. Install Zephyr Dependencies + +Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections: + +- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os) +- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies) + +:::info +Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/installation_linux.html) page may be of use for users of Linux distributions which are not based on Ubuntu. +::: + +## 2. Source Code + +Next, you'll need to clone the ZMK source repository if you haven't already. Open a terminal and navigate to the folder you would like to place your `zmk` directory in, then run the following command: + +```sh +git clone https://github.com/zmkfirmware/zmk.git +``` + +Then step into the repository. + +```sh +cd zmk +``` + +## 3. Get Zephyr and install Python dependencies + +:::note +These steps are very similar to Zephyr's [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies) instructions, but specialized for ZMK. +::: + + + + + + +1. Use `apt` to install Python `venv` package: + +```sh +sudo apt install python3-venv +``` + +2. Create a new virtual environment and activate it: + +```sh +python3 -m venv .venv +source .venv/bin/activate +``` + + + + +1. Create a new virtual environment: + +```sh +python -m venv .venv +``` + +2. Activate the virtual environment: + + + + +```sh +.venv\Scripts\activate.bat +``` + + + + + +```powershell +.venv\Scripts\Activate.ps1 +``` + + + + + + + + +1. Create a new virtual environment: + +```sh +python3 -m venv .venv +``` + +2. Activate the virtual environment: + +```sh +source .venv/bin/activate +``` + + + + +Once activated your shell will be prefixed with `(.venv)`. The virtual environment can be deactivated at any time by running `deactivate`. + +:::note +Remember to activate the virtual environment every time you start working. +::: + +4. Install west: + +```sh +pip install west +``` + +5. Initialize the application and update to fetch modules, including Zephyr: + +```sh +west init -l app/ +west update +``` + +:::tip +This step pulls down quite a bit of tooling, be patient! +::: + +6. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications. + +```sh +west zephyr-export +``` + +7. Install the additional dependencies found in Zephyr's `requirements-base.txt`: + +```sh +pip install -r zephyr/scripts/requirements-base.txt +``` + + + + + +1. Install `west`: + +```sh +pip3 install --user -U west +``` + +:::note +You need `~/.local/bin` to be on your `PATH` environment variable; verify that it is by running + +```sh +west --version +``` + +If this prints an error rather than a `west` version number, then add `~/.local/bin` to your `PATH`: + +```sh +echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc +source ~/.bashrc +``` + +::: + + + + +1. Install `west`: + +```sh +pip install -U west +``` + +:::note +You need the Python scripts directory to be on your PATH environment variable; verify that it is by running + +```sh +west --version +``` + +If this prints an error rather than a `west` version number, then add said directory to your `PATH` with PowerShell: + +```powershell +$Scripts = python -c "import sysconfig; print(sysconfig.get_path('scripts'))" +$Path = [Environment]::GetEnvironmentVariable('PATH', 'User') +[Environment]::SetEnvironmentVariable('PATH', "$Path;$Scripts", 'User') +$env:PATH += ";$Scripts" +``` + +::: + + + + + +1. Install `west`: + +```sh +pip3 install -U west +``` + + + + +2. Initialize the application and update to fetch modules, including Zephyr: + +```sh +west init -l app/ +west update +``` + +:::tip +This step pulls down quite a bit of tooling, be patient! +::: + +3. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications. + +```sh +west zephyr-export +``` + + + + +4. Install the additional dependencies found in Zephyr's `requirements-base.txt`: + +```sh +pip3 install --user -r zephyr/scripts/requirements-base.txt +``` + + + + + +4. Install the additional dependencies found in Zephyr's `requirements-base.txt`: + +```sh +pip install -r zephyr/scripts/requirements-base.txt +``` + + + + +4. Install the additional dependencies found in Zephyr's `requirements-base.txt`. + +```sh +pip3 install -r zephyr/scripts/requirements-base.txt +``` + + + + + + +## 4. Install Zephyr SDK + +Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk). + +### OS specific notes + + + + `dfu-util` is required to flash devices that use DFU, but there is currently + no maintained package for it on Chocolatey. [QMK + Toolbox](https://github.com/qmk/qmk_toolbox) contains a working version of it + though. + + + +#### Install Cross-Compile Toolchain + +Because Raspberry OS runs on the same architecture (but different ABI) as ARM keyboard MCUs, the operating system's installed [cross compilers](https://docs.zephyrproject.org/3.5.0/develop/toolchains/other_x_compilers.html) can be used to target the different ABI. Building for non-ARM MCUs has not been tested. + +First, the cross compiler should be installed: + +```sh +sudo apt install gcc-arm-none-eabi +``` + +Next, we'll configure Zephyr with some [environment variables](https://docs.zephyrproject.org/3.5.0/develop/env_vars.html#env-vars) needed to find the cross compiler. Create a file named `~/.zephyrrc` if it doesn't exist, and add these lines to it: + +```sh +export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile +export CROSS_COMPILE=/usr/bin/arm-none-eabi- +``` + + + + +Your setup is now complete. diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md index 09efdecf770..876cbb9b4d2 100644 --- a/docs/docs/troubleshooting.md +++ b/docs/docs/troubleshooting.md @@ -34,7 +34,7 @@ macOS 14.x (Sonoma) Finder may report an "Error code -36" when copying `