New CLI subcommand to create clang-compatible compilation database (`compile_commands.json`) (#14370)

* pulled source from dev branch

* missed a file from origin

* formatting

* revised argument names. relaxed matching rules to work for avr too

* add docstrings

* added docs. tightened up regex

* remove unused imports

* cleaning up command file. use existing qmk dir constant

* rename parser library file

* move lib functions into command file. there are only 2 and they aren't large

* currently debugging...

* more robustly find config

* updated docs

* remove unused imports

* reuse make executable from the main make command

* pulled source from dev branch

* missed a file from origin

* formatting

* revised argument names. relaxed matching rules to work for avr too

* add docstrings

* added docs. tightened up regex

* remove unused imports

* cleaning up command file. use existing qmk dir constant

* rename parser library file

* move lib functions into command file. there are only 2 and they aren't large

* currently debugging...

* more robustly find config

* updated docs

* remove unused imports

* reuse make executable from the main make command

* remove MAKEFLAGS from environment for better control over process management

* Update .gitignore

Co-authored-by: Michael Forster <forster@google.com>

* add a usage line to docs

* doc change as suggested

Co-authored-by: Nick Brassel <nick@tzarc.org>

* rename command

* remove debug print statements

* generate-compilation-database: fix arg handling

* generate-comilation-db: improve error handling

* use cli.run() instead of Popen()

Co-authored-by: Xton <cdewan@apple.com>
Co-authored-by: Christon DeWan <cmdpix@mac.com>
Co-authored-by: Michael Forster <forster@google.com>
Co-authored-by: Nick Brassel <nick@tzarc.org>

1 files changed, 27 insertions, 0 deletions

diff --git a/docs/cli_commands.md b/docs/cli_commands.md
index 06568afb4..1427b592f 100644
--- a/docs/cli_commands.md
+++ b/docs/cli_commands.md
@@ -320,6 +320,33 @@ 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 8936.