1 How the scripts are structured:
2 - check-package is the main engine, called by the user.
3 For each input file, this script decides which parser should be used and it
4 collects all classes declared in the library file and instantiates them.
5 The main engine opens the input files and it serves each raw line (including
6 newline!) to the method check_line() of every check object.
7 Two special methods before() and after() are used to call the initialization
8 of variables (for the case it needs to keep data across calls) and the
9 equivalent finalization (e.g. for the case a warning must be issued if some
10 pattern is not in the input file).
11 - base.py contains the base class for all check functions.
12 - lib.py contains the classes for common check functions.
13 Each check function is explicitly included in a given type-parsing library.
14 Do not include every single check function in this file, a class that will
15 only parse hash files should be implemented in the hash-parsing library.
16 When a warning must be issued, the check function returns an array of strings.
17 Each string is a warning message and is displayed if the corresponding verbose
18 level is active. When the script is called without --verbose only the first
19 warning in the returned array is printed; when called with --verbose both
20 first and second warnings are printed; when called with -vv until the third
21 warning is printed; an so on.
22 Helper functions can be defined and will not be called by the main script.
23 - lib_type.py contains check functions specific to files of this type.
25 Some hints when changing this code:
26 - prefer O(n) algorithms, where n is the total number of lines in the files
28 - when there is no other reason for ordering, use alphabetical order (e.g. keep
29 the check functions in alphabetical order, keep the imports in alphabetical
31 - use pyflakes to detect and fix potential problems.
32 - use pep8 formatting.
33 - keep in mind that for every class the method before() will be called before
34 any line is served to be checked by the method check_line(). A class that
35 checks the filename should only implement the method before(). A function that
36 needs to keep data across calls (e.g. keep the last line before the one being
37 processed) should initialize all variables using this method.
38 - keep in mind that for every class the method after() will be called after all
39 lines were served to be checked by the method check_line(). A class that
40 checks the absence of a pattern in the file will need to use this method.
41 - try to avoid false warnings. It's better to not issue a warning message to a
42 corner case than have too many false warnings. The second can make users stop
44 - do not check spacing in the input line in every single function. Trailing
45 whitespace and wrong indentation should be checked by separate functions.
46 - avoid duplicate tests. Try to test only one thing in each function.
47 - in the warning message, include the url to a section from the manual, when
48 applicable. It potentially will make more people know the manual.
49 - use short sentences in the warning messages. A complete explanation can be
50 added to show when --verbose is used.
51 - when testing, verify the error message is displayed when the error pattern is
52 found, but also verify the error message is not displayed for few
53 well-formatted packages... there are many of these, just pick your favorite
54 as golden package that should not trigger any warning message.
55 - check the url displayed by the warning message works.
58 - to get a list of check functions that would be called without actually
59 calling them you can use the --dry-run option:
60 $ support/scripts/check-package --dry-run package/yourfavorite/*
62 - when you just added a new check function, e.g. Something, check how it behaves
63 for all current packages:
64 $ support/scripts/check-package --include-only Something $(find package -type f)
66 - the effective processing time (when the .pyc were already generated and all
67 files to be processed are cached in the RAM) should stay in the order of few
69 $ support/scripts/check-package $(find package -type f) >/dev/null ; \
70 time support/scripts/check-package $(find package -type f) >/dev/null
72 - vim users can navigate the warnings (most editors probably have similar
73 function) since warnings are generated in the form 'path/file:line: warning':
74 $ find package/ -name 'Config.*' > filelist && vim -c \
75 'set makeprg=support/scripts/check-package\ $(cat\ filelist)' -c make -c copen