<div dir="ltr">Hi,<br><br># TLDR #<br><br>FileCheck just became less noisy on failures by default.  However, for<br>some cases, it now provides too little debug info, so new<br>configuration options have landed.  When debugging CI failures, many<br>LLVM committers have no feasible way to adjust these options, so I<br>think LLVM CI configs should include the following environment setting<br>to maximize the debug info:<br><br>```<br>FILECHECK_OPTS='-dump-input-filter=all -vv -color'<br>```<br><br># Background: FileCheck Input Dumps by Default #<br><br>D81422 recently landed to enable `-dump-input=fail` by default in<br>FileCheck.  As a result, when FileCheck fails, it by default produces<br>an annotated input dump like the following (which is intended to be<br>viewed in a monospaced font):<br><br>```<br><span style="font-family:monospace"><<<<<<<br>           1: foo<br>           2: foo<br>           3: foo<br>           4: foo<br>           5: foo<br>           6: foo<br>           7: foo<br>           8: foo<br>           9: foo<br>          10: foo<br>          11: foo<br>          12: foo<br>          13: foo<br>          14: foo<br>          15: hello world<br>          16: foo<br>check:2'0     X~~ error: no match found<br>          17: foo<br>check:2'0     ~~~<br>          18: foo<br>check:2'0     ~~~<br>          19: foo<br>check:2'0     ~~~<br>          20: foo<br>check:2'0     ~~~<br>          21: foo<br>check:2'0     ~~~<br>          22: foo<br>check:2'0     ~~~<br>          23: foo<br>check:2'0     ~~~<br>          24: foo<br>check:2'0     ~~~<br>          25: foo<br>check:2'0     ~~~<br>          26: foo<br>check:2'0     ~~~<br>          27: foo<br>check:2'0     ~~~<br>          28: foo<br>check:2'0     ~~~<br>          29: foo<br>check:2'0     ~~~<br>          30: goodbye word<br>check:2'0     ~~~~~~~~~~~~<br>check:2'1     ?            possible intended match<br>          31: foo<br>check:2'0     ~~~<br>          32: foo<br>check:2'0     ~~~<br>          33: foo<br>check:2'0     ~~~<br>          34: foo<br>check:2'0     ~~~<br>          35: foo<br>check:2'0     ~~~<br>          36: foo<br>check:2'0     ~~~<br>          37: foo<br>check:2'0     ~~~<br>          38: foo<br>check:2'0     ~~~<br>          39: foo<br>check:2'0     ~~~<br>          40: foo<br>check:2'0     ~~~<br>>>>>>></span><br>```<br><br>LLVM developers' views on this change vary.  See the following<br>discussions:<br><br>* <<a href="https://reviews.llvm.org/D81422">https://reviews.llvm.org/D81422</a>><br>* Thread starting at: <<a href="http://lists.llvm.org/pipermail/llvm-dev/2020-June/142369.html">http://lists.llvm.org/pipermail/llvm-dev/2020-June/142369.html</a>><br><br>## The Good ##<br><br>Some people feel this change is a significant improvement for<br>debugging FileCheck errors.  It's especially helpful for those who<br>aren't aware of the `-dump-input=fail` option or the `FILECHECK_OPTS`<br>environment variable, which can be used to set such debugging options.<br>This change is perhaps even more helpful in the case of CI<br>configurations that don't set `-dump-input=fail`.  In that case, upon<br>a test failure, it is not feasible for many LLVM committers to set<br>`-dump-input=fail` and run a failing test again on precisely the same<br>platform in order to get the debugging info they need.  Now they don't<br>have to.<br><br>## The Bad ##<br><br>Others feel this dump produces far too much noise to be useful,<br>especially when the FileCheck input is large and the test suite is<br>being run in a terminal window.  Sometimes the actual error message is<br>buried thousands of lines earlier in a terminal's scrollback or may<br>have even overflowed the scrollback buffer.<br><br># Fix 1: Filtered Input Dumps #<br><br>In an attempt to satisfy both views, D82203 just landed to filter the<br>input dump to just error diagnostics plus some context.  Thus, the<br>previous example now looks like the following by default:<br><br>```<br><span style="font-family:monospace"><<<<<<<br>           .<br>           .<br>           .<br>          11: foo<br>          12: foo<br>          13: foo<br>          14: foo<br>          15: hello world<br>          16: foo<br>check:2'0     X~~ error: no match found<br>          17: foo<br>check:2'0     ~~~<br>          18: foo<br>check:2'0     ~~~<br>          19: foo<br>check:2'0     ~~~<br>          20: foo<br>check:2'0     ~~~<br>          21: foo<br>check:2'0     ~~~<br>           .<br>           .<br>           .<br>          25: foo<br>check:2'0     ~~~<br>          26: foo<br>check:2'0     ~~~<br>          27: foo<br>check:2'0     ~~~<br>          28: foo<br>check:2'0     ~~~<br>          29: foo<br>check:2'0     ~~~<br>          30: goodbye word<br>check:2'0     ~~~~~~~~~~~~<br>check:2'1     ?            possible intended match<br>          31: foo<br>check:2'0     ~~~<br>          32: foo<br>check:2'0     ~~~<br>          33: foo<br>check:2'0     ~~~<br>          34: foo<br>check:2'0     ~~~<br>          35: foo<br>check:2'0     ~~~<br>           .<br>           .<br>           .<br>>>>>>></span><br>```<br><br>## The Good ##<br><br>Unless there are many FileCheck errors (e.g., one FileCheck run can<br>report an error per `CHECK-LABEL`), the input dump is now relatively<br>small.  Thus, this change supports the original motivation to enable<br>`-dump-input=fail` by default but avoids being overwhelming when the<br>full input is large.<br><br>## The Bad ##<br><br>I find that it is *often* true that the default amount of context, as<br>shown in the example above, is far from sufficient.  For example,<br>often there is no `possible intended match` or it's a bad guess, and<br>the intended match is hundreds of lines away from any error<br>diagnostic.  Even worse, the actual bug is often at a different<br>directive than the directive for which FileCheck reports an error.  In<br>other words, the information I need is often filtered out, so I need<br>to be able to configure the input dump filter.<br><br># Fix 2: Filter Configuration #<br><br>D83097 and D82203 have landed to implement `-dump-input-filter` and<br>`-dump-input-context` for configuring the filtered input lines (that<br>is, include more than just errors) and their lines of context.  See<br>`FileCheck -help` for details.<br><br>## Where to Specify Them ##<br><br>Like other FileCheck debugging options, these can be set via<br>`FILECHECK_OPTS` either globally (e.g., in a `~/.profile`) or per test<br>suite run (e.g., `FILECHECK_OPTS=-dump-input-context=100 ninja<br>check`).  They can even be set as command-line options in specific<br>FileCheck calls within specific tests in case those calls have very<br>specific debugging needs.  In that case, they won't conflict with<br>options in `FILECHECK_OPTS` because multiple occurrences of an option<br>are resolved in favor of the option requesting the most debugging<br>info.<br><br>## Is This Too Configurable? ##<br><br>It has been suggested that the configuration space provided by<br>`-dump-input-filter` and `-dump-input-context` is too large.  We could<br>have instead reduced it to a simple boolean: filter as shown above by<br>default, or show the full input if requested.  However, I anticipate<br>that the default amount of context, no matter what it is, will be too<br>frequently wrong for some LLVM developers' use cases.  On the other<br>hand, a full input dump can be overwhelming even when enabled for a<br>single test.  I think the ability to select levels in between these<br>two extremes is important.  Finally, in my opinion, this extra<br>configurability adds minimal complexity to the FileCheck<br>implementation.  Most of the implementation needed is already needed<br>to support just the default configuration.<br><br># Fix 3: Filter Configuration in CI #<br><br>As I mentioned above, upon a test failure in CI, it is not feasible<br>for many LLVM committers to set `FILECHECK_OPTS` and run the failing<br>test again on precisely the same platform in order to configure the<br>precise information they need for debugging.  In my experience, the<br>inability to request sufficient debugging information is a much more<br>severe problem than encountering too much debugging information.  For<br>these reasons, I think LLVM CI configs should maximize the debugging<br>info upon FileCheck failures by setting:<br><br>```<br>FILECHECK_OPTS='-dump-input-filter=all -vv -color'<br>```<br><br><div>I use this successfully in my local Gitlab CI configs.  Hopefully</div><div> others will adopt it too.<br></div><br><div>Thanks.</div><div><br></div><div>Joel<br></div></div>