Back to home page

Project CMSSW displayed by LXR



Warning, /Utilities/ReleaseScripts/scripts/includechecker_README is written in an unsupported language. File is not indexed.

0001                            Include Checker 1.0.0
0002                 Shahzad Muzaffar (
0003                    Northeastern University, Boston, USA
0005 What is Include Checker: 
0007   Include Checker is a perl script which can parse any c/c++ files (source/
0008 header) and checks if any include statement is needed or not. It can tell you
0010   - Which files you do not need to include (because they are not need or might
0011     be included by some other files).
0012   - Which files you need to include
0013   - Numbers of lines in each file
0014   - Number of comment lines
0015   - Number of empty lines
0016   - Number of actual code lines (If a line has code and comments then that
0017     will be counted once for code and once for comments).
0018   - Number of included files
0020   Your code should not have any compilation errors and each file should be
0021 self parsed.
0023   This script assumes that a .cc file always needs its own .h. e.g. will
0024 always need A.h.
0026   There is also another script available to generate some statistics of the code
0027 e.g. number of code/empty/comments lines for project upto the file level. The
0028 script is and to run it you have to first run and
0029 save its output in a log file then run of that log file. e.g.
0030   > ...  > mylog.txt
0031   > --log mylog.txt
0033 How does it work:
0035   Include Checker parses the c/c++ (source/header) file and collects the list
0036 of files included in it. Then it compiles the original file and collects the
0037 warnings generated by the compiler (if there are any). After this, it comments
0038 the 1st include line, compiles and checks the compiler warnings/errors with the
0039 original results. If there is mismatch then this tool assumes that this include
0040 line is needed otherwise it keeps that include line commented (this is all done
0041 on a copy of original file). It does this for all the includes and at the end
0042 it copies the modified file in a temp area. Compilation is done in a way that
0043 for each file the already modified files are used. e.g. if file A/file1.h
0044 includes A/file2.h then first A/file1.h will be checked and copied to
0045 /tmp/A/file1.h. Now when A/file2.h is tested then -I/tmp will be added to the
0046 start of compilation command for A/file2.h so that it get the modified
0047 A/file.h.
0049   Some times developers do not include a header file because it is indirectly
0050 included by some other header they have included. e.g. A/file2.h assumes
0051 that A/file1.h has already included X/file3.h, so just including A/file1.h
0052 in A/file2.h would be enough. Now what will happen if include checker decided
0053 to remove X/file3.h from A/file1.h? Will the compilation of A/file2.h failed.
0054 The answer is no, before compiling A/file2.h, include checker will add all the
0055 removed include statement from A/file1.h (or all other dependent includes) into
0056 A/file2.h. If X/file3.h is really needed by A/file2.h the include checker will
0057 suggest to add it otherwise it silently remove it from A/file2.h.
0059   If for some reasons the compilation of original file failed (most of time it
0060 happens when a file is not parsed by itself) then include checker will stop its
0061 processing. Its better to use "--keep" command line option which will save you
0062 some time. e.g. if you have 300 files to check and at file number 250 the
0063 include checker decided to stop then all the time checking 250 files will be
0064 wasted if --keep was not ON. Please see --keep command line argument detail.
0066 How to run:
0068   Here are the command line options you can use
0070   --config <file>
0072     Please see "How to create a config file" section
0074   --recursive
0076     If this flag is used then all the included files will be check first (only
0077   if they exist under any BASE_DIR, matched by the INCLUDE_FILTER and not
0078   explicitly skipped via SKIP_FILES key).
0080   --keep <num>
0082     Do not delete the tmp files.
0083     num < 0: Internal cache will be saved only once at the time of exit
0084     num > 0: Internal cache will be saved after checking num files
0085     num = 0: Same as if keep was not passed to command line argument i.e. do
0086   not keep the tmp area.
0088     By default the tmp directory used by the include checker is deleted at the
0089   end. If you want to keep it then use this option. So if you think that include
0090   checker has done a good job, you can copy updated files from this tmp area to
0091   your original area.
0092     Also --keep is useful if you are going to check many files and in middle
0093   include checker stops due to errors in your original files. In this case
0094   you can fix the error and start include checker again with --tmpdir <prev_dir>
0095   This will save you a lot of time.
0096     Include checker writes its internal cache in this tmp area, so next time
0097   when you start include checker with --tmpdir <dir> then it reads that
0098   previously saved cache and start the processing where it left.
0100   --tmpdir <dir>
0102     One can provide its own tmp directory. This option will also enable the
0103   --keep option. If your <dir> already has a config_cache file then include
0104   checker will ignore your config file passed via --config command line option.
0105   At the end of include checker processing you can find an updated version of
0106   your file in <dir>/includechecker/src. If you are happy with include checker
0107   results then you can directly copy these file from this tmp area to your
0108   original area.
0110   --detail
0112     It will prints more detail messages of include checker. e.g. why include
0113     checker thinks a included file is needed etc.
0115   --help
0117     To see the include checker help message.
0119 How to create a config file:
0121   One needs to create a config file which then can be passed to include checker
0122 via command line argument. Here is what one needs to provide in this config
0123 file. Format of this file is KEY=VALUE. Some keys are optional. Here are the
0124 list of keys
0126 - BASE_DIR=<space separated list of base directories>
0128   Files only exist under these directories will be checked. One can use this
0129   key multiple times to provide more BASE_DIR. e.g.
0131     BASE_DIR=/my/dev/area
0132     BASE_DIR=/project/release/area
0134   OR
0136     BASE_DIR=/my/dev/area /project/release/area
0138   Files will be search in these BASE_DIRs according to the order of these
0139   BASE_DIR. So always provide your dev area first and then the release area.
0141 - COMPILER=<command to compile the c/c++ files>
0143   It is an optional key. Default value is "c++".
0145 - COMPILER_FLAGS=flags
0147   It is an optional key. Default value is "".
0148   You can provide all the include path and defines to pass to compiler to
0149   compile your file here. e.g. if your files needs qt, coin3d then you can
0150   have something like (in one line)
0152     COMPILER_FLAGS=-I/my/qt/installation/include
0153       -I/my/coin3d/installation/include
0156   NOTE: Define this key before any FILES key (see FILES key)
0158 - HEADER_EXT=<regexp>
0160   It is an optional key. Default is \.h
0161   A Perl regular expression to to check if a file is c/c++ header or not.
0163 - SOURCE_EXT=<regexp>
0165   It is an optional key. Default is \.(cc|CC|cpp|C|c|CPP|cxx|CXX)
0166   A Perl regular expression to to check if a file is c/c++ source or not.
0168 - INCLUDE_FILTER=<regexp>
0170   It is an optional key. Default is .+
0171   This filter will be used to limit the recursive checking. e.g. if your project
0172   consists of many packages (e.g. A/A1, A/A2, B/B1...) and you are only
0173   interested to check files which exists in you package A/A1 then you can have
0175     INCLUDE_FILTER=A/A1/.+
0177   Now if A/A1/ depends on A/A1/file1.h, A/A2/file3.h, B/B1/file4.h then
0178   only A/A1/ and A/A1/file1.h will be checked.
0180 - FILES=<space separated file names (relative path within any BASE_DIR)>
0182   You at least need one key like this in your config file. e.g.
0184     FILES=A/A1/ A/A1/
0186   OR
0188    FILES=A/A/
0189    FILEs/A/A1/
0191   A file will only be checked if it exists under any of the BASE_DIR.
0192   Please remember that if you want to use any COMPILER_FLAGS to compile your
0193   files then those must be defined before the FILES=<file> key. e.g. if you
0194   have something like this in your config file
0197     FILES=A/A1/ A/A1/
0198     COMPILER_FLAGS=-I/my/qt/installation/include -DMYDEFINE1
0199     FILES=B/B1/
0201   then files A/A1/ and A/A1/ will be compiled with "-DMYDEFINE1"
0202   compiler flags and file B/B1/ will be compiled with
0203   "-I/my/qt/installation/include -DMYDEFINE1" compiler flags.
0205 - SKIP_FILES=<space separated regexp (relative path within any BASE_DIR)>
0207   It is an optional key. If for some reason you want to skip a file to be
0208   checked by the include checker then add that file in here. e.g. sometime
0209   developers create header files which only export things for others to use
0210   (like common headers used by every one etc).
0212 - SKIP_INCLUDES=<space separated regexp (relative path within any BASE_DIR)>
0214   It is an optional key. This key will skip the checking of a include directive
0215   for a give file. e.g. if a file B/b.h includes files A/a1.h, A/a2.h and if you
0216   think that file A/a1.h is really needed by B/b.h then you can add the following
0217   line in the config file
0219   SKIP_INCLUDES=B/b.h:A/a1.h
0221   Now include checker will only test A/a2.h while checking for B/b.h.
0224 Config File Generation for SCRAM-Based projects:
0226   For SCRAM-based projects this config file can be generated by the
0227 script. e.g. If you are only interested to check the source
0228 available in /PROJECT/src/SubSystem/Package then just run
0230     ./ /PROJECT/src/SubSystem/Package > myconfig.txt
0232   If you are interested in whole project then do
0234     ./ /PROJECT/src > myconfig.txt
0236   After generating this config file you can edit it according to your needs e.g.
0237 you can add INCLUDE_FILTER, SKIP_FILES, SKIP_INCLUDES etc. in it.
0240 Modified by: Shahzad Muzaffar
0241 Dated: 20 July, 2005