clang/docs/WarningSuppressionMappings.rst

   1 ============================
   2 Warning suppression mappings
   3 ============================
   4
   5 .. contents::
   6    :local:
   7
   8 Introduction
   9 ============
  10
  11 Warning suppression mappings enable users to suppress Clang's diagnostics at a
  12 per-file granularity. This allows enforcing diagnostics in specific parts of the
  13 project even if there are violations in some headers.
  14
  15 Goal and usage
  16 ==============
  17
  18 Clang allows diagnostics to be configured at a translation-unit granularity.
  19 If a ``foo.cpp`` is compiled with ``-Wfoo``, all transitively included headers
  20 also need to be clean. Hence, turning on new warnings in large codebases
  21 requires cleaning up all the existing warnings. This might not be possible when
  22 some dependencies aren't in the project owner's control or because new
  23 violations are creeping up quicker than the clean up.
  24
  25 Warning suppression mappings aim to alleviate some of these concerns by making
  26 diagnostic configuration granularity finer, at a source file level.
  27
  28 To achieve this, user can create a file that lists which :doc:`diagnostic
  29 groups <DiagnosticsReference>` to suppress in which files or paths, and pass it
  30 as a command line argument to Clang with the ``--warning-suppression-mappings``
  31 flag.
  32
  33 Note that this mechanism won't enable any diagnostics on its own. Users should
  34 still turn on warnings in their compilations with explicit ``-Wfoo`` flags.
  35 `Controlling diagnostics pragmas
  36 <https://clang.llvm.org/docs/UsersManual.html#controlling-diagnostics-via-pragmas>`_
  37 take precedence over suppression mappings. Ensuring code author's explicit
  38 intent is always preserved.
  39
  40 Example
  41 =======
  42
  43 .. code-block:: bash
  44
  45   $ cat my/user/code.cpp
  46   #include <foo/bar.h>
  47   namespace { void unused_func1(); }
  48
  49   $ cat foo/bar.h
  50   namespace { void unused_func2(); }
  51
  52   $ cat suppression_mappings.txt
  53   # Suppress -Wunused warnings in all files, apart from the ones under `foo/`.
  54   [unused]
  55   src:*
  56   src:*foo/*=emit
  57   $ clang -Wunused --warning-suppression-mappings=suppression_mappings.txt my/user/code.cpp
  58   # prints warning: unused function 'unused_func2', but no warnings for `unused_func1`.
  59
  60 Format
  61 ======
  62
  63 Warning suppression mappings uses the same format as
  64 :doc:`SanitizerSpecialCaseList`.
  65
  66 Sections describe which diagnostic group's behaviour to change, e.g.
  67 ``[unused]``. When a diagnostic is matched by multiple sections, the latest
  68 section takes precedence.
  69
  70 Afterwards in each section, users can have multiple entities that match source
  71 files based on the globs. These entities look like ``src:*/my/dir/*``.
  72 Users can also use the ``emit`` category to exclude a subdirectory from
  73 suppression.
  74 Source files are matched against these globs either:
  75
  76 - as paths relative to the current working directory
  77 - as absolute paths.
  78
  79 When a source file matches multiple globs in a section, the longest one takes
  80 precedence.
  81
  82 .. code-block:: bash
  83
  84     # Lines starting with # are ignored.
  85     # Configure suppression globs for `-Wunused` warnings
  86     [unused]
  87     # Suppress on all files by default.
  88     src:*
  89     # But enforce for all the sources under foo/.
  90     src:*foo/*=emit
  91
  92     # unused-function warnings are a subgroup of `-Wunused`. So this section
  93     # takes precedence over the previous one for unused-function warnings, but
  94     # not for unused-variable warnings.
  95     [unused-function]
  96     # Only suppress for sources under bar/.
  97     src:*bar/*