diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/docs/assets/dev-setup/vscode_devcontainer.png | bin | 0 -> 20773 bytes | |||
| -rw-r--r-- | docs/docs/dev-build.md | 13 | ||||
| -rw-r--r-- | docs/docs/dev-setup.md | 83 | ||||
| -rw-r--r-- | docs/docs/user-setup.md | 7 | ||||
| -rw-r--r-- | docs/static/setup.ps1 | 15 | ||||
| -rw-r--r-- | docs/static/setup.sh | 7 |
6 files changed, 123 insertions, 2 deletions
diff --git a/docs/docs/assets/dev-setup/vscode_devcontainer.png b/docs/docs/assets/dev-setup/vscode_devcontainer.png Binary files differnew file mode 100644 index 0000000..e5c22b0 --- /dev/null +++ b/docs/docs/assets/dev-setup/vscode_devcontainer.png diff --git a/docs/docs/dev-build.md b/docs/docs/dev-build.md index 816468e..83ed8cb 100644 --- a/docs/docs/dev-build.md +++ b/docs/docs/dev-build.md @@ -84,6 +84,19 @@ west build -d build/right -b nice_nano -- -DSHIELD=kyria_right ``` This produces `left` and `right` subfolders under the `build` directory and two separate .uf2 files. For future work on a specific half, use the `-d` parameter again to ensure you are building into the correct location. +### Building from `zmk-config` Folder + +Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](user-setup#github-repo) by adding +`-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build` command. **Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.** + + +For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this: + +``` +west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config" +``` + + ## Flashing Once built, the previously supplied parameters will be remembered so you can run the following to flash your diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 4891f5a..521d5d0 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -16,6 +16,7 @@ values={[ {label: 'macOS', value: 'mac'}, {label: 'Raspberry OS', value: 'raspberryos'}, {label: 'Fedora', value: 'fedora'}, +{label: 'VS Code & Docker', value: 'docker'}, ] }>{props.children}</Tabs>); @@ -167,6 +168,10 @@ Chocolatey is recommended and used for the following instructions. You can manua choco install ninja gperf python git ``` +It is recommended to install `dfu-util` to avoid any later confusion while flashing devices. You can do this by running this command with chocolatey: +``` shell +choco install dfu-util +``` </TabItem> <TabItem value="mac"> @@ -175,10 +180,24 @@ Chocolatey is recommended and used for the following instructions. You can manua 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 +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> ## Setup @@ -349,12 +368,63 @@ 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 @@ -373,6 +443,17 @@ section again for links to how to do this 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](./dev-build.md). +::: + + #### Export Zephyr™ Core ```sh diff --git a/docs/docs/user-setup.md b/docs/docs/user-setup.md index 2aade82..2785096 100644 --- a/docs/docs/user-setup.md +++ b/docs/docs/user-setup.md @@ -63,6 +63,7 @@ defaultValue="curl" values={[ {label: 'Using curl', value: 'curl'}, {label: 'Using wget', value: 'wget'}, +{label: 'Using PowerShell', value: 'PowerShell'}, ]}> <TabItem value="curl"> @@ -78,6 +79,12 @@ bash -c "$(wget https://zmkfirmware.dev/setup.sh -O -)" ``` </TabItem> +<TabItem value="PowerShell"> + +``` +iex ((New-Object System.Net.WebClient).DownloadString('https://zmkfirmware.dev/setup.ps1'))" +``` +</TabItem> </Tabs> ### MCU Board Selection diff --git a/docs/static/setup.ps1 b/docs/static/setup.ps1 index abdb698..63bd5c0 100644 --- a/docs/static/setup.ps1 +++ b/docs/static/setup.ps1 @@ -57,7 +57,20 @@ catch [System.Management.Automation.CommandNotFoundException] { }
Test-Git-Config -Option "user.name" -ErrMsg "Git username not set!`nRun: git config --global user.name 'My Name'"
-Test-Git-Config -Option "user.email" -ErrMsg "Git email not set!`nRun: git config --global user.name 'example@myemail.com'"
+Test-Git-Config -Option "user.email" -ErrMsg "Git email not set!`nRun: git config --global user.email 'example@myemail.com'"
+
+$permission = (Get-Acl $pwd).Access |
+?{$_.IdentityReference -match $env:UserName `
+ -and $_.FileSystemRights -match "FullControl" `
+ -or $_.FileSystemRights -match "Write" } |
+
+ Select IdentityReference,FileSystemRights
+
+If (-Not $permission){
+ Write-Host "Sorry, you do not have write permissions in this directory."
+ Write-Host "Please try running this script again from a directory that you do have write permissions for."
+ exit 1
+}
$repo_path = "https://github.com/zmkfirmware/zmk-config-split-template.git"
diff --git a/docs/static/setup.sh b/docs/static/setup.sh index 49ed3eb..96e8768 100644 --- a/docs/static/setup.sh +++ b/docs/static/setup.sh @@ -22,6 +22,13 @@ check_exists "command -v curl" "curl is not installed, and is required for this check_exists "git config user.name" "Git username not set!\nRun: git config --global user.name 'My Name'" check_exists "git config user.email" "Git email not set!\nRun: git config --global user.email 'example@myemail.com'" +# Check to see if the user has write permissions in this directory to prevent a cryptic error later on +if [ ! -w `pwd` ]; then + echo 'Sorry, you do not have write permissions in this directory.'; + echo 'Please try running this script again from a directory that you do have write permissions for.'; + exit 1 +fi + repo_path="https://github.com/zmkfirmware/zmk-config-split-template.git" title="ZMK Config Setup:" |
