changelog.d/pr-10644.md

   1 ---
   2 synopsis: Show source of project parse error or warning
   3 packages: [cabal-install]
   4 prs: 10644
   5 issues: 10635
   6 ---
   7
   8 Improves warning and error messages shown when parsing project files and their
   9 imports.
  10
  11 ## Warning Messages
  12
  13 To trigger these warning messages, the examples use badly formed comments that
  14 have a single dash instead of two as is required of a line comment in `.cabal`
  15 and `.project` files (and imported `.config` files).
  16
  17
  18 * Before the fix:
  19
  20     The `cabal.project` file name is repeated. Warnings are misattributed to
  21     having been in the project rather than from a configuration file imported by
  22     the project. Warnings are shown in reverse line number order.
  23
  24     ```
  25     $ ~/.ghcup/bin/cabal-3.12.1.0 build all --dry-run
  26     ...
  27     Warning:
  28     /.../ParseWarningProvenance/cabal.project,
  29     cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized
  30     section '-' on line 123
  31     /.../ParseWarningProvenance/cabal.project,
  32     cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized
  33     section '-' on line 3
  34     /.../ParseWarningProvenance/cabal.project,
  35     cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized
  36     section '-' on line 2
  37     /.../ParseWarningProvenance/cabal.project,
  38     cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized
  39     section '-' on line 1
  40     /.../ParseWarningProvenance/cabal.project,
  41     cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized
  42     section '-' on line 123
  43     /.../ParseWarningProvenance/cabal.project,
  44     cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized
  45     section '-' on line 3
  46     /.../ParseWarningProvenance/cabal.project,
  47     cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized
  48     section '-' on line 2
  49     /.../ParseWarningProvenance/cabal.project,
  50     cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized
  51     section '-' on line 1
  52     ```
  53
  54 * After the fix:
  55
  56     The warnings are shown in a list. For warnings within the same `.project` or
  57     imported `.config` file, warnings are sorted by line number. The file that
  58     is the source of the warning is shown.
  59
  60     The warnings associated with configuration files are shown in the order
  61     these files were imported by the project:
  62
  63     ```
  64     $ cat cabal.project
  65     packages: no-pkg-dir
  66     import: dir-x/a.config
  67     import: dir-y/a.config
  68     import: x.config
  69     import: y.config
  70     ```
  71
  72     ```
  73     $ cabal build all --dry-run
  74     ...
  75     Warnings found while parsing the project file, cabal.project:
  76     - dir-x/a.config: Unrecognized section '-' on line 1
  77     - dir-x/a.config: Unrecognized section '-' on line 2
  78     - dir-x/a.config: Unrecognized section '-' on line 3
  79     - dir-y/a.config: Unrecognized section '-' on line 123
  80     - x.config: Unrecognized section '-' on line 1
  81     - x.config: Unrecognized section '-' on line 2
  82     - x.config: Unrecognized section '-' on line 3
  83     - y.config: Unrecognized section '-' on line 123
  84     ```
  85
  86 ## Error Messages from Project
  87
  88 To trigger these error messages, the examples use badly formed conditions:
  89
  90 ```
  91 $ cat cabal.project
  92 -- The following failing condition is not on the first line so we can check the
  93 -- line number:
  94 if _
  95 ```
  96
  97 * Before the fix:
  98
  99     The parse error is shown with hard line breaks.
 100
 101     ```
 102     $ ~/.ghcup/bin/cabal-3.12.1.0 build all --dry-run
 103     ...
 104     Error: [Cabal-7090]
 105     Error parsing project file /.../ParseErrorProvenance/cabal.project:3:
 106     "<condition>" (line 1, column 1):
 107     unexpected SecArgName (Position 1 4) "_"
 108     ```
 109
 110 * After the fix:
 111
 112     The snippet that failed to parse may be shown and the parse error is shown
 113     as one line, with no hard line breaks.
 114
 115     ```
 116     $ cabal build all --dry-run
 117     ...
 118     Error: [Cabal-7090]
 119     Error parsing project file cabal.project:3:
 120     - Failed to parse 'if(_)' with error:
 121         "<condition>" (line 1, column 1): unexpected SecArgName (Position 1 4) "_"
 122     ```
 123
 124 ## Error Messages from Imported Config
 125
 126 With the same setup but now with the error in an imported file:
 127
 128 ```
 129 $ cat elif.project
 130 import: dir-elif/elif.config
 131
 132 $ cat dir-elif/elif.config
 133 -- The following failing condition is not on the first line so we can check the
 134 -- line number:
 135 if false
 136 elif _
 137 ```
 138
 139 * Before the fix:
 140
 141     The project rather than the imported configuration file is shown as the source file.
 142
 143     ```
 144     $ ~/.ghcup/bin/cabal-3.12.1.0 build all --dry-run
 145     ...
 146     Error: [Cabal-7090]
 147     Error parsing project file /.../ParseErrorProvenance/elif.project:4:
 148     "<condition>" (line 1, column 1):
 149     unexpected SecArgName (Position 1 6) "_"
 150     ```
 151
 152 * After the fix:
 153
 154     The imported configuration file is shown as the source with a snippet of the error.
 155
 156     ```
 157     $ cabal build all --dry-run
 158     ...
 159     Error: [Cabal-7090]
 160     Error parsing project file dir-elif/elif.config:4:
 161       - dir-elif/elif.config
 162           imported by: elif.project
 163       - Failed to parse 'elif(_)' with error:
 164         "<condition>" (line 1, column 1): unexpected SecArgName (Position 1 6) "_"
 165     ```