Tools for tracking compiler warnings

The compiler warning tracking tooling is intended to alert developers about new compiler warnings introduced by their contributions. The tooling consists of a Python script which is ran by the following GitHub workflows:

You can check the documentation for the Tools/build/check_warnings.py tool by running:

python Tools/build/check_warnings.py --help

The script can be run locally by providing the compiler output file (where the output is saved) and the compiler output type (either gcc or clang) to see a list of unique warnings:

python Tools/build/check_warnings.py --compiler-output-file-path=compiler_output.txt --compiler-output-type=gcc

What to do if a warning check fails GitHub CI

The Tools/build/check_warnings.py tool will fail if the compiler generates more or less warnings than expected for a given source file as defined in the platform-specific warning ignore file. The warning ignore file is either Tools/build/.warningignore_ubuntu or Tools/build/.warningignore_macos depending on the platform.

If a warning check fails with:

  • Unexpected warnings

    • Attempt to refactor the code to avoid the warning.

    • If it is not possible to avoid the warning document in the PR why it is reasonable to ignore and add the warning to the platform-specific warning ignore file. If the file exists in the warning ignore file increment the count by the number of newly introduced warnings.

  • Unexpected improvements (less warnings)

    • Document in the PR that the change reduces the number of compiler warnings. Decrement the count in the platform-specific warning ignore file or remove the file if the count is now zero.

Updating the warning ignore file

The warning ignore files can be found in the Tools/build/ directory. Both files and directories can be added to the ignore file. Files can have an explicit warning count or a wildcard count. Directories must be followed by a wildcard count. Wildcards indicate that 0 or more warnings will be ignored. The following is an example of the warning ignore file format:

Modules/_ctypes/_ctypes_test_generated.c.h *
Objects/longobject.c 46
Objects/methodobject.c 1
Objects/mimalloc/ *

Using wildcards is reserved for code that is not maintained by CPython, or code that is for tests. Keep lines in warning ignore files sorted lexicographically.