diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/cli.md | 250 | ||||
| -rw-r--r-- | docs/cli_commands.md | 10 | ||||
| -rw-r--r-- | docs/cli_development.md | 12 |
3 files changed, 21 insertions, 251 deletions
diff --git a/docs/cli.md b/docs/cli.md index 625ac4fb70..760fe1cdb5 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -37,253 +37,3 @@ We are looking for people to create and maintain a `qmk` package for more operat * Document why in a comment when you do deviate * Install using a virtualenv * Instruct the user to set the environment variable `QMK_HOME` to have the firmware source checked out somewhere other than `~/qmk_firmware`. - -# Local CLI - -If you do not want to use the global CLI there is a local CLI bundled with `qmk_firmware`. You can find it in `qmk_firmware/bin/qmk`. You can run the `qmk` command from any directory and it will always operate on that copy of `qmk_firmware`. - -**Example**: - -``` -$ ~/qmk_firmware/bin/qmk hello -Ψ Hello, World! -``` - -## Local CLI Limitations - -There are some limitations to the local CLI compared to the global CLI: - -* The local CLI does not support `qmk setup` or `qmk clone` -* The local CLI always operates on the same `qmk_firmware` tree, even if you have multiple repositories cloned. -* The local CLI does not run in a virtualenv, so it's possible that dependencies will conflict - -# CLI Commands - -## `qmk cformat` - -*dev mode* - -This command formats C code using clang-format. Run it with no arguments to format all core code, or pass filenames on the command line to run it on specific files. - -**Usage**: - -``` -qmk cformat [file1] [file2] [...] [fileN] -``` - -## `qmk compile` - -This command allows you to compile firmware from any directory. You can compile JSON exports from <https://config.qmk.fm>, compile keymaps in the repo, or compile the keyboard in the current working directory. - -**Usage for Configurator Exports**: - -``` -qmk compile <configuratorExport.json> -``` - -**Usage for Keymaps**: - -``` -qmk compile -kb <keyboard_name> -km <keymap_name> -``` - -**Usage in Keyboard Directory**: - -Must be in keyboard directory with a default keymap, or in keymap directory for keyboard, or supply one with `--keymap <keymap_name>` -``` -qmk compile -``` - -**Example**: -``` -$ qmk config compile.keymap=default -$ cd ~/qmk_firmware/keyboards/planck/rev6 -$ qmk compile -Ψ Compiling keymap with make planck/rev6:default -... -``` -or with optional keymap argument - -``` -$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4 -$ qmk compile -km 66_iso -Ψ Compiling keymap with make clueboard/66/rev4:66_iso -... -``` -or in keymap directory - -``` -$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak -$ qmk compile -Ψ Compiling keymap with make make gh60/satan:colemak -... -``` - -**Usage in Layout Directory**: - -Must be under `qmk_firmware/layouts/`, and in a keymap folder. -``` -qmk compile -kb <keyboard_name> -``` - -**Example**: -``` -$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi -$ qmk compile -kb dz60 -Ψ Compiling keymap with make dz60:mechmerlin-ansi -... -``` - -## `qmk flash` - -This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default. -To specify a different bootloader, use `-bl <bootloader>`. Visit <https://docs.qmk.fm/#/flashing> -for more details of the available bootloaders. - -**Usage for Configurator Exports**: - -``` -qmk flash <configuratorExport.json> -bl <bootloader> -``` - -**Usage for Keymaps**: - -``` -qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader> -``` - -**Listing the Bootloaders** - -``` -qmk flash -b -``` - -## `qmk config` - -This command lets you configure the behavior of QMK. For the full `qmk config` documentation see [CLI Configuration](cli_configuration.md). - -**Usage**: - -``` -qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] -``` - -## `qmk docs` - -This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936. - -**Usage**: - -``` -qmk docs [-p PORT] -``` - -## `qmk doctor` - -This command examines your environment and alerts you to potential build or flash problems. It can fix many of them if you want it to. - -**Usage**: - -``` -qmk doctor [-y] [-n] -``` - -**Examples**: - -Check your environment for problems and prompt to fix them: - - qmk doctor - -Check your environment and automatically fix any problems found: - - qmk doctor -y - -Check your environment and report problems only: - - qmk doctor -n - -## `qmk json-keymap` - -Creates a keymap.c from a QMK Configurator export. - -**Usage**: - -``` -qmk json-keymap [-o OUTPUT] filename -``` - -## `qmk kle2json` - -This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `info.json` if it is already present. Use the `-f` or `--force` flag to overwrite. - -**Usage**: - -``` -qmk kle2json [-f] <filename> -``` - -**Examples**: - -``` -$ 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 list-keyboards` - -This command lists all the keyboards currently defined in `qmk_firmware` - -**Usage**: - -``` -qmk list-keyboards -``` - -## `qmk list-keymaps` - -This command lists all the keymaps for a specified keyboard (and revision). - -**Usage**: - -``` -qmk list-keymaps -kb planck/ez -``` - -## `qmk new-keymap` - -This command creates a new keymap based on a keyboard's existing default keymap. - -**Usage**: - -``` -qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] -``` - -## `qmk pyformat` - -*dev mode* - -This command formats python code in `qmk_firmware`. - -**Usage**: - -``` -qmk pyformat -``` - -## `qmk pytest` - -*dev mode* - -This command runs the python test suite. If you make changes to python code you should ensure this runs successfully. - -**Usage**: - -``` -qmk pytest -``` diff --git a/docs/cli_commands.md b/docs/cli_commands.md index eb5362bd29..570f841bc8 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -4,6 +4,8 @@ ## `qmk cformat` +*(dev mode)* + This command formats C code using clang-format. Run it with no arguments to format all core code that has been changed. Default checks `origin/master` with `git diff`, branch can be changed using `-b <branch_name>` @@ -138,6 +140,8 @@ qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] ## `qmk docs` +*(dev mode)* + This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936. **Usage**: @@ -182,6 +186,8 @@ qmk json2c [-o OUTPUT] filename ## `qmk kle2json` +*(dev mode)* + This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `info.json` if it is already present. Use the `-f` or `--force` flag to overwrite. **Usage**: @@ -234,6 +240,8 @@ qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] ## `qmk pyformat` +*(dev mode)* + This command formats python code in `qmk_firmware`. **Usage**: @@ -244,6 +252,8 @@ qmk pyformat ## `qmk pytest` +*(dev mode)* + This command runs the python test suite. If you make changes to python code you should ensure this runs successfully. **Usage**: diff --git a/docs/cli_development.md b/docs/cli_development.md index e41afc42f4..2a967de4ab 100644 --- a/docs/cli_development.md +++ b/docs/cli_development.md @@ -6,7 +6,17 @@ This document has useful information for developers wishing to write new `qmk` s The QMK CLI operates using the subcommand pattern made famous by git. The main `qmk` script is simply there to setup the environment and pick the correct entrypoint to run. Each subcommand is a self-contained module with an entrypoint (decorated by `@cli.subcommand()`) that performs some action and returns a shell returncode, or None. -*Tip*: Enable dev mode by `qmk config user.developer=True` +## Developer mode: + +If you intend to maintain keyboards and/or contribute to QMK, you can enable the CLI's "Developer" mode: + +`qmk config user.developer=True` + +This will allow you to see all available subcommands. +**Note:** You will have to install additional requirements: +```bash +python3 -m pip install -r requirements-dev.txt +``` # Subcommands |