docs: Add redirect setup script informing users to switch to ZMK CLI (#3168)

This commit is contained in:
Nicolas Munnich
2025-12-29 18:26:00 +00:00
committed by GitHub
parent 40e06f3c00
commit 340e35c461
4 changed files with 5 additions and 617 deletions

View File

@@ -1,313 +0,0 @@
# Copyright (c) 2020 The ZMK Contributors
# SPDX-License-Identifier: MIT
$ErrorActionPreference = "Stop"
function Get-Choice-From-Options {
param(
[String[]] $Options,
[String] $Prompt
)
while ($true) {
for ($i = 0; $i -lt $Options.length; $i++) {
Write-Host "$($i + 1)) $($Options[$i])"
}
Write-Host "$($Options.length + 1)) Quit"
$selection = (Read-Host $Prompt) -as [int]
if ($selection -eq $Options.length + 1) {
Write-Host "Goodbye!"
exit 1
}
elseif ($selection -le $Options.length -and $selection -gt 0) {
$choice = $($selection - 1)
break
}
else {
Write-Host "Invalid Option. Try another one."
}
}
return $choice
}
function Test-Git-Config {
param(
[String] $Option,
[String] $ErrMsg
)
git config $Option | Out-Null
if ($lastExitCode -ne 0) {
Write-Host $ErrMsg
exit 1
}
}
try {
git | Out-Null
}
catch [System.Management.Automation.CommandNotFoundException] {
Write-Host "Git is not installed, and is required for this script!"
exit 1
}
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.email 'example@myemail.com'"
function Test-CommandExists {
param ($command)
$oldPreference = $ErrorActionPreference
$ErrorActionPreference = "stop"
try {
if(Get-Command $command){ return $true }
} Catch { return $false }
Finally { $ErrorActionPreference=$oldPreference }
}
if (Test-CommandExists Get-Acl) {
$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/unified-zmk-config-template.git"
$title = "ZMK Config Setup:"
Write-Host ""
Write-Host "Keyboard Shield Selection:"
$prompt = "Pick a keyboard"
$keyboards = [ordered]@{
{{#keyboards}}
"{{id}}" = @{
name = "{{{name}}}";
type = "{{type}}";
basedir = "{{__base_dir}}";
split = "{{split}}";
arch = "{{arch}}";
siblings = {{#siblings.0}}@(
{{#siblings}}
"{{.}}"
{{/siblings}}
){{/siblings.0}}{{^siblings.0}}( "{{id}}" ){{/siblings.0}};
}
{{/keyboards}}
}
# TODO: Add support for "Other" and linking to docs on adding custom shields in user config repos.
$choice = Get-Choice-From-Options -Options ($keyboards.values | % { $_['name'] }) -Prompt $prompt
$keyboard = $($($keyboards.keys)[$choice])
$keyboard_title = $keyboards[$keyboard].name
$basedir = $keyboards[$keyboard].basedir
$keyboard_split = $keyboards[$keyboard].split
$keyboard_arch = $keyboards[$keyboard].arch
$keyboard_siblings = $keyboards[$keyboard].siblings
$keyboard_type = $keyboards[$keyboard].type
if ($keyboard_type -eq "shield") {
$prompt = "Pick an MCU board"
$boards = [ordered]@{
{{#boards}}
{{id}} = "{{{name}}}";
{{/boards}}
}
$boards_usb_only = [ordered]@{
{{#boards}}
{{id}} = "{{usb_only}}";
{{/boards}}
}
$boards_revisions = [ordered]@{
{{#boards}}
{{id}} = @({{#revisions}}
"{{.}}"{{/revisions}});
{{/boards}}
}
$boards_default_revision=[ordered]@{
{{#boards}}
{{id}} = "{{{default_revision}}}";
{{/boards}}
}
Write-Host "$title"
Write-Host ""
Write-Host "MCU Board Selection:"
$choice = Get-Choice-From-Options -Options $boards.values -Prompt $prompt
if ($keyboard_split -eq "true" -and $($($boards_usb_only.values)[$choice]) -eq "true") {
Write-Host "Wired split is not yet supported by ZMK."
exit 1
}
$shields = $keyboard_siblings
$board = $($($boards.keys)[$choice])
$boards = ( $board )
if ($($($boards_revisions.values)[$choice]).count -gt 0) {
$valid_revisions = $($($boards_revisions.values)[$choice])
$revision_choices = @() + $valid_revisions
for ($i = 0; $i -lt $valid_revisions.count; $i += 1) {
if ($valid_revisions[$i] -eq $($($boards_default_revision.values)[$choice])) {
$revision_choices[$i] += " (default)"
}
}
$revision_choice = Get-Choice-From-Options -Options $revision_choices -Prompt $prompt
$board = $board + "@" + $valid_revisions[$revision_choice]
$boards = ( $board )
}
} else {
$boards = ( $keyboard_siblings )
$shields = @( )
}
$copy_keymap = Read-Host "Copy in the stock keymap for customisation? [Yn]"
if ($copy_keymap -eq "" -or $copy_keymap -eq "Y" -or $copy_keymap -eq "y") {
$copy_keymap = "yes"
}
$github_user = Read-Host "GitHub Username (leave empty to skip GitHub repo creation)"
if ($github_user -ne "") {
$repo_name = Read-Host "GitHub Repo Name [zmk-config]"
if ($repo_name -eq "") {
$repo_name = "zmk-config"
}
$github_repo = Read-Host "GitHub Repo [https://github.com/$github_user/$repo_name.git]"
if ($github_repo -eq "") {
$github_repo = "https://github.com/$github_user/$repo_name.git"
}
}
else {
$repo_name = "zmk-config"
$github_repo = ""
}
Write-Host ""
Write-Host "Preparing a user config for:"
if ($keyboard_type -eq "shield") {
Write-Host "* MCU Board: ${boards}"
Write-Host "* Shield(s): ${shields}"
} else {
Write-Host "* Board(s): ${boards}"
}
if ($copy_keymap -eq "yes") {
Write-Host "* Copy Keymap?: Yes"
}
else {
Write-Host "* Copy Keymap?: No"
}
if ($github_repo -ne "") {
Write-Host "* GitHub Repo to Push (please create this in GH first!): $github_repo"
}
Write-Host ""
$do_it = Read-Host "Continue? [Yn]"
if ($do_it -ne "" -and $do_it -ne "Y" -and $do_it -ne "y") {
Write-Host "Aborting..."
exit 1
}
git clone --single-branch "$repo_path" "$repo_name"
Set-Location "$repo_name"
Push-Location config
if ($keyboard_type -eq "shield") {
$url_base = "https://raw.githubusercontent.com/zmkfirmware/zmk/main/app/boards/shields/${basedir}"
} else {
$url_base = "https://raw.githubusercontent.com/zmkfirmware/zmk/main/app/boards/${keyboard_arch}/${basedir}"
}
Write-Host "Downloading config file (${url_base}/${keyboard}.conf)"
Try {
Invoke-RestMethod -Uri "${url_base}/${keyboard}.conf" -OutFile "${keyboard}.conf"
} Catch {
Try {
Write-Host "Could not find it, falling back to ${url_base}/${basedir}.conf"
Invoke-RestMethod -Uri "${url_base}/${basedir}.conf" -OutFile "${basedir}.conf"
} Catch {
Set-Content -Path "${keyboard}.conf" "# Put configuration options here"
}
}
if ($copy_keymap -eq "yes") {
Write-Host "Downloading keymap file (${url_base}/${keyboard}.keymap)"
Try {
Invoke-RestMethod -Uri "${url_base}/${keyboard}.keymap" -OutFile "${keyboard}.keymap"
} Catch {
Write-Host "Could not find it, falling back to ${url_base}/${basedir}.keymap"
Try {
Invoke-RestMethod -Uri "${url_base}/${basedir}.keymap" -OutFile "${basedir}.keymap"
} Catch {
Write-Host "Warning: Could not find a keymap file to download!"
}
}
}
Pop-Location
Add-Content -Path "build.yaml" -Value "include:"
foreach ($b in ${boards}) {
if ($keyboard_type -eq "shield") {
foreach ($s in ${shields}) {
Add-Content -Path "build.yaml" -Value " - board: $b"
Add-Content -Path "build.yaml" -Value " shield: $s"
}
} else {
Add-Content -Path "build.yaml" -Value " - board: $b"
}
}
Remove-Item -Recurse -Force .git
git init .
git add .
git commit -m "Initial User Config."
if ($github_repo -ne "") {
git remote add origin "$github_repo"
git push --set-upstream origin $(git symbolic-ref --short HEAD)
# If push failed, assume that the origin was incorrect and give instructions on fixing.
if ($lastExitCode -ne 0) {
Write-Host "Remote repository $github_repo not found..."
Write-Host "Check GitHub URL, and try adding again."
Write-Host "Run the following: "
Write-Host " git remote rm origin"
Write-Host " git remote add origin FIXED_URL"
Write-Host " git push --set-upstream origin $(git symbolic-ref --short HEAD)"
Write-Host "Once pushed, your firmware should be available from GitHub Actions at: $actions"
exit 1
}
if ($github_repo -imatch "https") {
$actions = "$($github_repo.substring(0, $github_repo.length - 4))/actions"
Write-Host "Your firmware should be available from GitHub Actions shortly: $actions"
}
}

View File

@@ -1,304 +0,0 @@
#!/usr/bin/env bash
# Copyright (c) 2020 The ZMK Contributors
# SPDX-License-Identifier: MIT
set -e
check_exists() {
command_to_run=$1
error_message=$2
local __resultvar=$3
if ! eval "$command_to_run" &> /dev/null; then
if [[ "$__resultvar" != "" ]]; then
eval $__resultvar="'false'"
else
printf "%s\n" "$error_message"
exit 1
fi
else
if [[ "$__resultvar" != "" ]]; then
eval $__resultvar="'true'"
fi
fi
}
check_exists "command -v git" "git is not installed, and is required for this script!"
check_exists "command -v curl" "curl is not installed, and is required for this script!" curl_exists
check_exists "command -v wget" "wget is not installed, and is required for this script!" wget_exists
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
# Parse all commandline options
while [[ "$#" -gt 0 ]]; do
case $1 in
-w|--wget) force_wget="true"; break;;
*) echo "Unknown parameter: $1"; exit 1;;
esac
shift
done
if [[ $curl_exists == "true" && $wget_exists == "true" ]]; then
if [[ $force_wget == "true" ]]; then
download_command="wget "
else
download_command="curl -fsOL "
fi
elif [[ $curl_exists == "true" ]]; then
download_command="curl -fsOL "
elif [[ $wget_exists == "true" ]]; then
download_command="wget "
else
echo 'Neither curl nor wget are installed. One of the two is required for this script!'
exit 1
fi
repo_path="https://github.com/zmkfirmware/unified-zmk-config-template.git"
title="ZMK Config Setup:"
echo ""
echo "Keyboard Selection:"
PS3="Pick a keyboard: "
options=({{#keyboards}}"{{{name}}}" {{/keyboards}})
keyboards_id=({{#keyboards}}"{{id}}" {{/keyboards}})
keyboards_type=({{#keyboards}}"{{type}}" {{/keyboards}})
keyboards_arch=({{#keyboards}}"{{arch}}" {{/keyboards}})
keyboards_basedir=({{#keyboards}}"{{__base_dir}}" {{/keyboards}})
keyboards_split=({{#keyboards}}"{{#split}}y{{/split}}{{^split}}n{{/split}}" {{/keyboards}})
keyboards_shield=({{#keyboards}}"{{#compatible}}y{{/compatible}}{{^compatible}}n{{/compatible}}" {{/keyboards}})
{{#keyboards}}
{{#siblings.0}}
{{id}}_siblings=({{#siblings}}"{{.}}" {{/siblings}})
{{/siblings.0}}
{{/keyboards}}
select opt in "${options[@]}" "Quit"; do
case "$REPLY" in
''|*[!0-9]*) echo "Invalid option. Try another one."; continue;;
$(( ${#options[@]}+1 )) ) echo "Goodbye!"; exit 1;;
*)
if [ $REPLY -gt $(( ${#options[@]}+1 )) ] || [ $REPLY -lt 0 ]; then
echo "Invalid option. Try another one."
continue
fi
keyboard_index=$(( $REPLY-1 ))
keyboard=${keyboards_id[$keyboard_index]}
keyboard_arch=${keyboards_arch[$keyboard_index]}
keyboard_basedir=${keyboards_basedir[$keyboard_index]}
keyboard_title=${options[$keyboard_index]}
keyboard_sibling_var=${keyboard}_siblings[@]
keyboard_sibling_first=${keyboard}_siblings[0]
if [ -n "${!keyboard_sibling_first}" ]; then
keyboard_siblings=${!keyboard_sibling_var}
else
keyboard_siblings=( "${keyboard}" )
fi
split=${keyboards_split[$keyboard_index]}
keyboard_shield=${keyboards_shield[$keyboard_index]}
break
;;
esac
done
if [ "$keyboard_shield" == "y" ]; then
shields=$keyboard_siblings
shield=${keyboard}
shield_title=${keyboard_title}
prompt="Pick an MCU board:"
options=({{#boards}}"{{{name}}}" {{/boards}})
board_ids=({{#boards}}"{{id}}" {{/boards}})
boards_usb_only=({{#boards}}"{{#usb_only}}y{{/usb_only}}{{^usb_only}}n{{/usb_only}}" {{/boards}})
boards_revisions=({{#boards}}"{{#revisions}}{{.}} {{/revisions}}" {{/boards}})
boards_default_revision=({{#boards}}"{{{default_revision}}}" {{/boards}})
echo ""
echo "MCU Board Selection:"
PS3="$prompt "
select opt in "${options[@]}" "Quit"; do
case "$REPLY" in
''|*[!0-9]*) echo "Invalid option. Try another one."; continue;;
$(( ${#options[@]}+1 )) ) echo "Goodbye!"; exit 1;;
*)
if [ $REPLY -gt $(( ${#options[@]}+1 )) ] || [ $REPLY -lt 0 ]; then
echo "Invalid option. Try another one."
continue
fi
board_index=$(( $REPLY-1 ))
if [ -n "${!keyboard_sibling_first}" ] && [ "${boards_usb_only[$board_index]}" = "y" ] ; then
echo "Wired split is not yet supported by ZMK."
exit 1
fi
board=${board_ids[$board_index]}
board_title=${options[$board_index]}
boards=( "${board}" )
break
;;
esac
done
if [ -n "${boards_revisions[$board_index]}" ]; then
read -a _valid_revisions <<< "${boards_revisions[$board_index]}"
_rev_choices=("${_valid_revisions[@]}")
for (( _i=0; _i<${#_valid_revisions}; _i++ )); do
if [ "${boards_default_revision[board_index]}" = "${_valid_revisions[_i]}" ]; then
_rev_choices[_i]+=" (default)"
fi
done
echo ""
echo "MCU Board Revision:"
select opt in "${_rev_choices[@]}" "Quit"; do
case "$REPLY" in
''|*[!0-9]*) echo "Invalid option. Try another one."; continue;;
$(( ${#_valid_revisions[@]}+1 )) ) echo "Goodbye!"; exit 1;;
*)
if [ $REPLY -gt $(( ${#_valid_revisions[@]}+1 )) ] || [ $REPLY -lt 0 ]; then
echo "Invalid option. Try another one."
continue
fi
_rev_index=$(( $REPLY-1 ))
board="${board_ids[$board_index]}@${_valid_revisions[_rev_index]}"
boards=( "${board}" )
break
;;
esac
done
fi
else
board=${keyboard}
boards=$keyboard_siblings
fi
read -r -e -p "Copy in the stock keymap for customization? [Yn]: " copy_keymap
if [ -z "$copy_keymap" ] || [ "$copy_keymap" == "Y" ] || [ "$copy_keymap" == "y" ]; then copy_keymap="yes"; fi
read -r -e -p "GitHub Username (leave empty to skip GitHub repo creation): " github_user
if [ -n "$github_user" ]; then
read -r -p "GitHub Repo Name [zmk-config]: " repo_name
if [ -z "$repo_name" ]; then repo_name="zmk-config"; fi
read -r -p "GitHub Repo [https://github.com/${github_user}/${repo_name}.git]: " github_repo
if [ -z "$github_repo" ]; then github_repo="https://github.com/${github_user}/${repo_name}.git"; fi
else
repo_name="zmk-config"
fi
echo ""
echo "Preparing a user config for:"
if [ "$keyboard_shield" == "y" ]; then
echo "* MCU Board: ${boards}"
echo "* Shield(s): ${shields}"
else
echo "* Board(s): ${boards}"
fi
if [ "$copy_keymap" == "yes" ]; then
echo "* Copy Keymap?: ✓"
else
echo "* Copy Keymap?: ❌"
fi
if [ -n "$github_repo" ]; then
echo "* GitHub Repo To Push (please create this in GH first!): ${github_repo}"
fi
echo ""
read -r -p "Continue? [Yn]: " do_it
if [ -n "$do_it" ] && [ "$do_it" != "y" ] && [ "$do_it" != "Y" ]; then
echo "Aborting..."
exit 1
fi
git clone --single-branch $repo_path ${repo_name}
cd ${repo_name}
pushd config
if [ "$keyboard_shield" == "y" ]; then
url_base="https://raw.githubusercontent.com/zmkfirmware/zmk/main/app/boards/shields/${keyboard_basedir}"
else
url_base="https://raw.githubusercontent.com/zmkfirmware/zmk/main/app/boards/${keyboard_arch}/${keyboard_basedir}"
fi
echo "Downloading config file (${url_base}/${keyboard}.conf)"
if ! $download_command "${url_base}/${keyboard}.conf"; then
echo "Could not find it, falling back to ${url_base}/${keyboard_basedir}.conf"
$download_command "${url_base}/${keyboard_basedir}.conf" || echo "# Put configuration options here" > "${keyboard}.conf"
fi
if [ "$copy_keymap" == "yes" ]; then
echo "Downloading keymap file (${url_base}/${keyboard}.keymap)"
if ! $download_command "${url_base}/${keyboard}.keymap"; then
echo "Could not find it, falling back to ${url_base}/${keyboard_basedir}.keymap"
$download_command "${url_base}/${keyboard_basedir}.keymap" || echo "Warning: Could not find a keymap file to download!"
fi
fi
popd
echo "include:" >> build.yaml
for b in ${boards}; do
if [ -n "${shields}" ];
then
for s in ${shields}; do
echo " - board: ${b}" >> build.yaml
echo " shield: ${s}" >> build.yaml
done
else
echo " - board: ${b}" >> build.yaml
fi
done
rm -rf .git
git init .
git add .
git commit -m "Initial User Config."
if [ -n "$github_repo" ]; then
git remote add origin "$github_repo"
git push --set-upstream origin "$(git symbolic-ref --short HEAD)"
push_return_code=$?
# If push failed, assume that the origin was incorrect and give instructions on fixing.
if [ ${push_return_code} -ne 0 ]; then
echo "Remote repository $github_repo not found..."
echo "Check GitHub URL, and try adding again."
echo "Run the following: "
echo " git remote rm origin"
echo " git remote add origin FIXED_URL"
echo " git push --set-upstream origin $(git symbolic-ref --short HEAD)"
echo "Once pushed, your firmware should be available from GitHub Actions at: ${github_repo%.git}/actions"
exit 1
fi
# TODO: Support determining the actions URL when non-https:// repo URL is used.
if [ "${github_repo}" != "${github_repo#https://}" ]; then
echo "Your firmware should be available from GitHub Actions shortly: ${github_repo%.git}/actions"
fi
fi

3
docs/static/setup.ps1 vendored Normal file
View File

@@ -0,0 +1,3 @@
# setup.ps1
Write-Host "This setup script has been removed. Please use the ZMK CLI instead."
Write-Host "Visit https://zmk.dev/docs/user-setup for more information."

2
docs/static/setup.sh vendored Normal file
View File

@@ -0,0 +1,2 @@
echo "This setup script has been removed. Please use the ZMK CLI instead."
echo "Visit https://zmk.dev/docs/user-setup for more information."