From a25dd58bc56b0c4010673723ac44eaff914979bb Mon Sep 17 00:00:00 2001 From: skullydazed Date: Mon, 15 Jul 2019 12:14:27 -0700 Subject: QMK CLI and JSON keymap support (#6176) * Script to generate keymap.c from JSON file. * Support for keymap.json * Add a warning about the keymap.c getting overwritten. * Fix keymap generating * Install the python deps * Flesh out more of the python environment * Remove defunct json2keymap * Style everything with yapf * Polish up python support * Hide json keymap.c into the .build dir * Polish up qmk-compile-json * Make milc work with positional arguments * Fix a couple small things * Fix some errors and make the CLI more understandable * Make the qmk wrapper more robust * Add basic QMK Doctor * Clean up docstrings and flesh them out as needed * remove unused compile_firmware() function --- docs/cli.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 docs/cli.md (limited to 'docs/cli.md') diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000000..0365f2c9c8 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,31 @@ +# QMK CLI + +This page describes how to setup and use the QMK CLI. + +# Overview + +The QMK CLI makes building and working with QMK keyboards easier. We have provided a number of commands to help you work with QMK: + +* `qmk compile-json` + +# Setup + +Simply add the `qmk_firmware/bin` directory to your `PATH`. You can run the `qmk` commands from any directory. + +``` +export PATH=$PATH:$HOME/qmk_firmware/bin +``` + +You may want to add this to your `.profile`, `.bash_profile`, `.zsh_profile`, or other shell startup scripts. + +# Commands + +## `qmk compile-json` + +This command allows you to compile JSON files you have downloaded from . + +**Usage**: + +``` +qmk compile-json mine.json +``` -- cgit v1.2.3 From f22c5c17b6fe069bec1241262a1c27eb89d3d3af Mon Sep 17 00:00:00 2001 From: skullydazed Date: Sun, 25 Aug 2019 11:58:24 -0700 Subject: Refactor `qmk compile-json` to `qmk compile` (#6592) --- docs/cli.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) (limited to 'docs/cli.md') diff --git a/docs/cli.md b/docs/cli.md index 0365f2c9c8..1843f42cd1 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -6,7 +6,8 @@ This page describes how to setup and use the QMK CLI. The QMK CLI makes building and working with QMK keyboards easier. We have provided a number of commands to help you work with QMK: -* `qmk compile-json` +* `qmk compile` +* `qmk doctor` # Setup @@ -20,12 +21,18 @@ You may want to add this to your `.profile`, `.bash_profile`, `.zsh_profile`, or # Commands -## `qmk compile-json` +## `qmk compile` -This command allows you to compile JSON files you have downloaded from . +This command allows you to compile firmware from any directory. You can compile JSON exports from or compile keymaps in the repo. -**Usage**: +**Usage for Configurator Exports**: ``` -qmk compile-json mine.json +qmk compile +``` + +**Usage for Keymaps**: + +``` +qmk compile -kb -km ``` -- cgit v1.2.3 From 95477749629407e2a9e33c6ccf26ecc8b24ab07a Mon Sep 17 00:00:00 2001 From: skullY Date: Thu, 22 Aug 2019 10:18:52 -0700 Subject: CLI command to format C code --- docs/cli.md | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/cli.md') diff --git a/docs/cli.md b/docs/cli.md index 1843f42cd1..4b8472b19e 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -36,3 +36,13 @@ qmk compile ``` qmk compile -kb -km ``` + +## `qmk cformat` + +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] +``` -- cgit v1.2.3 From d569f0877155efc752994f8a21f5cf001f9d6ae6 Mon Sep 17 00:00:00 2001 From: skullydazed Date: Sun, 22 Sep 2019 13:25:33 -0700 Subject: Configuration system for CLI (#6708) * Rework how bin/qmk handles subcommands * qmk config wip * Code to show all configs * Fully working `qmk config` command * Mark some CLI arguments so they don't pollute the config file * Fleshed out config support, nicer subcommand support * sync with installable cli * pyformat * Add a test for subcommand_modules * Documentation for the `qmk config` command * split config_token on space so qmk config is more predictable * Rework how subcommands are imported * Document `arg_only` * Document deleting from CLI * Document how multiple operations work * Add cli config to the doc index * Add tests for the cli commands * Make running the tests more reliable * Be more selective about building all default keymaps * Update new-keymap to fit the new subcommand style * Add documentation about writing CLI scripts * Document new-keyboard * Update docs/cli_configuration.md Co-Authored-By: noroadsleft <18669334+noroadsleft@users.noreply.github.com> * Update docs/cli_development.md Co-Authored-By: noroadsleft <18669334+noroadsleft@users.noreply.github.com> * Update docs/cli_development.md Co-Authored-By: noroadsleft <18669334+noroadsleft@users.noreply.github.com> * Update docs/cli_development.md Co-Authored-By: noroadsleft <18669334+noroadsleft@users.noreply.github.com> * Address yan's comments. * Apply suggestions from code review suggestions from @noahfrederick Co-Authored-By: Noah Frederick * Apply suggestions from code review Co-Authored-By: Noah Frederick * Remove pip3 from the test runner --- docs/cli.md | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 106 insertions(+), 8 deletions(-) (limited to 'docs/cli.md') diff --git a/docs/cli.md b/docs/cli.md index 4b8472b19e..cb609e2a93 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -4,22 +4,70 @@ This page describes how to setup and use the QMK CLI. # Overview -The QMK CLI makes building and working with QMK keyboards easier. We have provided a number of commands to help you work with QMK: +The QMK CLI makes building and working with QMK keyboards easier. We have provided a number of commands to simplify and streamline tasks such as obtaining and compiling the QMK firmware, creating keymaps, and more. -* `qmk compile` -* `qmk doctor` +* [Global CLI](#global-cli) +* [Local CLI](#local-cli) +* [CLI Commands](#cli-commands) -# Setup +# Requirements -Simply add the `qmk_firmware/bin` directory to your `PATH`. You can run the `qmk` commands from any directory. +The CLI requires Python 3.5 or greater. We try to keep the number of requirements small but you will also need to install the packages listed in [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt). + +# Global CLI + +QMK provides an installable CLI that can be used to setup your QMK build environment, work with QMK, and which makes working with multiple copies of `qmk_firmware` easier. We recommend installing and updating this periodically. + +## Install Using Homebrew (macOS, some Linux) + +If you have installed [Homebrew](https://brew.sh) you can tap and install QMK: + +``` +brew tap qmk/qmk +brew 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 +``` + +## Install Using easy_install or pip + +If your system is not listed above you can install QMK manually. First ensure that you have python 3.5 (or later) installed and have installed pip. Then install QMK with this command: + +``` +pip3 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 +``` + +## Packaging For Other Operating Systems + +We are looking for people to create and maintain a `qmk` package for more operating systems. If you would like to create a package for your OS please follow these guidelines: + +* Follow best practices for your OS when they conflict with these guidelines + * Documment 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**: ``` -export PATH=$PATH:$HOME/qmk_firmware/bin +$ ~/qmk_firmware/bin/qmk hello +Ψ Hello, World! ``` -You may want to add this to your `.profile`, `.bash_profile`, `.zsh_profile`, or other shell startup scripts. +## Local CLI Limitations -# Commands +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 compile` @@ -46,3 +94,53 @@ This command formats C code using clang-format. Run it with no arguments to form ``` qmk cformat [file1] [file2] [...] [fileN] ``` + +## `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 doctor` + +This command examines your environment and alerts you to potential build or flash problems. + +**Usage**: + +``` +qmk doctor +``` + +## `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` + +This command formats python code in `qmk_firmware`. + +**Usage**: + +``` +qmk pyformat +``` + +## `qmk pytest` + +This command runs the python test suite. If you make changes to python code you should ensure this runs successfully. + +**Usage**: + +``` +qmk pytest +``` -- cgit v1.2.3 From de386e5972597e89bda99022d30591ae2f6087b5 Mon Sep 17 00:00:00 2001 From: Erik Doffagne Date: Wed, 2 Oct 2019 22:41:32 +0200 Subject: Fixed typos in documentation (#6871) * Fixed typos in documentation * Update docs/arm_debugging.md Co-Authored-By: fauxpark * Update docs/arm_debugging.md Co-Authored-By: fauxpark --- docs/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/cli.md') diff --git a/docs/cli.md b/docs/cli.md index cb609e2a93..fe86cac1fb 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -44,7 +44,7 @@ qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build We are looking for people to create and maintain a `qmk` package for more operating systems. If you would like to create a package for your OS please follow these guidelines: * Follow best practices for your OS when they conflict with these guidelines - * Documment why in a comment when you do deviate + * 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`. -- cgit v1.2.3 From f04e58dad6f56cdbd5d369c9e00405dcdb47c8ea Mon Sep 17 00:00:00 2001 From: Dan McClain Date: Mon, 7 Oct 2019 14:32:30 -0400 Subject: [CLI] Add `qmk list_keyboards` (#6927) `list_keyboards` replicates the `make list-keyboards` by globbing for all paths that include `rules.mk` and then removing the paths that include `keymaps`. This basis of this cli command could be reused in the future as a util, but is not done so here since this would be the only place that would use it currently Resolves #6911 --- docs/cli.md | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/cli.md') diff --git a/docs/cli.md b/docs/cli.md index fe86cac1fb..6ffe033653 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -115,6 +115,16 @@ This command examines your environment and alerts you to potential build or flas qmk doctor ``` +## `qmk list_keyboards` + +This command lists all the keyboards currently defined in `qmk_firmware` + +**Usage**: + +``` +qmk list_keyboards +``` + ## `qmk new-keymap` This command creates a new keymap based on a keyboard's existing default keymap. -- cgit v1.2.3 From 2707652c9877e5fc7dd67670f8e14962c31baf42 Mon Sep 17 00:00:00 2001 From: fauxpark Date: Wed, 9 Oct 2019 05:06:26 +1100 Subject: [Docs] CLI command to serve docs locally (#6956) * CLI command to serve docs locally * Document it * Default port * Use `with` and subclass `SimpleHTTPRequestHandler` to set working dir * Apply suggestions from code review Co-Authored-By: skullydazed * Update docs/cli.md --- docs/cli.md | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/cli.md') diff --git a/docs/cli.md b/docs/cli.md index 6ffe033653..d150ee917d 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -105,6 +105,16 @@ This command lets you configure the behavior of QMK. For the full `qmk config` d 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. -- cgit v1.2.3 From a5a31a5fc0f14f4f66cf362ee85747be159e364d Mon Sep 17 00:00:00 2001 From: Erovia Date: Sun, 13 Oct 2019 20:23:11 +0200 Subject: MILC: Use dashes instead of underscores for subcommands The subcommand functions' name follows the Python convention of using snake case, but looks odd on the command line. Fix it by converting underscores to dashes, eg.: list_keyboards -> list-keyboards. --- docs/cli.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/cli.md') diff --git a/docs/cli.md b/docs/cli.md index d150ee917d..0d3703c8cf 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -125,14 +125,14 @@ This command examines your environment and alerts you to potential build or flas qmk doctor ``` -## `qmk list_keyboards` +## `qmk list-keyboards` This command lists all the keyboards currently defined in `qmk_firmware` **Usage**: ``` -qmk list_keyboards +qmk list-keyboards ``` ## `qmk new-keymap` -- cgit v1.2.3 From e0e26957d43018998c405783a2609b99f0e098a7 Mon Sep 17 00:00:00 2001 From: "St. John Johnson" Date: Mon, 28 Oct 2019 18:24:36 -0700 Subject: Fix the CLI docs (#6979) - Sort the commands alphabetically - Add missing `json_keymap` - Correct underscore to dash --- docs/cli.md | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) (limited to 'docs/cli.md') diff --git a/docs/cli.md b/docs/cli.md index 0d3703c8cf..e655b0ee89 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -69,6 +69,16 @@ There are some limitations to the local CLI compared to the global CLI: # CLI Commands +## `qmk cformat` + +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 or compile keymaps in the repo. @@ -85,16 +95,6 @@ qmk compile qmk compile -kb -km ``` -## `qmk cformat` - -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 config` This command lets you configure the behavior of QMK. For the full `qmk config` documentation see [CLI Configuration](cli_configuration.md). @@ -125,6 +125,16 @@ This command examines your environment and alerts you to potential build or flas qmk doctor ``` +## `qmk json-keymap` + +Creates a keymap.c from a QMK Configurator export. + +**Usage**: + +``` +qmk json-keymap [-o OUTPUT] filename +``` + ## `qmk list-keyboards` This command lists all the keyboards currently defined in `qmk_firmware` -- cgit v1.2.3 From 7329c2d02d38f40a23d38f789de34057fd2acd42 Mon Sep 17 00:00:00 2001 From: Cody Bender <50554676+cfbender@users.noreply.github.com> Date: Tue, 12 Nov 2019 21:55:41 -0700 Subject: Add cli convert subcommand, from raw KLE to JSON (#6898) * Add initial pass at KLE convert * Add cli log on convert * Move kle2xy, add absolute filepath arg support * Add overwrite flag, and context sensitive conversion * Update docs/cli.md * Fix converter.py typo * Add convert unit test * Rename to kle2qmk * Rename subcommand * Rename subcommand to kle2json * Change tests to cover rename * Rename in __init__.py * Update CLI docs with new subcommand name * Fix from suggestions in PR #6898 * Help with cases of case sensitivity * Update cli.md * Use angle brackets to indicate required option * Make the output text more accurate --- docs/cli.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'docs/cli.md') diff --git a/docs/cli.md b/docs/cli.md index e655b0ee89..fb7d17d2a1 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -135,6 +135,28 @@ Creates a keymap.c from a QMK Configurator export. 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] +``` + +**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` -- cgit v1.2.3 From 897888db419239f013561b155de5993b1966820e Mon Sep 17 00:00:00 2001 From: jorgemanzo Date: Fri, 4 Oct 2019 23:38:34 -0700 Subject: Add CLI command for flashing a keyboard A new CLI subcommand was added, flash, which behaves very similar to the already present compile CLI comamnd, but with the added ability to target a bootloader. The command is used like so: qmk flash [-h] [-b] [-kb KEYBOARD] [-km KEYMAP] [-bl BOOTLOADER] [filename]. A -kb and -km is expected, or a configurator export JSON filename. A bootloader can be specified using -bl , and if left unspecified, the target is assumed to be :flash. -bl can be used to list the available bootloaders. If -km is provided, but no -kb , then a message is printed suggesting the user to run qmk list_keyboards. --- docs/cli.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) (limited to 'docs/cli.md') diff --git a/docs/cli.md b/docs/cli.md index fb7d17d2a1..1c09527221 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -95,6 +95,30 @@ qmk compile qmk compile -kb -km ``` +## `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 `. Visit +for more details of the available bootloaders. + +**Usage for Configurator Exports**: + +``` +qmk flash -bl +``` + +**Usage for Keymaps**: + +``` +qmk flash -kb -km -bl +``` + +**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). -- cgit v1.2.3