Installation

CI Status Documentation Status Test coverage percentage

uv ruff pypeline pre-commit

PyPI Version Supported Python versions License

C language utils and tools based on the clang and binutils modules.

Installation#

Install clanguru using pipx for isolated installation:

pipx install clanguru

Usage#

Clanguru provides four main commands for C/C++ code analysis and utility operations:

  • Documentation: Generate (minimal) documentation for C/C++ sources functions and classes. It supports multiple output formats including Myst Markdown, standard Markdown, and RestructuredText.

  • Testing: Create mock objects for unit testing C functions

  • Analysis: Understand object file dependencies and symbol usage. It can generate HTML and Excel reports.

Check the help message for more details:

clanguru --help


 Usage: clanguru [OPTIONS] COMMAND [ARGS]...

 C language utils and tools based on the libclang module.

╭─ Options ────────────────────────────────────────────────────────────╮
│ --version  -v        Show version and exit.                          │
│ --help               Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────╮
│ docs      Generate documentation for C/C++ source code.              │
│ mock      Generate mocks for C functions and variables.              │
│ parse     Parse C source code and print the translation unit.        │
│ analyze   Analyze object files dependencies.                         │
╰──────────────────────────────────────────────────────────────────────╯

For detailed help on each command, use the --help option with the command name.

clanguru analyze --help

Object File Analysis#

Clanguru can analyze object files to understand their dependencies and symbol usage. For this, you need to build your project and provide the compilation database (compile_commands.json). Also, ensure that the nm command-line tool is available in your system PATH.

To generate an html dynamic dependency report, run the following command:

clanguru analyze --compilation-database compile_commands.json --output-file dependencies.html --use-parent-deps

[!NOTE] Here is the generated HTML report for my smart home temperature sensor project: https://maxiniuc.com/objects_deps/index.html. I only wrote some lines of code to make a temperature sensor available as a matter device but the esp32 modules, matter stack, and all the libraries bring a lot of code and dependencies. 🫣 Feel free to move the nodes around and explore the dependencies.

If the output file ends with .xlsx, an Excel report will be generated instead of an HTML one.

Contributing#

The project uses UV for dependencies management and packaging and the pypeline for streamlining the development workflow. Use pipx (or your favorite package manager) to install the pypeline in an isolated environment:

pipx install pypeline-runner

To bootstrap the project and run all the steps configured in the pypeline.yaml file, execute the following command:

pypeline run

For those using VS Code there are tasks defined for the most common commands:

  • run tests

  • run pre-commit checks (linters, formatters, etc.)

  • generate documentation

See the .vscode/tasks.json for more details.

Contents