kb01/zmk
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Making the discussed toolchain docs changes

Browse source
This commit is contained in:
Nicolas Munnich 2024-04-15 03:17:09 +02:00
parent e22bc7620c
commit 98e60d5885
1 changed files with 28 additions and 160 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

188
docs/docs/development/setup.mdx
View file

@ -9,14 +9,13 @@ import TabItem from "@theme/TabItem";
export const OsTabs = (props) => ( export const OsTabs = (props) => (
<Tabs <Tabs
groupId="operating-systems" groupId="operating-systems"
defaultValue="debian" defaultValue="linux"
values={[ values={[
{ label: "VS Code & Docker", value: "docker" }, { label: "VS Code & Docker", value: "docker" },
{ label: "Debian/Ubuntu", value: "debian" }, { label: "Linux", value: "linux" },
{ label: "Windows", value: "win" }, { label: "Windows", value: "win" },
{ label: "macOS", value: "mac" }, { label: "macOS", value: "mac" },
{ label: "Raspberry OS", value: "raspberryos" }, { label: "Raspberry OS", value: "raspberryos" },
{ label: "Fedora", value: "fedora" },
]} ]}
> >
{/* eslint-disable-next-line */} {/* eslint-disable-next-line */}
@ -26,44 +25,45 @@ export const OsTabs = (props) => (
This guide will show you how to set up a development environment for building ZMK locally. This guide will show you how to set up a development environment for building ZMK locally.
## Install Dependencies ## Install Zephyr and West
Click the operating system you are using. (The VS Code & Docker option can be used on any OS.) Click the operating system you are using. (The VS Code & Docker option can be used on any OS.)
<OsTabs> <OsTabs>
<TabItem value="docker"> <TabItem value="docker">
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. 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 may be easier to set up for some operating systems. 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. 1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system.
2. Install [Visual Studio Code](https://code.visualstudio.com/) 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) 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).
:::
</TabItem> </TabItem>
<TabItem value="debian"> <TabItem value="linux">
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: 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) 1. [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) 2. [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) 3. [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies)
4. [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. Return to this guide once you are finished with all four sections.
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 distributions which are not based on Ubuntu.
</TabItem> </TabItem>
<TabItem value="win"> <TabItem value="win">
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: 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) 1. [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) 2. [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) 3. [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies)
4. [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. Return to this guide once you are finished with all four sections.
`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. `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.
@ -72,11 +72,12 @@ 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: 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) 1. [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) 2. [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) 3. [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies)
4. [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. Return to this guide once you are finished with all four sections.
</TabItem> </TabItem>
<TabItem value="raspberryos"> <TabItem value="raspberryos">
@ -85,10 +86,12 @@ 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 for Ubuntu under these sections: 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) 1. [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) 2. [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
3. [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies)
4. [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. Return to this guide once you are finished with all four sections.
#### Install Cross-Compile Toolchain #### Install Cross-Compile Toolchain
@ -107,85 +110,9 @@ export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
export CROSS_COMPILE=/usr/bin/arm-none-eabi- export CROSS_COMPILE=/usr/bin/arm-none-eabi-
``` ```
</TabItem>
<TabItem value="fedora">
Follow Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/installation_linux.html) documentation for Fedora.
</TabItem> </TabItem>
</OsTabs> </OsTabs>
### 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:
<Tabs
defaultValue="linux"
groupId="python-os"
values={[
{label: 'Linux', value: 'linux'},
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
]}>
<TabItem value="linux">
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
```
</TabItem>
<TabItem value="win">
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"
```
</TabItem>
<TabItem value="mac">
Install west:
```sh
pip3 install -U west
```
</TabItem>
</Tabs>
## Get Source Code ## 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: 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:
@ -203,21 +130,7 @@ Zephyr™ application is in the `app/` source directory:
### Step into the repository ### Step into the repository
<OsTabs> <OsTabs>
<TabItem value="debian"> <TabItem value="linux">
```sh
cd zmk
```
</TabItem>
<TabItem value="raspberryos">
```sh
cd zmk
```
</TabItem>
<TabItem value="fedora">
```sh ```sh
cd zmk cd zmk
@ -273,50 +186,5 @@ This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can tak
::: :::
:::info :::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). 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.
<Tabs
defaultValue="linux"
groupId="python-os"
values={[
{label: 'Linux', value: 'linux'},
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
]}>
<TabItem value="linux">
```sh
pip3 install --user -r zephyr/scripts/requirements.txt
```
</TabItem>
<TabItem value="win">
```sh
pip3 install -r zephyr/scripts/requirements.txt
```
</TabItem>
<TabItem value="mac">
```sh
pip3 install -r zephyr/scripts/requirements.txt
```
</TabItem>
</Tabs>