Slice up the development environment setup some included changes:
- Give a brief overview of docker+vscode vs native os - Dedicated page for docker+vscode setup - Dedicated page for native os setup - Dedicated page for setting up zmk sources for development
This commit is contained in:
KemoNine
parent
0f9fff7554
commit
fa39132c2a
5 changed files with 186 additions and 132 deletions
17
docs/docs/development/setup/docker-vscode.md
Normal file
17
docs/docs/development/setup/docker-vscode.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
title: Docker+VSCode Setup
|
||||
sidebar_label: Docker+VSCode
|
||||
---
|
||||
|
||||
:::danger The Docker+VSCode environment will **NOT** run on arm CPUs. You must use the Native environment if using an arm CPU.
|
||||
:::
|
||||
|
||||
This setup leverages the same [image which is used by the GitHub action](https://github.com/zmkfirmware/zephyr-west-action) 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 [VS Code](https://code.visualstudio.com/)
|
||||
3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
|
||||
|
||||
:::info
|
||||
Once the above is setup you're ready to setup the ZMK sources as defined [here](/docs/development/setup/zmk)
|
||||
:::
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: Basic Setup
|
||||
sidebar_label: Basic Setup
|
||||
title: Native OS Setup
|
||||
sidebar_label: Native OS
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
|
|
@ -15,7 +15,6 @@ values={[
|
|||
{label: 'macOS', value: 'mac'},
|
||||
{label: 'Raspberry OS', value: 'raspberryos'},
|
||||
{label: 'Fedora', value: 'fedora'},
|
||||
{label: 'VS Code & Docker', value: 'docker'},
|
||||
]
|
||||
}>{props.children}</Tabs>);
|
||||
|
||||
|
|
@ -185,19 +184,6 @@ Homebrew is required to install the system dependencies. If you haven't done so,
|
|||
brew install cmake ninja python3 ccache dtc git wget dfu-util
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="docker">
|
||||
|
||||
This setup leverages the same [image which is used by the GitHub action](https://github.com/zmkfirmware/zephyr-west-action) 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 [VS 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 includes `west` and the compilation toolchain. If you're using docker and VS Code, you can skip right to [Source Code](#source-code).
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</OsTabs>
|
||||
|
||||
|
|
@ -355,116 +341,6 @@ The transient instructions can be used to setup the current shell, and the autom
|
|||
The transient instructions must be run to build firmware using the current shell.
|
||||
:::
|
||||
|
||||
### 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
|
||||
|
||||
<OsTabs>
|
||||
<TabItem value="debian">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="raspberryos">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fedora">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="mac">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="win">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="docker">
|
||||
|
||||
Open the `zmk` checkout folder in VS Code. The repository includes a configuration for containerized development, so an alert will pop up:
|
||||
|
||||
|
||||
|
||||
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!
|
||||
|
||||
:::caution
|
||||
All subsequent steps must be performed from the VS Code terminal _inside_ the container.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</OsTabs>
|
||||
|
||||
#### Initialize West
|
||||
|
||||
```sh
|
||||
west init -l app/
|
||||
```
|
||||
|
||||
:::caution Command Not Found?
|
||||
If you encounter errors like `command not found: west` then your `PATH` environment variable is likely
|
||||
missing the Python 3 user packages directory. See the [West Build Command](#west-build-command)
|
||||
section again for links to how to do this
|
||||
:::
|
||||
|
||||
#### 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.md).
|
||||
:::
|
||||
|
||||
#### Export Zephyr™ Core
|
||||
|
||||
```sh
|
||||
west zephyr-export
|
||||
```
|
||||
|
||||
#### Install Zephyr Python Dependencies
|
||||
|
||||
```sh
|
||||
pip3 install --user -r zephyr/scripts/requirements-base.txt
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
<Tabs
|
||||
|
|
@ -481,23 +357,23 @@ On Windows, only two environment variables need to be set for ZMK to build prope
|
|||
|
||||
1. Open Start Menu and type 'env' to find the 'Edit the system environment variables' option. Open it.
|
||||
|
||||
|
||||
|
||||
|
||||
2. Click 'Environment Variables...'.
|
||||
|
||||
|
||||
|
||||
|
||||
3. Click "New..." under System variables to create a new system variable.
|
||||
|
||||
|
||||
|
||||
|
||||
4. Set the variable name to 'ZEPHYR_TOOLCHAIN_VARIANT' and value to 'gnuarmemb'. Click OK to save.
|
||||
|
||||
|
||||
|
||||
|
||||
5. Create another variable with variable name 'GNUARMEMB_TOOLCHAIN_PATH' and value set to wherever you installed your toolchain. **Make sure this path does not contain any spaces.** If it does, rename the folder and update here. Click OK to save.
|
||||
|
||||
|
||||
|
||||
|
||||
6. Close Command Prompt and reopen, or run `refreshenv` to apply the changes.
|
||||
|
||||
|
|
@ -553,3 +429,7 @@ cat ~/.zephyrrc >> ~/.zshrc
|
|||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
:::info
|
||||
Once the above is setup you're ready to setup the ZMK sources as defined [here](/docs/development/setup/zmk)
|
||||
:::
|
||||
19
docs/docs/development/setup/setup.md
Normal file
19
docs/docs/development/setup/setup.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
title: General Info
|
||||
sidebar_label: General Information
|
||||
---
|
||||
|
||||
## Environment Setup
|
||||
|
||||
There are 2 ways to setup the zmk development environment: Docker+VSCode and Native OS. The Docker+VSCode approach is a self-contained development environment while Native OS approach will setup your local operating system for development.
|
||||
|
||||
The Docker+VSCode approach is very straight forward to setup. The Native approach requires more up-front work but doesn't require installing Docker/VSCode and can be faster for development depending on your computer's hardware.
|
||||
|
||||
The links in the navigation bar will outline the necessary steps for setting up both of these approaches.
|
||||
|
||||
:::danger The Docker+VSCode environment will **NOT** run on arm CPUs. You must use the Native OS environment if using an arm CPU.
|
||||
:::
|
||||
|
||||
## ZMK Sources Setup
|
||||
|
||||
Once you've setup either the Docker+VSCode environment or Native OS environment you will need to setup the ZMK sources. Please see the [ZMK Sources](/docs/development/setup/zmk) section once you've setup your chosen environment.
|
||||
128
docs/docs/development/setup/zmk.md
Normal file
128
docs/docs/development/setup/zmk.md
Normal file
|
|
@ -0,0 +1,128 @@
|
|||
---
|
||||
title: ZMK Sources
|
||||
sidebar_label: ZMK Sources
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
export const OsTabs = (props) => (<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="docker"
|
||||
values={[
|
||||
{label: 'VS Code & Docker', value: 'docker'},
|
||||
{label: 'Debian/Ubuntu', value: 'debian'},
|
||||
{label: 'macOS', value: 'mac'},
|
||||
{label: 'Windows', value: 'win'},
|
||||
{label: 'Raspberry OS', value: 'raspberryos'},
|
||||
{label: 'Fedora', value: 'fedora'},
|
||||
]
|
||||
}>{props.children}</Tabs>);
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
:::caution
|
||||
If you're using the Docker+VSCode environment on Windows, you _must_ checkout the sources to a folder within `C:\Users\[your_user_here]` to avoid a potential permissions issue.
|
||||
:::
|
||||
|
||||
### 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
|
||||
|
||||
<OsTabs>
|
||||
<TabItem value="docker">
|
||||
|
||||
Open the `zmk` checkout folder in VS Code. The repository includes a configuration for containerized development, so an alert will pop up:
|
||||
|
||||
|
||||
|
||||
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!
|
||||
|
||||
:::caution
|
||||
All subsequent steps must be performed from the VS Code terminal _inside_ the container.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="debian">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="raspberryos">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fedora">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="mac">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="win">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</OsTabs>
|
||||
|
||||
#### Initialize West
|
||||
|
||||
```sh
|
||||
west init -l app/
|
||||
```
|
||||
|
||||
:::caution Command Not Found? (Native OS)
|
||||
If you encounter errors like `command not found: west` then your `PATH` environment variable is likely
|
||||
missing the Python 3 user packages directory. See the [West Build Command](#west-build-command)
|
||||
section again for links to how to do this
|
||||
:::
|
||||
|
||||
#### 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!
|
||||
:::
|
||||
|
||||
#### Export Zephyr™ Core
|
||||
|
||||
```sh
|
||||
west zephyr-export
|
||||
```
|
||||
|
||||
#### Install Zephyr Python Dependencies
|
||||
|
||||
```sh
|
||||
pip3 install --user -r zephyr/scripts/requirements-base.txt
|
||||
```
|
||||
|
|
@ -43,7 +43,17 @@ module.exports = {
|
|||
Development: [
|
||||
"development/clean-room",
|
||||
"development/documentation",
|
||||
"development/setup",
|
||||
{
|
||||
type: "category",
|
||||
label: "Setup",
|
||||
collapsed: false,
|
||||
items: [
|
||||
"development/setup/setup",
|
||||
"development/setup/docker-vscode",
|
||||
"development/setup/native",
|
||||
"development/setup/zmk",
|
||||
],
|
||||
},
|
||||
"development/build-flash",
|
||||
"development/boards-shields-keymaps",
|
||||
"development/posix-board",
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue