Metadata-Version: 2.4
Name: puncover
Version: 0.8.0
Summary: Analyses C/C++ build output for code size, static variables, and stack usage.
License-File: LICENSE.txt
Author: Hendrik Behrens
Author-email: hendrik.behrens@gmail.com
Requires-Python: >=3.10
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: Flask (==2.2.5)
Requires-Dist: configargparse[yaml] (>=1.7.1)
Requires-Dist: jinja2 (==3.1.6)
Requires-Dist: werkzeug (==3.1.5)
Project-URL: Homepage, https://github.com/HBehrens/puncover
Project-URL: Repository, https://github.com/HBehrens/puncover
Description-Content-Type: text/markdown

[![](https://img.shields.io/badge/GitHub-HBehrens/puncover-8da0cb?style=flat-square&logo=github)](https://github.com/HBehrens/puncover)
[![](https://img.shields.io/github/actions/workflow/status/HBehrens/puncover/ci.yml?style=flat-square&branch=master)](https://github.com/HBehrens/puncover/actions?query=branch%3Amaster+)
[![](https://img.shields.io/codecov/c/github/HBehrens/puncover/master?style=flat-square)](https://codecov.io/gh/HBehrens/puncover)
[![](https://img.shields.io/pypi/v/puncover?style=flat-square)](https://pypi.org/project/puncover)
[![](https://img.shields.io/pypi/pyversions/puncover?style=flat-square)](https://pypi.org/project/puncover)
[![](https://img.shields.io/github/license/HBehrens/puncover?color=blue&style=flat-square)](https://github.com/HBehrens/puncover)

# puncover

![](https://raw.githubusercontent.com/HBehrens/puncover/master/images/overview.png)

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:

```bash
pip install puncover
```

Run it by passing the binary to analyze:

```bash
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:

```bash
uvx puncover project.elf
```

### 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.

```bash
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.ini)):

```bash
tox
```

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

```bash
tox -e py
```

## Publishing Release

### Release Script

See `release.sh` for a script that automates the above steps. Requires
[uv](https://github.com/astral-sh/uv) to be installed. This example will work
with the PyPi tokens (now required):

```bash
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.

<details><summary>Click to expand</summary>

1. Update the version in `puncover/__version__.py`.
2. Commit the version update:

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

3. Create an annotated tag:

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

4. Push the commit and tag:

   ```bash
   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:

   ```bash
   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/*`

</details>

## Contributing

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

