| 1 |
.. title:: clang-tidy - cppcoreguidelines-macro-usage |
| 2 |
|
| 3 |
cppcoreguidelines-macro-usage |
| 4 |
============================= |
| 5 |
|
| 6 |
Finds macro usage that is considered problematic because better language |
| 7 |
constructs exist for the task. |
| 8 |
|
| 9 |
The relevant sections in the C++ Core Guidelines are |
| 10 |
`ES.31 <https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es31-dont-use-macros-for-constants-or-functions>`_, and |
| 11 |
`ES.32 <https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es32-use-all_caps-for-all-macro-names>`_. |
| 12 |
|
| 13 |
Examples: |
| 14 |
|
| 15 |
.. code-block:: c++ |
| 16 |
|
| 17 |
#define C 0 |
| 18 |
#define F1(x, y) ((a) > (b) ? (a) : (b)) |
| 19 |
#define F2(...) (__VA_ARGS__) |
| 20 |
#define COMMA , |
| 21 |
#define NORETURN [[noreturn]] |
| 22 |
#define DEPRECATED attribute((deprecated)) |
| 23 |
#if LIB_EXPORTS |
| 24 |
#define DLLEXPORTS __declspec(dllexport) |
| 25 |
#else |
| 26 |
#define DLLEXPORTS __declspec(dllimport) |
| 27 |
#endif |
| 28 |
|
| 29 |
results in the following warnings:: |
| 30 |
|
| 31 |
4 warnings generated. |
| 32 |
test.cpp:1:9: warning: macro 'C' used to declare a constant; consider using a 'constexpr' constant [cppcoreguidelines-macro-usage] |
| 33 |
#define C 0 |
| 34 |
^ |
| 35 |
test.cpp:2:9: warning: function-like macro 'F1' used; consider a 'constexpr' template function [cppcoreguidelines-macro-usage] |
| 36 |
#define F1(x, y) ((a) > (b) ? (a) : (b)) |
| 37 |
^ |
| 38 |
test.cpp:3:9: warning: variadic macro 'F2' used; consider using a 'constexpr' variadic template function [cppcoreguidelines-macro-usage] |
| 39 |
#define F2(...) (__VA_ARGS__) |
| 40 |
^ |
| 41 |
|
| 42 |
|
| 43 |
Options |
| 44 |
------- |
| 45 |
|
| 46 |
.. option:: AllowedRegexp |
| 47 |
|
| 48 |
A regular expression to filter allowed macros. For example |
| 49 |
`DEBUG*|LIBTORRENT*|TORRENT*|UNI*` could be applied to filter `libtorrent`. |
| 50 |
Default value is `^DEBUG_*`. |
| 51 |
|
| 52 |
.. option:: CheckCapsOnly |
| 53 |
|
| 54 |
Boolean flag to warn on all macros except those with CAPS_ONLY names. |
| 55 |
This option is intended to ease introduction of this check into older |
| 56 |
code bases. Default value is `false`. |
| 57 |
|
| 58 |
.. option:: IgnoreCommandLineMacros |
| 59 |
|
| 60 |
Boolean flag to toggle ignoring command-line-defined macros. |
| 61 |
Default value is `true`. |