================
@@ -0,0 +1,90 @@
+============================
+Warning suppression mappings
+============================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+Warning suppression mappings enable users to suppress Clang's diagnostics in a
+per-file granular manner. Enabling enforcement of diagnostics in specific parts
+of the project, even if there are violations in some headers.
+
+Goal and usage
+==============
+
+Clang allows diagnostics to be configured at a translation-unit granularity.
+If a ``foo.cpp`` is compiled with ``-Wfoo``, all transitively included headers
+also need to be clean. Hence turning on new warnings in large codebases can be
+difficult today. Since it requires cleaning up all the existing warnings,
+which might not be possible when some dependencies aren't in the project
owner's
+control or because new violations are creeping up quicker than the clean up.
+
+Warning suppression mappings aim to alleviate some of these concerns by making
+diagnostic configuration granularity finer, at a source file level.
+
+To achieve this, user can create a file that lists which diagnostic groups to
+suppress in which files or paths, and pass it as a command line argument to
+Clang with the ``--warning-suppression-mappings`` flag.
+
+Note that this mechanism won't enable any diagnostics on its own. Users should
+still turn on warnings in their compilations with explicit ``-Wfoo`` flags.
+
+Example
+=======
+
+.. code-block:: bash
+
+ $ cat my/user/code.cpp
+ #include <foo/bar.h>
+ namespace { void unused_func1(); }
+
+ $ cat foo/bar.h
+ namespace { void unused_func2(); }
+
+ $ cat suppression_mappings.txt
+ # Suppress -Wunused warnings in all files, apart from the ones under `foo/`.
+ [unused]
+ src:*
+ src:*foo/*=emit
+ $ clang -Wunused --warning-suppression-mappings=suppression_mappings.txt
my/user/code.cpp
+ # prints warning: unused function 'unused_func2', but no warnings for
`unused_func1`.
+
+Format
+======
+
+Warning suppression mappings uses the same format as
+:doc:`SanitizerSpecialCaseList`.
+
+Users can mention sections to describe which diagnostic group behaviours to
+change. Sections are denoted as ``[unused]`` in this format. Each section name
+must match a diagnostic group.
+When a diagnostic is matched by multiple groups, the latest one takes
+precendence.
+
+Afterwards in each section, users can have multiple entities that match source
+files based on the globs. These entities look like ``src:*/my/dir/*``.
+Users can also use the ``emit`` category to exclude a subdirectory from
+suppression.
+Source files are matched against these globs either as paths relative to th
+current working directory, or as absolute paths.
----------------
bricknerb wrote:
Careful reading it again this is ok.
If you want to emphasize it better, you can make it a list and/or emphasize the
either.
... against these globs **either**:
* as ...
* as ...
https://github.com/llvm/llvm-project/pull/112517
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
