Add -fdefer-diagnostics to defer and group diagnostic messages in make-mode

When loading many modules in parallel there can a lot of warnings and
errors get mixed up with regular output. When the compilation fails,
the relevant error message can be thousands of lines backward and is
hard to find. When the compilation successes, warning message is likely
to be ignored as it is not seen. We can address this by deferring the
warning and error message after the compilation. We also put errors
after warnings so it is more visible.

This idea was originally proposed by Bartosz Nitka in
https://phabricator.haskell.org/D4219.

1 files changed, 12 insertions, 0 deletions

diff --git a/docs/users_guide/using.rst b/docs/users_guide/using.rst
index 83eeb51eed..d11dedfb9a 100644
--- a/docs/users_guide/using.rst
+++ b/docs/users_guide/using.rst
@@ -931,6 +931,18 @@ messages and in GHCi:
                   in a’
         or by using the flag -fno-warn-unused-do-bind
 
+.. ghc-flag:: -fdefer-diagnostics
+    :shortdesc: Defer and group diagnostic messages by severity
+    :type: dynamic
+    :category: verbosity
+
+    Causes GHC to group diagnostic messages by severity and output them after
+    other messages when building a multi-module Haskell program. This flag can
+    make diagnostic messages more visible when used in conjunction with
+    :ghc-flag:`--make` and :ghc-flag:`-j[⟨n⟩]`. Otherwise, it can be hard to
+    find the relevant errors or likely to ignore the warnings when they are
+    mixed with many other messages.
+
 .. ghc-flag:: -fdiagnostics-color=⟨always|auto|never⟩
     :shortdesc: Use colors in error messages
     :type: dynamic