diff --git a/Cabal/src/Distribution/Simple/ShowBuildInfo.hs b/Cabal/src/Distribution/Simple/ShowBuildInfo.hs
index 9bfda3eadd525a22132de7a2d61ebe1217fe7dbc..44bb55916f3994ff75dfc578e56eff5b89762639 100644
--- a/Cabal/src/Distribution/Simple/ShowBuildInfo.hs
+++ b/Cabal/src/Distribution/Simple/ShowBuildInfo.hs
@@ -104,6 +104,10 @@ mkBuildInfo wdir pkg_descr lbi _flags targetsToBuild = (warnings, JsonObject bui
-- | A variant of 'mkBuildInfo' if you need to call 'mkCompilerInfo' and
-- 'mkComponentInfo' yourself.
+--
+-- If you change the format or any name in the output json, don't forget to update
+-- the schema at @\/doc\/json-schemas\/build-info.schema.json@ and the docs of
+-- @--enable-build-info@\/@--disable-build-info@.
mkBuildInfo'
:: Json -- ^ The 'Json' from 'mkCompilerInfo'
-> [Json] -- ^ The 'Json' from 'mkComponentInfo'
diff --git a/doc/cabal-project.rst b/doc/cabal-project.rst
index e66825957a0764de68b0958185e34bd4df74e040..6ac3b6b8e16ab41f48fd796aa641c39dc83e785b 100644
--- a/doc/cabal-project.rst
+++ b/doc/cabal-project.rst
@@ -1432,6 +1432,32 @@ 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``, where it is identified by ``build-info`` within the items in
+ the ``install-plan``.
+ 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``).
+ If the field is missing entirely, the component is not a local one, thus,
+ no ``build-info`` exists for that particular component within the
+ ``install-plan``.
+
+ .. 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
diff --git a/doc/json-schemas/build-info.schema.json b/doc/json-schemas/build-info.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..ae3be7e5310480ab03c320a7ae1f168ae3fc0a0f
--- /dev/null
+++ b/doc/json-schemas/build-info.schema.json
@@ -0,0 +1,84 @@
+{
+ "$schema": "https://json-schema.org/draft/2019-09/schema",
+ "$comment": "When you change this, make sure to update the code in 'ShowBuildInfo.hs'",
+ "type": "object",
+ "properties": {
+ "cabal-lib-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-lib-version", "compiler", "components"]
+}
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 38333cb225d124f427e1ae50cf3ec818042b6a35..3ec19d5512a00e70a3132b6425eec105df64e74f 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,2 +1,3 @@
sphinx == 3.1.*
sphinx_rtd_theme
+sphinx-jsonschema == 1.16.*
diff --git a/doc/setup-commands.rst b/doc/setup-commands.rst
index d2162aa6b95113804da452622fa0473acc669e65..12c4f32f89b96fdd6568c3403f50fb0c7a6d3f44 100644
--- a/doc/setup-commands.rst
+++ b/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-lib-version": "<cabal lib 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