diff --git a/docs/blog/2021-07-17-zephyr-2-5.md b/docs/blog/2021-07-17-zephyr-2-5.md index 12116941..789a644c 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/getting-started) 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 7afbeb49..92e8b33b 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/getting-started) 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/2023-04-06-zephyr-3-2.md b/docs/blog/2023-04-06-zephyr-3-2.md index 8b181572..cdd50e48 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/getting-started) 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 2c490dcf..738f22da 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/getting-started) 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/customization.md b/docs/docs/customization.md index 3a5b46a9..d9bcd89b 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/getting-started.md) and +It is also possible to build firmware locally on your computer by following the [toolchain setup](development/setup) 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 9553d0f1..3ed45a10 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/getting-started.md), +Using GitHub Actions to build your new firmware can save you from doing any local [development setup](./setup), 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/getting-started.md) guide first. +To build locally, be sure you've followed the [development setup](./setup) guide first. ::: Once you've fully created the new keyboard shield definition, diff --git a/docs/docs/development/setup/docker.md b/docs/docs/development/setup/docker.md index 02470a1d..1b1f26b3 100644 --- a/docs/docs/development/setup/docker.md +++ b/docs/docs/development/setup/docker.md @@ -4,7 +4,7 @@ sidebar_label: Docker --- :::note -Currently the Docker approach is only documented for [VS Code](https://github.com/microsoft/vscode). While it can be replicated using [devcontainers](https://containers.dev/) this is not documented yet - contributions are welcome! +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 @@ -15,15 +15,6 @@ First, you'll need to clone the ZMK source repository if you haven't already. Op git clone https://github.com/zmkfirmware/zmk.git ``` -:::warning - -#### Windows Users - -If you're using the Docker environment on Windows, you _must_ checkout the sources to a folder within `C:\Users\[your_user_here]` to avoid a potential permissions issue. - -If you're using the WSL2 filesystem the sources should go under `~/` to avoid potential permissions issues. -::: - ## Installing Development Tools 1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system. @@ -67,7 +58,7 @@ 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! +This step pulls down quite a bit of tooling, be patient! ::: :::info diff --git a/docs/docs/development/setup/getting-started.md b/docs/docs/development/setup/index.md similarity index 79% rename from docs/docs/development/setup/getting-started.md rename to docs/docs/development/setup/index.md index f53a3de9..964cff2a 100644 --- a/docs/docs/development/setup/getting-started.md +++ b/docs/docs/development/setup/index.md @@ -3,16 +3,6 @@ title: Getting Started sidebar_label: Getting Started --- -:::info -Throughout this documentation you will see commands like - -```sh -sudo apt update -``` - -These commands should be run in a terminal such as Bash (Linux/MacOS/Docker), PowerShell, or Command Prompt (Windows). -::: - :::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. ::: @@ -28,4 +18,4 @@ The Docker approach is a self-contained development environment while the native The native approach installs the toolchain and dependencies on your system directly. This typically 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](docker.md) instructions or [native](native.mdx) instructions to continue setup. +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 index b688e702..8afdb1b4 100644 --- a/docs/docs/development/setup/native.mdx +++ b/docs/docs/development/setup/native.mdx @@ -13,7 +13,21 @@ export const OsTabs = (props) => ( values={[ { label: "Ubuntu", value: "ubuntu" }, { label: "Windows", value: "win" }, - { label: "Mac OS", value: "mac" }, + { label: "Mac OS", value: "mac" } + ]} + > + {/* eslint-disable-next-line */} + {props.children} + + +); + +export const OsNoteTabs = (props) => ( + @@ -84,11 +98,10 @@ cd zmk 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: @@ -96,102 +109,16 @@ These steps are very similar to Zephyr's [Get Zephyr and install Python dependen sudo apt install python3-venv ``` -2. Create a new virtual environment: +2. Create a new virtual environment and activate it: ```sh python3 -m venv .venv -``` - -3. 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 -pip3 install west -``` - -5. Initialise the application (This provides ZMK with its own copy of Zephyr): - -```sh -west init -l app/ -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! -::: - -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 -pip3 install -r zephyr/scripts/requirements-base.txt -``` - - - - -1. Install `west`, and make sure `~/.local/bin` is on your `PATH` environment variable: - -```sh -pip3 install --user -U west -echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc -source ~/.bashrc -``` - -2. Initialise the application (This provides ZMK with its own copy of Zephyr): - -```sh -west init -l app/ -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! -::: - -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 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). - -Your setup is now complete. - - - - 1. Create a new virtual environment: ```sh @@ -216,6 +143,22 @@ python -m venv .venv + + +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`. @@ -223,13 +166,13 @@ Once activated your shell will be prefixed with `(.venv)`. The virtual environme Remember to activate the virtual environment every time you start working. ::: -3. Install west: +4. Install west: ```sh pip install west ``` -4. Initialise the application (This provides ZMK with its own copy of Zephyr): +5. Initialize the application and update to fetch modules, including Zephyr: ```sh west init -l app/ @@ -237,16 +180,16 @@ 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! +This step pulls down quite a bit of tooling, be patient! ::: -5. 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. +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 ``` -6. Install the additional dependencies found in Zephyr's `requirements-base.txt`: +7. Install the additional dependencies found in Zephyr's `requirements-base.txt`: ```sh pip install -r zephyr/scripts/requirements-base.txt @@ -254,14 +197,17 @@ pip install -r zephyr/scripts/requirements-base.txt - + + 1. Install `west`, and make sure `~/.local/bin` is on your `PATH` environment variable: ```sh -pip install -U west +pip3 install --user -U west +echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc +source ~/.bashrc ``` -2. Initialise the application (This provides ZMK with its own copy of Zephyr): +2. Initialize the application and update to fetch modules, including Zephyr: ```sh west init -l app/ @@ -269,7 +215,38 @@ 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! +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 +``` + + + +1. Install `west`, and make sure `~/.local/bin` is on your `PATH` environment variable: + +```sh +pip 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. @@ -284,81 +261,16 @@ west zephyr-export pip 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). - -:::note -`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. -::: - -Your setup is now complete. - - - -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. -::: - -3. Install west: - -```sh -pip3 install west -``` - -4. Initialise the application (This provides ZMK with its own copy of Zephyr) - -```sh -west init -l app/ -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! -::: - -5. 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 -``` - -6. Install the additional dependencies found in Zephyr's `requirements-base.txt`. - -```sh -pip3 install -r zephyr/scripts/requirements-base.txt -``` - - - - 1. Install `west` ```sh pip3 install -U west ``` -2. Initialise the application (This provides ZMK with its own copy of Zephyr) +2. Initialize the application and update to fetch modules, including Zephyr: ```sh west init -l app/ @@ -366,7 +278,7 @@ 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! +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. @@ -381,112 +293,28 @@ west zephyr-export pip3 install -r ~/zephyrproject/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. + - - - -1. Use `apt` to install Python `venv` package: - -```sh -sudo apt install python3-venv -``` - -2. Create a new virtual environment: - -```sh -python3 -m venv .venv -``` - -3. 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 -pip3 install west -``` - -5. Initialise the application (This provides ZMK with its own copy of Zephyr): - -```sh -west init -l app/ -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! -::: - -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 -pip3 install -r zephyr/scripts/requirements-base.txt -``` - - - - -1. Install `west`, and make sure `~/.local/bin` is on your `PATH` environment variable: - -```sh -pip3 install --user -U west -echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc -source ~/.bashrc -``` - -2. Initialise the application (This provides ZMK with its own copy of Zephyr): - -```sh -west init -l app/ -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! -::: - -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 ~/zephyrproject/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). - -## 5. Install Cross-Compile Toolchain +#### 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. @@ -503,7 +331,8 @@ export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile export CROSS_COMPILE=/usr/bin/arm-none-eabi- ``` -Your setup is now complete. - - + + + +Your setup is now complete. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 685f64e7..4017b125 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -80,7 +80,7 @@ module.exports = { }, { label: "Development", - to: "docs/development/setup/getting-started", + to: "docs/development/setup", }, ], }, diff --git a/docs/sidebars.js b/docs/sidebars.js index 0e9f2e25..5f607130 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -81,7 +81,7 @@ module.exports = { label: "Setup", collapsed: false, items: [ - "development/setup/getting-started", + "development/setup/index", "development/setup/docker", "development/setup/native", ], diff --git a/docs/static/_redirects b/docs/static/_redirects deleted file mode 100644 index 9f166559..00000000 --- a/docs/static/_redirects +++ /dev/null @@ -1 +0,0 @@ -/docs/development/setup /docs/development/setup/getting-started \ No newline at end of file