|
| 1 | +.. Copyright 2011-2012, 2017 David Malcolm <dmalcolm@redhat.com> |
| 2 | + Copyright 2011-2012, 2017 Red Hat, Inc. |
| 3 | +
|
| 4 | + This is free software: you can redistribute it and/or modify it |
| 5 | + under the terms of the GNU General Public License as published by |
| 6 | + the Free Software Foundation, either version 3 of the License, or |
| 7 | + (at your option) any later version. |
| 8 | +
|
| 9 | + This program is distributed in the hope that it will be useful, but |
| 10 | + WITHOUT ANY WARRANTY; without even the implied warranty of |
| 11 | + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 12 | + General Public License for more details. |
| 13 | +
|
| 14 | + You should have received a copy of the GNU General Public License |
| 15 | + along with this program. If not, see |
| 16 | + <http://www.gnu.org/licenses/>. |
| 17 | +
|
| 18 | +Generating custom errors and warnings |
| 19 | +===================================== |
| 20 | + |
| 21 | +.. py:function:: gcc.warning(location, message, option=None) |
| 22 | +
|
| 23 | + Emits a compiler warning at the given :py:class:`gcc.Location`, potentially |
| 24 | + controlled by a :py:class:`gcc.Option`. |
| 25 | + |
| 26 | + If no option is supplied (or `None` is supplied), then the warning is an |
| 27 | + unconditional one, always issued:: |
| 28 | + |
| 29 | + gcc.warning(func.start, 'this is an unconditional warning') |
| 30 | + |
| 31 | + .. code-block:: bash |
| 32 | +
|
| 33 | + $ ./gcc-with-python script.py input.c |
| 34 | + input.c:25:1: warning: this is an unconditional warning [enabled by default] |
| 35 | +
|
| 36 | + and will be an error if `-Werror` is supplied as a command-line argument to |
| 37 | + GCC: |
| 38 | + |
| 39 | + .. code-block:: bash |
| 40 | +
|
| 41 | + $ ./gcc-with-python script.py -Werror input.c |
| 42 | + input.c:25:1: error: this is an unconditional warning [-Werror] |
| 43 | +
|
| 44 | + It's possible to associate the warning with a command-line option, so that |
| 45 | + it is controlled by that option. |
| 46 | + |
| 47 | + For example, given this Python code:: |
| 48 | + |
| 49 | + gcc.warning(func.start, 'Incorrect formatting', gcc.Option('-Wformat')) |
| 50 | + |
| 51 | + if the given warning is enabled, a warning will be printed to stderr: |
| 52 | + |
| 53 | + .. code-block:: bash |
| 54 | +
|
| 55 | + $ ./gcc-with-python script.py input.c |
| 56 | + input.c:25:1: warning: incorrect formatting [-Wformat] |
| 57 | +
|
| 58 | + If the given warning is being treated as an error (through the usage |
| 59 | + of `-Werror`), then an error will be printed: |
| 60 | + |
| 61 | + .. code-block:: bash |
| 62 | +
|
| 63 | + $ ./gcc-with-python script.py -Werror input.c |
| 64 | + input.c:25:1: error: incorrect formatting [-Werror=format] |
| 65 | + cc1: all warnings being treated as errors |
| 66 | +
|
| 67 | + .. code-block:: bash |
| 68 | +
|
| 69 | + $ ./gcc-with-python script.py -Werror=format input.c |
| 70 | + input.c:25:1: error: incorrect formatting [-Werror=format] |
| 71 | + cc1: some warnings being treated as errors |
| 72 | +
|
| 73 | + If the given warning is disabled, the warning will not be printed: |
| 74 | + |
| 75 | + .. code-block:: bash |
| 76 | +
|
| 77 | + $ ./gcc-with-python script.py -Wno-format input.c |
| 78 | +
|
| 79 | + .. note:: Due to the way GCC implements some options, it's not always |
| 80 | + possible for the plugin to fully disable some warnings. See |
| 81 | + :py:attr:`gcc.Option.is_enabled` for more information. |
| 82 | + |
| 83 | + The function returns a boolean, indicating whether or not anything was |
| 84 | + actually printed. |
| 85 | + |
| 86 | +.. py:function:: gcc.error(location, message) |
| 87 | +
|
| 88 | + Emits a compiler error at the given :py:class:`gcc.Location`. |
| 89 | + |
| 90 | + For example:: |
| 91 | + |
| 92 | + gcc.error(func.start, 'something bad was detected') |
| 93 | + |
| 94 | + would lead to this error being printed to stderr: |
| 95 | + |
| 96 | + .. code-block:: bash |
| 97 | +
|
| 98 | + $ ./gcc-with-python script.py input.c |
| 99 | + input.c:25:1: error: something bad was detected |
| 100 | +
|
| 101 | +.. py:function:: gcc.permerror(loc, str) |
| 102 | +
|
| 103 | + This is a wrapper around GCC's `permerror` function. |
| 104 | + |
| 105 | + Expects an instance of :py:class:`gcc.Location` (not None) and a string |
| 106 | + |
| 107 | + Emit a "permissive" error at that location, intended for things that really |
| 108 | + ought to be errors, but might be present in legacy code. |
| 109 | + |
| 110 | + In theory it's suppressable using "-fpermissive" at the GCC command line |
| 111 | + (which turns it into a warning), but this only seems to be legal for C++ |
| 112 | + source files. |
| 113 | + |
| 114 | + Returns True if the warning was actually printed, False otherwise |
| 115 | + |
| 116 | +.. py:function:: gcc.inform(loc, str) |
| 117 | +
|
| 118 | + This is a wrapper around GCC's `inform` function. |
| 119 | + |
| 120 | + Expects an instance of :py:class:`gcc.Location` (not None) and a string |
| 121 | + |
| 122 | + Emit an informational message at that location. |
| 123 | + |
| 124 | + For example:: |
| 125 | + |
| 126 | + gcc.inform(stmt.loc, 'this is where X was defined') |
| 127 | + |
| 128 | + would lead to this informational message being printed to stderr: |
| 129 | + |
| 130 | + .. code-block:: bash |
| 131 | +
|
| 132 | + $ ./gcc-with-python script.py input.c |
| 133 | + input.c:23:3: note: this is where X was defined |
0 commit comments