You’ve installed pycdep and obviously now you want to use it. The way pycdep works is as follows:
Run the following command
python pycdep.py --sandbox mysandbox -R /path/to/code --common-root-folder code --strip-common-root-folder
This will run pycdep.py. The –sandbox option causes pycdep to use folder mysandbox as a sandbox folder, i.e. a folder where intermediary files (should they be needed) will be saved. Also, if you don’t specify a path to a log file, the log file will end up in the sandbox folder. The -R option adds /path/to/code as a directory that has to be recursively scanned and processed. The –common-root-folder option specifies that path names in the output will be truncated so that they start with the folder specified as –common-root-folder. The –strip-common-root-folder causes the common root folder to be stripped from the pathnames.
To clarify the meaning of the –common-root-folder and –strip-common-root-folder options, here’s an example. Suppose you have the following file structure
/path/to/code/a.cpp
/path/to/code/a.h
/path/to/code/lib/b.cpp
/path/to/code/lib/b.h
If you specify –common-root-folder code, the path names in the resulting prolog and graphviz files will be truncated as follows
code/a.cpp
code/a.h
code/lib/b.cpp
code/lib/b.h
If you additionally specify –strip-common-root-folder, the path names in the resulting prolog and graphviz files will be truncated as follows
a.cpp
a.h
lib/b.cpp
lib/b.h
Load the generated prolog program in swi-prolog (type the following on the command line/shell)
swipl -f dependencies.pl
You arrive in an interactive prompt, and now you can already perform prolog queries. The generated prolog file contains many examples of predefined queries. A useful one is the full_report query. It will write all kinds of interesting facts about your source code in a text report
?- full_report(_).
Use its source. Here’s an example prolog query that finds all the files that include file ‘lib/b.h’
?- findall(F, F depends on 'lib/b.h', Result), write(Result).
Here’s how to dump all the include dependencies in a .dot file for visualization using graphviz (inside prolog)
?- findall([F1,F2], F1 includes F2, Result), to_graphviz('test.dot', Result).
(see the documentation inside the generated prolog file to see more examples).
To generate a .png from the .dot file, you can do (on a command line)
dot -Tpng test.dot -o test.png
If you are not too keen on learning prolog to get information about the system, you can try out the very experimental natural language front-end. To be able to use this front-end you need to load two additional prolog files: intuitivequery.pl and categories.pl. The file intuitivequery.pl implements an interpreter for a dialect of a superset of a subset of the artificial-intelligence markup language (AIML). The categories.pl defines the natural language queries using an AIML-like syntax. Unlike AIML, the syntax used in categories.pl is not XML based, which makes it less cumbersome to edit.
Here’s how to load the generated prolog file together with the natural language interface, and to start up the natural language input loop
swipl -g "[dependencies, intuitivequery, categories], loop."
You can now type queries like
?- Show me the header files in project 'lib' ?
?- Which header files are included by noone ?
Please see categories.pl, and tests.pl for some inspiration about possible queries.
To get an overview of the command line options, type
python pycdep.py --help
As a result you get
usage: pycdep.py [-h] [-s SANDBOX] [-l LOGFILE] [-V VERBOSITY] [-r REPORTNAME]
[-v] [-p PREFIXLENGTH] [-i] [-I INCLUDEDIR]
[-R RECURSIVEINCLUDEDIR] [-X EXCLUDEDIR]
[-Y RECURSIVEEXCLUDEDIR] [-C CPPSUFFIX] [-H HEADERSUFFIX]
[-S SEPARATOR] [-P PROLOGDATABASENAME]
[-d HIERARCHYDEFINITION] [-f COMMONROOTFOLDER] [-c]
The available command line options are
-h, --help show this help message and exit
-s SANDBOX, --sandbox SANDBOX
generates intermediate files in the SANDBOX folder (if
any)
-l LOGFILE, --logfile LOGFILE
choose how to name the logfile
-V VERBOSITY, --verbosity VERBOSITY
choose log level (50 = CRITICAL, 40 = ERRROR, 30 =
WARNING, 20 = INFO, 10 = DEBUG, 0 = NOT SET)
-r REPORTNAME, --report-name REPORTNAME
generates a report with name REPORTNAME
-v, --version show version and quit
-p PREFIXLENGTH, --prefix-length PREFIXLENGTH
max no of path prefixes to keep (to avoid duplicate
names)
-i, --case-insensitive
consider file names to be case insensitive (win32)
-I INCLUDEDIR, --include-dir INCLUDEDIR
add a directory to examine non-recursively
-R RECURSIVEINCLUDEDIR, --recursive-include-dir RECURSIVEINCLUDEDIR
add a directory to examine recursively
-X EXCLUDEDIR, --exclude-dir EXCLUDEDIR
exclude a directory from analysis
-Y RECURSIVEEXCLUDEDIR, --recursive-exclude-dir RECURSIVEEXCLUDEDIR
exclude a directory and all its subdirectories from
analysis
-C CPPSUFFIX, --cppfile-suffix CPPSUFFIX
define file extension of c/c++ files (default: cpp)
-H HEADERSUFFIX, --headerfile-suffix HEADERSUFFIX
define file extension of header files (default: h)
-S SEPARATOR, --path-separator SEPARATOR
define an additional path separator (default: '/')
-P PROLOGDATABASENAME, --prolog-name PROLOGDATABASENAME
define the name of the prolog database that will be
saved
-d HIERARCHYDEFINITION, --hierarchy-definition HIERARCHYDEFINITION
location of hierarchy.txt (include constraint
specificiation)
-f COMMONROOTFOLDER, --common-root-folder COMMONROOTFOLDER
when displaying a file path, always start from the
common root folder if possible
-c, --strip-common-root-folder
when displaying a file path starting from a common
root folder, include the common root folder from the
displayed path