mirror of
https://github.com/RPCS3/llvm-mirror.git
synced 2024-11-26 04:32:44 +01:00
12285ee434
Extend FileCheck to dump its input annotated with FileCheck's
diagnostics: errors, good matches if -v, and additional information if
-vv. The goal is to make it easier to visualize FileCheck's matching
behavior when debugging.
Each patch in this series implements input annotations for a
particular category of FileCheck diagnostics. While the first few
patches alone are somewhat useful, the annotations become much more
useful as later patches implement annotations for -v and -vv
diagnostics, which show the matching behavior leading up to the error.
This first patch implements boilerplate plus input annotations for
error diagnostics reporting that no matches were found for a
directive. These annotations mark the search ranges of the failed
directives. Instead of using the usual `^~~`, which is used by later
patches for good matches, these annotations use `X~~` so that this
category of errors is visually distinct.
For example:
```
$ FileCheck -dump-input=help
The following description was requested by -dump-input=help to
explain the input annotations printed by -dump-input=always and
-dump-input=fail:
- L: labels line number L of the input file
- T:L labels the match result for a pattern of type T from line L of
the check file
- X~~ marks search range when no match is found
- colors error
If you are not seeing color above or in input dumps, try: -color
$ FileCheck -v -dump-input=always check1 < input1 |& sed -n '/^Input file/,$p'
Input file: <stdin>
Check file: check1
-dump-input=help describes the format of the following dump.
Full input was:
<<<<<<
1: ; abc def
2: ; ghI jkl
next:3 X~~~~~~~~ error: no match found
>>>>>>
$ cat check1
CHECK: abc
CHECK-SAME: def
CHECK-NEXT: ghi
CHECK-SAME: jkl
$ cat input1
; abc def
; ghI jkl
```
Some additional details related to the boilerplate:
* Enabling: The annotated input dump is enabled by `-dump-input`,
which can also be set via the `FILECHECK_OPTS` environment variable.
Accepted values are `help`, `always`, `fail`, or `never`. As shown
above, `help` describes the format of the dump. `always` is helpful
when you want to investigate a successful FileCheck run, perhaps for
an unexpected pass. `-dump-input-on-failure` and
`FILECHECK_DUMP_INPUT_ON_FAILURE` remain as a deprecated alias for
`-dump-input=fail`.
* Diagnostics: The usual diagnostics are not suppressed in this mode
and are printed first. For brevity in the example above, I've
omitted them using a sed command. Sometimes they're perfectly
sufficient, and then they make debugging quicker than if you were
forced to hunt through a dump of long input looking for the error.
If you think they'll get in the way sometimes, keep in mind that
it's pretty easy to grep for the start of the input dump, which is
`<<<`.
* Colored Annotations: The annotated input is colored if colors are
enabled (enabling colors can be forced using -color). For example,
errors are red. However, as in the above example, colors are not
vital to reading the annotations.
I don't know how to test color in the output, so any hints here would
be appreciated.
Reviewed By: george.karpenkov, zturner, probinson
Differential Revision: https://reviews.llvm.org/D52999
llvm-svn: 349418
|
||
|---|---|---|
| .. | ||
| _ocamldoc | ||
| _static | ||
| _templates | ||
| _themes/llvm-theme | ||
| AMDGPU | ||
| CommandGuide | ||
| Frontend | ||
| HistoricalNotes | ||
| PDB | ||
| Proposals | ||
| TableGen | ||
| tutorial | ||
| AdvancedBuilds.rst | ||
| AliasAnalysis.rst | ||
| AMDGPUInstructionNotation.rst | ||
| AMDGPUInstructionSyntax.rst | ||
| AMDGPUModifierSyntax.rst | ||
| AMDGPUOperandSyntax.rst | ||
| AMDGPUUsage.rst | ||
| ARM-BE-bitcastfail.png | ||
| ARM-BE-bitcastsuccess.png | ||
| ARM-BE-ld1.png | ||
| ARM-BE-ldr.png | ||
| Atomics.rst | ||
| Benchmarking.rst | ||
| BigEndianNEON.rst | ||
| BitCodeFormat.rst | ||
| BlockFrequencyTerminology.rst | ||
| BranchWeightMetadata.rst | ||
| BugLifeCycle.rst | ||
| Bugpoint.rst | ||
| CFIVerify.rst | ||
| CMake.rst | ||
| CMakeLists.txt | ||
| CMakePrimer.rst | ||
| CodeGenerator.rst | ||
| CodeOfConduct.rst | ||
| CodingStandards.rst | ||
| CommandLine.rst | ||
| CompileCudaWithLLVM.rst | ||
| CompilerWriterInfo.rst | ||
| conf.py | ||
| Contributing.rst | ||
| Coroutines.rst | ||
| CoverageMappingFormat.rst | ||
| DebuggingJITedCode.rst | ||
| DeveloperPolicy.rst | ||
| Docker.rst | ||
| doxygen-mainpage.dox | ||
| doxygen.cfg.in | ||
| ExceptionHandling.rst | ||
| ExtendedIntegerResults.txt | ||
| ExtendingLLVM.rst | ||
| Extensions.rst | ||
| FAQ.rst | ||
| FaultMaps.rst | ||
| FuzzingLLVM.rst | ||
| GarbageCollection.rst | ||
| gcc-loops.png | ||
| GetElementPtr.rst | ||
| GettingStarted.rst | ||
| GettingStartedVS.rst | ||
| GlobalISel.rst | ||
| GoldPlugin.rst | ||
| HowToAddABuilder.rst | ||
| HowToBuildOnARM.rst | ||
| HowToBuildWithPGO.rst | ||
| HowToCrossCompileBuiltinsOnArm.rst | ||
| HowToCrossCompileLLVM.rst | ||
| HowToReleaseLLVM.rst | ||
| HowToSetUpLLVMStyleRTTI.rst | ||
| HowToSubmitABug.rst | ||
| HowToUseAttributes.rst | ||
| HowToUseInstrMappings.rst | ||
| InAlloca.rst | ||
| index.rst | ||
| LangRef.rst | ||
| Lexicon.rst | ||
| LibFuzzer.rst | ||
| LinkTimeOptimization.rst | ||
| linpack-pc.png | ||
| LLVMBuild.rst | ||
| LLVMBuild.txt | ||
| make.bat | ||
| Makefile.sphinx | ||
| MarkdownQuickstartTemplate.md | ||
| MarkedUpDisassembly.rst | ||
| MCJIT-creation.png | ||
| MCJIT-dyld-load.png | ||
| MCJIT-engine-builder.png | ||
| MCJIT-load-object.png | ||
| MCJIT-load.png | ||
| MCJIT-resolve-relocations.png | ||
| MCJITDesignAndImplementation.rst | ||
| MemorySSA.rst | ||
| MergeFunctions.rst | ||
| MIRLangRef.rst | ||
| NVPTXUsage.rst | ||
| OptBisect.rst | ||
| Packaging.rst | ||
| Passes.rst | ||
| Phabricator.rst | ||
| ProgrammersManual.rst | ||
| Projects.rst | ||
| re_format.7 | ||
| README.txt | ||
| ReleaseNotes.rst | ||
| ReleaseProcess.rst | ||
| ReportingGuide.rst | ||
| ScudoHardenedAllocator.rst | ||
| SegmentedStacks.rst | ||
| SourceLevelDebugging.rst | ||
| speculative_load_hardening_microbenchmarks.png | ||
| SpeculativeLoadHardening.md | ||
| SphinxQuickstartTemplate.rst | ||
| StackMaps.rst | ||
| StackSafetyAnalysis.rst | ||
| Statepoints.rst | ||
| SupportLibrary.rst | ||
| SystemLibrary.rst | ||
| TableGenFundamentals.rst | ||
| TestingGuide.rst | ||
| TestSuiteGuide.md | ||
| TestSuiteMakefileGuide.rst | ||
| TransformMetadata.rst | ||
| TypeMetadata.rst | ||
| Vectorizers.rst | ||
| WritingAnLLVMBackend.rst | ||
| WritingAnLLVMPass.rst | ||
| XRay.rst | ||
| XRayExample.rst | ||
| XRayFDRFormat.rst | ||
| yaml2obj.rst | ||
| YamlIO.rst | ||
LLVM Documentation
==================
LLVM's documentation is written in reStructuredText, a lightweight
plaintext markup language (file extension `.rst`). While the
reStructuredText documentation should be quite readable in source form, it
is mostly meant to be processed by the Sphinx documentation generation
system to create HTML pages which are hosted on <http://llvm.org/docs/> and
updated after every commit. Manpage output is also supported, see below.
If you instead would like to generate and view the HTML locally, install
Sphinx <http://sphinx-doc.org/> and then do:
cd <build-dir>
cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_HTML=true <src-dir>
make -j3 docs-llvm-html
$BROWSER <build-dir>/docs//html/index.html
The mapping between reStructuredText files and generated documentation is
`docs/Foo.rst` <-> `<build-dir>/docs//html/Foo.html` <-> `http://llvm.org/docs/Foo.html`.
If you are interested in writing new documentation, you will want to read
`SphinxQuickstartTemplate.rst` which will get you writing documentation
very fast and includes examples of the most important reStructuredText
markup syntax.
Manpage Output
===============
Building the manpages is similar to building the HTML documentation. The
primary difference is to use the `man` makefile target, instead of the
default (which is `html`). Sphinx then produces the man pages in the
directory `<build-dir>/docs/man/`.
cd <build-dir>
cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_MAN=true <src-dir>
make -j3 docs-llvm-man
man -l >build-dir>/docs/man/FileCheck.1
The correspondence between .rst files and man pages is
`docs/CommandGuide/Foo.rst` <-> `<build-dir>/docs//man/Foo.1`.
These .rst files are also included during HTML generation so they are also
viewable online (as noted above) at e.g.
`http://llvm.org/docs/CommandGuide/Foo.html`.
Checking links
==============
The reachability of external links in the documentation can be checked by
running:
cd docs/
make -f Makefile.sphinx linkcheck
Doxygen page Output
==============
Install doxygen <http://www.stack.nl/~dimitri/doxygen/download.html> and dot2tex <https://dot2tex.readthedocs.io/en/latest>.
cd <build-dir>
cmake -DLLVM_ENABLE_DOXYGEN=On <llvm-top-src-dir>
make doxygen-llvm # for LLVM docs
make doxygen-clang # for clang docs
It will generate html in
<build-dir>/docs/doxygen/html # for LLVM docs
<build-dir>/tools/clang/docs/doxygen/html # for clang docs