98 lines · plain
1============================2Warning suppression mappings3============================4 5.. contents::6 :local:7 8Introduction9============10 11Warning suppression mappings enable users to suppress Clang's diagnostics at a12per-file granularity. This allows enforcing diagnostics in specific parts of the13project even if there are violations in some headers.14 15Goal and usage16==============17 18Clang allows diagnostics to be configured at a translation-unit granularity.19If a ``foo.cpp`` is compiled with ``-Wfoo``, all transitively included headers20also need to be clean. Hence, turning on new warnings in large codebases21requires cleaning up all the existing warnings. This might not be possible when22some dependencies aren't in the project owner's control or because new23violations are creeping up quicker than the clean up.24 25Warning suppression mappings aim to alleviate some of these concerns by making26diagnostic configuration granularity finer, at a source file level.27 28To achieve this, user can create a file that lists which :doc:`diagnostic29groups <DiagnosticsReference>` to suppress in which files or paths, and pass it30as a command line argument to Clang with the ``--warning-suppression-mappings``31flag.32 33Note that this mechanism won't enable any diagnostics on its own. Users should34still turn on warnings in their compilations with explicit ``-Wfoo`` flags.35`Controlling diagnostics pragmas36<https://clang.llvm.org/docs/UsersManual.html#controlling-diagnostics-via-pragmas>`_37take precedence over suppression mappings. Ensuring code author's explicit38intent is always preserved.39 40Example41=======42 43.. code-block:: bash44 45 $ cat my/user/code.cpp46 #include <foo/bar.h>47 namespace { void unused_func1(); }48 49 $ cat foo/bar.h50 namespace { void unused_func2(); }51 52 $ cat suppression_mappings.txt53 # Suppress -Wunused warnings in all files, apart from the ones under `foo/`.54 [unused]55 src:*56 src:*foo/*=emit57 $ clang -Wunused --warning-suppression-mappings=suppression_mappings.txt my/user/code.cpp58 # prints warning: unused function 'unused_func2', but no warnings for `unused_func1`.59 60Format61======62 63Warning suppression mappings uses the same format as64:doc:`SanitizerSpecialCaseList`.65 66Sections describe which diagnostic group's behavior to change, e.g.67``[unused]``. When a diagnostic is matched by multiple sections, the latest68section takes precedence.69 70Afterwards in each section, users can have multiple entities that match source71files based on the globs. These entities look like ``src:*/my/dir/*``.72Users can also use the ``emit`` category to exclude a subdirectory from73suppression.74Source files are matched against these globs either:75 76- as paths relative to the current working directory77- as absolute paths.78 79When a source file matches multiple globs in a section, the last one takes80precedence.81 82.. code-block:: bash83 84 # Lines starting with # are ignored.85 # Configure suppression globs for `-Wunused` warnings86 [unused]87 # Suppress on all files by default.88 src:*89 # But enforce for all the sources under foo/.90 src:*foo/*=emit91 92 # unused-function warnings are a subgroup of `-Wunused`. So this section93 # takes precedence over the previous one for unused-function warnings, but94 # not for unused-variable warnings.95 [unused-function]96 # Only suppress for sources under bar/.97 src:*bar/*98