clang-tools-extra/docs/clang-tidy/checks/portability/restrict-system-includes.rst

   1 .. title:: clang-tidy - portability-restrict-system-includes
   2
   3 portability-restrict-system-includes
   4 ====================================
   5
   6 Checks to selectively allow or disallow a configurable list of system headers.
   7
   8 For example:
   9
  10 In order to **only** allow `zlib.h` from the system you would set the options
  11 to `-*,zlib.h`.
  12
  13 .. code-block:: c++
  14
  15   #include <curses.h>       // Bad: disallowed system header.
  16   #include <openssl/ssl.h>  // Bad: disallowed system header.
  17   #include <zlib.h>         // Good: allowed system header.
  18   #include "src/myfile.h"   // Good: non-system header always allowed.
  19
  20 In order to allow everything **except** `zlib.h` from the system you would set
  21 the options to `*,-zlib.h`.
  22
  23 .. code-block:: c++
  24
  25   #include <curses.h>       // Good: allowed system header.
  26   #include <openssl/ssl.h>  // Good: allowed system header.
  27   #include <zlib.h>         // Bad: disallowed system header.
  28   #include "src/myfile.h"   // Good: non-system header always allowed.
  29
  30 Since the options support globbing you can use wildcarding to allow groups of
  31 headers.
  32
  33 `-*,openssl/*.h` will allow all openssl headers but disallow any others.
  34
  35 .. code-block:: c++
  36
  37   #include <curses.h>       // Bad: disallowed system header.
  38   #include <openssl/ssl.h>  // Good: allowed system header.
  39   #include <openssl/rsa.h>  // Good: allowed system header.
  40   #include <zlib.h>         // Bad: disallowed system header.
  41   #include "src/myfile.h"   // Good: non-system header always allowed.
  42
  43 Options
  44 -------
  45
  46 .. option:: Includes
  47
  48    A string containing a comma separated glob list of allowed include
  49    filenames. Similar to the -checks glob list for running clang-tidy itself,
  50    the two wildcard characters are `*` and `-`, to include and exclude globs,
  51    respectively. The default is `*`, which allows all includes.