memtab

Warning

For detailed documentation, please view the documentation web page: https://etn-corp.github.io/memtab/

memtab is a Python-based project that provides both a command line interface (CLI) and a Python library. It is designed to produce both machine and human-readable reports from binary files in the ELF (Executable and Linkable Format) format.

For more information on the ELF file format, please refer to the Wikipedia article on ELF.

Features

• Command Line Interface (CLI)
• Python library
• Generates machine-readable reports
• Generates human-readable reports

Installation

To install memtab, you can use pip:

pip install memtab

You can also install it directly from git if desired:

pip install git+https://github.com/etn-corp/memtab.git

Usage

Command Line Interface

To use the CLI, run:

memtab --elf <path-to-elf-file>

or, if you already have a configuration file, you can add that argument:

memtab --elf <path-to-elf-file> --config <path-to-yml-file>

For more information on writing a config file, please refer to Configuration section of the usage documentation.

Python Library

To use the Python library:

import memtab

tabulator = Memtab(elf_file, [config])
report = tabulator.tabulate()

print(report)  # this is a pandas dataframe at this point

GitHub Action

To use this as a GitHub Action:

- name: Memtab
  uses: etn-corp/memtab@main
  with:
      sdk_path: [YOUR_SDK_HERE]
      elf: ${{ github.workspace }}\source\build\zephyr\zephyr.elf

The action will generate the markdown output (using the --md argument) and upload that markdown as a step summary.

Developing

This project is managed using uv. For more information, refer to Astral's page on uv.

Common Commands

• uv sync: Sync your development environment with the project dependencies.
• uv run <command>: Run a command within the project's virtual environment.
• uv build: generate a pip installable wheel or sdist file in the dist/ directory.

Running Tests

To run tests, use uv with coverage:

uv run coverage run -m pytest

Pre-commit Hooks

We use prek to ensure code quality and consistency. After cloning the project, install the pre-commit hooks by running:

prek install

For more information on prek, visit the prek project page.

We also have a GitHub Action that runs prek checks on every push and pull request, so you can rely on that if you prefer not to install prek locally.

Contribution Guidelines

We welcome contributions! Please follow these guidelines:

1. Fork the repository.
2. Create a new branch (git checkout -b feature-branch).
3. Make your changes.
4. Commit your changes (git commit -am 'Add new feature').
5. Push to the branch (git push origin feature-branch).
6. Create a new Pull Request.

Reporting Issues

If you encounter any issues, please report them on the GitHub Issues page.

Generating Documentation

To generate documentation, use Sphinx:

sphinx-build docs docs/_build/html

Or, if you have poe installed, you can run:

poe docs

License

This project is licensed under the MIT License. See the LICENSE file for more information.