Skip to content

package the chb API for PyPI as codehawk-binary - #296

Open
leftbyte wants to merge 1 commit into
static-analysis-engineering:masterfrom
leftbyte:dphung/pypi-packaging
Open

leftbyte wants to merge 1 commit into
static-analysis-engineering:masterfrom
leftbyte:dphung/pypi-packaging

Conversation

@leftbyte

@leftbyte leftbyte commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

These changes support the publishing of the CodeHawk-Binary python bindings to PyPI.org. After review and commit of these changes, a maintainer on CodeHawk-Binary needs to:

  1. Create two GitHub environments (Settings -> Environments), named exactly:

    • pypi
    • testpypi
      Add required reviewers to pypi, which makes a release need one approval click. Optionally restrict them to protected tags.
  2. Do a dry run: Actions -> release -> "Run workflow", tick

   "Also publish the built distribution to TestPyPI". 

Then pip install -i https://test.pypi.org/simple/ codehawk-binary in a scratch venv. TestPyPI keeps every version it has seen, so a second dry run of the same version fails; bump chbversion or accept one shot.

  1. Cut a release:
    • bump chbversion in chb/app/CHVersion.py
    • commit, then tag v<version> and push the tag
    • approve the pypi environment when Actions asks

NOTE: PEP 440 renders the current 0.3.0-20260901 as 0.3.0.post20260901. A plain
0.3.1 or 0.4.0 would read better on PyPI; changing that string is
preferable to introducing a second version source.

  1. Confirm https://pypi.org/project/codehawk-binary/ shows the README, the MIT license and the 3.9+ requirement.

The pypi.org and test.pypi.ogrg PIPY accounts have been registered and configured:

image image

Replace setup.py with a PEP 621 pyproject.toml.
- name: codehawk-binary (import name stays chb)
- version read from chb/app/CHVersion.py
- requires-python >=3.9 since six modules use builtin generics
- no dependencies because the package is stdlib-only,
- packages restricted to chb*
- explicit package-data for bchsummaries.jar, bch_header.c, and the two
opcodes_covered.json files that exist.

ConfigLocal.py is gitignored local configuration that sits inside the
package, so a wheel built from a working copy would embed a developer's
absolute analyzer paths. This is excluded explicitly and release.yml
builds from a fresh checkout.

Also adds chb/py.typed, since the package is fully annotated and CI
already runs mypy over it.

The analyzer itself is deliberately not packaged: it is a separate OCaml
build invoked over subprocess, and Config() keeps locating it through
ConfigLocal.py.
@leftbyte
leftbyte marked this pull request as ready for review September 24, 2026 22:08

@waskyo waskyo left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for putting this together.

build:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v4

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can we use the latest version of these actions? checkout, setup-python and upload-artifacts are all up to 7. no clue about download-artifact or the other ones.

Comment thread pyproject.toml
readme = "README.md"
license = "MIT"
license-files = ["LICENSE"]
requires-python = ">=3.9"

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment thread README.md
The distribution contains the python API only. Running an analysis additionally
needs the analyzer itself (`chx86_analyze`, `parseFile`), which is built from the
[CodeHawk](https://github.com/static-analysis-engineering/codehawk) repository;
copy `chb/util/ConfigLocal.template` to `chb/util/ConfigLocal.py` and point it at

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Requirements section of the README already covers installation. Let's skip these shortened/duplicated instructions.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants