Skip to content

Latest commit

 

History

History
101 lines (91 loc) · 4.5 KB

README.md

File metadata and controls

101 lines (91 loc) · 4.5 KB
Raw

cpp-util

Utility scripts that make use of the clang library to help understand C / C++ source code

Dependencies

Install clang libclang and graphviz

sudo apt-get install clang libclang-dev graphviz

install python graphviz binding

pip install graphviz

Note the clang version and install the corresponding python clang binding

clang --version
* pip install clang==10.0.1  # for libclang version 10
* pip install clang==14      # for libclang version 14
* pip install clang==17.0.6  # for libclang version 17

To ensure accurate results, it is highly recommended to generate a compile database JSON following clang's specification
Checkout the Bear project https://github.com/rizsotto/Bear. The JSON file then can be generated by

# Makefile users
bear -- make

class_graph.py

Generate a graph of the C++ class inheritance hierarchy class_graph

usage

Run the script at the root path of the project or use --path to specify the run path

python3 class_graph.py

options

class_graph.py -h

ositional arguments:
  classes               name(s) of the querying class, use * for fuzzy match, e.g, a*d matches abd and abcd

options:
  -h, --help            show this help message and exit
  --rebuild             regenerate the json database, use when source code is modify
  --compile_db compile_commands.json
                        JSON Compilation Database in Clang Format, will attempt to use ./compile_commands.json when not provided
  --path PATH           path to workspace root, defult is current directory
  --tree                output in tree view instead of graph view
  --excl EXCL           file or directory names to be excluded, support glob, support multiple --excl
  -v, --verbal          turn on verbel printouts
  -b, --base            only print the ancestor classes
  -d, --derived         only print the descendant classes
  -r, --related         print both the ancestor and descendant classes, this is the default
  -c, --connected, --all
                        print all classes that are connected to any of the ancestor and descendant classes, only available in graph report

call_graph.py

Generate a call graph for the C++ functions call_graph

usage

Run the script at the root path of the project or use --path to specify the run path

python3 call_graph.py function_name

options

call_graph.py -h

positional arguments:
  functions             name(s) of the querying functions

options:
  -h, --help            show this help message and exit
  --rebuild             regenerate the json database, use when source code is modify
  --compile_db compile_commands.json
                        JSON Compilation Database in Clang Format, will attempt to use ./compile_commands.json when not provided
  --path PATH           path to workspace root, defult is current directory
  --excl EXCL           file or directory names to be excluded, support glob, support multiple --excl
  -v, --verbal          turn on verbel printouts
  -l, --list, --ls      list symbols matching the input
  -L LEVEL, --level LEVEL
                        level of traversal in both direction
  --up-level LEVEL, --up-lv LEVEL
                        level of traversal towards the caller direction
  --down-level LEVEL, --down-lv LEVEL
                        level of traversal towards the callee direction
  -u, --up              only find the callers (and their callers)
  -d, --down            only find the callees (and their callees)
  -r, --related         find both the callers and the callees, this is the default
  -c, --connected, --all
                        find all connected nodes in the call graph, includes for example, other callees of the caller (sibling nodes), only available in graph report

Reading the report

By default, a graph report will be generated. The report is stored at ./class_graph or ./call_graph as Graphviz's DOT text and a pdf as an image
The Graphviz DOT text can be visualized using online tools like https://www.devtoolsdaily.com/graphviz/

Because parsing the source code is time consuming, a JSON file will be used to store the parsing result. When the scripts are run afterward, it will re-use the result stored in the JSON files. If the source code has been changed, one can either remove the JSON files or use --rebuild option to force re-parse the source code.