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