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 (Shahzad.Muzaffar@cern.ch)
0003 Northeastern University, Boston, USA
0004
0005 What is Include Checker:
0006
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
0009
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
0019
0020 Your code should not have any compilation errors and each file should be
0021 self parsed.
0022
0023 This script assumes that a .cc file always needs its own .h. e.g. A.cc will
0024 always need A.h.
0025
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 codestats.pl and to run it you have to first run includechecker.pl and
0029 save its output in a log file then run codestats.pl of that log file. e.g.
0030 > includechecker.pl ... > mylog.txt
0031 > codestats.pl --log mylog.txt
0032
0033 How does it work:
0034
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.
0048
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.
0058
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.
0065
0066 How to run:
0067
0068 Here are the command line options you can use
0069
0070 --config <file>
0071
0072 Please see "How to create a config file" section
0073
0074 --recursive
0075
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).
0079
0080 --keep <num>
0081
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.
0087
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.
0099
0100 --tmpdir <dir>
0101
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.
0109
0110 --detail
0111
0112 It will prints more detail messages of include checker. e.g. why include
0113 checker thinks a included file is needed etc.
0114
0115 --help
0116
0117 To see the include checker help message.
0118
0119 How to create a config file:
0120
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
0125
0126 - BASE_DIR=<space separated list of base directories>
0127
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.
0130
0131 BASE_DIR=/my/dev/area
0132 BASE_DIR=/project/release/area
0133
0134 OR
0135
0136 BASE_DIR=/my/dev/area /project/release/area
0137
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.
0140
0141 - COMPILER=<command to compile the c/c++ files>
0142
0143 It is an optional key. Default value is "c++".
0144
0145 - COMPILER_FLAGS=flags
0146
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)
0151
0152 COMPILER_FLAGS=-I/my/qt/installation/include
0153 -I/my/coin3d/installation/include
0154 -DMYDEFINE -DMYDEFINE2
0155
0156 NOTE: Define this key before any FILES key (see FILES key)
0157
0158 - HEADER_EXT=<regexp>
0159
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.
0162
0163 - SOURCE_EXT=<regexp>
0164
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.
0167
0168 - INCLUDE_FILTER=<regexp>
0169
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
0174
0175 INCLUDE_FILTER=A/A1/.+
0176
0177 Now if A/A1/file1.cc depends on A/A1/file1.h, A/A2/file3.h, B/B1/file4.h then
0178 only A/A1/file1.cc and A/A1/file1.h will be checked.
0179
0180 - FILES=<space separated file names (relative path within any BASE_DIR)>
0181
0182 You at least need one key like this in your config file. e.g.
0183
0184 FILES=A/A1/file1.cc A/A1/file2.cc
0185
0186 OR
0187
0188 FILES=A/A/file1.cc
0189 FILEs/A/A1/file2.cc
0190
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
0195
0196 COMPILER_FLAGS=-DMYDEFINE1
0197 FILES=A/A1/file1.cc A/A1/file2.cc
0198 COMPILER_FLAGS=-I/my/qt/installation/include -DMYDEFINE1
0199 FILES=B/B1/file4.cc
0200
0201 then files A/A1/file1.cc and A/A1/file2.cc will be compiled with "-DMYDEFINE1"
0202 compiler flags and file B/B1/file4.cc will be compiled with
0203 "-I/my/qt/installation/include -DMYDEFINE1" compiler flags.
0204
0205 - SKIP_FILES=<space separated regexp (relative path within any BASE_DIR)>
0206
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).
0211
0212 - SKIP_INCLUDES=<space separated regexp (relative path within any BASE_DIR)>
0213
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
0218
0219 SKIP_INCLUDES=B/b.h:A/a1.h
0220
0221 Now include checker will only test A/a2.h while checking for B/b.h.
0222
0223
0224 Config File Generation for SCRAM-Based projects:
0225
0226 For SCRAM-based projects this config file can be generated by the
0227 createconfig.pl script. e.g. If you are only interested to check the source
0228 available in /PROJECT/src/SubSystem/Package then just run
0229
0230 ./createconfig.pl /PROJECT/src/SubSystem/Package > myconfig.txt
0231
0232 If you are interested in whole project then do
0233
0234 ./createconfig.pl /PROJECT/src > myconfig.txt
0235
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.
0238
0239
0240 Modified by: Shahzad Muzaffar
0241 Dated: 20 July, 2005
