commit ee1228622291217fd2614a4e29469559b8dc4129 Author: Nick Mathewson nickm@torproject.org Date: Mon Jul 9 16:02:31 2018 -0400

Add a little documentation to checkIncludes.py.

Someday people might be glad I did. --- scripts/maint/checkIncludes.py | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+)

diff --git a/scripts/maint/checkIncludes.py b/scripts/maint/checkIncludes.py index eb25cb209..d13ff565c 100755 --- a/scripts/maint/checkIncludes.py +++ b/scripts/maint/checkIncludes.py @@ -1,6 +1,21 @@ #!/usr/bin/python3 # Copyright 2018 The Tor Project, Inc. See LICENSE file for licensing info.

+"""This script looks through all the directories for files matching *.c or + *.h, and checks their #include directives to make sure that only "permitted" + headers are included. + + Any #include directives with angle brackets (like #include <stdio.h>) are + ignored -- only directives with quotes (like #include "foo.h") are + considered. + + To decide what includes are permitted, this script looks at a .may_include + file in each directory. This file contains empty lines, #-prefixed + comments, filenames (like "lib/foo/bar.h") and file globs (like lib/*/*.h) + for files that are permitted. +""" + + from __future__ import print_function

import fnmatch @@ -8,20 +23,26 @@ import os import re import sys

+# Global: Have there been any errors? trouble = False

def err(msg): + """ Declare that an error has happened, and remember that there has + been an error. """ global trouble trouble = True print(msg, file=sys.stderr)

def fname_is_c(fname): + """ Return true iff 'fname' is the name of a file that we should + search for possibly disallowed #include directives. """ return fname.endswith(".h") or fname.endswith(".c")

INCLUDE_PATTERN = re.compile(r'\s*#\s*include\s+"([^"]*)"') RULES_FNAME = ".may_include"

class Rules(object): + """ A 'Rules' object is the parsed version of a .may_include file. """ def __init__(self, dirpath): self.dirpath = dirpath self.patterns = [] @@ -59,6 +80,7 @@ class Rules(object): print("Pattern {} in {} was never used.".format(p, self.dirpath))

def load_include_rules(fname): + """ Read a rules file from 'fname', and return it as a Rules object. """ result = Rules(os.path.split(fname)[0]) with open(fname, 'r') as f: for line in f: