From c10679b9b0ac3cef083efdf2913fb4825ebffb52 Mon Sep 17 00:00:00 2001
From: Rene Rivera <grafikrobot@gmail.com>
Date: Sat, 1 Jun 2024 08:15:56 -0500
Subject: [PATCH] Add documentation.

---
 doc/src/history.adoc  |  3 +++
 doc/src/overview.adoc |  8 ++++++--
 doc/src/tasks.adoc    | 47 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/doc/src/history.adoc b/doc/src/history.adoc
index 2bab3937a8..39bd3d618f 100644
--- a/doc/src/history.adoc
+++ b/doc/src/history.adoc
@@ -3,6 +3,9 @@
 
 == Version 5.2.0
 
+* *New*: Add support for generating `compile_commands.json` command database
+  for some IDE integration.
+  -- _René Ferdinand Rivera Morell_
 * *New*: Addition of a module (`db`) for structured data management. Has a
   `property-db` class that can write out as JSON data.
   -- _René Ferdinand Rivera Morell_
diff --git a/doc/src/overview.adoc b/doc/src/overview.adoc
index 48e4ceafcc..cee21409c4 100644
--- a/doc/src/overview.adoc
+++ b/doc/src/overview.adoc
@@ -626,8 +626,7 @@ B2 recognizes the following command line options.
 `-d0`::
   Suppress all informational messages.
 `-d N`::
-  Enable cumulative debugging levels from 1 to n. Values are:
-  +
+  Enable cumulative debugging levels from 1 to n. Values are: +
   1.  Show the actions taken for building targets, as they are executed
   (the default).
   2.  Show "quiet" actions and display all action text, as they are
@@ -653,6 +652,11 @@ B2 recognizes the following command line options.
 `-s var=value`::
   Set the variable `var` to `value` in the global scope of the jam language
   interpreter, overriding variables imported from the environment.
+`--command-database=_format_`::
+  Output a compile commands database as _format_. Currently _format_ can be:
+  `json`. (See xref:tasks#b2.tasks.commanddb[Command Database] for details.)
+`--command-database-out=_file_`::
+  Specify the _file_ path to output the commands database to.
 
 [[bbv2.overview.invocation.properties]]
 === Properties
diff --git a/doc/src/tasks.adoc b/doc/src/tasks.adoc
index d56bcc4727..51cfce786f 100644
--- a/doc/src/tasks.adoc
+++ b/doc/src/tasks.adoc
@@ -821,3 +821,50 @@ When loading a `*.jam` file as the _path_ it is equivalent to calling:
 In this case it means that the file will be loaded as part of the referenced
 project and hence any bare targets or information it declares will be part of
 the project.
+
+[[b2.tasks.commanddb]]
+== Command Database, and IDE Integration
+
+Many IDE programs accept the use of a
+https://clang.llvm.org/docs/JSONCompilationDatabase.html[`compile_commands.json`]
+file to learn what and how your project builds. B2 supports generating such
+files for any build you make. B2 supports this through a generic facility to
+extract commands from the actions it executes. There are two options that
+control this. The `--command-database=_format_` option indicates to generate the
+file for the given _format_. It has a couple of effects when specified:
+
+* It tells B2 to start observing and extracting commands from actions (as
+  specified by the toolset).
+* It disables execution of actions. I.e. equivalent to adding the `-n` option.
+* It enables building all default and specified targets. I.e. the equivalent to
+  adding the `-a` option.
+* It disables all action execution output. I.e. as if specifying `-d0` option.
+* At the end of the main build it writes out the results of what it observed
+  to the database file.
+
+Currently on `json` is supported as a format that follows the
+https://clang.llvm.org/docs/JSONCompilationDatabase.html[Clang JSON Compilation
+Database Format Specification].
+
+The `--command-database-out=_file_` option controls the name, and optionally
+location, of the generated file. By default the _file_ is
+`compile_commands.json` to follow the ecosystem convention. And it is generated,
+by default, in one of the following locations:
+
+* Relative to the `build-dir` of the root project, if it's specified by the
+  project. With the default _file_ name or as given.
+* At the absolute _file_ path if it is rooted.
+* At the _current working directory_.
+
+The following fields are populated in the generated database:
+
+* `directory` - This will always be the current directory as B2 makes all paths
+  relative to that (or absolute).
+* `file` - The first source of each action recorded.
+* `command` - The quoted, full, command as extracted by the toolset.
+* `output` - The first target file of each action recorded. As B2 can build
+  multiple variants at once this is required to differentiate between multiple
+  compilations of the same source file.
+
+NOTE: Only one command database file is generated per `b2` invocation. And each
+time it is generated it overwrites any previous such file.