<?xml version="1.0" ?>
<notes>
The <em>CScout</em> engine (<em>cscout</em>)
requires as an argument a processing script,
for example a <em>cswc</em>-compiled workspace definition file
or the <code>make.cs</code> script generated by <em>csmake</em>.
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 <em>CScout</em> 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.
<em>CScout</em> only checks the code to the extend needed to perform its
analysis; <em>CScout</em> will hapily process many illegal constructs.
<p>
The following lines illustrate the output of <em>CScout</em>
when run on the <code>bin</code> workspace.
<pre>
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
</pre>
After processing your files <em>CScout</em> 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 <em>CScout</em> contact is the Web browser
interface;
only fatal errors and progress indicators will appear on <em>CScout</em>'s
standard output.
Depending on the access control list specified, you may also be
able to perform some operations over the network.
However, since <em>CScout</em> operates as a single-threaded process,
you may experience delays when another user sends a complex query.

<h2>Preprocessor invocation</h2>
As an aid for configuring <em>CScout</em> for a different compiler
you can run <em>CScout</em> with the optional
<code>-E</code> command-line argument.
The <code>-E</code> option will orchestrate <em>CScout</em> 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 <em>CScout</em> will be the file with all 
preprocessor commands evaluated.
If <em>CScout</em> 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 <em>CScout</em> 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 <em>CScout</em> will not generate <code>#line</code> directives.
Alternatively, you can rerun <em>CScout</em> on the preprocessed file.

<h2>Checking invocation</h2>
There are cases where you may only want to run <em>CScout</em> to see
its error diagnostic messages.
As an example, you may be running <em>CScout</em> as part of your daily
build cycle to verify that the source code can always be parsed by
<em>CScout</em>.
The <code>-c</code> command-line option will cause <em>CScout</em> to
immediately exit after processing the specified file.
<p>
The <code>-c</code> option is often used in conjunction with the
<code>-r</code> option.
The <code>-r</code> command-line option instructs <em>CScout</em> 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.
<em>CScout</em> 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 <em>CScout</em>'s output:
<pre>
$ 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
</pre>
Notice that there are two types of unused include files:
<ol>
<li> Directly included files
<li> Included files that are only indirectly included
</ol>

You will typically remove the <code>#include</code> 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 <em>CScout</em> 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):
<fmtcode ext="c">
/* Main file main.c */
main(int argc
#include "comma.h"
char *argv[])
{
}

/* File comma.h */
,
</fmtcode>
Although such a construct is legal C it is not used in practice.
<p>
<em>CScout</em> has processed a 190KLOC project that was under
active development since 1989.
The project consisted of 231 files, containing 5249 include directives.
Following <em>CScout</em>'s analysis 765 include directives from
178 files were removed, without a single problem.
</p>
</notes>
