CScout has already been applied on
CScout as a source code analyzer can:
More importantly, CScout helps you in refactoring code by identifying dead objects to remove, and automatically performing accurate global rename identifier refactorings, and various function argument refactorings. CScout will automatically rename identifiers
make),
entering the example directory and typing
../src/build/cscout awk.cs
For a more structured walkthrough, read on.
Consider the following C file, idtest.c
#define getval(x) ((x).val)
struct number {
int id;
double val;
} n;
struct character {
int id;
char val;
} c;
static int val;
main(int argc, char *argv[])
{
int val;
if (argc > 2)
goto val;
return getval(n) + getval(c);
val: return 0;
}
val entail.
CScout will help us to automate this process.
Although, we are dealing with a single file we need to specify its processing
within the context of a workspace.
In a realistic concept a workspace will specify how numerous projects
consisting of multiple files will be processed; think of a workspace
as a collection of Makefiles.
CScout will operate across the many source files and related
executables in the same way as it operates on our example
file idtest.c.
A workspace specifies the set of files on which CScout will operate. Each workspace consists of a number of projects; a project is a set rules for linking together C files to form an executable. The workspace definition file is in our case very simple:
workspace example {
project idtest {
file idtest.c
}
}
Our workspace, named example, consists of a single
project, named idtest, that consists of a single
C source file, idtest.c.
Our first step will be to transform the declarative workspace definition file into a processing script: a file with imperative processing directives that CScout will handle.
prompt> cswc example.csw >example.cWe then invoke CScout on the processing script (the compiled workspace definition file)
example.c.
prompt> cscout example.c Processing workspace example Processing project idtest Processing file idtest.c Done processing file idtest.c Done processing project idtest Done processing workspace example Post-processing our_path/example.c Post-processing our_path/idtest.c Processing identifiers 100% We are now ready to serve you at http://localhost:8081The output of CScout is quite verbose; when processing a large source code collection, the messages will serve to assure us that progress is being made.
The primary interface of CScout is Web-based, so once our files have been processed, we fire-up our Web browser and navigate to the CScout's URL. We leave the CScout process running; its job from now on will be to service the pages we request and perform the operations we specify.
Our browser will show us a page like the following:
In our first example we will only rename an identifier, but as is evident from the page's links CScout provides us with many powerfull tools.
By navigating through the links All files, idtest.c, and Source code with identifier hyperlinks we can see the source code with each recognised identifier marked as a hyperlink:
Source Code With Identifier Hyperlinks: your_path/idtest.c(Use the tab key to move to each marked element.) #define getval(x) ((x).val)
|
Scout Main Pageval (in the macro definition)
we are taken to a page specifying the identifier's details.
There we can specify the identifier's new name, e.g. value.
Identifier: val |
val matches marked as
hyperlinks:
Identifier val: C:\dds\src\Research\cscout\refactor\idtest.c(Use the tab key to move to each marked element.) #define getval(x) ((x).val)
|
val
label, the static variable, or the local variable;
each one will only affect the relevant identifiers.
Selecting the hyperlink
Exit - saving changes from the
CScout's main page will commit our changes,
modifying the file idtest.c.
-std=c++11 flag. CScout
has been built and tested both with GCC and LLVM.
You install CScout in five steps:
cd cscoutmakemake test (optional, but highly recommended)sudo make install. If you want the installation
to use a different directory hierarchy than the default
/usr/localPREFIX variable.
For example, you run make install PREFIX=/home/mydir
to install CScout under your home directory or
sudo make install PREFIX=/usr
to install CScout under /usr.
By default the installation will create in /usr/local/include/cscout
headers corresponding to a generic standard C compilation and to your
host's specific configuration.
If you want to process programs based on other host configurations
you can modify these files or create a local version of the files
in your home or the project's current directory.
In most cases you want CScout to process your code using
the include files of the compiler you are normally using.
This will allow CScout to handle programs using the libraries
and facilities available in your environment
(e.g. Unix system calls or the Windows API).
In the other hand it exposes CScout to the extensions and quirks
that might reside in your system's header files.
You can typically reslove these problems by adding a few additional
macro definitions that neutralize unknown compiler extensions.
As an example,
if your compiler supports a quad_double type and associated
keyword with semantics roughly equivalent to double
you would add a line in host-defs.h:
#define quad_double doubleHave a look in the existing
host-defs.h file to see
what might be required.
If your programs are written in standard C and do not use any additional
include files, you can use the generic header files.
The following diagram illustrates the data flow when working with
CScout.
The thick-lined objects depict active processes;
the thin-lined objects depict data.
CScout will analyze and process C source code under the directions
of a processing script.
After some user interactions through a web browser CScout can
write out the modified source code.
CScout can also convert the C source code
into an SQL script that can be further analyzed and processesed through
an RDBMS.
There are three ways to generate the processing script:
Workspace definition files offer by far the most readable and transparent way to setup a CScout workspace. They are declarative and express exactly the operations that CScout will perform. On the other hand, they can be difficult to specify for an existing large project and they must be kept in sync with the project's build process.
Running your make process under the csmake command is a
very easy way to generate a CScout processing script.
This method however only works if the essentials of your make process
aren't too contrived.
csmake can handle builds implemented through the Unix-related
make,
gcc, ld, ar, and mv commands.
It has been successfuly tested on the Linux and FreeBSD kernels and the Apache
web server.
If csmake can deal with your project, you will be up and running
in minutes; if not, you will only have lost those few minutes.
Another advantage of the csmake method
is that csmake will obtain from
the compiler the predefined macros and the include file path.
As a result you often don't have to tailor the files
host-incs.h and host-defs.h
to match you environment;
you can directly use the supplied file gcc-defs.h,
which provides workarounds for GCC extensions.
Tailoring your project's build process to generate a CScout processing script is a final possibility. Here you gain maximum flexibility and integration with the project build system at the expense of having to modify the project's build procedure. If the project is relatively large and the build procedure is under your control, this may be an option worth investigating.
Workspace definition files are line-oriented and organized around C-like blocks. Comments are introduced using the # character. Consider the following simple example:
workspace echo {
project echo {
cd "/usr/src/bin/echo"
file echo.c
}
}
The above workspace definition consists of a single program (echo),
which in turn consists of a single source file (echo.c).
See how we could expand this for two more programs, all residing in
our system's /usr/src/bin directory:
workspace bin {
cd "/usr/src/bin"
ro_prefix "/usr/include"
project cp {
cd "cp"
file cp.c utils.c
}
project echo {
cd "echo"
file echo.c
}
project date {
cd "date"
file date.c
}
}
In the new bin workspace we have factored out the common
source directory at the workspace level
(cd "/usr/src/bin"), so that each project only
specifies its directory relatively to the workspace directory
(e.g. cd "date").
In addition, we have specified that files residing in the
directory /usr/include are to be considered read-only
(ro_prefix "/usr/include").
This is typically needed when the user running CScout
has permission to modify the system's include files.
Specifying one or more read-only prefixes allows CScout to
distinguish between application identifiers and files, which you can
modify, and system identifiers and files, which should not be changed.
The CScout workspace compiler cswc will read from its standard input, or from the file(s) specified on its command line, a workspace definition and produce on its standard output a processing script: a C-like file that CScout can process. You will have to redirect the cswc output to a file that will then get passed as an argument to CScout.
WORKSPACE:
workspace NAME { WORKSPACE_ELEMENT ... }
WORKSPACE_ELEMENT:
SCOPED_COMMAND
GLOBAL_COMMAND
cd "PATH"
PROJECT
SCOPED_COMMAND:
ipath "PATH"
define MACRO
define MACRO VALUE
GLOBAL_COMMAND:
ro_prefix "PATH"
readonly "FILENAME"
PROJECT:
project NAME { PROJECT_ELEMENT ... }
PROJECT_ELEMENT:
SCOPED_COMMAND
cd "PATH"
DIRECTORY
FILE
DIRECTORY:
directory PATH { DIRECTORY_ELEMENT ... }
DIRECTORY_ELEMENT:
SCOPED_COMMAND
FILE
FILE:
file FILENAME ...
file "FILENAME" { FILESPEC ... }
FILESPEC:
SCOPED_COMMAND
cd "PATH"
readonly
The above grammar essentially specifies that a workspace consists of
projects, which consist of files or files in a directory.
At the workspace level you can specify files and directories that are
to be considered read-only using the readonly and
ro_prefix commands.
Both commands affect the complete workspace.
The scoped commands (define and ipath)
are used to specify macro definitions and the include path.
Their scope is the block they appear in; when you exit the block
(project, directory, or file) their definition is lost.
You can therefore define a macro or an include path for the complete workspace,
a specific project, files within a directory, or a single file.
The syntax of the define command is the same as the one
used in C programs.
The cd command is also scoped; once you exit the block
you return to the directory that was in effect in the outside block.
Within a project you can either specify individual files using
the file command, or express a grouping of files in
a directory using the directory command.
The directory command's name is the directory where a
group of files resides and serves as an implicit cd
command for the files it contains.
Finally, files can be either specified directly as arguments to the
file command, or file can be used to start
a separate block.
In the latter case the argument of file is the file name
to process; the block can contain additional specifications
(scoped commands or the readonly command without an
argument) for processing that file.
The following workspace definition was used for processing the apache web server and includes most of the features and formulations we discussed.
workspace apache {
cd "/usr/local/src/apache/src"
ro_prefix "/usr/local/src/apache/src/include/ap_config"
# Global project definitions
define HTTPD_ROOT "/usr/local/apache"
define SUEXEC_BIN "/usr/local/apache/bin/suexec"
define SHARED_CORE_DIR "/usr/local/apache/libexec"
define DEFAULT_PIDLOG "logs/httpd.pid"
define DEFAULT_SCOREBOARD "logs/httpd.scoreboard"
define DEFAULT_LOCKFILE "logs/httpd.lock"
define DEFAULT_XFERLOG "logs/access_log"
define DEFAULT_ERRORLOG "logs/error_log"
define TYPES_CONFIG_FILE "conf/mime.types"
define SERVER_CONFIG_FILE "conf/httpd.conf"
define ACCESS_CONFIG_FILE "conf/access.conf"
define RESOURCE_CONFIG_FILE "conf/srm.conf"
define AUX_CFLAGS
define LINUX 22
define USE_HSREGEX
define NO_DL_NEEDED
# Give project-specific directory and include path properties
project gen_uri_delims {
cd "main"
ipath "../os/unix"
ipath "../include"
file gen_uri_delims.c
}
# Alternative formulation; specify per-file properties
project gen_test_char {
file gen_test_char.c {
cd "main"
ipath "../os/unix"
ipath "../include"
}
}
# httpd executable; specify directory-based properties
project httpd {
directory main {
ipath "../os/unix"
ipath "../include"
file alloc.c buff.c http_config.c http_core.c
file http_log.c http_main.c http_protocol.c
file http_request.c http_vhost.c util.c util_date.c
file util_script.c util_uri.c util_md5.c rfc1413.c
}
directory regex {
ipath "."
ipath "../os/unix"
ipath "../include"
define POSIX_MISTAKE
file regcomp.c regexec.c regerror.c regfree.c
}
directory os/unix {
ipath "../../os/unix"
ipath "../../include"
file os.c os-inline.c
}
directory ap {
ipath "../os/unix"
ipath "../include"
file ap_cpystrn.c ap_execve.c ap_fnmatch.c ap_getpass.c
file ap_md5c.c ap_signal.c ap_slack.c ap_snprintf.c
file ap_sha1.c ap_checkpass.c ap_base64.c ap_ebcdic.c
}
directory modules/standard {
ipath "../../os/unix"
ipath "../../include"
file mod_env.c mod_log_config.c mod_mime.c
file mod_negotiation.c mod_status.c mod_include.c
file mod_autoindex.c mod_dir.c mod_cgi.c mod_asis.c
file mod_imap.c mod_actions.c mod_userdir.c
file mod_alias.c mod_access.c mod_auth.c mod_setenvif.c
}
directory . {
ipath "./os/unix"
ipath "./include"
file modules.c buildmark.c
}
}
}
In CScout from version 2.2 and onward you can you can also use the supplied tool csmake to directly generate CScout processing scripts by monitoring a project's make-based build process. For this to work your project's build must (probably) be based on a Unix or Unix-like system, and use make and gcc. The make process can also invoke ld, ar, and mv. Recursive make invocations among different directories are also supported.
The way to use csmake is fairly simple. You first arrange for performing a full build, for example by running
make clean
Then, instead of running make on the project's top-level
directory you run csmake.
When the build process has finished, csmake will leave in
the directory where you started it a CScout processing script
named make.cs.
csmake has been used out-of-the-box to run CScout on the Linux kernel version 2.6.11.4 and the Apache httpd version 2.2.3. It has also been used to process the FreeBSD 7-CURRENT kernel under its three Tier-1 architecture configurations by cross-compiling each configuration separately and merging the resulting CScout processing scripts. This is the shell script that did the job.
for a in amd64 i386 sparc64
do
(
cd sys/$a/conf/
make LINT
config LINT
)
export MAKEOBJDIRPREFIX=/home/dds/src/fbsd-head/obj/$a
csmake buildkernel TARGET_ARCH=$a KERNCONF=LINT
mv make.cs make.$a.cs
done
cat make.*.cs >all.cs
sed -n 's/#pragma process "\(.*hack.c\)"/\1/p' all.cs | xargs touch
cscout all.cs
Finally, for processing a couple of C files, you can create a project file by invoking the cscc tool with the arguments you would pass to the C compiler.
#pragma preprocessor directives.
CScout uses the following pragmas:
#pragma echo "STRING"Example:
#pragma echo "Processing workspace date\n"
#pragma ro_prefix "STRING"Example:
#pragma ro_prefix "C:\gcc"
#pragma define_immutable macro definition#define command, but
mark the definition as one that cannot be later be undefined or redefined.
This is useful for defining macros that handle compiler extensions
so that code cannot change them.
#pragma project "STRING"Example:
#pragma project "date"
#pragma block_enterblock_enter will enter the project scope
(linkage unit); the second encountered nested
block_enter will enter the file scope
(compilation unit).
#pragma block_exitblock_enter pragmas should match the number of
block_exit pragmas and there should never be more
than two block_enter pragmas in effect.
#pragma process "STRING"Example:
#pragma process "date.d"
#pragma pushd "STRING"Example:
#pragma pushd "cp"
#pragma popd pushd pragmas should match the number of
popd pragmas.
#pragma set_dp "STRING INTEGERdbpoints file, it is enabled at a particular
code instance using the #pragma set_dp.
Example:
#pragma set_dp "macro.cpp" 486
#pragma includepath "STRING"Example:
#pragma includepath "/usr/lib/gcc-lib/i386-redhat-linux/2.96/include"
#pragma clear_include
#pragma clear_defines #define C preprocessor directive.
// workspace bin
#pragma echo "Processing workspace bin\n"
#pragma ro_prefix "/usr/include"
#pragma echo "Entering directory /usr/src/bin"
#pragma pushd "/usr/src/bin"
// project date
#pragma echo "Processing project date\n"
#pragma project "date"
#pragma block_enter
#pragma echo "Entering directory date"
#pragma pushd "date"
// file date.c
#pragma echo "Processing file date.c\n"
#pragma block_enter
#pragma clear_defines
#pragma clear_include
#include "/home/dds/src/cscout/cscout_defs.h"
#include "/home/dds/src/cscout/cscout_incs.h"
#pragma process "date.c"
#pragma block_exit
#pragma echo "Done processing file date.c\n"
#pragma echo "Exiting directory date\n"
#pragma popd
#pragma block_exit
#pragma echo "Done processing project date\n"
#pragma echo "Exiting directory /usr/src/bin\n"
#pragma popd
#pragma echo "Done processing workspace bin\n"
config LINT
make depend)
and compile
(make).
This step is used to create all automatically generated C and header files.
Also during this step note the include path used, in order to provide
CScout with the same specification.
rm *.o).
.include "$S/conf/kern.pre.mk"
The code below was added after the line above
NORMAL_C= echo '\#pragma echo "Processing file ${.IMPSRC}\n"' >>kernel.cs ;\
echo '\#pragma block_enter' >>kernel.cs ;\
echo '\#pragma clear_defines' >>kernel.cs ;\
echo '\#pragma clear_include' >>kernel.cs ;\
echo '\#include "cscout_defs.h"' >>kernel.cs ;\
for i in $(INCLUDES) ; \
do \
case $$i in \
-nostdinc) continue ;; \
-I-) continue ;; \
esac ; \
i=`echo $$i | sed 's/-I//'` ; \
echo '\#pragma includepath "'$$i'"' >>kernel.cs ; \
done ; \
echo '\#define _KERNEL 1' >>kernel.cs ;\
echo '\#pragma process "opt_global.h"' >>kernel.cs ;\
echo '\#pragma process "${.IMPSRC}"' >>kernel.cs ;\
echo '\#pragma block_exit' >>kernel.cs ;\
echo '\#pragma echo "Done processing file ${.IMPSRC}\n"' >>kernel.cs
cscout_incs.h file for each different architecture.
#pragma echo "Processing workspace FreeBSD kernel\n"
#pragma echo "Entering directory sys/i386/compile/LINT\n"
#pragma pushd "sys/i386/compile/LINT"
#pragma echo "Processing project i386\n"
#pragma project "i386"
#pragma block_enter
#include "kernel.cs"
#pragma echo "Exiting directory sys/i386/compile/LINT\n"
#pragma popd
#pragma echo "Done processing project i386\n"
#pragma block_exit
#pragma echo "Entering directory sys/amd64/compile/GENERIC\n"
// [...]
// and so on for all architectures
// [...]
#pragma echo "Exiting directory sys/sparc64/compile/LINT\n"
#pragma popd
#pragma echo "Done processing project sparc64\n"
#pragma block_exit
block_enter and
block_exit pragmas
are furnished by this top-level file.
CScout HomeFile MetricsWritable FilesNumber of files: 4310
|
When processing a project for the first time, Cscout may terminate its processing with a syntax error. The errors are typically occurring because of incompatibilities between CScout and C compiler extensions or features of a particular version of the C Standard used in the project. Here is advice for troubleshooting such errors.
include/template directory, and reinstall CScout.
Look within the existing header files for examples of how diverse
compiler extensions are handled.
If the fix is general and widely applicable, please consider
contributing it back via a GitHub pull request.
#if !defined(__CSCOUT__) conditional compilation directive.
#pragma process directive of the employed CScout
processing script.
cscout -E /path/to/file.c main.cs >file.i.
#pragma process directives for header
files, as in the example below, then the above method will not work.
#include "/usr/local/include/cscout/csmake-post-defs.h"
#pragma process "[...]/include/linux/kconfig.h"
#pragma process "[...]/init/do_mounts_rd.c"
In this case, employ the cscut command to extract from the
processing script the part associated with the offending file
(e.g. into a file named file.cs),
and then run CScout in preprocessing mode on that file:
cscout -E . file.cs >file.i
#pragma block_enter
#pragma block_enter
#pragma process "file.i"
#pragma block_exit
#pragma block_exit
cscout -P command to process only the parts
of the processing script associated with the offending file.
This will allow you to iterate through possible fixes and test them,
without waiting for CScout to process all other files.
As described above, if the processing
script contains #pragma process directives for header
files use cscut to extract the script part for the offending
file, and only process this.
cscut -e
command or by deleting the processed parts with your editor.
When modifying the processing script by hand,
be careful not to violate the project and file block nestings.
You can remove the processing of entire projects (an outward
#pragma block_enter / block_exit block) or entire
files (an inward #pragma block_enter / block_exit),
but you should never leave incomplete blocks.
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 */
,
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.
First of all, the preprocessor token concatenation feature can result in C identifiers that are composed of multiple CScout identifiers. Consider the following example, which uses a macro to define a number of different functions. (Yes, I am familiar with the C++ templates, this is just an example.)
#define typefun(name, type, op) \
type type ## _ ## name(type a, type b) { return a op b; }
typefun(add, int, +)
typefun(sub, int, -)
typefun(mul, int, *)
typefun(div, int, /)
typefun(add, double, +)
typefun(sub, double, -)
typefun(mul, double, *)
typefun(div, double, /)
main()
{
printf("%d\n", int_add(5, 4));
printf("%g\n", double_mul(3.14, 2.0));
}
int_add C identifier is
actually composed of three separate parts:
int _ add int identifier into integer
would change it in five different places: the argument to the four
typefun macro invocations, and the part of int_add.
In addition, preprocessor macro definitions can confuse the notion of the C scope, bringing together scopes that would be considered separate in the context of the C language-proper. Consider the following (slightly contrived) example:
struct foo {
int foo;
};
struct bar {
int foo;
};
#define getpart(tag, name) (((struct tag *)p)->name)
#define getfoo(var) (var.foo)
#define get(name) (name(0) + ((struct name *)p)->name)
#define conditional(x) do {if (!x(0)) goto x; return x(0);} while(0)
int
foo(void *p)
{
struct foo f;
struct bar b;
foo:
if (p && getpart(foo, foo))
return getpart(bar, foo);
else if (getfoo(f))
return get(foo);
else if (getfoo(b))
conditional(foo);
else
return 0;
}
foo is occuring in a number of different
scopes:
foo identifier,
CScout will change all the instances marked below,
in order to obtain a program that has the same meaning as the original
one.
Identifier foo: test.c(Use the tab key to move to each marked element.) struct foo {
|
#define macro() middlemacro()
#define middlemacro() innemacro()
#define innemacro() function1()
function1() {}
function2() {}
main() {
macro();
function2();
function3();
printf("Hello");
}
Note that in CScout functions are separate entities from identifiers. The name of a function can consist of multiple identifiers; an identifier can exist in more than one function names.
For instance,
the page for the _ (underscore) identifier in the
typefun macro example we saw earlier
will appear as follows.
Identifier: _CScout 2.0 - 2004/07/31 12:37:12 |
Note how each function name is composed of three separate parts,
and that this instance of the _ identifier occurs in
8 different function names.
One important feature of CScout concerning files has to do with the handling of files that are exact copies of each other. These may occur in the building of a large system for the sake of convenience; for example, one header file may be copied to various parts of the source code tree. CScout will locate identical files and group them together when reporting a file's details. Identifiers occuring in the same position of two identical files are considered equivalent; if you change the name of one of them the name of the other will also change. Moreover, when CScout reports unused identifiers it takes into account uses of an identifier from all instances of the identical files, not just one of them.
readonly and ro_prefix definitions
provided in workspace definition files)
to determine which elements of the compiled source code are under
your control and which elements are part of the development system.
Often the CScout user-interface allows you to specify whether you are
interested in writable (i.e. your project's), read-only (i.e. the system's)
or all elements.
Therefore,
all of the files that belong to your project must be writable.
Any other files used by your project but not belonging to it
(e.g. header files of third-party libraries or auto-generated code)
must either be read-only or must be flagged for treatment as
read-only using the readonly and ro_prefix
workspace definition commands.
Since CScout is not just a browser, but a refactoring browser,
you are expected to ensure that every file in your project is
writable.
This is how CScout figures out which files are part
of your project and which are system files (for instance the standard
library header files).
System files
should not be writable; if any system files happen to be writable,
use the readonly and ro_prefix workspace
definition commands to tell CScout to treat them as if
they are not writable.
File-spanning Writable IdentifiersMatching IdentifiersElements 1 to 20 of 416. |
Also note that often a query's results are split into pages. The program's options allow you to specify how many elements you want to see on each page. Keep in mind that some browsers may choke on huge pages, so keep this number down to a reasonable number (say below 1000). You can navigate between result pages using the links at the bottom of each result page page. The link titled all will present all the query's results. It is most useful as a way to save all the query's results into a file, using a browser command like Save Link Target As ...
We will examine CScout's functionality using as an
example the bin workspace we presented in the previous section.
File: C:\dds\src\Research\cscout\example\awk\main.cDetails
Listings
FunctionsFile Dependencies
Include Files
Metrics
|
You can view a file's source code in five different forms:
360 #if defined(__GNUC__) && defined(__STDC__)
|
int
|
int |
#if !defined(_ANSI_SOURCE) && !defined(_POSIX_SOURCE)
|
File MetricsWritable FilesNumber of elements: 13
Read-only FilesNumber of elements: 15
|
All Files
You can bookmark this page to save the respective query CScout 1.6 - 2003/06/04 15:14:51 |
Read-only Files
You can bookmark this page to save the respective query CScout 2.0 - 2004/07/31 12:37:12 |
Writable Files
You can bookmark this page to save the respective query CScout 1.6 - 2003/06/04 15:14:51 |
static) identifiers, but
detecting global identifiers is more tricky, since it requires
processing of all files that will be linked together.
The restriction to writable identifiers will filter-out noise
generated through the use of the system's library functions.
In our example, the following list is generated:
Files Containing Unused Project-scoped Writable IdentifiersMatching Files
You can bookmark this page to save the respective query CScout 2.0 - 2004/07/31 12:37:12 |
tab
to go to each hyperlink.
In our example the identifier will appear as follows:
|
setthetime is declared as
static, but not defined as such.)
static) unused writable identifiers.
Although some modern compilers can detect file-local
identifiers, they fail to detect macros and some types of
variable declarations.
The CScout query is more general and can be more reliable.
The restriction to writable identifiers will filter-out noise
generated through the use of the system's library functions.
In our example, the following list is generated:
Files Containing Unused File-scoped Writable IdentifiersMatching Files
You can bookmark this page to save the respective query CScout 2.0 - 2004/07/31 12:37:12 |
copyright and the rcsid
identifiers.
|
#ifdef'd out.
In our example, the result set only contains the processing script (the compiled workspace definition file).
Writable .c Files Without Any StatmentsYou can bookmark this page to save the respective query CScout 1.6 - 2003/06/04 15:14:51 |
#pragma commands)
to drive the CScout's source code analysis.
In our case the results are:
Writable Files Containing Unprocessed Lines
You can bookmark this page to save the respective query CScout 2.0 - 2004/07/31 12:37:12 |
In our case the results are:
Writable Files Containing Strings
You can bookmark this page to save the respective query CScout 1.6 - 2003/06/04 15:14:51 |
#include
invocations.
This query can be used to find files that break such a guideline.
As usual, read-only system files are excluded; these typically
use recursive #include invocations as a matter of course.
In our example, the result is:
Writable .h Files With #include directivesYou can bookmark this page to save the respective query CScout 1.6 - 2003/06/04 15:14:51 |
You specify the query through the following form:
File QueryCScout |
You start by specifying whether the file should be
writable (i.e. typically part of your application)
and/or
readable (i.e. typically part of the compiler or system).
Next come a series of metrics CScout collects for each
file.
For each metric (e.g. the number of comments) you can specify
an operator ==, !=, < or > and a number
to match that metric against.
Thus to locate files without any comments you would specify
Number of block comments == 0.
On the left of each metric you can specify whether that metric will be used to sort the resulting file list. In that case, the corresponding number will appear together with each file listed. A separate option allows you to specify that files should be sorted in the reverse order.
You can request to see files matching any of your specifications (Match any of the above) or to see files matching all your specifications (Match all of the above).
Sometimes you may only want to search in a subset of files; you can then specify a regular expression that filenames should match (or not match) against: "File names should (not) match RE".
Finally, you can also specify a title for your query. The title will then appear on the result document annotating the results, and will also provide you with a sensible name when creating a bookmark to it.
Two global options specify the format of the include graph and the content on each graph's node. Through these options you can obtain graphs in
including file -> included file
Two links on the main page
(file include graph - writable files and
file include graph - all files)
can give you the include graphs of the complete program.
For programs larger than a hundred thousand lines,
these graphs are only useful in their textual form.
In their graphical form, even with node information disabled,
they can only serve to give you a rough idea of how the program is
structured.
The following image depicts how writable (non-system) files are
included in the awk source code.
and the following is a part of the include file structure of the
Windows Research Kernel
More useful are typically the include graphs that can be generated for individual files. These can allow you to see what paths can possibly lead to the inclusion of a given file (include graph of all including files) or what files a given file includes (include graph of all included files). (call graph of all callers), which functions can be reached starting from a given function, and how functions in a given file relate to each other.
As an example, the following diagram depicts all files that
main.c includes
while the following diagrams shows all the files including
(directly or indirectly)
proto.h.
static within a file
will not interfere with identifiers outside that scope.
Thus, the following example will print 3 and not 7.
int i = 3;
foo()
{
int i = 7;
}
main()
{
foo();
printf("%d\n", i);
}
In addition, C also partitions a program's identifiers into four namespaces. Identifiers in one namespace, are also considered different from identifiers in another. The four namespaces are:
struct/union/enum
struct/union
(actually a separate namespace is assigned
to each struct/union)
id identifier instances are
different:
/* structure tag */
struct id {
int id; /* structure member */
};
/* Different structure */
struct id2 {
char id; /* structure member */
};
/* ordinary identifier */
id()
{
id: /* label */
}
Normally when you want to locate or change an identifier name, you only consider identifiers in the same scope and namespace. Sometimes however, a C preprocessor macro can semantically unite identifiers living in different namespaces, so that changes in one of them should be propagated to the others. The most common case involves macros that access structure members.
struct s1 {
int id;
} a;
struct s2 {
char id;
} b;
#define getid(x) ((x)->id)
main()
{
printf("%d %c", getid(a), getid(b));
}
id
instances should be propagated to all others for the program to
retain its original meaning.
CScout understands such changes and will propagate any changes
you specify accordingly.
Finally, the C preprocessor's token concatenation feature can result in identifiers that should be treated for substitution purposes in separate parts. Consider the following example:
int xleft, xright;
int ytop, ybottom;
#define coord(a, b) (a ## b)
main()
{
printf("%d %d %d %d\n",
coord(x, left),
coord(x, right),
coord(y, top),
coord(y, bottom));
}
x in one of the coord
macro invocations should replace the x part in the
xleft and xright variables.
Again CScout will recognize and correctly handle this code.
Identifier: copy_fileCScout 2.0 - 2004/07/31 12:37:12 |
typedef
(typedef's belong to the ``ordinary identifier'' namespace,
but are obviously important, so CScout will tag them as such).
Finally, the identifier's page will list the writable and all files
the specific identifier appears in.
Clicking on the ``marked source'' hyperlink will display the respective
file's source code with only the given identifier marked as a hyperlink.
By pressing your browser's cp.c source code
with the copy_file identifier marked
would appear as follows:
|
case S_IFBLK: case S_IFCHR: if (Rflag) { if (copy_special(curr->fts_statp, !dne)) badcp = rval = 1; } else { if (copy_file(curr, dne)) badcp = rval = 1; } break; case S_IFIFO: if (Rflag) { if (copy_fifo(curr->fts_statp, !dne)) badcp = rval = 1; } else { if (copy_file(curr, dne)) badcp = rval = 1; } break; default: if (copy_file(curr, dne)) badcp = rval = 1; break; } |
Identifier MetricsWritable Identifiers
Read-only Identifiers
CScout |
You can use these metrics to compare characteristics of different projects, adherance to coding standards, or to identify identifier classes with abnormally short or long names. The ratio between the distinct number of identifiers and the total number of identifiers is the number of times each identifier is used. Notice the difference in our case between the read-only identifiers (which are mostly declarations) and the writable identifiers (which are actually used).
File-spanning Writable IdentifiersMatching Identifiers
PATH_T You can bookmark this page to save the respective query CScout 1.6 - 2003/06/04 15:14:51 |
Unused File-scoped Writable IdentifiersMatching Identifiers
copyright You can bookmark this page to save the respective query CScout 1.6 - 2003/06/04 15:14:51 |
Unused Writable MacrosMatching IdentifiersYou can bookmark this page to save the respective query CScout 1.6 - 2003/06/04 15:14:51 |
Identifier Query |
As an example, the following query could be used to identify
unused file-scoped writable identifiers, but excluding
the copyright and rcsid identifiers:
Identifier QueryCScout 1.16 - 2003/08/17 12:13:01 |
Function: format (C function) |
From this page you can refactor the function's arguments (more on this in the next section) and obtain the following data.
static, and function-like
macros.
@N@2, @1" will
swap their order, while specifying "@1, sizeof(@1), stdin" as
the arguments for gets will refactor them in a form suitable for
calling fgets (if the original argument refers to a fixed-size character array).@.Nstdout, @1, @.2" will introduce an extra first parameter, named stdout.
(Presumably the function will also be renamed to fprintf.)@+N{...}@-N{...}@1, @2, @+3{@3}@-3{NULL}" will add to any
call to the function missing a third argument, a third argument with a
value of NULL.
Note that the refactorings will take place on all instances where the
identifier is found to match the function or macro.
This includes declarations and definitions
(which might require some hand-editing if arguments are introduced),
and the appearance of the name in the replacement
text of a macro, when that macro is used in a way that makes the function
match the one being refactored.
The replacements will not be performed to function calls that are executed
through a function pointer.
Two global options specify the format of the call graph and the content on each graph's node. Through these options you can obtain graphs in
calling function -> called function
Two links on the main page
(function and macro call graph, and non-static function call graph)
can give you the call graphs of the complete program.
For any program larger than a few thousand lines,
these graphs are only useful in their textual form.
In their graphical form, even with node information disabled,
they can only serve to give you a rough idea of how the program is
structured.
The following image depicts how the three different programs we
analyzed in the bin example relate to each other.
More useful are the call graphs that can be generated for individual functions or files. These can allow you to see what paths can possibly lead to a given function (call graph of all callers), which functions can be reached starting from a given function, the function in context, and how functions in a given file relate to each other.
As an example, the following diagram depicts all paths leading to the
setfile function.
Correspondingly, the functions that can be reached starting from the
copy_file function appears in the following diagram.
while the following shows the function setsymtab in context,
depicting all the paths leading to it (callers) and leaving from it
(called functions).
Finally, the following is an example of how the functions in a single
file (parse.c) relate to each other.
Function QueryCScout |
On the top you can specify whether each function you want listed:
As is the case in file queries,
next comes a series of metrics CScout collects for each
defined function.
For each metric (e.g. the number of comments) you can specify
an operator ==, !=, < or > and a number
to match that metric against.
Thus to locate functions containing goto statement
you would specify
Number of goto statements != 0.
On the left of each metric you can specify whether that metric will be used to sort the resulting file list. In that case, the corresponding number will appear together with each file listed. A separate option allows you to specify that files should be sorted in the reverse order.
Similarly to the identifier query, you can also specify whether the specified properties should be treated
In addition you can specify:
Global Options |
Identifier: argcCScout 2.0 - 2004/07/31 12:37:12 |
78 fa *makedfa(const char *s, int anchor) /* returns dfa for reg expr s */
|
Windows.h, WINDOWS.h, and
windows.h).
The use of the
``case-insensitive file name regular expression match''
option makes filename regular expression matches
ignore letter case thereby matching the operating system's semantics.
Read-only Files
You can bookmark this page to save the respective query |
_t.
The following list contains our example's typedefs ordered by the last
character, making it easy to distinguish typedefs not ending
in _t
|
| Graph options | bgcolor=lightblue |
| Node options | color=yellow,fontname="Helvetica",fillcolor=yellow,style=filled |
| Edge options | arrowtail=odiamond |
/home/jack/src/foo/filename.c, you could
specify that /foo/ should be changed
into /../foo.new/.
Note than when this option is specified the existing and new locations of the file must reside on the same drive and partition (under Windows) or file system (under Unix).
%s placeholders.
The first is substituted by a regular expression that is associated
with the identifier for which the file is edited,
while the second is substituted with the corresponding file name.
The default string under Unix is
xterm -c "$VISUAL +/'%s' '%s'"
echo Ignoring search for "%s" & start notepad "%s"
start C:\Progra~1\Vim\vim70\gvim.exe +/"%s" "%s"
.cscout will be created in the
current directory (if it does not already exist),
and a file named options will be written in it,
listing the options you specified.
When CScout starts-up it will attempt to load the options
file by searching in
$CSCOUT_HOME,
$HOME/.cscout, or
.cscout in the current directory.
The options file is text based and contains key-value pairs.
The order of the entries is not significant.
This is an example of an options file.
show_true: 1 show_projects: 1 show_identical_files: 1 show_line_number: 0 tab_width: 8 rename_override_ro: 1 refactor_fun_arg_override_ro: 1 file_icase: 0 entries_per_page: 20 fname_in_context: 1 sort_rev: 0 cgraph_type: s cgraph_show: n fgraph_show: n cgraph_depth: 5 fgraph_depth: 5 cgraph_dot_url: 0 sfile_re_string: sfile_repl_string: sfile_repl_string: entries_per_page: start_editor_cmd: start C:\Progra~1\Vim\vim71\gvim.exe +/"%s" "%s"
The following is an example of the identifier replacements page. You see all identifiers for which replacements have been specified. All specified replacements are originally active. If a particular replacement appears to be causing problems you can deactivate it from this page. In addition, you can change the replaced name of any of the replaced identifiers. Finally, clicking on an identifier name will lead you to the corresponding identifier page.
Identifier Replacements |
Select Active ProjectProject cp is currently selected CScout 1.6 - 2003/06/04 15:14:51 |
cscout_checkout;
after the file is modified CScout will try to execute the
command cscout_checkin.
Both commands will receive as their argument the full path name of the
respective file.
If commands with such names are in your path, they will be executed
performing whatever action you require.
As an example, for a system managed with Perforce (https://www.perforce.com/) the following commands could be used:
#!/bin/sh p4 edit $1
#!/bin/sh p4 submit -d 'CScout identifier name refactoring' $1
alignof operator can be used on types (gcc) for statement (C99)
restrict qualifier and the inline specifier (C99)
_Bool type (C99)
_Thread_local storage class specifier (C11)
_Generic generic selection expression (C11)
static and other qualifiers in array type declarations (C99)
__atribute__(__unused__) for determining which
identifiers should not be reported as unused (gcc).
// line comments (common extension)
__asm__ blocks (gcc)
enum lists ending with a comma (common extension)
struct/union members (gcc, Microsoft C)
case expression ranges (gcc).
goto targets and the label address-of operator (gcc).
__typeof keyword (gcc)
/##/ into
// are then treated as a line comment (Microsoft C)
__try __except __finally __leave keywords (Microsoft C) #include_next preprocessor directive (gcc)
#warning preprocessor directive (gcc)
long long type (common extension)
__label__) (gcc).
y' are considered
to contain yacc source and processed accordingly.
CScout processes yacc files as follows:
y.tab.h
immediately after the grammar (i.e. in the same scope) will
unify the terminal symbols with the corresponding macro definitions
throughout the program.
%union construct are defined as
members of the YYSTYPE union typedef.
These are then considered to be accessed in all
%type and the precedence specification constructs,
as well as the
explicit type specification through the $<tag># construct.
yyerrok,
YYABORT,
YYACCEPT, etc)
are defined.
Feel free to define anything required to silence CScout
as a macro in the workspace definition file.
CScout is designed to process well-formed modern-style yacc files. All rules must be terminated with a semicolon (apparently this is optional in the original yacc version). The accepted grammar appears below.
body:
defs '%%' rules tail
;
tail:
/* Empty */
| '%%' c_code
;
defs:
/* Empty */
| defs def
;
def:
'%start' IDENTIFIER
| '%union' '{' member_declaration_list '}'
| '%{' c_code '%}'
| rword name_list_declaration
;
rword:
'%token'
| '%left'
| '%right'
| '%nonassoc'
| '%type'
;
tag:
/* Empty: union tag is optional */
| '<' IDENTIFIER '>'
;
name_list_declaration:
tag name_number
| name_list_declaration opt_comma name_number
;
opt_comma:
/* Empty */
| ','
;
name_number:
name
| name INT_CONST
;
name:
IDENTIFIER
| CHAR_LITERAL
;
/* rules section */
rules:
rule
| rules rule
;
rule:
IDENTIFIER ':' rule_body_list ';'
;
rule_body_list:
rule_body
| rule_body_list '|' rule_body
;
rule_body:
id_action_list prec
;
id_action_list:
/* Empty */
| id_action_list name
| id_action_list '{' c_code '}'
;
prec:
/* Empty */
| '%prec' name
| '%prec' name '{' c_code '}'
;
variable:
'$$'
| '$' INT_CONST
| '$-' INT_CONST
{ $$ = basic(b_int); }
| '$<' IDENTIFIER '>' variable_suffix
{ $$ = $3; }
;
variable_suffix:
'$'
| INT_CONST
| '-' INT_CONST
;
Regular expressions (``REs''), as defined in IEEE Std 1003.2 (``POSIX.2''), come in two forms: modern REs (roughly those of egrep(1); 1003.2 calls these ``extended'' REs) and obsolete REs (roughly those of ed(1); 1003.2 ``basic'' REs). CScout has adopted the use of modern (extended) REs.
A (modern) RE is one= or more non-empty= branches, separated by `|'. It matches anything that matches one of the branches.
A branch is one= or more pieces, concatenated. It matches a match for the first, followed by a match for the second, etc.
A piece is an atom possibly followed by a single= `*', `+', `?', or bound. An atom followed by `*' matches a sequence of 0 or more matches of the atom. An atom followed by `+' matches a sequence of 1 or more matches of the atom. An atom followed by `?' matches a sequence of 0 or 1 matches of the atom.
A bound is `{' followed by an unsigned decimal integer, possibly followed by `,' possibly followed by another unsigned decimal integer, always fol- lowed by `}'. The integers must lie between 0 and RE_DUP_MAX (255=) inclusive, and if there are two of them, the first may not exceed the second. An atom followed by a bound containing one integer i and no comma matches a sequence of exactly i matches of the atom. An atom fol- lowed by a bound containing one integer i and a comma matches a sequence of i or more matches of the atom. An atom followed by a bound containing two integers i and j matches a sequence of i through j (inclusive) matches of the atom.
An atom is a regular expression enclosed in `()' (matching a match for the regular expression), an empty set of `()' (matching the null string)=, a bracket expression (see below), `.' (matching any single character), `^' (matching the null string at the beginning of a line), `$' (matching the null string at the end of a line), a `\' followed by one of the characters `^.[$()|*+?{\' (matching that character taken as an ordinary character), a `\' followed by any other character= (matching that character taken as an ordinary character, as if the `\' had not been present=), or a single character with no other significance (matching that character). A `{' followed by a character other than a digit is an ordinary character, not the beginning of a bound=. It is illegal to end an RE with `\'.
A bracket expression is a list of characters enclosed in `[]'. It nor- mally matches any single character from the list (but see below). If the list begins with `^', it matches any single character (but see below) not from the rest of the list. If two characters in the list are separated by `-', this is shorthand for the full range of characters between those two (inclusive) in the collating sequence, e.g. `[0-9]' in ASCII matches any decimal digit. It is illegal= for two ranges to share an endpoint, e.g. `a-c-e'. Ranges are very collating-sequence-dependent, and portable programs should avoid relying on them.
To include a literal `]' in the list, make it the first character (fol- lowing a possible `^'). To include a literal `-', make it the first or last character, or the second endpoint of a range. To use a literal `-' as the first endpoint of a range, enclose it in `[.' and `.]' to make it a collating element (see below). With the exception of these and some combinations using `[' (see next paragraphs), all other special charac- ters, including `\', lose their special significance within a bracket expression.
Within a bracket expression, a collating element (a character, a multi- character sequence that collates as if it were a single character, or a collating-sequence name for either) enclosed in `[.' and `.]' stands for the sequence of characters of that collating element. The sequence is a single element of the bracket expression's list. A bracket expression containing a multi-character collating element can thus match more than one character, e.g. if the collating sequence includes a `ch' collating element, then the RE `[[.ch.]]*c' matches the first five characters of `chchcc'.
Within a bracket expression, a collating element enclosed in `[=' and `=]' is an equivalence class, standing for the sequences of characters of all collating elements equivalent to that one, including itself. (If there are no other equivalent collating elements, the treatment is as if the enclosing delimiters were `[.' and `.]'.) For example, if `x' and `y' are the members of an equivalence class, then `[[=x=]]', `[[=y=]]', and `[xy]' are all synonymous. An equivalence class may not= be an end- point of a range.
Within a bracket expression, the name of a character class enclosed in `[:' and `:]' stands for the list of all characters belonging to that class. Standard character class names are:
alnum digit punct alpha graph space blank lower upper cntrl print xdigitThese stand for the character classes defined in ctype(3). A locale may provide others. A character class may not be used as an endpoint of a range.
There are two special cases= of bracket expressions: the bracket expres- sions `[[:<:]]' and `[[:>:]]' match the null string at the beginning and end of a word respectively. A word is defined as a sequence of word characters which is neither preceded nor followed by word characters. A word character is an alnum character (as defined by ctype(3)) or an underscore. This is an extension, compatible with but not specified by IEEE Std 1003.2 (``POSIX.2''), and should be used with caution in soft- ware intended to be portable to other systems.
In the event that an RE could match more than one substring of a given string, the RE matches the one starting earliest in the string. If the RE could match more than one substring starting at that point, it matches the longest. Subexpressions also match the longest possible substrings, subject to the constraint that the whole match be as long as possible, with subexpressions starting earlier in the RE taking priority over ones starting later. Note that higher-level subexpressions thus take priority over their lower-level component subexpressions.
Match lengths are measured in characters, not collating elements. A null string is considered longer than no match at all. For example, `bb*' matches the three middle characters of `abbbc', `(wee|week)(knights|nights)' matches all ten characters of `weeknights', when `(.*).*' is matched against `abc' the parenthesized subexpression matches all three characters, and when `(a*)*' is matched against `bc' both the whole RE and the parenthesized subexpression match the null string.
If case-independent matching is specified, the effect is much as if all case distinctions had vanished from the alphabet. When an alphabetic that exists in multiple cases appears as an ordinary character outside a bracket expression, it is effectively transformed into a bracket expres- sion containing both cases, e.g. `x' becomes `[xX]'. When it appears inside a bracket expression, all case counterparts of it are added to the bracket expression, so that (e.g.) `[x]' becomes `[xX]' and `[^x]' becomes `[^xX]'.
To allow other hosts to connect CScout features an access control list.
The list is specified in a file called acl which
should be located in
$CSCOUT_HOME,
$HOME/.cscout, or
.cscout in the current directory.
The list contains lines with IP numeric addresses prefixed by an
A (allow)
or
D (deny)
prefix and a space.
Matching is performed by comparing a substring of a machine's IP address
against the specified access rule.
Thus an entry such as
A 128.135.11.can be used to allow access from a whole subnet. Unfortunatelly allowing access from the IP address
192.168.1.1 will
also allow access
192.168.1.10, 192.168.1.100, and so on.
Allow and deny entries cannot be combined in a useful manner
since the rules followed are:
printf)
unchanged.
Finally, run CScout with the switch -o.
For each writable workspace file CScout will create a file ending
in .obf that will contain the obfuscated version of its
contents.
The files are not overwritten, providing you with another countermeasure
against accidentally destroying them.
To overwrite the original source with the obfuscated one,
use the following Unix command:
find . -name '*.obf' |
sed 's/\\/\//g;s/\(.*\)\.obf$/mv "\1.obf" "\1"/' |
sh
-s dialect,
where the argument specifies the SQL dialect (for example,
mysql, or postgresql).
The SQL script will appear in CScout's standard output,
allowing you to directly pipe the results into the database's
client.
For example, say the database you would want to create for your project
was called myproj.
rm -f myproj.db
cscout -s sqlite myproj.cs | sqlite3 myproj.db
(
echo "create database myproj; use myproj ;"
cscout -s mysql myproj.cs
) | mysql
createdb -U username myproj
cscout -s postgres myproj.cs | psql -U username myproj
cscout -s hsqldb myproj.cs |
java -classpath $HSQLDBHOME/lib/hsqldb/hsqldb.jar org.hsqldb.util.SqlTool --rcfile $HSQLDBHOME/lib/hsqldb/sqltool.rc mem -
-- Details of interdependant identifiers appearing in the workspace
CREATE TABLE IDS(
EID BIGINT PRIMARY KEY, -- Unique identifier key
NAME CHARACTER VARYING, -- Identifier name
READONLY BOOLEAN, -- True if it appears in at least one read-only file
UNDEFMACRO BOOLEAN, -- True if it is apparantly an undefined macro
MACRO BOOLEAN, -- True if it a preprocessor macro
FUNMACRO BOOLEAN, -- True if it a preprocessor function-like macro
MACROARG BOOLEAN, -- True if it a preprocessor macro argument
CPPCONST BOOLEAN, -- True if used in a preprocessor constant
CPPSTRVAL BOOLEAN, -- True if macro value is used as a preprocessor string operand
DEFCCONSTVAL BOOLEAN, -- True if macro value defined as a C compile time constant
NOTDEFCCONSTVAL BOOLEAN, -- True if macro value defined as not a C compile time constant
EXPCCONSTVAL BOOLEAN, -- True if macro value expanded as a C compile time constant
NOTEXPCCONSTVAL BOOLEAN, -- True if macro value expanded as not a C compile time constant
ORDINARY BOOLEAN, -- True if it is an ordinary identifier (variable or function)
SUETAG BOOLEAN, -- True if it is a structure, union, or enumeration tag
SUMEMBER BOOLEAN, -- True if it is a structure or union member
LABEL BOOLEAN, -- True if it is a label
TYPEDEF BOOLEAN, -- True if it is a typedef
ENUM BOOLEAN, -- True if it is an enumeration member
YACC BOOLEAN, -- True if it is a yacc identifier
FUN BOOLEAN, -- True if it is a function name
CSCOPE BOOLEAN, -- True if its scope is a compilation unit
LSCOPE BOOLEAN, -- True if it has linkage scope
UNUSED BOOLEAN -- True if it is not used
);
-- File details
CREATE TABLE FILES(
FID INTEGER PRIMARY KEY, -- Unique file key
NAME CHARACTER VARYING, -- File name
RO BOOLEAN -- True if the file is read-only
);
-- File metrics
CREATE TABLE FILEMETRICS(
FID INTEGER, -- File key
PRECPP BOOLEAN, -- True for values before the cpp false for values after it
NCHAR INTEGER, -- Number of characters
NCCOMMENT INTEGER, -- Number of comment characters
NSPACE INTEGER, -- Number of space characters
NLCOMMENT INTEGER, -- Number of line comments
NBCOMMENT INTEGER, -- Number of block comments
NLINE INTEGER, -- Number of lines
MAXLINELEN INTEGER, -- Maximum number of characters in a line
MAXSTMTLEN INTEGER, -- Maximum number of tokens in a statement
MAXSTMTNEST INTEGER, -- Maximum level of statement nesting
MAXBRACENEST INTEGER, -- Maximum level of brace nesting
MAXBRACKNEST INTEGER, -- Maximum level of bracket nesting
BRACENEST INTEGER, -- Dangling brace nesting
BRACKNEST INTEGER, -- Dangling bracket nesting
NULINE INTEGER, -- Number of unprocessed lines
NPPDIRECTIVE INTEGER, -- Number of C preprocessor directives
NPPCOND INTEGER, -- Number of processed C preprocessor conditionals (ifdef, if, elif)
NPPFMACRO INTEGER, -- Number of defined C preprocessor function-like macros
NPPOMACRO INTEGER, -- Number of defined C preprocessor object-like macros
NTOKEN INTEGER, -- Number of tokens
NSTMT INTEGER, -- Number of statements or declarations
NOP INTEGER, -- Number of operators
NUOP INTEGER, -- Number of unique operators
NNCONST INTEGER, -- Number of numeric constants
NCLIT INTEGER, -- Number of character literals
NSTRING INTEGER, -- Number of character strings
NPPCONCATOP INTEGER, -- Number of token concatenation operators (##)
NPPSTRINGOP INTEGER, -- Number of token stringification operators (#)
NIF INTEGER, -- Number of if statements
NELSE INTEGER, -- Number of else clauses
NSWITCH INTEGER, -- Number of switch statements
NCASE INTEGER, -- Number of case labels
NDEFAULT INTEGER, -- Number of default labels
NBREAK INTEGER, -- Number of break statements
NFOR INTEGER, -- Number of for statements
NWHILE INTEGER, -- Number of while statements
NDO INTEGER, -- Number of do statements
NCONTINUE INTEGER, -- Number of continue statements
NGOTO INTEGER, -- Number of goto statements
NRETURN INTEGER, -- Number of return statements
NASM INTEGER, -- Number of assembly statements
NTYPEOF INTEGER, -- Number of typeof operators
NPID INTEGER, -- Number of project-scope identifiers
NFID INTEGER, -- Number of file-scope (static) identifiers
NMID INTEGER, -- Number of macro identifiers
NID INTEGER, -- Total number of object and object-like identifiers
NUPID INTEGER, -- Number of unique project-scope identifiers
NUFID INTEGER, -- Number of unique file-scope (static) identifiers
NUMID INTEGER, -- Number of unique macro identifiers
NUID INTEGER, -- Number of unique object and object-like identifiers
NLABEL INTEGER, -- Number of goto labels
NMACROEXPANDTOKEN INTEGER, -- Tokens added by macro expansion
NCOPIES INTEGER, -- Number of copies of the file
NINCFILE INTEGER, -- Number of directly included files
NPFUNCTION INTEGER, -- Number of defined project-scope functions
NFFUNCTION INTEGER, -- Number of defined file-scope (static) functions
NPVAR INTEGER, -- Number of defined project-scope variables
NFVAR INTEGER, -- Number of defined file-scope (static) variables
NAGGREGATE INTEGER, -- Number of complete aggregate (struct/union) declarations
NAMEMBER INTEGER, -- Number of declared aggregate (struct/union) members
NENUM INTEGER, -- Number of complete enumeration declarations
NEMEMBER INTEGER, -- Number of declared enumeration elements
PRIMARY KEY(FID, PRECPP),
FOREIGN KEY(FID) REFERENCES FILES(FID)
);
-- Instances of identifier tokens within the source code
CREATE TABLE TOKENS(
FID INTEGER, -- File key
FOFFSET INTEGER, -- Offset within the file
EID BIGINT, -- Identifier key
PRIMARY KEY(FID, FOFFSET),
FOREIGN KEY(FID) REFERENCES FILES(FID),
FOREIGN KEY(EID) REFERENCES IDS(EID)
);
-- Comments in the code
CREATE TABLE COMMENTS(
FID INTEGER, -- File key
FOFFSET INTEGER, -- Offset within the file
COMMENT CHARACTER VARYING, -- The comment, including its delimiters
PRIMARY KEY(FID, FOFFSET),
FOREIGN KEY(FID) REFERENCES FILES(FID)
);
-- Strings in the code
CREATE TABLE STRINGS(
FID INTEGER, -- File key
FOFFSET INTEGER, -- Offset within the file
STRING CHARACTER VARYING, -- The string, including its delimiters
PRIMARY KEY(FID, FOFFSET),
FOREIGN KEY(FID) REFERENCES FILES(FID)
);
-- Remaining, non-identifier source code
CREATE TABLE REST(
FID INTEGER, -- File key
FOFFSET INTEGER, -- Offset within the file
CODE CHARACTER VARYING, -- The actual code
PRIMARY KEY(FID, FOFFSET),
FOREIGN KEY(FID) REFERENCES FILES(FID)
);
-- Line number offsets within each file
CREATE TABLE LINEPOS(
FID INTEGER, -- File key
FOFFSET INTEGER, -- Offset within the file
LNUM INTEGER, -- Line number (starts at 1)
PRIMARY KEY(FID, FOFFSET),
FOREIGN KEY(FID) REFERENCES FILES(FID)
);
-- Project details
CREATE TABLE PROJECTS(
PID INTEGER PRIMARY KEY, -- Unique project key
NAME CHARACTER VARYING -- Project name
);
-- Identifiers appearing in projects
CREATE TABLE IDPROJ(
EID BIGINT, -- Identifier key
PID INTEGER, -- Project key
FOREIGN KEY(EID) REFERENCES IDS(EID),
FOREIGN KEY(PID) REFERENCES PROJECTS(PID)
);
-- Files used in projects
CREATE TABLE FILEPROJ(
FID INTEGER, -- File key
PID INTEGER, -- Project key
FOREIGN KEY(FID) REFERENCES FILES(FID),
FOREIGN KEY(PID) REFERENCES PROJECTS(PID)
);
-- Foreign keys for the following four tables are not specified, because it is
-- difficult to satisfy integrity constraints: files (esp. their metrics,
-- esp. ncopies) can't be written until the end of processing, while
-- to conserve space, these tables are written after each file is processed.
-- Alternatively, inserts to these tables could be wrapped into
-- SET REFERENTIAL_INTEGRITY { TRUE | FALSE } calls.
-- Included files defining required elements for a given compilation unit and project
CREATE TABLE DEFINERS(
PID INTEGER, -- Project key
CUID INTEGER, -- Compilation unit key
BASEFILEID INTEGER, -- File (often .c) requiring (using) a definition
DEFINERID INTEGER -- File (often .h) providing a definition
-- FOREIGN KEY(PID) REFERENCES PROJECTS(PID),
-- FOREIGN KEY(CUID) REFERENCES FILES(FID),
-- FOREIGN KEY(BASEFILEID) REFERENCES FILES(FID),
-- FOREIGN KEY(DEFINERID) REFERENCES FILES(FID)
);
-- Included files including files for a given compilation unit and project
CREATE TABLE INCLUDERS(
PID INTEGER, -- Project key
CUID INTEGER, -- Compilation unit key
BASEFILEID INTEGER, -- File included in the compilation
INCLUDERID INTEGER -- Files that include it
-- FOREIGN KEY(PID) REFERENCES PROJECTS(PID),
-- FOREIGN KEY(CUID) REFERENCES FILES(FID),
-- FOREIGN KEY(BASEFILEID) REFERENCES FILES(FID),
-- FOREIGN KEY(INCLUDERID) REFERENCES FILES(FID)
);
-- Included files providing code or data for a given compilation unit and project
CREATE TABLE PROVIDERS(
PID INTEGER, -- Project key
CUID INTEGER, -- Compilation unit key
PROVIDERID INTEGER -- Included file
-- FOREIGN KEY(PID) REFERENCES PROJECTS(PID),
-- FOREIGN KEY(CUID) REFERENCES FILES(FID),
-- FOREIGN KEY(PROVIDERID) REFERENCES FILES(FID)
);
-- Tokens requiring file inclusion for a given compilation unit and project
CREATE TABLE INCTRIGGERS(
PID INTEGER, -- Project key
CUID INTEGER, -- Compilation unit key
BASEFILEID INTEGER, -- File requiring a definition
DEFINERID INTEGER, -- File providing a definition
FOFFSET INTEGER, -- Definition's offset within the providing file
LEN INTEGER -- Token's length
-- FOREIGN KEY(PID) REFERENCES PROJECTS(PID),
-- FOREIGN KEY(CUID) REFERENCES FILES(FID),
-- FOREIGN KEY(BASEFILEID) REFERENCES FILES(FID),
-- FOREIGN KEY(DEFINERID) REFERENCES FILES(FID)
);
-- C functions and function-like macros
CREATE TABLE FUNCTIONS(
ID BIGINT PRIMARY KEY, -- Unique function identifier
NAME CHARACTER VARYING, -- Function name (redundant; see FUNCTIONID)
ISMACRO BOOLEAN, -- True if a function-like macro (otherwise a C function)
DEFINED BOOLEAN, -- True if the function is defined within the workspace
DECLARED BOOLEAN, -- True if the function is declared within the workspace
FILESCOPED BOOLEAN, -- True if the function's scope is a single compilation unit (static or macro)
FID INTEGER, -- File key of the function's definition, declaration, or use
FOFFSET INTEGER, -- Offset of definition, declaration, or use within the file
FANIN INTEGER, -- Fan-in (number of callers)
FOREIGN KEY(FID) REFERENCES FILES(FID)
);
-- Details of defined functions and macros
CREATE TABLE FUNCTIONDEFS(
FUNCTIONID BIGINT PRIMARY KEY, -- Function identifier key
FIDBEGIN INTEGER, -- File key of the function's definition begin
FOFFSETBEGIN INTEGER, -- Offset of definition begin within the file
FIDEND INTEGER, -- File key of the function's definition end
FOFFSETEND INTEGER, -- Offset of definition end within the file
FOREIGN KEY(FUNCTIONID) REFERENCES FUNCTIONS(ID)
);
-- Metrics of defined functions and macros
CREATE TABLE FUNCTIONMETRICS(
FUNCTIONID BIGINT, -- Function identifier key
PRECPP BOOLEAN, -- True for values before the cpp false for values after it
NCHAR INTEGER, -- Number of characters
NCCOMMENT INTEGER, -- Number of comment characters
NSPACE INTEGER, -- Number of space characters
NLCOMMENT INTEGER, -- Number of line comments
NBCOMMENT INTEGER, -- Number of block comments
NLINE INTEGER, -- Number of lines
MAXLINELEN INTEGER, -- Maximum number of characters in a line
MAXSTMTLEN INTEGER, -- Maximum number of tokens in a statement
MAXSTMTNEST INTEGER, -- Maximum level of statement nesting
MAXBRACENEST INTEGER, -- Maximum level of brace nesting
MAXBRACKNEST INTEGER, -- Maximum level of bracket nesting
BRACENEST INTEGER, -- Dangling brace nesting
BRACKNEST INTEGER, -- Dangling bracket nesting
NULINE INTEGER, -- Number of unprocessed lines
NPPDIRECTIVE INTEGER, -- Number of C preprocessor directives
NPPCOND INTEGER, -- Number of processed C preprocessor conditionals (ifdef, if, elif)
NPPFMACRO INTEGER, -- Number of defined C preprocessor function-like macros
NPPOMACRO INTEGER, -- Number of defined C preprocessor object-like macros
NTOKEN INTEGER, -- Number of tokens
NSTMT INTEGER, -- Number of statements or declarations
NOP INTEGER, -- Number of operators
NUOP INTEGER, -- Number of unique operators
NNCONST INTEGER, -- Number of numeric constants
NCLIT INTEGER, -- Number of character literals
NSTRING INTEGER, -- Number of character strings
NPPCONCATOP INTEGER, -- Number of token concatenation operators (##)
NPPSTRINGOP INTEGER, -- Number of token stringification operators (#)
NIF INTEGER, -- Number of if statements
NELSE INTEGER, -- Number of else clauses
NSWITCH INTEGER, -- Number of switch statements
NCASE INTEGER, -- Number of case labels
NDEFAULT INTEGER, -- Number of default labels
NBREAK INTEGER, -- Number of break statements
NFOR INTEGER, -- Number of for statements
NWHILE INTEGER, -- Number of while statements
NDO INTEGER, -- Number of do statements
NCONTINUE INTEGER, -- Number of continue statements
NGOTO INTEGER, -- Number of goto statements
NRETURN INTEGER, -- Number of return statements
NASM INTEGER, -- Number of assembly statements
NTYPEOF INTEGER, -- Number of typeof operators
NPID INTEGER, -- Number of project-scope identifiers
NFID INTEGER, -- Number of file-scope (static) identifiers
NMID INTEGER, -- Number of macro identifiers
NID INTEGER, -- Total number of object and object-like identifiers
NUPID INTEGER, -- Number of unique project-scope identifiers
NUFID INTEGER, -- Number of unique file-scope (static) identifiers
NUMID INTEGER, -- Number of unique macro identifiers
NUID INTEGER, -- Number of unique object and object-like identifiers
NLABEL INTEGER, -- Number of goto labels
NMACROEXPANDTOKEN INTEGER, -- Tokens added by macro expansion
NGNSOC INTEGER, -- Number of global namespace occupants at function's top
NMPARAM INTEGER, -- Number of parameters (for macros)
NFPARAM INTEGER, -- Number of parameters (for functions)
NEPARAM INTEGER, -- Number of passed non-expression macro parameters
FANIN INTEGER, -- Fan-in (number of calling functions)
FANOUT INTEGER, -- Fan-out (number of called functions)
CCYCL1 INTEGER, -- Cyclomatic complexity (control statements)
CCYCL2 INTEGER, -- Extended cyclomatic complexity (includes branching operators)
CCYCL3 INTEGER, -- Maximum cyclomatic complexity (includes branching operators and all switch branches)
CSTRUC REAL, -- Structure complexity (Henry and Kafura)
CHAL REAL, -- Halstead volume
IFLOW REAL, -- Information flow metric (Henry and Selig)
PRIMARY KEY(FUNCTIONID, PRECPP),
FOREIGN KEY(FUNCTIONID) REFERENCES FUNCTIONS(ID)
);
-- Identifiers comprising a function's name
CREATE TABLE FUNCTIONID(
FUNCTIONID BIGINT, -- Function identifier key
ORDINAL INTEGER, -- Position of the identifier within the function name (0-based)
EID BIGINT, -- Identifier key
PRIMARY KEY(FUNCTIONID, ORDINAL),
FOREIGN KEY(FUNCTIONID) REFERENCES FUNCTIONS(ID),
FOREIGN KEY(EID) REFERENCES IDS(EID)
);
-- Function calls
CREATE TABLE FCALLS(
SOURCEID BIGINT, -- Calling function identifier key
DESTID BIGINT, -- Called function identifier key
FOREIGN KEY(SOURCEID) REFERENCES FUNCTIONS(ID),
FOREIGN KEY(DESTID) REFERENCES FUNCTIONS(ID)
);
-- Files occuring in more than one copy
CREATE TABLE FILECOPIES(
GROUPID INTEGER, -- File group identifier
FID INTEGER, -- Key of file belonging to a group of identical files
PRIMARY KEY(GROUPID, FID),
FOREIGN KEY(FID) REFERENCES FILES(FID)
);
CREATE INDEX IF NOT EXISTS idx_tokens_eid ON tokens(eid);
CREATE INDEX IF NOT EXISTS idx_tokens_fid_idx on tokens(fid);
CREATE INDEX IF NOT EXISTS idx_fcalls_destid ON fcalls(destid);
CREATE INDEX IF NOT EXISTS idx_fcalls_sourceid ON fcalls(sourceid);
CREATE INDEX IF NOT EXISTS idx_functiondefs_functionid ON functiondefs(functionid);
CREATE INDEX IF NOT EXISTS idx_ids_name ON ids(name);
CREATE INDEX IF NOT EXISTS idx_ids_name ON ids(eid);
CREATE INDEX IF NOT EXISTS idx_includers_cuid ON includers(cuid);
CREATE INDEX IF NOT EXISTS idx_includers_includerid ON includers(includerid);
SELECT name FROM ids WHERE ids.typedef ORDER BY name;
SELECT name, Count(*) AS cf FROM (
SELECT fid, tokens.eid, Count(*) AS c
FROM tokens
GROUP BY eid, fid
) AS cl
INNER JOIN ids ON cl.eid = ids.eid
GROUP BY ids.eid, ids.name
HAVING cf > 1
ORDER BY cf DESC, name;
SELECT ids.name AS iname, files.name AS fname, Count(*) AS c
FROM tokens
INNER JOIN ids ON ids.eid = tokens.eid
INNER JOIN files ON tokens.fid = files.fid
GROUP BY ids.eid, tokens.fid
HAVING c >= 10
ORDER BY c DESC, ids.name, files.name;
SELECT name, Count(*) AS c FROM tokens
INNER JOIN ids ON ids.eid = tokens.eid
GROUP BY ids.eid
HAVING c >= 10
ORDER BY c DESC, name;
SELECT ids.name, projects.name
FROM ids
INNER JOIN idproj ON ids.eid = idproj.eid
INNER JOIN projects ON idproj.pid = projects.pid
WHERE ids.name = 'main'
ORDER BY ids.name;
SELECT
projects.name AS projname,
cufiles.name AS cuname,
basefiles.name AS basename,
definefiles.name AS defname
FROM definers
INNER join projects ON definers.pid = projects.pid
INNER JOIN files AS cufiles ON definers.cuid=cufiles.fid
INNER JOIN files AS basefiles ON definers.basefileid=basefiles.fid
INNER JOIN files AS definefiles ON definers.definerid = definefiles.fid;
SELECT
min(ids.name) as identifier,
min(filesb.name) as defined,
min(filesa.name) as used
FROM definers
INNER JOIN tokens AS tokensa ON definers.basefileid = tokensa.fid
INNER JOIN tokens AS tokensb ON definers.definerid = tokensb.fid
INNER JOIN ids ON ids.eid = tokensa.eid
INNER JOIN files as filesa ON tokensa.fid = filesa.fid
INNER JOIN files as filesb ON tokensb.fid = filesb.fid
WHERE tokensa.eid = tokensb.eid
GROUP BY tokensa.eid, definerid, basefileid
ORDER BY defined, identifier, used;
SELECT source.name AS CallingFunction, dest.name AS CalledFunction
FROM fcalls
INNER JOIN functions AS source ON fcalls.sourceid = source.id
INNER JOIN functions AS dest ON fcalls.destid = dest.id
ORDER BY CallingFunction, CalledFunction;
SELECT Sum(nppdirective) FROM filemetrics
WHERE precpp
AND fid != (SELECT fid FROM files WHERE name LIKE '%.cs');
CREATE INDEX IF NOT EXISTS idx_tokens_eid ON tokens(eid);
CREATE INDEX IF NOT EXISTS idx_functiondefs_functionid ON functiondefs(functionid);
CREATE INDEX IF NOT EXISTS idx_fcalls_destid ON fcalls(destid);
CREATE INDEX IF NOT EXISTS idx_fcalls_sourceid ON fcalls(sourceid);
-- Macros that use local variables
WITH scoped_confused_macros AS (
SELECT DISTINCT macrodefs.functionid
FROM functiondefs AS macrodefs
INNER JOIN functions ON functions.id = macrodefs.functionid
AND functions.ismacro
-- Obtain macro's tokens
INNER JOIN tokens AS macrotokens ON macrotokens.fid = macrodefs.fidbegin
AND macrotokens.fid = macrodefs.fidend
AND macrotokens.foffset >= macrodefs.foffsetbegin
AND macrotokens.foffset < macrodefs.foffsetend
-- See those that are local objects or labels
INNER JOIN ids ON ids.eid = macrotokens.eid
AND ids.ordinary
AND NOT (ids.macro OR ids.macroarg OR ids.suetag OR ids.sumember OR ids.typedef OR ids.enum)
AND NOT ids.cscope
AND NOT ids.lscope
INNER JOIN files ON macrodefs.fidbegin = files.fid
-- For macros that get called by C code
WHERE EXISTS (
SELECT 1
FROM fcalls
WHERE fcalls.destid = macrodefs.functionid
AND EXISTS (
SELECT 1
FROM functions AS cfunctions
WHERE
fcalls.sourceid = cfunctions.id
AND cfunctions.defined
AND NOT cfunctions.ismacro
)
-- And tokens that also appear in the C function body
AND EXISTS (
SELECT 1
FROM functiondefs AS cdefs
INNER JOIN tokens AS ctokens ON ctokens.eid = macrotokens.eid
WHERE
fcalls.sourceid = cdefs.functionid
AND (cdefs.fidbegin != macrodefs.fidbegin
OR cdefs.foffsetbegin > macrodefs.foffsetbegin)
AND ctokens.fid = cdefs.fidend
AND ctokens.foffset >= cdefs.foffsetbegin
AND ctokens.foffset < cdefs.foffsetend
)
)
)
SELECT Count(*) FROM
functions
INNER JOIN filemetrics ON filemetrics.fid = functions.fid AND filemetrics.precpp
INNER JOIN functionmetrics AS fnmet ON functions.id = fnmet.functionid AND fnmet.precpp
WHERE ismacro
AND filemetrics.fid != (SELECT fid FROM files WHERE name LIKE '%.cs')
AND (
fnmet.fanin = 0
OR fnmet.bracenest != 0
OR fnmet.bracknest != 0
OR fnmet.nppstringop > 0
OR fnmet.nppconcatop > 0
OR fnmet.neparam > 0
-- Control flow problems
OR (
-- Callable macro, rather than macro defining a function
fnmet.fanin > 0
AND ((fnmet.ngoto > 0 AND fnmet.nlabel = 0)
OR (fnmet.nreturn > 1 AND fnmet.ndo = 1))
)
OR EXISTS (
SELECT 1
FROM scoped_confused_macros AS scm
WHERE scm.functionid = fnmet.functionid
)
)
;
The data stored in the database allow the exact reconstitution of the original source code. All that is required is to run an appropriate query and filter its results to recreate the original line breaks from irs output. Elements modified in the database, such as identifier names or comment contents, will be correctly mirrored in the generated output.
The following is the required SQL query for the SQLite database
to reconstitute the contents of the file with
file identifier (fid) 4.
.print "Starting dump"
SELECT s FROM (
SELECT name AS s, foffset
FROM ids
INNER JOIN tokens ON ids.eid = tokens.eid
WHERE fid = 4
UNION SELECT code AS s, foffset FROM rest WHERE fid = 4
UNION SELECT comment AS s, foffset FROM comments WHERE fid = 4
UNION SELECT string AS s, foffset FROM strings WHERE fid = 4
)
ORDER BY foffset;
The query's output needs to be pipped to the following commands to adjust it as needed.
# Remove header and footer lines
sed -e '1,/^Starting dump/d;/^[0-9][0-9]* rows/d' |
# Remove line breaks added by the database engine
tr -d '\n\r' |
# Add line breaks appearing in the database output as Unicode escapes
perl -pe 's/\\u0000d\\u0000a/\n/g;s/\\u0000a/\n/g' >test/chunk/$NAME
while (a)
if (b)
c();
do .. while form.
See note 3.
if (a) {
...
} else if (b) {
...
} else if (c) {
...
} else
...
}
else clauses.
Thus the above code will be given a nesting level of 1,
rather than 3, which is implied by the following
(actual) reading of the code.
if (a) {
...
} else
if (b) {
...
} else
if (c) {
...
} else
...
}
switch statements, this metric
measures the complexity of a switch statement as 1.
case label as a separate node.
#define x(if, while, else) (if + while + else)
#define WHILE(x) while(x) {
#define WEND }
WHILE (x)
foo();
WEND
Some programs have parts of them compiled under conditional preprocessor directives. Consider the following example:
#ifdef unix
#include <unistd.h>
#define erase_file(x) unlink(x)
#endif
#ifdef WIN32
#include <windows.h>
#define erase_file(x) DeleteFile(x)
#endif
main(int argc, char *argv[])
{
erase_file(argv[1]);
}
erase_file occurs three times
within the file.
However, because CScout preprocesses the file following the
C preprocessor semantics, it will typically match only two instances.
In some cases you can get around this problem by defining macros that will
ensure that all code inside conditional directives gets processed.
In other cases this will result in errors (e.g. a duplicate macro definition
in the above example).
In such cases you can include in your workspace the same project multiple
times, each time with a different set of defined macros.
workspace example {
project idtest {
define DEBUG 1
define TEST 1
file idtest.c util.c
}
project idtest2 {
define NDEBUG 1
define PRODUCTION
file idtest.c util.c
}
Consider the following example:
struct s1 {
int id;
} a;
struct s2 {
char id;
} b;
struct s3 {
double id;
} c;
#define getid(x) ((x)->id)
main()
{
printf("%d %c", getid(a), getid(b));
}
id instance should
also change the other three instances.
However, CScout will not associate the member of
s3 with the identifier appearing in the getid
macro or the
s1 or s2 structures,
because there is no getid macro invocation to link them together.
If e.g. id is replaced with val
the program will compile and function correctly,
but when one tries to access the c struture's member
in the future using getid an error will result.
struct s1 {
int val;
} a;
struct s2 {
char val;
} b;
struct s3 {
double id;
} c;
#define getid(x) ((x)->val)
main()
{
printf("%d %c", getid(a), getid(b)); /* OK */
printf(" %g", getid(c)); /* New statement: error */
}
#ifdef CSCOUT
(void)getid(d)
#endif
We employ a heuristic classifying all instances of an undefined macro
as being the same identifier.
Thus in the following sequence foo will match all
three macro instances:
#undef foo
#ifdef foo
#endif
#ifdef foo
#endif
#define foo 1
In addition, the analysis of functions can be confused by the following situations.
Finally, because function argument refactoring works at a higher level thann simple identifiers, the following limitations hold.
#ifdef argument is not an identifier#ifdef
directive is not a legal identifier.Application of macro " ... ": operator # only valid before macro parameters# was not followed
by a macro parameter.Assuming declaration int ... (...)Duplicate (different) macro definition of macro ...Empty character literalIllegal combination of sign specifiersunsigned signed).Processing automatically generated file; #line directive ignored.#line
directive was found.
This signifies that the source file is automatically
generated and refactoring changes on that file may
be lost in the future.
References to the original source file are ignored.Sign specification on non-integral type - ignoredUndeclared identifier in typeof expression: ...typeof
has not been declared.Undeclared identifier: ...#pragma pushd: unable to get current directory: ...getcwd failed while
processing the
#pragma pushd
CScout-specific directive.EOF in commentError count exceeds 100; exiting ...Invalid C token: '$'Unable to get path of file ...Unable to stat file ...#pragma echo: string expected#pragma echo
CScout-specific directive was not followed by a
string.#pragma includepath: string expected#pragma includepath
CScout-specific directive was not followed by a
string.#pragma process: string expected#pragma process
CScout-specific directive was not followed by a
string.#pragma project: string expected#pragma project
CScout-specific directive was not followed by a
string.#pragma pushd: string expected#pragma pushd
CScout-specific directive was not followed by a
string.#pragma readonly: string expected#pragma readonly
CScout-specific directive was not followed by a
string.#pragma ro_prefix: string expected#pragma ro_prefix
CScout-specific directive was not followed by a
string.% not followed by yacc keyword%union does not have a member ...Application of macro " ... ": operator # at end of macro pattern#.Array not an abstract typeAt most one storage class can be specifiedConflicting declarations for identifier ...Declared parameter does not appear in old-style function parameter list: ...Division by zero in #if expression#if expression
divided by zero.Duplicate definition of identifier ...Duplicate definition of tag ...EOF while processing #if directive#if
block reached the end of file, without a
corresponding
#endif /
#else /
#elif directive.Empty #include directive#include
directive was not followed by a filename specification.End of file in character literalEnd of file in string literalExplicit element tag without no %union in effectIllegal characters in hex escape sequence\x continued with a non-hexadecimal
character.Illegal combination of type specifiersdouble char).Illegal pointer dereferenceInvalid #include syntax#include
directive was not followed by a legal filename specification.Invalid application of basic type, storage class, or type specifierInvalid character escape sequence\c can not be
recognised.Invalid macro name#define or
#undef
directive is not a valid identifier.Invalid macro parameter name#define
directive is not a valid identifier.Invalid macro parameter punctuation#define macro
definition are not separated
by commas.Invalid preprocessor directiveInvalid type specificationLabel ... already definedgoto label is defined more
than once in a given function.Macro [ ... ]: EOF while reading function macro argumentsMacro [ ... ]: close bracket expected for function-like macroMember access in incomplete struct/union: ...Missing close bracket in defined operatordefined operator was not
followed by a closing bracket.Modulo division by zero in #if expression#if expression
divided by zero in a modulo
expression.Multiple storage classes in type declarationNo identifier following defined operatordefined operator was not followed
by an identifier.Object is not a functionOnly struct/union anonymous elements allowedstruct {int x, y;})
can only be structures or unions.
(GCC/Microsoft C extension).Pointer not an abstract typePopd: directory stack empty#pragma popd
CScout-specific directive was performed on an
empty directory stack.Structure or union does not have a member .... or
-> operator
does not have as a member the
identifier appearing on the
operator's right.Subscript not on array or pointer[]
operator is not an array or a pointer.Syntax error in preprocessor expression#if or
#elif expression was syntactically
incorrect.Unable to open include file ...Unbalanced #elif#elif
directive was found without a corresponding
#if.Unbalanced #else#else
directive was found without a corresponding
#if.Unbalanced #endif#endif
directive was found without a corresponding
#if.Undefined label ...goto
label used within a function was never defined.Unexpected end in character escape sequence\c) was not
completed; no character follows the backslash.Unknown preprocessor directive: ...Unkown %union element tag ...Yacc $value out of rangeCScout is distributed as open source software under the GNU General Public License, which is reproduced below. Other licensing options and professional support are available on request.
Version 3, 29 June 2007
Copyright © 2007 Free Software Foundation, Inc. <http://fsf.org/ (http://fsf.org/)>
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The GNU General Public License is a free, copyleft license for software and other kinds of works.
The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.
Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.
Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and modification follow.
“This License” refers to version 3 of the GNU General Public License.
“Copyright” also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.
“The Program” refers to any copyrightable work licensed under this License. Each licensee is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.
To “modify” a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a “modified version” of the earlier work or a work “based on” the earlier work.
A “covered work” means either the unmodified Program or a work based on the Program.
To “propagate” a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.
To “convey” a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.
The “source code” for a work means the preferred form of the work for making modifications to it. “Object code” means any non-source form of a work.
A “Standard Interface” means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.
The “System Libraries” of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Component”, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.
The “Corresponding Source” for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.
The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.
The Corresponding Source for a work in source code form is that same work.
All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.
When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures.
You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.
You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:
A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.
You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:
A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.
A “User Product” is either (1) a “consumer product”, which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, “normally used” refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.
“Installation Information” for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.
If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).
The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.
“Additional permissions” are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:
All other non-permissive additional terms are considered “further restrictions” within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.
You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.
You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.
Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.
An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.
A “contributor” is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's “contributor version”.
A contributor's “essential patent claims” are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control” includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.
In the following three paragraphs, a “patent license” is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To “grant” such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.
If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. “Knowingly relying” means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.
A patent license is “discriminatory” if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.
If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.
Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.
The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.
If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program.
Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
#define __declspec(x)If the problem isn't obvious from the source code, you might need preprocess the file by using the
-E option,
and look at the preprocessed code.
To do this search in the preprocessed code for an (ideally unique)
occurrence of non-macro code near the problem spot.
ro_prefix and ipath
pragmas under a Windows platform, respect the following rules.
Option (or Alt) Tab, instead of
Tab.
You can also permanently change Safari's behavior under
Safari - Preferences - Advanced.
cscc - CScout C compiler front end
cscc [gcc(1) options]
cscc is a wrapper around gcc. commands. When invoked instead of gcc, it will compile the specified file(s) in the same way as gcc would do. As a side-effect it will monitor the invocation of gcc(1) and record its environment and arguments. With those data it will generate a CScout project specification that can be used to process the file(s) that were compiled. The project specification is saved into a file named make.cs.
The following commands are often the only ones required to process a few C files.
cscc example.c cscout make.cs
If you want to use cscc with another C compiler, prepend CC=compiler-name to the cscc invocation, as shown in the following example.
CC=x86_64-w64-gcc cscc
cscout(1), csmake(1)
(C) Copyright 2006-2019 Diomidis Spinellis.
cscout - C code analyzer and refactoring browser
cscout [-bCcrv3] [-d D] [-E file specification] [-d H] [-l log file] [-p port] [-R specification] [-m specification] [-t sname] [-o | -S db | -s db | -M files] file
CScout is a source code analyzer and refactoring browser for collections of C programs. It can process workspaces of multiple projects (we define a project as a collection of C source files that are linked together) mapping the complexity introduced by the C preprocessor back into the original C source code files. CScout takes advantage of modern hardware advances (fast processors and large memory capacities) to analyze C source code beyond the level of detail and accuracy provided by current compilers and linkers. The analysis CScout performs takes into account the identifier scopes introduced by the C preprocessor and the C language proper scopes and namespaces.
CScout as a source code analyzer can:
|
• |
annotate source code with hyperlinks to each identifier | ||
|
• |
list files that would be affected by changing a specific identifier | ||
|
• |
determine whether a given identifier belongs to the application or to an external library based on the accessibility and location of the header files that declare or define it | ||
|
• |
locate unused identifiers taking into account inter-project dependencies | ||
|
• |
perform queries for identifiers based on their namespace, scope, reachability, and regular expressions of their name and the filename(s) they are found in, | ||
|
• |
perform queries for files, based on their metrics, or properties of the identifiers they contain | ||
|
• |
monitor and report superfluously included header files | ||
|
• |
provide accurate metrics on identifiers and files |
More importantly, CScout helps you in refactoring code by identifying dead objects to remove, and can automatically perform accurate global rename identifier refactorings. CScout will automatically rename identifiers
|
• |
taking into account the namespace of each identifier: a renaming of a structure tag, member, or a statement label will not affect variables with the same name | ||
|
• |
respecting the scope of the renamed identifier: a rename can affect multiple files, or variables within a single block, exactly matching the semantics the C compiler would enforce | ||
|
• |
across multiple projects when the same identifier is defined in common shared include files | ||
|
• |
occuring in macro bodies and parts of other identifiers, when these are created through the C preprocessor’s token concatenation feature |
This manual page describes the CScout invocation and command-line options. Details about its web interface, setup, and configuration can be found in the online hypertext documentation and at the project’s home page http://www.spinellis.gr/cscout.
|
-C |
Create a ctags-compatible tags file. Tens of editors and other tools can utilize tags to help you navigate through the code. In contrast to other tag generation tools, the file that CScout creates also includes information about entities dynamically generated through macros. | ||
|
-c |
Exit immediately after processing the specified files. Useful, when you simply want to check the source code for errors or when you want to create a tags file. | ||
|
-d D |
Display the #define directives being processed on the standard output. | ||
|
-d H |
Display the (mainly header) files being included on the standard output. Each line is prefixed by a number of dots indicating the depth of the included file stack. |
-E file specification
Preprocess the file specified with the regular expression given as the option’s argument and send the result to the standard output.
-p port
The web server will listen for requests on the TCP port number specified. By default the CScout server will listen at port 8081. The port number must be in the range 1024-32767.
-m specification
Specify the type of identifiers that CScout will monitor. The identifier attribute specification is given using the syntax: Y|L|E|T[:attr1][:attr2]... The meaning of the first letter is:
|
Y: |
Match anY of the specified attributes |
|||
|
L: |
Match alL of the specified attributes |
|||
|
E: |
ExcludE the specified attributes matched |
|||
|
T: |
ExacT match of the specified attributes |
Allowable attribute names and their corresponding meanings are:
unused:
Unused identifier
writable:
Writable identifier
|
ro: |
Read-only identifier |
idmtoken:
Identifier stored in a macro
funmacro:
Defined as a function-like macro
cppconst:
Used to derive a preprocessor constant, i.e. used in a #if or #include directive or in a defined() expression
cppstrval:
Macro’s value is used as a string (pasting or stringization) in the preprocessor
defcconst:
Macro value seen as a C compile-time constant
defnotcconst:
Macro value seen as not a C compile-time constant
expcconst:
Macro value seen as a C compile-time constant
expnotcconst:
Macro value seen as not a C compile-time constant
|
tag: |
Tag for a struct/union/enum |
member:
Member of a struct/union
|
label: |
Label | ||
|
obj: |
Ordinary identifier (note that enumeration constants and typedefs belong to the ordinary identifier namespace) | ||
|
macro: |
Preprocessor macro |
umacro:
Undefined preprocessor macro
macroarg:
Preprocessor macro argument
fscope:
Identifier with file scope
pscope:
Identifier with project scope
typedef:
Typedef
enumconst:
Enumeration constant
|
yacc: |
Yacc identifier |
function:
C function
The -m flag can provide enormous savings on the memory CScout uses (specify e.g. -m Y:pscope to only track project-global identifiers), but the processing CScout performs under this flag is unsound. The flag should therefore be used only if you are running short of memory. There are cases where the use of preprocessor macros can change the attributes of a given identifier shared between different files. Since the -m optimization is performed after each single file is processed, the locations where an identifier is found may be misrepresented.
|
-r |
Report on the standard error output warnings about unused and wrongly scoped identifiers and unused included files. The error message format is compatible with gcc and can therefore be automatically processed by editors that recognize this format. | ||
|
-v |
Display the CScout version and copyright information and exit. | ||
|
-3 |
Implement support for trigraph characters. | ||
|
-b |
Operate in multiuser browse-only mode. In this mode the web server can concurrently process multiple requests. All web operations that can affect the server’s functioning (such as setting the various options, renaming identifiers, refactoring function arguments, selecting a project, editing a file, or terminating the server) are prohibited. Call graphs are truncated to 1000 elements (nodes or edges). |
-S database dialect
Output the database schema as an SQL script. Specify help as the database dialect to obtain a list of supported database back-ends.
-s database dialect
Dump the workspace contents as an SQL script. Specify help as the database dialect to obtain a list of supported database back-ends.
-M files
Merge the specified eclasses, ids, and functionids files that contain token, id, and functionid, details into new records saved in three further corresponding files. These can be directly imported into the tokens, ids, and functionids tables.
-l log file
Specify the location of a file where web requests will be logged.
-R specification
Generate call graphs and exit. The option can be specified multiple times. The specification is the type of desired graph (fgraph.txt for a file dependency graph or cgraph.txt for a function and macro call graph), optionally followed by parameters appearing in the corresponding URL of the CScout web interface. The generated text file contains one space-delimited relationship per line. It can be further processed by tools such sas awk and dot to produce graphical output as shown in the following examples.
# Create a function call graph and a compile-time file dependency graph
cscout -R cgraph.txt -R fgraph.txt?gtype=C.
# Convert the generated call graph into an SVG diagram
awk ’
BEGIN { print "digraph G {" }
{print $1 "->" $2}
END { print "}" }’ cgraph.txt |
dot -Tsvg >cgraph.svg
-t name
Generate SQL output for the named table. By default SQL output for all tables is generated. If this option is provided, then output only for the specified tables will be generated. It is the user’s responsibility to list the tables required to avoid breaking integrity constraints. The option can be specified multiple times.
|
-o |
Create obfuscated versions of all the writable files of the workspace. |
Assume you want to analyze three programs in /usr/src/bin. You first create the following project definition file, bin.prj.
# Some small tools from the src/bin directory
workspace bin {
ro_prefix "/usr/include"
cd "/usr/src/bin"
project cp {
cd "cp"
file cp.c utils.c
}
project echo {
cd "echo"
file echo.c
}
project date {
cd "date"
file date.c
}
}
Then you compile the workspace file bin.prj by running the CScout workspace compiler cswc on it, and finally you run cscout on the compiled workspace file. At that point you are ready to analyze your code and rename its identifiers through your web browser.
$ cswc bin.prj >bin.cs $ cscout bin.cs Processing workspace bin 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 /usr/home/dds/src/cscout/bin.c [...] 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
cscc(1), cscut(1), csmake(1), csreconst(1), cssplit(1), cswc(1).
(c) Copyright 2003-2024 Diomidis Spinellis.
cscut - Extract portions of a CScout processing script
cscut [-b] [-e] [-F file-list | -f file | -p project] cscout-file
The cscut command-line tool extracts specific portions of a CScout processing script. It provides a flexible way to select parts of the CScout processing script based on files or projects.
The following options are available:
|
-b |
Output from the file’s beginning until the specified point. |
|||
|
-e |
Output from the specified point to the end of the file. |
-F file-list
Output a script to process only the files specified in file-list, where file-list is a file containing a list of filenames.
-f file
Output a script to process only the specified file.
-p project
Output a script to process only the specified project.
The last argument, cscout-file, specifies the CScout processing script to be processed.
Below are some typical use cases for cscut.
Extract a script to process the file x86.cs:
cscut -f /home/dds/src/linux/arch/x86/kvm/x86.c make.cs >x86.cs
Extract a script to process the files listed in file-list.txt:
cscut -F file-list.txt make.cs >files.cs
Extract a script to process only the project .tmp_vmlinux3:
cscut -p /home/dds/src/linux/.tmp_vmlinux3 >linux.cs
Extract a script to process from the file export.c and onward:
cscut -f /home/dds/src/linux/fs/ocfs2/export.c linux.cs >ocfs2-export.cs
cscout(1), cssplit(1), csmake(1)
(C) Copyright 2024 Diomidis Spinellis.
csmake - CScout make
csmake [ [-d] [-h] [-k] [-o output-file] [-s cs-files-directory] [-A] [-T temporary-directory] [-t time-file] [-N rules-file] -- ] [make(1) options]
csmake is a wrapper around make and typical C compilation commands. When invoked instead of make on a clean (unbuilt) system, it will build the system in the same way as make. As a side-effect it will monitor the invocations of cc(1), gcc(1), clang(1), ar(1), ld(1), and mv(1) commands and record their environment and arguments. With those data it will generate a CScout project specification that can be used to process the project that was compiled. The project specification is saved into a file named make.cs. Moreover, a separate CScout .cs file can be generated for each executable in a specified cs_files_directory.
To allow csmake to be used as a drop in replacement in build sequences that execute multiple make commands, you can create a /tmp/csmake-spy, which will be used to create rules for the superset of all make-generated executables.
csmake options can be passed through CSMAKEFLAGS environment variable.
|
-d |
Run in debug mode (it also keeps spy directory in place). |
|||
|
-h |
Print help message. |
|||
|
-k |
Keep temporary directory in place. |
-o output-file
Specify the name of the generated specification file, which is by default make.cs . A name of - will output the file on the standard output.
-s cs-files-directory
Create a separate CScout .cs file for each real executable. Save the .cs files into cs-files-directory in the current directory.
|
-A |
Generate cs projects for static libraries. |
-N rules-file
Run on an existing rules file.
-T temporary-directory
Set temporary directory. Use temporary-directory as temporary directory, remember to clear it if you use it multiple times.
-t time-file
Record C compiler timing information in the specified file. The information recorded is the output of time(1) with format ’%D %e %F %I %K %M %O %S %U.
The following commands are often the only ones required to process a typical C project.
make clean csmake cscout make.cs
If you want to use csmake with another C compiler, prepend CC=compiler-name to the csmake invocation, as shown in the following example.
CC=x86_64-w64-gcc csmake
The following commands create an inspectable rules file, and then use that to creat the final make.cs file. (Note the obligatory -- sequence used to terminate the csmake arguments.)
mkdir csmake-tmp csmake -k -T csmake-tmp -- csmake -N csmake-tmp/rules --
The following commands can be used to run csmake for a Debian package using the dpkg-buildpackage command.
rm -rf tmp_dir && mkdir -p tmp_dir CSMAKEFLAGS=’-T tmp_dir -A -s cscout_projects -k --’ \ MAKE=/usr/local/bin/csmake dpkg-buildpackage -b
cscout(1), cscut(1), cssplit(1).
(C) Copyright 2006-2024 Diomidis Spinellis.
csreconst - Test the reconstitution of files from a CScout database
csreconst
-t [-ckqs] database.db
csreconst -f file [-o] [-b
line] [-e line] ...
database.db
csreconst is a utility for testing the reconstitution of files stored in a CScout database or reconstituting specific files.
The program provides two modes of operation:
|
-t |
Test the reconstitution of all files in the specified SQLite database.db. Additional options can be specified to refine the behavior of the testing: | ||
|
-c |
Count the number of correct and incorrect files. | ||
|
-k |
Keep comparing after finding a difference. | ||
|
-q |
Run a quick diff without listing the full differences. | ||
|
-s |
Provide a summary of each file’s reconstitution result. |
-f
Reconstitute a specified file stored in SQLite
database.db. Additional options allow fine-grained
control of the reconstitution:
-b line
Reconstitute starting from the specified beginning line number.
-e line
Reconstitute up to the specified ending line number.
|
-o |
Prefix each reconstituted part with its file offset value. |
Test all files in a CScout database and provide a summary:
csreconst -tckqs result.db
Reconstitute the file main.c from a CScout database:
csreconst -f main.c result.db
Reconstitute file main.c from line 10 to line 50, listing the offset of each part:
csreconst -f main.c -b 10 -e 50 -o result.db
The exit code indicates the result of the comparison operation:
|
0 |
All files compare equal (no differences found). | ||
|
1 |
Differences were found between the reconstituted and original files. |
cscout(1), csmake(1)
(C) Copyright 2024 Diomidis Spinellis.
cssplit - Split a CScout processing script into smaller scripts
cssplit N
The cssplit command-line program is a filter that splits a CScout processing script into N smaller scripts for parallel or distributed processing. Each output script is named using a zero-padded sequence, starting with file-0001.cs.
The input is read from the standard input, and the output files are written to the current working directory.
This tool is useful for distributing the workload of a large CScout analysis across multiple scripts for efficiency or manageability.
|
N |
The number of output scripts to generate. The input processing script is divided into N approximately equal parts. |
Each output script contains the appropriate subset of the input commands to ensure no loss of information during the split. Currently cssplit supports only processing scripts containing a single project.
To split an input processing script into 4 smaller scripts:
cssplit 4 <make.cs
This will create the following files in the current directory:
file-0001.cs file-0002.cs file-0003.cs file-0004.cs
Each file contains a portion of the original processing script.
cscout(1), cscut(1), csmake(1)
(C) Copyright 2024 Diomidis Spinellis.
cswc - CScout workspace compiler
cswc [-gv] [-d directory] [file]
cswc is a workspace compiler for the CScout C source code analyzer and refactoring browser. CScout integrates in a single process the functionality of a multi-project build engine, an ANSI C preprocessor, and the parts of a C compiler up to and including the semantic analysis based on types. The build engine functionality is required to allow the user to process multiple compilation and link units as a single batch. Only thus can CScout detect dependencies across different files and projects. Each compilation unit can reside in a different directory and can require processing using different macro definitions or a different include file path. In a normal build process these options are typically specified in a Makefile. The CScout operation is similarly guided by a declarative workspace definition file. To decouple the complexity of the CScout workspace processing specification from its actual operation, and to encouriage experimentation with alternative (e.g. IDE-based) workspace specification mechanisms, CScout is guided by a very simple imperative script typically generated from more sophisticated workspace definitions by cswc, the CScout workspace compiler.
This manual page describes the cswc invocation and command-line options. Details about its input and output formats, setup, and configuration can be found in the online hypertext documentation and at the project’s home page http://www.spinellis.gr/cscout.
-d directory
Specify the directory to use for locating the CScout configuration files.
|
-g |
Compile the project as generic rather than host-specific C code. This means that the generated files will include CScout’s standard-C include and macro definition files (stdc-incs.h and stdc-defs.h), rather than the host-specific ones (host-incs.h and host-defs.h). | ||
|
-v |
Display the cswc version and copyright information and exit. |
The following is a configuration file used for processing the apache web server.
workspace apache {
cd "/usr/local/src/apache/src"
ro_prefix "/usr/local/src/apache/src/include/ap_config"
# Global project definitions
define HTTPD_ROOT "/usr/local/apache"
define SUEXEC_BIN "/usr/local/apache/bin/suexec"
define SHARED_CORE_DIR "/usr/local/apache/libexec"
define DEFAULT_PIDLOG "logs/httpd.pid"
define DEFAULT_SCOREBOARD "logs/httpd.scoreboard"
define DEFAULT_LOCKFILE "logs/httpd.lock"
define DEFAULT_XFERLOG "logs/access_log"
define DEFAULT_ERRORLOG "logs/error_log"
define TYPES_CONFIG_FILE "conf/mime.types"
define SERVER_CONFIG_FILE "conf/httpd.conf"
define ACCESS_CONFIG_FILE "conf/access.conf"
define RESOURCE_CONFIG_FILE "conf/srm.conf"
define AUX_CFLAGS
define LINUX 22
define USE_HSREGEX
define NO_DL_NEEDED
# Give project-specific directory and include path properties
project gen_uri_delims {
cd "main"
ipath "../os/unix"
ipath "../include"
file gen_uri_delims.c
}
# Alternative formulation; specify per-file properties
project gen_test_char {
file gen_test_char.c {
cd "main"
ipath "../os/unix"
ipath "../include"
}
}
# httpd executable; specify directory-based properties
project httpd {
directory main {
ipath "../os/unix"
ipath "../include"
file alloc.c buff.c http_config.c http_core.c
file http_log.c http_main.c http_protocol.c
file http_request.c http_vhost.c util.c util_date.c
file util_script.c util_uri.c util_md5.c rfc1413.c
}
directory regex {
ipath "."
ipath "../os/unix"
ipath "../include"
define POSIX_MISTAKE
file regcomp.c regexec.c regerror.c regfree.c
}
directory os/unix {
ipath "../../os/unix"
ipath "../../include"
file os.c os-inline.c
}
directory ap {
ipath "../os/unix"
ipath "../include"
file ap_cpystrn.c ap_execve.c ap_fnmatch.c ap_getpass.c
file ap_md5c.c ap_signal.c ap_slack.c ap_snprintf.c
file ap_sha1.c ap_checkpass.c ap_base64.c ap_ebcdic.c
}
directory modules/standard {
ipath "../../os/unix"
ipath "../../include"
file mod_env.c mod_log_config.c mod_mime.c
file mod_negotiation.c mod_status.c mod_include.c
file mod_autoindex.c mod_dir.c mod_cgi.c mod_asis.c
file mod_imap.c mod_actions.c mod_userdir.c
file mod_alias.c mod_access.c mod_auth.c mod_setenvif.c
}
directory . {
ipath "./os/unix"
ipath "./include"
file modules.c buildmark.c
}
}
}
cscout(1)
(C) Copyright 2003 Diomidis Spinellis.
-C option will create a ctags compatible
tags file, which many editors can use to navigate through the code.-d D option will dump on the standard output
the #define directives that get processed.-d H option will dump on the standard output
the (mostly header) files getting included.y.tab.h macros.include_next
preprocessor directive with those of gcc.include_next gcc-specific directive now
works correctly, even when preceded in its file by other include
directives.
__alignof__ gcc extension now also supports expressions,
in addition to types.typedef followed a structure
initializer.else block are now correctly
handled.-r option. goto labels (gcc extension).__typeof__ declarations to be preceded by type qualifiers. __typeof__ of objects with a storage class within typedef declarations. alignof operator (gcc extension)__typeof can also have as its argument a type name index[array] construct.__inline and __restrict__.__builtin_expect function. typedefs involving a
__typeof construct._Bool data type.restrict and inline keywords.typedefed pointers and arrays to be further
qualified with e.g. const or volatile.
Problem reported by Walter Briscoe.__typeof can have as its argument an expression
and not only an identifier.case expression ranges (gcc extension).__atribute__(__unused__) for determining which
identifiers should not be reported as unused (gcc extension).-m T option.)__builtin_va_copy in the provided
definition files.main() in the example definition
files.__label__) (gcc extension).#if and #elif directives expand macros
before processing the defined operator.__asm__ declaration can be used instead of a function's body (gcc).__asm__ extension with a single operand-p command-line option to specify the web server port