make.cs
script generated by csmake.
It will serially process each project and directory parsing the
corresponding files specified in the workspace definition file,
and then process once more each one of the files examined to establish
the location of the identifiers.
Note that the bulk of the work is performed in the first pass.
During the first pass CScout may report warnings, errors,
and fatal errors.
Fatal errors will terminate processing, all other errors may result in an
incorrect analysis of the particular code fragment.
CScout only checks the code to the extend needed to perform its
analysis; CScout will hapily process many illegal constructs.
The following lines illustrate the output of CScout
when run on the bin
workspace.
Entering directory /usr/src/bin Processing project cp Entering directory cp Processing file cp.c Done processing file cp.c Processing file utils.c Done processing file utils.c Exiting directory cp Done processing project cp Processing project echo Entering directory echo Processing file echo.c Done processing file echo.c Exiting directory echo Done processing project echo Processing project date Entering directory date Processing file date.c Done processing file date.c Exiting directory date Done processing project date Exiting directory /usr/src/bin Done processing workspace bin Post-processing /home/dds/src/cscout/cscout_defs.h Post-processing /home/dds/src/cscout/cscout_incs.h Post-processing /usr/home/dds/src/cscout/bin.c Post-processing /usr/include/ctype.h Post-processing /usr/include/err.h Post-processing /usr/include/errno.h Post-processing /usr/include/fcntl.h Post-processing /usr/include/fts.h Post-processing /usr/include/limits.h Post-processing /usr/include/locale.h Post-processing /usr/include/machine/ansi.h Post-processing /usr/include/machine/endian.h Post-processing /usr/include/machine/limits.h Post-processing /usr/include/machine/param.h Post-processing /usr/include/machine/signal.h Post-processing /usr/include/machine/trap.h Post-processing /usr/include/machine/types.h Post-processing /usr/include/machine/ucontext.h Post-processing /usr/include/runetype.h Post-processing /usr/include/stdio.h Post-processing /usr/include/stdlib.h Post-processing /usr/include/string.h Post-processing /usr/include/sys/_posix.h Post-processing /usr/include/sys/cdefs.h Post-processing /usr/include/sys/inttypes.h Post-processing /usr/include/sys/param.h Post-processing /usr/include/sys/signal.h Post-processing /usr/include/sys/stat.h Post-processing /usr/include/sys/syslimits.h Post-processing /usr/include/sys/time.h Post-processing /usr/include/sys/types.h Post-processing /usr/include/sys/ucontext.h Post-processing /usr/include/sys/unistd.h Post-processing /usr/include/sysexits.h Post-processing /usr/include/syslog.h Post-processing /usr/include/time.h Post-processing /usr/include/unistd.h Post-processing /vol/src/bin/cp/cp.c Post-processing /vol/src/bin/cp/extern.h Post-processing /vol/src/bin/cp/utils.c Post-processing /vol/src/bin/date/date.c Post-processing /vol/src/bin/date/extern.h Post-processing /vol/src/bin/date/vary.h Post-processing /vol/src/bin/echo/echo.c Processing identifiers 100% We are now ready to serve you at http://localhost:8081After processing your files CScout will start operating as a Web server. At that point you must open a Web browser and connect to the location printed on its output. From that point onward your CScout contact is the Web browser interface; only fatal errors and progress indicators will appear on CScout's standard output. Depending on the access control list specified, you may also be able to perform some operations over the network. However, since CScout operates as a single-threaded process, you may experience delays when another user sends a complex query.
-E
command-line argument.
The -E
option will orchestrate CScout to act as
a simple C preprocessor for the file(s) specified through a regular
expression as the option's argument.
(Typically the name of the file, and in some cases a few distinguishing
elements of its path should be enough.)
The corresponding output of CScout will be the file with all
preprocessor commands evaluated.
If CScout reports an error in a place where a macro is invoked,
you can examine the preprocessed output to see the result of the macro
execution.
During the CScout trials, this feature often located the use
of nonstandard compiler extensions, that were hidden inside header files.
To search for the corresponding error location in the postprocessed file use the
name of a nearby identifier as a bookmark, since the line numbers will not
match and CScout will not generate #line
directives.
Alternatively, you can rerun CScout on the preprocessed file.
-c
command-line option will cause CScout to
immediately exit after processing the specified file.
The -c
option is often used in conjunction with the
-r
option.
The -r
command-line option instructs CScout to
report all superfluously included header files and identifiers that are
either unused or wrongly scoped.
Although it is easy to recognise when a header file must be included
(if you do not follow the specification of the respective API,
a compiler's error message will act as a reminder)
detecting when an included header is no longer needed is a lot more difficult.
Thus, as code changes, entire files are duplicated as source code templates,
and functions are moved to different files, header files that were once
needed may no longer be required.
Their existence can confuse the programmers reading the code
(why is this header file included?) and unnecessarily burden the compilation
process.
CScout can detect such files by keeping track of dependencies across
files, and report included files that are not required.
The following is an example of CScout's output:
$ cscout -rc awk.cs Processing workspace awk Processing project awk Entering directory awk Processing file awkgram.y Done processing file awkgram.y [...] Processing file tran.c Done processing file tran.c Exiting directory awk Done processing project awk Done processing workspace awk Post-processing /home/dds/src/cscout/example/.cscout/cscout_defs.h [...] Post-processing /home/dds/src/cscout/include/time.h Processing identifiers 100% /home/dds/src/cscout/example/awk/run.c:84: jexit: unused project scoped writable identifier [...] /home/dds/src/cscout/example/awk/awkgram.y:93: LASTTOKEN: unused file scoped writable identifier /home/dds/src/cscout/example/awk/awk.h:152: CFREE: unused writable macro [...] /home/dds/src/cscout/example/awk/tran.c:44: CONVFMT: writable identifier should be made static /home/dds/src/cscout/example/awk/lib.c:36: file: writable identifier should be made static [...] /home/dds/src/cscout/example/awk/lib.c:33: unused included file /home/dds/src/cscout/example/awk/ytab.h /home/dds/src/cscout/example/awk/main.c:29: unused included file /home/dds/src/cscout/include/ctype.h /home/dds/src/cscout/example/awk/main.c:35: unused included file /home/dds/src/cscout/example/awk/ytab.h /home/dds/src/cscout/example/awk/tran.c:32: unused included file /home/dds/src/cscout/example/awk/ytab.hNotice that there are two types of unused include files:
#include
directives for the
directly included files.
The files that are indirectly included and unused are a lot more tricky.
They are brought into your file's compilation by the inclusion of another
file.
Even if you have control over the header file that included them
and even if your file has no use for their contents, another file
may require them, so in most cases it is best not to mess with those
files.
Finally note that it is possible to construct pathological examples of
include files that CScout will not detect as being required.
These will contain just parts of a statement or declaration that can not
be related to the file including them (e.g. a single operator, or a comma):
/* Main file main.c */
main(int argc
#include "comma.h"
char *argv[])
{
}
/* File comma.h */
,
Although such a construct is legal C it is not used in practice.
CScout has processed a 190KLOC project that was under active development since 1989. The project consisted of 231 files, containing 5249 include directives. Following CScout's analysis 765 include directives from 178 files were removed, without a single problem.