# CScout Execution

The CScout engine (cscout) requires as an argument a processing script, for example a cswc-compiled workspace definition file or the `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:8081

After 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 version of CScout you have, 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.

When CScout processes a large project it will contact our server over the Web to say hello. The unsupported version will also send us the identifier and file metrics of the project it has processed and register your CScout project for public browsing over the Web (the unsupported version is licensed only for use on free open-source software).

## Preprocessor invocation

As an aid for configuring CScout for a different compiler you can run CScout and the workspace compiler with the optional `-E` command-line argument. The `-E` option will orchestrate both programs to act as a simple C preprocessor. The workspace definition file you should use in such a case should only specify a single file. 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.

## Checking invocation

There are cases where you may only want to run CScout to see its error diagnostic messages. As an example, you may be running CScout as part of your daily build cycle to verify that the source code can always be parsed by CScout. The `-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.h

Notice that there are two types of unused include files:

1. Directly included files
2. Included files that are only indirectly included

You will typically remove the `#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.

Recently CScout processed a 190KLOC project that is under active development since 1989. The project consists of 231 files, containing 5249 include directives. Following CScout's analysis 765 include directives from 178 files were removed, without a single problem.

Contents | « Previous Next (Basic Concepts) »