总结
qmk cli使构建和使用qmk键盘变得更加容易。我们提供了许多命令来简化和合理化任务,例如获取和编译qmk固件、创建密钥映射等。
需求
使用Homebrew安装(macOS,以及某些Linux)
如果你已经安装了Homebrew,你可以点击并安装QMK:
代码如下:
brew install qmk/qmk/qmk
export QMK_HOME=’~/qmk_firmware’ # Optional, set the location for `qmk_firmware`
qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment
安装并使用pip(Python包管理工具)
如果您的系统并不在上面列出的范围之内,您可以手动安装QMK。首先您需要确保安装了Python 3.6(或更高版本)并安装了pip。然后请使用以下命令安装QMK
python3 -m pip install qmk
export QMK_HOME=’~/qmk_firmware’ # Optional, set the location for `qmk_firmware`
qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment
为其他操作系统适配安装包
我们正在寻找为更多操作系统创建和维护qmk安装包的人员。如果你想为你的操作系统创建一个安装包包,请遵循这些指南:
·当您的操作系统与这些指导方针冲突时,请遵循它们的最佳解决方案
·当您确实需要脱离指导方针时,请在注释中记录原因
·请使用虚拟环境安装
·请指导用户设置环境变量QMK_HOME,以便在~/qmk_firmware之外的地方检出固件源。
QMK CLI配置
本文档解释了你应该如何配置qmk CLI
介绍
配置QMK CLI实际上是去配置一个键/值系统。每个键由一个子命令和一个用句点分隔的参数名称组成。这允许在您配置的键和它们设置的参数之间进行直接的转换。
一个简单的例子
作为一个示例,让我们看看这行命令qmk compile——keyboard clueboard/66/rev4——keymap default。
有两个命令行参数可以从这个配置中读取:
·compile.keyboard
·compile.keymap
接下来让我们现在设置一下这些:
$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default
compile.keyboard: None -> clueboard/66/rev4
compile.keymap: None -> default
Ψ Wrote configuration to ‘/Users/example/Library/Application Support/qmk/qmk.ini’
现在,我可以运行qmk编译程序了,而无需每次都要指定键盘和键映射。
设置用户默认值
有时您希望在多个命令之间共享一个设置。例如,多个命令采用一个共同的参数–keyboard。您不需要为每个命令设置该值,您可以设置一个用户值,该值将被任何接受该参数的命令所使用。
例子:
$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default
user.keyboard: None -> clueboard/66/rev4
user.keymap: None -> default
Ψ Wrote configuration to ‘/Users/example/Library/Application Support/qmk/qmk.ini’
CLI文档(qmkconfig 命令)
qmk config命令用于与底层配置交互。当不带参数运行时,它将显示当前的配置。当提供参数时,它们被假定为配置的标记,这些标记是不包含空格的字符串,形式如下:
<subcommand|general|default>[.<key>][=<value>]
设置配置值
您可以通过在配置键中放入一个等号(=)来设置配置值。键必须总是遵循<section>.<key>的格式,例如:
$ qmk config default.keymap=default
default.keymap: None -> default
Ψ Wrote configuration to ‘/Users/example/Library/Application Support/qmk/qmk.ini’
阅读配置值
您可以读取整个配置、单个键或整个节的配置值。您还可以指定多个键来显示多个值。
整个配置示例:
qmk config
整个部分的示例:
qmk config compile
单个键示例:
qmk config compile.keyboard
多个键示例:
qmk config user compile.keyboard compile.keymap
删除配置值
可以通过将配置值设置为特殊字符串None来删除该配置值。
例如:
$ qmk config default.keymap=None
default.keymap: default -> None
Ψ Wrote configuration to ‘/Users/example/Library/Application Support/qmk/qmk.ini’
多个操作并行
您可以将多个读和写操作合并到一个命令中。它们将按以下顺序执行和显示:
$ qmk config compile default.keymap=default compile.keymap=None
compile.keymap=skully
compile.keyboard=clueboard/66_hotswap/gen1
default.keymap: None -> default
compile.keymap: skully -> None
Ψ Wrote configuration to ‘/Users/example/Library/Application Support/qmk/qmk.ini’
用户配置选项
所有的用户配置选项
常用命令
QMK CLI命令
用户命令
编译qmk
此命令是直接可见的的。如果你在任何键盘或键图的目录时,它将自动填写键盘和/或键图。
配置器导出的用法:
qmk compile <configuratorExport.json>
键映射的用法:
qmk compile -kb <keyboard_name> -km <keymap_name>
键盘目录中的用法:
您必须在键盘目录中使用默认键图,或在键盘键图目录中使用–keymap <keymap_name>命令:
qmk compile
用于建立所有支持一个特定的键图的键盘:
qmk compile -kb all -km <keymap_name>
例子:
$ qmk config compile.keymap=default
$ cd ~/qmk_firmware/keyboards/planck/rev6
$ qmk compile
Ψ Compiling keymap with make planck/rev6:default
…
或者您可以选用可选的键映射参数:
$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4
$ qmk compile -km 66_iso
Ψ Compiling keymap with make clueboard/66/rev4:66_iso
…
或者在键盘目录内:
$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
$ qmk compile
Ψ Compiling keymap with make make gh60/satan:colemak
…
在层布局目录使用:
条件是必须在qmk_firmware/layouts/下,并在键映射文件夹中。
qmk compile -kb <keyboard_name>
例子:
$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi
$ qmk compile -kb dz60
Ψ Compiling keymap with make dz60:mechmerlin-ansi
…
刷写qmk
此命令是可被目录感知的。如果你在键盘或键图目录时,它将自动填写到你的键盘和/或键图中。
在导出配置器的使用方法:
qmk flash <configuratorExport.json> -bl <bootloader>
在键映射(键图)中的使用方法:
qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader>
装载引导器清单:
qmk flash -b
配置qmk
用法:
qmk config [-ro] [config_token1] [config_token2] […] [config_tokenN]
qmk医生
此命令可以帮助您检查您的环境,并提醒您潜在的构建或刷写问题。如果您使用恰当的话,它可以解决很多问题。
用法:
qmk doctor [-y] [-n]
例子:(常用示例)
检查您的环境问题,并提示修复它们:
qmk doctor
检查您的环境并自动修复任何发现的问题:
qmk doctor -y
检查您的环境并只报告问题
qmk doctor -n
qmk的相关信息
这是指在QMK中显示的有关键盘和键映射的信息。您可以使用它来获取有关键盘的信息、显示布局、显示底层的键矩阵,或者制作精良的JSON键映射。
用法:
qmk info [-f FORMAT] [-m] [-l] [-km KEYMAP] [-kb KEYBOARD]
此命令是可被目录感知的。如果你在键盘或键图目录时,它将自动填写到你的键盘和/或键图中。
例子:(常用示例)
显示键盘的基本信息:
qmk info -kb planck/rev5
显示键盘矩阵:
qmk info -kb ergodox_ez -m
显示键盘的JSON键映射:
qmk info -kb clueboard/california -km default
qmk json2c
从QMK配置器导出并创建一个keymap.c文件。
用法:
qmk json2c [-o OUTPUT] filename
qmk 键盘列表
这个命令列出了qmk_firmware中当前所有已经被定义过的键盘
用法:
qmk键映射列表
这个命令用于列出指定键盘(和被修订过版本)的所有键映射。
此命令是可被目录感知的。如果你在键盘或键图目录时,它将自动填写到你的键盘和/或键图中。
用法:
qmk list-keymaps -kb planck/ez
qmk 新的键映射
这个命令用于创建一个基于现存标准键映射的新的键映射(键图)
此命令是可被目录感知的。如果你在键盘或键图目录时,它将自动填写到你的键盘和/或键图中。
用法:
qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
开发者命令
qmk cformat
使用这个命令可以用clang-format格式化C语言代码。
请不要带参数运行它,这样才能格式化所有已更改的核心代码。默认用git diff检查origin/master,分支可以改变使用-b <branch_name>来更改
请使用使用-a运行它,以格式化所有核心代码,或在命令行上传递文件名,以便在特定文件上运行它。
指定文件的用法:
qmk cformat [file1] [file2] […] [fileN]
在所有核心文件上使用它:
qmk cformat -a
仅对更改的原始/主文件格式化:
qmk cformat
仅对更改的branch_name文件格式化:
qmk cformat -b branch_name
qmk dcos
这个命令用来启动一个本地HTTP服务器,您可以使用它浏览或改进文档。默认端口是8936。
用法:
qmk docs [-p PORT]
qmk kle2json
该命令允许您将原始KLE数据转换为QMK配置器的JSON格式。它接受直接的文件路径或当前目录中的文件名。默认情况下,它不会覆盖已经存在的文件。如果需要,则会使用info.json格式或者使用-f或-force标志来覆盖。
用法:
qmk kle2json [-f] <filename>
例子:
$ qmk kle2json kle.txt
☒ File info.json already exists, use -f or –force to overwrite.
或者
$ qmk kle2json -f kle.txt -f
Ψ Wrote out to info.json
qmk pyformat
该命令用于在qmk_firmware中格式化python代码。
用法:
qmk pyformat
qmk pytest
该命令用于运行python测试套件。如果您需要对python代码进行更改,您应该确保它能够成功运行。
用法: