diff options
Diffstat (limited to 'docs/cli_commands.md')
-rw-r--r-- | docs/cli_commands.md | 73 |
1 files changed, 39 insertions, 34 deletions
diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 4cd5ae98c3..c6a7ffe191 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -17,7 +17,7 @@ qmk compile [-c] <configuratorExport.json> **Usage for Keymaps**: ``` -qmk compile [-c] [-e <var>=<value>] [-j <num_jobs>] -kb <keyboard_name> -km <keymap_name> +qmk compile [-c] [-e <var>=<value>] [-j <num_jobs>] [--compiledb] -kb <keyboard_name> -km <keymap_name> ``` **Usage in Keyboard Directory**: @@ -84,6 +84,25 @@ The `num_jobs` argument determines the maximum number of jobs that can be used. qmk compile -j 0 -kb <keyboard_name> ``` +**Compilation Database**: + +Creates a `compile_commands.json` file. + +Does your IDE/editor use a language server but doesn't _quite_ find all the necessary include files? Do you hate red squigglies? Do you wish your editor could figure out `#include QMK_KEYBOARD_H`? You might need a [compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html)! Compiling using this argument can create this for you. + +**Example:** + +``` +$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak +$ qmk compile --compiledb +Ψ Making clean +Ψ Gathering build instructions from make ........ +Ψ Found 63 compile commands +Ψ Writing build database to /Users/you/src/qmk_firmware/compile_commands.json +Ψ Compiling keymap with make ........ +... build log continues ... +``` + ## `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 the [Flashing Firmware](flashing) guide for more details of the available bootloaders. @@ -694,52 +713,28 @@ qmk format-c qmk format-c -b branch_name ``` -## `qmk generate-compilation-database` - -**Usage**: - -``` -qmk generate-compilation-database [-kb KEYBOARD] [-km KEYMAP] -``` - -Creates a `compile_commands.json` file. - -Does your IDE/editor use a language server but doesn't _quite_ find all the necessary include files? Do you hate red squigglies? Do you wish your editor could figure out `#include QMK_KEYBOARD_H`? You might need a [compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html)! The qmk tool can build this for you. - -This command needs to know which keyboard and keymap to build. It uses the same configuration options as the `qmk compile` command: arguments, current directory, and config files. - -**Example:** - -``` -$ 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 -``` - -Now open your dev environment and live a squiggly-free life. - ## `qmk docs` -This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 5173. +This command starts a local HTTP server which you can use for browsing or improving the docs, and provides live reload capability whilst editing. Default port is 8936. +Use the `-b`/`--browser` flag to automatically open the local webserver in your default browser. -This command requires `node` and `yarn` to be installed as prerequisites, and provides live reload capability whilst editing. +Requires `node` and `yarn` to be installed as prerequisites. **Usage**: ``` -usage: qmk docs [-h] +usage: qmk docs [-h] [-b] [-p PORT] options: - -h, --help show this help message and exit + -h, --help show this help message and exit + -b, --browser Open the docs in the default browser. + -p, --port PORT Port number to use. ``` ## `qmk generate-docs` -This command allows you to generate QMK documentation locally. It can be uses for general browsing or improving the docs. -Use the `-s`/`--serve` flag to also serve the static site once built. Default port is 4173. +This command generates QMK documentation for production. +Use the `-s`/`--serve` flag to also serve the static site on port 4173 once built. Note that this does not provide live reloading; use `qmk docs` instead for development purposes. This command requires `node` and `yarn` to be installed as prerequisites, and requires the operating system to support symlinks. @@ -882,3 +877,13 @@ Run single test: ``` qmk test-c --test basic ``` + +## `qmk generate-compilation-database` + +**Usage**: + +``` +qmk generate-compilation-database [-kb KEYBOARD] [-km KEYMAP] +``` + +This command has been deprecated as it cannot take into account configurables such as [converters](/feature_converters) or environment variables normally specified on the command line; please use the `--compiledb` flag with `qmk compile` instead. |