Add user-guide documentation for 'build-info'

Author: fendor

doc/cabal-project.rst

@@ -1432,6 +1432,26 @@ Advanced global configuration options
     the ``-package-env -`` option that allows ignoring the package
     environment files).
 
+.. cfg-field:: build-info: True, False
+               --enable-build-info
+               --disable-build-info
+    :synopsis: Whether build information for each individual component should be
+               written in a machine readable format.
+
+    :default: ``False``
+
+    Enable generation of build information for Cabal components. Contains very detailed information
+    on how to build an individual component, such as compiler version, modules of a component and
+    how to compile the component.
+
+    The output format is in json, and the exact location can be discovered from ``plan.json``.
+    Note, that this field in ``plan.json`` can be ``null``, if and only if ``build-type: Custom`` is
+    set, and the ``Cabal`` version is too old (i.e. ``< 3.7``).
+
+    .. note::
+        The format and fields of the generated build information is currently experimental,
+        in the future we might add or remove fields, depending on the needs of other tooling.
+
 
 .. cfg-field:: http-transport: curl, wget, powershell, or plain-http
                --http-transport=transport

doc/json-schemas/build-info.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "type": "object",
+  "properties": {
+    "cabal-version": {
+      "type": "string"
+    },
+    "compiler": {
+      "type": "object",
+      "properties": {
+        "flavour": {
+          "type": "string"
+        },
+        "compiler-id": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string"
+        }
+      },
+      "required": ["flavour", "compiler-id", "path"]
+    },
+    "components": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "unit-id": {
+            "type": "string"
+          },
+          "compiler-args": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "modules": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "src-files": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "hs-src-dirs": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "src-dir": {
+            "type": "string"
+          },
+          "cabal-file": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "type",
+          "name",
+          "unit-id",
+          "compiler-args",
+          "modules",
+          "src-files",
+          "hs-src-dirs",
+          "src-dir",
+          "cabal-file"
+        ]
+      }
+    }
+  },
+  "required": ["cabal-version", "compiler", "components"]
+}

doc/requirements.txt

@@ -1,2 +1,3 @@
 sphinx == 3.1.*
 sphinx_rtd_theme
+sphinx-jsonschema == 1.16.*

doc/setup-commands.rst

@@ -32,7 +32,7 @@ performs the actual building, while the last both copies the build
 results to some permanent place and registers the package with GHC.
 
 .. note ::
-    
+
     Global installing of packages is not recommended.
     The :ref:`nix-style-builds` is the preferred way of building and installing
     packages.
@@ -1034,6 +1034,61 @@ Miscellaneous options
     Specify a soft constraint on versions of a package. The solver will
     attempt to satisfy these preferences on a "best-effort" basis.
 
+.. option:: --enable-build-info
+
+    Generate accurate build information for build components.
+
+    Information contains meta information, such as component type, compiler type, and
+    Cabal library version used during the build, but also fine grained information,
+    such as dependencies, what modules are part of the component, etc...
+
+    On build, a file ``build-info.json`` (in the ``json`` format) will be written to
+    the root of the build directory.
+
+    .. note::
+        The format and fields of the generated build information is currently
+        experimental. In the future we might add or remove fields, depending
+        on the needs of other tooling.
+
+    :: example
+        {
+            "cabal-version": "<cabal version>",
+            "compiler": {
+                "flavour": "<compiler name>",
+                "compiler-id": "<compiler id>",
+                "path": "<absolute path of the compiler>"
+            },
+            "components": [
+                {
+                "type": "<component type, e.g. lib | bench | exe | flib | test>",
+                "name": "<component name>",
+                "unit-id": "<unitid>",
+                "compiler-args": [
+                    "<compiler args necessary for compilation>"
+                ],
+                "modules": [
+                    "<modules in this component>"
+                ],
+                "src-files": [
+                    "<source files relative to hs-src-dirs>"
+                ],
+                "hs-src-dirs": [
+                    "<source directories of this component>"
+                ],
+                "src-dir": "<root directory of this component>",
+                "cabal-file": "<cabal file location>"
+                }
+            ]
+        }
+
+    .. jsonschema:: ./json-schemas/build-info.schema.json
+
+.. option:: --disable-build-info
+
+    (default) Do not generate detailed build information for built components.
+
+    Already generated `build-info.json` files will be removed since they would be stale otherwise.
+
 .. option:: --disable-response-files
 
     Enable workaround for older versions of programs such as ``ar`` or
@@ -1132,7 +1187,7 @@ This command takes the following options:
 .. option:: --hscolour-css=path
 
     The argument *path* denotes a CSS file, which is passed to HsColour_ as in
-    
+
     ::
 
         $ runhaskell Setup.hs hscolour --css=*path*
@@ -1358,7 +1413,7 @@ the package.
     results in real time).
 
 .. option:: --test-options=options
-    
+
     Give extra options to the test executables.
 
 .. option:: --test-option=option