Skip to content

Commit 8a7e96d

Browse files
fendorfendor
committed
Add user-guide documentation for 'build-info'
1 parent 705228e commit 8a7e96d

File tree

5 files changed

+173
-3
lines changed

5 files changed

+173
-3
lines changed

‎Cabal/src/Distribution/Simple/ShowBuildInfo.hs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,10 @@ mkBuildInfo wdir pkg_descr lbi _flags targetsToBuild = (warnings, JsonObject bui
104104

105105
-- | A variant of 'mkBuildInfo' if you need to call 'mkCompilerInfo' and
106106
-- 'mkComponentInfo' yourself.
107+
--
108+
-- If you change the format or any name in the output json, don't forget to update
109+
-- the schema at @\/doc\/json-schemas\/build-info.schema.json@ and the docs of
110+
-- @--enable-build-info@\/@--disable-build-info@.
107111
mkBuildInfo'
108112
:: Json -- ^ The 'Json' from 'mkCompilerInfo'
109113
-> [Json] -- ^ The 'Json' from 'mkComponentInfo'

‎doc/cabal-project.rst‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1432,6 +1432,32 @@ Advanced global configuration options
14321432
the ``-package-env -`` option that allows ignoring the package
14331433
environment files).
14341434

1435+
.. cfg-field:: build-info: True, False
1436+
--enable-build-info
1437+
--disable-build-info
1438+
:synopsis: Whether build information for each individual component should be
1439+
written in a machine readable format.
1440+
1441+
:default: ``False``
1442+
1443+
Enable generation of build information for Cabal components. Contains very
1444+
detailed information on how to build an individual component, such as
1445+
compiler version, modules of a component and how to compile the component.
1446+
1447+
The output format is in json, and the exact location can be discovered from
1448+
``plan.json``, where it is identified by ``build-info`` within the items in
1449+
the ``install-plan``.
1450+
Note, that this field in ``plan.json`` can be ``null``, if and only if
1451+
``build-type: Custom`` is set, and the ``Cabal`` version is too
1452+
old (i.e. ``< 3.7``).
1453+
If the field is missing entirely, the component is not a local one, thus,
1454+
no ``build-info`` exists for that particular component within the
1455+
``install-plan``.
1456+
1457+
.. note::
1458+
The format and fields of the generated build information is currently experimental,
1459+
in the future we might add or remove fields, depending on the needs of other tooling.
1460+
14351461

14361462
.. cfg-field:: http-transport: curl, wget, powershell, or plain-http
14371463
--http-transport=transport

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

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2019-09/schema",
3+
"$comment": "When you change this, make sure to update the code in 'ShowBuildInfo.hs'",
4+
"type": "object",
5+
"properties": {
6+
"cabal-lib-version": {
7+
"type": "string"
8+
},
9+
"compiler": {
10+
"type": "object",
11+
"properties": {
12+
"flavour": {
13+
"type": "string"
14+
},
15+
"compiler-id": {
16+
"type": "string"
17+
},
18+
"path": {
19+
"type": "string"
20+
}
21+
},
22+
"required": ["flavour", "compiler-id", "path"]
23+
},
24+
"components": {
25+
"type": "array",
26+
"items": {
27+
"type": "object",
28+
"properties": {
29+
"type": {
30+
"type": "string"
31+
},
32+
"name": {
33+
"type": "string"
34+
},
35+
"unit-id": {
36+
"type": "string"
37+
},
38+
"compiler-args": {
39+
"type": "array",
40+
"items": {
41+
"type": "string"
42+
}
43+
},
44+
"modules": {
45+
"type": "array",
46+
"items": {
47+
"type": "string"
48+
}
49+
},
50+
"src-files": {
51+
"type": "array",
52+
"items": {
53+
"type": "string"
54+
}
55+
},
56+
"hs-src-dirs": {
57+
"type": "array",
58+
"items": {
59+
"type": "string"
60+
}
61+
},
62+
"src-dir": {
63+
"type": "string"
64+
},
65+
"cabal-file": {
66+
"type": "string"
67+
}
68+
},
69+
"required": [
70+
"type",
71+
"name",
72+
"unit-id",
73+
"compiler-args",
74+
"modules",
75+
"src-files",
76+
"hs-src-dirs",
77+
"src-dir",
78+
"cabal-file"
79+
]
80+
}
81+
}
82+
},
83+
"required": ["cabal-lib-version", "compiler", "components"]
84+
}

‎doc/requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
sphinx == 3.1.*
22
sphinx_rtd_theme
3+
sphinx-jsonschema == 1.16.*

‎doc/setup-commands.rst‎

Lines changed: 58 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ performs the actual building, while the last both copies the build
3232
results to some permanent place and registers the package with GHC.
3333

3434
.. note ::
35-
35+
3636
Global installing of packages is not recommended.
3737
The :ref:`nix-style-builds` is the preferred way of building and installing
3838
packages.
@@ -1034,6 +1034,61 @@ Miscellaneous options
10341034
Specify a soft constraint on versions of a package. The solver will
10351035
attempt to satisfy these preferences on a "best-effort" basis.
10361036

1037+
.. option:: --enable-build-info
1038+
1039+
Generate accurate build information for build components.
1040+
1041+
Information contains meta information, such as component type, compiler type, and
1042+
Cabal library version used during the build, but also fine grained information,
1043+
such as dependencies, what modules are part of the component, etc...
1044+
1045+
On build, a file ``build-info.json`` (in the ``json`` format) will be written to
1046+
the root of the build directory.
1047+
1048+
.. note::
1049+
The format and fields of the generated build information is currently
1050+
experimental. In the future we might add or remove fields, depending
1051+
on the needs of other tooling.
1052+
1053+
:: example
1054+
{
1055+
"cabal-lib-version": "<cabal version>",
1056+
"compiler": {
1057+
"flavour": "<compiler name>",
1058+
"compiler-id": "<compiler id>",
1059+
"path": "<absolute path of the compiler>"
1060+
},
1061+
"components": [
1062+
{
1063+
"type": "<component type, e.g. lib | bench | exe | flib | test>",
1064+
"name": "<component name>",
1065+
"unit-id": "<unitid>",
1066+
"compiler-args": [
1067+
"<compiler args necessary for compilation>"
1068+
],
1069+
"modules": [
1070+
"<modules in this component>"
1071+
],
1072+
"src-files": [
1073+
"<source files relative to hs-src-dirs>"
1074+
],
1075+
"hs-src-dirs": [
1076+
"<source directories of this component>"
1077+
],
1078+
"src-dir": "<root directory of this component>",
1079+
"cabal-file": "<cabal file location>"
1080+
}
1081+
]
1082+
}
1083+
1084+
.. jsonschema:: ./json-schemas/build-info.schema.json
1085+
1086+
.. option:: --disable-build-info
1087+
1088+
(default) Do not generate detailed build information for built components.
1089+
1090+
Already generated `build-info.json` files will be removed since they would be stale otherwise.
1091+
10371092
.. option:: --disable-response-files
10381093

10391094
Enable workaround for older versions of programs such as ``ar`` or
@@ -1132,7 +1187,7 @@ This command takes the following options:
11321187
.. option:: --hscolour-css=path
11331188

11341189
The argument *path* denotes a CSS file, which is passed to HsColour_ as in
1135-
1190+
11361191
::
11371192

11381193
$ runhaskell Setup.hs hscolour --css=*path*
@@ -1358,7 +1413,7 @@ the package.
13581413
results in real time).
13591414

13601415
.. option:: --test-options=options
1361-
1416+
13621417
Give extra options to the test executables.
13631418

13641419
.. option:: --test-option=option

0 commit comments

Comments
 (0)