From ba88f8ad8e1e1b051519629a1eb65a122bb71ac0 Mon Sep 17 00:00:00 2001
From: Federico Perini <federico.perini@gmail.com>
Date: Sun, 13 Apr 2025 14:46:17 +0200
Subject: [PATCH 1/2] document `compile_commands.json`

---
 pages/spec/compile_commands.md | 67 ++++++++++++++++++++++++++++++++++
 pages/spec/index.md            |  3 ++
 2 files changed, 70 insertions(+)
 create mode 100644 pages/spec/compile_commands.md

diff --git a/pages/spec/compile_commands.md b/pages/spec/compile_commands.md
new file mode 100644
index 000000000..8bf22a791
--- /dev/null
+++ b/pages/spec/compile_commands.md
@@ -0,0 +1,67 @@
+# `compile_commands.json`
+
+`fpm` automatically generates a `compile_commands.json` file during each successful build. This file is placed in the `build/` directory and provides detailed information about how each source file in the project is compiled.
+
+```txt
+build/compile_commands.json
+```
+
+This file follows the [Clang Compilation Database format](https://clang.llvm.org/docs/JSONCompilationDatabase.html) as is widely used by code editors, IDEs, and developer tools for enhanced navigation, static analysis, and diagnostics.
+
+## Purpose
+
+The `compile_commands.json` file serves as a bridge between `fpm` and tooling such as:
+
+- Language Server Protocol (LSP) servers (e.g. `fortls`)
+- Code editors (e.g. Visual Studio Code)
+- Static analyzers
+- Code linters and formatters
+
+These tools use `compile_commands.json` to understand compilation flags, include directories, and output paths.
+
+## How it Works
+
+- Automatically created during `fpm build`
+- Located at `build/compile_commands.json`
+- No need to configure or enable it explicitly
+- Regenerated each time a build completes successfully
+
+## Example
+
+A minimal `compile_commands.json` entry may look like:
+
+```json
+[
+  {
+    "directory": "/path/to/my/fpm/package",
+    "arguments": [
+      "gfortran",
+      "-c",
+      "src/module.f90",
+      "-Iinclude",
+      "-Jbuild",
+      "-o",
+      "build/module.o"
+    ],
+    "file": "src/module.f90"
+  }
+]
+```
+
+## Integration with Tools
+
+### Command Line Tools
+
+`compile_commands.json` is a valid JSON file and can be inspected with any JSON tools. 
+A simple way to pretty print and inspect the file from a terminal is:
+
+```bash
+cat build/compile_commands.json | jq .
+```
+
+## Limitations
+
+- Only generated after a successful build
+- Currently not configurable in `fpm.toml`
+- Overwrites previous version on each new build
+
diff --git a/pages/spec/index.md b/pages/spec/index.md
index 90e81ceb4..50e9034af 100644
--- a/pages/spec/index.md
+++ b/pages/spec/index.md
@@ -13,5 +13,8 @@ The generated API documentation of the fpm internals can be found [here](https:/
 :::{toctree}
 manifest
 metapackages
+compile_commands
 API documentation <https://fortran-lang.github.io/fpm>
 :::
+
+

From 5d9b10e1a5c88092ed9a5e9ddd5d85408198f127 Mon Sep 17 00:00:00 2001
From: Federico Perini <federico.perini@gmail.com>
Date: Sun, 13 Apr 2025 14:47:12 +0200
Subject: [PATCH 2/2] fpm version notice

---
 pages/spec/compile_commands.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/pages/spec/compile_commands.md b/pages/spec/compile_commands.md
index 8bf22a791..8e97d72c8 100644
--- a/pages/spec/compile_commands.md
+++ b/pages/spec/compile_commands.md
@@ -64,4 +64,5 @@ cat build/compile_commands.json | jq .
 - Only generated after a successful build
 - Currently not configurable in `fpm.toml`
 - Overwrites previous version on each new build
+- This feature is supported since `fpm 0.12.0`