puncover

Analyzes C/C++ binaries for code size, static variables and stack usages. It creates a report with disassembler and call-stack analysis per directory, file, or function.

Installation and Usage

Install with pip:

pip install puncover

Run it by passing the binary to analyze:

puncover project.elf
...
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

Open the link in your browser to view the analysis.

You can also use uvx to run the script without installing globally:

uvx puncover project.elf

Analysing stack usage

In order to evaluate the stack usage of function and call trees, it is necessary to build with the -fstack-usage flag.

This tells GCC to generate stack usage files (.su) for each compilation unit.

For puncover to evaluate these .su files the --build_dir option needs to point to the build folder of the firmware.

Report export and non-interactive usage

To monitor firmware changes in CI it can be useful to run puncover and save a JSON report.

To generate a report add these flags --generate-report --non-interactive --report-type json and for a distinguishing entry to save more than one report in one file also add a report tag --report-tag $COMMIT_FEATURE. The report is saved under this tag as an object entry.

Running Tests Locally

Setup

To run the tests locally, you need to install the development dependencies. This project uses uv to manage the python environment.

uv venv && source .venv/bin/activate
uv sync

Running Tests

Then you can run the tests with tox (note that this will fail if any of the supported python versions aren't found, see tox.ini):

tox

or, to target only the current python on $PATH:

tox -e py

Publishing Release

Release Script

See release.sh for a script that automates the above steps. Requires uv to be installed. This example will work with the PyPi tokens (now required):

PUNCOVER_VERSION=0.3.5 PYPI_TOKEN=<pypi token> ./release.sh

Manual Steps

Only for reference, the release script should take care of all of this.

Click to expand

1. Update the version in puncover/__version__.py.

2. Commit the version update:

   git add . && git commit -m "Bump version to x.y.z"
   

3. Create an annotated tag:

   git tag -a {-m=,}x.y.z
   

4. Push the commit and tag:

   git push && git push --tags
   

5. Either wait for the GitHub Action to complete and download the release artifact for uploading: https://github.com/HBehrens/puncover/actions OR Build the package locally: python setup.py sdist bdist_wheel

6. Upload the package to PyPI:

   twine upload dist/*
   

7. Create GitHub releases:

   • gh release create --generate-notes x.y.z
   • attach the artifacts to the release too: gh release upload x.y.z dist/*

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.