diff --git a/changelog.d/pr-10644 b/changelog.d/pr-10644 new file mode 100644 index 00000000000..dd92023f3ab --- /dev/null +++ b/changelog.d/pr-10644 @@ -0,0 +1,165 @@ +--- +synopsis: Show source of project parse error or warning +packages: [cabal-install] +prs: 10644 +issues: 10635 +--- + +Improves warning and error messages shown when parsing project files and their +imports. + +## Warning Messages + +To trigger these warning messages, the examples use badly formed comments that +have a single dash instead of two as is required of a line comment in `.cabal` +and `.project` files (and imported `.config` files). + + +* Before the fix: + + The `cabal.project` file name is repeated. Warnings are misattributed to + having been in the project rather than from a configuration file imported by + the project. Warnings are shown in reverse line number order. + + ``` + $ ~/.ghcup/bin/cabal-3.12.1.0 build all --dry-run + ... + Warning: + /.../ParseWarningProvenance/cabal.project, + cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized + section '-' on line 123 + /.../ParseWarningProvenance/cabal.project, + cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized + section '-' on line 3 + /.../ParseWarningProvenance/cabal.project, + cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized + section '-' on line 2 + /.../ParseWarningProvenance/cabal.project, + cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized + section '-' on line 1 + /.../ParseWarningProvenance/cabal.project, + cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized + section '-' on line 123 + /.../ParseWarningProvenance/cabal.project, + cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized + section '-' on line 3 + /.../ParseWarningProvenance/cabal.project, + cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized + section '-' on line 2 + /.../ParseWarningProvenance/cabal.project, + cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized + section '-' on line 1 + ``` + +* After the fix: + + The warnings are shown in a list. For warnings within the same `.project` or + imported `.config` file, warnings are sorted by line number. The file that + is the source of the warning is shown. + + The warnings in import configuration files are shown in the order they were + imported by the project: + + ``` + $ cat cabal.project + packages: no-pkg-dir + import: dir-x/a.config + import: dir-y/a.config + import: x.config + import: y.config + ``` + + ``` + $ cabal build all --dry-run + ... + Warnings found while parsing the project file, cabal.project: + - dir-x/a.config: Unrecognized section '-' on line 1 + - dir-x/a.config: Unrecognized section '-' on line 2 + - dir-x/a.config: Unrecognized section '-' on line 3 + - dir-y/a.config: Unrecognized section '-' on line 123 + - x.config: Unrecognized section '-' on line 1 + - x.config: Unrecognized section '-' on line 2 + - x.config: Unrecognized section '-' on line 3 + - y.config: Unrecognized section '-' on line 123 + ``` + +## Error Messages from Project + +To trigger these error messages, the examples use badly formed conditions: + +``` +$ cat cabal.project +-- The following failing condition is not on the first line so we can check the +-- line number: +if _ +``` + +* Before the fix: + + The parse error is shown with hard line breaks. + + ``` + $ ~/.ghcup/bin/cabal-3.12.1.0 build all --dry-run + ... + Error: [Cabal-7090] + Error parsing project file /.../ParseErrorProvenance/cabal.project:3: + "" (line 1, column 1): + unexpected SecArgName (Position 1 4) "_" + ``` + +* After the fix: + + The snippet that failed to parse may be shown and the parse error is shown + as one line, with no hard line breaks. + + ``` + $ cabal build all --dry-run + ... + Error: [Cabal-7090] + Error parsing project file cabal.project:3: + - Failed to parse 'if(_)' with error: + "" (line 1, column 1): unexpected SecArgName (Position 1 4) "_" + ``` + +## Error Messages from Imported Config + +With the same setup but now with the error in an imported file: + +``` +$ cat elif.project +import: dir-elif/elif.config + +$ cat dir-elif/elif.config +-- The following failing condition is not on the first line so we can check the +-- line number: +if false +elif _ +``` + +* Before the fix: + + The project rather than the imported configuration file is shown as the source file. + + ``` + $ ~/.ghcup/bin/cabal-3.12.1.0 build all --dry-run + ... + Error: [Cabal-7090] + Error parsing project file /.../ParseErrorProvenance/elif.project:4: + "" (line 1, column 1): + unexpected SecArgName (Position 1 6) "_" + ``` + +* After the fix: + + The imported configuration file is shown as the source with a snippet of the error. + + ``` + $ cabal build all --dry-run + ... + Error: [Cabal-7090] + Error parsing project file dir-elif/elif.config:4: + - dir-elif/elif.config + imported by: elif.project + - Failed to parse 'elif(_)' with error: + "" (line 1, column 1): unexpected SecArgName (Position 1 6) "_" + ```