Merge branch 'tor-github/pr/1246'

Makefile.am

@@ -168,6 +168,7 @@ EXTRA_DIST+= \
 	ReleaseNotes					\
 	scripts/maint/checkIncludes.py                  \
 	scripts/maint/checkSpace.pl 			\
+	scripts/maint/practracker/README                \
 	scripts/maint/practracker/exceptions.txt	\
 	scripts/maint/practracker/includes.py		\
 	scripts/maint/practracker/metrics.py		\

scripts/maint/practracker/README

@@ -0,0 +1,21 @@
+Practracker is a simple python tool that keeps track of places where
+our code is ugly, and tries to warn us about new ones or ones that
+get worse.
+
+Right now, practracker looks for the following kinds of
+best-practices violations:
+
+  .c files greater than 3000 lines long
+  .h files greater than 500 lines long
+  .c files with more than 50 includes
+  .h files with more than 15 includes
+
+  All files that include a local header not listed in a .may_include
+  file in the same directory, when that .may_include file has an
+  "!advisory" marker.
+
+The list of current violations is tracked in exceptions.txt; slight
+deviations of the current exceptions cause warnings, whereas large
+ones cause practracker to fail.
+
+For usage information, run "practracker.py --help".

scripts/maint/practracker/includes.py

@@ -212,7 +212,7 @@ def consider_include_rules(fname, f):
     log_sorted_levels = False
 
 def walk_c_files(topdir="src"):
-    """Run through all c and h files under topdir, looking for
+    """Run through all .c and .h files under topdir, looking for
        include-rule violations. Yield those violations."""
 
     for dirpath, dirnames, fnames in os.walk(topdir):

scripts/maint/practracker/practracker.py

@@ -7,7 +7,8 @@ Go through the various .c files and collect metrics about them. If the metrics
 violate some of our best practices and they are not found in the optional
 exceptions file, then log a problem about them.
 
-We currently do metrics about file size, function size and number of includes.
+We currently do metrics about file size, function size and number of includes,
+for C source files and headers.
 
 practracker.py should be run with its second argument pointing to the Tor
 top-level source directory like this:
@@ -143,8 +144,12 @@ HEADER="""\
 #
 # There are three kinds of problems that we recognize right now:
 #   function-size -- a function of more than {MAX_FUNCTION_SIZE} lines.
-#   file-size -- a file of more than {MAX_FILE_SIZE} lines.
-#   include-count -- a file with more than {MAX_INCLUDE_COUNT} #includes.
+#   file-size -- a .c file of more than {MAX_FILE_SIZE} lines, or a .h
+#      file with more than {MAX_H_FILE_SIZE} lines.
+#   include-count -- a .c file with more than {MAX_INCLUDE_COUNT} #includes,
+       or a .h file with more than {MAX_H_INCLUDE_COUNT} #includes.
+#   dependency-violation -- a file includes a header that it should
+#      not, according to an advisory .may_include file.
 #
 # Each line below represents a single exception that practracker should
 # _ignore_. Each line has four parts:
@@ -184,13 +189,13 @@ def main(argv):
     parser.add_argument("--terse", action="store_true",
                         help="Do not emit helpful instructions.")
     parser.add_argument("--max-h-file-size", default=MAX_H_FILE_SIZE,
-                        help="Maximum lines per .H file")
+                        help="Maximum lines per .h file")
     parser.add_argument("--max-h-include-count", default=MAX_H_INCLUDE_COUNT,
-                        help="Maximum includes per .H file")
+                        help="Maximum includes per .h file")
     parser.add_argument("--max-file-size", default=MAX_FILE_SIZE,
-                        help="Maximum lines per C file")
+                        help="Maximum lines per .c file")
     parser.add_argument("--max-include-count", default=MAX_INCLUDE_COUNT,
-                        help="Maximum includes per C file")
+                        help="Maximum includes per .c file")
     parser.add_argument("--max-function-size", default=MAX_FUNCTION_SIZE,
                         help="Maximum lines per function")
     parser.add_argument("--max-dependency-violations", default=MAX_DEP_VIOLATIONS,