summaryrefslogtreecommitdiffstats
path: root/docs/zh-cn/cli_commands.md
blob: ed36ed975bbcaf58ca17d4a0f6e9f0aac1ad9f45 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
# QMK CLI 命令

<!---
  original document: 0.15.12:docs/cli_commands.md
  git diff 0.15.12 HEAD -- docs/cli_commands.md | cat
-->

# 用户命令

## `qmk compile`

该命令用于在指定目录下编译固件,可用于构建<https://config.qmk.fm>导出的JSON数据,代码库中的键映射,或是当前目录下的键盘。

该命令会尝试感知目录路径,当你在键盘或键映射目录下执行时,KEYBOARD及KEYMAP参数将被自动填入。

**用于配置器导出的数据时**:

```
qmk compile [-c] <configuratorExport.json>
```

**用于键映射时**:

```
qmk compile [-c] [-e <var>=<value>] [-j <num_jobs>] -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 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
...
```

**并行编译**:

在编译时添加 `-j`/`--parallel` 开关可能有助于加快编译速度。
```
qmk compile -j <num_jobs> -kb <keyboard_name>
```
`num_jobs` 用于指定并行的job上限,将其设置为0可以实现无限制的并行编译。
```
qmk compile -j 0 -kb <keyboard_name>
```

## `qmk flash` :id=qmk-flash

该命令与 `qmk compile` 类似,但额外地可以指定bootloader。bootloader参数是可选的,默认会指定为 `:flash`。可通过 `-bl <bootloader>` 来指定bootloader。请查阅[刷写固件](zh-cn/flashing.md)指引以深入了解可用的bootloader信息。

该命令会尝试感知目录路径,当你在键盘或键映射目录下执行时,KEYBOARD及KEYMAP参数将被自动填入。

**用于配置器导出的数据时**:

```
qmk flash [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>] <configuratorExport.json>
```

**用于键映射时**:

```
qmk flash -kb <keyboard_name> -km <keymap_name> [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>]
```

**列出所有bootloader**

```
qmk flash -b
```

## `qmk config`

该命令用于配置QMK功能,完整的 `qmk config` 文档参见[CLI配置](zh-cn/cli_configuration.md)。

**使用方法**:

```
qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
```

## `qmk cd`

该命令会启动一个新的 shell 会话并定位到 `qmk_firmware` 所在目录。

须留意如果你已经位于 `QMK_HOME` 下的某个位置(比如 `keyboards/` 目录中),该指令不会生效。

若要退回到原来的 shell 会话,只需要执行 `exit`。

**使用方法**:

```
qmk cd
```

## `qmk console`

该命令用于连接键盘终端并展示调试信息。仅当键盘固件通过 `CONSOLE_ENABLE=yes` 编译时有效。

**用法**:

```
qmk console [-d <pid>:<vid>[:<index>]] [-l] [-n] [-t] [-w <seconds>]
```

**示例**:

连接到所有可用的键盘并输出终端信息:

```
qmk console
```

列出所有设备:

```
qmk console -l
```

仅输出 clueboard/66/rev3 键盘的信息:

```
qmk console -d C1ED:2370
```

仅输出第二把 clueboard/66/rev3 键盘的信息:

```
qmk console -d C1ED:2370:2
```

输出时间戳及VID:PID以替代键盘名:

```
qmk console -n -t
```

屏蔽bootloader的消息:

```
qmk console --no-bootloaders
```

## `qmk doctor`

该命令用以检查你的开发环境并对发现的潜在的构建及刷写问题进行提醒,如果您乐意,它也可以修复其中大部分问题。

**用法**:

```
qmk doctor [-y] [-n]
```

**示例**:

检查开发环境中的问题并提示是否修复:

    qmk doctor

检查开发环境中的问题并自动进行修复:

    qmk doctor -y

检查开发环境中的问题,仅生成报告:

    qmk doctor -n

## `qmk format-json`

将JSON文件格式化为(尽量)便于阅读的形式。会自动分辨JSON结构类型(info.json还是keymap.json),必要时也可以通过 `--format` 指定。

**用法**:

```
qmk format-json [-f FORMAT] <json_file>
```

## `qmk info`

展示QMK中的键盘及键映射信息,该命令用来获取键盘信息,输出配列,展示底层按键矩阵,及格式化地输出键映射JSON数据。

**用法**:

```
qmk info [-f FORMAT] [-m] [-l] [-km KEYMAP] [-kb KEYBOARD]
```

该命令会尝试感知目录路径,当你在键盘或键映射目录下执行时,KEYBOARD及KEYMAP参数将被自动填入。

**示例**:

输出键盘的基础信息:

    qmk info -kb planck/rev5

输出键盘的矩阵信息:

    qmk info -kb ergodox_ez -m

输出键盘的键映射JSON数据:

    qmk info -kb clueboard/california -km default

## `qmk json2c`

从QMK配置器导出的数据中生成 keymap.c 文件
Creates a keymap.c from a QMK Configurator export.

**用法**:

```
qmk json2c [-o OUTPUT] filename
```

## `qmk c2json`

从 keymap.c 文件中生成 keymap.json
**注意:** 解析C代码文件并不容易,该命令有可能无法对你的键映射文件生效,不使用C预处理代码有时可以解决问题。

**用法**:

```
qmk c2json -km KEYMAP -kb KEYBOARD [-q] [--no-cpp] [-o OUTPUT] filename
```

## `qmk lint`

检查键盘及键映射数据并提示出常见错误与问题,以及不符合模板规范的地方。

**用法**:

```
qmk lint [-km KEYMAP] [-kb KEYBOARD] [--strict]
```

该命令会尝试感知目录路径,当你在键盘或键映射目录下执行时,KEYBOARD及KEYMAP参数将被自动填入。

**示例**:

基本的lint检查:

    qmk lint -kb rominronin/katana60/rev2

## `qmk list-keyboards`

该命令可以列出 `qmk_firmware` 中所有的键盘

**用法**:

```
qmk list-keyboards
```

## `qmk list-keymaps`

该命令可以列出指定键盘(及指定版本)下的所有键映射。

该命令会尝试感知目录路径,当你在键盘或键映射目录下执行时,KEYBOARD及KEYMAP参数将被自动填入。

**用法**:

```
qmk list-keymaps -kb planck/ez
```

## `qmk new-keyboard`

该命令可基于现有模板创建出新的键盘定义。

对于未给出的参数,会提示你输入,若未传入 `-u` 参数且 .gitconfig 中设置了 `user.name`,则会提示你使用该值作为默认用户名。

**用法**:

```
qmk new-keyboard [-kb KEYBOARD] [-t {avr,ps2avrgb}] -u USERNAME
```

## `qmk new-keymap`

该命令可基于键盘已有的默认键映射创建新的键映射。

该命令会尝试感知目录路径,当你在键盘或键映射目录下执行时,KEYBOARD及KEYMAP参数将被自动填入。

**用法**:

```
qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
```

## `qmk clean`

该命令会清理 `.build` 目录,若传入 `--all` 开关,在 `qmk_firmware` 下的所有.hex及.bin文件也会一并删除。

**用法**:

```
qmk clean [-a]
```

---

# 面向开发者的命令

## `qmk format-text`

该命令会重新格式化并统一文件的换行符。

代码库下所有的文件须使用Unix换行符(LF)。
若你在**Windows**下进行开发,必须确保文件中的换行符是正确的,才能让你的PR被允许合入。

```
qmk format-text
```

## `qmk format-c`

该命令会使用clang-format来格式化C代码。

不带参数地执行该命令以用来格式化核心代码相关的改动,默认会通过 `git diff` 来检查 `origin/master`, 可以通过 `-b <分支名>` 来改变检查的分支。

带着 `-a` 开关执行命令会格式化所有的核心代码,也可以在命令行中传入文件名来指定格式化某个文件。

**用以处理指定文件时**:

```
qmk format-c [file1] [file2] [...] [fileN]
```

**用以处理所有的核心代码时**:

```
qmk format-c -a
```

**用以处理 origin/master 下的所有改动时**:

```
qmk format-c
```

**用以处理指定分支下的所有改动时**:

```
qmk format-c -b branch_name
```

## `qmk generate-compilation-database`

**用法**:

```
qmk generate-compilation-database [-kb KEYBOARD] [-km KEYMAP]
```

创建新 `compile_commands.json` 文件。

你的IDE/编辑器是否使用了“编程语言本地服务器”(language server)且 _总是_ 无法找到全部的包含文件(include files)?是不是很讨厌红色的波浪线?想不想让你的编辑器看得懂 `#include QMK_KEYBOARD_H`?你需要的是一个[编译数据库](https://clang.llvm.org/docs/JSONCompilationDatabase.html)!而 QMK 可以帮助你构建出一个。

该命令需要知道你在构建的是哪个键盘及键映射,它使用与 `qmk compile` 命令一样的选项:参数、当前目录以及配置文件。

**示例:**

```
$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
$ qmk generate-compilation-database
Ψ Making clean
Ψ Gathering build instructions from make -n gh60/satan:colemak
Ψ Found 50 compile commands
Ψ Writing build database to /Users/you/src/qmk_firmware/compile_commands.json
```

现在可以打开你的开发环境并享受没有波浪线的日子了。

## `qmk docs`

该命令会在本地启动一个HTTP服务,从而你可以浏览及改进文档,默认端口号为8936,使用 `-b`/`--browser` 开关可以让该命令自动通过默认浏览器打开链接地址。

**用法**:

```
qmk docs [-b] [-p PORT]
```

## `qmk generate-docs`

该命令可以在本地生成QMK文档,用以文档的常规浏览使用,或进行文档改进工作。可以使用类似[serve](https://www.npmjs.com/package/serve)这样的工具来浏览生成的文档文件。

**用法**:

```
qmk generate-docs
```

## `qmk generate-rgb-breathe-table`

该命令可以生成用于[RGB灯光](zh-cn/feature_rgblight.md)的呼吸效果的查询表(LUT)头文件。将该文件命名为 `rgblight_breathe_table.h` 并放入键盘或键映射目录下,可以覆盖替换 `quantum/rgblight/` 下的默认LUT。

**用法**:

```
qmk generate-rgb-breathe-table [-q] [-o OUTPUT] [-m MAX] [-c CENTER]
```

## `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 format-python`

该命令可以对 `qmk_firmware` 下的python代码进行格式化。

**用法**:

```
qmk format-python
```

## `qmk pytest`

该命令会执行python测试框架,在你更改了python代码后,应确保该命令可以成功执行。

**用法**:

```
qmk pytest
```

**示例**:

执行全部的测试套件:

    qmk pytest

执行指定的测试用例组:

    qmk pytest -t qmk.tests.test_cli_commands

执行单个测试用例:

    qmk pytest -t qmk.tests.test_cli_commands.test_c2json
    qmk pytest -t qmk.tests.test_qmk_path