Metadata-Version: 2.4
Name: ocgraph
Version: 1.0.0
Summary: Tool to visualize object code as control flow graph
License-Expression: MIT
License-File: LICENSE
License-File: LICENSES/Celeres.md
License-File: LICENSES/MauriMustonen.md
Keywords: Object Code,Control Flow Graph,ECSS Category A,asm2cfg,Coverage
Author: Mauri Mustonen
Author-email: kazooiebombchu@gmail.com
Maintainer: Christoph Weiss
Maintainer-email: christoph.weiss@celeres.com
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Requires-Dist: graphviz (>=0.21,<0.22)
Project-URL: Changelog, https://gitlab.com/gtd-gmbh/ocgraph/-/blob/main/CHANGELOG.md
Project-URL: Documentation, https://gtd-gmbh.gitlab.io/ocgraph/
Project-URL: Forked from asm2cfg, https://github.com/Kazhuu/asm2cfg
Project-URL: Homepage, https://gitlab.com/gtd-gmbh/ocgraph
Project-URL: Issues, https://gitlab.com/gtd-gmbh/ocgraph/-/issues
Project-URL: Repository, https://gitlab.com/gtd-gmbh/ocgraph
Description-Content-Type: text/markdown

# Object Code Graph (ocgraph)

ocgraph converts the disassembly of one function into a control-flow graph
(CFG). It can enrich the graph with instruction and branch coverage from
[OCCTRE](https://pypi.org/project/occtre/) or TSIM.

The analyzer supports ARM, MSP430, PowerPC, RISC-V, SPARC V8, and x86 GNU
objdump output. Every run writes both a PDF for review and the corresponding
Graphviz source (`.gv`).

A graph is a view of the disassembly you supply: it depends on that disassembly,
on the architecture selection, and on the optional runtime coverage, so validate
a generated graph for the intended toolchain and assurance process.

## Quick start

Python 3.11 or newer and the Graphviz system package are required, because the
`dot` binary renders the PDF. Install the tool with
[pipx](https://pipx.pypa.io/), which keeps it in its own virtual environment:

```console
pipx install ocgraph
objdump -d --disassemble=my_function ./application > my_function.asm
ocgraph --file my_function.asm --arch x86 --diss objdump
```

`python -m pip install ocgraph` installs it into the active environment instead,
which is what a packager wants. `python -m ocgraph` runs the same command from a
checkout of the source tree, and `ocgraph --version` reports the version.

This creates `my_function.pdf` and `my_function.gv`. Use `--output` to choose a
different output basename and `--view` to open the generated PDF after both
files have been written.

## Documentation

The full documentation covers installation, accepted disassembly input,
coverage formats, command-line and Python usage, graph interpretation, and
extension development:

- [Published documentation](https://gtd-gmbh.gitlab.io/ocgraph/)
- [Documentation sources](https://gitlab.com/gtd-gmbh/ocgraph/-/tree/main/doc)

Build it locally with:

```console
poetry install
poetry run sphinx-build -W -b html doc doc_html
```

The generated entry page is `doc_html/index.html`.

## Development

[CONTRIBUTING.md](https://gitlab.com/gtd-gmbh/ocgraph/-/blob/main/CONTRIBUTING.md)
describes the development environment, and the
[development chapter](https://gitlab.com/gtd-gmbh/ocgraph/-/tree/main/doc/development)
explains the analysis flow and the extension points. The short version:

```console
poetry install
poetry run pytest
poetry run mypy -p ocgraph
poetry run pre-commit run --all-files
```

The pipeline runs the suite on Debian bookworm, Debian trixie, Ubuntu 24.04, and
Arch Linux, which pins the interpreters 3.11, 3.13, 3.12, and the rolling 3.14.

## License

Released under the MIT License, see
[LICENSE](https://gitlab.com/gtd-gmbh/ocgraph/-/blob/main/LICENSE).
The project was forked from [asm2cfg](https://github.com/Kazhuu/asm2cfg) by
Mauri Mustonen, who holds the copyright of 2021 for the work it builds on, and
Celeres holds the copyright of 2023 to 2026 for the extensions. The two notices
are kept apart in
[LICENSES](https://gitlab.com/gtd-gmbh/ocgraph/-/tree/main/LICENSES).

## Links

- [Documentation](https://gtd-gmbh.gitlab.io/ocgraph/)
- [PyPI](https://pypi.org/project/ocgraph/)
- [Source repository](https://gitlab.com/gtd-gmbh/ocgraph)
- [Issues](https://gitlab.com/gtd-gmbh/ocgraph/-/issues)
- [Changelog](https://gitlab.com/gtd-gmbh/ocgraph/-/blob/main/CHANGELOG.md)
- [asm2cfg, the upstream project](https://github.com/Kazhuu/asm2cfg)

